@softize/opus 30.0.0 → 31.1.0

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

@@ -1,229 +1,155 @@
-## Esqueleto de página
+## Página com cabeçalho único
 
-Use `Page` para manter cabeçalho, estado e conteúdo na mesma anatomia. `PageHeader` recebe navegação e ações da superfície;
-`PageIntro` abre o corpo com título e orientação. Na composição compacta, o título fica no header e a intro é omitida. O conteúdo interno do body é
-centralizado e ocupa a largura disponível até `80rem` (`max-w-7xl`). O header e o viewport
-de rolagem ocupam toda a largura do painel.
+Use `Page` para reunir título, ações e conteúdo em uma coluna aberta, sem divisores
+entre regiões. A coluna tem padding de `2,5rem` em todos os lados, intervalo de `1,5rem`
+entre cabeçalho e conteúdo, `1rem` entre as demais regiões e título de `1,875rem`.
+A largura e a ocupação de altura são independentes:
+`flow` rola a página inteira; `fill` mantém o cabeçalho visível e entrega a altura restante
+ao conteúdo. Drawer e Dialog conservam seus recuos de `1rem` e superfícies delimitadas.
 
-A forma curta é o padrão para páginas comuns e cria `PageIntro` dentro de `PageBody` e um `PageHeader` quando existem controles. A forma explícita
-exige exatamente um heading principal. Use `PageTitle` na intro ou no cabeçalho, `Surface level={1}` no body,
-ou deixe um `PageState` ativo assumir esse papel. O cabeçalho pode ser omitido quando o próprio
-conteúdo nomeia a página. Contadores e outros indicadores pertencem ao conteúdo que os explica.
+A forma curta cobre páginas comuns:
 
-Use `surfaceLayout="sectioned"` (padrão) para separar as regiões por bordas ou
-`surfaceLayout="continuous"` para uma superfície contínua. O `layout` decide a ocupação de altura:
-`flow`, o padrão, mantém a rolagem vertical em `PageBody`; `fill` permite que uma região interna,
-como uma tabela longa ou um split, assuma a rolagem. Header e footer ficam fora desse viewport.
+```tsx preview col
+<Page title="Clientes" actions={<Button size="default">Criar cliente</Button>}>
+  <p>Conteúdo da listagem.</p>
+</Page>
+```
 
-Nos botões da barra superior, declare `size="sm"` para texto e `size="icon-sm"` para ícones.
-`PageHeader` reserva uma linha mínima de `2rem`, mesmo sem ações; conteúdo maior pode expandi-la.
-`PageBack` já usa `icon-sm`. A mesma escala vale para ações nos headers de Dialog, Drawer e Surface, inclusive criação de coleções.
+Use `default` para ações textuais do cabeçalho e `icon` para ícones. A linha reserva
+`2,25rem` mesmo sem botões, evitando variação na altura. Drawer, Dialog e Surface compartilham
+essa escala nos headers. Controles do body e dos menus mantêm sua escala local.
 
-`PageShell` não inclui sidebar nem inventa breadcrumb. Ele ocupa o painel principal já delimitado e
-entrega ao `PageHeader` descendente a navegação e as ações conhecidas pela aplicação, sem criar uma
-barra visual. Tabs ficam reservados a recortes da mesma superfície. Canvas e outros workspaces
-espaciais imersivos podem usar um shell próprio.
+`PageActions` usa `ButtonGroup` internamente, sem moldura e com o espaçamento padrão de `0,25rem`.
+O voltar e as ações fornecidas pelo shell e pela página entram no mesmo grupo, nessa ordem.
 
