@snksergio/design-system 0.61.0 → 0.63.0

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

@@ -0,0 +1,128 @@
+# MenuSidebar — USAGE
+
+Sidebar composto: rail 64px (ícones de contexts) + panel 264px (items do context ativo, colapsável).
+
+## Quando usar
+- Navegação primária de app multi-context (Inbox, Clientes, Configurações, etc)
+- Dentro de `<AppShell>` (template canônico) ou standalone em apps custom
+
+## Import
+```tsx
+import { MenuSidebar } from "@/components/ui/MenuSidebar";
+```
+
+## Props essenciais
+| Prop | Tipo | Função |
+|---|---|---|
+| `contexts` | SidebarContext[] | Lista de workspaces (rail) — `{ id, label, icon, items, sections? }` |
+| `activeContextId` | string | Context ativo (controlled) |
+| `defaultActiveContextId` | string | Context inicial (uncontrolled) |
+| `onContextChange` | (id: string) => void | Callback de troca de context |
+| `activeItemHref` | string | Item ativo no panel (controlled, match por href) |
+| `defaultActiveItemHref` | string | Item ativo inicial (uncontrolled) |
+| `onItemClick` | (item, event?) => void | Callback ao clicar em item do panel. **O 2º arg é o `MouseEvent`** — use pra `preventDefault()` se você roteia na mão |
+| `renderLink` | (props) => ReactNode | ⭐ **Integração com router** — substitui o `<a>` interno pelo `<Link>` do seu router. Ver a seção abaixo |
+| `brandHref` | string | Destino do brand no rail. Default `"/"`; `""` torna não-navegável (vira `<button>`) |
+| `onBrandClick` | (e) => void | Clique no brand |
+| `panelCollapsed` | boolean | Panel colapsado — só rail visível (controlled) |
+| `defaultPanelCollapsed` | boolean | Panel colapsado inicial (uncontrolled) |
+| `onPanelCollapseChange` | (collapsed: boolean) => void | Callback do collapse |
+| `expandOnHover` | boolean (default `true`) | Com panel colapsado, hover abre o panel como overlay absoluto (não empurra conteúdo) |
+| `mobileOpen` | boolean | Drawer mobile aberto (controlled) |
+| `defaultMobileOpen` | boolean (default `false`) | Drawer mobile inicial (uncontrolled) |
+| `onMobileOpenChange` | (open: boolean) => void | Callback do drawer mobile |
+| `mobileBreakpoint` | string (default `"(max-width: 767px)"`) | Media query que ativa o modo mobile (matchMedia) |
+| `brand` | ReactNode | Logo/avatar no topo do rail |
+| `user` | ReactNode | Avatar+menu no bottom do rail |
+
+## Exemplo mínimo
+```tsx
+<MenuSidebar
+  contexts={MOCK_CONTEXTS}
+  defaultActiveContextId="inbox"
+  defaultActiveItemHref="#chat"
+  brand={<Logo />}
+  user={<UserMenu user={currentUser} />}
+/>
+```
+
+## 🧭 Integração com router — LEIA se seu app tem rotas
+
+O sidebar renderiza `<a href={item.href}>`. Sem integração, clicar num item com `href` de
+**path** (`/app/clientes`) faz o browser **recarregar a página inteira** — foi um bug real,
+reportado por consumidor em 2026-08-08 e corrigido na v0.38.0.
+
+### Recomendado: `renderLink`
+
+```tsx
+import { Link } from "react-router-dom";
+
+<MenuSidebar
+  contexts={contexts}
+  renderLink={(p) => <Link {...p} to={p.href} />}
+/>
+```
+
+| Router | `renderLink` |
+|---|---|
+| **react-router** | `(p) => <Link {...p} to={p.href} />` |
+| **Next.js** | `(p) => <Link {...p} />` (já usa `href`) |
+| **TanStack Router** | `(p) => <Link {...p} to={p.href} />` |
+
+Com `renderLink`, o sidebar **não** mexe em `preventDefault` — quem decide é o `<Link>`.
+Você ganha navegação client-side **e** mantém ctrl/cmd+clique pra abrir em nova aba.
+
+> ⚠️ **É render-prop, não `linkComponent`.** Um prop que recebe *tipo de componente* e é
+> escrito inline cria um tipo novo a cada render, e o React desmonta/remonta a subárvore —
+> perde foco, reinicia animação, e o sintoma parece aleatório. Render-prop inline é seguro.
+
+### Alternativa: `onItemClick` + `navigate()`
+
+Se preferir rotear na mão, funciona sem `renderLink` — o sidebar cancela a navegação
+nativa automaticamente quando você passa `onItemClick`:
+
+```tsx
+const navigate = useNavigate();
+<MenuSidebar contexts={contexts} onItemClick={(item) => item.href && navigate(item.href)} />
+```
+
+O 2º argumento é o evento, se você precisar dele: `onItemClick={(item, e) => { … }}`.
+
+### O que o cancelamento automático NÃO faz (de propósito)
+
+Ele **nunca** cancela nestes 5 casos, e cada um quebraria algo real:
+
+| Caso | Por que não cancela |
+|---|---|
+| ctrl/cmd/shift/alt ou botão do meio | é como o usuário abre em nova aba |
+| `target: "_blank"` no item | o item pediu outra aba |
+| `href` externo (`https:`, `mailto:`, `tel:`, `//host`) | não é rota do app; cancelar deixa o link morto |
+| **`href` de hash (`#/rota`)** | hash router escuta `hashchange`; cancelar impede o fragmento de mudar e o evento **nunca dispara** |
+| sem `onItemClick` nem `item.onClick` | ninguém trataria — o `<a>` é a navegação pretendida |
+
+A regra vive em **`@/utils/nav-link`** e é exportada (`shouldPreventNavigation`,
+`isExternalHref`, `isHashHref`, `isModifiedClick`) pra quem compõe com `<SidebarItem>`
+avulso — reimplementar na unha é como o bug volta.
+
+> ⚠️ **Mudou de lugar em 2026-08-18**: era `MenuSidebar/nav-link.ts`, virou
+> `src/utils/nav-link.ts`. O `SingleMenuSidebar` passou a precisar da MESMA regra, e as
+> alternativas eram piores: duplicar cria duas cópias divergindo, e importar do MenuSidebar
+> faria o `single-menu-sidebar` depender do item de registry do MenuSidebar **inteiro** por
+> 60 linhas puras. Agora é util compartilhada, embutida como `registry:file` nos dois itens
+> — mesmo padrão do `@/utils/color-contrast`.
+>
+> **O re-export por `@/components/ui/MenuSidebar` continua valendo**, então quem importava
+> daqui não muda nada. Só quem fazia deep-import do arquivo (`.../MenuSidebar/nav-link`)
+> precisa apontar pro caminho novo.
+
+> **Por que passou meses invisível:** o exemplo canônico
+> (`src/examples/app-shell/nav-data.ts`) usa `href` de **hash** em todos os itens, e hash
+> não recarrega documento. Showcase verde, consumidor quebrado.
+
+## Cuidados / Gotchas
+- `w-fit` no root é crítico — sem isso o hover-to-expand dispararia em qualquer lugar do parent
+- Mobile é auto-detectado via `mobileBreakpoint` (matchMedia) — NÃO existe prop `mobile`. Vira drawer fixed overlay (translate-x lateral); backdrop scrim e botão de fechar (X) são renderizados automaticamente pelo próprio MenuSidebar. Consumer só controla `mobileOpen` (ex: hamburger no header)
+- `floating` NÃO é prop pública do MenuSidebar — é prop interna de `<SidebarPanel>` (composição manual). No all-in-one, o overlay flutuante é gerenciado por `expandOnHover` + panel colapsado
+- Items hierárquicos: `items: [{ name, href, subitems: [...] }]` — subitems renderizam indentados; `defaultOpen` define o estado inicial do grupo
+- Context pode ter `sections?: SidebarSection[]` (variants `bookmark` | `chat`) renderizadas abaixo dos items do panel
+- Bookmark item aceita `icon?` opcional: presente → ícone colorido (tingido com `color`, sem fundo; estilo atalho, ex.: ferramentas/integrações); ausente → dot redondo. `color` vale pra ambos. `onAdd?` na section renderiza o botão "+" no header (ex.: abrir catálogo)

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

