@snksergio/design-system 0.60.0 → 0.62.0

package/dist-lib/ai/componentes/DatePicker.md

@@ -0,0 +1,84 @@
+# DatePicker — USAGE
+
+**Categoria:** composto (Popover + Calendar). Seletor de data(s) com trigger no estilo input do DS.
+
+## Quando usar
+- Campo de formulário pra escolher **uma** data (nascimento, vencimento, data de referência).
+- Selecionar um **intervalo** de datas (período de relatório, filtro por data inicial/final).
+- Selecionar **várias datas soltas** (não contíguas).
+
+## Import
+```tsx
+import { DatePicker } from "@/components/ui/DatePicker";
+import type { DatePickerProps, DateRange } from "@/components/ui/DatePicker";
+```
+
+## Variants (`mode`) — muda o shape do `value`
+
+`DatePickerProps` é uma discriminated union por `mode`. Trocar de modo troca o TIPO de
+`value`/`onValueChange` junto — trate como union, não como prop solta.
+
+| `mode` | Obrigatória? | `value` | `onValueChange` | Nº de meses (default) |
+|---|---|---|---|---|
+| `"single"` (default) | não (`mode?: "single"`) | `Date \| undefined` | `(value: Date \| undefined) => void` | 1 |
+| `"range"` | sim (`mode: "range"`) | `DateRange \| undefined` (`{ from: Date \| undefined; to?: Date }`, reexportado de `react-day-picker`) | `(value: DateRange \| undefined) => void` | 2 |
+| `"multiple"` | sim (`mode: "multiple"`) | `Date[] \| undefined` | `(value: Date[] \| undefined) => void` | 1 |
+
+Comportamento de fechamento do popover por modo:
+- `single`: fecha ao clicar numa data.
+- `range`: só fecha quando `from` **e** `to` estão preenchidos (clique único no primeiro dia não fecha).
+- `multiple`: **não fecha sozinho** — o usuário fecha clicando fora.
+
+Label do trigger por modo (não é customizável — ver Gotchas). Formatos conferidos no
+showcase, não inferidos do código:
+- `single`: mês por extenso — `19 de junho de 2026` (`month: "long"`).
+- `range`: mês abreviado nas duas pontas — `10 de jul. de 2026 – 18 de ago. de 2026`
+  (`month: "short"`); com só o `from` preenchido, mostra apenas ele.
+- `multiple`: contagem — `1 data selecionada` / `N datas selecionadas`.
+
+## Props essenciais
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `mode` | `"single" \| "range" \| "multiple"` | `"single"` | Modo de seleção — ver tabela acima pro shape de `value`. |
+| `value` | `Date` \| `DateRange` \| `Date[]` (conforme `mode`) | — | Seleção controlada. |
+| `onValueChange` | conforme `mode` (ver tabela acima) | — | Callback de mudança. |
+| `placeholder` | `string` | `"Selecione a data"` (single/multiple) ou `"Selecione o período"` (range) | Texto do trigger quando nada está selecionado. |
+| `disabled` | `boolean` | — | Desabilita o **trigger** (botão inteiro). |
+| `align` | `"start" \| "center" \| "end"` | `"start"` | Alinhamento do `PopoverContent`. |
+| `numberOfMonths` | `number` | `1` (single/multiple) / `2` (range) | Nº de meses exibidos no `Calendar` interno. |
+| `className` | `string` | — | className do trigger (mesmos overrides de um input/`SelectTrigger`). |
+
+## Exemplo mínimo
+```tsx
+// single (default)
+const [date, setDate] = useState<Date>();
+<DatePicker value={date} onValueChange={setDate} placeholder="Data de nascimento" />
+
+// range
+const [range, setRange] = useState<DateRange>();
+<DatePicker mode="range" value={range} onValueChange={setRange} />
+
+// multiple
+const [dates, setDates] = useState<Date[]>();
+<DatePicker mode="multiple" value={dates} onValueChange={setDates} />
+```
+
+## Cuidados / Gotchas
+- **Composto sobre `Popover` + `Calendar` do DS** (`@/components/shadcn/popover` e
+  `@/components/shadcn/calendar`, este último em cima de `react-day-picker`). Copiando via
+  registry essas deps já vêm junto (`date-picker` declara `@igreen/calendar` +
+  `@igreen/popover` como `registryDependencies`); copiando manual, garanta que os dois
+  existem no consumidor antes.
+- **`mode` muda o TIPO, não só o comportamento.** `single` é opcional (default), mas
+  `range`/`multiple` exigem a prop explícita. Trocar o modo de um DatePicker controlado
+  exige trocar o estado (`Date` → `DateRange`/`Date[]`) junto — o TS não deixa passar
+  `value` do shape errado se a discriminated union for respeitada.
+- Em `range`, o `Calendar` interno recebe `min={1}` — sem isso o react-day-picker fecharia
+  o range já no primeiro clique (`from`/`to` iguais no mesmo dia).
+- Em `multiple`, não há botão "Aplicar"/"Fechar" embutido — o popover some só no
+  clique-fora.
+- **Não há pass-through de restrição de datas** (desabilitar dias específicos / limitar o
+  intervalo navegável) pro `Calendar` interno — a prop `disabled` do DatePicker desabilita
+  o trigger inteiro, não datas específicas do calendário.
+- O label do trigger é formatado em pt-BR fixo (`toLocaleDateString("pt-BR", ...)`); não
+  existe prop de formato customizável.