-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
-uma falha parcial não deve ocultar as demais seções.
+## Composição explícita
+
+Use os slots para acrescentar metadados ou compor as ações diretamente. Declare um título
+principal no header. Não misture `title` da forma curta com `PageHeader` ou `PageBody`.
 
 ```tsx preview col
-render(
-  <div className="w-full overflow-hidden rounded-lg border border-border">
-    <Page
-      title="Workspaces"
-      actions={
-        <Button variant="outline" size="sm">
-          Exportar
-        </Button>
-      }
-    >
-      <div className="rounded-lg border border-dashed border-border p-10 text-center text-sm text-muted-foreground">
-        O conteúdo da página (tabela, cards, grid…).
-      </div>
-    </Page>
-  </div>,
-);
+<Page>
+  <PageHeader>
+    <PageTitle>Carla Souza</PageTitle>
+    <PageMeta>Atualizado hoje · Por: Marina</PageMeta>
+    <PageActions>
+      <Button size="default">Editar</Button>
+    </PageActions>
+  </PageHeader>
+  <PageBody>Dados do cliente.</PageBody>
+</Page>
 ```
 
-## Orientar sobre a finalidade
+`description` e `PageDescription` são orientações breves e opcionais. Regras necessárias
+à decisão pertencem aos campos, às ações ou ao corpo. `PageMeta` recebe badges, autoria e
+datas; o slot ausente não reserva espaço.
 
-Use `description` na forma curta ou `PageDescription` junto ao título em `PageIntro` ou `PageHeader` quando uma frase breve
-ajudar a reconhecer a finalidade da página. Omita texto que só repita o título. Regras de negócio,
-limites e consequências ficam nos campos, ações ou corpo em que são necessários. Pular o
-subheading não deve comprometer a decisão nem a conclusão correta da tarefa.
+## Abas no cabeçalho
 
-```tsx
-<Page
-  title="Conhecimento"
-  description="Consulte os materiais de apoio da sua área."
->
-  <KnowledgeList />
-</Page>
+Use `PageHeader.tabs` para reunir as abas ao cabeçalho. Com `layout="fill"`, elas
+permanecem visíveis durante a rolagem dos resultados.
+Envolva a página em `Tabs`, coloque `TabsList` no header e `TabsPanel` no body.
+O cabeçalho fornece o alinhamento; seleção, indicador ativo e teclado continuam no Tabs. Ações da coleção ficam na barra da listagem dentro do painel ativo. `PageActions`
+recebe somente ações gerais da página, sem repetir o título no painel.
+
+```tsx preview col
+<Tabs defaultValue="deliveries" className="min-h-0 flex-1">
+  <Page>
+    <PageHeader
+      tabs={
+        <TabsList aria-label="Configurações de e-mail">
+          <TabsListItem value="deliveries">Envios</TabsListItem>
+          <TabsListItem value="senders">Remetentes</TabsListItem>
+        </TabsList>
+      }
+    >
+      <PageTitle>E-mails</PageTitle>
+    </PageHeader>
+    <PageBody>
+      <TabsPanel value="deliveries">Acompanhe as entregas de e-mail.</TabsPanel>
+      <TabsPanel value="senders">Configure os remetentes.</TabsPanel>
+    </PageBody>
+  </Page>
+</Tabs>
 ```
 
+`DrawerHeader`, `DialogHeader` e `SurfaceHeader` oferecem a mesma região `tabs`.
+Ela recebe abas horizontais. Alertas e legendas de fieldset não aceitam essa região.
+Para listas que ocupam a altura disponível, use `Page layout="fill"`; o `TabsPanel`
+repassa essa altura à lista ativa. Sem `tabs`, a geometria do header permanece igual.
+
 ## 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. O controle aparece acima
-da linha do título como ícone; o nome acessível e a dica nativa do navegador (atributo
-`title`) derivam do destino.
+Use `PageBack` com `href` explícito, que continue correto após acesso por link direto.
+Para retorno controlado por uma pilha de Presentation, use `onBack` no lugar de `href`: ele
+renderiza um botão acessível e aceita `disabled` durante operações.
+Ele aparece como primeiro ícone das ações, em `ghost`, com nome acessível e tooltip.
+O aplicativo precisa de `TooltipProvider`, como nos demais controles com tooltip.
 
 ```tsx preview col
 <Page>
   <PageHeader>
     <PageBack href="/customers">Clientes</PageBack>
