avnt-react-orm

O avnt-react-orm é um pacote poderoso e flexível projetado para simplificar o gerenciamento de estado e a manipulação de dados em aplicações React. Ele fornece uma estrutura organizada e intuitiva para trabalhar com modelos, controladores e provedores, facilitando operações CRUD, gerenciamento de formulários e validações.

Características

• Estrutura organizada para gerenciamento de dados em React
• Implementação de controladores para lógica de negócios e manipulação de estado
• Modelos para representação e interação com dados
• Gerenciamento simplificado de formulários para criação e edição de registros
• Interface similar a ORM para interação com dados
• Suporte a relacionamentos entre modelos
• Sistema de validação integrado
• Flexibilidade para trabalhar com diferentes backends e APIs

Instalação

Para instalar o avnt-react-orm em seu projeto, use um dos seguintes comandos:

npm install avnt-react-orm

ou

yarn add avnt-react-orm

Uso Básico

Criando um Modelo

import { ModelBase } from 'avnt-react-orm';
import { Attributes } from '@/types/attributes';

export class Usuario extends ModelBase {
  collection = 'usuarios';

  attributes: Attributes<Usuario> = {
    id: { name: 'id', value: '' },
    nome: { name: 'nome', value: '' },
    email: { name: 'email', value: '' },
    documento: { name: 'documento', value: '' },
    senha: { name: 'senha', value: '' },
  };

  fillable = ['nome', 'email', 'documento', 'senha'];
}

Criando um Controlador

import { ControllerBase } from 'avnt-react-orm';
import { Usuario } from './models/Usuario';
import { FieldData } from '@/interfaces/field';
import { z } from 'zod';
import { zodResolver } from '@hookform/resolvers/zod';

export class UsuarioController extends ControllerBase<Usuario> {
  constructor() {
    super(new Usuario());
  }

  settings = {
    fields: {
      nome: { 
        removeDescriptionField: true,
        label: 'Nome', 
        type: 'text', 
        showWhen: ['store', 'update'],
        component: props => <YourTextComponent { ...props } /> 
      } as FieldData,
      documento: { 
        label: 'CPF', 
        type: 'text', 
        showWhen: ['store', 'update'],
        component: props => <YourCPFComponent { ...props } /> 
      } as FieldData,
      email: { 
        label: 'E-mail', 
        type: 'email', 
        showWhen: ['store', 'update'], 
        disabledWhen: ['update'],
        component: props => <YourEmailComponent { ...props } /> 
      } as FieldData,
      senha: { 
        label: 'Senha', 
        type: 'password',
        showWhen: ['store'], 
        component: props => <YourPasswordComponent { ...props } /> 
      } as FieldData,
    },

    // Schema padrão (usado em create e update)
    schema: z.object({
      nome: z.string().min(1, 'Nome é obrigatório'),
      email: z.string().email('E-mail inválido'),
      documento: z.string().regex(/^\d{3}\.\d{3}\.\d{3}-\d{2}$/, 'CPF inválido'),
      senha: z.string().min(8, 'A senha deve ter pelo menos 8 caracteres')
    }),

    // Use isso quando precisar sobrescrever o schema padrão para páginas específicas
    create: {
      schema: z.object({
        nome: z.string().min(1, 'Nome é obrigatório'),
        email: z.string().email('E-mail inválido'),
        documento: z.string().regex(/^\d{3}\.\d{3}\.\d{3}-\d{2}$/, 'CPF inválido'),
        senha: z.string().min(8, 'A senha deve ter pelo menos 8 caracteres')
      })
    },
    update: {
      schema: z.object({
        nome: z.string().min(1, 'Nome é obrigatório'),
        documento: z.string().regex(/^\d{3}\.\d{3}\.\d{3}-\d{2}$/, 'CPF inválido')
      })
    }
    // Defina configurações para outros tipos de página conforme necessário
  };

  getResolver(pageType?: 'create' | 'update') {
    const schema = pageType ? this.settings[pageType].schema : this.settings.schema;
    return zodResolver(schema);
  }
}

Usando o PageProvider em um Componente React

import React from 'react';
import { PageProvider } from 'avnt-react-orm';
import { UsuarioController } from './controllers/UsuarioController';

const FormUsuario = () => {
  const usuarioController = new UsuarioController();
  
  const provedor = new PageProvider({
    resource: 'usuarios',
    resources: { usuarios: usuarioController },
    onLoad: () => {
      // Lógica de carregamento personalizada
    },
    onSearch: (termosBusca, instancia) => {
      // Lógica de busca personalizada
      return instancia;
    },
    onAction: (instancia) => {
      // Lógica de ação personalizada
      return instancia;
    },
  });

  provedor.subscribe((instancia) => {
    // Reaja às atualizações do provedor
  });

  const { register, handleSubmit, formState: { errors } } = useForm({
    resolver: usuarioController.getResolver('create')
  });

  const onSubmit = (data) => {
    // Lógica de submissão do formulário
    console.log(data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      {/* Renderize seus campos de formulário aqui */}
      <button type="submit">Enviar</button>
    </form>
  );
};

export default FormUsuario;

Conceitos Principais

Modelos

Modelos representam a estrutura de dados da sua aplicação. Eles definem atributos, relacionamentos e regras de negócio específicas para cada tipo de dado. Os modelos utilizam a interface ModelInterface e o tipo Attributes para definir sua estrutura.

Controladores

Controladores gerenciam a lógica de negócios e o estado da aplicação. Eles implementam a interface ControllerInterface, que inclui métodos para operações CRUD, gerenciamento de estado e manipulação de campos. Os controladores também definem schemas de validação e configurações de campos.

Provedores

Provedores lidam com a conexão entre seus componentes React e os controladores. Eles gerenciam parâmetros de URL, ações e atualizações de estado.

Campos

Campos são definidos usando a interface FieldData e representam a estrutura de formulários e interfaces de usuário. Eles fornecem uma maneira fácil de gerar e validar formulários dinamicamente, com suporte para diferentes tipos de páginas e condições de exibição.

Tipos Importantes

• ControllerState: Representa o estado atual do controlador ('draft' | 'initialized' | 'error' | 'processing' | 'inuse').
• PageType: Define os tipos de páginas suportados pelo sistema.
• Filter: Interface para definir filtros de dados.

Recursos Avançados

• Relacionamentos: Defina e gerencie relacionamentos entre diferentes modelos.
• Validação: Implemente regras de validação personalizadas para seus dados usando Zod ou outras bibliotecas.
• Acesso a atributos baseado em proxy: Acesse e modifique atributos do modelo diretamente.
• Operações CRUD automáticas: Utilize métodos integrados para criar, ler, atualizar e excluir registros.
• Filtros: Use a interface Filter para implementar filtragem avançada de dados.
• Componentes de campo personalizados: Defina componentes React personalizados para cada campo.
• Schemas de validação específicos por página: Configure schemas de validação diferentes para páginas de criação e atualização.

Licença

Este projeto está licenciado sob a Licença MIT.

Suporte

Se você encontrar algum problema ou tiver alguma dúvida, por favor, abra uma issue no repositório do projeto: avnt-sistemas/react-orm — Bitbucket