package/dist-lib/ai/componentes/DateSeparatorChip.md

@@ -0,0 +1,59 @@
+# DateSeparatorChip
+
+**Categoria:** composto (Chip + Icon + Separator). Separador **centralizado na thread** do chat/atendimento. Marcador estático — não interativo.
+
+## Quando usar
+
+- **Separador de data** numa lista de mensagens (`MessagesList`): "Hoje", "Ontem", "22 jun".
+- **Limite de conversa** (`boundary`): "Conversa encerrada" / "Conversa iniciada" — chip ladeado por duas réguas finas.
+
+Não use para status de mensagem individual (use `Chip`) nem para divisões de seção genéricas fora da thread (use `Separator`).
+
+## Anatomia
+
+```
+variant="date"                          variant="boundary"
+        ┌──────────┐            ──────  ┌────────────────────┐  ──────
+        │   Hoje   │                    │ ✓ Conversa encerrada│
+        └──────────┘                    └────────────────────┘
+   (chip pílula neutra,           (chip entre 2 réguas bg-border;
+    centralizado mx-auto)          ícone opcional à esquerda)
+```
+
+## Props essenciais
+
+| Prop | Tipo | Default | Descrição |
+|------|------|---------|-----------|
+| `label` | `string` | — | **Obrigatório.** Texto centralizado da pílula. |
+| `variant` | `"date" \| "boundary"` | `"date"` | `date` = só o chip; `boundary` = chip entre 2 réguas. |
+| `icon` | `IconName` | — | Ícone opcional à esquerda do label (ex: `line-check-circle` em boundary). |
+| `className` | `string` | — | className do container (root). |
+
+## Exemplo mínimo
+
+```tsx
+import { DateSeparatorChip } from "@snksergio/design-system";
+
+// Separador de data na MessagesList
+<DateSeparatorChip label="Hoje" />
+
+// Limite de conversa
+<DateSeparatorChip
+  variant="boundary"
+  icon="line-check-circle"
+  label="Conversa encerrada"
+/>
+```
+
+## Variants
+
+| Variant | Valores | Efeito |
+|---------|---------|--------|
+| `variant` | `date` · `boundary` | `date` = chip centralizado isolado; `boundary` = chip ladeado por 2 réguas finas (`bg-border` do Separator) ocupando o espaço lateral |
+
+## Gotchas
+
+- **Composição pura:** reusa `Chip` (color `neutral`, variant `soft`, size `sm` → pílula `rounded-radius-full`, `text-caption-sm`), `Icon` (`size="xs"` = 12px) e `Separator` do shadcn. Não reescreve nenhum deles.
+- **Réguas:** as réguas de `boundary` são `<Separator>` do shadcn com só `flex-1` (slot `rule`) pra esticar — a cor `bg-border` já vem do próprio Separator, sem override; centralização do chip via `mx-auto` + `gap-gp-md` lateral.
+- **Estático:** sem foco/disabled — é um marcador, não um controle. Renderiza `role="separator"` + `aria-label={label}`.
+- **Acessibilidade do ícone:** o `Icon` aqui é decorativo (sem `title`) — o significado já vem no `label` lido pelo `aria-label` do separador.

package/dist-lib/ai/componentes/EmptyState.md

