@softize/opus 18.5.0 → 19.0.0

package/CHANGELOG.md

@@ -7,6 +7,88 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 19.0.0 — 2026-09-24
+
+Card, Dialog, Drawer e Pane passam a derivar a anatomia da mesma infraestrutura que Page e Content
+já usavam. Cada superfície declara `layout="continuous" | "sectioned"` no seu componente raiz, e o
+layout responde por um pacote: recuo das regiões, ritmo vertical, escala do título, posição das
+ações, apresentação da mídia e divisores. O divisor passa a ser derivado da vizinhança das regiões —
+um header seguido de corpo desenha a linha; um header sozinho, não.
+
+Os headers passam a posicionar sozinhos o que antes o consumidor montava: mídia, título, descrição
+(onde a família a tem), ações no extremo oposto e o botão de fechar depois delas. `Dialog`, `Drawer`
+e `Pane` ganham slots de ações e de navegação; `Card` e `Pane` ganham slot de mídia; `Card` ganha
+título com nível semântico.
+
+A família `Pane` deixa de viver em dois módulos: raiz e slots agora moram juntos, com título,
+mídia, ações, descrição e página própria na documentação.
+
+`MetricCard` ganha ativação: com `onActivate`, `active` e `activationLabel`, a medida vira um
+controle que aplica o recorte que ela resume — o card passa a emitir `aria-pressed` e a anunciar o
+próprio nome. As três propriedades andam juntas pelo tipo; declarar `active` sem `onActivate` não
+compila. A marcação de ativo é a borda na cor primária: antes era um anel desenhado para fora da
+borda, que qualquer ancestral com `overflow-hidden` cortava. O anel de foco também passa a ser
+interno.
+
+Na mesma versão, a lista em `layout="fill"` troca a rolagem montada com um contêiner posicionado
+por uma grade de duas linhas: os resultados ocupam a folga, o rodapé se mede pelo conteúdo, e o
+contêiner da tabela abre mão da rolagem horizontal para não roubar do cabeçalho a referência do
+`sticky`. O rodapé encosta na última linha e mantém a mesma altura com e sem paginador. O detalhe
+aproxima o ícone do rótulo, na escala densa das superfícies produtivas.
+
+### Breaking
+
+**Headers validam seus slots.** `CardHeader`, `DialogHeader`, `DrawerHeader` e `PaneHeader` aceitam
+apenas os slots da família e no máximo um de cada. Nó solto dentro do header passa a lançar erro com
+a lista do que é aceito. Migração: envolva ações em `CardAction`, `DialogActions`, `DrawerActions`
+ou `PaneActions`; navegação em `DialogNavigation` ou `DrawerNavigation`; ícone em `CardMedia`,
+`DrawerMedia` ou `PaneMedia`. Descrição dentro do header de modal não tem slot e vai para o começo
+do corpo, como as ADRs 0014 e 0018 já determinavam.
+
+**`CardTitle` virou heading.** Era um `div` sem escala tipográfica; agora emite `h3` por padrão,
+aceita `level` para a hierarquia correta e declara a escala pelo layout. Migração: remova o heading
+que você embutia dentro dele e o `text-*` que aplicava por fora; passe `level` quando a página pedir
+outra hierarquia.
+
+**Divisores saem do consumidor.** `<CardHeader className="border-b">` e
+`<CardFooter className="border-t">` deixam de ser necessários: use `layout="sectioned"` no `Card`.
+As classes continuam funcionando, mas somam uma segunda linha sobre a derivada.
+
+**`PaneHeader` e `PaneFooter` ganharam recuo próprio** e o `Pane` passa a usar `inset="none"`
+sozinho quando contém slots estruturais. Migração: remova o `inset="none"` e o padding que a tela
+aplicava no header; remova também o `border-b-0`/`border-t-0` de quem desligava o divisor para
+redesenhá-lo à mão.
+
+**O rodapé do `Drawer` recebeu a faixa sutil do `Dialog`.** A ausência era divergência não declarada
+entre duas superfícies com a mesma anatomia; agora as duas usam o mesmo fundo. O título do Drawer
+também perdeu o `text-foreground` que só ele tinha.
+
+**Títulos de modal passam a truncar.** `DialogTitle` e `DrawerTitle` mantêm o nome da superfície em
+uma linha, com reticências quando não cabe, em vez de empurrar o corpo para baixo. O
+`mode="alert"` é a exceção: ali o título é centralizado e pode ocupar duas linhas, porque a
+resposta obrigatória não tem corpo para empurrar. As telas que já
+escreviam `truncate` podem remover a classe. Quando o nome precisar aparecer inteiro, ele pertence
+ao começo do corpo, não ao cabeçalho (ADR 0018).
+
+**Mídia com visual próprio.** Os slots de mídia aceitam `asChild`: uma marca que já se desenha —
+um orbe, um logotipo — ocupa o slot sem ganhar a moldura por cima, e continua herdando a escala.
+
+**O rodapé do `Drawer` mantém o `mt-auto`** que o `Dialog` não tem. A diferença passa a ser
+declarada: o conteúdo lateral raramente preenche a altura da janela, e sem isso o rodapé subiria
+atrás do corpo.
+
+**Divisor não se desliga por classe.** `border-b-0` no consumidor não apaga a linha derivada — ela
+vem de uma variante condicional, que vence uma classe simples. Uma superfície sem divisores é uma
+superfície `continuous`: troque o layout no root em vez de apagar a borda região a região.
+
+### Migração rápida
+
+1. Rode a aplicação e siga os erros dos headers: cada um diz o slot que falta.
+2. Remova `p-*`, `border-b`, `border-t`, `flex-row`, `justify-between` e `text-*` que existiam só
+   para corrigir o default da família.
+3. Troque `<Card>` + classes de divisor por `<Card layout="sectioned">`.
+4. Onde a tela remontava header com `div`, use os slots — eles agora posicionam sozinhos.
+
 ## 18.5.0 — 2026-09-22
 
 `Content` passa a concentrar estrutura e apresentação de blocos com cabeçalho e corpo: aceita

