@snksergio/design-system 0.61.0 → 0.62.0

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

@@ -0,0 +1,60 @@
+# ScreenLoader
+
+<!-- ds:regras
+- omita `size`: `md` é o calibrado pro slot do AppShell; `lg` não é "pra dar destaque"
+- omita `skeletonLayout`: `page` serve pra qualquer tela — só mude se ela TEM KPIs no topo
+- o pai precisa ter altura, senão a variante spinner colapsa no topo
+- loading inline (botão, célula) → `Spinner` direto; overlay é composição do consumidor
+-->
+
+**Categoria:** iGreen (tv()). Estado de **carregamento de página/área** — preenche o container pai e mostra um indicador enquanto o conteúdo processa. Irmão do `EmptyState` (mesma família de "estado de área").
+
+## Quando usar
+
+- Conteúdo de uma página inteira carregando dentro do slot de conteúdo do AppShell.
+- Área grande (card, section, painel) aguardando primeira carga de dados.
+- **Não** é pra loading inline (botão, célula) — aí use `Spinner` direto.
+- **Não** é overlay sobre conteúdo já renderizado — cobre o slot vazio; sobrepor é composição do consumidor.
+
+## Props essenciais
+
+| Prop | Tipo | Default | Descrição |
+|------|------|---------|-----------|
+| `variant` | `"spinner" \| "skeleton"` | `"spinner"` | `spinner` = Spinner centrado + título + descrição. `skeleton` = silhueta genérica de página, sem prever o layout final. |
+| `skeletonLayout` | `"page" \| "dashboard" \| "kpis"` | `"page"` | Blocos da silhueta (só `skeleton`): `page` = header + conteúdo · `dashboard` = header + linha de 4 KPIs + conteúdo · `kpis` = KPIs + conteúdo, sem header. |
+| `title` | `string` | `"Carregando…"` | Visível no `spinner`; sr-only no `skeleton` (leitores anunciam via `role="status"`). |
+| `description` | `string` | — | Linha auxiliar sob o título (só `spinner`). |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Escala spinner + tipografia do título. Sem efeito no `skeleton`. **`md` é o padrão de uso** — não passe `size` a menos que a área destoe (ver Gotchas). |
+| `color` | cores do Spinner | `"brand"` | Repassada ao Spinner (só `spinner`). |
+| `className` | `string` | — | Overrides no root (aceita `ref` de `HTMLDivElement`). |
+
+## Exemplo mínimo
+
+```tsx
+import { ScreenLoader } from "@snksergio/design-system";
+
+// dentro do slot de conteúdo (o pai precisa ter altura)
+{isLoading ? (
+  <ScreenLoader title="Carregando clientes" description="Buscando os dados mais recentes…" />
+) : (
+  <ClientesPage />
+)}
+
+// variação skeleton — silhueta genérica em vez de spinner
+{isLoading ? <ScreenLoader variant="skeleton" /> : <ClientesPage />}
+
+// tela de painel: skeleton com linha de KPIs (com ou sem header)
+{isLoading ? <ScreenLoader variant="skeleton" skeletonLayout="dashboard" /> : <Dashboard />}
+{isLoading ? <ScreenLoader variant="skeleton" skeletonLayout="kpis" /> : <KpiSection />}
+```
+
+## Gotchas
+
+- **Padrão de uso: omita `size` (= `md`).** É o calibrado pro slot de conteúdo do AppShell. `sm` só pra área comprovadamente pequena (card baixo, painel lateral); `lg` só pra tela cheia vazia sem chrome. Não escolha `lg` "pra dar destaque".
+- **Padrão do skeleton: omita `skeletonLayout` (= `page`, header + conteúdo).** É a silhueta genérica que serve pra qualquer tela — só saia dela quando a tela alvo COMPROVADAMENTE tem KPIs no topo: `dashboard` (com header de página) ou `kpis` (quando o header já está renderizado fora da área que carrega). Não invente combinação além dessas três: layout mais específico que isso = compor `Skeleton` na mão.
+
+- **O pai precisa ter altura.** O componente preenche o container (`h-full flex-1`) — num pai sem altura definida, a variante `spinner` colapsa no topo (o `skeleton` tem `min-h` próprio de fallback). No AppShell o slot de conteúdo já tem altura.
+- **Nunca `position: fixed`** — cobrir o viewport inteiro (splash, auth guard) é composição do consumidor, de propósito.
+- **Skeleton genérico de propósito**: quando o layout final é conhecido (tabela, lista de cards), componha `<Skeleton>` na mão desenhando a silhueta real — o `DataTable`/`DataList` já trazem os próprios skeletons; não empilhe este por cima.
+- **A11y sem duplicação**: o root tem `role="status"` + `aria-live="polite"`; o Spinner interno vai `aria-hidden`. Não embrulhe em outro `role="status"`.
+- A rotação do Spinner para sob `prefers-reduced-motion` (`motion-reduce:animate-none`); o pulse do Skeleton (só opacidade, sem deslocamento) **não** é gated — é o comportamento do `shadcn/skeleton.tsx`.

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

