@softize/opus 19.0.0 → 20.0.0

package/src/ui/docs/content/menu.md

@@ -17,13 +17,58 @@ direita; separe ações perigosas e declare `context="danger"` nelas.
 </Menu>
 ```
 
+`MenuShortcut` só exibe o atalho. Registre a tecla no aplicativo; o menu não a escuta.
+
+## Executar a ação do item
+
+`onSelect` recebe a escolha feita por clique ou teclado. Depois dele, o menu fecha. Para manter o
+painel aberto, como em uma alternância que a pessoa pode repetir, chame `event.preventDefault()` no
+handler. `disabled` mantém o item visível, mas impede a seleção.
+
+```tsx preview
+const [pinned, setPinned] = useState(false)
+const [last, setLast] = useState('Nenhuma ação ainda.')
+
+render(
+  <div className="flex items-center gap-4">
+    <Menu>
+      <MenuTrigger asChild>
+        <Button variant="outline">Sessão <ChevronDown /></Button>
+      </MenuTrigger>
+      <MenuContent align="start">
+        <MenuItem onSelect={() => setLast('Link copiado.')}><Link /> Copiar link</MenuItem>
+        <MenuItem
+          onSelect={(event) => {
+            event.preventDefault()
+            setPinned((current) => !current)
+          }}
+        >
+          {pinned ? <PinOff /> : <Pin />} {pinned ? 'Desafixar' : 'Fixar'}
+        </MenuItem>
+        <MenuItem disabled><Share2 /> Compartilhar</MenuItem>
+      </MenuContent>
+    </Menu>
+    <p className="text-sm text-muted-foreground">{last}</p>
+  </div>,
+)
+```
+
+Para navegar em vez de executar, use `asChild` com um link: o item passa a renderizar o `<a>`,
+com o estilo e a navegação por teclado do menu.
+
+```tsx
+<MenuItem asChild>
+  <a href="/sessoes/42">Abrir sessão</a>
+</MenuItem>
+```
+
 ## Abrir pelo menu de contexto
 
 Para abrir pelo clique direito, controle o estado do menu e use a posição do ponteiro como âncora.
-Esse padrão substitui o antigo `ContextMenu` sem introduzir outra família de componentes.
+Não há componente separado para menu de contexto; use `Menu` controlado.
 
 ```tsx preview
-const [pos, setPos] = useState(null)
+const [pos, setPos] = useState<{ x: number; y: number } | null>(null)
 
 render(
   <div>
@@ -34,7 +79,7 @@ render(
       }}
       className="flex h-28 items-center justify-center rounded-md border border-dashed text-sm text-muted-foreground select-none"
     >
-      clique direito aqui
+      Clique com o botão direito aqui
     </div>
     <Menu open={pos !== null} onOpenChange={(open) => { if (!open) setPos(null) }}>
       <MenuTrigger asChild>
