@snksergio/design-system 0.62.0 → 0.63.0

package/dist-lib/ai/roteiros/crud-builder/blueprint.md

@@ -0,0 +1,63 @@
+> **Nota de portabilidade.** Este roteiro foi extraído do pipeline do iGreen DS
+> para Claude Code. Menções a slash command (`/ds-create-…`), a `.claude/` e a
+> ferramentas daquele ambiente descrevem **como ele é acionado lá** — aqui o
+> equivalente é carregar este roteiro pelo `indice.json`. O conteúdo de decisão
+> (entrevista, blueprint, regras de composição) vale igual.
+
+> **Modo submódulo (`ds-link`).** Existe `.claude/ds-config.json` com `"mode": "submodule"`?
+> Então **NÃO rode `igreen:add`** — esse script não existe no seu projeto. Os componentes e
+> exemplos já estão no disco em `<dsPath>/src`: importe pelo `importBase` do config
+> (compostos) e pelo `primitivesBase` (primitivos shadcn), e **leia** o exemplo direto de
+> `<dsPath>/src/examples/`.
+
+# CRUD Builder — Blueprint [GATE]
+
+Consolide a entrevista num preview ÚNICO e **pare** pra aprovação. Nenhuma edição
+em disco antes do "aprovar".
+
+## Apresente ao usuário
+
+```
+Entidade:        <Nome>   (tipo <NomeRow>)
+Modo:            client | server (endpoint: ...)
+Onde:            <PAGES_DIR>/<Arquivo>.tsx  · registro: <REGISTRO>
+Wrapper:         AppShell + PageHeader | puro   (chrome do print entregue? sim/não)
+Colunas:         <campo:tipo[:sortable][:editável]>, ... (primária: <campo>)
+Busca/Filtros:   busca=<sim/não> · filtros=<col:tipo, ...>
+Ações linha:     <editar, excluir(confirm AlertModal), ...>   · seleção/bulk: <...>
+Export:          <não | escopo tudo/filtrado/selecionado · csv>
+Views:           presets=<nome → filtro>, ...   · do usuário=<sim/não · savedViewsService+persistId>
+Paginação/virt:  <pageSize / virtualize>   · totalizadores: <colunas>
+Drawers:         criar/editar=<sim/não> · campos=<campo:obrigatório?:máscara?> · detalhe=<sim/não>
+Estados:         loading=<skeleton> · vazio=<msg + CTA> · sem-resultado=<msg + limpar>
+Kanban:          <não | campo de agrupamento>
+Componentes a puxar: data-table[, example-finance p/ drawers][, alert-modal p/ excluir][, ...]
+```
+
+## ⚠️ Decisões inferidas — vete se discordar
+
+Depois do bloco acima, liste **só** o que o usuário não disse e você decidiu sozinho —
+uma linha cada, com o que muda se ele vetar. Sem inferência → `nenhuma`; não apague a
+seção: é a ausência dela que faz a decisão passar aprovada em pacote.
+
+```
+⚠️ Inferido (não perguntei):
+  • wrapper = puro       → a tela nasce SEM rail/menu/header
+  • tema = light         → a referência mostrava dark
+  • <coluna> = <tipo>    → confiança baixa (inferido só pelo nome do campo)
+```
+
+## Pré-validações (rode ANTES de pedir aprovação)
+- Todo filtro tem operador compatível com o filterType (multiSelect⇒isAnyOf, text⇒contains, date⇒between, number⇒gte/lte/between, boolean⇒equals).
+- `virtualize` ⇒ paginação off + container com altura. `groupBy`/kanban ⇒ paginação off.
+- Kanban: cada lane mapeia uma option do campo de agrupamento.
+- Coluna `actions` se há ações por linha; cada action tem `id` único.
+- **Ação `destructive` (excluir) ⇒ tem `AlertModal` de confirmação no plano.**
+- **Os 3 estados (loading/vazio/sem-resultado) estão definidos** (mesmo que com default).
+- Nome/rota da página sem colisão.
+
+Liste qualquer ajuste necessário. Só depois pergunte: **"Aprovar e gerar?"**
+
+- `aprovar` → carregue `generate.md`.
+- pedir mudança → ajuste o blueprint e reapresente.
+- `cancelar` → encerre (zero edições).

package/dist-lib/ai/roteiros/crud-builder/entrevista.md

