forlogic-core 2.0.3 → 2.0.4

package/docs/design-system/crud.md

@@ -0,0 +1,243 @@
+<!-- ⚠️ ARQUIVO GERADO AUTOMATICAMENTE — NÃO EDITAR MANUALMENTE -->
+<!-- Fonte: src/design-system/docs/ | Regenerar: npx tsx scripts/generate-ds-docs.ts -->
+
+# CRUD
+
+Categoria: **CRUD** | 8 componentes
+
+### CRUD Overview
+
+Visão geral da arquitetura CRUD do forlogic-core. Explica os 3 níveis de abstração: createCrudPage (alto nível), CrudTable/CrudGrid (médio nível) e Primitives (baixo nível).
+
+**Uso:**
+```tsx
+import { createSimpleService, createCrudPage } from 'forlogic-core';
+
+const notesService = createSimpleService({
+  tableName: 'notes',
+  entityName: 'nota',
+  searchFields: ['title', 'content'],
+});
+
+const NotesPage = createCrudPage({
+  title: 'Notas',
+  service: notesService,
+  columns: [
+    { key: 'title', header: 'Título' },
+    { key: 'content', header: 'Conteúdo' },
+  ],
+  formSections: [{
+    id: 'main',
+    fields: [
+      { name: 'title', label: 'Título', type: 'text', required: true },
+      { name: 'content', label: 'Conteúdo', type: 'textarea' },
+    ],
+  }],
+});
+```
+
+**Notas:**
+- Nível Alto: createCrudPage — página CRUD completa com 1 configuração
+- Nível Médio: CrudTable/CrudGrid — componentes compostos para layouts customizados
+- Nível Baixo: Primitives (DataTable, DataPagination, DataFilterBar) — controle total
+
+> Fonte: `src\design-system\docs\components\crud\CrudOverviewDoc.tsx`
+
+---
+
+### createCrudPage
+
+Factory de alto nível que gera uma página CRUD completa com ~15 linhas de configuração declarativa.
+
+> Fonte: `src\design-system\docs\components\crud\CreateCrudPageDoc.tsx`
+
+---
+
+### CrudActionBar
+
+Barra de ações unificada usada por todos os componentes CRUD (CrudTable, CrudGrid, createCrudPage) para garantir UX consistente.
+
+> Fonte: `src\design-system\docs\components\crud\CrudActionBarDoc.tsx`
+
+---
+
+### CrudTable
+
+Componente de tabela CRUD completo com ordenação, seleção, resize de colunas, ações em massa e paginação integrada com useCrud.
+
+> Fonte: `src\design-system\docs\components\crud\CrudTableDoc.tsx`
+
+---
+
+### CrudGrid
+
+Componente para exibir dados em formato de grade (cards) com todas as funcionalidades CRUD. Alternativa visual ao CrudTable para listagens com layout mais visual.
+
+> Fonte: `src\design-system\docs\components\crud\CrudGridDoc.tsx`
+
+---
+
+### CRUD Primitives
+
+Componentes de baixo nível para interfaces CRUD totalmente customizadas com controle total sobre layout e comportamento. Aliases disponíveis: DataTable, DataFilterBar, DataPagination.
+
+> Fonte: `src\design-system\docs\components\crud\CrudPrimitivesDoc.tsx`
+
+---
+
+### Pagination
+
+Barra de paginação completa com seletor de itens por página e controles de navegação.
+
+**Uso:**
+```tsx
+import { Pagination } from "forlogic-core/crud"
+
+<Pagination
+  currentPage={1}
+  totalPages={10}
+  totalItems={100}
+  itemsPerPage={10}
+  onPageChange={(page) => setPage(page)}
+  onItemsPerPageChange={(limit) => setLimit(limit)}
+  variant="full"
+/>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `currentPage` | `number` | - | Página atual (1-indexed) |
+| `totalPages` | `number` | - | Número total de páginas |
+| `totalItems` | `number` | - | Número total de itens |
+| `itemsPerPage` | `number` | - | Quantidade de itens por página |
+| `onPageChange` | `(page: number) => void` | - | Callback ao mudar de página |
+| `onItemsPerPageChange` | `(limit: number) => void` | - | Callback ao mudar itens por página |
+
+**Exemplos:**
+```tsx
+<Pagination
+  currentPage={1}
+  totalPages={2}
+  totalItems={15}
+  itemsPerPage={10}
+  onPageChange={setPage}
+  onItemsPerPageChange={setItemsPerPage}
+  variant=
+```
+```tsx
+<Pagination
+  currentPage={3}
+  totalPages={25}
+  totalItems={250}
+  itemsPerPage={10}
+  onPageChange={setPage}
+  onItemsPerPageChange={setItemsPerPage}
+  variant=
+```
+
+**Acessibilidade:**
+- Navegável por teclado
+- Labels ARIA apropriados
+- Indicação visual da página atual
+- Botões desabilitados quando não aplicável
+- Amigável para leitores de tela
+
+> Fonte: `src\design-system\docs\components\PaginationDoc.tsx`
+
+---
+
+### Form
+
+Construindo formulários com React Hook Form e Zod.
+
+**Uso:**
+```tsx
+import { zodResolver } from "@hookform/resolvers/zod"
+import { useForm } from "react-hook-form"
+import * as z from "zod"
+import {
+  Form,
+  FormControl,
+  FormDescription,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from "forlogic-core"
+
+const formSchema = z.object({
+  username: z.string().min(2).max(50),
+})
+
+function MyForm() {
+  const form = useForm<z.infer<typeof formSchema>>({
+    resolver: zodResolver(formSchema),
+  })
+
+  function onSubmit(values: z.infer<typeof formSchema>) {
+    console.log(values)
+  }
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)}>
+        <FormField
+          control={form.control}
+          name="username"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Username</FormLabel>
+              <FormControl>
+                <Input placeholder="shadcn" {...field} />
+              </FormControl>
+              <FormDescription>
+                This is your public display name.
+              </FormDescription>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+        <Button type="submit">Submit</Button>
+      </form>
+    </Form>
+  )
+}
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `Form` | `FormProvider props` | - | Wrapper que provê o contexto do formulário via React Hook Form |
+| `FormField.control` | `Control` | - | Objeto control do useForm para gerenciar o campo |
+| `FormField.name` | `string` | - | Nome do campo no schema do formulário |
+| `FormField.render` | `(field) => ReactNode` | - | Função de renderização do campo com acesso ao field object |
+| `FormItem` | `HTMLDivElement` | - | Container que agrupa label, controle, descrição e mensagem de erro |
+| `FormLabel` | `LabelProps` | - | Label associado ao campo do formulário |
+| `FormControl` | `SlotProps` | - | Wrapper que conecta o controle ao contexto do campo |
+| `FormDescription` | `HTMLParagraphElement` | - | Texto de ajuda exibido abaixo do controle |
+| `FormMessage` | `HTMLParagraphElement` | - | Exibe mensagens de erro de validação automaticamente |
+
+**Exemplos:**
+```tsx
+<FormField
+  control={form.control}
+  name=
+```
+```tsx
+const formSchema = z.object({
+  username: z.string().min(3, {
+    message:
+```
+
+**Acessibilidade:**
+- Labels são automaticamente associados aos controles via aria-describedby
+- Mensagens de erro são anunciadas por leitores de tela
+- Suporta navegação por teclado nativa dos controles
+- Estados de erro são indicados visualmente e semanticamente
+- Usa React Hook Form para gerenciamento de estado de formulário
+- Integra com Zod para validação de schema
+
+> Fonte: `src\design-system\docs\components\FormDoc.tsx`
+
+---