@@ -0,0 +1,171 @@
+# SingleMenuSidebar
+
+<!-- ds:regras
+- NÃO passe `logo`: o default é a marca iGreen. Só com marca própria pedida explicitamente
+- `title` = nome do projeto (vai à direita da logo) — pergunte, não invente
+- é a escolha quando NÃO há divisão em áreas: `showSearch={false}`, sem `module`/`modules`
+-->
+
+**O que é** — Sidebar de navegação de **nível único**: categoria → sub-itens em
+accordion (1 aberto por vez). Categoria sem `items` é link simples.
+**Categoria**: Templates / App-level (mesma família de `MenuSidebar`, `Header`, `AppShell`).
+
+**Quando usar** — App com navegação plana, sem múltiplos contextos/rail. É a
+alternativa **enxuta** ao `MenuSidebar` (que tem rail + painel + sections +
+badges). Sem variantes — escolha o componente pela necessidade, não por props.
+Precisa de rail + contextos + bookmarks/chats? → use `MenuSidebar`.
+
+**Qual das duas** — o critério é *o sistema tem áreas grandes e separadas, cada uma com o
+menu dela?* Sim → `MenuSidebar` (as áreas ficam todas visíveis no rail). Não → esta, na
+variação **"Sem módulo / sem busca"** (omita `module`/`modules`, passe `showSearch={false}`).
+Ela **também** aceita módulos, mas aí eles ficam atrás de um botão acima da busca — por isso
+não é a recomendação quando a divisão existe.
+
+**A logo é a da iGreen por default** — `logo` é opcional desde a 0.46.0 e cai em
+`SidebarBrandMark`. Só passe quando o app tem marca própria; `title` é o **nome do projeto**,
+exibido à direita dela.
+
+> ⚠️ Até a 0.46.0 `logo` era **obrigatória e sem fallback**, enquanto o `brand` do `MenuSidebar`
+> sempre foi opcional. Trocar pra esta sidebar portanto *forçava* quem montava a inventar uma
+> logo — e foi assim que a marca da iGreen sumiu num app de consumidor (2026-08-22).
+
+## Props essenciais
+
+| Prop                            | Tipo                          | Default | Obrigatório |
+| ------------------------------- | ----------------------------- | ------- | ----------- |
+| `logo`                          | `ReactNode`                   | **marca iGreen** | — (omita p/ ficar com a marca) |
+| `title`                         | `string`                      | —       | ✅          |
+| `user`                          | `SingleMenuUser`              | —       | ✅          |
+| `categories`                    | `SingleMenuCategory[]`        | —       | opcional se usar `modules` |
+| `modules`                       | `SingleMenuModuleConfig[]`    | —       |             |
+| `activeModuleId` / `defaultModuleId` / `onModuleChange` | multi-módulo (controlado / inicial / callback) | — | |
+| `module`                        | `SingleMenuModule`            | —       | **ignorado se `modules`** |
+| `showSearch`                    | `boolean`                     | `true`  |             |
+| `searchCommand`                 | `ReactNode`                   | —       |             |
+| `searchPlaceholder`             | `string`                      | —       |             |
+| `activeItemId`                  | `string`                      | —       |             |
+| `onItemClick`                   | `(id: string) => void`        | —       |             |
+| `defaultExpanded`               | `boolean`                     | `true`  |             |
+| `expanded` / `onExpandedChange` | toggle controlado             | —       |             |
+| `showToggleIndicator`           | `boolean`                     | `false` |             |
+
+⚠️ **A busca NÃO é input controlado.** `searchValue`/`onSearchChange`/`searchRef` **não
+existem** nesta API (estavam documentados aqui e nunca foram props do componente). A busca
+abre um `CommandDialog`: você passa o **conteúdo** dele em `searchCommand` e, se quiser, o
+texto do placeholder em `searchPlaceholder`. As props `value`/`onChange`/`inputRef` existem
+em `SingleMenuSearchProps`, que é subcomponente interno.
+
+### Multi-módulo
+
+`modules` é a API pra sidebar que troca de contexto: cada `SingleMenuModuleConfig` traz suas
+próprias `categories`, e trocar de módulo **sobrepõe** as categorias exibidas. Quando
+`modules` é passado, `module` (singular) é ignorado e `categories` no nível raiz vira
+opcional.
+
+## Data model
+
+```ts
+SingleMenuCategory  = { id, icon, label, href?, items?, active? }
+SingleMenuSubItem   = { id, label, href? }
+SingleMenuModule    = { icon, title, subtitle, options?, onModuleChange? }
+SingleMenuUser      = { name, email, avatar?, actions?, onAction? }
+SingleMenuUserAction= { id, label, icon?, variant?: "default" | "destructive" }
+```
+
+## Navegação — `href` e `renderLink`
+
+Item **com `href`** vira `<a href>`: ctrl/cmd+clique abre em nova aba, "copiar endereço do
+link" funciona, e o leitor de tela anuncia **link** (com `aria-current="page"` no ativo).
+Sem `href`, continua `<button>`. Vale pro sub-item e pra **categoria-folha** (sem `items`).
+
+Pra integrar o router do consumidor, use **`renderLink`** — render-prop, não componente:
+
+```tsx
+<SingleMenuSidebar
+  categories={categories}
+  onItemClick={(id) => setAtivo(id)}
+  renderLink={({ href, ...rest }) => <Link to={href} {...rest} />}
+/>
+```
+
+⚠️ **Sem `renderLink`**, o clique cancela a navegação nativa quando há handler — **exceto**
+em clique modificado, `target="_blank"`, href externo (`https:`, `mailto:`…) e **href de
+hash** (`#/rota`). A regra e o porquê de cada exceção estão em `@/utils/nav-link`, que é a
+MESMA lógica do `MenuSidebar` (util compartilhada, não cópia).
+
+> ⚠️ Até 2026-08-18 o `href` acima **não fazia nada**: o tipo o aceitava, este USAGE o
+> documentava, e o componente renderizava `<button>` sempre. Se você escreveu código
+> contando com navegação por `href` aqui, ele nunca navegou — agora navega.
+
+## Exemplo mínimo
+
+```tsx
+import { SingleMenuSidebar } from "@/components/ui/SingleMenuSidebar";
+
+<SingleMenuSidebar
+  logo={<Logo />}
+  title="Sólis iGreen"
+  module={{
+    icon: <Zap />,
+    title: "Créditos",
+    subtitle: "MÓDULO ATIVO",
+    options,
+  }}
+  categories={[
+    { id: "dashboard", icon: <LayoutGrid />, label: "Dashboard", active: true },
+    {
+      id: "instalacoes",
+      icon: <Zap />,
+      label: "Instalações",
+      items: [
+        { id: "contratos", label: "Contratos" },
+        { id: "vistorias", label: "Vistorias" },
+      ],
+    },
+  ]}
+  user={{ name: "Sérgio", email: "sergio@igreen.com.br", actions }}
+  activeItemId={activeItemId}
+  onItemClick={setActiveItemId}
+/>;
+```
+
+## Comportamentos
+
+- **Accordion** — apenas 1 categoria aberta por vez. Definir `activeItemId` abre
+  automaticamente a categoria que contém o item.
+- **Seleção única** — sempre 1 item marcado: folha ativa OU pai aberto (abrir um
+  pai o marca e suprime a folha) OU pai que contém o sub-item ativo. Clicar numa
+  folha fecha o pai aberto e assume a marca.
+- **Toggle** — botão no header trava/destrava o estado expandido. Após recolher
+  manualmente, o hover-expand fica suprimido ~500ms (não "pisca" com o mouse por cima).
+- **Hover-to-expand** — recolhida, o hover sobre a sidebar a expande
+  temporariamente; sai o mouse, recolhe (~200ms). Categorias mostram tooltip.
+  ⚠️ **A espiada FLUTUA sobre o conteúdo — não empurra** (v0.43.0+). No desktop o
+  painel vira `absolute z-40` e o `<aside>` continua ocupando só a largura do rail,
+  então o que está ao lado não se mexe. **Só o clique** (travar aberta) ocupa espaço
+  no fluxo e empurra — é decisão de layout do usuário, e quem está com o menu
+  recolhido escolheu maximizar a área de conteúdo.
+  Antes disso a espiada animava a largura **dentro** do fluxo: numa tela com
+  `DataTable` isso disparava 5 recálculos completos de largura de coluna por gesto,
+  ~100ms de travada e **CLS 0,117**. É o mesmo desenho que o `MenuSidebar` sempre
+  teve (painel flutuante), agora aqui. Se você depende do empurrão no hover, use
+  `expanded` controlado e trave aberta.
+- **Controlado/não-controlado** — `expanded` + `onExpandedChange` (controlado) ou
+  `defaultExpanded` (não-controlado).
+- **Responsivo (mobile)** — abaixo de `md` (768px) a sidebar ocupa **100% da
+  largura** (pronta pra drawer); no desktop mantém a largura fixa (280px/80px). A
+  sidebar é **dumb**: exibir/ocultar no mobile é responsabilidade do consumidor
+  (um toggle/drawer controlado pelo seu app — veja o exemplo "Responsivo (mobile)").
+
+## Gotchas
+
+- **Sem variantes (por design).** Não há `variant`/`size`. Mudança visual = editar
+  `single-menu-sidebar.styles.ts`. Outra forma de navegação = outro componente.
+- **Dá altura ao container.** O `<aside>` é `h-full` — o pai precisa ter altura
+  (ex.: `h-[680px]` ou `flex-1 min-h-0` num pai `h-full`).
+- **`logo` e `avatar` são ReactNode** — você controla o tamanho; o slot do logo só
+  faz `shrink-0`. Passe um elemento já dimensionado (ex.: caixa `size-form-lg`).
+- **Cores 100% via tokens DS.** Estado marcado = `fg-brand` + `bg-sidebar-accent`;
+  rodapé/hover = `bg-sidebar-accent`. Não usa palette própria `sidebar-*`.
+- **`<TooltipProvider>` embutido** — o componente já envolve a árvore; não precisa
+  de provider externo só pra ele.

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