@@ -0,0 +1,139 @@
+> **Nota de portabilidade.** Este roteiro foi extraído do pipeline do iGreen DS
+> para Claude Code. Menções a slash command (`/ds-create-…`), a `.claude/` e a
+> ferramentas daquele ambiente descrevem **como ele é acionado lá** — aqui o
+> equivalente é carregar este roteiro pelo `indice.json`. O conteúdo de decisão
+> (entrevista, blueprint, regras de composição) vale igual.
+
+> **Modo submódulo (`ds-link`).** Existe `.claude/ds-config.json` com `"mode": "submodule"`?
+> Então **NÃO rode `igreen:add`** — esse script não existe no seu projeto. Os componentes e
+> exemplos já estão no disco em `<dsPath>/src`: importe pelo `importBase` do config
+> (compostos) e pelo `primitivesBase` (primitivos shadcn), e **leia** o exemplo direto de
+> `<dsPath>/src/examples/`.
+
+# CRUD Builder — Entrevista
+
+Pergunte em fases, **uma pergunta de cada vez quando possível**, acumulando as
+escolhas. NÃO edite arquivo nenhum aqui. Ao fim, vá pro `blueprint.md`.
+
+## ⛔ Perguntas obrigatórias (NUNCA pular, mesmo que dê pra inferir)
+
+A IA tende a inferir tudo e ir direto pro blueprint — **não faça isso**. Estas duas
+são sempre explícitas:
+
+1. **Colunas** — mesmo que dê pra inferir do nome da entidade, **LISTE** as colunas
+   inferidas (campo · rótulo · tipo) e **confirme** (adicionar/remover/reordenar) +
+   pergunte se **alguma tem particularidade** (ordenável, editável inline, alinhamento,
+   fixar/pin, largura, filtro, totalizador). Nunca gere com colunas só inferidas.
+2. **Views salvas** — **sempre OFEREÇA e explique** (não trate como "off" silencioso):
+
+   > "Quer **views salvas**? São abas com filtros + ordenação + colunas/densidade
+   > pré-configurados (ex.: _Ativos_, _Alto valor_, _Atrasados_). O usuário troca de
+   > recorte num clique — sem precisar de uma tela nova pra cada um."
+
+   Pergunte quais (nome + filtro + sort). Default = nenhuma, **mas só depois de perguntar**.
+
+## Fase 0 — Entidade & origem dos dados
+
+- Qual entidade? (ex.: Clientes, Pedidos, Faturas) → vira o nome da tela/tipo.
+- Dados **client-side** (array em memória/mock) ou **server-side** (fetch paginado da API)?
+  - Server: qual o endpoint/forma de buscar? (vira `fetchData` em `useCallback`).
+- Onde a página vai morar e como registra a rota? (`PAGES_DIR`/`REGISTRO`).
+
+## Fase 1 — Página e shell
+
+| Pergunta | Default |
+| --- | --- |
+| Título da página | plural da entidade |
+| Descrição (1-2 frases) | gerada do domínio, confirmar |
+| **Wrapper** | ver abaixo |
+| Onde mora + como registra a rota | `PAGES_DIR` / `REGISTRO` do seu projeto |
+
+**Antes de perguntar o wrapper, VERIFIQUE** — as duas respostas costumam decidir sozinhas:
+
+1. existe `AppShell` no projeto? (grep em `src/`)
+2. a referência que o usuário deu — print, Figma, tela existente — mostra rail/menu/header?
+
+- **`AppShell` + `PageHeader`** → chrome na referência **e** shell disponível. Sem perguntar.
+- **componente puro** (no seu `PAGES_DIR`) → sem referência visual, ou app sem shell e sem
+  chrome na referência.
+- **chrome na referência e SEM shell no projeto** → **pare e ofereça `/ds-create-app` junto**.
+  Se o usuário recusar, o blueprint diz em **linha destacada** o que do print não vai ser
+  entregue.
+
+> Print de app inteiro + pedido de "uma tela" é **`shell + tela`**, não `tela`. Foi este
+> recorte que fez uma tela nascer sem o menu que o print mostrava. A regra de o que é da
+> referência e o que é do DS está em `_claude/rules/ds-design.md`.
+
+---
+
+## Fase 2 — Colunas
+
+Pra cada coluna: campo, rótulo, **tipo** (text, number, currency, percentage, date,
+datetime, email, phone, url, status/badge, boolean, user, tags, actions), e se é
+sortable / editável (inline). Pergunte quais colunas o usuário quer e em que ordem.
+Marque a coluna "primária" (a que abre detalhe / leva avatar).
+
+**`copyable` é inferido, não perguntado** — marque nas colunas cujo valor a pessoa
+**cola em outro lugar** (documento, e-mail, telefone, conta/chave PIX, protocolo/NF/
+rastreio, token, ID externo) e **só** nelas; nome, status, data, valor e quantidade
+ficam de fora. Não abra pergunta própria pra isso: **declare** as colunas marcadas
+quando apresentar a lista de colunas, junto do tipo e do filtro, pra o usuário tirar
+em lote ("CNPJ sem copyable"). Critério completo e limites: `generate.md` item 4.
+
+## Fase 3 — Busca, filtros & ações
+
+> ⛔ **Anti-pattern — NUNCA gerar form/selects soltos ACIMA da tabela.** Intenção de
+> "adicionar filtro" (select de status em cima, campo de período, "filtrar por X") →
+> **sugira o padrão certo** (a tabela já filtra reativo, com chips clicáveis/editáveis):
+>
+> - **Filtro por COLUNA** (status/categoria/tipo/data…) → `enableColumnFilter` +
+>   `filterType`. Quer abrir já filtrado? **pré-aplique** (`defaultViews`/`presetView`
+>   ou `filterModel`) → abre com o **chip aplicado**, editável, reativo. Pode pré-setar
+>   **vários** (id/período/status/…), sem campos.
+> - **toolbar.actions é SÓ pra caso pequeno e simples que NÃO reage com coluna** (ex.:
+>   data/período, escopo) — **label curta**, **máx ~2**. Se mexe com coluna, é grande, ou
+>   são muitos → **NÃO use o toolbar.**
+> - **Muitos filtros, ou ligados a coluna** → SEMPRE os nativos **pré-aplicados** (chips no
+>   load) + drawer "Filtros". Nunca empilhar selects.
+>
+> Regra de ouro: **filtro é recurso da tabela (reativo), não UI montada na unha.**
+
+- Busca global? (`enableSearch`)
+- Filtros por coluna? **Default = TODAS as colunas de dados filtram** (`enableColumnFilter: true` + `filterType` por tipo) — pergunte só "alguma NÃO deve filtrar?". O funil/drawer só lista colunas com `enableColumnFilter`; marcar só 2 = bug. (Ver §Regras de coluna em `generate.md`.)
+- Ações por linha (editar, excluir, ...)? (coluna `actions`, `getActions`) — vai por **último**; o DataTable ancora à direita/estreita sozinho (sem `pinned`/`width`). NÃO setar `width` nas demais (autoFit distribui).
+  **Toda ação destrutiva (Excluir) → confirmação OBRIGATÓRIA via `AlertModal`** (nunca
+  deletar direto). Pergunte o texto do confirm.
+- Seleção + ações em massa (exportar, etc.)? (`selectionConfig` + bulk actions).
+- Export: escopo (tudo / filtrado / selecionado) + formato (csv)? (`toolbar.enableExport`).
+- Ação custom no toolbar (ex.: seletor de período/mês, botão extra)? `toolbar.actions: ToolbarAction[]` (`button`/`dropdown`/`input`) — inline no desktop, colapsa no ⋯ no mobile. Oferecer só se o usuário pedir.
+
+## Fase 4 — Views, paginação & densidade
+
+- Views (ver bloco obrigatório). Dois sabores, pergunte os dois:
+  - **Presets fixos** que VOCÊ define (`defaultViews`/`presetView`, ex.: "Ativos", "Alto valor").
+  - **Views do usuário**: ele cria/salva/persiste as próprias (`savedViewsService` + `persistId`).
+- Paginação (tamanho inicial, opções) ou virtualização (10k+ linhas)?
+- Totalizadores no rodapé? (`showTotalizers` + `aggregate`).
+
+## Fase 5 — Criar/editar/detalhe (drawers)
+
+- Precisa criar/editar registro? → drawer estilo `NovoClienteDrawer` (Panel + FormField).
+  - **Quais campos no form?** (default: espelha as colunas editáveis). Pra cada campo:
+    **obrigatório?** **máscara** (CNPJ / telefone / CEP / moeda)? **validação** (formato,
+    min/max)? Todo label via `<FormField>` (nunca `<label>` cru) + `gap-form-gap`.
+- Precisa ver detalhe ao clicar na linha? → `FinanceDetailPanel` (FloatingPanel).
+- (Puxar `example-finance` na geração pra reusar esses padrões.)
+
+## Fase 6 — Kanban (opcional)
+
+- Quer alternar tabela↔kanban? Se sim: qual campo agrupa as colunas (ex.: status)?
+  Cada lane = uma option desse campo. (`viewMode` controlado + `kanbanConfig`.)
+
+## Fase 7 — Estados (SEMPRE perguntar — sai faltando se não)
+
+- **Loading** (`loading` + `renderLoading`): skeleton enquanto carrega — obrigatório em server mode.
+- **Vazio** (`renderEmpty`): sem nenhum registro → "Nenhuma `<entidade>` ainda" + CTA _Adicionar_.
+- **Sem resultado** (`renderNoResults`): filtro/busca sem match → "Nenhum resultado" + _Limpar filtros_.
+- (Aceite defaults sensatos se o usuário não quiser customizar — mas **sempre wire os três**.)
+
+Ao terminar: resuma as escolhas e siga pro `blueprint.md` (gate).

