@snksergio/design-system 0.61.0 → 0.63.0

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

@@ -0,0 +1,129 @@
+# PageHeader — USAGE
+
+Bloco de título reutilizável renderizado dentro do body do `<AppShell>`. Cobre o pattern comum de "header de página" do CRM iGreen: **título + descrição + badge + actions**, com slot opcional pra conteúdo extra abaixo (tabs, filtros).
+
+## Quando usar
+- Páginas listagem (CRUD, dashboards) que precisam de título + CTA principal
+- Páginas com tabs/filtros abaixo do header
+- Qualquer tela que reaproveite a estrutura "title/description/badge + actions"
+
+Quando **não** usar:
+- Telas chat-like (ChatV2/ChatShowcase) — o header global do AppShell já basta
+- Detail pages onde o header é parte de um card/drawer (use composição direta)
+
+## Import
+```tsx
+import { PageHeader } from "@/components/ui/PageHeader";
+```
+
+## Props essenciais
+
+| Prop | Tipo | Default | Função |
+|---|---|---|---|
+| `title` | string | — | Título h1 (text-title-lg) |
+| `description` | string | — | Sub-linha (text-body-md fg-subtle) |
+| `badge` | ReactNode | — | Inline ao lado do title (geralmente `<Chip>`) |
+| `actions` | ReactNode | — | Bloco de ações à direita (Buttons, dropdowns) |
+| `children` | ReactNode | — | Conteúdo extra abaixo (tabs, filtros) |
+| `hideTextOnMobile` | boolean | `true` | Em mobile (<md), esconde title/description/badge |
+| `fluidPrimaryOnMobile` | boolean | `true` | Em mobile, último filho do `actions` vira fluid (full-width CTA) |
+| `className` | string | — | className extra no `<header>` root |
+
+## Exemplos
+
+### Mínimo (só título)
+```tsx
+<PageHeader title="Configurações" />
+```
+
+### Pattern CRUD (replica o header da página de Clientes)
+```tsx
+<PageHeader
+  title="Clientes"
+  description="Gerencie sua base de clientes, acompanhe status e abra atendimentos pelo WhatsApp."
+  badge={
+    <Chip color="primary" variant="soft" size="sm" shape="rounded">
+      87 registros
+    </Chip>
+  }
+  actions={
+    <>
+      <Button variant="outline" color="secondary" size="icon-md" aria-label="Mais ações">
+        <MoreHorizontal />
+      </Button>
+      <Button variant="filled" color="primary" iconLeft={<Plus />}>
+        Novo cliente
+      </Button>
+    </>
+  }
+/>
+```
+
+### Com tabs abaixo do header
+```tsx
+<PageHeader
+  title="Relatórios"
+  description="Análise consolidada de vendas e leads."
+  actions={<Button>Exportar</Button>}
+>
+  <Tabs value={tab} onValueChange={setTab}>
+    <TabsList>
+      <TabsTrigger value="day">Hoje</TabsTrigger>
+      <TabsTrigger value="week">Semana</TabsTrigger>
+      <TabsTrigger value="month">Mês</TabsTrigger>
+    </TabsList>
+  </Tabs>
+</PageHeader>
+```
+
+### Mantendo título visível no mobile
+```tsx
+<PageHeader
+  title="Termos de uso"
+  description="Última atualização: jan/2026"
+  hideTextOnMobile={false}
+/>
+```
+
+### Sem actions, só conteúdo
+```tsx
+<PageHeader title="FAQ">
+  <SearchBar />
+</PageHeader>
+```
+
+## Cuidados / Gotchas
+
+- **`title` é renderizado como `<h1>`** — use **apenas um** `<PageHeader>` com title por página (semântica HTML).
+- **Mobile fluid** assume que o último filho do `actions` é o CTA primary. Se a ordem for diferente, desligue via `fluidPrimaryOnMobile={false}` e controle manualmente.
+- **`description` truncate em 1 linha** (`whitespace-nowrap overflow-hidden text-ellipsis`) — pra descrições longas, considere usar o slot `children` em vez disso.
+- **Body do AppShell** já aplica `gap-gp-4xl` entre filhos diretos. Não envolva o `<PageHeader>` num wrapper extra — coloque direto como filho do `<AppShell>`.
+
+## Anatomia
+
+```
+<PageHeader> (header.flex-col.gap-gp-md)
+├─ topRow (flex.justify-between.gap-gp-2xl)
+│  ├─ textCol [optional]   (flex-col.gap-gp-xs.flex-1)
+│  │  ├─ titleRow (flex.gap-gp-md)
+│  │  │  ├─ <h1 title>
+│  │  │  └─ {badge}
+│  │  └─ <p description>
+│  └─ actionsRow [optional]   (flex.gap-gp-sm)
+│     └─ {actions}
+└─ extraRow [optional — children]   (w-full)
+```
+
+## Composição manual
+
+Pra layouts que fogem do pattern (ex: title centralizado, ações em coluna), use os slots de styles direto:
+
+```tsx
+import { pageHeaderStyles } from "@/components/ui/PageHeader";
+
+const s = pageHeaderStyles();
+
+<header className={s.root()}>
+  {/* sua estrutura custom */}
+</header>
+```

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