@@ -0,0 +1,72 @@
+# EmptyState
+
+**Categoria:** composto (Icon/lucide + Button). Estado vazio genérico, reusável no app inteiro — sem dados, busca sem resultado, conversa não selecionada, lista/inbox vazia, erro de carregamento, etc.
+
+## Quando usar
+
+- Uma área não tem conteúdo a exibir e você quer comunicar o porquê + (opcional) uma ação para sair do vazio.
+- Tela de chat sem conversa selecionada, tabela/lista sem itens, resultado de busca/filtro vazio.
+
+Não use para erros bloqueantes de página inteira com retry de sistema (use um padrão de erro dedicado) nem para loading (use skeleton/spinner).
+
+## Anatomia
+
+```
+        [ ícone ]        ← size-icon-xl (sm) / 2xl (md,lg), cor fg-subtle
+        Título           ← text-title-sm (sm,md) / md (lg), fg-strong
+   Descrição opcional    ← body-sm, fg-muted, max-w 360px
+       [ Button ]        ← ação opcional (mt de respiro)
+```
+
+Tudo centralizado vertical e horizontalmente, texto centralizado.
+
+## Props essenciais
+
+| Prop | Tipo | Default | Descrição |
+|------|------|---------|-----------|
+| `title` | `string` | — | **Obrigatório.** Título principal. |
+| `icon` | `LucideIcon \| ReactNode` | — | Componente lucide (ex: `Inbox`) **ou** node (Icon do DS, ilustração). Componente é dimensionado pelo `size`; node herda o tamanho via `[&_svg]:size-full`. |
+| `description` | `string` | — | Texto auxiliar sob o título. |
+| `action` | `{ label, onClick, color?, variant? } \| ReactNode` | — | Objeto vira um `<Button>` do DS; ou passe um node custom (2 botões, link...). |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Tamanho do ícone + tipografia do título + size do Button da ação. |
+| `className` | `string` | — | className do container. |
+
+## Variants
+
+| `size` | Ícone | Título | Button da ação |
+|--------|-------|--------|----------------|
+| `sm` | `size-icon-xl` (32px) | `text-title-sm` | `sm` |
+| `md` | `size-icon-2xl` (40px) | `text-title-sm` | `md` |
+| `lg` | `size-icon-2xl` (40px) | `text-title-md` | `lg` |
+
+## Exemplo mínimo
+
+```tsx
+import { Inbox } from "lucide-react";
+import { EmptyState } from "@/components/ui/EmptyState";
+
+// Lista vazia com ação
+<EmptyState
+  icon={Inbox}
+  title="Nenhuma conversa selecionada"
+  description="Selecione uma conversa ao lado para visualizar as mensagens."
+  action={{ label: "Iniciar atendimento", onClick: handleStart }}
+/>
+
+// Só ícone + título (busca sem resultado)
+<EmptyState size="sm" icon={Search} title="Nenhum resultado encontrado" />
+
+// Ícone custom via Icon do DS + ação custom (node)
+<EmptyState
+  icon={<Icon name="line-mail" />}
+  title="Caixa de entrada vazia"
+  action={<MyCustomButtons />}
+/>
+```
+
+## Gotchas / cuidados
+
+- **`icon` aceita componente OU node.** Passe a referência do componente lucide (`icon={Inbox}`, sem `<>`), que ele é instanciado e dimensionado pelo `size`. Para um `<Icon>` do DS ou ilustração, passe o elemento (`icon={<Icon name="..." />}`) — o wrapper aplica cor `fg-subtle` e o SVG ocupa o tamanho via `[&_svg]:size-full`.
+- **`action` é discriminada em runtime:** objeto plano com `label`+`onClick` vira Button; qualquer element React é renderizado como está. Para customizar a cor/variante do Button, use `{ label, onClick, color, variant }`.
+- Componente declarativo de **display** — não tem foco próprio nem `disabled`. O único elemento interativo é o Button da ação (já traz o Padrão 1 de foco do DS).
+- O título usa `<h3>`; garanta hierarquia de headings coerente na página que o consome.

package/dist-lib/ai/componentes/FileUploadField.md