+    <PageTitle>Carla Souza</PageTitle>
+    <PageActions>
+      <Button size="default">Editar</Button>
+    </PageActions>
   </PageHeader>
-  <PageBody>
-    <PageIntro>
-      <PageTitle>Qualidade da base</PageTitle>
-    </PageIntro>
-    Conteúdo da análise.
-  </PageBody>
+  <PageBody>Dados do cliente.</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`](/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>
-  <PageBody>
-    <PageIntro>
-      <PageTitle>Carla Souza</PageTitle>
-    </PageIntro>
-    Dados do cliente.
-  </PageBody>
-</Page>
-```
+O retorno também pode ser declarado primeiro dentro de `PageActions`. Páginas raiz
+não precisam dele. A navegação corrente não recebe uma segunda barra de breadcrumb.
 
-## Contexto conhecido pelo shell
+## Ações conhecidas pelo shell
 
-Use `PageShell` quando o shell conhece o breadcrumb e a rota conhece ações globais ou uma
-introdução. Não crie um cabeçalho paralelo no layout nem esconda slots de `Page` com CSS. O Opus compõe a
-navegação e as ações do shell no `PageHeader` estável da página ativa.
+`PageShell` entrega ações à Page descendente sem desenhar outro cabeçalho. Declare o retorno
+antes das demais ações. Isso permite à aplicação escolher o pai e à rota cuidar do conteúdo.
 
 ```tsx preview col
-<PageShell
-  navigation={
-    <Breadcrumb>
-      <BreadcrumbList>
-        <BreadcrumbItem>Vendas</BreadcrumbItem>
-        <BreadcrumbSeparator />
-        <BreadcrumbPage>Clientes</BreadcrumbPage>
-      </BreadcrumbList>
-    </Breadcrumb>
-  }
->
-  <Page
-    title="Clientes"
-    actions={
-      <Button variant="outline" size="sm">
-        Exportar
-      </Button>
-    }
-  >
-    Conteúdo da listagem.
+<PageShell actions={<PageBack href="/customers">Clientes</PageBack>}>
+  <Page title="Carla Souza" actions={<Button size="default">Editar</Button>}>
+    Dados do cliente.
   </Page>
 </PageShell>
 ```
 
-Durante `PageState`, o cabeçalho inteiro desaparece e o título do estado assume o heading principal.
-Se uma ação não puder ser executada sem o conteúdo, a própria rota deve omiti-la naquele estado.
+## Listas e rolagem
 
-Na composição explícita, separe navegação e ações da superfície do título no corpo:
+Use `layout="fill"` quando a lista deve ocupar a altura disponível. `ActionList` recebe a
+altura por `PageBody` e mantém sua própria rolagem. O título pertence ao header da Page;
+criação e outras operações da coleção ficam em `ActionList.toolbarActions`. Uma `Surface`
+no body representa uma seção subordinada, não outro título principal.
 