@@ -0,0 +1,84 @@
+# Panel — USAGE
+
+<!-- ds:regras
+- painel de DETALHE → siga o bloco `dsgreen-paneldetail-1` (o **padrão**). `-2` (tarefa com abas) e `-3` (com tabela) só se o usuário citar o ID
+- header aqui é só STRING (`title`/`description`): precisa de avatar, Chip de status ou ação de ícone? → `FloatingPanel`
+- form dentro dele → `<FormField>` + `gap-form-gap`, nunca `<label>` cru
+- aba dentro dele → `<Tabs fullWidth>` na variante default (560px é estreito pro `line`)
+-->
+
+Drawer flutuante lateral (right/left/top/bottom) — default `md` (560px) com header + body scrollável + footer sticky.
+
+## Quando usar
+- Detail/edit panel que precisa de mais espaço que `<Modal>`
+- Forms longos com seções (preferível a Modal large)
+- Quando user precisa ver conteúdo ao lado enquanto interage
+
+## Import
+```tsx
+import { Panel } from "@/components/ui/Panel";
+
+// Composição manual (avançado): PanelRoot, PanelTrigger, PanelContent,
+// PanelHeader, PanelBody, PanelFooter, PanelCloseAction
+```
+
+## Variants
+| Variant | Valores | Default | Tamanho |
+|---|---|---|---|
+| `side` | right / left / top / bottom | right | right/left: largura via `size`, altura full (gutter 24px); top/bottom: largura via inset, altura conforme conteúdo |
+| `size` | sm / md / lg / xl / full \| string CSS | md | 320 / 560 / 720 / 920px / full (viewport − gutter). Aceita CSS arbitrário: `"720px"`, `"60vw"` |
+
+## Props essenciais
+| Prop | Tipo | Função |
+|---|---|---|
+| `open` | boolean | Visibilidade (controlled) |
+| `onOpenChange` | (open: boolean) => void | Callback de abertura/fechamento (o X do header fecha por aqui) |
+| `trigger` | ReactNode | Elemento que abre o panel sem state externo (vira `<SheetTrigger asChild>`) |
+| `side` | "right" \| "left" \| "top" \| "bottom" | Lado de ancoragem (default: "right") |
+| `size` | "sm" \| "md" \| "lg" \| "xl" \| "full" \| string | Largura (default: "md" = 560px) |
+| `title` | string | Header title |
+| `description` | string | Header subtitle |
+| `titleIcon` | LucideIcon | Ícone à esquerda do título (cor brand) |
+| `footer` | ReactNode | Footer sticky — geralmente botões de ação (único caminho pro footer no modo all-in-one) |
+
+## Exemplo mínimo
+```tsx
+<Panel
+  open={panelOpen}
+  onOpenChange={setPanelOpen}
+  side="right"
+  title="Editar cliente"
+  description="Salvo automaticamente"
+  footer={
+    <>
+      <Button variant="ghost" onClick={() => setPanelOpen(false)}>Cancelar</Button>
+      <Button onClick={handleSave}>Salvar</Button>
+    </>
+  }
+>
+  <ClientForm />
+</Panel>
+```
+
+## Painel de DETALHE de registro → o bloco `dsgreen-paneldetail-1`
+
+Detalhe de registro tem estrutura definida e referenciável por ID: a composição inteira mora
+em `src/blocks/paneldetail/` e renderiza em `#/blocks-paneldetail`. Cite o ID em vez de
+recompor — `use a referência dsgreen-paneldetail-1 no painel de detalhe do pedido`. As zonas
+(identidade no header · métricas em cards · seções colapsáveis · ação primária no footer) e o
+porquê de cada uma estão documentados no arquivo do bloco.
+
+⚠️ **O bloco usa `FloatingPanel`, e a razão é este componente aqui:** o header do `Panel`
+aceita `title`/`description` como **string**, então avatar, `Chip` de status inline e ação de
+ícone não cabem nele. Precisa desse header → `FloatingPanel` (`titleSlot` + `headerActions`).
+Escolha o `Panel` quando o que importa é **bloquear** a tela atrás e o header é texto simples.
+
+## Cuidados / Gotchas
+- **Aba dentro do Panel** → `<Tabs fullWidth>` com a variante **default** (`segmented`). O Panel tem 560px: `line` aqui vira um trilho curto que lê como fragmento, e sem `fullWidth` as abas ficam num canto. `line` só se houver um `segmented` num nível acima.
+
+- **Children são auto-embrulhados em `<PanelBody>`** — NÃO passar `<PanelBody>`/`<PanelFooter>` como filhos do `<Panel>` (duplica o body e o footer perde o sticky). Footer vai SEMPRE via prop `footer`. Pra composição manual, usar `PanelRoot`/`PanelTrigger`/`PanelContent` do barrel
+- **Modal** (com backdrop suave / `SheetOverlay`) — bloqueia interação com página atrás. Pra non-modal, usar `<FloatingPanel>`
+- **Mobile (<md)**: independente do `side`, vira **sheet bottom-up colado nas bordas** do device — flush nas laterais + bottom, só cantos superiores arredondados, sem outline/shadow, `max-height: 92vh`, slide bottom-up. O backdrop (modal) continua
+- Body é único elemento scrollável (`overflow-y-auto` + `min-h-0`) — header e footer ficam fixos; conteúdo longo rola automaticamente
+- **Footer fluido**: botões crescem lado a lado e **empilham quando não cabem** (`flex-wrap` + `flex-1` + `min-w-140px`). Não precisa passar `fullWidth` nos Buttons
+- No desktop o `side` controla orientação/slide normalmente (right/left/top/bottom)

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