package/docs/design-system/data-display.md

@@ -0,0 +1,360 @@
+<!-- ⚠️ ARQUIVO GERADO AUTOMATICAMENTE — NÃO EDITAR MANUALMENTE -->
+<!-- Fonte: src/design-system/docs/ | Regenerar: npx tsx scripts/generate-ds-docs.ts -->
+
+# Data Display
+
+Categoria: **Data Display** | 8 componentes
+
+### Avatar
+
+Um elemento de imagem com fallback para representar o usuário.
+
+**Uso:**
+```tsx
+import { Avatar, AvatarImage, AvatarFallback } from "forlogic-core"
+
+<Avatar>
+  <AvatarImage src="https://github.com/shadcn.png" alt="@shadcn" />
+  <AvatarFallback>CN</AvatarFallback>
+</Avatar>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `src` | `string` | - | A URL da fonte da imagem (AvatarImage). |
+| `alt` | `string` | - | Texto alternativo para a imagem (AvatarImage). |
+
+**Exemplos:**
+```tsx
+<Avatar>
+  <AvatarImage src=
+```
+```tsx
+<Avatar>
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>
+```
+
+**Acessibilidade:**
+- Texto alternativo adequado para imagens
+- Fallback garante que o conteúdo seja sempre exibido
+- Estrutura HTML semântica
+
+> Fonte: `src\design-system\docs\components\AvatarDoc.tsx`
+
+---
+
+### Badge
+
+Exibe um badge ou um componente que se parece com um badge.
+
+**Uso:**
+```tsx
+import { Badge } from "forlogic-core"
+
+<Badge>Badge</Badge>
+<Badge variant="secondary">Secondary</Badge>
+<Badge variant="info">Info</Badge>
+<Badge variant="success">Success</Badge>
+<Badge variant="warning">Warning</Badge>
+<Badge variant="danger">Danger</Badge>
+<Badge variant="outline">Outline</Badge>
+<Badge variant="sharp">Sharp</Badge>
+```
+
+**Exemplos:**
+```tsx
+<Badge>Default</Badge>
+<Badge variant=
+```
+```tsx
+<Badge variant=
+```
+```tsx
+<Badge variant=
+```
+```tsx
+<div className=
+```
+```tsx
+<Badge variant=
+```
+
+**Acessibilidade:**
+- HTML semântico com taxas de contraste adequadas
+- Funciona com leitores de tela
+- Pode ser tornado interativo com labels ARIA adequadas se necessário
+
+> Fonte: `src\design-system\docs\components\BadgeDoc.tsx`
+
+---
+
+### Card
+
+Exibe um card com cabeçalho, conteúdo e rodapé.
+
+**Uso:**
+```tsx
+import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from "forlogic-core"
+
+<Card>
+  <CardHeader>
+    <CardTitle>Card Title</CardTitle>
+    <CardDescription>Card Description</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p>Card Content</p>
+  </CardContent>
+  <CardFooter>
+    <p>Card Footer</p>
+  </CardFooter>
+</Card>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `className` | `string` | - | Classes CSS adicionais para o card. |
+
+**Acessibilidade:**
+- Estrutura semântica com elementos apropriados
+- Hierarquia de cabeçalhos adequada
+- Contraste de cores acessível
+- Funciona com leitores de tela
+
+> Fonte: `src\design-system\docs\components\CardDoc.tsx`
+
+---
+
+### DataList
+
+Sistema de lista de dados com composição de componentes. Ideal para exibir informações estruturadas em formato de cards.
+
+**Uso:**
+```tsx
+import { DataList, Badge } from "forlogic-core"
+
+<DataList.Root>
+  <DataList.Item onClick={() => console.log('clicked')}>
+    <DataList.Field label="Nome" value="João Silva" />
+    <DataList.Field label="Email" value="joao@exemplo.com" />
+    <DataList.Field label="Status" value={<Badge>Ativo</Badge>} />
+  </DataList.Item>
+  <DataList.Item>
+    <DataList.Field label="Nome" value="Maria Santos" />
+    <DataList.Field label="Email" value="maria@exemplo.com" />
+  </DataList.Item>
+</DataList.Root>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `DataList.Root` | `ReactNode` | - | Container principal com espaçamento vertical. |
+| `DataList.Item` | `ReactNode` | - | Item individual renderizado como Card. |
+| `DataList.Item.onClick` | `() => void` | - | Handler de clique (adiciona hover state). |
+| `DataList.Field` | `{ label, value }` | - | Par label/value formatado horizontalmente. |
+| `DataList.Field.value` | `ReactNode` | - | Valor pode ser texto ou componentes (Badge, etc.). |
+
+**Acessibilidade:**
+- Items clicáveis tem cursor pointer
+- Hover state visual para feedback
+- Estrutura semântica com Cards
+
+**Notas:**
+- 💡 Use para listas de dados estruturados
+- 💡 Field.value aceita ReactNode - use Badge, Button, etc.
+- 💡 onClick em Item adiciona hover state automaticamente
+
+> Fonte: `src\design-system\docs\components\DataListDoc.tsx`
+
+---
+
+### Empty State
+
+Componente para exibir estados vazios com ícone, mensagem e ação opcional.
+
+**Uso:**
+```tsx
+import { EmptyState } from "forlogic-core"
+
+// Estado vazio padrão
+<EmptyState
+  title="Nenhum item encontrado"
+  description="Adicione seu primeiro item para começar"
+  action={{
+    label: "Adicionar Item",
+    onClick: () => handleAddItem()
+  }}
+/>
+
+// Sem resultados de busca
+<EmptyState
+  variant="search"
+  title="Nenhum resultado encontrado"
+  description="Tente ajustar sua busca"
+/>
+
+// Estado de erro
+<EmptyState
+  variant="error"
+  title="Erro ao carregar dados"
+  description="Não foi possível carregar as informações"
+  action={{
+    label: "Tentar Novamente",
+    onClick: () => refetch()
+  }}
+/>
+
+// Ícone customizado
+<EmptyState
+  icon={<Package className="h-8 w-8" />}
+  title="Sem produtos"
+/>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `icon` | `ReactNode` | - | Ícone customizado (sobrescreve o variant). |
+| `title` | `string` | - | Título principal. |
+| `description` | `string` | - | Descrição opcional. |
+| `action` | `{ label: string, onClick: () => void }` | - | Botão de ação opcional. |
+| `className` | `string` | - | Classes CSS adicionais. |
+
+**Acessibilidade:**
+- Ícones pré-configurados por variant
+- Botão de ação opcional
+- Centralizado e responsivo
+- Suporte a ícone customizado
+
+> Fonte: `src\design-system\docs\components\EmptyStateDoc.tsx`
+
+---
+
+### Separator
+
+Separa visual ou semanticamente o conteúdo.
+
+**Uso:**
+```tsx
+import { Separator } from "forlogic-core"
+
+<Separator />
+<Separator orientation="vertical" />
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `decorative` | `boolean` | true | Se o separador é decorativo ou semântico. |
+
+**Exemplos:**
+```tsx
+<Separator />
+```
+```tsx
+<Separator orientation=
+```
+
+**Acessibilidade:**
+- HTML semântico com role adequado
+- Pode ser decorativo ou estrutural
+- Atributos ARIA adequados
+
+> Fonte: `src\design-system\docs\components\SeparatorDoc.tsx`
+
+---
+
+### Progress
+
+Exibe um indicador mostrando o progresso de conclusão de uma tarefa, tipicamente exibido como uma barra de progresso.
+
+**Uso:**
+```tsx
+import { Progress } from "forlogic-core"
+
+<Progress value={60} />
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `value` | `number` | 0 | O valor de progresso (0-100). |
+| `max` | `number` | 100 | O valor máximo de progresso. |
+| `getValueLabel` | `(value: number, max: number) => string` | - | Função para gerar label acessível. |
+| `className` | `string` | - | Classes CSS para estilização. |
+
+**Acessibilidade:**
+- Usa atributos ARIA apropriados (role=
+- )
+- Anuncia o progresso para leitores de tela via aria-valuenow
+- aria-valuemin e aria-valuemax definidos automaticamente
+- Use getValueLabel para descrições customizadas
+- Indicador visual claro para estado de progresso
+
+**Notas:**
+- Use Progress para indicar conclusão de tarefas de longa duração
+- Combine com textos descritivos para fornecer contexto adicional
+- Prefira Spinner para loading de curta duração ou indeterminado
+- Ajuste a altura via className (h-1, h-2, h-4) para diferentes contextos
+- Para uploads, mostre tamanho atual e total junto com o percentual
+
+> Fonte: `src\design-system\docs\components\ProgressDoc.tsx`
+
+---
+
+### Loading
+
+Componentes para estados de carregamento: Skeleton (placeholders), Spinner (indicador de loading), e LoadingState (gerenciamento declarativo).
+
+**Uso:**
+```tsx
+import { Skeleton, Spinner, LoadingState } from "forlogic-core"
+
+// Skeleton básico
+<Skeleton className="h-4 w-[200px]" />
+
+// Spinner
+<Spinner size="md" />
+
+// LoadingState declarativo
+<LoadingState isLoading={isLoading} type="spinner">
+  <div>Conteúdo carregado</div>
+</LoadingState>
+```
+
+**Props:**
+| Prop | Tipo | Padrão | Descrição |
+|------|------|--------|-----------|
+| `className` | `string` | - | Classes CSS para customizar dimensões e formato. |
+| `rows` | `number` | 5 | Número de linhas (TableSkeleton). |
+| `columns` | `number` | 4 | Número de colunas (TableSkeleton). |
+| `count` | `number` | 3 | Número de cards (CardSkeleton). |
+| `fields` | `number` | 4 | Número de campos (FormSkeleton). |
+| `isLoading` | `boolean` | - | Estado de loading (LoadingState). |
+
+**Acessibilidade:**
+- Usa animação para indicar estado de carregamento
+- Dimensionamento corresponde ao conteúdo esperado
+- Não interfere com leitores de tela
+- Animação respeita preferências de movimento reduzido
+- LoadingState com overlay mantém contexto visual para usuários
+- Spinner tem role=
+-  implícito para leitores de tela
+
+**Notas:**
+- **Skeleton**: Placeholder animado que imita o formato do conteúdo. Use para carregamentos iniciais.
+- **Spinner**: Indicador circular de loading. Use em botões ou áreas pequenas.
+- **LoadingState**: Componente declarativo que gerencia exibição de loading vs conteúdo.
+- **type=
+- **: Esconde children e mostra apenas o spinner centralizado.
+- **type=
+- **: Mantém children visíveis com um spinner sobreposto. Ideal para salvar.
+- **type=
+- **: Mostra um placeholder animado no lugar dos children.
+
+> Fonte: `src\design-system\docs\components\SkeletonDoc.tsx`
+
+---