-```tsx preview col
-<PageShell
-  navigation={
-    <Breadcrumb>
-      <BreadcrumbList>
-        <BreadcrumbItem>Vendas</BreadcrumbItem>
-        <BreadcrumbSeparator />
-        <BreadcrumbPage>Clientes</BreadcrumbPage>
-      </BreadcrumbList>
-    </Breadcrumb>
-  }
->
-  <Page>
-    <PageHeader>
-      <PageActions>
-        <Button size="sm">Exportar</Button>
-      </PageActions>
-    </PageHeader>
-    <PageBody>
-      <PageIntro>
-        <PageTitle>Clientes</PageTitle>
-      </PageIntro>
-      Conteúdo da listagem.
-    </PageBody>
-  </Page>
-</PageShell>
+```tsx
+<Page title="Clientes" layout="fill">
+  <ActionList
+    action={customerListContract}
+    input={{}}
+    toolbarActions={<Button aria-label="Criar cliente">Criar</Button>}
+  />
+</Page>
 ```
 
-## Composição explícita
-
-Use os slots quando a página precisar compor o cabeçalho diretamente. Não misture propriedades da
-forma curta com `PageHeader` ou `PageBody`.
-
-```tsx preview col
-render(
-  <Page>
-    <PageHeader>
-      <PageActions>
-        <Button variant="outline" size="sm">
-          Exportar
-        </Button>
-      </PageActions>
-    </PageHeader>
-    <PageBody>
-      <PageIntro>
-        <PageTitle>Workspaces</PageTitle>
-      </PageIntro>
-
-      <div className="rounded-lg border border-dashed border-border p-10 text-center">
-        O conteúdo da página.
-      </div>
-    </PageBody>
-  </Page>,
-);
-```
+`flow`, o padrão, rola título e conteúdo juntos. `fill` mantém o header visível e permite
+que uma região interna assuma a rolagem. Preserve a cadeia de altura no layout que hospeda
+a Page; não acrescente outro contêiner vertical com rolagem ao redor.
 
-Em uma página de listagem, [`Surface`](/ui/surface) pode fornecer o título e as ações da coleção,
-deixando `Page` apenas com `PageBody`. Se `PageShell` fornecer navegação ou ações nesse caso, `Page`
-materializa somente o `PageHeader` necessário para recebê-las, sem duplicar o heading de `Surface`.
-[Composições](/ui/compositions) compara essa forma, com o título no corpo, à forma compacta, com o
-título no cabeçalho.
+O body separa seus blocos diretos por `1rem`. Uma grade ou grupo com ritmo próprio fica
+num wrapper filho. O padding externo pertence à coluna; PageBody não acrescenta outro
+recuo ao conteúdo.
 
-## Ações de etapa no rodapé
+## Rodapé de etapa
 
-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 as ações alinhadas
-no fim da linha.
+Use `PageFooter` quando a confirmação precisa permanecer disponível ao fim de uma etapa.
 
 ```tsx preview col
 <Page>
-  <PageBody>
-    <PageIntro>
-      <PageTitle>Importar clientes</PageTitle>
-    </PageIntro>
-    Revise os 128 registros antes de confirmar.
-  </PageBody>
+  <PageHeader>
+    <PageTitle>Importar clientes</PageTitle>
+  </PageHeader>
+  <PageBody>Revise os registros antes de confirmar.</PageBody>
   <PageFooter>
     <ButtonGroup mode="spaced">
       <Button variant="ghost">Cancelar</Button>
@@ -233,209 +159,96 @@ no fim da linha.
 </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">
-      <PageBody className="min-h-0 flex-1 overflow-y-auto">
-        <PageIntro>
-          <PageTitle>Ordens de serviço</PageTitle>
-        </PageIntro>
-
-        <div className="space-y-2">
-          {[
-            "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>
-          ))}
-        </div>
-      </PageBody>
-    </Page>
-  </div>,
-);
-```
-
-Uma [`ActionList`](/ui/action-list) não precisa dessas classes. Filha de `PageBody`, ou de um
-[`Surface`](/ui/surface) dentro dele, ela recebe a altura da página e assume `layout="fill"`
-sozinha: `PageBody`, `Surface` e `SurfaceBody` 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 um hospedeiro próprio
-
-Use `PageActionsTarget` somente quando um hospedeiro próprio tiver uma região externa 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" size="sm">
-              Exportar
-            </Button>
-          }
-        >
-          Conteúdo da listagem.
-        </Page>
-      </PageActionsTarget>
-    </div>
-  );
-}
-
-render(<Example />);
-```
-
-## Estados integrais
+## Carregamento, erro e ausência
 