@@ -0,0 +1,421 @@
+# Scheduler
+
+**Categoria:** Data Display · **Dep:** `date-fns`
+
+Calendário de **eventos ao longo do tempo**, com 4 modos de visualização
+(mês · semana · dia · lista), toolbar embutida e detalhe por callback.
+
+A toolbar traz: título do período + grupo `‹ Hoje ›` à esquerda; e à direita
+busca, área custom, **seletor de view** (dropdown), **Filtro** e ação primária —
+nessa ordem, do recorte mais amplo (qual período) pro mais específico (o que
+dentro dele).
+
+**O botão Filtro carrega dois sinais independentes:**
+
+- **Verde** (`primary soft` + `border-border-brand` → brand a **14%** de
+  opacidade, texto e borda em brand) = a ferramenta está **engajada**: painel
+  aberto **ou** filtro aplicado.
+- **Ponto** no canto = existe **filtro aplicado**, e só isso.
+
+| Situação | Verde? | Ponto? |
+|---|---|---|
+| nada aberto, nada filtrado | não | não |
+| painel aberto, sem filtro | **sim** | não |
+| filtro aplicado, painel fechado | **sim** | **sim** |
+| filtro aplicado, painel aberto | **sim** | **sim** |
+
+A cor é a mesma receita do `ToolbarToolButton` do `TableToolbar` — o precedente
+do DS pra "esta ferramenta tem algo ligado". O ponto **não** é redundante com
+ela: é o que separa "abri pra olhar" de "tem filtro mexendo no que eu vejo", e é
+o portador não-cromático da informação pra quem não distingue o verde.
+
+O botão Filtro abre um **painel-coluna à direita da grade** — não um overlay.
+
+> ⚠️ **Não confunda com `Calendar`.** `Calendar` é o primitivo
+> shadcn/react-day-picker: **seletor de data** dentro de um form. O `Scheduler`
+> exibe **eventos**. As intenções são opostas, por isso os nomes são distintos.
+
+---
+
+## Quando usar
+
+| Precisa de | Use |
+|---|---|
+| escolher uma data num campo | `Calendar` / `DatePicker` |
+| escolher mês+ano | `MonthYearPicker` |
+| **ver compromissos numa grade de tempo** | **`Scheduler`** |
+| grade de registros com colunas | `DataTable` |
+| lista de cards | `DataList` |
+| quadro por estágio de workflow | `Kanban` |
+
+---
+
+## Estado atual — o que está e o que NÃO está pronto
+
+Leia antes de planejar uma tela em cima disto:
+
+| | Status |
+|---|---|
+| view `month` | ✅ grade 6×7, multi-dia com pontas truncadas, `+N mais` em popover, `+` de criar no hover |
+| views `week` / `day` | ✅ a MESMA view (`views/time-grid.tsx`) com 7 ou 1 coluna — gutter de horas, banda de dia inteiro, lane-packing, linha do "agora", faixa de hora clicável |
+| view `list` | ✅ agenda agrupada por dia, **só os dias que têm evento** |
+| drag & drop | ✅ **por ponteiro** — mover no mês (muda a data, preserva hora e duração), mover em week/day (coluna + minutos snapados), **redimensionar** pela borda do bloco em week/day |
+| navegação por teclado | ✅ roving tabindex — cada grade é **uma** parada de `Tab`, setas movem dentro, `Home`/`End` vão às pontas da linha, `Enter` cria no slot focado. ⛔ **Arrastar por teclado não existe** — ver o gotcha do dnd |
+
+O núcleo é puro e testado: `hooks/layout.test.ts` (51 casos de borda) mais
+`hooks/use-scheduler-dnd.test.ts` (19 casos da resolução do drop).
+
+---
+
+## Props essenciais
+
+| Prop | Tipo | Default | Nota |
+|---|---|---|---|
+| `events` | `SchedulerEvent[]` | — | nunca é mutado pelo componente |
+| `view` / `defaultView` | `"month" \| "week" \| "day" \| "list"` | `"month"` | controlado / não-controlado |
+| `date` / `defaultDate` | `Date` | hoje | idem |
+| `onDateChange` · `onViewChange` | `(v) => void` | — | **obrigatórios no modo controlado** |
+| `locale` | `Locale` (date-fns) | en-US | passe `ptBR` |
+| `weekStartsOn` | `0`–`6` | `0` (domingo) | |
+| `hourFormat` | `"12h" \| "24h"` | `"24h"` | |
+| `onEventClick` | `(event, evt) => void` | — | é assim que o detalhe abre |
+| `onSlotClick` | `(start, end) => void` | — | o `+` revelado no hover da célula |
+| `searchable` | `boolean` | `true` | |
+| `filterFields` | `SchedulerFilterField[]` | — | declarativo; o componente filtra sozinho |
+| `filterModel` | `Record<string, string[]>` | — | controlado / **pré-aplicado** |
+| `filterMode` | `"client" \| "server"` | `"client"` | `server` só emite |
+| `toolbarActions` | `ReactNode` | — | área custom, entre o filtro e o seletor de view |
+| `defaultFilterPanelOpen` | `boolean` | `false` | o painel-coluna de filtro já vem aberto |
+| `primaryAction` | `ReactNode` | — | botão primário à direita |
+| `renderEvent` | `({event, view, selected}) => ReactNode` | — | troca só o miolo |
+
+### `SchedulerEvent`
+
+| Campo | Tipo | Nota |
+|---|---|---|
+| `id` | `string` | |
+| `title` | `ReactNode` | |
+| `start` · `end` | `Date` | **`end` é obrigatório**; duração zero se diz `end === start` |
+| `allDay` | `boolean` | |
+| `color` | `"brand" \| "info" \| "success" \| "warning" \| "danger" \| "neutral"` | default `"brand"` |
+| `categoryId` · `tagIds` | `string` · `string[]` | filtráveis |
+| `description` | `ReactNode` | aparece na view `list` |
+| `searchText` | `string` | **necessário quando `title` não é string** |
+| `meta` | `unknown` | payload cru, devolvido em `onEventClick` |
+
+---
+
+## Exemplo mínimo
+
+```tsx
+import { ptBR } from "date-fns/locale";
+import { Scheduler } from "@/components/ui/Scheduler";
+
+<div className="h-[720px]">
+  <Scheduler
+    events={eventos}
+    locale={ptBR}
+    filterFields={[
+      { id: "categoryId", label: "Categoria", options: [
+        { value: "interna", label: "Interna" },
+        { value: "cliente", label: "Cliente" },
+      ]},
+    ]}
+    onEventClick={(evento) => setSelecionado(evento)}
+    primaryAction={<Button variant="filled" size="sm">Novo evento</Button>}
+  />
+</div>
+```
+
+---
+
+## Gotchas
+
+### 1. O pai precisa ter altura — e é a altura dele que dimensiona tudo
+
+A grade é `flex-1` dentro de um `flex-col`. Num pai sem altura definida ela
+colapsa pra altura mínima das células. Embrulhe em algo com altura
+(`h-[720px]`, ou `flex-1 min-h-0` numa página que já tem altura).
+
+**Não existe prop de "tela cheia".** O componente já é `h-full`: pra usá-lo como
+página inteira, dê `h-screen` ao container e deixe o `Scheduler` em `flex-1`.
+
+E isso não é só esticar — **a célula do mês passa a caber mais eventos**. O corte
+do `+N mais` é derivado da altura MEDIDA da linha, como as linhas da tabela.
+Medido no browser, mesmo dataset:
+
+| viewport | altura da linha | pills por célula | células com "+N mais" |
+|---|---|---|---|
+| 800px | 76px | **2** | 13 |
+| 1400px | 176px | **6** | 2 |
+
+Pra travar num número fixo (quando a tela precisa de altura de linha previsível
+independentemente do conteúdo), a view de mês aceita `maxPerCell` — mas o
+default adaptativo é o que aproveita a tela.
+
+Exemplo vivo: **Scheduler Full Screen**, na categoria Examples do showcase
+(`#/scheduler-full`).
+
+> ⚠️ A re-medição pós-montagem depende de `ResizeObserver`. Ela **não pôde ser
+> verificada** no browser de teste: a emulação de viewport por CDP não dispara
+> `ResizeObserver`, nem `window.resize`, nem `MediaQueryList.change` — medido,
+> zero callbacks nos três. O que foi verificado é a montagem correta em cada
+> altura (a tabela acima veio de reloads reais). Em browser de verdade o
+> `ResizeObserver` é o mesmo mecanismo que o resto do DS usa.
+
+### 2. A cor **nunca** vai no texto — e nunca é o único portador da informação
+
+Medido em WCAG antes de decidir: `text-fg-{cor}` sobre a pílula tingida dá
+**1.72–4.49** no claro e **2.97–4.31** no escuro. Nenhuma das 6 famílias passa
+AA, e `warning` chega a 1.72:1.
+
+Por isso o texto é sempre `fg-default` (medido no browser: **16.2–18.2** no
+claro, **16.4–17.8** no escuro — AAA nos dois modos) e a cor mora no **dot, na
+borda e no tint de fundo**.
+
+Corolário pra quem monta a tela: **cor é reforço**. O título tem que dizer o
+que o evento é — quem não distingue as cores precisa continuar entendendo a
+agenda.
+
+### 3. O teto real é ~5 categorias, não 6
+
+`brand` (matiz 151) e `success` (161) estão a **10°** de distância. Como tint a
+14% os dois viram praticamente o mesmo off-white — **não use os dois como
+categorias distintas no mesmo calendário**.
+
+`info` é matiz 280, ou seja **violeta**: se você precisa de "roxo", ele já
+existe.
+
+Precisa de 6+ categorias simultâneas e distinguíveis? Isso é o gatilho pra
+abrir uma paleta categórica própria (`event-*`) via cascata de token — não
+force a união atual.
+
+### 4. Busca não lê `title` rico
+
+O motor casa **só string**: `searchText`, `title` (se for string),
+`description` (idem) e `tagIds`. Varrer a árvore de um `ReactNode` é caro e
+frágil, então não é feito.
+
+Consequência: `title={<b>Reunião</b> — Cliente X}` **não é encontrável** —
+falha em silêncio. Declare `searchText` nesses casos.
+
+### 4b. O painel de filtro é uma COLUNA, e some abaixo de 1024px
+
+O botão **Filtro** não abre popover nem sheet: abre uma coluna à direita que
+**empurra** a grade (~296px). É deliberado — filtro é o controle cujo resultado
+você quer ver *enquanto* mexe, e por cima da grade isso viraria
+marcar → fechar → olhar → reabrir.
+
+Três consequências práticas:
+
+- **A grade encolhe.** Se a sua tela é estreita, prefira deixar
+  `defaultFilterPanelOpen` em `false` (o default).
+- **O cabeçalho do painel é `sticky` e a barra é a do DS.** O bloco "Filtros /
+  Limpar / ×" fica fixo no topo enquanto o resto rola, com `bg-bg-surface`
+  opaco — `sticky` não cria fundo, e sem ele o mini-calendário passaria por
+  baixo do título. A rolagem usa `scrollbar-thin`, a `@utility` do tema gerado
+  (trilho transparente + thumb tokenizado), que é o padrão do repo com 26 usos.
+- **O painel nunca estica a altura da linha.** Ele acompanha a altura da grade e
+  **rola por dentro** (medido: 664px de caixa com 958px de conteúdo). É por isso
+  que o root é `h-full` — sem isso ele dimensionava por conteúdo, o painel ficava
+  mais alto que a grade e passava a mandar na altura das duas, vazando pra fora
+  do container. Se você vir o calendário cortado, o pai é que está sem altura
+  (gotcha nº 1).
+- **Abaixo de 1024px o painel vira DRAWER**, não some. A coluna não cabe junto
+  de uma semana legível, então nessa faixa o mesmo painel abre num
+  `FloatingPanel side="right"` por cima — o veículo que `DataTable` e
+  `DataList` já usam pro filtro deles (`ToolbarSimpleFilterDrawer`). Mesmo
+  conteúdo, mesmo estado, mesmo botão: só o invólucro muda.
+
+  No drawer, escolher uma data no mini-calendário **fecha** o painel — ele
+  cobre a grade, e manter aberto esconderia justamente o resultado. Como
+  coluna isso não acontece.
+
+⚠️ **O breakpoint vive em UM lugar só:** `useMediaQuery("(min-width: 1024px)")`
+em `scheduler.tsx`. Não acrescente media query no `schedulerFilterAside`.
+
+> Até 2026-09-01 este parágrafo mandava mudar **dois** lugares — o `lg:flex` do
+> style *mais* o hook. O `lg:flex` foi removido justamente porque a duplicação
+> produzia um estado em que o botão se dizia aberto e o painel estava
+> `display: none`; o `scheduler.tsx` diz isso em maiúsculas desde então. A doc
+> continuou mandando reintroduzir o defeito — L-060: comentário é load-bearing.
+
+### 4c. "Nada marcado" = sem filtro, não "esconde tudo"
+
+Num app de calendário de verdade, desmarcar todas as agendas esconde tudo.
+**Aqui não**: campo sem opção marcada significa *sem restrição* — a convenção do
+`filterModel` do DS, a mesma do `DataTable` e do `DataList`. O cabeçalho do
+grupo mostra **"Todas"** nesse estado, pra não parecer que a seleção se perdeu.
+
+Inverter isso só neste componente faria o mesmo `filterModel` significar coisas
+opostas em telas diferentes.
+
+### 4d. A contagem ao lado da opção ignora os filtros de campo
+
+O número é "quantos eventos casam com a **busca** e têm esta opção" — **não**
+"quantos vou ver se marcar".
+
+A base exclui de propósito todos os filtros de campo, inclusive o do próprio
+campo, pra que os números fiquem **estáveis enquanto você marca e desmarca**.
+Com a facet count clássica (base = os outros campos já aplicados), cada clique
+mexeria nos números das outras listas, e a leitura vira alvo móvel exatamente na
+hora de decidir. As duas leituras são defensáveis; confundi-las é que engana.
+
+### 5. `filterFields` no modo `client` só filtra 3 ids
+
+`categoryId`, `tagIds` e `color`. Qualquer outro `id` **renderiza o chip e não
+filtra nada** — o componente emite `console.warn` em DEV nomeando o campo.
+Para filtrar por campo próprio, use `filterMode="server"` e filtre fora.
+
+### 5b. Drag & drop: você PRECISA aplicar a mudança
+
+O componente é dumb sobre mutação — ele emite e para:
+
+```tsx
+const [eventos, setEventos] = useState(EVENTOS);
+const aplicar = ({ id, start, end }) =>
+  setEventos((a) => a.map((e) => (e.id === id ? { ...e, start, end } : e)));
+
+<Scheduler
+  events={eventos}
+  draggable
+  resizable
+  onEventMove={aplicar}
+  onEventResize={aplicar}
+/>
+```
+
+O que cada gesto significa:
+
+| gesto | resultado |
+|---|---|
+| arrastar no **mês** | muda a **data**; hora e duração preservadas |
+| arrastar em **week/day** | combina coluna (dia) + `delta.y` (minutos, snapado por `snapMinutes`) |
+| arrastar a **borda** do bloco (week/day) | muda a **duração**, uma ponta só |
+
+Detalhes que evitam surpresa:
+
+- **A duração nunca é snapada separadamente.** Um evento de 50min movido continua
+  com 50min — snapar as duas pontas o encurtaria pra 45 a cada arrasto.
+- **Resize não existe no mês** (a altura da pílula não representa duração) nem em
+  evento `allDay`.
+- **All-day em week/day ignora o `delta.y`** e só troca de dia: ele mora na banda,
+  não na grade de horas.
+- **Arrastar pra baixo perto do fim da grade encosta no limite** em vez de vazar
+  pro dia seguinte. Mudar de dia se faz atravessando a coluna — o gesto explícito.
+- **O bloco que segue o cursor é um `DragOverlay`, em `position: fixed`.** É
+  obrigatório: três ancestrais cortam (o frame da grade, a pilha de eventos da
+  célula e o corpo rolável de week/day), e elemento transformado continua sujeito
+  ao clipping do ancestral — a primeira versão movia o próprio bloco e ele
+  **desaparecia** ao sair da célula. Se você embrulhar o `Scheduler` num
+  container com `transform`, `filter` ou `contain: paint`, esse container passa
+  a ser o containing block do `fixed` e o defeito volta.
+- **Só dá pra mover pra um dia VISÍVEL na grade.** No mês isso inclui as células
+  cinzas dos meses vizinhos (a grade de setembro/2026 vai de 30/ago a 10/out, e
+  as duas pontas são alvo válido). Pra um mês fora da tela, navegue primeiro —
+  não há auto-avanço ao arrastar sobre as setas.
+
+- **O dnd é por PONTEIRO.** O `KeyboardSensor` do dnd-kit não está registrado,
+  de propósito: ele reivindica `Space`/`Enter`, que num `<button>` de evento já
+  significam "abrir o detalhe" — as duas coisas brigavam e o arraste era
+  cancelado (medido na live region do dnd-kit). `Space`/`Enter` abrem o detalhe,
+  que é onde data e hora se editam em campo de formulário: a rota acessível pra
+  reagendar. O raciocínio completo está no topo de `use-scheduler-dnd.ts`.
+
+> ⚠️ O gesto de ponteiro **não pôde ser verificado no browser de teste**: o
+> `PointerSensor` usa `setPointerCapture` com `pointerId` real, e nem
+> `left_click_drag` nem `PointerEvent` sintéticos o ativam — medido, o evento não
+> sai do lugar. A resolução do drop é coberta por
+> `hooks/use-scheduler-dnd.test.ts` (20 casos), e no DOM foi medido: 12 blocos
+> com 24 alças na semana, e o droppable respondendo (a live region do dnd-kit
+> nomeou `day:<ms>` ao passar por cima).
+
+### 5c. Teclado: a grade é UMA parada de `Tab`
+
+Roving tabindex (padrão WAI-ARIA de `grid`): a célula ativa tem `tabIndex=0`, as
+outras `-1`.
+
+| tecla | ação |
+|---|---|
+| `←` `→` | dia anterior / seguinte |
+| `↑` `↓` | mesma coluna, linha acima / abaixo (mês: semana; week/day: hora) |
+| `Home` / `End` | início / fim da **linha** — não da grade |
+| `PageUp` / `PageDown` | primeira / última célula |
+| `Enter` ou `Space` | cria no slot focado (dispara `onSlotClick`) |
+
+Sem isso a grade do mês custava **42 `Tab`** e a da semana **168**. O `+` de
+criar tem `tabIndex={-1}` de propósito: ele é alcançado pelo `Enter` na célula,
+e deixá-lo tabbável reintroduziria as 42 paradas.
+
+Medido no browser: `→` levou de 0 pra 1, `↓` de 1 pra 8 (+7), `Home` de 8 pra 7
+(início da linha), com sempre exatamente 1 célula em `tabIndex=0`.
+
+### 6. `draggable` e `resizable` nascem `false`
+
+Deliberado (mesmo default do `enableDnD` do `Kanban`): dnd ligado sem
+`onEventMove` conectado deixa o usuário arrastar e ver o evento voltar sozinho
+— o pior estado possível, porque parece bug do app.
+
+O componente **não liga o dnd** se não houver `onEventMove`/`onEventResize`
+conectado, e em DEV avisa por `console.warn` nomeando qual falta. `event.draggable`
+e `event.resizable` sobrepõem por evento — é como se diz "esta reunião é fixa"
+sem desligar o board todo.
+
+### 6b. `SchedulerFilterPanel` também é exportado solto
+
+Mesmo padrão do `TableToolbar`, que expõe `ToolbarSearch`, `ToolbarSegmented` e
+as outras partes pelo barrel. Serve pra tela que queira posicionar o painel em
+outro lugar do próprio layout — e pra doc page, que o renderiza isolado pra
+mostrar a anatomia (cabeçalho sticky · mini-calendário · um grupo por campo).
+
+**Em uso normal você não precisa dele:** o `Scheduler` monta e controla o seu.
+Usando solto, todo o estado é seu — `filterModel`, `counts`, `date`, `now` e os
+callbacks vêm por prop, e nada é derivado sozinho.
+
+#### `embedded` — quando o painel NÃO é a superfície
+
+| | `embedded={false}` (default) | `embedded` |
+|---|---|---|
+| Largura | `w-[280px]` fixa | `w-full` |
+| Moldura | borda + radius + `bg-bg-surface` | nenhuma |
+| Cabeçalho próprio | título + Limpar + × | não renderiza |
+
+Ligue quando ele viver **dentro** de outro contêiner que já é a superfície e já
+traz cabeçalho — é o que o próprio `Scheduler` faz no modo drawer (<1024px),
+dentro de um `FloatingPanel`.
+
+São duas mudanças numa prop só porque é uma decisão só: *"existe outro contêiner
+em volta?"*. Separadas, dava pra combinar metade de cada e obter um card de 280px
+sem cabeçalho dentro de um painel de 375 — que é exatamente o defeito.
+
+### 7. O painel de detalhe é seu, não do componente
+
+O `Scheduler` não importa `FloatingPanel`. Ele emite
+`onEventClick(event, evt)` e devolve `event.meta` intacto; quem monta o painel
+é a tela. O padrão de referência é o bloco **`dsgreen-paneldetail-2`**
+(`side="right"`, `size="lg"`, `titleSlot` com o contexto, lista plana de
+propriedades) — há um exemplo completo em `src/preview/pages/SchedulerDoc.tsx`.
+
+⚠️ O body do `FloatingPanel` **não tem gap entre filhos**. Sem um wrapper
+`flex flex-col gap-gp-2xl`, título e lista ficam colados.
+
+### 8. No mês, evento multi-dia aparece por dia, não como barra contínua
+
+`hooks/layout.ts` já calcula `colStart`/`colSpan` por linha, mas a view desenha
+o evento em **cada dia que ocupa**, com as pontas truncadas marcando a
+continuação. A barra única atravessando as colunas exige reservar a mesma faixa
+vertical em todas as células (lane-packing por linha da grade) e vem com o dnd.
+A extensão do evento é lida corretamente — o que falta é refinamento visual.
+
+### 9. `filterModel` pré-aplicado é o caminho certo pra "já vem filtrado"
+
+Nunca monte um form de filtro acima da grade (L-051). Passe `filterModel` e o
+chip aparece já aplicado, com o `×` pra desfazer.
+
+### 10. Nada aqui importa de `TableToolbar`
+
+A gramática visual do segmented, da busca e dos chips é **copiada** em
+`scheduler.styles.ts`, não importada. Cross-import entre pastas de `ui/` é o
+que gerou o `registryDependency` dangling da L-049 (`@igreen/table-toolbar` não
+existe como item de registry). Se você editar o visual da toolbar do
+`TableToolbar`, considere se esta cópia deve acompanhar.