@snksergio/design-system 0.60.0 → 0.62.0

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

@@ -0,0 +1,99 @@
+# CardCheckbox
+
+**Categoria:** Form input (opção destacada).
+**Status:** Disponível v0.7.0+.
+
+## O que é
+
+Checkbox apresentado como card clicável grande, com label + description
+visíveis. Mesma estética dos radio cards do design system (bg verde fraco no
+selected, border-brand, shadow leve).
+
+Diferente do `FormFieldCheckbox` que é layout horizontal compact (ideal pra
+um aceite "li os termos") — `CardCheckbox` é pra opções que merecem destaque
+visual ("salvar essa conta", "marcar como favorito", "ativar notificações").
+
+## Quando usar
+
+- Opção dentro de form que precisa de visibilidade extra (com explicação)
+- Toggle de feature opcional após uma ação principal (ex: "salvar essa conta
+  pra usar depois")
+- Item de lista de opções binárias onde cada item tem título + descrição
+- Quando você quer área-clique grande (acessibilidade) sem inflar visualmente
+  um checkbox simples
+
+## Quando NÃO usar
+
+- Lista de aceite legal (terms & conditions) → use `FormFieldCheckbox`
+- Múltiplos checkboxes em sequência (form denso) → use `FormFieldCheckbox` com
+  `gap-form-gap`
+- Toggle ON/OFF de uma config (sem descrição longa) → use `Switch`
+
+## Props essenciais
+
+| Prop              | Tipo                    | Default | Descrição                                    |
+|-------------------|-------------------------|---------|----------------------------------------------|
+| `label`           | `ReactNode`             | —       | Título do card (obrigatório)                 |
+| `description`    | `ReactNode`             | —       | Texto secundário abaixo do label             |
+| `icon`            | `ReactNode`             | —       | Ícone opcional à esquerda (antes do checkbox)|
+| `checked`         | `boolean \| "indeterminate"` | — | Estado controlado                         |
+| `onCheckedChange` | `(checked) => void`     | —       | Callback de mudança                          |
+| `disabled`        | `boolean`               | `false` | Desativa o card inteiro                      |
+| `className`       | `string`                | —       | Override de classe no card root              |
+
+Aceita também as demais props do `CheckboxPrimitive.Root` do Radix
+(`name`, `required`, etc), **exceto `id`** (gerado automaticamente via
+`useId()` pra vincular o `<label>` ao checkbox) e `className`, que é
+aplicado ao card root (`<label>`), não ao checkbox Radix.
+
+## Exemplo mínimo
+
+```tsx
+import { useState } from "react";
+import { CardCheckbox } from "@/components/ui/CardCheckbox";
+
+function MyForm() {
+  const [save, setSave] = useState(true);
+  return (
+    <CardCheckbox
+      label="Salvar essa conta pra usar depois"
+      description="A conta aparecerá nas próximas vezes em 'Contas cadastradas'."
+      checked={save}
+      onCheckedChange={(v) => setSave(v === true)}
+    />
+  );
+}
+```
+
+## Variants (via card-checkbox.styles.ts)
+
+| Variant   | Valores                  | Efeito                                            |
+|-----------|--------------------------|---------------------------------------------------|
+| `selected` | `true` \| `false`       | Selected: bg-success-muted + border-brand + shadow|
+| `disabled` | `true`                   | Opacity 50% + pointer-events none                 |
+
+`selected` é derivado de `checked` automaticamente — não precisa passar.
+
+## Gotchas
+
+- **Não usar dentro de `<form>` sem prevenir submit** — clicar no card
+  dispara o checkbox via label htmlFor. Se houver `<button type="submit">`
+  no mesmo form, o teclado Enter no card pode submeter. Use
+  `<button type="button">` em outros controles próximos.
+- **`onCheckedChange` recebe `boolean | "indeterminate"`** — não pode passar
+  direto pra `setState<boolean>`. Use `(v) => setX(v === true)`.
+- **icon prop** é renderizado dentro de um `<span aria-hidden>` — não use
+  ícone como controle clicável, só como dica visual.
+
+## Tokens usados
+
+- `bg-bg-success-muted` (selected bg)
+- `border-border-brand` (selected border)
+- `bg-bg-muted` (hover bg, não-selected)
+- `text-fg-default` (label)
+- `text-fg-muted` (description)
+- `shadow-sh-sm` (selected shadow)
+- `rounded-radius-lg`
+- `p-pad-xl`
+- `gap-gp-lg` (entre checkbox/icon/body)
+- `ring-ring-brand` (focus)

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

@@ -0,0 +1,133 @@
+# CardOption
+
+<!-- ds:regras
+- switch = efeito IMEDIATO, sem Salvar, e só em `layout="list"`; tela com botão Salvar → `type="checkbox"`
+- opções que se COMPARAM (plano, tier, preço, descrição longa) → cards espaçados; itens do mesmo tipo com rótulo curto (settings, permissões, pagamento, endereço) → `layout="list"`
+- mais de ~5 opções → não é CardOption: `Select`/`Combobox`. E on/off de UMA coisa nunca são 2 radios
+- `type="radio"` EXIGE `<CardOptionGroup type="radio">` em volta; checkbox e switch funcionam soltos
+- em lista o selecionado NÃO pinta por default (a borda ali é a divisória) — queira pintado? `highlightSelected` no grupo
+- omita `orientation`, `highlightSelected` e `size`: derivam do type · `md` é o calibrado
+-->
+
+**O que é** — controle de formulário apresentado como **card clicável** (área grande, label +
+descrição visíveis), com o controle trocável por prop: `checkbox`, `radio` ou `switch`.
+**Categoria**: Form Controls.
+
+**Quando usar** — opção destacada que merece área de clique grande e texto de apoio: escolha
+de plano/frete, lista de permissões, painel de configurações. Para campo compacto em
+formulário, use `FormFieldCheckbox` / `RadioGroup` cru. Para um único toggle inline, `Switch`
+direto. **Acima de ~5 opções, não use CardOption**: vira parede de cards — é `Select` ou
+`Combobox` ([Soul DS](https://soul.emplifi.io/latest/components/in-progress/radio-button-card-Pnx3WsEU)).
+
+## Escolhendo: duas perguntas
+
+### 1. Qual `type`? — depende da DECISÃO, não da aparência
+
+| Use | Quando | Fonte |
+|---|---|---|
+| `switch` | liga/desliga uma funcionalidade **com efeito imediato**, sem Salvar | [NN/g](https://www.nngroup.com/articles/toggle-switch-guidelines/) |
+| `radio` | uma entre várias mutuamente exclusivas, e o usuário precisa **ver todas** pra decidir | [NN/g](https://www.nngroup.com/articles/checkboxes-vs-radio-buttons/) |
+| `checkbox` | combinação livre (zero, uma ou várias) — **e** o substituto do switch quando há Salvar | idem |
+
+Os dois erros que essa tabela evita, os dois de fonte externa:
+
+- **Switch em tela com botão Salvar.** O switch promete efeito imediato — "should take
+  immediate effect and should not require the user to click Save or Submit" (NN/g). Num form
+  com submit, o usuário não sabe se já valeu. Ali o controle é `type="checkbox"`.
+- **Dois radios pra on/off de uma coisa.** Um par "Ativado / Desativado" é um switch (se
+  imediato) ou **um** checkbox (se tem submit) — nunca dois radios.
+
+### 2. Lista ou cards espaçados? — depende de quanta COMPARAÇÃO a decisão pede
+
+| Use | Quando |
+|---|---|
+| `layout="list"` | itens **do mesmo tipo**, rótulo curto, decisão já conhecida: configurações (switch), permissões (checkbox), meio de pagamento / endereço / forma de entrega (radio). Densidade > destaque |
+| `spaced` (default) | cada opção precisa ser **comparada** — preço, descrição longa, ícone, badge: plano, tier, onboarding. O gap é o que separa as unidades de comparação |
+
+**Switch vive em lista, não em card solto.** É literal na Apple HIG: *"Use the switch toggle
+style only in a list row"* — e a razão é que o switch tem mais peso visual que um checkbox, o
+que só se justifica quando a linha inteira lhe dá contexto
+([HIG](https://developers.apple.com/design/human-interface-guidelines/components/selection-and-input/toggles/)).
+
+Meio de pagamento é o caso clássico de **radio em lista**: alvo grande e indicador visível
+resolvem o problema do radio nativo, e o logo/ícone entra à esquerda, junto do nome
+([Baymard](https://baymard.com/blog/payment-method-selection)) — o que o `icon` do CardOption
+já faz por construção.
+
+## Props essenciais
+
+| Prop | Tipo | Default | Descrição |
+|------|------|---------|-----------|
+| `type` | `"checkbox" \| "radio" \| "switch"` | herda do grupo, ou `"checkbox"` | qual controle o card embrulha |
+| `value` | `string` | — | **obrigatório com `type="radio"`** |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | 8 / 12 / 16px de padding |
+| `orientation` | `"left" \| "right"` | **derivado do `type`** | lado do controle |
+| `highlightSelected` | `boolean` | do `type`; **em lista: `false`** | fundo + cor de borda no selecionado |
+| `label` | `ReactNode` | — | obrigatório |
+| `description` | `ReactNode` | — | texto de apoio |
+| `icon` | `ReactNode` | — | **sempre à esquerda**, mesmo com `orientation="right"`. Piso de 20×20px |
+| `checked` / `onCheckedChange` | | — | controlado (no radio, quem manda é o grupo) |
+| `disabled` | `boolean` | — | |
+
+### `CardOptionGroup`
+
+| Prop | Tipo | Default | Descrição |
+|------|------|---------|-----------|
+| `type` | igual ao item | `"checkbox"` | `"radio"` faz o grupo **ser** o `RadioGroup` do Radix |
+| `layout` | `"spaced" \| "list"` | `"spaced"` | `list` = contorno no grupo + divisória entre linhas, sem gap. Vale pros **3 tipos** |
+| `highlightSelected` | `boolean` | — | liga/desliga o destaque em todos os filhos de uma vez |
+| `size` / `orientation` | | | aplicados a todos os filhos |
+| `value` / `defaultValue` / `onValueChange` / `name` | | — | só `type="radio"` |
+
+## Exemplo mínimo
+
+```tsx
+// checkbox solto
+<CardOption
+  label="Salvar essa conta pra usar depois"
+  description="Aparece na lista de contas favoritas"
+  checked={salvar}
+  onCheckedChange={setSalvar}
+/>
+
+// radio — o grupo é obrigatório
+<CardOptionGroup type="radio" value={frete} onValueChange={setFrete}>
+  <CardOption value="standard" label="Standard" description="4 a 10 dias úteis" />
+  <CardOption value="express" label="Express" description="2 a 3 dias úteis" />
+</CardOptionGroup>
+
+// lista de settings — switch, à direita, sem destaque de selecionado
+<CardOptionGroup type="switch" layout="list">
+  <CardOption label="Wi-Fi" description="Conectar a redes sem fio" checked={wifi} onCheckedChange={setWifi} />
+  <CardOption label="Bluetooth" description="Permitir conexões Bluetooth" checked={bt} onCheckedChange={setBt} />
+</CardOptionGroup>
+```
+
+## Gotchas / cuidados
+
+- **`type="radio"` sem `CardOptionGroup` não funciona direito.** É o `RadioGroup` do Radix que
+  dá navegação por seta e agrupamento por `name`. Checkbox e switch são autônomos.
+- **Não passe `orientation` nem `highlightSelected` sem motivo.** Eles derivam do `type`, e o
+  default é a convenção: switch fica **à direita** (linha de configuração) e **sem destaque de
+  selecionado**, porque switch é *estado*, não seleção — uma lista de settings toda pintada de
+  verde é ruído. Foi por isso que o exemplo antigo do Card Toggle não tinha estado visual.
+- **`layout="list"` não é exclusivo do switch.** Com radio vira seletor de linha única; com
+  checkbox, lista de permissões. No modo lista o contorno é do grupo e a divisória é a borda
+  de baixo de cada item (a última suprimida) — não force borda no item.
+- **Em lista, o destaque de selecionado vem desligado — inclusive em checkbox e radio.** É
+  consequência de onde a borda mora: em lista a única borda do item é a de baixo, ou seja a
+  **divisória**, então o `border-brand` não contorna o selecionado — pinta a linha que o separa
+  do vizinho — e o fundo vira faixa colorida no meio da lista (medido em 2026-08-27, antes do
+  ajuste: linha verde com divisória verde). Quem quer o pintado liga `highlightSelected` no
+  grupo ou no item; a prop vence nas duas direções, e em lista a sombra do destaque sai (dentro
+  do `overflow-hidden` do grupo ela não eleva, só vaza).
+- **O ícone fica sempre à esquerda**, inclusive com `orientation="right"`: o `order-last` move
+  só o controle. Ele identifica a opção e pertence ao lado do texto. Piso de 20×20px.
+- **É um `<label htmlFor>` nativo, nunca `<button>` (L-025).** Não embrulhe em outro botão nem
+  ponha `onClick` no card: o clique já chega ao controle real pelo label, e trocar isso quebra
+  o leitor de tela ("button" em vez de checkbox) e o submit nativo.
+- **O anel de foco é do CARD**, via `has-[:focus-visible]`. O `CardCheckbox` antigo declarava
+  `focus-visible:ring-4` no próprio `<label>` — inerte, porque label não recebe foco (medido
+  em 2026-08-27: o único anel visível era o do controle de 16px).
+- **`CardCheckbox` continua existindo** como atalho de `type="checkbox"`. Componente novo
+  deve usar `CardOption`.

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

@@ -0,0 +1,93 @@
+# Chart — USAGE
+
+Wrapper sobre o **Recharts 3** que aplica a paleta do DS (tokens `--color-chart-1..5`) e fornece Tooltip/Legend já estilizados com os tokens iGreen. Categoria: data-display.
+
+## Quando usar
+
+- Qualquer gráfico (área, barras, linhas, pizza, radar, radial) numa tela do iGreen
+- Garantir cores, tooltip e legenda consistentes entre gráficos
+
+## Import
+
+```tsx
+import {
+  ChartContainer,
+  ChartTooltip,
+  ChartTooltipContent,
+  ChartLegend,
+  ChartLegendContent,
+  type ChartConfig,
+} from "@/components/ui/Chart";
+import { Area, AreaChart, CartesianGrid, XAxis } from "recharts";
+```
+
+## Conceito
+
+`ChartContainer` recebe um `config` (mapa série → label/cor/ícone) e injeta cada
+cor como CSS var `--color-{key}` **escopada nessa instância**. Os elementos do
+Recharts referenciam `var(--color-{key})`.
+
+```tsx
+const config = {
+  desktop: { label: "Desktop", color: "var(--color-chart-1)" },
+  mobile:  { label: "Mobile",  color: "var(--color-chart-2)" },
+} satisfies ChartConfig;
+
+<ChartContainer config={config} className="h-[260px] w-full">
+  <AreaChart data={data}>
+    <CartesianGrid vertical={false} />
+    <XAxis dataKey="month" tickLine={false} axisLine={false} />
+    <ChartTooltip content={<ChartTooltipContent />} />
+    <Area dataKey="desktop" fill="var(--color-desktop)" stroke="var(--color-desktop)" />
+    <Area dataKey="mobile"  fill="var(--color-mobile)"  stroke="var(--color-mobile)" />
+  </AreaChart>
+</ChartContainer>
+```
+
+## Props essenciais
+
+| Componente | Prop | Função |
+|---|---|---|
+| `ChartContainer` | `config: ChartConfig` | mapa série → `{ label, color?, icon?, theme? }` |
+| `ChartContainer` | `className` | controle de altura/aspect (ex: `h-[260px] w-full`) |
+| `ChartTooltip` | `content={<ChartTooltipContent/>}` | tooltip do DS |
+| `ChartTooltipContent` | `hideLabel`, `hideIndicator`, `indicator` (`dot`/`line`/`dashed`), `labelFormatter`, `formatter`, `nameKey`, `labelKey` | customização |
+| `ChartLegend` | `content={<ChartLegendContent/>}` | legenda do DS |
+
+## Cores
+
+Use os tokens `var(--color-chart-1)` … `var(--color-chart-5)` no `config`.
+Paleta verde-marca + harmônicas (teal/azul/âmbar/violeta), light/dark-aware.
+
+## Grid (linhas-guia)
+
+`<CartesianGrid vertical={false} strokeDasharray="4 4" />` — **sem** passar
+`stroke`. O container já reescreve o stroke default pro token `--color-chart-grid`
+(visível em light e dark). Mesmo vale pro `PolarGrid` (radar/radial).
+
+## Gotchas
+
+- `ChartContainer` já embute o `ResponsiveContainer` — passe só o gráfico (ex:
+  `<AreaChart>`) como filho, **sem** envolver em outro ResponsiveContainer.
+- Defina **altura** via `className` (ex: `h-[260px]`) — o aspect default é `video`.
+- Recharts 3: `dataKey` precisa casar com a chave do `config` pra `--color-{key}`
+  resolver.
+
+### Recharts 3 — caveats que quebram silenciosamente
+
+- **`text-display-sm` / `text-display-xs` NÃO existem** como utility (renderizam
+  14px). Em KPIs use `text-heading-sm` (24–32px) / `text-heading-xs` (24px) ou
+  `text-display-md` (28–39px).
+- **Pizza**: não há `activeIndex`/`activeShape` no `Pie` — usar a prop
+  `shape={(props, index) => <Sector .../>}` (render por setor).
+- **Radial empilhado**: precisa de `<PolarAngleAxis type="number" domain={[0,total]} />`
+  senão só 1 segmento aparece.
+- **Eixo Y omite ticks de borda** (ex: o `0`): `interval={0}` força todos.
+- **Linha-guia duplicada no topo**: o `domain` máximo deve ser igual ao maior
+  `tick` (ex: `domain={[0,90]}` com tick 90, não `[0,95]`).
+
+## Composições de dashboard
+
+Catálogo + padrões de header/card/categoria/largura na rota `#/chart-showcase` do
+catálogo hospedado. (Fonte no repo do DS: `.ai/context/components/chart-patterns.md`
+— caminho **interno**, não existe em quem consome por npm ou copy-in.)

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

@@ -0,0 +1,68 @@
+# Chip — USAGE
+
+Pílula compacta para status, tags, filtros — dual-mode (span estático ou button interativo).
+
+## Quando usar
+- Tags / categorias (status, prioridade, label)
+- Filtros aplicados (com onClick = remove)
+- Chips de seleção (selected state)
+- Counters inline
+
+## Import
+```tsx
+import { Chip, ChipGroup, ChipGroupItem } from "@/components/ui/Chip";
+```
+
+## Variants
+| Variant | Valores | Default | Quando |
+|---|---|---|---|
+| `color` | primary / neutral / danger / warning / success / info | neutral | Cor semântica |
+| `variant` | solid / outline / soft / soft-outline | soft | Intensidade visual |
+| `size` | sm / md / lg / xl | md | sm=24px, md=28px, lg=32px, xl=36px |
+| `shape` | pill / rounded | pill | Border-radius |
+
+## Props essenciais
+| Prop | Tipo | Função |
+|---|---|---|
+| `onClick` | () => void | Vira `<button>` automaticamente |
+| `asButton` | boolean | Força modo button mesmo sem onClick |
+| `selected` | boolean | Visual ativo (force soft) |
+
+## ChipGroup props
+Seleção via `@radix-ui/react-toggle-group`. Visual ativo/inativo configurável independentemente.
+
+| Prop | Tipo | Default | Função |
+|---|---|---|---|
+| `type` | `"single"` \| `"multiple"` | — (obrigatória) | single = radio-like, multiple = checkbox-like |
+| `value` | string (single) / string[] (multiple) | — | Seleção controlada |
+| `defaultValue` | string (single) / string[] (multiple) | — | Seleção inicial (uncontrolled) |
+| `onValueChange` | (value: string) => void (single) / (value: string[]) => void (multiple) | — | Callback de mudança |
+| `inactiveColor` | mesmos valores de `color` | `"neutral"` | Cor dos items NÃO selecionados |
+| `inactiveVariant` | mesmos valores de `variant` | `"outline"` | Variant dos items NÃO selecionados |
+| `activeColor` | mesmos valores de `color` | `"primary"` | Cor dos items selecionados |
+| `activeVariant` | mesmos valores de `variant` | `"soft-outline"` | Variant dos items selecionados |
+| `size` | sm / md / lg / xl | `"md"` | Size aplicado em todos os chips do grupo |
+| `shape` | pill / rounded | `"pill"` | Shape aplicado em todos os chips |
+| `orientation` | `"horizontal"` \| `"vertical"` | `"horizontal"` | Direção do grupo |
+| `ariaLabel` | string | — | Aria-label do grupo |
+
+## Exemplo mínimo
+```tsx
+// Tag estática
+<Chip color="warning" variant="soft">Royal</Chip>
+
+// Filtro com remove
+<Chip color="primary" onClick={removeFilter}>Status: Ativo ×</Chip>
+
+// Group multi-select
+<ChipGroup type="multiple" value={selected} onValueChange={setSelected}>
+  <ChipGroupItem value="all">Todas</ChipGroupItem>
+  <ChipGroupItem value="unread">Não lidas</ChipGroupItem>
+</ChipGroup>
+```
+
+## Cuidados / Gotchas
+- Sem `onClick` e sem `asButton={true}` renderiza como `<span>` (decorativo)
+- O visual interativo (cursor pointer + focus ring) é calculado internamente a partir de `onClick`/`asButton` — não existe prop `interactive` no Chip
+- `selected=true` força visual "soft" da cor mesmo se `variant="outline"`
+- Pra counter inline, usar `chipCount` slot (10px font-semibold)

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

@@ -0,0 +1,118 @@
+# ChoroplethMap
+
+**Categoria:** iGreen (tv() + d3-geo). Primitiva **genérica** de mapa coroplético (regiões SVG coloridas por valor).
+
+## Quando usar
+
+- Visualizar uma métrica por região geográfica: municípios (IBGE), estados, países.
+- Ex.: "Mapa de Cidades" do Rankings — clientes por município do Brasil.
+
+Não é acoplado a nenhum dataset: você passa a geografia (GeoJSON/TopoJSON) + um mapa `id → número`.
+
+## Props essenciais
+
+| Prop | Tipo | Default | Descrição |
+|------|------|---------|-----------|
+| `geography` | `FeatureCollection \| Feature[] \| Topology` | — | Fonte geográfica. TopoJSON com 2+ objetos exige `topologyObject`. |
+| `topologyObject` | `string` | objeto único da `Topology` | Nome do objeto a extrair do `Topology` (ex.: `"municipios"`). Obrigatório só quando há 2+ objetos — com 2+ e sem a prop, o mapa renderiza **vazio** (sem erro). |
+| `values` | `Record<string \| number, number>` | — | Mapa `id → valor`. Ids casam com `getFeatureId`. |
+| `getFeatureId` | `(f) => string \| number` | `f.id` → `f.properties.id` | Como obter o id de uma feature. |
+| `getFeatureName` | `(f) => string` | `properties.name/nome/NOME` → id | Nome exibido no tooltip. |
+| `colorScale` | `(value, {min,max}) => string` | gradiente token | Escala custom (retorna cor CSS). |
+| `scaleToken` | `"brand"\|"success"\|"info"\|"warning"\|"danger"` | `"brand"` | Token DS do extremo "cheio" do gradiente default. |
+| `domain` | `[number, number]` | min/max de `values` | Domínio fixo da escala. |
+| `projection` | `GeoProjection` (d3-geo) | `geoMercator().fitSize(...)` | Projeção custom (senão auto-fit). |
+| `width` / `height` | `number` | `800` / `600` | ViewBox (o SVG é responsivo, `w-full h-auto`). |
+| `strokeWidth` | `number` | `0.5` | Espessura das divisas (unidades do viewBox). |
+| `showLegend` | `boolean` | `true` | Barra de gradiente + min/max. |
+| `legendTitle` | `ReactNode` | — | Título da legenda. |
+| `formatValue` | `(v) => string` | `Intl.NumberFormat("pt-BR")` | Formata legenda + tooltip. |
+| `renderTooltip` | `(info) => ReactNode` | nome + valor | Conteúdo custom do tooltip. |
+| `onFeatureClick` | `(info) => void` | — | Clique numa região. |
+| `selectedId` | `string \| number \| null` | — | Destaque PERSISTENTE de uma região (controlado; par natural de `onFeatureClick` pra seleção por clique). |
+| `ariaLabel` | `string` | `"Mapa"` | Rótulo acessível (`role="img"`). |
+
+## Exemplo mínimo (municípios do Brasil, IBGE TopoJSON)
+
+```tsx
+import { ChoroplethMap } from "@snksergio/design-system";
+import brasilMunicipios from "./geo/br-municipios.topo.json"; // TopoJSON IBGE
+
+<ChoroplethMap
+  geography={brasilMunicipios}
+  topologyObject="municipios"
+  values={clientesPorMunicipio}         // { "3550308": 120, "3304557": 88, ... }
+  getFeatureId={(f) => f.id ?? f.properties?.codarea}
+  getFeatureName={(f) => f.properties?.name}
+  scaleToken="brand"
+  legendTitle="Clientes por cidade"
+  ariaLabel="Clientes por município"
+/>
+```
+
+## Interação (comportamento embutido — não reimplemente)
+
+- **Hover**: a região sob o cursor é REDESENHADA por cima de todas (contorno
+  `fg-{scaleToken}` com 3× a espessura das divisas + tinta de 18% do token).
+  O contorno acompanha a família de cor do mapa — amarelo forte num mapa
+  `warning`, roxo forte num `info` — nunca verde fixo.
+- **Tooltip**: próprio (NÃO Radix), vive numa camada `pointer-events-none` e
+  SEGUE o cursor, trocando só o conteúdo. Nunca captura o mouse (era a causa
+  de flicker direcional com o Tooltip portalado). Flip automático perto das
+  bordas. Região sem valor mostra "Sem dados".
+- **Seleção** (`selectedId`, controlado): destaque persistente com a mesma
+  técnica do hover, tinta mais forte (32% vs 18%). Toggle é responsabilidade
+  do consumer: `onFeatureClick={(i) => setSel(s => s?.id === i.id ? null : i)}`.
+
+## Receita: UFs do Brasil (malha IBGE em runtime)
+
+```tsx
+const IBGE_UF = "https://servicodados.ibge.gov.br/api/v3/malhas/paises/BR?formato=application/json&qualidade=minima&intrarregiao=UF";
+// devolve TopoJSON { objects: { BRUF } } — objeto único, extraído automaticamente
+// qualidade=minima NÃO traz nome — só properties.codarea. Mapeie código → nome:
+<ChoroplethMap
+  geography={geo}                       // fetch da URL acima
+  topologyObject="BRUF"                 // explícito por clareza (opcional: é único)
+  values={clientesPorUf}                // { "35": 612, "31": 388, ... } (código IBGE)
+  getFeatureId={(f) => String((f.properties as { codarea?: string })?.codarea ?? f.id ?? "")}
+  getFeatureName={(f) => UF_NOMES[id] ?? id}  // tabela código → "São Paulo"...
+/>
+```
+
+## Receita: master-detail (mapa + painel de detalhe)
+
+Espelhe a seção "Seleção por clique" da doc page (`ChoroplethMapDoc.tsx`):
+
+- Wrapper `relative w-full` com o mapa em largura total; painel FLUTUANDO no
+  canto superior direito (área de oceano): `md:absolute md:right-0 md:top-0
+  md:w-[220px] md:shadow-sh-md` + card `rounded-radius-lg border
+  border-border-default bg-bg-surface p-pad-xl`. Mobile: empilha (`mt-gp-2xl`).
+- ⚠️ **Largura do painel SEMPRE fixa** — painel que cresce com o conteúdo
+  redimensiona o svg (que é `w-full` do espaço restante) a cada seleção.
+- Dentro: título + subtítulo num card interno `rounded-radius-md bg-bg-muted
+  px-pad-xl py-pad-lg` (`subtle` sobre `surface` mal aparece; `muted` dá o
+  contraste do header); métricas abaixo, UMA por linha (`flex justify-between`,
+  label `text-caption-md text-fg-muted`, valor `text-body-sm font-semibold
+  tabular-nums`).
+- Cobertura parcial: UF fora de `values` fica neutra (`bg-bg-muted`) — estado
+  "vazio" de graça, sem prop.
+
+## Gotchas
+
+- **Dependências:** usa `d3-geo` (projeção + path) e `topojson-client` (TopoJSON → features) — as MESMAS primitivas que a `react-simple-maps` embrulha. Não usamos `react-simple-maps` porque ela trava peer em React ≤18 (o DS é React 19) — usar `--legacy-peer-deps` seria hack e contaminaria a árvore de todos os consumidores.
+- **Cor data-driven é inline:** o `fill` de cada região é `color-mix(... var(--color-bg-{scaleToken}) ...)` e o contorno de hover/seleção é `var(--color-fg-{scaleToken})` (derivados de tokens, valor vem do dado) — não dá pra virar classe utilitária (valor contínuo/infinito). Mesma exceção justificada do `Avatar.colorHex` (L-027). Todo o resto (shell/legenda/tooltip) é classe token.
+- **Não envolva o tooltip em Radix/portal:** qualquer wrapper portalado captura o mouse e reintroduz o flicker direcional (cursor persegue o tooltip → mouseleave do svg → fecha/reabre em loop).
+- **Ids precisam casar:** as chaves de `values` têm que bater com o retorno de `getFeatureId`. TopoJSON do IBGE costuma trazer o código em `properties.codarea` (malhas v3) ou `feature.id` — confira a fonte e ajuste `getFeatureId`.
+- **Dentro de container flex centrado** (ex.: preview de ExampleSection): dê `w-full` ao wrapper do mapa — sem ele o svg cai na largura intrínseca default (300px).
+- **Performance:** milhares de `<path>` renderizam bem em SVG, mas re-render pesado; passe `values`/`geography` estáveis (memoize no consumer). A geometria (paths) é memoizada por `geography/projection/width/height`.
+
+## Quando NÃO usar
+
+Mapa **fixo** do Brasil por UF (KPI de dashboard) → use a **receita de paths inline**
+(`#/chart-map`, `_dashboard-brazil-map.ts`): é SVG puro, zero dependência e não busca
+malha em runtime.
+
+Este componente existe para o caso **data-driven**: topologia arbitrária (municípios de
+um estado, recortes que mudam), projeção real via `d3-geo` e drill-down por
+`onFeatureClick`. Ele traz `d3-geo` + `topojson-client` junto — não pague esse custo
+para desenhar o Brasil parado.

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

@@ -0,0 +1,70 @@
+# ColorPicker
+
+**Categoria:** composto (Popover + Input + FormField + Button + Separator). Seletor de cor **hex `#RRGGBB`** controlado, pensado para **Tags** e **Filas**.
+
+## Quando usar
+
+- Escolher uma cor de marca/identidade para uma entidade (tag, fila, etiqueta, status custom).
+- Quando o usuário precisa **ver e digitar** o hex E ter atalho para uma **paleta curada**.
+
+Não use para escolha semântica (sucesso/erro/aviso) — isso são tokens DS, não cor livre.
+
+## Anatomia
+
+```
+[ swatch ]  [ Input hex (#RRGGBB) ]      ← trigger inline (swatch abre o popover)
+            ▼ (clique no swatch)
+┌─────────────────────────────┐
+│  grid 10-col de presets      │          ← swatch selecionado = checkmark (contraste auto)
+│  ───────── Separator ─────── │
+│  Cor personalizada  [input]  │          ← allowCustomHex (default true)
+│  [ Aplicar ]                 │
+└─────────────────────────────┘
+```
+
+## Props essenciais
+
+| Prop | Tipo | Default | Descrição |
+|------|------|---------|-----------|
+| `value` | `string` | — | **Obrigatório.** Hex controlado `#RRGGBB`. |
+| `onValueChange` | `(hex: string) => void` | — | **Obrigatório.** Recebe sempre `#RRGGBB` maiúsculo normalizado. |
+| `presets` | `string[]` | `DEFAULT_COLOR_PRESETS` | Cores do grid (paleta iGreen + neutras, ~26 hex). |
+| `id` | `string` | auto | id do input hex (linka label externo via `htmlFor`). |
+| `state` | `"default" \| "error" \| "warning" \| "success"` | `"default"` | Colore **só a borda** do trigger. **Não** é color variant. |
+| `size` | `"xxs" \| "xs" \| "sm" \| "md"` | `"md"` | Mesma escala do `Input`, e repassado a ele: `xxs` 28px · `xs` 32px · `sm` 36px · `md` 40px. |
+| `disabled` | `boolean` | `false` | Desabilita o seletor inteiro. |
+| `allowCustomHex` | `boolean` | `true` | Mostra o input hex livre + botão Aplicar no popover. |
+| `placeholder` | `string` | `"#RRGGBB"` | Placeholder dos inputs hex. |
+| `open` / `onOpenChange` | — | — | Controle externo de abertura do popover. |
+| `className` | `string` | — | className do container (root). |
+
+## Exemplo mínimo
+
+```tsx
+import { ColorPicker } from "@snksergio/design-system";
+
+const [color, setColor] = useState("#16A34A");
+
+<FormField label="Cor da tag" id="tag-color">
+  {({ id }) => (
+    <ColorPicker id={id} value={color} onValueChange={setColor} />
+  )}
+</FormField>
+```
+
+## Variants
+
+| Variant | Valores | Efeito |
+|---------|---------|--------|
+| `size` | `xxs` · `xs` · `sm` · `md` | altura do trigger (swatch + input) — escala do `Input` |
+| `state` | `default` · `error` · `warning` · `success` | cor da borda do swatch |
+| `disabled` | — | último compoundVariant (L-006); desabilita tudo |
+
+## Gotchas
+
+- **Normalização:** aceita `3` ou `6` dígitos com/sem `#` (`fff`, `#FFF`, `00ff00`) → sempre emite `#RRGGBB` **maiúsculo**. Hex inválido no input inline restaura o `value` atual no blur.
+- **bg dinâmico = exceção L-027:** o fundo do swatch e dos presets vem por `style={{ backgroundColor }}` (cor externa). É a única exceção de hardcode permitida; todo o resto é token DS.
+- **Checkmark com contraste auto:** o preset selecionado usa `getContrastTextColor(hex)` para escolher branco/preto — não cor cega.
+- **Anchor do Popover:** o swatch é `forwardRef` via `PopoverTrigger asChild` (L-021). O `ref` encaminhado vai para o botão do swatch.
+- **Foco:** swatch + presets seguem Padrão 1 (botão, `ring-4 ring-ring-brand`); o input hex herda o foco animado do `Input` do DS (Padrão 2).
+- Para parear visualmente com outros campos de um form, envolva em `<FormField>` (render-prop) — o `state` do ColorPicker espelha o do Input para casar a borda.

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

@@ -0,0 +1,51 @@
+# Combobox
+
+**Categoria:** composto (Popover + Command/cmdk). Select de escolha única com **busca (autocomplete)** e **lista rolável**.
+
+## Quando usar
+
+- Lista de opções **longa** onde o usuário precisa **digitar pra achar** (ex.: escolher 1 coluna entre 30, 1 país, 1 cliente).
+- Quando um `Select` simples ficaria alto demais / sem scroll confortável e sem busca.
+
+Para listas curtas (≤ ~8 itens) e sem necessidade de busca, prefira `FormFieldSelect` / `Select`.
+
+## Props essenciais
+
+| Prop | Tipo | Default | Descrição |
+|------|------|---------|-----------|
+| `options` | `ComboboxOption[]` | — | `{ value, label, keywords? }`. Busca casa por `label` + `keywords` (que já inclui `value`). |
+| `value` | `string` | — | Valor selecionado (controlado). |
+| `onValueChange` | `(value: string) => void` | — | Recebe o `value` da opção escolhida. |
+| `placeholder` | `ReactNode` | `"Selecione…"` | Texto do trigger vazio. |
+| `searchPlaceholder` | `string` | `"Buscar…"` | Placeholder do input de busca. |
+| `emptyMessage` | `ReactNode` | `"Nenhum resultado."` | Quando a busca não casa nada. |
+| `open` / `defaultOpen` / `onOpenChange` | — | — | Controle de abertura (igual a um Select). |
+| `align` | `"start" \| "center" \| "end"` | `"start"` | Alinhamento do dropdown. |
+| `className` | `string` | — | Estiliza o **trigger** (aceita os mesmos overrides de um `SelectTrigger`). |
+| `contentClassName` | `string` | — | Estiliza o **dropdown** (PopoverContent). |
+| `disabled` | `boolean` | — | Desabilita o trigger. |
+
+`ComboboxOption = { value: string; label: string; keywords?: string[] }`
+
+## Exemplo mínimo
+
+```tsx
+import { Combobox } from "@snksergio/design-system";
+
+<Combobox
+  options={columns.map((c) => ({ value: c.key, label: c.label }))}
+  value={field}
+  onValueChange={setField}
+  placeholder="Campo"
+  searchPlaceholder="Buscar campo…"
+  emptyMessage="Nenhum campo"
+  aria-label="Campo"
+/>
+```
+
+## Gotchas
+
+- O trigger é um `<button role="combobox">` e espelha o `SelectTrigger` (mesma altura/borda/foco). Para parear com Selects irmãos num form, passe o mesmo `className` que você passaria ao `SelectTrigger`.
+- A seleção **não** depende do argumento do `onSelect` do cmdk (que vem normalizado/lowercased) — o componente fecha via closure sobre `option.value`. Por isso `value`s com maiúsculas/acentos/espaços funcionam.
+- O dropdown nasce com a **largura do trigger** (`--radix-popover-trigger-width`). Para largura própria, use `contentClassName="w-[...]"`.
+- `label`s devem ser únicos (o cmdk indexa por `value`/label do item). Se houver rótulos repetidos, diferencie via `keywords`.