@@ -0,0 +1,52 @@
+# Spinner
+
+**Categoria:** iGreen (tv()). Indicador de **loading** (SVG que gira).
+
+## Quando usar
+
+- Estado de carregamento inline: dentro de botões (`Salvando…`), ao lado de um label, em placeholders de área que ainda vai popular.
+- Para um bloco de página inteiro carregando, componha com o seu próprio layout (ex.: centralizar `<Spinner size="lg" />`).
+
+Não é barra de progresso determinística — para isso use `Progress`.
+
+## Props essenciais
+
+| Prop | Tipo | Default | Descrição |
+|------|------|---------|-----------|
+| `size` | `"sm" \| "md" \| "lg" \| "xl" \| "2xl"` | `"md"` | Tamanho via `size-icon-*` (16/20/24/32/40px). `xl`/`2xl` são pra loading de área/página (é o que o `ScreenLoader` usa). |
+| `color` | `"current" \| "default" \| "muted" \| "brand" \| "on-brand"` | `"muted"` | Cor via `text-fg-*`. `current` herda a cor do texto do pai. |
+| `label` | `string` | `"Carregando"` | Rótulo acessível (`role="status"`). |
+| `className` | `string` | — | Overrides (o SVG é o próprio nó — aceita `ref` para `SVGSVGElement`). |
+
+Aceita qualquer prop de `<svg>` (menos `color`, sobrescrita pela variante).
+
+## Variantes
+
+| Variante | Valores |
+|----------|---------|
+| `size` | `sm` · `md` · `lg` · `xl` · `2xl` |
+| `color` | `current` · `default` · `muted` · `brand` · `on-brand` |
+
+## Exemplo mínimo
+
+```tsx
+import { Spinner } from "@snksergio/design-system";
+
+// standalone, neutro
+<Spinner />
+
+// dentro de um botão primário (herda o branco do texto do botão)
+<Button disabled>
+  <Spinner size="sm" color="current" aria-hidden />
+  Salvando…
+</Button>
+
+// destaque de marca, maior
+<Spinner size="lg" color="brand" label="Carregando ranking" />
+```
+
+## Gotchas
+
+- **Respeita `prefers-reduced-motion`**: quando o usuário pede menos movimento, a rotação para (`motion-reduce:animate-none`) — o spinner fica estático mas ainda comunica "carregando" via `role="status"`.
+- **Decorativo dentro de botões**: passe `aria-hidden` — aí o `label`/`role="status"` são omitidos (o texto do botão já anuncia o estado) e evita anúncio duplicado no leitor de tela.
+- O traço usa `currentColor`; `color="current"` é o caminho para casar com a cor do container.

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

