@snksergio/design-system 0.61.0 → 0.63.0

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

@@ -0,0 +1,65 @@
+# Icon — USAGE
+
+Biblioteca de ícones própria da iGreen. O SVG é fixo; só o `d` do path muda via
+prop `name` (mapa de tokens em `icons.ts`). Categoria: data-display / foundation.
+
+## Quando usar
+
+- Ícones da identidade iGreen (não cobertos / divergentes do lucide).
+- Quando precisar de um set controlado e versionado dentro do DS.
+- Para ícones genéricos de UI, `lucide-react` continua válido — este componente é
+  o set **próprio** da marca.
+
+## Import
+
+```tsx
+import { Icon } from "@/components/ui/Icon";
+```
+
+## Exemplo mínimo
+
+```tsx
+<Icon name="line-user" />                      {/* md (20px), currentColor */}
+<Icon name="fill-user" size="lg" tone="brand" />
+<Icon name="line-edit" size={28} color="#0fc589" />
+<span className="text-fg-danger"><Icon name="line-bin" /></span>  {/* herda via CSS */}
+```
+
+## Props
+
+| Prop | Valor | Default |
+|---|---|---|
+| `name` | `IconName` (autocomplete da lib) | — |
+| `size` | preset `xs\|sm\|md\|lg\|xl` (tokens `size-icon-*` = 12/16/20/24/32) **ou** arbitrário (`number`→px / string CSS) | `md` |
+| `tone` | semântico → `text-fg-{default\|muted\|brand\|danger\|success\|warning\|info}` | — |
+| `color` | qualquer cor CSS (override; vence `tone`/CSS) | — |
+| `title` / `aria-label` | acessível → `role="img"` + `<title>`. Sem isso = decorativo (`aria-hidden`) | decorativo |
+
+## Cor — 3 formas
+
+1. **CSS** (recomendado): herda `currentColor`, controlável por classe — `<span className="text-fg-brand"><Icon name="..."/></span>`.
+2. **`tone`**: token semântico do DS (`tone="danger"`).
+3. **`color`**: valor CSS arbitrário (`color="#0fc589"` / `color="var(--x)"`).
+
+## Convenção de nomes
+
+- Prefixo `line-*` → contorno (viewBox `0 0 18 18` no set legado, senão 24).
+- Prefixo `fill-*` → preenchido (viewBox `0 0 24 24`).
+- Prefixo `igreen-*` → **ícones oficiais de marca** (produtos: green, livre, placas,
+  club, solar, telecom, licenciado, seguro, clientes). viewBox 24, herdam
+  `currentColor`/`tone` como qualquer ícone (sem cor fixa).
+- O `viewBox` é inferido automaticamente pelo prefixo.
+
+## Adicionar um ícone novo
+
+1. Adicionar a entrada `"line-foo": "M…"` (ou `"fill-foo"` / `"igreen-foo"`) em `icons.ts`.
+2. O `IconName` atualiza sozinho (deriva das chaves). Sem mais nada.
+3. **Multi-path**: o valor pode ser `string` (1 path) **ou** `string[]` (vários paths
+   sobrepostos — ex.: `igreen-club`). Remova `fill=` hardcoded do SVG (herda `currentColor`).
+
+## Gotchas
+
+- `size` arbitrário aplica `width`/`height` inline (não usa token) — prefira os presets.
+- Decorativo por padrão (`aria-hidden`); passe `title`/`aria-label` quando o ícone
+  carregar significado sozinho.
+- Catálogo navegável (busca + copiar nome): doc `#/icon`.

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