@@ -0,0 +1,95 @@
+# FileUploadField — USAGE
+
+Captura de **um** arquivo com preview. Componente **dumb**: só captura o `File` e
+mostra preview — o **consumidor faz o upload**. Categoria: form / data-input.
+
+Composto de `FormField` (label/estado/erro) + `Button` + `Chip` + `Icon` + `tv()`.
+
+## Quando usar
+
+- Anexar avatar, logo, comprovante, documento único em um formulário.
+- Quando o upload é responsabilidade do consumer (envia o `File` pra API depois).
+- Para **múltiplos** arquivos ou drag & drop, NÃO use este (single-file; D&D é fase 2).
+
+## Import
+
+```tsx
+import { FileUploadField } from "@/components/ui/FileUploadField";
+```
+
+## Props essenciais
+
+| Prop | Tipo | Default | Descrição |
+|---|---|---|---|
+| `value` | `File \| string \| null` | — (req) | `File` recém-selecionado, `string` (URL hospedada) ou `null` (vazio) |
+| `onChange` | `(file: File \| null) => void` | — (req) | Selecionar → `File`; remover → `null` |
+| `accept` | `string` | — | Filtro do seletor + validação (`"image/*"`, `".pdf,.png"`) |
+| `maxSizeMB` | `number` | — | Tamanho máximo; acima → rejeitado via `onError("size")` |
+| `preview` | `"image" \| "file" \| "auto"` | `"auto"` | Modo de preview; `auto` infere por accept/MIME |
+| `fileName` | `string` | — | Nome exibido quando `value` é uma URL |
+| `label` | `string` | — | Label (renderizado pelo FormField) |
+| `required` | `boolean` | — | Asterisco no label |
+| `state` | `"default" \| "error" \| "warning" \| "success"` | `"default"` | Estado semântico do FormField |
+| `errorMessage` | `string` | — | Mensagem quando `state="error"` |
+| `helperText` | `string` | — | Texto auxiliar abaixo do campo |
+| `onError` | `(reason: "type" \| "size") => void` | — | Disparado quando arquivo é rejeitado |
+| `disabled` | `boolean` | — | Desabilita dropzone + remover |
+| `id` | `string` | — | id do input (linka label↔input) |
+| `className` | `string` | — | className do container (FormField) |
+
+## Estados visuais
+
+| value | Render |
+|---|---|
+| `null` | Dropzone `<button>` full-width (`min-h-form-xl`, dashed) com ícone + "Clique para anexar" + hint accept/maxSize |
+| `File`/URL imagem | Row: thumbnail (`size-icon-2xl`, object-cover) + botão remover |
+| `File`/URL arquivo | Row: Chip soft (ícone file + nome truncate) + botão remover |
+
+## Exemplo mínimo
+
+```tsx
+const [file, setFile] = useState<File | null>(null);
+
+<FileUploadField
+  label="Comprovante"
+  required
+  value={file}
+  onChange={setFile}
+  accept="image/*,.pdf"
+  maxSizeMB={5}
+  onError={(reason) =>
+    toast.error(reason === "size" ? "Arquivo muito grande" : "Tipo inválido")
+  }
+/>
+```
+
+### Editar registro existente (value como URL)
+
+```tsx
+<FileUploadField
+  label="Logo"
+  value={logoUrl}            // string (URL já hospedada)
+  fileName="logo.png"
+  onChange={(f) => setNewLogo(f)}  // null = remover, File = trocar
+  accept="image/*"
+  preview="image"
+/>
+```
+
+## Gotchas / cuidados
+
+- **Dumb component**: não envia nada à rede. O `onChange(File)` te dá o `File`;
+  faça `FormData`/upload no consumer e persista a URL retornada.
+- Arquivo rejeitado (tipo/tamanho) **não** vira `value` — só dispara `onError`.
+  Para feedback visual no campo, controle `state="error"` + `errorMessage` no consumer.
+- Preview de `File` usa `URL.createObjectURL` (revogado automaticamente). Para URL
+  string, o `src` é o próprio value.
+- Single-file: o input não tem `multiple`. Drag & drop é fase 2 (API preservada).
+- A11y: dropzone é `<button>` (Enter/Space abrem o seletor); input file hidden com
+  `id` do FormField; thumbnail tem `alt`; remover é icon-only com `aria-label`.
+
+## Fonte de verdade
+
+- Estilos: `file-upload-field.styles.ts` (tv())
+- Lógica: `file-upload-field.tsx`
+- Tipos: `file-upload-field.types.ts`

package/dist-lib/ai/componentes/FloatingPanel.md