package/docs/adr/0023-surfaces-share-one-anatomy-and-two-layouts.md

@@ -0,0 +1,293 @@
+# ADR 0023 — Superfícies compartilham uma anatomia e dois layouts
+
+- **Status:** aceita.
+- **Data:** 2026-09-23.
+- **Complementa:** ADRs 0005, 0014, 0018, 0019 e 0021.
+
+## Contexto
+
+A ADR 0005 estabeleceu a gramática `Root > Header + Body + Footer` para as superfícies da casa. O
+vocabulário foi adotado, mas a implementação não: `Page` e `Content` derivam o header de uma
+infraestrutura interna comum, enquanto `Card`, `Dialog`, `Drawer` e `Pane` desenham o seu à mão.
+
+O efeito acumulado é mensurável no código de hoje:
+
+- **Três escalas de padding para o mesmo papel.** `p-3` no chrome de Page, `p-4` nos slots de Dialog
+  e Drawer, `px-5` no Card. `Card` é a única com ritmo vertical assimétrico (`pt-5 pb-3` no header,
+  `pt-3 pb-5` no footer). `Content`, `PageBody` e `PaneBody` não têm padding nenhum.
+- **`PaneHeader` sem padding e `PaneFooter` com `p-2`** — assimetria dentro da mesma família.
+- **`CardTitle` é um `div` sem escala tipográfica**, único título do conjunto que não é heading e
+  não declara tamanho; herda o que vier do contexto.
+- **Divisor automático em quatro famílias e manual no Card.** A documentação pública ensina o
+  consumidor a escrever `border-b` no `CardHeader` e `border-t` no `CardFooter`.
+- **`Dialog` e `Drawer` não têm slot de ações no header.** Quem precisa injeta nós soltos ao lado do
+  título, como `Presentation` faz hoje.
+- **A família `Pane` está partida**: a raiz mora em `split.tsx`, os slots em `sidebar.tsx`, a
+  documentação está na página da Sidebar e nenhum teste cobre a anatomia.
+- **`Drawer` duplica `Dialog`** com três divergências não declaradas: footer sem fundo, header sem a
+  supressão condicional do divisor e título com `text-foreground` a mais.
+- **Nenhuma suíte transversal** compara as famílias; cada divergência só aparece quando alguém
+  compõe as duas superfícies lado a lado.
+
+A evidência que motivou a decisão veio da tela do Evento de Pós-vendas: para aproximar dois Cards do
+recorte já usado por Dialog e Content, a tela precisou escrever `flex-row items-center gap-4
+border-b p-4` no header, `p-4` no body, `text-sm` no título, um `<h3>` dentro do `CardTitle` e o
+ícone dentro do texto. São cinco decisões estruturais tomadas pelo consumidor.
+
+As forças em tensão:
+
+- **Uniformidade × identidade da família.** Um modal, um card e um painel não precisam ter as mesmas
+  medidas; precisam ter a mesma gramática e o mesmo comportamento estrutural.
+- **Compatibilidade × correção.** Alterar o default de uma família muda todas as telas que já a
+  usam. Preservar o default errado perpetua o defeito que motivou a decisão.
+- **Uma API genérica × seis APIs específicas.** Um `<Surface>` público reduziria código e apagaria a
+  semântica de cada família; seis implementações independentes preservam a semântica e produzem a
+  divergência atual.
+
+## Decisão
+
+### 1. Uma infraestrutura interna, seis fachadas públicas
+
+As telas continuam usando `CardHeader`, `DialogHeader`, `DrawerHeader`, `PaneHeader`,
+`ContentHeader` e `PageHeader`. Não existe superfície genérica pública. `SurfaceHeader` e o novo
+módulo de anatomia permanecem internos: a aplicação não os importa.
+
+A anatomia compartilhada passa a viver em um único módulo interno, que responde por:
+
+- as classes de cada região (`header`, `body`, `footer`) por família e layout;
+- a escala visual do título, separada do nível semântico;
+- a posição e o tamanho das ações;
+- a apresentação da mídia;
+- os divisores entre regiões adjacentes;
+- o alinhamento horizontal comum entre as regiões da mesma superfície.
+
+Nenhuma família reimplementa essas regras. Quando uma família precisa divergir, a divergência é um
+valor declarado na tabela de anatomia, não uma classe escrita no componente.
+
+### 2. O layout é do root e chega aos slots por contexto
+
+`layout` é propriedade do componente raiz: `Card`, `DialogContent`, `DrawerContent` e `Pane`. Os
+slots não recebem `layout`; eles leem o contexto da superfície que os hospeda. Um slot usado fora da
+sua família continua sendo erro, como hoje.
+
+`Content` e `Page` não expõem `layout` de anatomia. `Content` é contínuo por definição e `Page`
+mantém `layout="flow" | "fill"`, que descreve ocupação de altura, não anatomia. São nomes
+diferentes para coisas diferentes e permanecem assim.
+
+### 3. O que cada layout significa
+
+`continuous` e `sectioned` não são a ausência e a presença de uma borda. Cada um é um pacote:
+
+| Aspecto | `continuous` | `sectioned` |
+| --- | --- | --- |
+| Divisores | nenhum | entre regiões adjacentes presentes |
+| Ritmo vertical | header aproxima-se do corpo; o espaço separa | regiões simétricas; o divisor separa |
+| Escala do título | a da família | a da família, um degrau mais contida quando a família tem duas |
+| Fundo do footer | igual ao da superfície | sutil, quando a família declara |
+| Alinhamento horizontal | idêntico entre header, body e footer | idêntico entre header, body e footer |
+
+O alinhamento horizontal é invariante dos dois layouts: o recuo lateral de header, body e footer de
+uma mesma superfície é sempre o mesmo valor. É o que a suíte transversal verifica.
+
+### 4. Os divisores são derivados, não escritos
+
+No layout `sectioned`, o divisor existe quando há duas regiões adjacentes. Um header seguido de nada
+não desenha linha; um footer que é a única região também não. A regra é estrutural e vive no
+componente, derivada da presença dos irmãos — não uma classe que o consumidor aplica.
+
+A recomendação de escrever `border-b` e `border-t` no Card sai da documentação.
+
+### 5. Defaults por família
+
+Os defaults preservam o que cada família já entrega hoje, exceto onde o comportamento atual é o
+defeito que esta decisão corrige:
+
+| Família | Default | Por quê |
+| --- | --- | --- |
+| `Card` | `continuous` | é o que a família entrega hoje: sem divisores, ritmo assimétrico |
+| `Dialog` (default) | `sectioned` | já tem divisores e faixas; o default nomeia o que existe |
+| `Dialog` (`mode="alert"`) | composição própria | a resposta obrigatória mantém sua anatomia centrada |
+| `Drawer` | `sectioned` | idem Dialog |
+| `Pane` | `sectioned` | header e footer já têm divisor |
+| `Content` | contínuo, sem opção | região semântica dentro de outra superfície |
+| `Page` | contínuo, sem opção | a separação do chrome pertence ao shell |
+
+Nenhum default muda de valor efetivo com esta ADR. O que muda é que o valor passa a ter nome,
+implementação única e teste.
+
+### 5.1. O que o inventário dos consumidores mostrou
+
+A migração foi decidida sobre 374 usos reais das seis famílias na plataforma. O que eles revelam:
+
+- **Nenhuma tela usa `CardDescription`, `ContentDescription`, `DialogDescription` ou equivalente.**
+  Toda descrição é um `<p className="text-sm text-muted-foreground">` escrito à mão. Quando esse
+  parágrafo está dentro de um `DialogHeader`, ele contraria a ADR 0018 e precisa ir para o corpo na
+  migração — não ganhar um slot novo no header.
+- **`Card` é usado como caixa sem slots em várias telas**, com o padding escolhido por elas (`p-3`,
+  `p-5`, `px-3 py-2`). O root do Card continua sem padding próprio: quem não usa slots continua
+  decidindo. O padding pertence aos slots, como hoje.
+- **Os dois `PaneHeader` do produto escrevem quase a mesma linha** (`flex h-[3.75rem] items-center
+  … p-3 … border-b-0`) em contextos diferentes. É a prova de que padding e divisor pertencem à
+  primitiva.
+- **Um comentário no código do login documenta o defeito**: o `py-3` do `CardBody` "conta com um
+  CardFooter, que o login não tem". O ritmo do layout contínuo precisa reagir à ausência do rodapé.
+- **Três testes de consumidor contradizem a unificação** e precisam de decisão explícita, não de
+  ajuste mecânico: um proíbe `p-4` no Card, outro exige `p-0` no `DrawerBody`, outro proíbe
+  `ContentHeader` em uma seção. Os dois primeiros fixam contornos; o terceiro fixa uma escolha de
+  composição que continua válida.
+
+### 6. Slots por família
+
+A anatomia é comum; o conjunto de slots continua sendo decisão de cada família, porque decisões
+anteriores já os delimitaram:
+
+| Slot | Card | Content | Page | Dialog | Drawer | Pane |
+| --- | --- | --- | --- | --- | --- | --- |
+| Media | sim | não | não | sim (`DialogMedia`) | sim | sim |
+| Title | sim | sim | sim | sim | sim | sim |
+| Description | sim | sim | não (ADR 0014) | não (ADR 0018) | não (ADR 0018) | não |
+| Meta | não | sim (contador) | não (ADR 0009) | não | não | não |
+| Actions | sim | sim | sim | sim | sim | sim |
+| Body | sim | sim | sim | sim | sim | sim |
+| Footer | sim | não | sim | sim | sim | sim |
+
+As ADRs 0009, 0014 e 0018 não são reabertas: Page, Dialog e Drawer continuam sem descrição no
+header, e Page continua sem contador. `Dialog`, `Drawer` e `Pane` ganham o slot de ações que hoje
+não têm — a ausência obrigava a injetar nós soltos ao lado do título, e o `Studio` a manter três
+anatomias paralelas para a mesma entrada declarativa. O botão de fechar continua sendo o último
+elemento da linha; as ações da tela ficam antes dele.
+
+`Pane` ganha também título e mídia. Hoje ele não tem nenhum dos dois, e as duas telas que precisam
+de um cabeçalho remontam a linha com `span`, incluindo o ícone dentro do texto.
+
+`Content` permanece sem footer: é uma região nomeada dentro de outra superfície, e um rodapé
+pertence à superfície que a hospeda.
+
+### 7. Título: hierarquia e tamanho são independentes
+
+O nível semântico vem de `level` (`1`–`6`) ou de `asChild`, e nunca do tamanho visual. O tamanho vem
+da família e do layout. `CardTitle` deixa de ser um `div` sem escala e passa a declarar as duas
+coisas, com `h3` como default — um card é uma seção dentro de uma página que já tem `h1`.
+
+### 8. Mídia reutiliza a moldura existente
+
+O slot de mídia usa `IconTile` ou a mesma infraestrutura visual dele. Nenhuma família cria outra
+escala de molduras.
+
+Quando a marca já tem visual próprio — um orbe, um logotipo —, `asChild` deixa o slot ceder o
+elemento para ela: a escala continua vindo da mesma fonte, e a moldura sai de cena em vez de ser
+desenhada por baixo.
+
+`DialogMedia` é a exceção declarada: no modo de alerta a mídia não acompanha uma linha de título,
+ela é o elemento de reconhecimento da resposta, e mantém a moldura maior e centrada. A exceção vale
+só nesse modo, deriva da mesma infraestrutura das demais e é coberta por teste. Fora do alerta, o
+`DialogMedia` é a mesma moldura das outras famílias.
+
+### 7.1. O Pane aceita conteúdo livre; as demais não
+
+`Card`, `Dialog`, `Drawer`, `Page` e `Content` sempre nomeiam alguma coisa: seus headers aceitam só
+os slots da família e reprovam nó solto, com uma mensagem que lista o que é aceito.
+
+`Pane` é a superfície genérica — a coluna que hospeda navegação, marca, busca ou chrome que não é
+título nem ação. Seu header aceita conteúdo livre ao lado dos slots, e esse conteúdo ocupa o mesmo
+espaço do heading, de modo que as ações continuam indo para o extremo oposto sem classe no
+consumidor. A permissividade é dele, não uma brecha geral: forçar a marca de uma barra lateral a
+virar "título" seria uniformidade sem semântica.
+
+O conteúdo livre é renderizado **dentro** da região de heading, depois do título e da descrição,
+qualquer que seja a ordem no JSX. Ele herda dali a largura que o heading absorve, o que é o que
+permite às ações continuarem no extremo oposto — mas também significa que uma busca colocada no
+header aparece **abaixo** do título, não ao lado dele. Um header que precise de algo antes do
+título usa o slot de mídia; um que precise de algo ao lado usa o de ações.
+
+### 8.1. Nível semântico em todas as fachadas
+
+Todo título de superfície aceita `level`. Nos modais, onde a primitiva de acessibilidade emite o
+elemento, o nível troca a tag do mesmo nó por composição, nunca aninha um heading dentro de outro, e
+não altera a escala. Sem `level`, vale o `h2` que a primitiva já emitia.
+
+### 9. `Pane` deixa de ser uma família partida
+
+Raiz e slots passam a viver no mesmo módulo, com validação de pertencimento, documentação própria e
+os mesmos testes das demais famílias. `split.tsx` continua dono do redimensionamento; `sidebar.tsx`
+continua dono da navegação. A fronteira deixa de ser acidental e passa a ser declarada.
+
+### 10. Compatibilidade
+
+Aliases depreciados existentes (`CardContent`, `PaneContent`) seguem seu plano de remoção; esta
+decisão não cria novos.
+
+Classes de recuo, ritmo e escala que o consumidor já aplica continuam funcionando: `className` é
+mesclado por último e vence. Uma tela que ainda escreve `p-4` no `CardHeader` não quebra, apenas
+deixa de precisar.
+
+**Os divisores são a exceção, e é uma exceção real.** Eles nascem de variantes condicionais
+(`:not(:last-child)`), que têm especificidade maior que uma classe simples: `border-b-0` no
+consumidor não desliga a linha derivada. Desligar o divisor de uma região isolada não é, portanto,
+uma decisão do consumidor — é decisão da superfície, e se expressa trocando o layout dela para
+`continuous`. A paleta de comandos é o caso dentro do próprio SDK: ela é contínua, e não um
+seccionado com a primeira linha apagada.
+
+Pela mesma razão, a regra que suprime o divisor entre um header e um rodapé adjacentes precisa
+vencer a que o cria — não basta vir depois dela na folha, porque a ordem das variantes não é nossa.
+
+## Consequências
+
+- Uma mudança de espaçamento, divisor ou escala passa a ter um lugar só; hoje tem seis.
+- Card ganha um modo que a aplicação já construía à mão, e a documentação deixa de ensinar o
+  contorno.
+- Dialog e Drawer ganham ações no header; `Presentation` deixa de injetar nós soltos.
+- Pane deixa de ser exceção não testada.
+- Consumidores que aplicavam classes de correção podem removê-las; quem não remover continua
+  funcionando, o que permite migração incremental.
+- O custo é concentrado: quase toda a superfície visual do SDK muda de implementação ao mesmo tempo,
+  e a rede de proteção precisa existir antes da migração, não depois.
+- Uma família que precise divergir passa a precisar declarar a divergência na tabela e cobri-la por
+  teste. Isso é deliberado: torna a diferença uma decisão, não um acidente.
+
+## Alternativas descartadas
+
+### Manter cada família com seu header
+
+Preservaria compatibilidade absoluta e evitaria o custo de migração. Foi descartada porque é o
+estado atual: produziu três escalas de padding, um título sem escala, divisores manuais em uma
+família e a documentação pública ensinando o contorno.
+
+### Expor um `<Surface>` genérico
+
+Reduziria o código a uma implementação e uma API. Foi descartada porque apagaria a semântica de cada
+família — um card, um modal e um painel deixariam de se distinguir no código da tela — e porque o
+ganho real está na infraestrutura interna, que este ADR unifica sem expor.
+
+### Unificar também as medidas entre famílias
+
+Um único recuo para todas as superfícies eliminaria a tabela de anatomia. Foi descartada porque as
+famílias têm densidades legítimas diferentes: o chrome de página é mais compacto que um card, e um
+modal tem largura controlada. O invariante que importa é o alinhamento dentro de cada superfície,
+não a igualdade entre superfícies diferentes.
+
+### Tratar `layout` como propriedade de cada slot
+
+Permitiria um header seccionado com um corpo contínuo. Foi descartada porque o layout é a relação
+entre as regiões: um divisor depende de quem está do outro lado. Propriedade por slot permitiria
+compor superfícies incoerentes sem erro.
+
+### Derivar os divisores por CSS no consumidor
+
+Manteria o componente menor. Foi descartada porque devolve ao consumidor a decisão que esta ADR
+retira dele, e porque a regra depende de presença de irmãos, que o componente conhece e a tela
+não.
+
+## Verificação
+
+- Uma suíte transversal parametrizada percorre as famílias configuráveis e verifica, para cada
+  layout: alinhamento horizontal idêntico entre header, body e footer; divisor apenas entre regiões
+  adjacentes presentes; escala do título independente do nível semântico; header com e sem mídia,
+  descrição e ações; ações no extremo oposto sem classe no consumidor; body sem header; header sem
+  footer; footer com e sem ações.
+- A mesma suíte verifica que `Page` e `Content` não expõem `sectioned` e que nenhuma família
+  reimplementa as classes de anatomia localmente.
+- Testes de família continuam cobrindo o que é específico de cada uma.
+- Exemplos vivos no catálogo apresentam a matriz de layouts e slots.
+- `opus check` continua reprovando slots fora da família.
+- Um teste de API pública reprova a exportação de `SurfaceHeader` ou do módulo de anatomia.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "18.5.0",
+  "version": "19.0.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/src/ui/components/patterns/content-header.tsx

