forlogic-core 3.0.11 → 4.0.0

package/docs/design-system/crud.md

@@ -1,243 +0,0 @@
-<!-- ⚠️ 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

@@ -1,365 +0,0 @@
-<!-- ⚠️ 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, StatusBadge, createStatusConfig } from "forlogic-core"
-
-// Badge genérico
-<Badge>Badge</Badge>
-<Badge variant="success">Aprovado</Badge>
-
-// Status Badge — uso direto
-<StatusBadge label="Em Execução" color="#2E7D5B" icon={Play} />
-
-// Status Badge — com createStatusConfig
-const getStatus = createStatusConfig({
-  pending: { label: 'Pendente', color: '#8B7355', icon: Clock },
-  approved: { label: 'Aprovado', color: '#3D7A40', icon: CheckCircle2 },
-});
-<StatusBadge {...getStatus('pending')} />
-```
-
-**Exemplos:**
-```tsx
-<Badge>Default</Badge>
-<Badge variant=
-```
-```tsx
-import { StatusBadge, createStatusConfig } from
-```
-```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`
-
----