@@ -0,0 +1,118 @@
+# FloatingPanel — USAGE
+
+<!-- ds:regras
+- painel de DETALHE → siga o bloco `dsgreen-paneldetail-1`, que é o **padrão**. As variações são opt-in: use `-2` (tarefa com abas) ou `-3` (com tabela, `size="xl"`) **só se o usuário citar o ID**
+- em todos: identidade ou contexto no `titleSlot`, ações de ícone `soft` + `aria-label` no `headerActions`, ação primária no `footer` — nunca botão de ação solto no corpo
+- `bodyPadded={false}` quando usar `FloatingPanelSection` (a section gerencia padding e divisória full-width)
+- é REDIMENSIONÁVEL em runtime — nenhuma largura escrita na mão acompanha o arrasto
+- aba dentro dele → `<Tabs fullWidth>` na variante default; `line` aqui vira trilho curto
+-->
+
+Drawer card flutuante non-modal — resizável, maximizável, coexiste com página atrás (sem backdrop).
+
+## Quando usar
+- Detail panel que precisa ficar visível enquanto user interage com lista atrás
+- Side-drawer leve sem bloquear navegação
+- Painel de propriedades estilo Figma/Notion
+
+## Import
+```tsx
+import {
+  FloatingPanel,
+  FloatingPanelSection, // seção colapsável (detail panel)
+  FloatingPanelField,   // linha label : valor
+} from "@/components/ui/FloatingPanel";
+```
+
+## Variants
+| Variant | Valores | Default | Quando |
+|---|---|---|---|
+| `side` | left / right | right | Lado de ancoragem |
+| `size` | sm / md / lg / xl / number (px) | md | sm=320, md=400, lg=560, xl=720px. `number` = largura custom em px; com `resizable`, vira a largura inicial |
+
+## Props essenciais
+| Prop | Tipo | Função |
+|---|---|---|
+| `open` | boolean | Visibilidade |
+| `onOpenChange` | (open: boolean) => void | Callback de fechamento |
+| `title` | string | Header title |
+| `description` | string | Header subtitle |
+| `titleIcon` | LucideIcon | Ícone à esquerda do título |
+| `hideClose` | boolean | Esconde o botão X de fechar (default `false`) |
+| `resizable` | boolean | Habilita drag-resize (desabilitado em mobile) |
+| `resizableMinWidth` / `resizableMaxWidth` | number | Bounds do resize em px (defaults `320` / `800`). São **px cegos à viewport** — quem impede o estouro é o teto `md:max-w-[calc(100vw-48px)]` do próprio painel, que mantém o gutter de 24px dos dois lados. Antes dele, props default numa janela de 800px punham a borda esquerda em **-24px** (800 de largura + 24 de gutter = 824 necessários) |
+| `resizableStorageKey` | string | Chave do localStorage pra persistir width entre sessões |
+| `maximizable` | boolean | Botão de expandir pra fullscreen |
+| `headerActions` | ReactNode | Slots no header |
+| `footer` | ReactNode | Slot do footer sticky |
+| `titleSlot` | ReactNode | Override total do header (avatar + nome custom) |
+| `bodyPadded` | boolean | Padding interno padrão do body (gutter 18px). **Default `true`** — conteúdo livre já respira. Use `false` com `<FloatingPanelSection>` (sections gerenciam o próprio padding edge-to-edge) |
+
+## Exemplo mínimo (conteúdo livre — padding automático)
+```tsx
+<FloatingPanel
+  open={panelOpen}
+  onOpenChange={setPanelOpen}
+  side="right"
+  size="md"
+  title="Detalhes do cliente"
+  description="Última edição há 2h"
+  resizable
+  maximizable
+  footer={<><Button variant="ghost">Cancelar</Button><Button>Salvar</Button></>}
+>
+  {/* bodyPadded=true (default) → conteúdo já tem gutter, não precisa de p-* manual */}
+  <ClientDetails />
+</FloatingPanel>
+```
+
+## Detail panel padrão → o bloco `dsgreen-paneldetail-1`
+
+**Painel de detalhe de registro tem estrutura definida, e ela é referenciável por ID.** A
+composição inteira (com fixture, medições e o porquê de cada decisão) vive em
+`src/blocks/paneldetail/` e é renderizada em `#/blocks-paneldetail`. Cite o ID em vez de
+recompor: `use a referência dsgreen-paneldetail-1 no painel de detalhe do pedido`.
+
+As quatro zonas, que são o que a IA erra quando compõe do zero — ela joga tudo no corpo:
+
+| zona | o que vai | por que |
+|---|---|---|
+| `titleSlot` | avatar + nome + código · Chip de status | responde "de quem é este painel"; fica fixo no scroll |
+| `headerActions` | 1–2 ações de ícone, **sempre `variant="soft"`** | `ghost` no meio da fileira fica sem container e lê como desabilitada ao lado do maximize/close, que são `soft` |
+| corpo, 1ª seção | métricas em **cards compactos** (não `Kpi`) | responde "como este registro está?" — vem antes dos campos, que respondem "quais são os dados" |
+| corpo, resto | campos em `FloatingPanelSection` por assunto | o colapso é o que permite 20 campos sem obrigar a rolar 20 |
+| `footer` | Fechar + ação primária | a ação que fecha a tarefa, sempre alcançável |
+
+⛔ **Não use aba aqui.** Se o corpo já é pilha de seções colapsáveis, o colapso **é** o
+mecanismo de esconder — ter os dois faz o usuário procurar o dado em dois lugares. Recorte
+volumoso de verdade (extrato de 200 linhas) não é aba nem seção: é outra tela.
+
+### Anatomia mínima
+
+Use `bodyPadded={false}` (as sections têm padding + divisória própria):
+
+```tsx
+<FloatingPanel open={open} onOpenChange={setOpen} bodyPadded={false} titleSlot={<HeaderCustom />}>
+  <FloatingPanelSection title="Contato">          {/* colapsável (default) */}
+    <FloatingPanelField label="Email" value={<a href={...}>{email}</a>} />
+    <FloatingPanelField label="Telefone" value={phone} />
+  </FloatingPanelSection>
+  <FloatingPanelSection title="Financeiro" defaultOpen={false}>
+    <FloatingPanelField label="Saldo" value={formatBRL(saldo)} />
+  </FloatingPanelSection>
+</FloatingPanel>
+```
+
+- `FloatingPanelSection` — props: `title`, `collapsible` (default `true`), `defaultOpen` (default `true`).
+- `FloatingPanelField` — props: `label`, `value` (fallback "—" quando vazio).
+
+## Cuidados / Gotchas
+- **Aba dentro do FloatingPanel** → `<Tabs fullWidth>` com a variante **default** (`segmented`). Aqui é o caso mais forte da prop: o painel é **redimensionável em runtime** (`sm` 320 · `md` 400 · `lg` 560 · `xl` 720, e o usuário arrasta), então nenhuma largura escrita na mão acompanha — `fullWidth` distribui os triggers e a aba segue o arrasto.
+
+- Renderizado via **portal em document.body** — escapa de overflow/transform ancestrais
+- Em mobile (<md) vira **sheet bottom-up colado nas bordas** do device: flush nas laterais + bottom, só cantos superiores arredondados, sem outline/shadow, `max-height: 92vh`
+- **Backdrop só em mobile** — scrim suave (toque fora fecha). No **desktop segue non-modal** (sem backdrop, página atrás clicável). Pra modal full use `<Modal>` ou `<AlertModal>`
+- **Body com scroll automático** (`overflow-y-auto` + `min-h-0`) — header/footer ficam fixos, conteúdo longo rola
+- **Footer fluido**: botões crescem lado a lado e **empilham quando não cabem** (`flex-wrap` + `flex-1` + `min-w-140px`). Não precisa passar `fullWidth` nos Buttons
+- `maximizable=true` adiciona botão de expandir; estado controlado internamente — `defaultMaximized` (default `false`) inicia maximizado
+- **ESC fecha por padrão** (`closeOnEscape` default `true`) — passe `false` pra desativar