@@ -0,0 +1,192 @@
+# Table — primitiva burra de grid
+
+`Table` é a **primitiva de baixo nível** que renderiza estrutura visual de grid: head, body, rows, cells. Sem lógica de dados. Use-a quando precisar de uma tabela leve sem o overhead do `DataTable` (smart wrapper que orquestra filtro/sort/pagination/virtualization).
+
+## Anatomia
+
+```tsx
+<Table density="standard" cellBorders ariaLabel="Lista de itens">
+  <TableHead>
+    <TableHeadCell field="id" sortable sortDirection="asc" icon={Hash} width={120}>
+      ID
+    </TableHeadCell>
+    <TableHeadCell field="name" sortable resizable width={240}>
+      Nome
+    </TableHeadCell>
+  </TableHead>
+
+  <TableBody>
+    {rows.map((row) => (
+      <TableRow key={row.id} selected={isSelected(row)} onClick={() => open(row)}>
+        <TableCell field="id" width={120}>{row.id}</TableCell>
+        <TableCell field="name" width={240} ellipsis>{row.name}</TableCell>
+      </TableRow>
+    ))}
+  </TableBody>
+</Table>
+```
+
+## Componentes
+
+| Componente | Responsabilidade |
+|---|---|
+| `Table` | Root grid container. Aceita `scrollRef` externa (pra virtualization). Expõe `cardBreakpoint?: number \| false` (default `768`) — hoje **no-op** no Table puro (ver Pattern 4). |
+| `TableHead` | Sticky row group de headers. `sticky` toggle. `rootProps` pra HTMLAttributes. |
+| `TableHeadCell` | Cell de header. `forwardRef`. Suporta sort, resize, icon, headMenu slot. |
+| `TableBody` | Row group de body. `virtualized={{ totalHeight }}` ativa modo absolute layout. |
+| `TableRow` | `forwardRef`. `selected`/`open`/`focused`/`clickable` variants. |
+| `TableCell` | `forwardRef`. Cell de dados. `purpose="selection"` remove padding (checkbox). |
+| `TableCardRow` | Modo card (mobile) — substitui TableRow inteira por card vertical. Pra auto-switch baseado em viewport, prefira `<DataTable cardBreakpoint={...}>` (faz o mapeamento automaticamente). |
+
+## Hooks expostos
+
+| Hook | Pra que serve |
+|---|---|
+| `useColumnWidths(columns)` | Calcula `widths` efetivos + `offsets` cumulativos pra colunas pinned. |
+| `useColumnResize({ currentWidth, onResize, onResizeEnd, onResizeLiveDOM })` | Drag-to-resize handle. 3 callbacks: live DOM (síncrono), onResize (mousemove), onResizeEnd (mouseup). |
+
+## Constants
+
+```ts
+import { SELECTION_COLUMN_WIDTH, TABLE_HEADER_HEIGHT } from "@/components/ui/Table";
+
+// SELECTION_COLUMN_WIDTH = 56 — usar em TableHeadCell/TableCell width
+// TABLE_HEADER_HEIGHT    = 42 — alinhar skeletons, totalizers, group headers
+```
+
+## Patterns
+
+### 1. Coluna de seleção (checkbox)
+
+```tsx
+import { SELECTION_COLUMN_WIDTH } from "@/components/ui/Table";
+
+<TableHeadCell width={SELECTION_COLUMN_WIDTH} purpose="selection">
+  <Checkbox checked={...} onCheckedChange={...} />
+</TableHeadCell>
+
+<TableCell width={SELECTION_COLUMN_WIDTH} purpose="selection">
+  <Checkbox checked={...} onCheckedChange={...} />
+</TableCell>
+```
+
+`purpose="selection"` é o **padrão pra coluna de checkbox**: remove o padding interno **e centraliza o checkbox** (header + body) automaticamente nos 56px — **não precisa** passar `align="center"`. Vale tanto no `<TableHeadCell>` quanto no `<TableCell>`. Use `width={SELECTION_COLUMN_WIDTH}` (56px) pra largura.
+
+### 2. Resize column com state externo
+
+```tsx
+const [colWidths, setColWidths] = useState<Record<string, number>>({});
+
+<TableHeadCell
+  field="name"
+  width={colWidths.name ?? 240}
+  resizable
+  // mousemove → side-effect (live DOM já é feito internamente pelo TableHeadCell)
+  onResize={(w) => console.log("dragging:", w)}
+  // mouseup → commit no state
+  onResizeEnd={(w) => setColWidths((prev) => ({ ...prev, name: w }))}
+>
+  Nome
+</TableHeadCell>
+```
+
+### 3. Virtualization (`@tanstack/react-virtual`)
+
+```tsx
+const scrollRef = useRef<HTMLDivElement | null>(null);
+const virtualizer = useVirtualizer({
+  count: rows.length,
+  getScrollElement: () => scrollRef.current,
+  estimateSize: () => 56,
+  overscan: 10,
+});
+
+<Table scrollRef={scrollRef}>
+  <TableHead>{/* ... */}</TableHead>
+  <TableBody virtualized={{ totalHeight: virtualizer.getTotalSize() }}>
+    {virtualizer.getVirtualItems().map((vi) => (
+      <TableRow
+        key={rows[vi.index].id}
+        rootProps={{
+          style: {
+            position: "absolute",
+            top: 0,
+            left: 0,
+            width: "100%",
+            height: `${vi.size}px`,
+            transform: `translateY(${vi.start}px)`,
+          },
+        }}
+      >
+        {/* cells */}
+      </TableRow>
+    ))}
+  </TableBody>
+</Table>
+```
+
+### 4. Card mode manual (TableCardRow + matchMedia)
+
+Pro `<Table>` puro, o auto-switch row→card NÃO é automático — você decide via `matchMedia` ou ResizeObserver:
+
+> ⚠️ `TableProps` expõe `cardBreakpoint?: number | false` (default `768`), mas no `<Table>` puro a prop é **no-op**: ela só escreve a CSS var `--table-card-bp` no root — nenhuma regra CSS/`@container` consome essa var hoje. Não passe `cardBreakpoint` no `<Table>` esperando card mode automático; o auto-switch real é o do `<DataTable cardBreakpoint={...}>`, implementado via JS.
+
+```tsx
+import { useMediaQuery } from "@/components/ui/MenuSidebar/use-media-query";
+import { TableCardRow } from "@/components/ui/Table";
+
+const isMobile = useMediaQuery("(max-width: 767px)");
+
+return isMobile ? (
+  <div className="flex flex-col gap-gp-md">
+    {rows.map((row) => (
+      <TableCardRow
+        key={row.id}
+        header={<strong>{row.name}</strong>}
+        items={[
+          { label: "Email", value: row.email },
+          { label: "Status", value: row.status },
+        ]}
+      />
+    ))}
+  </div>
+) : (
+  <Table>{/* ... */}</Table>
+);
+```
+
+> Pra evitar o trabalho manual, use `<DataTable cardBreakpoint={768}>` — ele mapeia automaticamente as colunas (selection + primary + actions + items) e renderiza `<TableCardRow>` abaixo do breakpoint.
+
+### 5. Sticky pinned columns
+
+```tsx
+const cols = [
+  { field: "id", width: 120, pinned: "left" as const },
+  { field: "name", width: 240, pinned: "left" as const },
+  { field: "email", width: 240 },
+];
+
+const { widths, offsets } = useColumnWidths(cols);
+
+<TableHeadCell field="id" width={widths.id} pinned="left" pinOffset={offsets.id}>
+  ID
+</TableHeadCell>
+```
+
+## Table vs DataTable — quando usar qual
+
+| Use **Table** quando | Use **DataTable** quando |
+|---|---|
+| Tabela estática sem filtros/sort/paginação | CRM/admin com filtros, sort, etc |
+| Lista simples controlada por estado próprio | Server mode ou client mode com mock |
+| Quer composição máxima manual | Quer setup rápido via prop config |
+| Tabela dentro de modal/drawer pequeno | Página inteira com toolbar + footer |
+
+## Princípio dumb
+
+`Table` **não armazena estado de dados**. Tudo é controlado externamente:
+- Selection → consumer mantém `Set<id>` e passa pra cada `TableRow`
+- Sort → consumer decide `sortDirection` por cell e implementa onClick
+- Pagination → consumer fatia rows antes de mapear
+
+O Table guarda **apenas** estado visual interno (resize hover, scroll detection) — via `TableContext` privado, nunca exposto.

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