@@ -0,0 +1,53 @@
+# MessageAck — USAGE
+
+Glifo de status/ack de mensagem (estilo WhatsApp/Baileys) — ícone + cor semântica derivados do valor de `ack`. Componente composto / atômico de chat.
+
+## Quando usar
+- Indicar entrega/leitura de mensagens enviadas (bolha de chat)
+- Rodapé da bolha, ao lado do timestamp
+- Estado de erro de envio (com `error`)
+
+## Import
+```tsx
+import { MessageAck } from "@/components/ui/MessageAck";
+```
+
+## Props essenciais
+| Prop | Tipo | Default | Função |
+|---|---|---|---|
+| `ack` | `0 \| 1 \| 2 \| 3 \| 4 \| 5` | — (obrigatória) | Estado de entrega da mensagem |
+| `error` | boolean | `false` | Sobrepõe o ack e mostra glifo de erro |
+| `className` | string | — | Classes extras no ícone |
+
+## Mapa ack → ícone + cor
+| ack | Significado | Ícone | Cor |
+|---|---|---|---|
+| 0 / 1 | Pendente / enviando | Clock | `fg-muted` |
+| 2 | Enviado ao servidor | Check | `fg-muted` |
+| 3 | Entregue | CheckCheck | `fg-muted` |
+| 4 / 5 | Lido / reproduzido | CheckCheck | `fg-success` |
+| — (error) | Falha no envio | AlertCircle | `fg-danger` |
+
+## Exemplo mínimo
+```tsx
+// Mensagem entregue
+<MessageAck ack={3} />
+
+// Mensagem lida (duplo check verde)
+<MessageAck ack={4} />
+
+// Falha no envio
+<MessageAck ack={1} error />
+
+// No rodapé da bolha, junto ao timestamp
+<span className="inline-flex items-center gap-gp-xs text-fg-muted">
+  10:42
+  <MessageAck ack={message.ack} error={message.failed} />
+</span>
+```
+
+## Cuidados / Gotchas
+- Ícone é `size-icon-xs` fixo — para outro tamanho, passar `className` (override de `size-*`).
+- Decorativo por padrão (`aria-hidden`) — o status é comunicado pelo timestamp/contexto da bolha; não duplica leitura no screen reader.
+- `error` tem precedência sobre `ack` (qualquer ack + error = AlertCircle danger).
+- Cores claro/escuro resolvidas via tokens (`fg-muted`/`fg-success`/`fg-danger`) — não passar cor inline.

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