-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 sozinho dentro de `PageBody`. Enquanto `status` for `loading`, `error` ou
-`empty`, `Page` oculta o cabeçalho inteiro — incluindo a navegação e as ações recebidas de
-`PageShell` — e o estado ocupa a altura disponível. Uma subpágina que dependa do retorno oferece a
-saída pelo `action` do próprio `PageState`. 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.
+`PageState` substitui o conteúdo durante um estado integral e assume o heading principal.
+O header fica oculto nesse período; quando o conteúdo volta a ficar pronto, ele reaparece.
+Uma falha parcial pertence à seção afetada e não deve ocultar as demais.
 
 ```tsx preview col
-<Page title="Relatório">
-  <PageState
-    status="error"
-    title="Não foi possível carregar o relatório"
-    description="Tente novamente. Se o problema continuar, volte mais tarde."
-    onRetry={() => {}}
-    retryLabel="Tentar novamente"
-  />
-</Page>
-```
-
-`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">
+<Page title="Clientes">
   <PageState
     status="empty"
-    title="Nenhum relatório"
-    description="Crie o primeiro relatório para começar."
-    action={<Button>Criar relatório</Button>}
+    title="Nenhum cliente"
+    description="Crie um cliente para começar."
   />
 </Page>
 ```
 
-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`](/ui/data-state), [`ActionView`](/ui/action-view),
-[`ActionList`](/ui/action-list) ou [`Alert`](/ui/alert).
+Use `onRetry` para oferecer recuperação. Não crie loaders e vazios paralelos a `ActionList`
+quando os dados pertencem a uma coleção: a lista já governa esses estados.
 
-## Metadados junto à identidade
+## Ações em um hospedeiro próprio
 
-Use `PageMeta` para badges, autoria e datas relacionados ao registro. A faixa fica
-abaixo da linha de título e ações, com espaço próprio; `PageDescription` continua
-reservado à orientação textual breve. Os itens quebram em várias linhas quando necessário.
+`PageActionsTarget` encaminha as ações para um elemento externo quando um hospedeiro precisa
+dessa integração. Com `target={null}`, elas permanecem no cabeçalho. O destino deve preservar
+nome acessível, ordem de foco e a associação com a página.
 
-```tsx preview col
-render(
-<Page title="Manual de atendimento" description="Orientações para a equipe." meta={<><Badge>Publicado</Badge><span>Por Ana</span></>}>
-  <p>Conteúdo do manual.</p>
-</Page>
-);
-```
+## Migração
 
-A composição aceita um único `PageMeta` e exige um `PageTitle`. Na forma explícita, coloque-o em `PageIntro` ou no `PageHeader` compacto. Não coloque o slot solto no corpo.
+Mova `PageIntro` para `PageHeader` e `PageIntroActions` para `PageActions`. Remova o breadcrumb
+e use `PageBack` quando houver um pai relevante. Retire limites de largura e classes locais
+de título e padding que duplicavam o padrão. `PageIntro`, `PageIntroActions` e `PageNavigation`
+foram removidos, sem aliases de compatibilidade. As opções
+`flow` e `fill` continuam disponíveis. Remova `composition` e `pageComposition`: Page
+tem uma única aparência. Para preservar a coluna intermediária de antigos documentos,
+declare `width="default"` ou `page: { width: "default" }`. Sem largura explícita, a Page é ampla.
 
 ## Propriedades de Page
 
-| Propriedade   | Tipo                       | Padrão      | Descrição                                                                                                                                                          |
-| ------------- | -------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `description` | `ReactNode`                |             | Orientação opcional sob o título na forma curta.                                                                                                                   |
-| `meta` | `ReactNode` | | Forma curta: metadados sob o título e a orientação. Exige `title`. |
-| `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 e leva essa altura até uma `ActionList` composta em `PageBody`. |
-| `className`   | `string`                   |             | Classes do container externo. Para largura interna, use `contentClassName`.                                                                                        |
-| `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 a moldura da página.                                              |
+| Propriedade   | Tipo                       | Padrão   | Descrição                                                                                                                                                          |
+| ------------- | -------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `description` | `ReactNode`                |          | Orientação opcional sob o título na forma curta.                                                                                                                   |
+| `meta`        | `ReactNode`                |          | Forma curta: metadados sob o título e a orientação. Exige `title`.                                                                                                 |
+| `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 e leva essa altura até uma `ActionList` composta em `PageBody`. |
+| `className`   | `string`                   |          | Classes adicionais da coluna. Para escolher sua largura, use `width`.                                                                                        |
+| `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 a moldura da página.                                              |
+| `width` | `'narrow' \| 'default' \| 'wide'` | `'wide'` | Limita a coluna inteira a 42rem, 58rem ou à largura disponível. |
 
 ## Propriedades de PageShell
 
-| Propriedade  | Tipo                          | Descrição                                                                                  |
-| ------------ | ----------------------------- | ------------------------------------------------------------------------------------------ |
-| `navigation` | `ReactNode`                   | Navegação contextual composta na linha de controles do header no `PageHeader` descendente. |
-| `actions`    | `ReactNode`                   | Ações conhecidas pelo shell, antes das ações declaradas pela `Page`.                       |
-| `children`   | `ReactNode`                   | Rota que renderiza uma `Page` descendente.                                                 |
-| `className`  | `string`                      | Classes adicionais da moldura.                                                             |
-| demais       | Atributos de `HTMLDivElement` | Atributos nativos repassados à moldura.                                                    |
+| Propriedade | Tipo                          | Descrição                                                            |
+| ----------- | ----------------------------- | -------------------------------------------------------------------- |
+| `actions`   | `ReactNode`                   | Ações conhecidas pelo shell, antes das ações declaradas pela `Page`. |
+| `children`  | `ReactNode`                   | Rota que renderiza uma `Page` descendente.                           |
+| `className` | `string`                      | Classes adicionais da moldura.                                       |
+| demais      | Atributos de `HTMLDivElement` | Atributos nativos repassados à moldura.                              |
 
-`surfaceLayout?: 'sectioned' | 'continuous'` escolhe os divisores; o padrão é `sectioned`.
+A Page não insere divisores entre header, body e footer.
 `contentClassName?: string` configura largura e alinhamento do conteúdo. O ritmo e os recuos
-continuam sob responsabilidade do body; não use essa prop para substituir padding ou gap.
+pertencem à Page; não use essa prop para substituir padding ou gap.
 
 ## Propriedades de PageHeader
 
-| Propriedade | Tipo                          | Descrição                                                                |
-| ----------- | ----------------------------- | ------------------------------------------------------------------------ |
-| `className` | `string`                      | Classes adicionais do cabeçalho estável.                                 |
-| `children`  | `ReactNode`                   | `PageBack` ou `PageNavigation`, um `PageTitle` opcional e `PageActions`. |
-| demais      | Atributos de `HTMLDivElement` | Atributos nativos repassados ao cabeçalho.                               |
+| Propriedade | Tipo                          | Descrição                                                                 |
+| ----------- | ----------------------------- | ------------------------------------------------------------------------- |
+| `tabs`      | `ReactNode`                   | `TabsList` sob o título, controlado por um `Tabs` ancestral.              |
+| `className` | `string`                      | Classes adicionais do cabeçalho estável.                                  |
+| `children`  | `ReactNode`                   | `PageTitle`, metadados e ações; `PageBack` é inserido primeiro nas ações. |
+| demais      | Atributos de `HTMLDivElement` | Atributos nativos repassados ao cabeçalho.                                |
 
 ## 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`                            | obrigatório              | Nome do destino pai usado no rótulo acessível e na dica nativa (`title`).                  |