@@ -0,0 +1,343 @@
+# Kanban — Guia de uso
+
+Primitive dumb (igual `<Table>`, `<TableToolbar>`, `<FooterTable>`) — recebe `columns` + `cards` via props e renderiza um board horizontal de estágios. Não gerencia state de domínio (selection, detail, menus, dados) — tudo controlado externamente.
+
+> Padrão equivalente ao DNA do DS: primitives dumb + smart orchestrators. Pra usar o Kanban acoplado a filter/sort/search da `<DataTable>`, veja [Integração com DataTable](#integração-com-datatable) abaixo.
+
+---
+
+## Imports
+
+```tsx
+import {
+  Kanban,
+  type KanbanColumn,
+  type KanbanCardData,
+  type KanbanMenuItem,
+  type KanbanRenderCardParams,
+} from "@/components/ui/Kanban";
+```
+
+---
+
+## Quick start — uso standalone
+
+```tsx
+const columns: KanbanColumn[] = [
+  { id: "todo",  label: "A fazer", dotColor: "var(--color-fg-muted)" },
+  { id: "doing", label: "Em andamento", dotColor: "var(--color-fg-info)" },
+  { id: "done",  label: "Concluído", dotColor: "var(--color-fg-success)", canReceiveDrop: false },
+];
+
+const cards: KanbanCardData[] = tasks.map((t) => ({
+  id: t.id,
+  columnId: t.status,
+  title: t.title,
+  subtitle: t.code,
+  avatar: <Avatar size="sm" colorHex={t.assignee.color}>{t.assignee.initials}</Avatar>,
+  chip: <Chip color="warning" variant="soft" size="sm">Urgente</Chip>,
+  value: formatBRL(t.value),
+}));
+
+<Kanban
+  columns={columns}
+  cards={cards}
+  selectedIds={selectedIds}
+  onToggleSelect={toggleSelect}
+  onOpenCard={(id) => openTaskDetail(id)}
+/>
+```
+
+---
+
+## Capacidades
+
+| Capability | Como ativar |
+|------------|-------------|
+| **Seleção (bulk)** | `selectedIds: Set<string>` + `onToggleSelect: (cardId) => void` — checkbox aparece no hover do card |
+| **Card aberto (detail)** | `openCardId` + `onOpenCard: (cardId) => void` — strip lateral brand |
+| **Add card (header)** | `onAddCard: (columnId) => void` — botão `+` no header da coluna |
+| **Add card (footer)** | `onAddInFooter: (columnId) => void` + `hideFooterAdd?: false` (default) |
+| **Menu coluna** | `onColumnMenu: (columnId, anchor) => void` (manual) OU `getColumnMenuItems: (col) => KanbanMenuItem[]` (auto) |
+| **Menu card** | `onCardMenu: (cardId, anchor) => void` (manual) OU `getCardMenuItems: (card) => KanbanMenuItem[]` (auto) |
+| **Card render custom** | `renderCard: ({ card, selected, open }) => ReactNode` — substitui o miolo; wrapper continua sob controle do primitive |
+| **DnD entre colunas** | `enableDnD: true` + `onCardMove: (cardId, from, to) => void \| Promise<unknown>` |
+| **Constraint por coluna** | `column.canReceiveDrop: false` (terminal) + `column.canDragFrom: false` (locked) |
+
+---
+
+## Recipes
+
+### Menus padronizados via items
+
+```tsx
+const cardMenu = (card: KanbanCardData): KanbanMenuItem[] => [
+  { label: "Ver detalhes", icon: <Eye />,    onClick: () => openDetail(card.id) },
+  { label: "Editar",       icon: <Pencil />, onClick: () => openEdit(card.id) },
+  { separator: true },
+  { label: "Excluir",      icon: <Trash2 />, destructive: true, onClick: () => remove(card.id) },
+];
+
+<Kanban {...} getCardMenuItems={cardMenu} />
+```
+
+Primitive renderiza `<DropdownMenu>` DS automático. `KanbanMenuItem`:
+- `label?` — string (ignorado se `separator: true`)
+- `icon?` — ReactNode
+- `onClick?` — handler
+- `destructive?` — vermelho via `variant="destructive"`
+- `disabled?` — bloqueia hover/click
+- `separator?` — renderiza `<DropdownMenuSeparator>`
+
+Coexiste com `onCardMenu`/`onColumnMenu` (callbacks manuais) — quando ambos fornecidos, `get*MenuItems` ganha.
+
+### Drag-and-Drop entre colunas
+
+```tsx
+<Kanban
+  columns={[
+    { id: "active",   label: "Ativo" },
+    { id: "pending",  label: "Pendente" },
+    { id: "done",     label: "Concluído", canReceiveDrop: false }, // terminal
+    { id: "archived", label: "Arquivado", canDragFrom: false },     // locked source
+  ]}
+  cards={cards}
+  enableDnD
+  onCardMove={(cardId, from, to) => {
+    // Optimistic update (consumer comita via props)
+    setCards((prev) =>
+      prev.map((c) => (c.id === cardId ? { ...c, columnId: to } : c)),
+    );
+  }}
+/>
+```
+
+**Visual feedback built-in:**
+- Card sendo arrastado: `opacity-40 cursor-grabbing`
+- Coluna candidata válida durante drag: outline brand + bg subtle + **drop placeholder** (linha fina com ícone `+`) na posição que vai aterrissar (antes do card hovered, ou no fim se hover em área vazia)
+- Coluna inválida (`canReceiveDrop: false`): `opacity-50` sempre durante drag (atenuada); `cursor-not-allowed` quando over
+
+**Primitive não faz revert**: se `onCardMove` falhar, consumer mantém `cards` props inalterado e o card visualmente "volta" (porque a fonte da verdade são os props). Pra async commit:
+
+```tsx
+onCardMove={async (cardId, from, to) => {
+  setCards((prev) => prev.map((c) => c.id === cardId ? { ...c, columnId: to } : c)); // optimistic
+  try {
+    await api.patch(`/cards/${cardId}`, { columnId: to });
+  } catch {
+    setCards((prev) => prev.map((c) => c.id === cardId ? { ...c, columnId: from } : c)); // revert
+  }
+}}
+```
+
+### Render custom do card
+
+```tsx
+<Kanban
+  {...}
+  renderCard={({ card, selected, open }) => (
+    <>
+      <div className="flex items-center gap-gp-md">
+        {card.avatar}
+        <span className="text-body-md font-medium flex-1 truncate">{card.title}</span>
+        {open && <Eye className="size-icon-sm text-fg-brand" />}
+      </div>
+      <Timeline events={card.description} />
+    </>
+  )}
+/>
+```
+
+Consumer customiza o **miolo** do card. Wrapper externo (border, shadow, focus ring, checkbox/menu positioning, accessibility) continua sob controle do primitive — garante consistência visual entre boards customizados.
+
+---
+
+## Integração com DataTable
+
+`<DataTable>` é o smart orchestrator. Quando `viewMode="kanban"` + `kanbanConfig`:
+- Filter/search/sort/selection aplicam transparente nas rows
+- O processado (já filtrado/ordenado) é mapeado em `<Kanban>` cards via `kanbanConfig.renderCard`
+- Paginação é desligada automaticamente (não se aplica em board)
+- TableToolbar parts irrelevantes (density, columns popover) podem ser ocultados via `toolbar.enableDensity: false`/`enableColumns: false` condicional
+
+### Paridade com `<Kanban>` standalone
+
+O `DataTableKanbanConfig` é **1:1 com `KanbanProps`** — toda capability do primitive está exposta no smart wrapper. Bridge automático resolve `cardId → row` onde aplicável.
+
+| `<Kanban>` prop | `kanbanConfig.*` | Bridge |
+|---|---|---|
+| `columns` | `columns?` | Auto-deriva de valores únicos do `groupByField` se omitido |
+| `cards` | (derivado) | Transformer `useDataTableViewMode` mapeia rows → cards |
+| `selectedIds` | (auto) | Bridge: `selectionModel.ids` (apenas modo include) |
+| `onToggleSelect` | (auto) | Bridge: `cardId → row → selection.toggleRow(row)` |
+| `openCardId` | `openCardId?` | Passthrough direto |
+| `onOpenCard` | (auto) | Bridge: `cardId → row → onRowClick(row)` |
+| `onAddCard` | `onAddCard?` | Passthrough direto (recebe `columnId`) |
+| `onAddInFooter` | `onAddInFooter?` | Passthrough direto |
+| `hideFooterAdd` | `hideFooterAdd?` | Passthrough direto |
+| `getCardMenuItems` | `getCardMenuItems?` | Bridge: recebe `row` (não `card`) — consumer-friendly |
+| `onCardMenu` | `onCardMenu?` | Passthrough direto (recebe `cardId, anchor`). Ignorado se `getCardMenuItems` definido |
+| `getColumnMenuItems` | `getColumnMenuItems?` | Passthrough direto |
+| `onColumnMenu` | `onColumnMenu?` | Passthrough direto. Ignorado se `getColumnMenuItems` definido |
+| `renderCard` (slot) | `renderCardContent?` | Bridge: recebe `{ card, row, selected, open }` — adiciona `row` original |
+| `enableDnD` | `enableDnD?` | Passthrough direto |
+| `onCardMove` | `onCardMove?` | Passthrough direto |
+| `emptyLabel` | `emptyLabel?` | Passthrough direto |
+| `addLabel` | `addLabel?` | Passthrough direto |
+
+> `renderCard` no `DataTableKanbanConfig` é o **mapeador de slots** (avatar/title/chip/...) — diferente do `renderCardContent` que substitui o miolo inteiro.
+
+### Exemplo completo
+
+```tsx
+const [viewMode, setViewMode] = useState<DataTableViewMode>("table");
+const [openCardId, setOpenCardId] = useState<string>();
+
+<DataTable<Task>
+  rows={tasks}
+  columns={tableColumns}
+  viewMode={viewMode}
+  onViewModeChange={setViewMode}
+  onRowClick={(row) => setOpenCardId(row.id)} // bridge cobre kanban também
+  kanbanConfig={{
+    groupByField: "status",
+    columns: [
+      { id: "todo",  label: "A fazer" },
+      { id: "doing", label: "Em andamento" },
+      { id: "done",  label: "Concluído", canReceiveDrop: false },
+    ],
+
+    // Mapeador de slots (uso comum)
+    renderCard: ({ row }) => ({
+      title: row.title,
+      subtitle: row.code,
+      avatar: <Avatar size="sm" colorHex={row.assignee.color}>{row.assignee.initials}</Avatar>,
+      chip: <Chip color="warning" variant="soft" size="sm">{row.priority}</Chip>,
+      value: formatBRL(row.value),
+    }),
+
+    // Detail panel
+    openCardId,
+
+    // Add card buttons
+    onAddCard: (columnId) => createNewTask(columnId),
+    onAddInFooter: (columnId) => createNewTask(columnId),
+    hideFooterAdd: false,
+
+    // Menus padronizados (auto via DropdownMenu DS)
+    getCardMenuItems: (row) => [
+      { label: "Editar", icon: <Pencil />, onClick: () => editTask(row) },
+      { separator: true },
+      { label: "Excluir", icon: <Trash2 />, destructive: true, onClick: () => deleteTask(row) },
+    ],
+    getColumnMenuItems: (col) => [
+      { label: "Renomear", icon: <Pencil />, onClick: () => renameColumn(col.id) },
+    ],
+
+    // DnD
+    enableDnD: true,
+    onCardMove: (cardId, _from, to) =>
+      setTasks((prev) => prev.map((t) => (t.id === cardId ? { ...t, status: to } : t))),
+
+    // Override TOTAL do miolo (opcional — sobrescreve `renderCard` slots)
+    // renderCardContent: ({ card, row, selected, open }) => <CustomTimelineCard row={row} />,
+  }}
+  toolbar={{
+    enableSearch: true,
+    enableFilters: true,
+    enableColumns: viewMode === "table", // oculta em kanban
+    enableDensity: viewMode === "table", // oculta em kanban
+    customLeft: <ToolbarSegmented value={viewMode} onValueChange={setViewMode} items={VIEW_MODES} />,
+  }}
+/>
+```
+
+Veja [src/preview/pages/ClientsKanbanPreview.tsx](../../../preview/pages/ClientsKanbanPreview.tsx) pra exemplo runnable com toggle table/kanban + DnD + filters compartilhados.
+
+---
+
+## API resumida
+
+### `KanbanProps`
+| Prop | Type | Default | Descrição |
+|---|---|---|---|
+| `columns` | `KanbanColumn[]` | — | Definição das colunas (ordem = visual) |
+| `cards` | `KanbanCardData[]` | — | Cards distribuídos via `columnId` |
+| `selectedIds` | `Set<string>` | — | IDs selecionados (estado checked); checkbox aparece quando `onToggleSelect` é fornecido |
+| `onToggleSelect` | `(cardId: string) => void` | — | Toggle do checkbox |
+| `openCardId` | `string` | — | Card aberto no detail panel (strip brand) |
+| `onOpenCard` | `(cardId: string) => void` | — | Click no card |
+| `onAddCard` | `(columnId: string) => void` | — | Botão `+` do header |
+| `onColumnMenu` | `(columnId: string, anchor: HTMLElement) => void` | — | Menu manual da coluna |
+| `getColumnMenuItems` | `(column) => KanbanMenuItem[]` | — | Menu auto (ganha de `onColumnMenu`) |
+| `onAddInFooter` | `(columnId: string) => void` | — | Botão `+ Adicionar` do rodapé |
+| `hideFooterAdd` | `boolean` | `false` | Oculta o `+ Adicionar` |
+| `onCardMenu` | `(cardId: string, anchor: HTMLElement) => void` | — | Menu manual do card |
+| `getCardMenuItems` | `(card) => KanbanMenuItem[]` | — | Menu auto (ganha de `onCardMenu`) |
+| `renderCard` | `({ card, selected, open }) => ReactNode` | — | Custom miolo do card |
+| `enableDnD` | `boolean` | `false` | Habilita DnD |
+| `onCardMove` | `(cardId, from, to) => void \| Promise<unknown>` | — | Callback de drop |
+| `emptyLabel` | `string` | `"Nenhum item neste estágio"` | Texto do empty state |
+| `addLabel` | `string` | `"Adicionar"` | Texto do botão `+ Adicionar` |
+| `className` | `string` | — | className extra no root |
+
+### `KanbanColumn`
+| Field | Type | Default | Descrição |
+|---|---|---|---|
+| `id` | `string` | — | Identificador único |
+| `label` | `string` | — | Label do header |
+| `dotColor` | `string` | — | Cor do dot (CSS var ou hex) |
+| `count` | `number` | auto | Override do badge (default = `cards.filter(c => c.columnId === id).length`) |
+| `canReceiveDrop` | `boolean` | `true` | `false` = coluna terminal/locked |
+| `canDragFrom` | `boolean` | `true` | `false` = cards desta coluna não-arrastáveis |
+
+### `KanbanCardData`
+Cada slot (`avatar`, `chip`, `value`, `footerLeft`, `footerRight`, `description`) é `ReactNode` — consumer monta usando DS (`<Avatar>`, `<Chip>`, etc) sem o Kanban ditar visual interno.
+
+---
+
+## Performance
+
+- `cards` e `columns` devem ser memoizados pelo consumer (`useMemo`) — evita recompute do filter interno (`cards.filter(c => c.columnId === col.id)`) a cada render
+- Em integração com DataTable, o transformer (`useDataTableViewMode`) já é memoizado em `rows`/`config`/`getRowId`
+- Pra > 1000 cards, considere virtualizar dentro de cada coluna (não built-in V1; consumer pode wrap `renderCard` com `react-window` se precisar)
+
+---
+
+## ARIA
+
+- Root `<Kanban>`: `role="region" aria-label="Quadro Kanban"`
+- Botões de ação/menu (`<Button>` DS) têm `aria-label` derivados das props
+- DnD via `@dnd-kit/core` traz suporte a teclado (Space/Setas) — KeyboardSensor sem configuração extra
+
+---
+
+## Troubleshooting
+
+| Sintoma | Causa | Fix |
+|---|---|---|
+| Cards não aparecem em coluna esperada | `columnId` da card não bate com `column.id` | Verificar mapping `getValue` ou hard-coded values |
+| Scroll horizontal aparece durante drag | Estado bug do `transform` (corrigido na V1 — não use `useDraggable.transform` no source quando há `<DragOverlay>`) | Atualizar Kanban primitive — V1 já não aplica transform no source |
+| Checkbox visível ao desmarcar | Bug antigo (`group-focus-within` mantém visível) | Corrigido na V1 — usa `group-focus-visible` |
+| Card "fica grande" no hover sem checkbox | `reserveCheck` aplicado por default | Corrigido na V1 — variant `reserveCheck` só ativa quando `onToggleSelect` é fornecido |
+| Avatar com letra desproporcional/desalinhada | Avatar shadcn antigo, sem `<Avatar>` iGreen | Use `<Avatar size="xs\|sm\|md\|lg\|xl" colorHex={hex}>{initials}</Avatar>` |
+| Scrollbar grossa demais | Não usa utility DS | Migrado pra `scrollbar-thin` (utility @utility no `tailwind-theme.css`) — V1 já aplica |
+| `onCardMove` chamado mas card não move | Esquema reverse: consumer não atualiza `cards` props | Optimistic update via setState (veja DnD recipe) |
+| DnD não preserva keyboard navigation | KeyboardSensor não fornecido | Já incluído via `useKanbanDnD` interno — nada a fazer |
+
+---
+
+## Versão atual: V1 — production-ready
+
+**O que entrou na V1** (refator completo 2026-05):
+- Bugs corrigidos: checkbox focus-within, avatar typography desalinhada, hover shift sem checkbox, scroll horizontal durante drag
+- Features novas: `renderCard` slot, `getCardMenuItems`/`getColumnMenuItems` padronizados, DnD entre colunas com placeholder localizado + feedback visual de coluna inválida, empty state com ícone
+- DS conformance: 3 botões raw → `<Button>` DS, 10+ hardcoded tokens migrados, scrollbar via utility `scrollbar-thin`, Avatar iGreen consumido nas previews
+- Integração: `<DataTable viewMode="kanban" kanbanConfig={...}>` orquestra filter/sort/search/selection compartilhados
+
+**Defer pra V2** (não bloqueia produção):
+- Virtualização por coluna (cards count > 1000)
+- Multi-level grouping (swimlanes)
+- WIP limits per coluna (count + visual warning)
+- Reordenação dentro da mesma coluna (hoje DnD só move entre colunas)
+- Saved views capturarem `viewMode` no DataTable persistence

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

@@ -0,0 +1,103 @@
+# Kpi
+
+<!-- ds:regras
+- `tone` e `KpiDelta tone` são DECISÃO, não derivação: subir nem sempre é bom (tempo de espera ↑ é ruim). `signed` só quando o sinal é literalmente bom/ruim
+- o valor sai do preset `stat-*` pela prop `size` (default `md`=24px) — nunca `text-[Npx]` na unha; fora do `Kpi`, `text-stat-* tabular-nums`
+- `divided` no `KpiGroup` vira UM card com divisórias e os filhos viram `plain` — não empilhe card dentro de card pra conseguir isso
+-->
+
+**O que é** — Primitivos composáveis pra cards de KPI/estatística.
+**Categoria**: Templates / App-level. Doc viva: `#/kpi`.
+
+3 peças que compõem qualquer card de métrica:
+
+| Peça       | Papel                                                                                    |
+| ---------- | ---------------------------------------------------------------------------------------- |
+| `Kpi`      | card base: label + ícone (por tone) + valor + delta + hint + slot (sparkline) + footnote |
+| `KpiGroup` | layout: `columns` (2–6, responsivo) + `divided` (vira 1 card com divisórias)             |
+| `KpiDelta` | pílula de variação (sobre o `Chip`): tom semântico + seta                                |
+
+## Quando usar
+
+Métricas de dashboard (rows de KPI, quad, cards com sparkline). Pra layouts
+muito específicos (card de marca preenchido, faixa de detalhe), componha à mão —
+veja as **Composições** em `#/kpi`.
+
+## Props
+
+### `Kpi`
+
+| Prop       | Tipo                                                   | Default                      |
+| ---------- | ------------------------------------------------------ | ---------------------------- |
+| `label`    | `string`                                               | — (obrigatório)              |
+| `value`    | `ReactNode`                                            | — (obrigatório)              |
+| `delta`    | `ReactNode` (use `<KpiDelta>`)                         | —                            |
+| `hint`     | `ReactNode` (sublabel, ex.: "vs ontem")                | —                            |
+| `icon`     | `ReactNode`                                            | —                            |
+| `tone`     | `brand·success·warning·info·danger·neutral`            | `neutral`                    |
+| `size`     | `sm·md·lg·xl` (preset `stat-*` do valor: 20/24/30/34px) | `md` (24px)                 |
+| `footnote` | `ReactNode` (com divisória acima)                      | —                            |
+| `children` | `ReactNode` (slot p/ sparkline/chart, abaixo do valor) | —                            |
+| `surface`  | `card · plain`                                         | herda do `KpiGroup` (`card`) |
+
+### `KpiGroup`
+
+| Prop      | Tipo                              | Default |
+| --------- | --------------------------------- | ------- |
+| `columns` | `2·3·4·5·6`                       | `4`     |
+| `divided` | `boolean` (1 card com divisórias) | `false` |
+
+### `KpiDelta`
+
+| Prop        | Tipo                         | Default              |
+| ----------- | ---------------------------- | -------------------- |
+| `value`     | `ReactNode`                  | —                    |
+| `tone`      | `success · danger · neutral` | `success`            |
+| `direction` | `up · down` (mostra seta)    | —                    |
+| `signed`    | `boolean` — deriva tom+seta do sinal do `value` | `false` |
+
+## Exemplo
+
+```tsx
+import { Kpi, KpiGroup, KpiDelta } from "@/components/ui/Kpi";
+import { Phone } from "lucide-react";
+
+// Row com divisórias (1 card único)
+<KpiGroup columns={4} divided>
+  <Kpi
+    label="Em atendimento"
+    value="12"
+    icon={<Phone />}
+    tone="success"
+    delta={<KpiDelta value="+3" />}
+    hint="vs ontem"
+  />
+  {/* ...mais Kpi */}
+</KpiGroup>
+
+// Card com sparkline (slot)
+<Kpi label="Total Income" value="$6,280" delta={<KpiDelta value="+18%" />}>
+  <ChartContainer config={cfg} className="h-[64px]"> ... </ChartContainer>
+</Kpi>
+```
+
+## Gotchas
+
+- **`tone` é decisão do consumidor.** "Subir" nem sempre é positivo (tempo de
+  espera ↑ é ruim) → escolha o `KpiDelta tone` certo, não derive cego da direção.
+  Atalho: `<KpiDelta value="+458" signed />` deriva verde/vermelho + seta do sinal
+  — use SÓ quando o delta é literalmente +/- bom/ruim.
+- **Composições de dashboard/lista** (Painel do Líder, fusão KPI+evolução,
+  chart-card, card dividido, distribuição de tabela/lista) → receitas canônicas na
+  rota `#/dashboard-showcase` do catálogo hospedado. (Fonte no repo do DS:
+  `.ai/context/components/dashboard-patterns.md` — caminho **interno**, não existe
+  em quem consome por npm ou copy-in.)
+- **`divided` controla a superfície** dos `Kpi` filhos (viram `plain`); fora de um
+  group `divided`, cada `Kpi` é um card. Override com a prop `surface` se preciso.
+- **Valor do KPI usa preset `stat-*`** (`size`, default `md`=24px). Números
+  grandes de dashboard → `size="lg"`/`"xl"`. Fora do `Kpi`, use `text-stat-*
+  tabular-nums` direto — nunca `text-[Npx]` na unha. O preset já traz bold +
+  leading tight; adicione só `tabular-nums`.
+- **Sparkline via `Chart`** (Recharts) no slot `children` — id de `linearGradient`
+  sem espaço/`&` (use índice), senão o `url(#...)` não resolve.
+- Cores 100% por token (tones via `bg-bg-*-muted`/`fg-*`). Sem hardcode.

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

@@ -0,0 +1,61 @@
+# List — USAGE
+
+**O que é:** primitivo de listagem em **cards** (cada row é um card). _Categoria: Data display._
+Burro como o `Table` — a versão com toolbar/busca/filtros/server (`DataList`) é o passo 2.
+
+**Quando usar:** listas de entidades em formato card, com 3 layouts:
+- `standard` — lista plana.
+- `grouped` — seções por status/seção + **drag-and-drop** (entre grupos e reorder dentro).
+- `hierarchical` — árvore-como-lista colapsável com **linhas de conexão** (org, treeview).
+
+Para tabela densa use `Table`/`DataTable`; para colunas horizontais use `Kanban`.
+
+## Conteúdo do card
+Slots (`ListItemData`): `leading` (avatar/ícone), `title`, `subtitle`, `description`,
+`meta` (colunas alinhadas tipo Role/Status), `trailing` (valor/badge). Para card rico,
+`renderItem(item, state)` substitui só o miolo — o wrapper (card, selected/open, handle,
+checkbox, indent, conectores) é sempre do List.
+
+## Exemplos mínimos
+```tsx
+// standard
+<List items={team} onItemClick={open} getMenuItems={(i) => [{ label: "Editar", onClick }]} />
+
+// grouped + DnD (consumer commita no onMove)
+<List layout="grouped" items={tasks} groups={groups} enableDnD
+      onMove={(id, from, to, toIndex) => commit(id, to, toIndex)} />
+
+// hierarchical (children aninhados)
+<List layout="hierarchical" items={org} defaultExpandedIds={new Set(["acme"])} />
+```
+
+## Props essenciais
+| Prop | Nota |
+|---|---|
+| `layout` | `standard` (default) · `grouped` · `hierarchical` |
+| `items` | `ListItemData[]`; na hierarquia, aninhe via `children` |
+| `groups` | `ListGroup[]` (layout grouped) |
+| `renderItem` | override do miolo do card |
+| `getMenuItems` | kebab `⋯` por item |
+| `selectable` + `selectedIds`/`defaultSelectedIds`/`onSelectionChange` | seleção (controlado/não-controlado) |
+| `expandedIds`/`defaultExpandedIds`/`onExpandedChange` | colapso de grupos/hierarquia |
+| `enableDnD` + `onReorder`(standard)/`onMove`(grouped) | drag-and-drop |
+| `showConnectors` / `indentSize` | conectores / indent px (hierárquico) |
+| `branchHighlight` | destaque de família (hierárquico): `none` (conectores, default) · `block` (painéis aninhados = 1 bloco por família) · `active` (só o ramo do último nó aberto recebe o painel + trilha) |
+| `loading`/`skeletonCount` · `emptyState` · `density` | estados / densidade |
+
+## Gotchas
+- **DnD via `@hello-pangea/dnd`** (física natural de lista — displacement suave +
+  placeholder que abre espaço). Burro: o List emite `onMove(id, from, to, toIndex)`
+  (grouped) / `onReorder(id, toIndex)` (standard) e **o consumer commita** o estado.
+  `toIndex` é o `destination.index` do hello-pangea (índice final no grupo destino).
+- `groupSurface` envolve cada grupo num painel sutil ("card fino") pra diferenciar da
+  superfície. Realce da área de destino (`isDraggingOver`) e elevação do card em
+  arrasto (`isDragging`) são automáticos.
+- **Grupos abrem por padrão**; hierarquia **colapsa** por padrão (semeie `defaultExpandedIds`).
+- Hierarquia: a fonte canônica é a **árvore aninhada** (`children`), não `parentId`.
+  Hierárquico **não** tem DnD no v1.
+- `meta` (colunas) é escondido em telas estreitas (`hidden md:flex`) — use `trailing`/
+  `subtitle` para info crítica em mobile.
+- Dep extra: `@hello-pangea/dnd` (List); o Kanban usa `@dnd-kit` — DnD libs distintas
+  por componente, por design (lista vertical favorece o hello-pangea).

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

@@ -0,0 +1,59 @@
+# MarkdownText
+
+**Categoria:** composto (ui/) — renderização de texto · Chat/Atendimento
+
+Renderiza markdown estilo WhatsApp já **sanitizado**. Faz parse manual do texto
+para React nodes (sem `dangerouslySetInnerHTML`), então qualquer HTML/markdown
+não suportado vira texto literal — seguro contra injeção por design. Porta do
+legado `ui-igreen-hub/src/components/MarkdownWrapper`.
+
+## Quando usar
+
+- Corpo de bolha de mensagem no chat (negrito/itálico/tachado/mono/links).
+- Prévia de última mensagem na lista de tickets (`inline` + `line-clamp-*` do consumer).
+- Qualquer texto vindo do WhatsApp que use a sintaxe `*_~` `` ` ``.
+
+## Sintaxe suportada
+
+| Markdown | Resultado |
+|----------|-----------|
+| `*bold*` | **negrito** (`font-semibold`) |
+| `_italic_` | _itálico_ |
+| `~strike~` | ~~tachado~~ |
+| `` `mono` `` ou ```` ```mono``` ```` | monoespaçado com fundo sutil (`bg-bg-muted`) |
+| `http(s)://…` ou `www.…` | link em nova aba (`target=_blank rel=noopener noreferrer`) |
+
+## Props
+
+| Prop | Tipo | Default | Descrição |
+|------|------|---------|-----------|
+| `children` | `string` | — (obrigatório) | Texto-fonte em markdown WhatsApp. |
+| `inline` | `boolean` | `false` | `true` → `<span>` e colapsa quebras de linha (prévia truncável). `false` → `<p>` preservando quebras (`whitespace-pre-wrap`). |
+| `className` | `string` | — | Classe extra no elemento raiz. |
+
+## Exemplo mínimo
+
+```tsx
+import { MarkdownText } from "@/components/ui/MarkdownText";
+
+// Bolha de mensagem (multilinha, preserva quebras)
+<MarkdownText>{"Olá *João*, segue o _link_: https://igreen.com.br"}</MarkdownText>
+
+// Prévia de última mensagem (truncável)
+<MarkdownText inline className="line-clamp-1">
+  {lastMessage.body}
+</MarkdownText>
+```
+
+## Gotchas
+
+- **Sem `dangerouslySetInnerHTML`** — tags HTML digitadas pelo usuário aparecem
+  como texto literal (intencional, sanitização).
+- `inline` colapsa **todas** as quebras/espaços redundantes num único espaço;
+  o truncamento (`line-clamp-1/2`) é responsabilidade do consumer.
+- Code spans são **opacos**: o conteúdo entre crases não recebe bold/italic/link.
+- `text-body-sm` é fixo (sem token novo). Para outro tamanho, sobreponha via
+  `className` no consumer.
+- Não é interativo além dos links (que herdam o foco padrão do `<a>`); não há
+  variante de cor/foco própria.
+```