npm package: @guilherme_grv/dynamic-form
Description: Formulário dinâmico para React
Author: Guilherme Soares
Latest version: 1.0.3

# @guilherme_grv/dynamic-form

## Introdução

Uma biblioteca React leve, performática e baseada em schema JSON para renderização de formulários dinâmicos.

**Características Principais:**

*   🚀 **Schema-Driven**: Defina toda a estrutura e validação do seu formulário utilizando um schema JSON, que pode ser facilmente consumido de uma API.
*   ⚡ **Performático**: Otimizado para evitar re-renderizações desnecessárias, garantindo uma experiência de usuário fluida.
*   🛡️ **Validação Robusta**: Sistema de validação integrado e tipado, sem dependências externas.
*   ♿ **Acessível**: Geração automática de atributos ARIA (`aria-invalid`, `aria-describedby`) para garantir acessibilidade.
*   🎨 **Estilização Flexível**: Utiliza classes utilitárias compatíveis com Tailwind CSS, permitindo total customização visual.
*   🔌 **Extensível**: Suporte para componentes de campo customizados e regras de validação assíncronas.

## Instalação

```bash
npm install @guilherme_grv/dynamic-form
```

## Uso Básico

Para usar a biblioteca, você precisa de duas coisas: um **schema** para definir o formulário e o componente **`DynamicForm`** para renderizá-lo.

### 1. Defina o Schema

O schema é um objeto JSON que descreve a estrutura do formulário, incluindo seções, campos e regras de validação.

```typescript
import { FormSchema } from '@guilherme_grv/dynamic-form';

const formSchema: FormSchema = {
  title: "Formulário de Contato",
  sections: [
    {
      id: "contact_info",
      title: "Informações de Contato",
      fields: [
        {
          key: "name",
          type: "text",
          label: "Nome",
          placeholder: "Digite seu nome completo",
          validations: [
            { type: "required", message: "O nome é obrigatório." },
            { type: "minLength", value: 3, message: "O nome deve ter no mínimo 3 caracteres." }
          ]
        },
        {
          key: "email",
          type: "email",
          label: "E-mail",
          placeholder: "seu@email.com",
          validations: [
            { type: "required", message: "O e-mail é obrigatório." },
            { type: "pattern", value: "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$", message: "Formato de e-mail inválido." }
          ]
        }
      ]
    }
  ]
};
```

#### Validadores Disponíveis

A biblioteca oferece um conjunto de validadores prontos para uso:

*   `required`: O campo não pode ser vazio.
*   `minLength` / `maxLength`: Define o comprimento mínimo e máximo para uma string.
*   `min` / `max`: Define o valor numérico mínimo e máximo.
*   `pattern`: Valida o campo contra uma expressão regular (regex).
*   `custom`: Permite uma função de validação customizada no formato `(value, allData) => boolean`.

### 2. Renderize o Formulário

Importe o componente `DynamicForm` e passe o schema e uma função `onSubmit`.

```jsx
import { DynamicForm } from '@guilherme_grv/dynamic-form';
import { formSchema } from './schema'; // O schema definido anteriormente

function App() {
  const handleSubmit = (data: any) => {
    alert("Formulário enviado com sucesso!");
    console.log("Dados do formulário:", data);
  };

  return (
    <div className="max-w-2xl mx-auto p-8">
      <DynamicForm 
        schema={formSchema} 
        onSubmit={handleSubmit} 
      />
    </div>
  );
}
```

## Propriedades do Componente

O componente `DynamicForm` aceita as seguintes propriedades:

| Propriedade   | Tipo                               | Obrigatório |   Descrição                                                                                             |
|---------------|------------------------------------|-------------|-------------------------------------------------------------------------------------------------------|
| `schema`      | `FormSchema`                       | Sim         | O schema JSON que define a estrutura e as validações do formulário.                                   |
| `onSubmit`    | `(data: any) => void`              | Sim         | Função executada na submissão bem-sucedida do formulário, recebendo os dados válidos como argumento.    |
| `initialData` | `object`                           | Não         | Um objeto com dados iniciais para preencher os campos do formulário, ideal para formulários de edição. |

## Exemplo Completo

Abaixo, um exemplo mais completo demonstrando diferentes tipos de campos, máscara e validações.

**`schema.ts`**
```typescript
import { FormSchema } from '@guilherme_grv/dynamic-form';

export const userSchema: FormSchema = {
  title: "Cadastro de Usuário",
  sections: [
    {
      id: "personal_info",
      title: "Dados Pessoais",
      fields: [
        {
          key: "name",
          type: "text",
          label: "Nome Completo",
          placeholder: "Digite seu nome",
          validations: [
            { type: "required", message: "O nome é obrigatório" },
            { type: "minLength", value: 3, message: "Mínimo 3 caracteres" }
          ]
        },
        {
          key: "email",
          type: "email",
          label: "E-mail Corporativo",
          validations: [
            { type: "required", message: "E-mail obrigatório" },
            { type: "pattern", value: "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$", message: "E-mail inválido" }
          ]
        },
        {
          key: "phone",
          type: "text",
          label: "Celular",
          mask: "(99) 99999-9999", // Máscara de formatação automática
          validations: [{ type: "required", message: "Telefone obrigatório" }]
        }
      ]
    },
    {
      id: "company_info",
      title: "Dados da Empresa",
      fields: [
        {
          key: "role",
          type: "select",
          label: "Cargo",
          options: [
            { value: "dev", label: "Desenvolvedor" },
            { value: "designer", label: "Designer" },
            { value: "manager", label: "Gerente" }
          ],
          validations: [{ type: "required", message: "Selecione um cargo" }]
        }
      ]
    }
  ]
};
```

**`App.tsx`**
```jsx
import { DynamicForm } from '@guilherme_grv/dynamic-form';
import { userSchema } from './schema';

function App() {
  const handleSubmit = (data: any) => {
    console.log("Dados Válidos:", data);
    // Ex: Enviar para uma API
    // fetch('/api/users', { method: 'POST', body: JSON.stringify(data) });
  };

  // Dados iniciais para um formulário de edição
  const initialData = {
    name: "Guilherme Soares",
    email: "gui@exemplo.com",
    phone: "11987654321",
    role: "dev"
  };

  return (
    <div className="max-w-2xl mx-auto p-4">
      <DynamicForm 
        schema={userSchema} 
        initialData={initialData} 
        onSubmit={handleSubmit} 
      />
    </div>
  );
}
```