@softize/opus 14.0.0 → 15.0.0

package/src/ui/docs/content/action-trigger.md

@@ -37,8 +37,9 @@ confirm: {
 
 ## Ação somente com ícone
 
-Com `icon`, o botão exibe somente o ícone no quadrado `icon-sm` da escala (1.75rem, a ação que mora
-dentro de uma linha ou card) e usa `label`, ou `action.label`, no tooltip e no nome acessível. O clique
+Com `icon`, o botão exibe somente o ícone no quadrado `icon-xs` da escala (1.5rem, a ação que mora
+dentro de uma linha ou card) e usa `label`, ou `action.label`, no tooltip e no nome acessível. Uma
+composição que peça mais presença, como a barra do `PageHeader`, declara `size="icon-sm"`. O clique
 não aciona o item clicável ao redor. `itemLabel` identifica o registro na mensagem de confirmação.
 
 ```tsx
@@ -83,4 +84,4 @@ um atalho, um arrastar, um item de menu.
 | `onSuccess` | `(data: TData) => void` | | Pós-sucesso (cache já invalidado pelo action.invalidates). |
 | `icon` | `React.ReactNode` | | Torna o botão icon-only: rótulo no tooltip e no `aria-label`, clique que não vaza para o item. |
 | `itemLabel` | `string` | | Nome do alvo na pergunta (sai entre aspas, em destaque, antes da mensagem do contrato). |
-| `className` | `string` | | Classes do botão. O tamanho vem de `size` (escala única); com `icon` é sempre `icon-sm`. |
+| `className` | `string` | | Classes do botão. O tamanho vem de `size` (escala única); com `icon`, o default é `icon-xs`. |

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

@@ -54,6 +54,11 @@ Quando a mensagem precisa de conteúdo rico, componha os slots da família. `Ale
 `AlertDescription` pertencem ao header. As ações ficam no fim lógico da superfície e centralizadas
 verticalmente na mesma linha do conteúdo — a mesma posição usada pelas ações do Toast.
 
+Use `ghost` como tratamento padrão para ações dentro do alert: a mensagem já fornece a superfície e
+o botão não precisa desenhar outra moldura. Mantenha texto quando a ação expressa um resultado
+específico. Para tentar novamente, recarregar ou repetir a operação descrita pelo aviso, prefira um
+botão só com ícone, nome acessível e tooltip.
+
 ```tsx preview col
 <Alert context="danger">
   <AlertMedia>
@@ -67,9 +72,16 @@ verticalmente na mesma linha do conteúdo — a mesma posição usada pelas aç
     </AlertDescription>
   </AlertHeader>
   <AlertActions>
-    <Button size="sm">
-      Tentar novamente
-    </Button>
+    <TooltipProvider>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button variant="ghost" size="icon" aria-label="Tentar novamente">
+            <RefreshCw />
+          </Button>
+        </TooltipTrigger>
+        <TooltipContent>Tentar novamente</TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
   </AlertActions>
 </Alert>
 ```
@@ -83,7 +95,7 @@ ação.
   title="Sessão presa"
   description="O ambiente não subiu no tempo esperado."
 >
-  <Button size="sm">
+  <Button variant="ghost">
     Reiniciar
   </Button>
 </Alert>

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

@@ -27,8 +27,8 @@ há texto visível. O glifo dentro do controle acompanha o tamanho (0.875rem em
 | `sm` | 2rem | Toolbar e cabeçalho densos, ao lado de `Select` e `Tabs` `sm`. |
 | `default` | 2.25rem | A linha padrão, a mesma de `Input`. |
 | `lg` | 2.5rem | Chamada principal com mais área de toque. |
-| `icon-xs` | 1.5rem | Ação só de ícone dentro de um campo, como o `trailing` de Input ou Select. |
-| `icon-sm` | 1.75rem | Ação só de ícone dentro de uma linha ou card; é o quadrado de `ActionTrigger` com `icon` e das setas do pager de `ActionList`. |
+| `icon-xs` | 1.5rem | Ação só de ícone dentro de um campo ou de uma linha densa; é o quadrado de `ActionTrigger` com `icon`. |
+| `icon-sm` | 1.75rem | Ação só de ícone em composições compactas que precisam de mais presença; também é o quadrado das setas do pager de `ActionList`. |
 | `icon` | 2.25rem | Ação só de ícone na linha padrão. |
 | `icon-lg` | 2.5rem | Ação só de ícone ao lado de um `lg`. |
 
@@ -80,9 +80,9 @@ buttonVariants serve para o caso sem filho único.
 
 ## ButtonGroup
 
-Use `ButtonGroup` quando ações relacionadas precisarem formar um bloco contínuo. As bordas internas
-colapsam e somente as pontas externas permanecem arredondadas. Mantenha a mesma variante nos filhos
-para preservar a unidade visual.
+Use `ButtonGroup` para manter ações relacionadas juntas. No modo `connected`, que permanece como
+padrão, as bordas internas colapsam e somente as pontas externas ficam arredondadas. Mantenha a
+mesma variante nos filhos para preservar a unidade visual.
 
 ```tsx preview
 <ButtonGroup>
@@ -92,6 +92,20 @@ para preservar a unidade visual.
 </ButtonGroup>
 ```
 
+### Ações espaçadas
+
+Use `mode="spaced"` quando os controles pertencem ao mesmo conjunto, mas cada um precisa preservar
+sua própria forma e superfície de hover. O grupo aplica o intervalo compacto de `0.25rem` sem
+conectar bordas. Esse modo atende ações icon-only em barras e linhas de listagem.
+
+```tsx preview
+<ButtonGroup mode="spaced">
+  <Button variant="ghost" size="icon" aria-label="Recarregar"><RotateCw /></Button>
+  <Button variant="ghost" size="icon" aria-label="Exibição"><SlidersHorizontal /></Button>
+  <Button context="primary" size="icon" aria-label="Novo item"><Plus /></Button>
+</ButtonGroup>
+```
+
 ### Ação dividida
 
 Combine a ação principal, um separador e um botão de ícone quando o mesmo comando oferecer
@@ -139,6 +153,7 @@ semântica de outro elemento, como `label`.
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direção do bloco e do colapso das bordas. |
+| `mode` | `'connected' \| 'spaced'` | `'connected'` | Conecta as bordas dos controles ou preserva cada controle com intervalo compacto. |
 | `shape` | `'default' \| 'pill'` | `'default'` | Geometria das extremidades externas do grupo. |
 
 ### Propriedades de ButtonGroupSeparator

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

@@ -22,8 +22,8 @@ render(
 
 Use os slots quando o header precisar de composição própria. A árvore aceita exatamente um
 `ContentHeader` e um `ContentBody` como filhos diretos. O header exige um `ContentTitle` e aceita
-uma descrição, um contador (`ContentMeta`) e uma região de ações — a mesma anatomia de `PageHeader`,
-com os mesmos slots e o mesmo layout; só o nível do heading e a hierarquia visual mudam.
+uma descrição, um contador (`ContentMeta`) e uma região de ações. O contador é próprio de
+`Content`; `PageHeader` reconhece somente título, descrição e ações.
 
 ```tsx preview col
 render(
@@ -49,7 +49,7 @@ do pai correto, filhos estruturais indiretos e a mistura de shorthand com compos
 | Propriedade | Tipo | Padrão | Descrição |
 |---|---|---|---|
 | `title` | `ReactNode` | | Forma curta: título da região (vira o heading ligado à `section`). |
-| `count` | `number` | | Forma curta: total de itens ao lado do título — o mesmo `count` de `Page`. |
+| `count` | `number` | | Forma curta: total de itens ao lado do título da região. |
 | `description` | `ReactNode` | | Forma curta: frase de apoio sob o título. |
 | `actions` | `ReactNode` | | Forma curta: ações alinhadas à direita do header. |
 | `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | herdado | Nível semântico do heading, independente do destaque visual. |

package/src/ui/docs/content/data-state.md

@@ -4,8 +4,8 @@ Use `DataState` para apresentar carregamento, erro, vazio e conteúdo de uma mes
 superfícies são as mesmas de `PageState`, na escala de uma seção: o carregamento é um contêiner
 `role="status"` com o `Spinner`; o vazio compõe `Empty` com moldura sólida e `emptyMessage` como
 título; o erro é um `Alert` de contexto `danger` com uma mensagem segura, sem expor detalhes
-técnicos, e o botão de recuperação quando há `onRetry`. Para uma ação em andamento depois do
-clique, use `busy` em `Button`.
+técnicos, e uma ação `ghost` só com ícone quando há `onRetry`. `retryLabel` fornece o nome acessível
+e o tooltip dessa ação. Para uma ação em andamento depois do clique, use `busy` em `Button`.
 
 ```tsx preview col
 <div className="w-full space-y-3">
@@ -48,6 +48,6 @@ disponível para criação ou vínculo, use `Empty` diretamente, com a moldura t
 | `emptyMessage` | `string` | `'Nada por aqui.'` | Frase do vazio (ex.: "Nenhum papel."). |
 | `error` | `{ message?: string } \| null` | | Erro da carga — aviso calmo. A mensagem técnica não vai para tela (use `errorMessage`). |
 | `errorMessage` | `string` | `'Não foi possível carregar.'` | Título do aviso de erro, orientado à pessoa. |
-| `onRetry` | `() => void \| Promise<void>` | | Recuperação: mostra o botão de tentar de novo no estado de erro. |
-| `retryLabel` | `string` | `'Tentar de novo'` | Rótulo do botão de recuperação. |
+| `onRetry` | `() => void \| Promise<void>` | | Recuperação: mostra a ação de tentar de novo somente com ícone no estado de erro. |
+| `retryLabel` | `string` | `'Tentar de novo'` | Nome acessível e tooltip da ação de recuperação. |
 | `colSpan` | `number` | | Em tabela: renderiza o estado como `<tr><td colSpan>` (cabe direto no tbody). |

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

@@ -1,22 +1,22 @@
 ## Esqueleto de página
 
-Use `Page` para manter título, contexto, ações e conteúdo no mesmo ritmo visual nas telas do
-back-office. Em larguras amplas, as ações ficam no extremo oposto e acompanham a base do conjunto
-formado pelo título e pela descrição; em larguras estreitas, passam para uma linha abaixo do
-contexto. O container é centralizado e ocupa a largura disponível até `80rem` (`max-w-7xl`). Use
-`className` somente quando a composição pedir explicitamente outro teto ou largura total. A área
-abaixo do cabeçalho permanece livre para tabelas, cards ou outras composições.
+Use `Page` para manter navegação contextual, título, ações e conteúdo na mesma anatomia. O
+`PageHeader` padrão acompanha o conteúdo dentro do container; `variant="bar"` transforma o mesmo
+cabeçalho em uma faixa compacta no topo. Não monte um chrome paralelo para repetir essas regiões.
+
+Em larguras amplas, as ações ficam no extremo oposto e acompanham a base do título e da descrição;
+em larguras estreitas, passam para uma linha abaixo. O container é centralizado e ocupa a largura
+disponível até `80rem` (`max-w-7xl`). Use `className` somente quando a composição pedir outro teto
+ou largura total.
 
 A forma curta é o padrão para páginas comuns. Ela cria internamente `PageHeader` e `PageBody`;
 portanto, não produz uma estrutura visual ou semântica diferente da forma explícita. O cabeçalho é a
-mesma anatomia de `Content` (título, contador, descrição e ações): o que muda entre os dois é o nível
-do heading e a hierarquia visual.
+mesma base estrutural de `Content`, mas reconhece somente título, descrição e ações. Contadores e
+outros indicadores pertencem ao conteúdo que os explica.
 
-`Page` é o esqueleto de páginas e recursos delimitados. Ele também pode ocupar o painel principal
-de um shell com sidebar; a navegação lateral não exige remover o teto nem reconstruir o cabeçalho.
-Uma navegação contextual para outra página pode ocupar `actions`, e tabs ficam reservados a
+`Page` também pode ocupar o painel principal de um shell com sidebar. Tabs ficam reservados a
 recortes da mesma superfície. Canvas e outros workspaces espaciais imersivos podem usar um shell
-próprio quando o cabeçalho reduzir a área útil ou duplicar controles persistentes da superfície.
+próprio quando o cabeçalho reduzir a área útil ou duplicar controles persistentes.
 
 Estados integrais de carregamento, falha ou ausência são compostos no body com `PageState`,
 detalhado abaixo. `Page` não recebe flags de dados: uma página pode agregar fontes independentes e
@@ -27,7 +27,6 @@ render(
   <div className="w-full overflow-hidden rounded-lg border border-border">
     <Page
       title="Workspaces"
-      count={3}
       description="Ambientes compartilhados pela equipe."
       actions={
         <Button>
@@ -40,16 +39,58 @@ render(
       </div>
     </Page>
   </div>,
-)
+);
 ```
 
-## Ações no chrome do shell
+## Retorno para a página pai
+
+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 acima do título com ícone e rótulo.
 
-Quando o shell reserva uma barra própria para contexto e ações, envolva sua região de conteúdo com
-`PageActionsTarget` e passe o elemento de destino em `target`. As ações declaradas em `Page`
-continuam pertencendo semanticamente ao cabeçalho da página, mas são projetadas nesse elemento.
-Com `target={null}`, elas permanecem na posição padrão; isso permite montar o alvo por `ref` sem
-uma renderização intermediária inconsistente.
+```tsx preview col
+<Page>
+  <PageHeader>
+    <PageBack href="/customers">Clientes</PageBack>
+    <PageTitle>Qualidade da base</PageTitle>
+    <PageDescription>Revise conflitos e canais de contato.</PageDescription>
+  </PageHeader>
+  <PageBody>Conteúdo da análise.</PageBody>
+</Page>
+```
+
+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.
+
+## Cabeçalho em barra
+
+Use `variant="bar"` quando título, retorno e ações precisarem formar uma faixa compacta e persistente
+no topo da página. `Page` estende a borda por toda a largura e mantém o conteúdo da barra alinhado ao
+mesmo teto do body. Nesse modo, `PageBack` vira icon-only e recebe tooltip e nome acessível “Voltar
+para {destino}”. Mantenha também as ações compactas: use `sm` em botões com texto e `icon-sm` em
+botões que exibem somente um ícone.
+
+```tsx preview col
+<Page className="max-w-none">
+  <PageHeader variant="bar">
+    <PageBack href="/customers">Clientes</PageBack>
+    <PageTitle>Qualidade da base</PageTitle>
+    <PageActions>
+      <Button variant="ghost" size="icon-sm" aria-label="Mais ações">
+        <Ellipsis />
+      </Button>
+    </PageActions>
+  </PageHeader>
+  <PageBody>Conteúdo da análise.</PageBody>
+</Page>
+```
+
+Uma página comum não ganha a barra apenas por estar dentro de um shell. Escolha essa variante quando
+a faixa acrescentar contexto ou ações persistentes; sem isso, mantenha o header padrão.
+
+`PageActionsTarget` continua disponível para um workspace imersivo que já possua um chrome próprio.
+Ele projeta somente `PageActions` no elemento informado; não cria uma segunda região de cabeçalho.
 
 ## Composição explícita
 
@@ -61,9 +102,12 @@ render(
   <Page>
     <PageHeader>
       <PageTitle>Workspaces</PageTitle>
-      <PageMeta>3</PageMeta>
       <PageDescription>Ambientes compartilhados pela equipe.</PageDescription>
-      <PageActions><Button><Plus /> Novo workspace</Button></PageActions>
+      <PageActions>
+        <Button>
+          <Plus /> Novo workspace
+        </Button>
+      </PageActions>
     </PageHeader>
     <PageBody>
       <div className="rounded-lg border border-dashed border-border p-10 text-center">
@@ -71,15 +115,18 @@ render(
       </div>
     </PageBody>
   </Page>,
-)
+);
 ```
 
 ## Estados integrais
 
 Use `PageState` quando carregamento, falha ou ausência substituírem todo o conteúdo principal. Na
 forma curta ele pode ser escrito como filho direto de `Page`, que cria o `PageBody`; na forma
-explícita, coloque-o dentro de `PageBody`. O cabeçalho continua visível e o estado recebe composição,
-altura e semântica acessível consistentes.
+explícita, coloque-o sozinho dentro de `PageBody`. Enquanto `status` for `loading`, `error` ou
+`empty`, `Page` oculta o cabeçalho e o estado ocupa a altura disponível. O título do estado assume o
+heading principal. Esse registro também funciona quando um componente intermediário decide qual
+`PageState` renderizar. Em `ready`, o cabeçalho e o conteúdo voltam à composição normal. O cabeçalho some inteiro, incluindo o `PageBack`: uma subpágina que dependa desse retorno
+oferece a saída pelo `action` do próprio `PageState` (ADR 0004, adendo).
 
 ```tsx preview col
 <Page title="Relatório">
@@ -87,15 +134,18 @@ altura e semântica acessível consistentes.
     status="error"
     title="Não foi possível carregar o relatório"
     description="Tente novamente. Se o problema continuar, volte mais tarde."
-    action={<Button>Tentar novamente</Button>}
+    onRetry={() => {}}
+    retryLabel="Tentar novamente"
   />
 </Page>
 ```
 
-`loading` centraliza o `Spinner` num contêiner `role="status"`; `error` compõe `Alert` com o botão
-de recuperação quando há `onRetry`; `empty` compõe `Empty`; e `ready` entrega os filhos sem
-acrescentar uma superfície. São as mesmas superfícies de `DataState`, na escala da página: `title`
-e `description` nomeiam a situação e, sem `title`, valem `errorMessage` e `emptyMessage`.
+`loading` centraliza o `Spinner` num contêiner `role="status"`; `error` usa a mesma anatomia visual
+centralizada dos outros estados, conserva `role="alert"` e oferece uma ação `outline` textual quando
+há `onRetry`; `empty` centraliza `Empty` sem moldura; e `ready` entrega os filhos sem
+acrescentar uma superfície. A moldura tracejada continua reservada ao `Empty` usado diretamente para
+representar uma região disponível para criar ou vincular. `title` e `description` nomeiam a situação
+e, sem `title`, valem `errorMessage` e `emptyMessage`.
 
 ```tsx preview col
 <Page title="Relatórios">
@@ -115,24 +165,89 @@ estado na própria seção com `DataState`, `ActionView`, `ActionList` ou `Alert
 
 | Propriedade   | Tipo        | Padrão      | Descrição                                                                                       |
 | ------------- | ----------- | ----------- | ----------------------------------------------------------------------------------------------- |
-| `title`       | `string`    |             | O h1 da página.                                                                                 |
-| `count`       | `number`    |             | Total de itens ao lado do título (mono, esmaecido).                                             |
+| `title`       | `ReactNode` |             | O h1 da página.                                                                                 |
 | `description` | `ReactNode` |             | Linha de contexto sob o título (ex.: "N no total · X ativos").                                  |
 | `actions`     | `ReactNode` |             | Ações contextuais no extremo oposto do cabeçalho; em telas estreitas, ficam abaixo do contexto. |
 | `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.                                          |
 
+## Propriedades de PageHeader
+
+| Propriedade | Tipo                   | Padrão      | Descrição                                                        |
+| ----------- | ---------------------- | ----------- | ---------------------------------------------------------------- |
+| `variant`   | `'default' \| 'bar'`  | `'default'` | Apresentação no container ou como faixa compacta no topo.        |
+| `className` | `string`               |             | Classes adicionais da região externa do cabeçalho.               |
+| `children`  | `ReactNode`            |             | Um `PageTitle` e, opcionalmente, `PageBack` ou `PageNavigation`, descrição e ações. |
+
+## Propriedades de PageBack
+
+| 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`                  |                           | Nome visível do destino no header padrão e conteúdo do tooltip na barra. |
+| `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`.              |
+
+## Propriedades de PageNavigation
+
+| Propriedade | Tipo                          | Descrição                                       |
+| ----------- | ----------------------------- | ----------------------------------------------- |
+| `children`  | `ReactNode`                   | Trilha estrutural, normalmente um `Breadcrumb`. |
+| `className` | `string`                      | Classes adicionais do container introdutório.   |
+| demais      | Atributos de `HTMLDivElement` | Atributos nativos repassados ao container.       |
+
+## Propriedades de PageTitle
+
+| Propriedade | Tipo                              | Descrição                                              |
+| ----------- | --------------------------------- | ------------------------------------------------------ |
+| `children`  | `ReactNode`                       | Título principal `h1`; compacto na variante `bar`.     |
+| `className` | `string`                          | Classes adicionais do título.                          |
+| demais      | Atributos de `HTMLHeadingElement` | Atributos nativos repassados ao heading.                |
+
+## Propriedades de PageDescription
+
+| Propriedade | Tipo                                | Descrição                                |
+| ----------- | ----------------------------------- | ---------------------------------------- |
+| `children`  | `ReactNode`                         | Contexto apresentado abaixo do título.   |
+| `className` | `string`                            | Classes adicionais da descrição.         |
+| demais      | Atributos de `HTMLParagraphElement` | Atributos nativos repassados ao parágrafo. |
+
+## Propriedades de PageActions
+
+| Propriedade | Tipo                           | Descrição                                    |
+| ----------- | ------------------------------ | -------------------------------------------- |
+| `children`  | `ReactNode`                    | Ações no extremo oposto do cabeçalho.        |
+| `className` | `string`                       | Classes adicionais da região de ações.       |
+| demais      | Atributos de `HTMLDivElement`  | Atributos nativos repassados ao container.    |
+
+## Propriedades de PageBody
+
+| Propriedade | Tipo                          | Descrição                                             |
+| ----------- | ----------------------------- | ----------------------------------------------------- |
+| `children`  | `ReactNode`                   | Conteúdo principal; recebe o container na barra.      |
+| `className` | `string`                      | Classes adicionais da região principal.               |
+| demais      | Atributos de `HTMLDivElement` | Atributos nativos repassados ao container.             |
+
+## Propriedades de PageActionsTarget
+
+| Propriedade | Tipo                 | Descrição                                                               |
+| ----------- | -------------------- | ----------------------------------------------------------------------- |
+| `target`    | `HTMLElement \| null` | Destino externo das ações; `null` mantém as ações no header.           |
+| `children`  | `ReactNode`          | Árvore de página que poderá declarar `PageActions`.                     |
+
 ## Propriedades de PageState
 
-| Propriedade | Tipo | Padrão | Descrição |
-|---|---|---|---|
-| `status` | `'loading' \| 'error' \| 'empty' \| 'ready'` | | Estado integral do conteúdo. |
-| `title` | `ReactNode` | Texto seguro por estado | Situação reconhecível pela pessoa. |
-| `description` | `ReactNode` | | Impacto ou próximo passo aplicável. |
-| `icon` | `ReactNode` | Alerta no erro | Ícone decorativo do estado. |
-| `action` | `ReactNode` | | Seleção ou criação aplicável ao estado. |
-| `emptyMessage` | `string` | `'Nada por aqui'` | Título do vazio quando `title` não é informado. |
-| `errorMessage` | `string` | `'Não foi possível carregar esta página'` | Título do erro quando `title` não é informado. |
-| `onRetry` | `() => void \| Promise<void>` | | Recuperação do erro: acrescenta o botão de tentar de novo ao lado de `action`. |
-| `retryLabel` | `string` | `'Tentar de novo'` | Rótulo do botão de recuperação. |
-| `children` | `ReactNode` | | Conteúdo renderizado somente em `ready`. |
+| Propriedade    | Tipo                                         | Padrão                                    | Descrição                                                                                       |
+| -------------- | -------------------------------------------- | ----------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `status`       | `'loading' \| 'error' \| 'empty' \| 'ready'` |                                           | Estado integral do conteúdo.                                                                    |
+| `title`        | `ReactNode`                                  | Texto seguro por estado                   | Situação reconhecível pela pessoa.                                                              |
+| `description`  | `ReactNode`                                  |                                           | Impacto ou próximo passo aplicável.                                                             |
+| `icon`         | `ReactNode`                                  | Alerta no erro                            | Ícone decorativo do estado.                                                                     |
+| `action`       | `ReactNode`                                  |                                           | Seleção ou criação aplicável ao estado.                                                         |
+| `emptyMessage` | `string`                                     | `'Nada por aqui'`                         | Título do vazio quando `title` não é informado.                                                 |
+| `errorMessage` | `string`                                     | `'Não foi possível carregar esta página'` | Título do erro quando `title` não é informado.                                                  |
+| `onRetry`      | `() => void \| Promise<void>`                |                                           | Recuperação do erro: acrescenta um botão `outline` textual ao lado de `action`.                 |
+| `retryLabel`   | `string`                                     | `'Tentar de novo'`                        | Texto do botão de recuperação.                                                                  |
+| `children`     | `ReactNode`                                  |                                           | Conteúdo renderizado somente em `ready`.                                                        |
+| `className`    | `string`                                     |                                           | Classes da superfície de estado.                                                                |

package/src/ui/meta.ts

@@ -27,7 +27,7 @@ export const componentMeta = {
     name: "alert",
     ancestry: "opus",
     whenToUse:
-      "Aviso inline no fluxo da página — `context` declara neutral/info/success/warning/danger e `variant` escolhe subtle/outline (ADR 0006). Forma curta: `<Alert title description icon context />`; para conteúdo rico, componha AlertMedia + AlertHeader (AlertTitle e AlertDescription) + AlertActions. A mídia mantém uma moldura tonal quadrada, mesmo com descrição multilinha. O texto comunica o significado sem depender só da cor. Para interromper cobrando decisão, use `dialog.confirm()`; para recado passageiro, `toast`.",
+      "Aviso inline no fluxo da página — `context` declara neutral/info/success/warning/danger e `variant` escolhe subtle/outline (ADR 0006). Forma curta: `<Alert title description icon context />`; para conteúdo rico, componha AlertMedia + AlertHeader (AlertTitle e AlertDescription) + AlertActions. Ações usam Button ghost como ponto de partida; tentativas repetidas podem usar somente o ícone, com nome acessível e tooltip. A mídia mantém uma moldura tonal quadrada, mesmo com descrição multilinha. O texto comunica o significado sem depender só da cor. Para interromper cobrando decisão, use `dialog.confirm()`; para recado passageiro, `toast`.",
   },
   badge: {
     name: "badge",
@@ -69,7 +69,7 @@ export const componentMeta = {
     name: "button",
     ancestry: "shadcn",
     whenToUse:
-      "Inicie uma ação com um controle clicável. Use `context` para o significado, `variant` para o tratamento visual e `size` para a escala compartilhada (`xs`…`lg` e os quadrados `icon-*`); `icon` recebe um nó e `busy` comunica o andamento e impede um novo acionamento. Para ações relacionadas, use ButtonGroup.",
+      "Inicie uma ação com um controle clicável. Use `context` para o significado, `variant` para o tratamento visual e `size` para a escala compartilhada (`xs`…`lg` e os quadrados `icon-*`); `icon` recebe um nó e `busy` comunica o andamento e impede um novo acionamento. Para ações relacionadas, use ButtonGroup conectado ou espaçado.",
   },
   card: {
     name: "card",
@@ -117,7 +117,7 @@ export const componentMeta = {
     name: "content-header",
     ancestry: "opus",
     whenToUse:
-      "Estruture o cabeçalho de um Content com título, contador, descrição e ações — a mesma anatomia de PageHeader. No caso comum, declare esses valores diretamente em Content; componha ContentHeader apenas quando precisar controlar a anatomia.",
+      "Estruture uma região de conteúdo com título, contador, descrição e ações. No caso comum, declare esses valores diretamente em Content; componha ContentHeader apenas quando precisar controlar a anatomia. Contadores pertencem a Content e não ao título da Page.",
   },
   copyable: {
     name: "copyable",
@@ -129,7 +129,7 @@ export const componentMeta = {
     name: "dialog",
     ancestry: "opus",
     whenToUse:
-      "Abra conteúdo ou uma tarefa em uma janela modal com foco contido. Use o modo padrão quando a superfície puder ser dispensada e `mode=\"alert\"` quando exigir resposta explícita. Para o caso imperativo comum, use `dialog.alert`, `dialog.confirm`, `dialog.prompt` ou `dialog.choose`. Distribua conteúdo próprio entre cabeçalho, corpo rolável e rodapé de ações.",
+      'Abra conteúdo ou uma tarefa em uma janela modal com foco contido. Use o modo padrão quando a superfície puder ser dispensada e `mode="alert"` quando exigir resposta explícita. Para o caso imperativo comum, use `dialog.alert`, `dialog.confirm`, `dialog.prompt` ou `dialog.choose`. Distribua conteúdo próprio entre cabeçalho, corpo rolável e rodapé de ações.',
   },
   input: {
     name: "input",
@@ -183,7 +183,7 @@ export const componentMeta = {
     name: "spinner",
     ancestry: "shadcn",
     whenToUse:
-      "Indique uma espera sem progresso determinado, como uma ação ou consulta em andamento. O ícone é decorativo: o contêiner (`role=\"status\"`) ou o texto ao lado nomeia a espera. Para reservar a forma do conteúdo, use Skeleton.",
+      'Indique uma espera sem progresso determinado, como uma ação ou consulta em andamento. O ícone é decorativo: o contêiner (`role="status"`) ou o texto ao lado nomeia a espera. Para reservar a forma do conteúdo, use Skeleton.',
   },
   table: {
     name: "table",
@@ -400,7 +400,7 @@ export const componentMeta = {
     name: "page",
     ancestry: "opus",
     whenToUse:
-      "O esqueleto de página do back-office: <main> + container centralizado com teto padrão de 80rem (`max-w-7xl`). O shorthand com title, description, count e actions cria a mesma anatomia de PageHeader(PageTitle/PageDescription/PageMeta/PageActions) + PageBody disponível na forma explícita. PageActionsTarget projeta as ações no chrome reservado pelo shell sem retirar sua declaração da Page. `className` substitui o teto quando a composição pede outra largura. Quando todo o body estiver carregando, falhar ou estiver vazio, use PageState. Para listagem em modal, ActionListDialog.",
+      "O esqueleto de página do back-office: <main> + container centralizado com teto padrão de 80rem (`max-w-7xl`). O shorthand cobre título, descrição e ações; a forma explícita acrescenta PageBack para retorno simples ou PageNavigation para uma trilha e permite `PageHeader variant=\"bar\"` quando a mesma anatomia precisar virar uma faixa compacta. No header padrão, PageBack fica acima do título; na barra, vira icon-only com tooltip. PageActionsTarget fica restrito a workspaces imersivos com chrome próprio. Quando todo o body estiver carregando, falhar ou estiver vazio, use PageState: ele oculta o header e ocupa a área disponível, centralizado e sem moldura. Para uma região disponível à criação ou vínculo, use Empty.",
   },
   router: {
     name: "router",

package/src/ui/react.tsx

@@ -423,14 +423,20 @@ export type { DataStateProps } from "./components/patterns/data-state.tsx";
 export {
   Page,
   PageHeader,
+  PageNavigation,
+  PageBack,
   PageTitle,
   PageDescription,
-  PageMeta,
   PageActions,
   PageActionsTarget,
   PageBody,
 } from "./components/patterns/page.tsx";
-export type { PageProps } from "./components/patterns/page.tsx";
+export type {
+  PageProps,
+  PageBackProps,
+  PageHeaderProps,
+  PageHeaderVariant,
+} from "./components/patterns/page.tsx";
 
 // Estado integral do conteúdo de Page (loading/error/empty/ready), sem acoplar Page a dados.
 export { PageState } from "./components/patterns/page-state.tsx";