package/dist-lib/ai/componentes/FooterTable.md

@@ -0,0 +1,62 @@
+# FooterTable — USAGE
+
+Footer de tabela com paginação + page-size select + range display + selection count.
+
+## Quando usar
+- Rodapé de qualquer `<Table>` ou `<DataTable>` (já é embutido no DataTable)
+- Listas paginadas com seleção múltipla
+
+## Import
+```tsx
+import { FooterTable } from "@/components/ui/FooterTable";
+```
+
+## Props essenciais
+| Prop | Tipo | Default | Função |
+|---|---|---|---|
+| `totalCount` | number | — | Total de registros |
+| `page` | number | — | Página atual (1-indexed) |
+| `pageSize` | number | — | Tamanho da página atual |
+| `onPageChange` | (page: number) => void | — | Callback de paginação |
+| `onPageSizeChange` | (size: number) => void | — | Callback de troca de page-size |
+| `pageSizeOptions` | number[] | [10, 25, 50, 100] | Opções do select |
+| `selectionCount` | number | 0 | Quantos selecionados (acrescenta "· N selecionado(s)" ao lado do range) |
+| `pageSizeLabel` | string | "Linhas" | Label do select de page-size |
+| `rowLabel` | string | "rows" | Sufixo do range (ex "registros") |
+| `locale` | string | "pt-BR" | Locale pra formatar números do range |
+| `hidePageSize` | boolean | false | Esconde select de page-size |
+| `hideRange` | boolean | false | Esconde "1–10 de 87 rows" |
+| `hideFirstLast` | boolean | false | Esconde botões « » |
+
+## Exemplo mínimo
+```tsx
+<FooterTable
+  totalCount={87}
+  page={currentPage}
+  pageSize={10}
+  onPageChange={setPage}
+  onPageSizeChange={setPageSize}
+  selectionCount={selectedIds.length}
+/>
+```
+
+## FooterTableSkeleton
+Estado loading do footer — usado pelo DataTable enquanto a primeira chamada de `fetchData` não retornou `totalCount`. Mantém a mesma silhueta do footer real pra evitar layout shift.
+
+```tsx
+import { FooterTableSkeleton } from "@/components/ui/FooterTable";
+
+<FooterTableSkeleton pageButtonCount={5} />
+```
+
+| Prop | Tipo | Default | Função |
+|---|---|---|---|
+| `pageButtonCount` | number | 5 | Quantos botões de página simular |
+| `className` | string | — | className extra no `<footer>` |
+
+## Cuidados / Gotchas
+- Calcula range "1–10 de 87 rows" automaticamente (sufixo customizável via `rowLabel`)
+- Empilha vertical em mobile (`flex-col <sm`) — layout fixo, sem custom
+- `selectionCount > 0` acrescenta "· N selecionado(s)" ao lado do range — NÃO substitui o range; pra esconder o range use `hideRange`
+- Default `rowLabel = "rows"` produz texto misto ("1–10 de 87 rows") — passe `rowLabel="registros"` pra texto 100% pt-BR
+- Pra usar fora de tabela, pode ser standalone — props são puramente paginação