package/dist-lib/ai/roteiros/crud-builder/geracao.md

@@ -0,0 +1,113 @@
+> **Nota de portabilidade.** Este roteiro foi extraído do pipeline do iGreen DS
+> para Claude Code. Menções a slash command (`/ds-create-…`), a `.claude/` e a
+> ferramentas daquele ambiente descrevem **como ele é acionado lá** — aqui o
+> equivalente é carregar este roteiro pelo `indice.json`. O conteúdo de decisão
+> (entrevista, blueprint, regras de composição) vale igual.
+
+> **Modo submódulo (`ds-link`).** Existe `.claude/ds-config.json` com `"mode": "submodule"`?
+> Então **NÃO rode `igreen:add`** — esse script não existe no seu projeto. Os componentes e
+> exemplos já estão no disco em `<dsPath>/src`: importe pelo `importBase` do config
+> (compostos) e pelo `primitivesBase` (primitivos shadcn), e **leia** o exemplo direto de
+> `<dsPath>/src/examples/`.
+
+# CRUD Builder — Geração
+
+Só entre aqui após o gate aprovado. Ordem obrigatória:
+
+## 1. Puxar do registry (componentes + exemplo canônico)
+
+```bash
+npm run igreen:add -- data-table example-clientes
+# + example-finance  (se houver drawers de criar/editar/detalhe)
+# + outros componentes citados no blueprint (chip, avatar-ig, etc — o registry resolve deps)
+```
+
+## 2. LER antes de escrever (precedência de fontes)
+
+1. `src/examples/clientes/clientes-screen.tsx` — o molde real (colunas via `textColumn/currencyColumn/dateColumn/statusColumn/actionColumn`, `useMemo`, toolbar, paginação, seleção).
+2. `src/components/ui/DataTable/USAGE.md` + types ao lado — API exata.
+3. Pra drawers: `src/examples/finance/components/NovoClienteDrawer` e `.../FinanceDetailPanel`.
+
+Nunca gere props de memória — copie a forma do exemplo.
+
+## 3. Criar a página
+
+- Caminho/rota conforme o blueprint (`PAGES_DIR`/`REGISTRO`).
+- Wrapper: `<div className="flex flex-col h-full min-h-0 gap-gp-2xl">` → `<PageHeader .../>` → `<DataTable className="flex-1 min-h-0" .../>`.
+- `columns` em `useMemo`; server mode ⇒ `fetchData` em `useCallback`.
+
+### Regras de coluna (OBRIGATÓRIO — pega bugs comuns)
+
+1. **Filtro em TODAS as colunas de dados**: cada coluna ganha `enableColumnFilter: true` + `filterType` (text→`"text"`, number/currency/percentage→`"number"`, date→`"date"`, badge/status/select→`"select"`, multiSelect/tags→`"multiSelect"`). Só ficam de fora `actions` e render-custom sem valor. ⚠️ O funil/drawer de filtros só lista colunas com `enableColumnFilter` — marcar só 2 = bug "filtra só 2 colunas".
+2. **Coluna `actions` por ÚLTIMO**, `type: "actions"` (via `actionColumn`/`getActions`). É o **`type`** que dá as 3 garantias — vai pro fim (mesmo declarada no meio), **ancora à direita** (`pinned: "right"` é redundante) e **não entra no rateio** do autoFit. Coluna de botões montada na unha (`render` sem `type`) não recebe nenhuma das três: fica no meio da tabela e cresce no rateio. ⚠️ **NÃO passe `width`** (lib 0.42.0+): a largura é **derivada do nº de ações** — 1→44px, 2→74px, 3→104px, **4+ colapsam no "…"** (44px). Até a 0.41.x esta linha mandava espelhar `width: 64`; era inútil, porque o cálculo **ignorava `col.width`** nesta coluna. Agora vale, e 64px cabe **1** ícone. Split manual: `showInMenu: true` nos itens que devem ir pro menu (desliga o automático, sem limite de inline).
+3. **Prefira NÃO setar `width`** nas colunas de dados — `autoFit` (default ON) distribui pra preencher o container (sem 1ª coluna esticada, sem scroll). Nunca `autoFit: false` sem motivo. **(v0.22.0+)** `col.width` virou **base/piso** (não trava fixa): o autoFit usa como mínimo e ainda distribui a sobra proporcionalmente — setar `width` em várias colunas **não** deixa mais sobra à direita. Travar de fato = `width`+`maxWidth` iguais (ou `type` fixo). Título do header **nunca trunca** (a largura mínima já inclui o `headerName`).
+4. **Copiar valor** (`copyable`) — **infira, não espere que peçam**; ícone de copiar no **hover/foco** da célula + feedback "Copiado!" (~2s, `navigator.clipboard`). Critério: **o valor é um identificador que a pessoa cola em outro lugar**. ✅ documento (CPF/CNPJ/RG/IE), e-mail, telefone/WhatsApp, conta/agência/chave PIX, código de rastreio/protocolo/contrato/NF/pedido, token/hash, ID **externo**. ❌ nome de pessoa/empresa, status, data, valor monetário, quantidade, percentual, endereço em prosa. ⚠️ `id` sequencial curto (1, 2, 3) **não**; UUID/protocolo/NF **sim** — decide servir fora da tela, não a coluna se chamar "id". **Limites (verificados no código):** inerte em `actions`, na coluna de árvore e na célula em edição — marcar lá não dá erro, só não aparece; **`readMore` vence `copyable`** na mesma coluna (escolha um); copia o texto **formatado**, então numa coluna `currency` sai `R$ 1.234,56` e não `1234.56` — pro valor cru use `copyable: { value: (row) => String(row.x) }`. Texto/rótulo diferentes: `copyable: { value: (row) => "...", label: "Copiar conta" }`. **Declare no gate** as colunas em que você inferiu, pra o usuário recusar em lote — inferência silenciosa de recurso que ele não sabe que existe é surpresa, não conveniência.
+5. **Grab-to-scroll é NATIVO** (`grabToScroll` default `true`, v0.26.0+): toda tabela já rola lateral ao arrastar o corpo (mouse/pen, threshold ~6px, clique/seleção preservados). Não configure — só `grabToScroll={false}` pra desligar.
+6. **Filtro visível na tabela** (`showEmptyFilterChips`, v0.6.0+): pros filtros que o usuário mais usa (status, categoria, tipo, graduação…), passe `showEmptyFilterChips={["status", "categoria"]}` no `<DataTable>` → os chips nascem **vazios e clicáveis** já no load, sem abrir o menu de filtros. É o que faz o filtro **aparecer** na tela — sem isso o usuário não vê a afordância e acaba pedindo select na unha (⛔ **proibido** montar form/select acima da tabela — ver `.claude/rules/ds-components.md`). Status/segmento como eixo de navegação (poucos valores) → alternativa: **uma visão por valor** em `defaultViews` (ver item de visões abaixo). Regra de ouro: se a informação está numa coluna, **chip nativo primeiro**.
+
+**Formato de data.** `type: "date"` renderiza `14/03/2023` e `type: "datetime"` renderiza `14/03/2023 09:30` — **com ano** (lib 0.43.0+). Precisa de outro formato (mês escrito, relativo, ISO)? Passe **`valueFormatter`** na coluna: ele vence o formato do tipo e vale na célula, no export e no clipboard. **NÃO** escreva `render` próprio só pra formatar data. ⚠️ Até a 0.42.1 esses tipos mostravam a data **sem ano** e o `valueFormatter` não chegava na célula — se você viu `render` de data em código antigo, era contorno disso.
+
+
+### Padrões de CÉLULA (consistência finance — OBRIGATÓRIO)
+
+Espelhar `finance-screen.tsx` (puxe `example-finance`). **Componente do DS sempre antes de markup manual**:
+
+- **Coluna primária (nome)**: `isPrimary` + `render` com `<Avatar size="md">` + nome `text-body-sm font-medium` + secundária `text-caption-md text-fg-muted` (email/ID/doc) + ícone "abrir detalhe" (`<SquareArrowOutUpRight>` num `size-[24px] rounded-radius-sm border bg-bg-canvas shadow-sh-sm`) quando o row click abre painel.
+- **Status / badge**: `type: "badge"` + `render` com `<Chip variant="soft" size="sm" shape="pill">` (cor semântica). Nunca pill na unha com `<span>` estilizado.
+- **Avatar**: use **`avatar-ig`** (`@/components/ui/avatar-ig`), não o `avatar` (Radix puro, sem `colorHex`/`size`). `size="md"` na tabela (não `sm`). **Números/moeda/%**: `tabular-nums` + `type` (`currency`/`percentage`) + `align: "right"`. **Tags**: `type: "tags"` + `<Chip soft sm rounded>`. **Código/identificador/valor técnico** (chave de env, ID, hash, slug, path): preset **`text-code-sm`** — nunca `font-mono text-body-sm` + `tracking-*` na unha.
+
+### Detail panel (row click → painel)
+
+**Cite o bloco `dsgreen-paneldetail-1`** — a estrutura inteira já está resolvida e
+referenciável por ID (`npm run igreen:add -- dsgreen-paneldetail-1`, ou peça
+*"use a referência dsgreen-paneldetail-1"*).
+
+A referência anterior era "espelhe o `FinanceDetailPanel`", e ela funciona — o
+`example-finance` distribui esse arquivo. O bloco é melhor por dois motivos, não porque o
+outro esteja quebrado: **não exige puxar uma tela inteira** só pra ver um painel, e o arquivo
+dele traz **o porquê de cada decisão** (com as medições) em vez de só o resultado.
+
+**Sempre** `<FloatingPanel>`, nunca markup solto. O que o bloco carrega:
+
+- `titleSlot`: `<Avatar size="lg">` + nome (`text-body-md font-semibold`) + linha
+  `código · <Chip status>`. ⚠️ Se você usar `Panel` em vez de `FloatingPanel`, esse header é
+  impossível: lá `title`/`description` são **string**.
+- `headerActions`: 1–2 ações de ícone, **todas `variant="soft"`** (`secondary` neutro,
+  `success` contato, `critical` destrutivo). `ghost` no meio da fileira fica sem container e lê
+  como desabilitada ao lado do maximize/close, que o componente renderiza como `soft`.
+  `aria-label` obrigatório — botão de ícone não tem texto.
+- `bodyPadded={false}` + **agrupar por assunto** em `<FloatingPanelSection title>`.
+- 1ª seção = **métricas do registro**, em cards compactos (ícone + valor 18px + rótulo), 2 por
+  linha. ⛔ **Não use `Kpi`**: ele é card de dashboard (144px de altura por célula) e come a
+  primeira dobra do painel antes de qualquer campo.
+- Cada dado simples = **uma linha** `<FloatingPanelField label value/>`.
+- Dado que **não é** `label: valor` sai do Field: entidade com marca (banco, gestor) vira linha
+  de largura cheia com `Avatar`; vários valores viram `<Chip>`; e-mail/telefone viram
+  `mailto:`/`tel:` com cor de link.
+- `footer`: Fechar + ação primária.
+- ⛔ **Sem aba.** 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.
+
+- **Tabela + Lista (toggle)**: se o usuário quer alternar entre tabela e uma **lista de cards** (não kanban), use `viewMode` + `listConfig={{ renderItem(row), paginated?, hierarchical?, getPath?, getMenuItems? }}` no próprio `<DataTable>` — mesma toolbar, toggle Tabela/Lista automático. NÃO monte um `<DataList>` paralelo + toggle na mão.
+  - **Lista flat paginada**: `listConfig.paginated: true` — a lista usa a MESMA paginação da tabela + mostra o footer. Default `false` (mostra todas, sem footer); ignorado em `hierarchical`. Use quando a lista flat puder ter muitas linhas.
+- ⛔ **No MÁXIMO 2 presets, e NUNCA um preset "Todos"/"Todas"**: `maxTabs` default é 3 e a aba **Default** (nativa, que já É a visão sem filtro) consome 1 slot — sobram 2. O excedente é cortado por `.slice(0, maxTabs - 1)` — em DEV o componente avisa no console qual visão foi engolida (v0.43.1), em produção não. Precisa de mais? `maxViewTabs={N + 1}` no `<DataTable>` (o `+1` é a Default) — mas 2 é o default por um motivo: barra de visões não é menu. Um preset "Todos" duplica a Default e gasta um slot com nada.
+- **Visões pré-definidas read-only (`allowCreateView={false}`, v0.23.0+)**: passe `defaultViews={[presetView({ id, name, filters?, sort?, viewMode? })]}` + `persistId` pras abas nativas da tela. `allowCreateView={false}` esconde o botão "+" (o usuário não salva visões próprias — só usa as suas). Default `true`. **viewMode "sticky"**: trocar de visão só muda Tabela↔Lista↔Kanban se o preset declarar `viewMode` explícito; sem isso, mantém a view que o usuário está vendo (só declare `viewMode` no preset que DEVE forçar uma view).
+  - Lista árvore **+ tabela árvore**: `hierarchical` + `getTreeDataPath` (tabela não pagina).
+  - **Tabela FLAT paginada + lista em ÁRVORE**: `hierarchical` + **`listConfig.getPath`** e NÃO passe `getTreeDataPath` (senão a tabela vira tree-data e perde paginação).
+- Drawers de criar/editar: espelhe `NovoClienteDrawer` (Panel + FormField + `gap-form-gap`), ligados via estado da página (igual ao `finance-screen.tsx`).
+- Tokens/spacing/typography conforme `.claude/rules/ds-design.md` + `DESIGN.md`.
+
+## 4. Registrar a rota
+
+No ponto que o usuário indicou (router / App). Página órfã = incompleto.
+
+## 5. Validar
+
+```bash
+npx tsc --noEmit   # abort se falhar — corrija antes do handoff
+```
+
+## 6. Handoff
+
+`CRUD_PRONTO: <Entidade>` + onde foi registrada + como rodar (`npm run dev`).
+Sugira ao usuário abrir a tela e conferir; ofereça ajustes finos (larguras de coluna, filtros).