+| `href`       | `string`                               |                          | Destino explícito da página pai; obrigatório quando não há `onBack`. |
+| `onBack`     | `() => void`                           |                          | Retorno controlado pela pilha; renderiza botão e não aceita `href`. |
+| `disabled`   | `boolean`                              | `false`                  | Bloqueia o retorno quando usado com `onBack`. |
+| `children`   | `ReactNode`                            | obrigatório              | Nome do destino pai usado no rótulo acessível e na tooltip.                                |
 | `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` na intro ou no header compacto. |
-| `className` | `string`                          | Classes adicionais do título.                         |
-| demais      | Atributos de `HTMLHeadingElement` | Atributos nativos repassados ao heading.              |
+| Propriedade | Tipo                              | Descrição                                |
+| ----------- | --------------------------------- | ---------------------------------------- |
+| `children`  | `ReactNode`                       | Título principal `h1` no header.         |
+| `className` | `string`                          | Classes adicionais do título.            |
+| demais      | Atributos de `HTMLHeadingElement` | Atributos nativos repassados ao heading. |
 
 ## Propriedades de PageActions
 
@@ -457,7 +270,9 @@ continuam sob responsabilidade do body; não use essa prop para substituir paddi
 
 `contentClassName?: string` configura largura e alinhamento do container interno.
 