@@ -10,6 +10,7 @@ import {
   type ReactNode,
 } from "react";
 import { cn } from "../../lib/cn.ts";
+import { headingTags } from "./heading-level.ts";
 import { usePageHeadingPresence } from "./page-heading-context.tsx";
 import {
   SurfaceHeader,
@@ -291,15 +292,6 @@ export function ContentHeader({
   );
 }
 
-const headingTags = {
-  1: "h1",
-  2: "h2",
-  3: "h3",
-  4: "h4",
-  5: "h5",
-  6: "h6",
-} as const;
-
 export function ContentTitle({
   className,
   id,

package/src/ui/components/patterns/heading-level.ts

@@ -0,0 +1,16 @@
+/**
+ * Nível de heading (interno): hierarquia do documento, separada do tamanho visual.
+ *
+ * A ADR 0023 fixa a regra: `h1`–`h6` expressam hierarquia; a escala do título vem da
+ * família e do layout. As duas decisões nunca se misturam num mesmo valor.
+ */
+export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+
+export const headingTags = {
+  1: "h1",
+  2: "h2",
+  3: "h3",
+  4: "h4",
+  5: "h5",
+  6: "h6",
+} as const satisfies Record<HeadingLevel, `h${HeadingLevel}`>;

package/src/ui/components/patterns/list.tsx

@@ -2144,8 +2144,11 @@ export function ActionList<TInput, TItem>({
         variant="plain"
         className={tableStateActive ? "h-full" : undefined}
         containerClassName={
+          // Quem rola é a linha de resultados, acima: aqui o contêiner abre mão da
+          // rolagem horizontal para não virar a referência do `sticky` do cabeçalho.
+          // `h-full` só no estado sem linhas, para a moldura vazia ocupar a altura.
           tableFillsAvailableHeight
-            ? "absolute inset-0 overflow-auto"
+            ? cn("overflow-x-visible", tableStateActive && "h-full")
             : undefined
         }
       >
@@ -2290,7 +2293,14 @@ export function ActionList<TInput, TItem>({
     ) : null;
 
   // — Rodapé (o estilo da casa): Página X de Y à esquerda · pager CENTRALIZADO ·
-  //   total à direita (grid de 3 colunas com laterais 1fr = centro geométrico) —
+  //   total à direita (grid de 3 colunas com laterais 1fr = centro geométrico).
+  //   Encosta na última linha: a borda de cima é o fecho da tabela, não a de um
+  //   bloco solto, então o rodapé não entra no `gap` da pilha.
+  //   Altura: 2.5rem de piso (a mesma do `TableHead`) para a faixa não mudar de
+  //   tamanho quando o pager aparece — ele ocupa 1.75rem e cabe dentro do piso.
+  //   O padding fica em 0.25rem só para o dia em que o conteúdo passar disso:
+  //   com `py-2` o padding empurraria o pager para fora e a faixa voltaria a
+  //   crescer —
   const pages =
     total !== undefined
       ? Math.max(1, Math.ceil(total / (state.limit ?? pageSize)))
@@ -2300,7 +2310,7 @@ export function ActionList<TInput, TItem>({
     total !== undefined && !isError ? (
       <div
         data-slot="action-list-footer"
-        className="grid grid-cols-[1fr_auto_1fr] items-center gap-3 border-t border-border px-3 py-1.5 text-xs text-muted-foreground"
+        className="grid min-h-10 grid-cols-[1fr_auto_1fr] items-center gap-3 border-t border-border px-3 py-1 text-xs text-muted-foreground"
       >
         <span>
           Página {state.page} de {pages}
@@ -2368,19 +2378,28 @@ export function ActionList<TInput, TItem>({
         {toolbar}
         {beforeContent}
         {selectionBar}
-        {/* Refetch com a lista já na tela: esmaece e trava interação até chegar. */}
-        <div
-          aria-busy={busy}
-          className={cn(
-            layout === "fill" && "relative flex min-h-0 flex-1 flex-col",
-            layout === "fill" &&
-              (tableFillsAvailableHeight ? "overflow-hidden" : "overflow-auto"),
-            busy && items.length > 0 && "pointer-events-none opacity-60",
-          )}
-        >
-          {body}
+        {/* Tabela e rodapé formam um bloco só: o `gap` da pilha separa a barra de
+            ferramentas do conteúdo, nunca o conteúdo do seu próprio rodapé. Duas
+            linhas: a dos resultados absorve a altura que sobra, a do rodapé se mede
+            pelo conteúdo. Em `flow` a primeira linha também é `1fr`, mas o bloco não
+            tem altura própria e ela vira a altura do conteúdo. */}
+        <div className={cn("grid min-h-0 grid-rows-[1fr_auto]", layout === "fill" && "flex-1")}>
+          {/* A rolagem mora aqui, nos dois eixos: é este elemento que o `sticky` do
+              cabeçalho enxerga. Um contêiner de rolagem entre ele e a tabela roubaria
+              essa referência e o cabeçalho voltaria a subir junto com as linhas.
+              Refetch com a lista já na tela: esmaece e trava interação até chegar. */}
+          <div
+            aria-busy={busy}
+            className={cn(
+              "min-h-0",
+              layout === "fill" && "overflow-auto",
+              busy && items.length > 0 && "pointer-events-none opacity-60",
+            )}
+          >
+            {body}
+          </div>
+          {footer}
         </div>
-        {footer}
         {confirming !== null && (
           <Dialog
             mode="alert"