package/dist-lib/ai/roteiros/crud-builder/roteiro.md

@@ -0,0 +1,89 @@
+> **Nota de portabilidade.** Este roteiro foi extraído do pipeline do iGreen DS
+> para Claude Code. Menções a slash command (`/ds-create-…`), a `.claude/` e a
+> ferramentas daquele ambiente descrevem **como ele é acionado lá** — aqui o
+> equivalente é carregar este roteiro pelo `indice.json`. O conteúdo de decisão
+> (entrevista, blueprint, regras de composição) vale igual.
+
+
+# CRUD Builder (consumidor) — Router
+
+Você guia a criação de uma tela de tabela que consome `<DataTable>` **sem fugir
+do exemplo e da documentação do projeto**. NÃO inventa API de props, NÃO gera
+código de memória, NÃO toca em arquivo antes do gate aprovado.
+
+> **Kanban / board / funil / pipeline de vendas** caem AQUI: kanban é uma `viewMode`
+> do DataTable (mesmos dados/colunas/filtros, só muda a exibição). "Quero um kanban/
+> funil" → esta skill; a Fase 6 do interview configura as lanes pela coluna de
+> status/etapa. Funil = board agrupado por etapa. Ref. visual: `example-finance`.
+
+## Ambiente (este é um projeto CONSUMIDOR, copy-in)
+
+| Variável                 | Valor                                                                                                           |
+| ------------------------ | --------------------------------------------------------------------------------------------------------------- |
+| `IMPORT_PATH`            | `@/components/ui/DataTable`, `@/components/ui/Button`, etc (copy-in via alias)                                  |
+| `EXEMPLO_CANÔNICO`       | `example-clientes` → `npm run igreen:add -- example-clientes` → ler `src/examples/clientes/clientes-screen.tsx` |
+| `DOC`                    | `src/components/ui/DataTable/USAGE.md` (após `igreen:add data-table`) + types ao lado                           |
+| `PAGES_DIR` / `REGISTRO` | perguntar ao usuário (onde mora a página + como registra rota)                                                  |
+
+Se o componente/exemplo ainda não está no disco, **puxe via `igreen:add`** antes de ler — nunca gere de memória.
+
+> **Modo submódulo (ds-link).** Se existe `.claude/ds-config.json` com `"mode": "submodule"`,
+> o DS é consumido como **submódulo** (não copy-in): os componentes/exemplos JÁ estão no disco
+> em `<dsPath>/src` e **não** há registry. Use `importBase` do config (ex.: `@ds/components/ui/<Nome>`)
+> e leia o exemplo canônico direto em `<dsPath>/src/examples/clientes/clientes-screen.tsx` —
+> **NÃO** rode `igreen:add`. `PAGES_DIR`/`REGISTRO` continuam do projeto pai.
+
+## Fluxo — 3 estágios
+
+```
+/ds-create-crud
+   ▼ interview.md
+1. ENTREVISTA (fases 0-6)         — acumula escolhas, ZERO edição em disco
+   ▼ blueprint.md
+2. BLUEPRINT [GATE]               — preview consolidado + pré-validações → aguarda "aprovar"
+   ▼ generate.md
+3. GERAÇÃO                        — igreen:add → ler exemplo → criar página → registrar → tsc → handoff
+```
+
+Carregue cada sub-arquivo só no estágio correspondente: `interview.md` agora, `blueprint.md` ao fim da entrevista, `generate.md` só após o gate.
+
+## ⚠️ Precedência de fontes (anti-drift)
+
+```
+1. src/examples/clientes/clientes-screen.tsx  (exemplo real, vence tudo)
+2. src/components/ui/DataTable/USAGE.md + types ao lado
+3. Snippets desta skill
+4. Memória da IA  ← NUNCA confiar sozinha
+```
+
+Se USAGE.md divergir do exemplo/types, o exemplo + types vencem.
+
+## Guardrails (não-negociáveis)
+
+1. `columns` SEMPRE em `useMemo`; `fetchData` (server mode) SEMPRE em `useCallback` (senão loop de refetch).
+2. Operador de filtro válido pro filterType (multiSelect⇒`isAnyOf`, text⇒`contains`, date⇒`between`...).
+3. `virtualize: true` ⇒ paginação desligada + container com altura (`flex-1 min-h-0` num pai `h-full`).
+4. `groupBy`/kanban ativo ⇒ paginação desligada (avisar).
+5. Forms em drawers/modais usam `<FormField>` (nunca `<label>` cru) + `gap-form-gap`.
+6. Classes DS antes de Tailwind literal; zero hardcode de cor/tamanho (ver `.claude/rules/ds-design.md`).
+7. Wrapper da tela: `flex flex-col h-full min-h-0 gap-gp-2xl` (PageHeader → 16px → tabela). Ver `DESIGN.md`.
+8. Página registrada no roteador do usuário — página órfã = tarefa incompleta.
+9. `npx tsc --noEmit` limpo antes do handoff (abort-on-error).
+10. LER o exemplo canônico ANTES de gerar — nunca de memória.
+11. Ação destrutiva (excluir) ⇒ **confirmação via `AlertModal`** — nunca deletar direto.
+12. Sempre wire os 3 estados: `loading`/`renderLoading` (skeleton), `renderEmpty` (sem
+    registros + CTA _Adicionar_), `renderNoResults` (filtro sem match). **O default
+    embutido conta como wirado — desde que declarado no blueprint** (linha `Estados:`).
+    Faltou = incompleto: o que não vale é o estado nunca ter sido decidido.
+
+## Drawers (criar/editar/detalhe) — ligado ao CRUD
+
+Se o CRUD precisa de criar/editar/ver-detalhe, espelhe o padrão do `example-finance`:
+`NovoClienteDrawer` (criar/editar via `Panel` + `FormField`) e `FinanceDetailPanel`
+(detalhe via `FloatingPanel`). Puxe `example-finance`, leia esses componentes e
+reuse a estrutura — mesmo design de drawer do DS.
+
+## Handoff
+
+- Entrevista pronta → `BLUEPRINT_PRONTO: <Entidade> — aguardando gate`
+- Pós-geração → `CRUD_PRONTO: <Entidade>` (+ onde foi registrada)