-`PageBody` separa seus blocos diretos por `1rem` e fornece os recuos internos. Uma grade, lista compacta ou linha horizontal fica dentro de um wrapper próprio.
+O recuo externo permanece na coluna mesmo quando o body usa `flush`.
+
+`PageBody` separa seus blocos diretos por `1rem`; o recuo externo pertence à coluna. Uma grade, lista compacta ou linha horizontal fica dentro de um wrapper próprio.
 
 | Propriedade | Tipo                          | Descrição                                           |
 | ----------- | ----------------------------- | --------------------------------------------------- |
@@ -493,75 +308,52 @@ ocupa a altura.
 
 ## Propriedades de PageDescription
 
-| Propriedade | Tipo                                   | Padrão | Descrição                                                                 |
-| ----------- | -------------------------------------- | ------ | ------------------------------------------------------------------------- |
-| `children`  | `ReactNode`                            |        | Orientação breve e opcional; filho direto da intro ou do header compacto. |
-| `className` | `string`                               |        | Ajusta a apresentação do parágrafo.                                       |
-| `…props`    | `HTMLAttributes<HTMLParagraphElement>` |        | Atributos nativos.                                                        |
+| Propriedade | Tipo                                   | Padrão | Descrição                                            |
+| ----------- | -------------------------------------- | ------ | ---------------------------------------------------- |
+| `children`  | `ReactNode`                            |        | Orientação breve e opcional; filho direto do header. |
+| `className` | `string`                               |        | Ajusta a apresentação do parágrafo.                  |
+| `…props`    | `HTMLAttributes<HTMLParagraphElement>` |        | Atributos nativos.                                   |
 
-## Composição compacta
-
-Quando o cabeçalho também identifica o conteúdo, mantenha o título nele e omita a intro.
-Não declare o mesmo título nas duas regiões.
-
-```tsx preview col
-<Page>
-  <PageHeader>
-    <PageTitle>Preferências</PageTitle>
-  </PageHeader>
-  <PageBody>Configurações da conta.</PageBody>
-</Page>
-```
-
-## Propriedades de PageIntro
-
-Aceita atributos HTML de `div` e exige um `PageTitle`. Recebe opcionalmente `PageDescription` e
-`PageIntroActions`. Deve abrir o `PageBody`; navegação e ações da superfície ficam no header.
-
-| Propriedade | Tipo                          | Descrição                                                                |
-| ----------- | ----------------------------- | ------------------------------------------------------------------------ |
-| `children`  | `ReactNode`                   | Um `PageTitle` e, opcionalmente, `PageDescription`, `PageMeta` e `PageIntroActions`. |
-| `className` | `string`                      | Classes adicionais da introdução.                                        |
-| demais      | Atributos de `HTMLDivElement` | Repassados à região introdutória.                                        |
-
-## Propriedades de PageIntroActions
+## Propriedades de PageMeta
 
-Agrupa ações locais do conteúdo no extremo oposto ao título da intro.
+| Propriedade | Tipo        | Descrição                                               |
+| ----------- | ----------- | ------------------------------------------------------- |
+| `children`  | `ReactNode` | Badges, datas, autoria ou outros metadados do registro. |
+| `className` | `string`    | Ajusta a faixa de metadados.                            |
 