@@ -0,0 +1,87 @@
+# TableToolbar — toolbar opinativa de tabela
+
+Toolbar **padrão** (e única) do DataTable. Layout OPINATIVO: slots semânticos em
+ordem fixa — o consumer não monta a ordem, impossível montar errado.
+
+## Quando usar
+
+- Você está montando uma toolbar de tabela custom (fora do DataTable) e quer o
+  visual/UX canônico do DS.
+- Dentro do DataTable é automático — não precisa instanciar à mão.
+
+## Ordem renderizada (fixa)
+
+```
+Esquerda:  viewToggle · ⟨divider⟩ · savedViews
+Direita:   refresh · actions · search · filter · settings · more
+```
+
+Em `< md`: o `refresh` some (o menu Configurações cobre o resto).
+
+## Slots (props)
+
+| Slot         | O que vai aqui                                                                                                                                                                  |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `viewToggle` | Toggle Kanban/Lista (`<ToolbarSegmented>`)                                                                                                                                      |
+| `savedViews` | Abas de visões + adicionar (`<TableToolbarViews>` + `<ViewsPopover>`). `<TableToolbarViews allowCreate={false}>` (v0.23.0) esconde o "+" e o modal de nova visão → só as visões pré-definidas (read-only). No DataTable use a prop `allowCreateView`. **`maxTabs`** (default `3`, **incluindo a aba "Default"**) limita quantas viram aba — o excedente é cortado por `.slice()`, sem overflow — mas em DEV sai um `console.warn` nomeando as visões engolidas e o valor que resolve (v0.43.1); no DataTable a prop equivalente é `maxViewTabs`. |
+| `refresh`    | Botão atualizar (`<ToolbarToolButton>`)                                                                                                                                         |
+| `search`     | Campo de busca (`<ToolbarSearch>`)                                                                                                                                              |
+| `filter`     | Filtro simples: use `<ToolbarFilterButton onClick isActive hasIndicator />` (funil, icon-only — **mesmo botão** no DataTable e DataList) → abre `<ToolbarSimpleFilterDrawer>`   |
+| `actions`    | Ações custom: `<ToolbarActions actions={[...]} />` (`button`/`dropdown`/`input`). Inline no desktop; **colapsam no ⋯ no mobile** (passe `extraItems` p/ absorver o ⋯ existente) |
+| `settings`   | Configurações: sliders → drill-down (`<ToolbarSettingsMenu>` com Ordenação · Colunas · Filtros avançados · Densidade)                                                           |
+| `more`       | Menu "⋯" (`<MoreMenu>`) — export + ações                                                                                                                                        |
+| `bulkBar`    | Substitui a toolbar inteira pela barra de ações em massa                                                                                                                        |
+| `className`  | —                                                                                                                                                                               |
+
+## Exemplo mínimo
+
+```tsx
+import {
+  TableToolbar,
+  ToolbarSearch,
+  ToolbarToolButton,
+  ToolbarSettingsMenu,
+  ToolbarSegmented,
+  ToolbarApplied,
+  MoreMenu,
+  SortPanel,
+  ColsPanel,
+  FilterPanel,
+} from "@/components/ui/TableToolbar";
+
+<TableToolbar
+  search={<ToolbarSearch value={q} onChange={(e) => setQ(e.target.value)} />}
+  settings={
+    <ToolbarSettingsMenu
+      trigger={<ToolbarToolButton icon={<SlidersHorizontal />} aria-label="Configurações da tabela" />}
+      sortPanel={(onBack) => <SortPanel ... onBack={onBack} />}
+      colsPanel={(onBack) => <ColsPanel ... onBack={onBack} />}
+      filterPanel={(onBack) => <FilterPanel ... onBack={onBack} />}
+      density={<ToolbarSegmented items={DENSITY} ... />}
+    />
+  }
+  more={<MoreMenu ... />}
+/>
+{/* Chips dos filtros aplicados LOGO ABAIXO */}
+<ToolbarApplied filters={appliedFilters} onRemove={...} />
+```
+
+## Gotchas
+
+- **Ordem é fixa** — não dá (nem precisa) reordenar. Cada controle tem seu slot semântico.
+- **Mobile**: o `refresh` é escondido em `< md` via `hidden md:contents`; o
+  `<ToolbarSettingsMenu>` expõe Visualização/Visões inline dentro do menu nesse breakpoint.
+- **`mobileDisplayToggle?: ReactNode`** (ToolbarSettingsMenu): slot pro toggle
+  **"Exibição" (Linhas/Cards)** — só renderiza em `< md`. O DataTable passa um
+  `<ToolbarSegmented>` aqui quando a tela cabe em card mode; permite o usuário
+  forçar tabela mesmo abaixo do `cardBreakpoint` (default mobile = **tabela**).
+- **bulkBar substitui tudo**: passe `<BulkActionsBar>` (auto-some quando `count=0`)
+  condicionalmente — `selectedIds.size > 0 ? <BulkActionsBar/> : undefined`.
+- **Chips ficam fora** da toolbar: renderize `<ToolbarApplied>` como irmão abaixo.
+
+## Acoplamento DataTable ↔ TableToolbar
+
+O DataTable consome os parts do TableToolbar via composição e orquestra os slots
+na ordem fixa. Mudar a ordem/conteúdo dos controles do DataTable é edição **no
+DataTable**, não aqui. Coupling reverso (DataTable → TableToolbar para
+`columnTypeRegistry`/`FilterModel`) é aceito; o inverso é proibido.