package/dist-lib/ai/componentes/FormField.md

@@ -0,0 +1,110 @@
+# FormField — USAGE
+
+Container de form com label + field + mensagem de validação (error/warning/success). Inclui wrappers "one-shot" (`FormFieldInput`, `FormFieldSelect`, etc) — a forma recomendada de consumo em forms (L-023).
+
+## Quando usar
+
+- Qualquer campo de formulário que tenha label + input + validação
+- Garantir spacing e tipografia consistente entre campos
+- NUNCA escrever `<label>` raw com classes manuais em forms (L-023)
+
+## Import
+
+```tsx
+import {
+  FormField, // base (children render-prop) — para widgets custom
+  FormFieldInput, // wrappers one-shot (recomendados)
+  FormFieldTextarea,
+  FormFieldSelect,
+  FormFieldCheckbox,
+  FormFieldSwitch,
+} from "@/components/ui/FormField";
+import type { FieldState, FormFieldSelectOption } from "@/components/ui/FormField";
+```
+
+## Props essenciais
+
+### `FormFieldBaseProps` — comuns a todos
+
+| Prop             | Tipo                                              | Default       | Função                                                       |
+| ---------------- | ------------------------------------------------- | ------------- | ------------------------------------------------------------ |
+| `label`          | `string`                                          | —             | Label acima do field (Checkbox/Switch: `ReactNode`, inline)  |
+| `required`       | boolean                                           | `false`       | Asterisco vermelho ao lado do label (só visual)              |
+| `helperText`     | `ReactNode`                                       | —             | Texto auxiliar abaixo do field                               |
+| `state`          | `"default" \| "error" \| "warning" \| "success"`  | `"default"`   | Estado semântico — afeta borda do field e mensagem exibida   |
+| `errorMessage`   | `ReactNode`                                       | —             | Exibida quando `state="error"` (substitui o helperText)      |
+| `warningMessage` | `ReactNode`                                       | —             | Exibida quando `state="warning"`                             |
+| `successMessage` | `ReactNode`                                       | —             | Exibida quando `state="success"`                             |
+| `id`             | `string`                                          | auto (`useId`) | Linka label↔input via `htmlFor`                             |
+| `className`      | `string`                                          | —             | className do container externo                               |
+
+### Específicas do `FormField` (base)
+
+| Prop        | Tipo                                                  | Função                                                                       |
+| ----------- | ----------------------------------------------------- | ---------------------------------------------------------------------------- |
+| `children`  | `(ctx: { id: string; state: FieldState }) => ReactNode` | **Render-prop obrigatório** — recebe o id gerado + state pra repassar ao field |
+| `hideLabel` | boolean                                               | Esconde o label (field self-contained, ex: Checkbox com label inline)        |
+| `disabled`  | boolean                                               | Esmaece SÓ o label (opacity-50) — o field filho precisa do próprio `disabled` |
+
+### Wrappers one-shot (recomendados — L-023)
+
+| Componente          | Field interno                  | Extras                                                                                                                                        |
+| ------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `FormFieldInput`    | `Input` / `InputGroup` (shadcn) | `startAddon` / `endAddon` (`ReactNode`; string vira `InputGroupText`, ex `"R$"`) + props de `Input`                                            |
+| `FormFieldTextarea` | `Textarea` (shadcn)            | props de `Textarea`                                                                                                                            |
+| `FormFieldSelect`   | `Select` (radix/shadcn)        | `options: FormFieldSelectOption[]` (`{ value, label, disabled? }`), `placeholder`, `value`, `defaultValue`, `onValueChange`, `disabled`, `triggerClassName`, `contentClassName` |
+| `FormFieldCheckbox` | `Checkbox` (shadcn)            | label inline à direita do checkbox; props do Radix `Checkbox.Root`                                                                             |
+| `FormFieldSwitch`   | `Switch` (shadcn)              | label inline; `switchPosition?: "start" \| "end"` (default `"end"`); props do Radix `Switch.Root`                                              |
+
+## Variants (slots internos de estilo)
+
+| Slot                        | Variant    | Valores                              | Default |
+| --------------------------- | ---------- | ------------------------------------ | ------- |
+| Label (`formFieldLabel`)    | `disabled` | true/false                           | false   |
+| Message (`formFieldMessage`) | `state`    | default / error / warning / success  | default |
+
+O container (`formFieldRoot`) não tem variants — é base-only (`flex flex-col gap-[7px] w-full`).
+
+## Exemplo mínimo
+
+```tsx
+// Wrapper one-shot — forma recomendada
+<FormFieldInput
+  label="Email"
+  required
+  type="email"
+  state="error"
+  errorMessage="Email inválido"
+  value={email}
+  onChange={(e) => setEmail(e.target.value)}
+/>
+
+// Com addons
+<FormFieldInput label="Valor" startAddon="R$" placeholder="0,00" />
+
+// Select
+<FormFieldSelect
+  label="País"
+  placeholder="Selecione..."
+  options={[
+    { value: "br", label: "Brasil" },
+    { value: "us", label: "Estados Unidos" },
+  ]}
+/>
+
+// Base com widget custom — children é render-prop
+<FormField label="Email" required state="error" errorMessage="Email inválido">
+  {({ id, state }) => <Input id={id} state={state} type="email" />}
+</FormField>
+```
+
+## Cuidados / Gotchas
+
+- `children` do `FormField` base é **função** (render-prop), não JSX direto — passar ReactNode é erro de tipo e quebra em runtime
+- NÃO existem componentes `FormFieldLabel`/`FormFieldMessage` — label e mensagem são props (`label`, `errorMessage`, `helperText`...); esses nomes existem só como slots internos em `form-field.styles.ts`
+- Prioridade da mensagem: error → warning → success → helperText. A mensagem do state só aparece se a prop correspondente (`errorMessage`, etc) for passada
+- O `state` é propagado ao field via argumento do render-prop (`ctx.state`) — não há context; em widget custom, repasse `id` e `state` manualmente
+- `disabled` no `FormField` base esmaece apenas o label — passe `disabled` também ao field. Os wrappers (`FormFieldInput`, etc) propagam automaticamente
+- Mensagem com `state="error"` recebe `role="alert"` (acessibilidade)
+- Spacing label/field/message é do container — não adicionar margins customizados; entre fields empilhados use `gap-form-gap` (L-024)
+- `required` é só visual — validação real é responsabilidade do consumer