-| Propriedade | Tipo                          | Descrição                                       |
-| ----------- | ----------------------------- | ----------------------------------------------- |
-| `children`  | `ReactNode`                   | Controles relacionados ao conteúdo apresentado. |
-| `className` | `string`                      | Classes adicionais do agrupamento.              |
-| demais      | Atributos de `HTMLDivElement` | Repassados ao agrupamento.                      |
+Aceita atributos nativos de `div`. O intervalo superior é de 0,75rem; os itens têm
+0,75rem entre colunas e 0,5rem entre linhas. O componente não insere separadores nem
+carrega dados. Omitir o slot não reserva espaço. Metadados não substituem orientações
+ou condições necessárias à decisão e não substituem a descrição textual da região.
 
-O header ocupa toda a largura disponível. O limite de 80rem e o recuo pertencem ao conteúdo
-interno do Body; o viewport ocupa a largura da página para manter sua barra de rolagem na extremidade.
+Presentation com `heading: "content"` recebe uma Page completa, inclusive quando o conteúdo
+vem de um componente de rota. O runtime rejeita conteúdo sem Page e dois rodapés concorrentes
+(PageFooter próprio e comandos de footer da Presentation), em vez de descartar ações.
 
-### Divisão visual das regiões
 
-Use `surfaceLayout="sectioned"` (padrão) para separar header, body e footer com divisores.
-Use `surfaceLayout="continuous"` para uma composição sem divisores. O header vazio continua
-omitido. Essa escolha é independente de `layout="flow" | "fill"`, que controla a altura e a rolagem.
+## Página centralizada
 
-## Largura e rolagem
+Para configurações curtas, escolha uma coluna estreita:
 
-`Page` e `PageBody` aceitam `contentClassName` para o container interno de leitura.
-Use `contentClassName="max-w-none"` para largura total ou `max-w-5xl` para uma leitura
-mais estreita, mantendo o header e a barra de rolagem na extremidade. `className` em Page
-controla a moldura externa; em PageBody, controla o viewport.
+```tsx
+<Page width="narrow" title="Segurança">
+  <SecuritySettings />
+</Page>
+```
 
-PageShell permite rolagem de contingência quando a rota renderiza um fallback ou um
-wrapper sem altura definida. Para manter o header fixo, a rota deve preservar a cadeia
-flexível de altura até Page. Uma Page diretamente no shell já segue esse contrato.
+Título, conteúdo e rodapé compartilham o mesmo limite de largura. Com `layout="flow"`,
+rolam juntos e a barra permanece na borda da Page. Com `layout="fill"`, o título permanece
+visível e a lista recebe a altura restante para rolar seus resultados. Sem lista, o body rola.
+As duas ocupações usam a mesma aparência e o mesmo padding.
 
-## Propriedades de PageMeta
+## Largura da coluna
 
-| Propriedade | Tipo | Descrição |
-| --- | --- | --- |
-| `children` | `ReactNode` | Badges, datas, autoria ou outros metadados do registro. |
-| `className` | `string` | Ajusta a faixa de metadados. |
+Use `width="narrow"` para preferências curtas, `width="default"` para conteúdo intermediário e
+`width="wide"` para tabelas que precisam da largura disponível. Os limites são 42rem, 58rem e
+sem teto, respectivamente, incluindo o padding da coluna. Header, Body e Footer compartilham
+esse limite; os espaçamentos internos não mudam.
 
-Aceita atributos nativos de `div`. O intervalo superior é de 0,75rem; os itens têm
-0,75rem entre colunas e 0,5rem entre linhas. O componente não insere separadores nem
-carrega dados. Omitir o slot não reserva espaço. Metadados não substituem orientações
-ou condições necessárias à decisão e não substituem a descrição textual da região.
+Sem `width`, a Page ocupa a largura disponível. Na declaração da Presentation, use
+`page: { width: "wide" }`. Quando o conteúdo fornece uma Page completa, ela herda essa
+largura e pode substituí-la com sua própria prop `width`.
+O dimensionamento de Dialog e Drawer permanece independente.