@@ -0,0 +1,115 @@
+# MessageBubble
+
+**Categoria:** composto (MessageAck + MarkdownText + Icon + Button + Popover + slot Avatar). Bolha de mensagem do **atendimento / chat WhatsApp** — o maior bloco do ChatV2.
+
+## Quando usar
+
+- Renderizar uma mensagem dentro de uma timeline de conversa (enviada ou recebida).
+- Suporta texto markdown WA, mídia (imagem/áudio/vídeo/documento/localização/contato), citação (reply), edição, exclusão, status de entrega e ações por hover.
+
+Não use para notificações de sistema, separadores de data ou logs de chamada — esses são blocos próprios.
+
+## Anatomia
+
+```
+[avatar]  ┌───────────────────────────────┐   ← side="received" (esquerda, bg-surface + border-subtle)
+          │ Autor (grupos)            ⋮   │   ← ⋮ = actions (Popover, hover top-right)
+          │ ▏ citação (reply) ............│   ← quotedMessage (border-l + nome + prévia)
+          │ [ mídia / MessageMediaRenderer]│
+          │ corpo markdown WA             │
+          │            editada · HH:mm ✓✓ │   ← meta: editada? + hora + MessageAck (só sent)
+          └───────────────────────────────┘
+                  ┌──────────────────┐  [avatar] ← side="sent" (direita, bg-success-muted)
+                  │ ...              │
+                  └──────────────────┘
+```
+
+## Props essenciais
+
+| Prop | Tipo | Default | Descrição |
+|------|------|---------|-----------|
+| `side` | `"sent" \| "received"` | — | **Obrigatório.** `sent` = direita (bg verde sutil) · `received` = esquerda (bg surface). |
+| `createdAt` | `string \| Date` | — | **Obrigatório.** Formatada como `HH:mm` (24h). |
+| `body` | `string` | — | Corpo em markdown WA → `MarkdownText`. |
+| `ack` | `0..5` | — | Status de entrega → `MessageAck`. **Só aparece em `side="sent"`.** |
+| `ackError` | `boolean` | `false` | Sobrepõe o `ack` com o glifo de erro de envio (encaminha `error` ao `MessageAck`). Só junto de `ack` em `side="sent"`. |
+| `mediaType` | `text \| image \| audio \| video \| document \| location \| vcard \| contact` | `"text"` | Tipo de mídia (switch interno). |
+| `mediaUrl` | `string` | — | URL da mídia (usada pelo renderer interno). |
+| `media` | `ReactNode` | — | Slot — **override completo** do renderer interno. |
+| `quotedMessage` | `{ authorName?, fromMe?, body?, mediaType?, mediaUrl? } \| null` | — | Citação/reply (barra lateral + prévia truncada). |
+| `isEdited` | `boolean` | `false` | Adiciona label `editada` no rodapé. |
+| `isDeleted` | `boolean` | `false` | Itálico mudo + ícone proibido; **suprime corpo, mídia e ações**. |
+| `tail` | `boolean` | `true` | Rabeta (canto reto) no lado do remetente. |
+| `origin` | `"human" \| "ai"` | `"human"` | `ai` = contorno sutil da marca na bolha (resposta da IA/Sol). **Quem decide é o consumidor**; `human` não muda nada. |
+| `authorName` | `string` | — | Nome no topo (útil em grupos). |
+| `avatar` | `ReactNode` | — | Slot de avatar ao lado da bolha. |
+| `actions` | `ReactNode` | — | Conteúdo do Popover de ações (botão ⋮ aparece no hover). |
+| `onMediaClick` | `() => void` | — | Clique na mídia (ex: abrir lightbox). |
+| `className` | `string` | — | className da linha inteira. |
+
+## Variants
+
+| Variant | Valores | Efeito |
+|---------|---------|--------|
+| `side` | `sent` · `received` | bg da bolha + alinhamento + lado da rabeta + lado do ack |
+| `tail` | `true` · `false` | canto reto (`rounded-br-none`/`rounded-bl-none`) vs todos arredondados |
+| `origin` | `human` · `ai` | `ai` troca a borda da bolha por `border-border-brand-subtle` (contorno sutil da marca, nos dois lados); `human` = borda padrão |
+
+`disabled` = n/a (bolha não é controle interativo).
+
+## Exemplo mínimo
+
+```tsx
+import { MessageBubble, MessageReplyIcon } from "@snksergio/design-system";
+
+<MessageBubble
+  side="received"
+  authorName="Maria"
+  avatar={<Avatar name="Maria" size="sm" />}
+  body="Olá! *Tudo certo* com o pedido?"
+  createdAt="2026-06-22T14:32:00Z"
+/>
+
+<MessageBubble
+  side="sent"
+  body="Sim, já está a caminho 🚚"
+  createdAt={new Date()}
+  ack={3}
+  isEdited
+  actions={<button onClick={onReply}><MessageReplyIcon /> Responder</button>}
+/>
+
+<MessageBubble
+  side="received"
+  mediaType="image"
+  mediaUrl="/uploads/nota.jpg"
+  body="Comprovante"
+  createdAt="14:40"
+  onMediaClick={() => openLightbox("/uploads/nota.jpg")}
+  quotedMessage={{ authorName: "João", body: "Pode mandar o comprovante?" }}
+/>
+
+<MessageBubble
+  side="sent"
+  origin="ai"
+  body="Oi! Sou a Sol. Posso ajudar com a sua fatura?"
+  createdAt={new Date()}
+  ack={3}
+  actions={<button onClick={onReply}><MessageReplyIcon /> Responder</button>}
+/>
+```
+
+## Gotchas
+
+- **`max-w-[70%]` é exceção de hardcode documentada** — não há token DS de porcentagem para largura de balão de chat; a coluna da bolha limita a 70% da linha por regra do domínio. Todo o resto é token DS.
+- **Ack só em `sent`:** `MessageAck` nunca aparece em mensagens recebidas (regra WA), mesmo se `ack` for passado. `ackError` (encaminhado como `error` ao `MessageAck`) troca o glifo pelo ícone de erro de envio.
+- **Mídia clicável é acessível por teclado:** quando `onMediaClick` é passado, a imagem/vídeo recebe `role="button"` + `tabIndex={0}` + ativação por Enter/Space e anel de foco DS. Sem `onMediaClick`, a mídia não é focável (apenas exibição).
+- **Documento: o CARD INTEIRO é o alvo do clique**, não um ícone na borda. Com `onMediaClick` o card vira `<button>` (teclado e leitor de tela de graça) e o ícone de baixar é só decoração — botão dentro de botão seria HTML inválido. Sem `onMediaClick` ele fica inerte e o rótulo passa de "Toque para abrir" para "Documento recebido": componente dumb não promete gesto que ninguém ligou. Até 2026-08-20 só o ícone de ~16px tinha clique, e em coluna estreita ele fica fora da área visível — o card ensinava um gesto que não existia.
+- **`isDeleted` vence tudo:** suprime corpo, mídia, citação e ações — só mostra "Mensagem apagada" em itálico mudo com ícone de proibido.
+- **`media` slot = override:** quando passado, substitui o `MessageMediaRenderer` interno por completo (use para players custom, mapas embedados, etc).
+- **Citação inline:** a prévia da citação usa `<MarkdownText inline>` (1 linha, truncável). Sem body, mostra o rótulo do tipo de mídia ("Imagem", "Áudio"…).
+- **Ações via Popover não-modal:** o botão ⋮ usa `PopoverAnchor` (não Trigger) + `modal={false}` (L-022/L-031) para o toggle externo não conflitar com o hover; aparece no `group-hover` da bolha (e no foco por teclado).
+- **O botão ⋮ tem superfície própria** (`bg-bg-emphasis` em pílula + `shadow-sh-sm`, glifo de 16px via `size="icon-xs"`). Sem isso ele sumia no tema escuro: bolha recebida (`bg-bg-surface`) e fundo da conversa têm quase a mesma luminância, e o ghost secundário só tinha `hover:bg-bg-muted` (3% de branco). Pelo mesmo motivo a bolha recebida tem `border-border-subtle` em vez de borda transparente.
+- **`origin="ai"` é só a variante:** o componente não sabe quem escreveu. O consumidor aplica o mesmo critério que já usa para ligar `actions` só às mensagens da IA.
+- **Subcomponente `MessageMediaRenderer` é interno** — não exportado. Consuma só via `MessageBubble`.
+```

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

@@ -0,0 +1,80 @@
+# MessageComposer
+
+**Categoria:** composto (chat / atendimento). Compõe `Textarea` + `Button` + `Icon` + `Separator`.
+
+Shell DUMB (sem lógica de API/upload/emoji/áudio) da barra de envio de mensagem,
+usado no Atendimento e no Chat interno. Só a moldura + slots; o consumer pluga
+emoji, anexo, mic, quick-messages, gravação, etc.
+
+## Quando usar
+
+- Caixa de digitação de qualquer conversa (ticket WhatsApp, chat interno).
+- Sempre que precisar de textarea auto-grow + botão de envio + slots de toolbar,
+  citação e aviso, sem reimplementar a moldura.
+
+## Props essenciais
+
+| Prop | Tipo | Default | Descrição |
+|------|------|---------|-----------|
+| `value` | `string` | — (req) | Texto controlado da mensagem. |
+| `onChange` | `(v: string) => void` | — (req) | Disparado a cada digitação. |
+| `onSend` | `() => void` | — (req) | Enter (sem Shift) ou clique no botão. Só dispara com texto e fora de disabled/sending. |
+| `onKeyDown` | `(e) => void` | — | Roda ANTES do Enter→onSend interno; `e.preventDefault()` suprime o envio padrão. |
+| `placeholder` | `string` | — | Placeholder da textarea (também vira `aria-label`). |
+| `state` | `'open' \| 'disabled' \| 'read-only'` | `'open'` | `read-only` esconde o campo e mostra só o `banner`. |
+| `size` | `'sm' \| 'md'` | `'md'` | Padding/altura do field e da textarea. |
+| `toolbarStart` | `ReactNode` | — | Slot à esquerda (emoji/anexo). |
+| `toolbarEnd` | `ReactNode` | — | Slot à direita, antes do envio (mic/extra). |
+| `replyPreview` | `ReactNode` | — | Barra de citação acima da textarea. |
+| `banner` | `ReactNode` | — | Aviso acima do campo (janela 24h / read-only). |
+| `sending` | `boolean` | `false` | Botão de envio em loading + bloqueado. |
+| `recording` | `ReactNode` | — | SUBSTITUI a textarea enquanto grava (waveform/timer). |
+| `className` | `string` | — | className do container. |
+
+`ref` é encaminhado para a `<textarea>` interna (foco programático).
+
+## Variants
+
+| Variant | Valores | Efeito |
+|---------|---------|--------|
+| `state` | open · disabled · read-only | editável · bloqueado · sem campo (só banner) |
+| `size` | sm · md | altura/padding compacto · padrão |
+
+## Exemplo mínimo
+
+```tsx
+import { MessageComposer } from "@/components/ui/MessageComposer";
+import { Button } from "@/components/ui/Button";
+import { Icon } from "@/components/ui/Icon";
+
+const [text, setText] = useState("");
+
+<MessageComposer
+  value={text}
+  onChange={setText}
+  onSend={() => {
+    sendMessage(text);
+    setText("");
+  }}
+  placeholder="Digite uma mensagem..."
+  toolbarStart={
+    <Button variant="ghost" color="secondary" size="icon-sm" aria-label="Anexar">
+      <Icon name="line-file-attachment" />
+    </Button>
+  }
+/>
+```
+
+## Gotchas / cuidados
+
+- **DUMB por design:** emoji picker, upload, gravação de áudio e quick-messages são
+  responsabilidade do consumer (slots). O composer não tem estado de negócio.
+- **Enter→onSend** é embutido. Para desabilitar (ex.: textarea multiline puro), trate
+  no `onKeyDown` e chame `e.preventDefault()`.
+- **Auto-grow** cresce até um teto (`max-h` interno) e então rola; a altura é
+  recalculada via `useLayoutEffect` a cada mudança de `value`. Componentes controlados.
+- **Botão de envio** usa o ícone `line-telegram` e só habilita com `value.trim()`.
+  Em `sending` entra em loading e bloqueia.
+- **`recording`** remove a textarea E o botão de envio padrão — o consumer controla as
+  ações de gravação dentro desse slot (cancelar/enviar áudio).
+- Ícone de anexo/emoji/mic não vem embutido: passe Buttons ghost com `Icon` nos slots.

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

@@ -0,0 +1,104 @@
+# MessageVariablesPicker
+
+**Categoria:** composto (ui/) — picker de variáveis de mensagem.
+
+Picker de variáveis `{{...}}` que emite `onSelect(token)`. Composto a partir de `Popover` (mobileSheet), `Button`, `Chip`, `Icon` e `Separator` do DS.
+
+> ⚠️ **Não contém o textarea.** O componente só dispara `onSelect(token)` — quem insere o token no cursor é o consumer (campo de texto/editor).
+
+---
+
+## Quando usar
+
+- Editores de mensagem (quick messages, campanhas, respostas automáticas) onde o usuário precisa inserir variáveis dinâmicas (`{{firstName}}`, `{{protocol}}`, etc).
+- Ao lado/dentro da toolbar de um `<textarea>` — o trigger só-ícone cabe numa barra de ações.
+
+---
+
+## Props essenciais
+
+| Prop | Tipo | Default | Descrição |
+|------|------|---------|-----------|
+| `onSelect` | `(token: string) => void` | — (req) | Recebe o token escolhido. O consumer insere no cursor. |
+| `variables` | `MessageVariable[]` | `DEFAULT_MESSAGE_VARIABLES` | Lista exibida (`{ token, label }`). |
+| `label` | `string` | `"Variáveis"` | Rótulo do trigger (`triggerVariant="button"`). |
+| `triggerVariant` | `"icon" \| "button"` | `"icon"` | `icon` = só-ícone (glyph chaves) · `button` = ícone + label. |
+| `open` / `onOpenChange` | `boolean` / `(o)=>void` | — | Controle externo de abertura (opcional). |
+| `closeOnSelect` | `boolean` | `true` | Fecha o popover ao selecionar. |
+| `size` | `"sm" \| "md"` | `"sm"` | Tamanho do trigger e largura mínima do conteúdo. |
+| `disabled` | `boolean` | — | Desabilita o trigger. |
+| `className` | `string` | — | Classe extra no trigger. |
+
+### `MessageVariable`
+
+```ts
+type MessageVariable = { token: string; label: string };
+```
+
+### `DEFAULT_MESSAGE_VARIABLES`
+
+```ts
+[
+  { token: "{{firstName}}", label: "Primeiro Nome" },
+  { token: "{{name}} ",     label: "Nome" },
+  { token: "{{ms}} ",       label: "Saudação" },
+  { token: "{{protocol}} ", label: "Protocolo" },
+  { token: "{{hora}} ",     label: "Hora" },
+]
+```
+
+> Os trailing spaces são **propositais** (token concatenado direto no texto) — todos têm espaço final **exceto** `{{firstName}}`.
+
+---
+
+## Variants
+
+| Variant | Valores | Default |
+|---------|---------|---------|
+| `triggerVariant` | `icon`, `button` | `icon` |
+| `size` | `sm`, `md` | `sm` |
+
+---
+
+## Exemplo mínimo
+
+```tsx
+import { MessageVariablesPicker } from "@/components/ui/MessageVariablesPicker";
+
+function MessageEditor() {
+  const ref = useRef<HTMLTextAreaElement>(null);
+
+  function insertAtCursor(token: string) {
+    const el = ref.current;
+    if (!el) return;
+    const { selectionStart: s, selectionEnd: e, value } = el;
+    el.value = value.slice(0, s) + token + value.slice(e);
+    const pos = s + token.length;
+    el.setSelectionRange(pos, pos);
+    el.focus();
+  }
+
+  return (
+    <div className="flex items-end gap-gp-sm">
+      <textarea ref={ref} />
+      <MessageVariablesPicker onSelect={insertAtCursor} />
+    </div>
+  );
+}
+```
+
+Variante com label:
+
+```tsx
+<MessageVariablesPicker triggerVariant="button" onSelect={insertAtCursor} />
+```
+
+---
+
+## Gotchas / cuidados
+
+- **Sem textarea embutido.** O componente só emite `onSelect`. Se você não inserir no cursor, nada acontece visualmente no campo.
+- **Foco do textarea.** Os Chips usam `onMouseDown` + `preventDefault()` para não roubar o foco do campo antes do clique — preserve isso ao customizar.
+- **Trailing spaces.** Não normalize os tokens de `DEFAULT_MESSAGE_VARIABLES`; o espaço final é parte do contrato.
+- **A11y.** Trigger só-ícone tem `aria-label="Inserir variável"` + `aria-haspopup="dialog"`; cada Chip tem `aria-label="Inserir <label>"`.
+- **Mobile.** Em telas `<md` o popover vira bottom-sheet (via `mobileSheet` do Popover).

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

@@ -0,0 +1,88 @@
+# Modal — USAGE
+
+<!-- ds:regras
+- aba dentro dele → `<Tabs fullWidth>` até o size `lg`; no `xl` (1100px) use hug
+- ação destrutiva → `AlertModal`, não confirmação montada na mão
+-->
+
+Dialog modal centrado com header (icon + title + description), body livre via `children` e footer estruturado por props de action (até 3 botões) — não há subcomponentes de composição.
+
+## Quando usar
+- Confirmação ou input que **interrompe** o fluxo (ex: editar dados, formulário curto)
+- Ação destrutiva → preferir `<AlertModal>` (mais explícito sobre tone)
+- Side-drawer → preferir `<Panel>` ou `<FloatingPanel>`
+
+## Import
+```tsx
+import { Modal } from "@/components/ui/Modal";
+// types: import type { ModalProps, ModalAction, ModalSize } from "@/components/ui/Modal";
+```
+
+## Variants
+| Variant | Valores | Default | Tamanho |
+|---|---|---|---|
+| `size` | sm / md / lg / xl / full | md | 440 / 540 / 720 / 1100px / min(1400px, 92vw) max-width |
+
+O layout do footer NÃO é prop: com `tertiaryAction` presente o footer vira
+`justify-between` (tertiary à esquerda, secondary+primary à direita);
+sem tertiary, tudo fica à direita (`justify-end`).
+
+## Props essenciais
+| Prop | Tipo | Default | Função |
+|---|---|---|---|
+| `open` | boolean | — | Controlled open (obrigatória) |
+| `onClose` | () => void | — | Callback quando o modal pede pra fechar — X, ESC, overlay click ou ação (obrigatória) |
+| `title` | ReactNode | — | Header title |
+| `description` | ReactNode | — | Header subtitle (opcional) |
+| `icon` | ReactNode | — | Icon decorativo no header (container 40×40) |
+| `children` | ReactNode | — | Conteúdo do body (flex-col, gap 18px) |
+| `primaryAction` | ModalAction | — | Botão filled à direita (critical quando `danger: true`) |
+| `secondaryAction` | ModalAction | — | Botão outline secondary. `onClick` default = `onClose` |
+| `tertiaryAction` | ModalAction | — | Botão ghost à ESQUERDA (ativa justify-between). Ghost critical quando `danger: true` |
+| `footer` | ReactNode | — | Escape hatch — substitui inteiramente as 3 actions estruturadas |
+| `size` | "sm" \| "md" \| "lg" \| "xl" \| "full" | "md" | Largura máxima (xl = 1100px p/ modais de dados; full = min(1400px, 92vw)) |
+| `hideClose` | boolean | false | Esconde o X de fechar |
+| `closeOnOverlay` | boolean | true | Click no overlay fecha o modal |
+
+Shape de `ModalAction`:
+```ts
+type ModalAction = {
+  label: ReactNode;
+  onClick?: () => void;
+  disabled?: boolean;
+  loading?: boolean;
+  danger?: boolean; // pinta o botão com cor critical (destrutivo)
+};
+```
+
+## Exemplo mínimo
+```tsx
+<Modal
+  open={open}
+  onClose={() => setOpen(false)}
+  size="md"
+  title="Editar cliente"
+  description="Alterações são salvas automaticamente"
+  primaryAction={{ label: "Salvar", onClick: handleSave }}
+  secondaryAction={{ label: "Cancelar" }}
+>
+  <FormFields />
+</Modal>
+```
+
+## Cuidados / Gotchas
+- **Aba dentro do Modal** → `<Tabs fullWidth>` com a variante **default** (`segmented`) até o size `lg` (720px). No `xl` (1100px) **não** use `fullWidth`: cada aba fica enorme e o grupo passa a ler como barra de segmented control, não como aba.
+
+- Footer aparece só quando há `footer` OU alguma action estruturada — sem nada disso, o modal não renderiza footer
+- `tertiaryAction` à esquerda é o padrão pra ações destrutivas (ex: "Deletar") ou neutras (ajuda); o grupo cancel/save fica à direita
+- **Body scrolla sozinho — não faça na mão.** O painel tem teto de altura
+  (`max-h-[calc(100dvh-32px)]`, `dvh` por causa da barra do navegador no mobile) e o body é
+  `min-h-0 flex-1 overflow-y-auto`. Conteúdo longo (form grande, lista) rola dentro do
+  modal, com header e footer fixos. O `min-h-0` é o que permite o flex item encolher — sem
+  ele o `overflow-y-auto` não tem efeito nenhum e o conteúdo empurra o container pra fora
+  da tela. Não replique altura/scroll no `children`: vira scroll duplo.
+  <br>Até v0.30.0 o body **não** scrollava (`overflow-hidden` clipava e não se chegava aos
+  botões do footer num form longo); corrigido em v0.30.1.
+- `closeOnOverlay={false}` ignora fechamento por overlay E por ESC (Radix dispara o mesmo callback) — pra prevenção fina, controle externamente
+- Render via portal — escapa de overflow/transform ancestrais
+- Pra confirmação destrutiva, use `<AlertModal>` (tem `tone="danger"` semântico)

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

@@ -0,0 +1,49 @@
+# MonthYearPicker
+
+**Categoria:** composto (Popover + grade de meses). Seletor de período **mês+ano**.
+
+## Quando usar
+
+- Filtro de período por competência mensal (ex.: "Ranking Verticais" por mês), relatórios mensais, faturas.
+- Quando um `calendar` de dia é granular demais — você só quer `mês/ano`.
+
+O valor é sempre `"YYYY-MM"` (ex.: `"2026-07"`).
+
+## Props essenciais
+
+| Prop | Tipo | Default | Descrição |
+|------|------|---------|-----------|
+| `value` | `string` (`"YYYY-MM"`) | — | Período selecionado (controlado). |
+| `onValueChange` | `(value: string) => void` | — | Recebe `"YYYY-MM"` ao escolher um mês. |
+| `placeholder` | `ReactNode` | `"Selecione o mês"` | Texto do trigger vazio. |
+| `min` / `max` | `string` (`"YYYY-MM"`) | — | Faixa selecionável (inclusive). Fora dela, meses ficam desabilitados. |
+| `locale` | `string` | `"pt-BR"` | Locale dos rótulos de mês (via `Intl`). |
+| `align` | `"start" \| "center" \| "end"` | `"start"` | Alinhamento do dropdown. |
+| `open` / `defaultOpen` / `onOpenChange` | — | — | Controle de abertura (igual a um Select). |
+| `disabled` | `boolean` | — | Desabilita o trigger. |
+| `className` | `string` | — | Estiliza o **trigger** (aceita os mesmos overrides de um `SelectTrigger`). |
+| `contentClassName` | `string` | — | Estiliza o **dropdown**. |
+
+## Exemplo mínimo
+
+```tsx
+import { MonthYearPicker } from "@snksergio/design-system";
+
+const [periodo, setPeriodo] = useState("2026-07");
+
+<MonthYearPicker
+  value={periodo}
+  onValueChange={setPeriodo}
+  min="2023-01"
+  max="2026-12"
+  aria-label="Período do ranking"
+/>
+// trigger mostra "Julho de 2026"; abre grade Jan…Dez com ‹ 2026 ›
+```
+
+## Gotchas
+
+- **Formato fixo `"YYYY-MM"`** — mês com zero à esquerda (`"2026-01"`, não `"2026-1"`). Valores fora desse formato são tratados como "nada selecionado".
+- O trigger espelha o `SelectTrigger` (mesma altura/borda/foco). Para parear com Selects irmãos num form, passe o mesmo `className`.
+- Rótulos vêm do `Intl` no `locale`: pt-BR gera "Jan", "Fev"… e "Julho de 2026" no trigger (primeira letra capitalizada pelo componente).
+- Navegação de ano (`‹`/`›`) só desabilita quando o ano inteiro cai fora de `[min, max]`; dentro do ano, meses individuais é que desabilitam.