package/dist-lib/ai/roteiros/drawers/roteiro.md

@@ -0,0 +1,41 @@
+> **Nota de portabilidade.** Este roteiro foi extraído do pipeline do iGreen DS
+> para Claude Code. Menções a slash command (`/ds-create-…`), a `.claude/` e a
+> ferramentas daquele ambiente descrevem **como ele é acionado lá** — aqui o
+> equivalente é carregar este roteiro pelo `indice.json`. O conteúdo de decisão
+> (entrevista, blueprint, regras de composição) vale igual.
+
+
+# drawers — Criar / Editar / Detalhe
+
+Padrão de drawer do DS, ligado ao CRUD/detalhe. Três variantes, mesma família visual.
+
+## Fluxo
+1. `npm run igreen:add -- example-finance` (traz os drawers + `Panel`, `FloatingPanel`, `FormField`).
+2. **Leia** os componentes-modelo:
+   - Criar/editar → `src/examples/finance/components/NovoClienteDrawer` e `.../EditarFinanceDrawer` (base: `Panel` + `FormField`).
+   - Ver detalhe → `src/examples/finance/components/FinanceDetailPanel` (base: `FloatingPanel`, não-modal).
+3. Adapte os campos/conteúdo ao caso. Ligue ao estado da página (igual `finance-screen.tsx`: `open`/`onOpenChange` + registro selecionado).
+
+> **Modo submódulo (ds-link).** Se existe `.claude/ds-config.json` com `"mode": "submodule"`,
+> o DS é consumido como **submódulo** (não copy-in): os componentes/exemplos JÁ estão no disco
+> em `<dsPath>/src` e **não** há registry. Use `importBase` do config (ex.: `@ds/components/ui/Panel`)
+> e leia os drawers-modelo direto em `<dsPath>/src/examples/finance/components/` —
+> **NÃO** rode `igreen:add`.
+
+## Gotchas do tipo
+- **Criar/Editar** = `Panel` (drawer modal lateral) com form em `<FormField>` + `gap-form-gap`. Footer sticky com Cancelar/Salvar.
+- **Detalhe** = `FloatingPanel` (não-modal, não bloqueia a página; pode coexistir com a tabela). `shadow-sh-aside`.
+- Largura: `Panel` default é `size="md"` = **560px**. O token `max-w-drawer-md` (480px) é outra coisa — não confunda. Mobile (<1024px): vira Sheet full.
+- Nunca `<label>` cru; nunca `<button onClick>` como "card de seleção" (use label/FormField nativo).
+- Abrir detalhe no click da linha (`onRowClick`); abrir editar via ação da linha.
+
+Aplique `DESIGN.md` + regras. Handoff: `DRAWER_PRONTO: <criar|editar|detalhe> de <Entidade>`.
+
+## Aba dentro do drawer/painel
+
+`<Tabs fullWidth>` com a variante **default** (`segmented`) — nunca `line`. Estas superfícies
+são estreitas por construção (`Panel` 560px, `FloatingPanel` 320–720 e **redimensionável**),
+e ali o `line` vira um trilho curto que lê como fragmento. Sem `fullWidth` as abas ficam num
+canto. ⛔ Não escreva `w-full` no `TabsList` nem `flex-1` nos triggers: a prop faz as três
+camadas (root + list + triggers), e `w-full` só no list estica o container e agrupa as abas
+na esquerda.