@@ -83,7 +128,8 @@ render(
 
 ## Submenu e inset
 
-MenuSub aninha um nível; inset alinha itens sem ícone com os que têm.
+`MenuSub` aninha um nível: `MenuSubTrigger` abre o painel `MenuSubContent` ao lado do item. `inset`
+alinha itens sem ícone com os que têm.
 
 ```tsx preview
 <Menu>
@@ -93,7 +139,7 @@ MenuSub aninha um nível; inset alinha itens sem ícone com os que têm.
   <MenuContent align="start">
     <MenuItem><ExternalLink /> Abrir preview</MenuItem>
     <MenuSub>
-      <MenuSubTrigger><ArrowDownAZ /> Mover para</MenuSubTrigger>
+      <MenuSubTrigger><FolderInput /> Mover para</MenuSubTrigger>
       <MenuSubContent>
         <MenuItem>Empresa X</MenuItem>
         <MenuItem>Softize</MenuItem>
@@ -104,6 +150,10 @@ MenuSub aninha um nível; inset alinha itens sem ícone com os que têm.
 </Menu>
 ```
 
+`MenuContent` já renderiza o painel em um portal, fora do fluxo da página. `MenuPortal` continua
+exportado, mas está depreciado e sai em uma próxima versão maior: envolver o conteúdo com ele não
+muda onde o painel aparece. Código novo usa só `MenuContent`.
+
 ## Propriedades de Menu
 
 | Propriedade | Tipo | Padrão | Descrição |
@@ -112,10 +162,26 @@ MenuSub aninha um nível; inset alinha itens sem ícone com os que têm.
 | `onOpenChange` | `(open: boolean) => void` | | Chamado quando o painel abre ou fecha. |
 | `defaultOpen` | `boolean` | `false` | Estado inicial no modo não controlado. |
 
+## Propriedades de MenuTrigger
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `asChild` | `boolean` | `false` | Usa o filho, como um `Button`, como gatilho em vez de renderizar outro `<button>`. |
+
+## Propriedades de MenuContent
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alinhamento do painel em relação ao gatilho. |
+| `sideOffset` | `number` | `4` | Distância entre o gatilho e o painel. |
+
 ## Propriedades de MenuItem
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
+| `onSelect` | `(event: Event) => void` | | Chamado quando a pessoa escolhe o item por clique ou teclado. `event.preventDefault()` mantém o menu aberto. |
+| `disabled` | `boolean` | `false` | Mantém o item visível e impede a seleção. |
+| `asChild` | `boolean` | `false` | Renderiza o filho, como um `<a>`, com o comportamento de item de menu. |
 | `context` | `'neutral' \| 'danger'` | `'neutral'` | `danger` sinaliza uma ação com consequência perigosa. |
 | `inset` | `boolean` | | Alinha um item sem ícone com os itens que possuem ícone. |
 
@@ -125,12 +191,11 @@ MenuSub aninha um nível; inset alinha itens sem ícone com os que têm.
 `MenuLabel` para nomear o grupo e `MenuSeparator` para separá-lo do próximo. Não tem props
 próprias além das de DOM.
 
-## Propriedades de MenuContent
+## Propriedades de MenuLabel
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alinhamento do painel em relação ao gatilho. |
-| `sideOffset` | `number` | `4` | Distância entre o gatilho e o painel. |
+| `inset` | `boolean` | | Alinha o rótulo com itens que possuem ícone. |
 
 ## Propriedades de MenuCheckboxItem
 
@@ -153,14 +218,34 @@ próprias além das de DOM.
 | `value` | `string` | | Valor que o item entrega ao `MenuRadioGroup` quando é selecionado. |
 | `disabled` | `boolean` | `false` | Impede a seleção do item. |
 
-## Propriedades de MenuLabel
+## Propriedades de MenuSeparator
+
+`MenuSeparator` desenha a linha entre grupos de itens. Não tem props próprias; aceita as de um
+elemento `div`, como `className`.
+
+## Propriedades de MenuShortcut
+
+`MenuShortcut` exibe o atalho no extremo direito do item. Não tem props próprias; aceita as de um
+elemento `span`, como `className`.
+
+## Propriedades de MenuSub
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `inset` | `boolean` | | Alinha o rótulo com itens que possuem ícone. |
+| `open` | `boolean` | | Estado do submenu no modo controlado. |
+| `onOpenChange` | `(open: boolean) => void` | | Chamado quando o submenu abre ou fecha. |
+| `defaultOpen` | `boolean` | `false` | Estado inicial no modo não controlado. |
 
 ## Propriedades de MenuSubTrigger
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `inset` | `boolean` | | Alinha o gatilho do submenu sem ícone com os itens que possuem ícone. |
+| `disabled` | `boolean` | `false` | Impede que o submenu abra. |
+
+## Propriedades de MenuSubContent
+
+| Propriedade | Tipo | Padrão | Descrição |
+|---|---|---|---|
+| `sideOffset` | `number` | `0` | Distância entre o item que abre o submenu e o painel. |
+| `alignOffset` | `number` | `0` | Deslocamento do painel ao longo do item que o abre. |

package/src/ui/docs/content/metric-card.md

@@ -1,6 +1,6 @@
-MetricCard apresenta uma medida resumida com hierarquia e espaçamento consistentes. Passe o
-valor já calculado e formatado; busca de dados, recorte e regras de negócio permanecem no
-consumidor.
+Use `MetricCard` para apresentar uma medida resumida, como um total ou uma contagem, com rótulo,
+valor e contexto em hierarquia consistente. Passe o valor já calculado e formatado; busca de dados,
+recorte e regras de negócio permanecem no consumidor.
 
 ```tsx preview col
 <MetricCard
@@ -101,6 +101,11 @@ render(
 `active`, `activationLabel` e `onActivate` formam uma capacidade única: informe as três propriedades
 para tornar o card ativável. O consumidor continua responsável pelo estado e pelo recorte aplicado.
 
+O card ativo recebe a borda na cor primária. Ao passar o ponteiro, a borda se destaca, e o foco de
+teclado desenha um anel por dentro da borda. Com ativação, use `onActivate` em vez de `onClick`: o
+tipo recusa `onClick`, porque um clique genérico no card também dispararia ao usar `labelAction` ou
+`action`. Enquanto `loading` estiver ativo, a ativação fica desabilitada.
+
 ## Carregamento
 
 `loading` preserva a geometria do card com placeholders e marca a superfície como ocupada para
@@ -125,7 +130,10 @@ tecnologias assistivas. O contêiner da coleção continua responsável pela men
 | `action`          | `ReactNode`                                                 |             | Ação relacionada diretamente à medida.                                                             |
 | `active`          | `boolean`                                                   |             | Indica se a medida controla o recorte atualmente aplicado. Exige `activationLabel` e `onActivate`. |
 | `activationLabel` | `string`                                                    |             | Nome acessível da ativação. Exige `active` e `onActivate`.                                         |
-| `onActivate`      | `() => void`                                                |             | Ativa a medida como recorte ou seleção. Exige `active` e `activationLabel`.                        |
+| `onActivate`      | `() => void`                                                |             | Ativa a medida como recorte ou seleção. Exige `active` e `activationLabel`; não combina com `onClick`. Desabilitada durante `loading`. |
+| `className`       | `string`                                                    |             | Ajusta o card, ou o contêiner quando há ativação ou medida complementar.                           |
+
+As demais propriedades são as nativas de `div`.
 
 ## Propriedades de MetricCardSecondaryMetric
 

package/src/ui/docs/content/observability.md

@@ -37,20 +37,21 @@ global. Um `Tracer` também pode ser injetado para testes ou providers não glob
 
 ## Semântica
 
-- nomes de span: `opus.action <action>` e `opus.reaction <reaction>`;
-- parent vem de `ContextBase.trace` ou do evento recebido;
-- actions usam `ActionResult.ok` para status; reactions usam resolve/reject;
-- somente atributos allowlisted de baixa cardinalidade são anexados;
-- input, output, actor, tenant, request ID, error code/message e baggage não entram no span;
+- Os spans se chamam `opus.action <action>` e `opus.reaction <reaction>`.
+- O span pai vem de `ContextBase.trace` ou do evento recebido.
+- Actions usam `ActionResult.ok` para o status; reactions usam a resolução ou a rejeição da Promise.
+- Somente atributos de baixa cardinalidade, de uma lista fixa, são anexados.
+- Input, output, ator, tenant, request ID, código e mensagem de erro e baggage não entram no span.
 - `TraceContext` devolve apenas `traceId`, `spanId`, `traceFlags` e `traceState`.
 
 ## Fronteira HTTP W3C
 
-Os drivers Fastify e Node oferecem propagação explícita, desativada por default:
+Os drivers Fastify e Node oferecem propagação explícita, desativada por padrão:
 
 ```ts
-fastifyServer({ app, traceContext: 'w3c' })
-nodeServer({ traceContext: 'w3c' })
+const server = fastifyServer({ app, traceContext: 'w3c' })
+// nodeServer devolve { adapter, handler, hasRoute }; o runtime recebe `adapter`.
+const node = nodeServer({ traceContext: 'w3c' })
 ```
 
 O opt-in extrai um `traceparent` v00 válido (e `tracestate` limitado) para
@@ -65,7 +66,7 @@ O driver OpenTelemetry não instrumenta HTTP automaticamente e não oferece back
 Use o opt-in dos drivers Fastify/Node acima ou forneça `ContextBase.trace` na instrumentação
 de outro transporte. A fronteira implementa somente `traceparent` v00 e uma validação
 defensiva limitada de `tracestate`; não é um propagator OTel genérico.
-Health do exporter/Collector só é reportado quando o app injeta `healthCheck`; o default
+A saúde do exporter e do Collector só é reportada quando o app injeta `healthCheck`; o padrão
 confirma apenas que a API do driver está configurada.
 Sem um provider que produza spans válidos, o driver falha antes do callback e o runtime aplica
 a degradação lenient — executa a action uma vez, sem trace — em vez de propagar IDs inválidos.

package/src/ui/docs/content/page.md

@@ -13,9 +13,8 @@ A forma curta é o padrão para páginas comuns. Fora de `PageShell`, ela cria `
 `PageBody`. Dentro dele, cria `PageHeader` para as ações, `PageIntro` para o título e `PageBody`.
 A forma explícita exige exatamente um heading principal. Use `PageTitle` no header ou intro,
 `Content level={1}` no body, ou deixe um `PageState` ativo assumir esse papel. Assim, header e
-introdução podem ser omitidos quando o próprio conteúdo nomeia a página.
-Contadores e outros indicadores pertencem ao
-conteúdo que os explica.
+introdução podem ser omitidos quando o próprio conteúdo nomeia a página. Contadores e outros
+indicadores pertencem ao conteúdo que os explica.
 
 A `Page` é contínua por definição: separar o chrome do conteúdo é trabalho do shell, e não há
 divisores entre regiões para declarar. O `layout` da `Page` não é a anatomia de superfície de
@@ -51,7 +50,8 @@ render(
 
 Use `PageBack` em uma subpágina simples. O destino é explícito para continuar correto após refresh ou
 acesso por link direto; não derive esse retorno do histórico do navegador. No header padrão, o
-controle aparece antes do título como ícone com nome acessível e tooltip derivados do destino.
+controle aparece antes do título como ícone; o nome acessível e a dica nativa do navegador (atributo
+`title`) derivam do destino.
 
 ```tsx preview col
 <Page>
@@ -64,8 +64,30 @@ controle aparece antes do título como ícone com nome acessível e tooltip deri
 ```
 
 Não combine `PageBack` com breadcrumb. Use o retorno para um único pai conhecido. Quando houver
-mais de um ancestral relevante, envolva o `Breadcrumb` em `PageNavigation`; ele ocupa a mesma
-posição introdutória sem transformar a trilha em ação.
+mais de um ancestral relevante, envolva o [`Breadcrumb`](/ui/breadcrumb) em `PageNavigation`; ele
+ocupa a mesma posição introdutória sem transformar a trilha em ação.
+
+```tsx preview col
+<Page>
+  <PageHeader>
+    <PageNavigation>
+      <Breadcrumb>
+        <BreadcrumbList>
+          <BreadcrumbItem>Vendas</BreadcrumbItem>
+          <BreadcrumbSeparator />
+          <BreadcrumbItem>Clientes</BreadcrumbItem>
+          <BreadcrumbSeparator />
+          <BreadcrumbPage>Carla Souza</BreadcrumbPage>
+        </BreadcrumbList>
+      </Breadcrumb>
+    </PageNavigation>
+  </PageHeader>
+  <PageIntro>
+    <PageTitle>Carla Souza</PageTitle>
+  </PageIntro>
+  <PageBody>Dados do cliente.</PageBody>
+</Page>
+```
 
 ## Barra persistente do shell
 
@@ -149,8 +171,87 @@ render(
 
 Fora de `PageShell`, use `PageIntro` quando o conteúdo precisar de uma introdução separada do
 chrome. Dentro do shell, ele pode ser combinado com `PageHeader`: o primeiro permanece no conteúdo
-e o segundo alimenta a barra. Em uma página de listagem, `Content` pode fornecer o título e as ações
-da coleção, deixando `Page` apenas com `PageBody`.
+e o segundo alimenta a barra. Em uma página de listagem, [`Content`](/ui/content) pode fornecer o
+título e as ações da coleção, deixando `Page` apenas com `PageBody`.
+
+## Ações de etapa no rodapé
+
+Use `PageFooter` quando a página for uma etapa de um fluxo e a decisão precisar ficar ao alcance ao
+fim do conteúdo, como confirmar uma importação. O rodapé fica depois do body, com a mesma altura da
+barra e as ações alinhadas no fim da linha.
+
+```tsx preview col
+<Page>
+  <PageHeader>
+    <PageTitle>Importar clientes</PageTitle>
+  </PageHeader>
+  <PageBody>Revise os 128 registros antes de confirmar.</PageBody>
+  <PageFooter>
+    <ButtonGroup mode="spaced">
+      <Button variant="ghost">Cancelar</Button>
+      <Button>Importar</Button>
+    </ButtonGroup>
+  </PageFooter>
+</Page>
+```
+
+## Ocupar a altura disponível
+
+Use `layout="fill"` quando uma região interna, como uma tabela longa ou um split, precisar rolar
+dentro da página em vez de a página inteira rolar. A página passa a ocupar exatamente a altura do
+contêiner. Para uma região que você mesmo compõe, dê `min-h-0 flex-1` à que assume a folga e a
+rolagem, como o `PageBody` do exemplo.
+
+```tsx preview col
+render(
+  <div className="h-72 overflow-hidden rounded-lg border border-border">
+    <Page layout="fill">
+      <PageHeader>
+        <PageTitle>Ordens de serviço</PageTitle>
+      </PageHeader>
+      <PageBody className="min-h-0 flex-1 space-y-2 overflow-y-auto">
+        {['OS-1842', 'OS-1839', 'OS-1835', 'OS-1830', 'OS-1827', 'OS-1821', 'OS-1818'].map((id) => (
+          <div key={id} className="rounded-md border border-border p-3 text-sm">
+            {id}
+          </div>
+        ))}
+      </PageBody>
+    </Page>
+  </div>,
+);
+```
+
+Uma [`ActionList`](/ui/action-list) não precisa dessas classes. Filha de `PageBody`, ou de um
+[`Content`](/ui/content) dentro dele, ela recebe a altura da página e assume `layout="fill"`
+sozinha: `PageBody`, `Content` e `ContentBody` passam a repassar a altura até ela, o cabeçalho da
+tabela fica fixo e só os resultados rolam. As demais seções do `PageBody` mantêm a altura do
+próprio conteúdo, e uma página `fill` sem lista não muda.
+
+## Levar as ações para outra barra
+
+`PageShell` já projeta as ações na barra persistente. Use `PageActionsTarget` somente quando um
+hospedeiro próprio tiver outra barra para elas: as `PageActions` da árvore interna passam a ser
+renderizadas no elemento indicado em `target`. Enquanto `target` for `null`, fora de um shell, as
+ações continuam no cabeçalho da página.
+
+```tsx preview col
+function Example() {
+  const [target, setTarget] = useState<HTMLElement | null>(null)
+
+  return (
+    <div className="space-y-3">
+      <div ref={setTarget} className="flex justify-end rounded-lg border border-border p-2" />
+      <PageActionsTarget target={target}>
+        <Page title="Clientes" actions={<Button variant="outline">Exportar</Button>}>
+          Conteúdo da listagem.
+        </Page>
+      </PageActionsTarget>
+    </div>
+  )
+}
+
+render(<Example />)
+```
 
 ## Estados integrais
 
@@ -195,7 +296,8 @@ e, sem `title`, valem `errorMessage` e `emptyMessage`.
 ```
 
 Não use `PageState` para uma falha parcial. Se outra parte da página continua utilizável, mantenha o
-estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert`.
+estado na própria seção com [`DataState`](/ui/data-state), [`ActionView`](/ui/action-view),
+[`ActionList`](/ui/action-list) ou [`Alert`](/ui/alert).
 
 ## Propriedades de Page
 
@@ -203,9 +305,10 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 | ----------- | ----------- | ----------- | ----------------------------------------------------------------------------------------------- |
 | `title`     | `ReactNode` |             | O h1 da página.                                                                                 |
 | `actions`   | `ReactNode` |             | Ações contextuais no extremo oposto do cabeçalho. |
-| `layout`    | `'flow' \| 'fill'` | `'flow'` | Ocupação de altura, não anatomia: `fill` limita a página ao shell para que uma região interna role. |
+| `layout`    | `'flow' \| 'fill'` | `'flow'` | Ocupação de altura, não anatomia: `fill` limita a página ao shell para que uma região interna role e leva essa altura até uma `ActionList` composta em `PageBody`. |
 | `className` | `string`    | `max-w-7xl` | Classes do container para substituir o teto padrão de `80rem`.                                  |
 | `children`  | `ReactNode` |             | O body da página — espaçamento e diagramação são seus.                                          |
+| demais      | Atributos de `HTMLElement` |  | Atributos nativos repassados ao elemento `main`, como `id` ou `aria-label`. `className` vai para o container interno. |
 
 ## Propriedades de PageShell
 
@@ -242,7 +345,7 @@ que o shell projeta na barra, e ignora `className` e os demais atributos.
 | Propriedade  | Tipo                                   | Padrão                   | Descrição                                                                                  |
 | ------------ | -------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------ |
 | `href`       | `string`                               | obrigatório              | Destino explícito da página pai. Sem ele o retorno não é tabulável nem tem nome acessível. |
-| `children`   | `ReactNode`                            | obrigatório              | Nome do destino pai usado no rótulo acessível e no tooltip.                                |
+| `children`   | `ReactNode`                            | obrigatório              | Nome do destino pai usado no rótulo acessível e na dica nativa (`title`).                   |
 | `aria-label` | `string`                               | `Voltar para {children}` | Nome acessível; informe-o quando `children` não for texto simples.                         |
 | `onClick`    | `MouseEventHandler<HTMLAnchorElement>` |                          | Integração opcional com o roteador do consumidor, junto do `href`, nunca no lugar dele.    |
 | `className`  | `string`                               |                          | Classes adicionais do link renderizado como botão `ghost`.                                 |
@@ -259,7 +362,7 @@ que o shell projeta na barra, e ignora `className` e os demais atributos.
 
 | Propriedade | Tipo                              | Descrição                                       |
 | ----------- | --------------------------------- | ----------------------------------------------- |
-| `children`  | `ReactNode`                       | Título principal `h1`; ampliado em `PageIntro`. |
+| `children`  | `ReactNode`                       | Título principal `h1`, com a mesma escala em `PageHeader` e `PageIntro`. |
 | `className` | `string`                          | Classes adicionais do título.                   |
 | demais      | Atributos de `HTMLHeadingElement` | Atributos nativos repassados ao heading.        |
 
@@ -287,6 +390,9 @@ que o shell projeta na barra, e ignora `className` e os demais atributos.
 | `className` | `string`                      | Classes adicionais da região principal.    |
 | demais      | Atributos de `HTMLDivElement` | Atributos nativos repassados ao container. |
 
+Em uma `Page` com `layout="fill"`, o `PageBody` vira coluna flexível sozinho quando contém uma `ActionList` que
+ocupa a altura.
+
 ## Propriedades de PageActionsTarget
 
 | Propriedade | Tipo                  | Descrição                                                    |

package/src/ui/docs/content/pagination.md

@@ -1,9 +1,12 @@
 ## Navegação entre páginas
 
-Componha `Pagination`, `PaginationContent` e um `PaginationItem` para cada link. `page` fornece o
+Use `Pagination` quando uma coleção for dividida em páginas e a pessoa precisar saltar entre elas.
+Em uma listagem derivada de uma action, [`ActionList`](/ui/action-list) já monta esta paginação no
+rodapé; componha-a diretamente apenas em coleções próprias.
+
+Monte `Pagination`, `PaginationContent` e um `PaginationItem` para cada link. `page` fornece o
 número e o nome acessível; `isActive` identifica a página atual. Os controles mantêm altura fixa e
-a largura cresce quando o número precisa de mais espaço. `ActionList` usa esta mesma primitiva no
-rodapé.
+a largura cresce quando o número precisa de mais espaço.
 
 ```tsx preview
 <Pagination>
@@ -30,8 +33,9 @@ rodapé.
 ## Números longos
 
 A largura mínima é quadrada e cresce conforme o conteúdo. Na escala densa de um rodapé, as setas e a
-elipse usam `size="icon-sm"` (o quadrado de 1.75rem da escala única, com o glifo de 0.875rem); os
-números, que não têm um degrau de 1.75rem na escala, ajustam por `className` (`h-7 min-w-7 text-xs`).
+elipse usam `size="icon-sm"`, o quadrado de `1.75rem` da escala única, com ícone de `0.875rem`. Os
+números não têm um degrau textual de `1.75rem` na escala e, por isso, recebem a mesma medida por
+`className`, como no exemplo.
 
 ```tsx preview
 <Pagination>
@@ -148,3 +152,7 @@ render(
 |---|---|---|---|
 | `size` | `'icon-xs' \| 'icon-sm' \| 'icon' \| 'icon-lg'` | `'icon'` | Quadrado da escala única; use o mesmo tamanho das setas ao lado. |
 | `className` | `string` | | Classes adicionais aplicadas à elipse. |
+
+`Pagination` renderiza um `<nav>` com o nome acessível “Paginação”, `PaginationContent` um `<ul>` e
+`PaginationItem` um `<li>`. Os três não têm propriedades próprias e aceitam as props nativas do
+respectivo elemento, incluindo `className`.

package/src/ui/docs/content/pane.md

@@ -62,11 +62,55 @@ render(
 
 O cabeçalho reconhece quatro slots — `PaneMedia`, `PaneTitle`, `PaneDescription` e `PaneActions` —
 e monta a linha sozinho: mídia, título e descrição de um lado, ações no extremo oposto. A ordem em
-que os slots são escritos não altera a posição, e um nó que não seja um desses slots interrompe a
-renderização com um erro. Conteúdo livre vai para `PaneBody`.
+que os slots são escritos não altera a posição. Cada slot aparece no máximo uma vez: repetir um
+deles interrompe a renderização com um erro que lista os slots aceitos.
 
 Título e descrição truncam quando a coluna encolhe, em vez de quebrar a altura da faixa.
 
+Nas ações do cabeçalho, use `Button` `ghost` no tamanho `icon-sm` (1.75rem), como nos exemplos. O
+pane é uma superfície densa, com título e descrição em escala menor, e o quadrado menor acompanha
+essa escala. [`Dialog`](/ui/dialog) e [`Drawer`](/ui/drawer) usam `icon` (2.25rem) no voltar e nas
+ações do cabeçalho, e a [`Presentation`](/ui/presentation) usa o mesmo tamanho no voltar e no botão
+que abre o assistente.
+
+## Busca ou marca no cabeçalho
+
+Uma coluna às vezes precisa, no topo, de algo que não é título nem ação: uma busca que filtra a
+lista, a marca de uma barra lateral. Escreva esse conteúdo direto dentro do `PaneHeader`, ao lado
+dos slots. Só o `Pane` aceita conteúdo livre no cabeçalho; os headers de `Card`, `Dialog` e `Drawer`
+aceitam apenas os próprios slots.
+
+```tsx preview
+render(
+  <div className="h-56 overflow-hidden rounded-lg border border-border">
+    <Split>
+      <Pane initialSize="18rem">
+        <PaneHeader>
+          <Input icon={<Search />} placeholder="Buscar conversa" aria-label="Buscar conversa" />
+          <PaneActions>
+            <Button variant="ghost" size="icon-sm" aria-label="Nova conversa">
+              <SquarePen />
+            </Button>
+          </PaneActions>
+        </PaneHeader>
+        <PaneBody className="space-y-1">
+          <p className="text-sm">Revisão do contrato</p>
+          <p className="text-sm text-muted-foreground">Importação de clientes</p>
+        </PaneBody>
+      </Pane>
+      <Pane grow>
+        <p className="text-sm text-muted-foreground">Conversa selecionada.</p>
+      </Pane>
+    </Split>
+  </div>,
+);
+```
+
+O conteúdo livre ocupa o lugar do título e absorve a largura disponível, por isso as ações
+continuam no extremo oposto. Quando há título, o conteúdo livre vem sempre depois do título e da descrição,
+qualquer que seja a ordem no JSX: uma busca escrita junto de um `PaneTitle` aparece abaixo dele, não
+ao lado. Para algo antes do título, use `PaneMedia`; para algo ao lado, use `PaneActions`.
+
 ## Escolher entre seccionado e contínuo
 
 `layout` declara a anatomia da superfície inteira e fica no root; os slots leem esse valor e não o
@@ -86,6 +130,11 @@ Os divisores são derivados da vizinhança: cada região desenha a linha quando
 lado. Um cabeçalho sem corpo não fecha nada, e um cabeçalho seguido direto de um rodapé produz uma
 linha só. A tela não escreve `border-b` nem `border-t`.
 
+No `continuous`, um cabeçalho sem corpo nem rodapé fecha o pane com o mesmo recuo que tem em cima.
+Uma classe `pb-*` no `PaneHeader` não altera esse recuo: a regra só vale quando o cabeçalho é a
+última região e tem precedência sobre o `className`. No `sectioned`, a faixa tem altura fixa e
+centraliza a linha, então não há recuo de baixo a ajustar.
+
 ## Recuo do pane e recuo das regiões
 
 `inset` é o respiro interno do pane sem slots: `md` por padrão, com `none`, `sm` e `lg`
@@ -99,11 +148,12 @@ O ajuste enxerga só o primeiro nível. Se os slots vierem dentro de outro compo
 
 ## A matriz de layouts e slots
 
-As regiões são independentes e o recuo se ajusta a cada combinação, nos dois layouts.
+As regiões são independentes: a coluna usa só as que precisa, nos dois layouts, e os divisores
+acompanham as regiões presentes.
 
 ```tsx preview col
 render(
-  <div className="grid gap-4 md:grid-cols-2">
+  <div className="grid grid-cols-2 gap-4">
     <div className="h-56 overflow-hidden rounded-lg border border-border">
       <Pane className="h-full">
         <PaneHeader>
@@ -198,7 +248,7 @@ documento não muda a aparência da faixa.
 
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
-| `children` | `ReactNode` | | Somente `PaneMedia`, `PaneTitle`, `PaneDescription` e `PaneActions`, no máximo um de cada. |
+| `children` | `ReactNode` | | `PaneMedia`, `PaneTitle`, `PaneDescription` e `PaneActions`, no máximo um de cada, e conteúdo livre, que aparece depois do título e da descrição. |
 | `className` | `string` | | Ajusta a faixa fixa sobre o recuo do layout. |
 
 ## Propriedades de PaneMedia