package/dist-lib/ai/roteiros/list-builder/blueprint.md

@@ -0,0 +1,94 @@
+> **Nota de portabilidade.** Este roteiro foi extraído do pipeline do iGreen DS
+> para Claude Code. Menções a slash command (`/ds-create-…`), a `.claude/` e a
+> ferramentas daquele ambiente descrevem **como ele é acionado lá** — aqui o
+> equivalente é carregar este roteiro pelo `indice.json`. O conteúdo de decisão
+> (entrevista, blueprint, regras de composição) vale igual.
+
+
+> **Modo submódulo (`ds-link`).** Existe `.claude/ds-config.json` com `"mode": "submodule"`?
+> Então **NÃO rode `igreen:add`** — esse script não existe no seu projeto. Os componentes e
+> exemplos já estão no disco em `<dsPath>/src`: importe pelo `importBase` do config
+> (compostos) e pelo `primitivesBase` (primitivos shadcn), e **leia** o exemplo direto de
+> `<dsPath>/src/examples/`.
+
+# List Builder — Blueprint [GATE]
+
+## Pré-validações automáticas (ANTES de exibir)
+
+Corrigir silenciosamente (ou reportar se exigir decisão):
+
+1. **Excludências de escala** — `virtualized` + `enableDnD` → desligar DnD;
+   `virtualized` + `onLoadMore` → escolher um; `fillHeight` + `virtualized` →
+   `fillHeight` off. Anotar `← corrigido`.
+2. **branchHighlight** só com `layout="hierarchical"` — em outro layout, ignorar
+   e avisar.
+3. **Coerência de layout** — `grouped` tem `groups`; `hierarchical` tem itens com
+   `children` (ou `onLoadChildren`).
+4. **filterFields** — cada um tem `accessor`; `select` tem `options`. Operador de
+   view/filtro pré-aplicado válido pro `type` (multiSelect⇒`isAnyOf`,
+   select⇒`equals`, text⇒`contains`, number⇒`equals`, date⇒`between`,
+   boolean⇒`equals`).
+5. **Colisão de rota** — o id/rota proposto não pode já existir no router **deste
+   projeto**. Colisão → propor sufixo. (Onde ficam as rotas varia: React Router,
+   TanStack Router, file-based do Next… **pergunte** se não for óbvio pelo repo.)
+6. **Card** — `title` presente (slots) OU `renderItem` definido. Excluir
+   (destructive) tem `AlertModal` no plano (se houver form).
+
+## Formato do blueprint (apresentar TUDO de uma vez)
+
+```markdown
+## Blueprint — Lista <Entidade>
+
+**Página**: <Título> · id `<page-id>` · wrapper <ExamplePageLayout|AppShell|puro> · nav "List Components"
+**Dados**: <client|server> mode · fonte: <sample|interface|endpoint|manual> · ~<N> itens · id: `<campo>`
+
+### ⚠️ Decisões inferidas — vete se discordar
+
+Só o que o usuário NÃO disse e você decidiu sozinho (wrapper, tema, tipo de campo com
+confiança baixa…) — uma linha cada, com o que muda se ele vetar. Sem inferência →
+`nenhuma`; não apague a seção: é a ausência dela que faz a decisão passar aprovada
+em pacote junto com o resto.
+
+### Card (<slots|renderItem>)
+- leading: <avatar/ícone|—> · title: `<campo>` · subtitle: `<campo|—>`
+- meta: [<label:campo(align)>, ...] · trailing: <badge|—> · description: <campo|—>
+- (ou renderItem custom: <descrição do card rico>)
+- densidade <comfortable|compact> · menu por card [<Editar·Excluir>|—]
+
+### Layout
+<standard | grouped (groups: <id(cor)>...; DnD <on|off>; surface <on|off>)
+ | hierarchical (branchHighlight <none|block|active>; expand inicial <...>; lazy <on|off>)>
+
+### Toolbar
+título OU views[<abas>] · busca <on|off> · refresh <on|off> · moreActions [<...>]
+filterFields: [<id:label:type>, ...]
+
+### Seleção / escala
+selectable <on|off> + bulk [<actions>] · onItemClick <nada|detalhe|nav>
+escala: <nenhuma | virtualized (estimate <N>) | infinite (onLoadMore/hasMore/loadingMore)>
+fillHeight <on|off>
+
+### Estados
+loading <skeletonCount> · vazio <emptyState msg/CTA>
+
+### Arquivos
+- CRIAR  <PAGES_DIR><Nome>.tsx (~<N> linhas)
+- EDITAR <REGISTRO> (rota + entrada de navegação do SEU projeto — ver Fase 0)
+
+### Referências canônicas que serão lidas antes de gerar
+<lista da matriz do generate.md, só os cenários presentes>
+
+⛔ Nenhum arquivo será tocado antes da aprovação.
+Responda **aprovar** · **ajustar <o quê>** · **cancelar**.
+```
+
+## Protocolo do gate
+
+- Enunciar a **Assumption** central junto do blueprint (ex.: "o sample é
+  representativo; `status` tem exatamente os N valores mapeados") — é o que torna a
+  decisão reversível depois. **Não** há audit log a preencher neste projeto.
+- `aprovar` → carregar `generate.md` e executar.
+- `ajustar X` → re-montar → re-apresentar (novo gate).
+- `cancelar` → abortar; nota de cancelamento. Zero disco.
+
+Sinal junto com o preview: `BLUEPRINT_PRONTO: <Entidade> (lista) — aguardando gate`