@softize/opus 27.0.0 → 28.0.0

package/src/ui/docs/DocBrowser.tsx

@@ -15,15 +15,25 @@
 import {
   Fragment,
   useEffect,
+  useId,
   useMemo,
   useRef,
   useState,
+  useSyncExternalStore,
   type ReactNode,
 } from "react";
-import { ArrowLeft, ArrowRight, ExternalLink, Search } from "lucide-react";
+import {
+  ArrowLeft,
+  ArrowRight,
+  ExternalLink,
+  Menu,
+  Search,
+  X,
+} from "lucide-react";
 import type { DocEntry, DocGroup, DocSection } from "./types.ts";
 import { Pane, Split, type PaneSize } from "../components/patterns/split.tsx";
 import { Input } from "../components/primitives/input.tsx";
+import { Button } from "../components/primitives/button.tsx";
 import {
   Breadcrumb,
   BreadcrumbList,
@@ -109,6 +119,8 @@ export interface DocBrowserProps {
   }>;
   /** Seções e grupos começam recolhidos; a busca revela resultados sem mudar a escolha manual. */
   sidebarInitiallyCollapsed?: boolean;
+  /** Em telas de até 48rem, oferece navegação recolhível no lugar da lateral fixa. Default false. */
+  collapsibleNavigation?: boolean;
 }
 
 function documentNavigation(
@@ -142,11 +154,15 @@ function EditorialDocument({
   const [headings, setHeadings] = useState<
     Array<{ id: string; title: string }>
   >([]);
-  const entries = documentEntries(sections);
+  const entries = documentEntries(
+    sections.filter((section) => section.readingSequence !== false),
+  );
   const index = entries.findIndex(({ entry }) => entry.slug === page.slug);
   const previous = index > 0 ? entries[index - 1]?.entry : undefined;
   const next = index >= 0 ? entries[index + 1]?.entry : undefined;
-  const context = entries[index]?.context;
+  const context = documentEntries(sections).find(
+    ({ entry }) => entry.slug === page.slug,
+  )?.context;
 
   useEffect(() => {
     const article = articleRef.current;
@@ -303,8 +319,10 @@ type SidebarSection = Omit<DocSection, "groups"> & {
 function filterSections(
   sections: DocSection[],
   query: string,
+  basePath: string,
 ): SidebarSection[] {
   const terms = searchable(query).split(/\s+/).filter(Boolean);
+  const namespace = JSON.stringify(basePath);
   // Identidade vem do manifesto completo, antes de remover ramos pela busca.
   const indexGroups = (groups: DocGroup[], parent: string): SidebarGroup[] =>
     groups.map((group, index) => {
@@ -317,8 +335,8 @@ function filterSections(
     });
   const indexedSections = sections.map((section, sectionIndex) => ({
     ...section,
-    navigationKey: `section:${sectionIndex}`,
-    groups: indexGroups(section.groups, `group:${sectionIndex}`),
+    navigationKey: `${namespace}:section:${sectionIndex}`,
+    groups: indexGroups(section.groups, `${namespace}:group:${sectionIndex}`),
   }));
   const matchingGroups = (groups: SidebarGroup[]): SidebarGroup[] =>
     groups.flatMap((group) => {
@@ -343,6 +361,7 @@ function DocSidebarTree({
   sections,
   activeSlug,
   onSelect,
+  onNavigate = navigate,
   forceExpanded = false,
   initiallyCollapsed = false,
   links = [],
@@ -350,6 +369,7 @@ function DocSidebarTree({
   sections: SidebarSection[];
   activeSlug?: string;
   onSelect: (slug: string) => void;
+  onNavigate?: (href: string) => void;
   forceExpanded?: boolean;
   initiallyCollapsed?: boolean;
   links?: DocBrowserProps["sidebarLinks"];
@@ -496,7 +516,7 @@ function DocSidebarTree({
               onClick={
                 link.newTab || /^https?:\/\//i.test(link.href)
                   ? undefined
-                  : () => navigate(link.href)
+                  : () => onNavigate(link.href)
               }
               label={link.label}
               icon={
@@ -510,6 +530,17 @@ function DocSidebarTree({
   );
 }
 
+const compactNavigationQuery = "(max-width: 48rem)";
+const subscribeCompactNavigation = (notify: () => void): (() => void) => {
+  const media = window.matchMedia(compactNavigationQuery);
+  media.addEventListener("change", notify);
+  return () => media.removeEventListener("change", notify);
+};
+const compactNavigationSnapshot = (): boolean =>
+  window.matchMedia(compactNavigationQuery).matches;
+const serverNavigationSnapshot = (): boolean => false;
+const skipNavigationSubscription = (): (() => void) => () => {};
+
 export function DocBrowser({
   basePath = "/docs",
   path: controlledPath,
@@ -525,8 +556,19 @@ export function DocBrowser({
   content,
   sidebarLinks = [],
   sidebarInitiallyCollapsed = false,
+  collapsibleNavigation = false,
 }: DocBrowserProps): React.ReactElement {
   const [sidebarQuery, setSidebarQuery] = useState("");
+  const watchViewport = sidebar && collapsibleNavigation;
+  const narrowViewport = useSyncExternalStore(
+    watchViewport ? subscribeCompactNavigation : skipNavigationSubscription,
+    watchViewport ? compactNavigationSnapshot : serverNavigationSnapshot,
+    serverNavigationSnapshot,
+  );
+  const compactNavigation = collapsibleNavigation && narrowViewport;
+  const [navigationOpen, setNavigationOpen] = useState(false);
+  const navigationId = useId();
+  const navigationButtonRef = useRef<HTMLButtonElement>(null);
   // Standalone: o path vem do router da casa (`usePathname` — pathname É o estado).
   // Controlado: o host manda, e este valor é ignorado. O hook roda sempre (regra dos
   // hooks); o que muda é quem vence no `??`.
@@ -542,9 +584,10 @@ export function DocBrowser({
   const searchOptions = typeof search === "object" ? search : {};
   const query =
     searchOptions.placement === "external" ? searchOptions.value : sidebarQuery;
+  const previousQuery = useRef(query);
   const visibleSections = useMemo(
-    () => filterSections(sections, query),
-    [query, sections],
+    () => filterSections(sections, query, basePath),
+    [query, sections, basePath],
   );
   const hasCustomContent = content !== undefined;
   const page = hasCustomContent
@@ -555,7 +598,40 @@ export function DocBrowser({
 
   // `navigate` emite `popstate`, então o host é notificado nos dois modos — inclusive o
   // que ainda escuta o evento na unha, que era como este componente avisava antes.
-  const go = (to: string): void => navigate(to);
+  const go = (to: string): void => {
+    if (compactNavigation) {
+      setNavigationOpen(false);
+      navigationButtonRef.current?.focus();
+    }
+    navigate(to);
+  };
+
+  useEffect(() => {
+    setNavigationOpen(false);
+    if (
+      collapsibleNavigation &&
+      document.getElementById(navigationId)?.contains(document.activeElement)
+    )
+      navigationButtonRef.current?.focus();
+  }, [path, collapsibleNavigation, navigationId]);
+
+  useEffect(() => {
+    if (previousQuery.current === query) return;
+    previousQuery.current = query;
+    if (collapsibleNavigation && query.trim()) setNavigationOpen(true);
+  }, [collapsibleNavigation, query]);
+
+  useEffect(() => {
+    if (!sidebar || !compactNavigation || !navigationOpen) return;
+    const closeOnEscape = (event: KeyboardEvent): void => {
+      if (event.key !== "Escape" || event.defaultPrevented) return;
+      event.preventDefault();
+      setNavigationOpen(false);
+      navigationButtonRef.current?.focus();
+    };
+    document.addEventListener("keydown", closeOnEscape);
+    return () => document.removeEventListener("keydown", closeOnEscape);
+  }, [sidebar, compactNavigation, navigationOpen]);
 
   useEffect(() => {
     if (!hasCustomContent && requestedSlug !== slug)
@@ -592,9 +668,14 @@ export function DocBrowser({
     <div className="mx-auto max-w-3xl px-8 py-8">{page?.render()}</div>
   );
 
-  return (
+  const browser = (
     <Split className="h-full">
-      <Pane initialSize={sidebarSize}>
+      <Pane
+        id={collapsibleNavigation ? navigationId : undefined}
+        initialSize={compactNavigation ? undefined : sidebarSize}
+        grow={compactNavigation}
+        className={compactNavigation && !navigationOpen ? "hidden" : undefined}
+      >
         <Sidebar className="w-full">
           <div className="flex min-h-0 flex-1 flex-col">
             {search !== false && searchOptions.placement !== "external" && (
@@ -632,6 +713,7 @@ export function DocBrowser({
                 forceExpanded={query.trim() !== ""}
                 initiallyCollapsed={sidebarInitiallyCollapsed}
                 links={sidebarLinks}
+                onNavigate={go}
                 onSelect={(nextSlug) => go(`${basePath}/${nextSlug}`)}
               />
             </div>
@@ -641,10 +723,38 @@ export function DocBrowser({
       <Pane
         key={hasCustomContent ? path : page?.slug}
         grow
-        className="overflow-y-auto"
+        className={
+          compactNavigation && navigationOpen ? "hidden" : "overflow-y-auto"
+        }
       >
         {readingContent}
       </Pane>
     </Split>
   );
+
+  if (!collapsibleNavigation) return browser;
+  return (
+    <div data-slot="doc-browser" className="flex h-full min-h-0 flex-col">
+      {compactNavigation && (
+        <div className="shrink-0 border-b border-border p-2">
+          <Button
+            ref={navigationButtonRef}
+            context="neutral"
+            variant="ghost"
+            aria-controls={navigationId}
+            aria-expanded={navigationOpen}
+            onClick={() => setNavigationOpen((open) => !open)}
+          >
+            {navigationOpen ? (
+              <X aria-hidden="true" />
+            ) : (
+              <Menu aria-hidden="true" />
+            )}
+            Navegação
+          </Button>
+        </div>
+      )}
+      {browser}
+    </div>
+  );
 }

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

@@ -536,7 +536,7 @@ render(
 | `text`     | `{ fields }` — liga a busca; convenção: param `q` no input. Ela aparece depois dos filtros inline e imediatamente antes do acesso aos filtros avançados. A busca participa da contagem de controles inline: com mais de um controle, a barra exibe as labels; quando ela é o único recorte, sua label é omitida.                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `sort`     | `{ fields, default }` — ordenação inicial; header ordenável escreve `sort: 'chave:dir'`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `periods`  | `{ value, label, default? }[]` — o controle de período (presets + Personalizado com calendário); `default: true` marca o preset inicial, senão vale o primeiro; materializa em `from`/`to` no input.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
-| `grouping` | `{ fields }` — dimensões enumeráveis disponíveis em **Agrupar por**. Cada nome referencia um filtro `select` ou `lookup` com até 12 opções declaradas ou resolvidas por `filterOptions`. Não define agrupamento inicial.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `grouping` | `{ fields }` — dimensões enumeráveis disponíveis em **Agrupar por**. Cada nome referencia um filtro `select` ou `lookup` com até 12 opções declaradas ou resolvidas por `filterOptions`. Não define agrupamento inicial.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 
 ## useListAction
 
@@ -547,6 +547,14 @@ declarativo (`items`, `total`, `error`, `isLoading`, `isFetching`, `refetch`) so
 chamar a action. `options.enabled` suspende a consulta enquanto for `false`; sem a opção, vale
 `true`.
 
+## Controles da visualização
+
+Controles específicos da visualização ativa, como a orientação de um comparativo, usam
+`viewControls`. O slot fica imediatamente após o seletor de visualização. As configurações da lista
+aparecem antes desse conjunto. O consumidor controla seu estado e quando exibi-lo. Isso mantém a
+configuração visual junto à escolha da visualização, sem deslocar ações sobre o recorte
+para fora de `toolbarActions`.
+
 ## Propriedades de ActionList
 
 | Propriedade             | Tipo                                                                                                        | Padrão                                                                                                                                | Descrição                                                                                                                                                                                                     |
@@ -555,7 +563,7 @@ chamar a action. `options.enabled` suspende a consulta enquanto for `false`; sem
 | `input`                 | `TInput`                                                                                                    |                                                                                                                                       | O escopo base, como `{ workspaceId }`. A toolbar acrescenta busca, filtros e paginação sem sobrescrever essas chaves.                                                                                         |
 | `layout`                | `'flow' \| 'fill'`                                                                                          | `'fill'` como filha direta de `PageBody`, `SurfaceBody` ou do corpo da `Presentation` em uma página `fill`; `'flow'` nos demais casos | Em `fill`, ocupa a altura de um ancestral limitado e rola somente a região de resultados; na tabela, o cabeçalho fica fixo. Sem ancestral limitado, equivale a `flow`.                                        |
 | `cells`                 | `Record<string, (item) => ReactNode>`                                                                       |                                                                                                                                       | Células custom por cima das colunas do contrato (chave = column.key).                                                                                                                                         |
-| `filterOptions`         | `Record<string, SelectOption[]>`                                                                            |                                                                                                                                       | Opções de runtime para filtros select/lookup. Em uma dimensão de agrupamento, a coleção precisa ser completa e ter de 1 a 12 itens.                                                                            |
+| `filterOptions`         | `Record<string, SelectOption[]>`                                                                            |                                                                                                                                       | Opções de runtime para filtros select/lookup. Em uma dimensão de agrupamento, a coleção precisa ser completa e ter de 1 a 12 itens.                                                                           |
 | `filterDefaults`        | `Record<string, string>`                                                                                    |                                                                                                                                       | Valores de repouso aplicados à consulta; o `X` só aparece quando o filtro diverge deles e retorna a eles.                                                                                                     |
 | `filterIcons`           | `Record<string, ReactNode>`                                                                                 |                                                                                                                                       | Ícones leading dos filtros, indexados pelo nome declarado no contrato.                                                                                                                                        |
 | `advancedFilters`       | `{ columns?: 1 \| 2 \| 3; sectionIcons?: Record<string, ReactNode>; sectionVariant?: 'plain' \| 'framed' }` | `{ columns: 1, sectionVariant: 'plain' }`                                                                                             | Define as colunas, os ícones e o tratamento dos grupos; o Opus deriva a largura correspondente do diálogo.                                                                                                    |
@@ -575,5 +583,6 @@ chamar a action. `options.enabled` suspende a consulta enquanto for `false`; sem
 | `errorMessage`          | `string`                                                                                                    | `'Não foi possível carregar.'`                                                                                                        | Título do aviso de erro; a ação de tentar de novo refaz a consulta.                                                                                                                                           |
 | `retryLabel`            | `string`                                                                                                    | `'Tentar de novo'`                                                                                                                    | Nome acessível e tooltip da ação de recuperação.                                                                                                                                                              |
 | `onRowClick`            | `(item: TItem) => void`                                                                                     |                                                                                                                                       | Clique na linha (ex.: navegar para o detalhe) — só na tabela.                                                                                                                                                 |
+| `viewControls`          | `ReactNode`                                                                                                 |                                                                                                                                       | Controles da visualização ativa, imediatamente após o seletor de visualização.                                                                                                                                |
 | `toolbarActions`        | `ReactNode`                                                                                                 |                                                                                                                                       | Operações ligadas ao recorte atual, no fim da barra e separadas do grupo de controles. Os nós são renderizados como recebidos: nome acessível e tooltip de uma ação somente com ícone ficam com o consumidor. |
 | `rowActions`            | `(item: TItem) => ReactNode`                                                                                |                                                                                                                                       | Ações por linha (coluna final, à direita). A partir de duas, entram em um grupo com intervalo compacto; uma só fica solta, sem grupo. Cliques ali não disparam o `onRowClick`.                                |

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

@@ -32,22 +32,22 @@ há texto visível. O glifo dentro do controle acompanha o tamanho (0.875rem em
 | Nome      | Medida  | Uso                                                                                                                                   |
 | --------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
 | `xs`      | 1.5rem  | Ação dentro de um campo (`InputGroupButton`).                                                                                         |
-| `sm`      | 2rem    | Operação densa em toolbar ou dentro de uma seção, ao lado de `Select` e `Tabs` `sm`.                                                  |
-| `default` | 2.25rem | Decisão da superfície: header de Page, criação no cabeçalho de uma coleção e footer de Dialog ou Drawer; é também a linha de `Input`. |
+| `sm`      | 2rem    | Headers, criação de coleções e operações densas de toolbar ou seção.                                                  |
+| `default` | 2.25rem | Footers de Dialog e Drawer e controles comuns; é também a linha 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 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-sm` | 2rem | 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`.                                                                                                  |
 
 Escolha o tamanho pela região, não pela importância visual: `variant` e `context` resolvem a
-hierarquia da ação. Headers de Page, a criação no cabeçalho de uma coleção e footers de
-[`Dialog`](/ui/dialog) e [`Drawer`](/ui/drawer) usam `default`; a criação de uma coleção é um botão textual, sem
-ícone, como mostra [`Surface`](/ui/surface). Operações densas de toolbar ou de seção usam `sm`;
+hierarquia da ação. Headers de Page, Dialog, Drawer e Surface usam `sm`/`icon-sm`. A criação
+no cabeçalho de uma coleção usa `sm` textual, sem ícone. Footers de
+[`Dialog`](/ui/dialog) e [`Drawer`](/ui/drawer) conservam `default`. Operações densas de toolbar ou de seção usam `sm`;
 ações dentro de linha ou célula usam `xs` ou `icon-xs`. Assim a mesma decisão mantém a mesma altura
 mesmo quando uma superfície troca uma ação secundária por uma primária.
 
-O retorno de `PageBack` usa `icon`. O fechamento de Dialog e Drawer é um `CloseButton` circular
+O retorno de `PageBack` usa `icon-sm`. O fechamento de Dialog e Drawer é um `CloseButton` circular
 (`shape="pill"`), `neutral` e `subtle`, no quadrado `icon-sm` por padrão, ou `icon-xs` com
 `closeSize="xs"`.
 

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

@@ -24,8 +24,8 @@ Cada família dá um nome próprio a cada região. A tabela mostra a correspond
 | Navegação            | `PageNavigation` ou `PageBack`              | `DialogNavigation`            | `DrawerNavigation`            | Não existe                    |
 | Título no cabeçalho  | `PageTitle`                                 | `DialogTitle`                 | `DrawerTitle`                 | `SurfaceTitle`                |
 | Ações do cabeçalho   | `PageActions`                               | `DialogActions`               | `DrawerActions`               | `SurfaceActions`              |
-| Intro                | `Surface level={1}` no início do `PageBody` | `DialogIntro`                 | `DrawerIntro`                 | Não existe                    |
-| Ações da intro       | Ações da `Surface level={1}`                | `DialogIntroActions`          | `DrawerIntroActions`          | Não existe                    |
+| Intro                | `PageIntro` no início do `PageBody` | `DialogIntro`                 | `DrawerIntro`                 | Não existe                    |
+| Ações da intro       | `PageIntroActions`                | `DialogIntroActions`          | `DrawerIntroActions`          | Não existe                    |
 | Corpo                | `PageBody`                                  | `DialogBody`                  | `DrawerBody`                  | `SurfaceBody`                 |
 | Rodapé               | `PageFooter`                                | `DialogFooter`                | `DrawerFooter`                | `SurfaceFooter`               |
 | Divisores            | Antes do `PageFooter`                       | `sectioned` (padrão)          | `sectioned` (padrão)          | `sectioned`                   |
@@ -97,7 +97,7 @@ function DialogWithIntro({ layout, label }) {
       <DialogContent layout={layout}>
         <DialogHeader>
           <DialogActions>
-            <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+            <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
               <MessageCircle />
             </Button>
           </DialogActions>
@@ -142,7 +142,7 @@ function CompactDialog({ layout, label }) {
             <Button variant="outline" size="sm">
               Ver histórico
             </Button>
-            <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+            <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
               <MessageCircle />
             </Button>
           </DialogActions>
@@ -197,7 +197,7 @@ function OrderField() {
 function CollapseButton() {
   return (
     <DrawerClose asChild>
-      <Button variant="ghost" size="icon" aria-label="Recolher painel">
+      <Button variant="ghost" size="icon-sm" aria-label="Recolher painel">
         <ChevronsRight />
       </Button>
     </DrawerClose>
@@ -216,7 +216,7 @@ function DrawerWithIntro({ layout, label }) {
             <CollapseButton />
           </DrawerNavigation>
           <DrawerActions>
-            <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+            <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
               <MessageCircle />
             </Button>
           </DrawerActions>
@@ -261,7 +261,7 @@ function CompactDrawer({ layout, label }) {
             <Button variant="outline" size="sm">
               Ver histórico
             </Button>
-            <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+            <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
               <MessageCircle />
             </Button>
           </DrawerActions>
@@ -300,8 +300,8 @@ painel.
 
 ## Page
 
-A `Page` não tem um slot de intro. Com intro, o `PageHeader` guarda a navegação e as ações da
-página, e uma `Surface level={1}` abre o `PageBody` com o título e as ações do conteúdo. A página
+Na composição com intro, o `PageHeader` guarda a navegação e as ações da
+página, e uma `PageIntro` abre o `PageBody` com o título e as ações do conteúdo. A página
 precisa de exatamente um heading principal, por isso o `PageHeader` dessa composição não leva
 `PageTitle`.
 
@@ -322,27 +322,20 @@ render(
           </Breadcrumb>
         </PageNavigation>
         <PageActions>
-          <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+          <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
             <MessageCircle />
           </Button>
         </PageActions>
       </PageHeader>
       <PageBody>
-        <Surface
-          as="section"
-          level={1}
-          title="Editar ordem de serviço"
-          actions={
-            <Button variant="outline" size="sm">
-              Ver histórico
-            </Button>
-          }
-        >
+        <PageIntro>
+          <PageTitle>Editar ordem de serviço</PageTitle>
+          <PageIntroActions><Button variant="outline" size="sm">Ver histórico</Button></PageIntroActions>
+        </PageIntro>
           <div className="space-y-2">
             <Label htmlFor="page-intro-owner">Responsável</Label>
             <Input id="page-intro-owner" defaultValue="Marina Alves" />
           </div>
-        </Surface>
       </PageBody>
       <PageFooter>
         <ButtonGroup mode="spaced">
@@ -380,7 +373,7 @@ render(
           <Button variant="outline" size="sm">
             Ver histórico
           </Button>
-          <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+          <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
             <MessageCircle />
           </Button>
         </PageActions>
@@ -449,7 +442,7 @@ render(
               <Button variant="outline" size="sm">
                 Ver histórico
               </Button>
-              <Button variant="ghost" size="icon" aria-label="Abrir conversa">
+              <Button variant="ghost" size="icon-sm" aria-label="Abrir conversa">
                 <MessageCircle />
               </Button>
             </SurfaceActions>
@@ -477,3 +470,22 @@ Os dois panes recebem conteúdos diferentes sem mudar de componente: o primeiro
 [`Sidebar`](/ui/sidebar), que já tem anatomia própria, e o segundo, uma `Surface` completa. A
 rolagem também pertence ao conteúdo: a `Surface` ocupa a altura do pane com `flex h-full flex-col`,
 e o `SurfaceBody` declara `min-h-0 flex-1 overflow-y-auto` para rolar entre o cabeçalho e o rodapé.
+
+## Ritmo entre regiões e blocos
+
+Surface (incluindo cards e seções), Page, Dialog, Drawer e Tabs organizam o conteúdo
+com intervalos de `1rem`. Os bodies separam seus blocos diretos; grupos internos podem
+ter densidade própria. DetailGroup e Separator não criam margens externas.
+
+Sem delimitação, Surface e Tabs não adicionam padding inferior. Uma Surface com moldura
+ou elevação, assim como Dialog e Drawer, reserva `1rem` até a borda. No layout contínuo,
+o intervalo vem da região anterior. No seccionado, há `1rem` entre cada divisória e o
+conteúdo adjacente. Não some padding e gap para expressar o mesmo intervalo.
+
+Page conserva os recuos laterais e a largura de leitura. Seu body não acrescenta padding
+inferior quando termina a página; antes de um footer seccionado, reserva `1rem` até a linha.
+O modo `flush` remove recuos do body para uma lista ou tabela controlar sua própria borda,
+mas mantém o intervalo entre blocos.
+
+Ao migrar, remova `space-y`, `gap`, `pt` e `pb` locais que apenas reconstruíam esses defaults
+nos slots. Preserve classes de layout internas, como uma grade ou um grupo de campos compacto.

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

@@ -48,7 +48,7 @@ distinta da página.
 ```
 
 O corpo cresce até o limite da janela e passa a rolar; cabeçalho e rodapé permanecem visíveis.
-Seus filhos diretos recebem o ritmo estrutural de `1.5rem`. Um grupo compacto, uma grade ou uma
+Seus filhos diretos recebem o ritmo estrutural de `1rem`. Um grupo compacto, uma grade ou uma
 linha declara a própria relação em um wrapper filho; `flush` fica reservado ao conteúdo que
 controla todo o inset.
 O backdrop escurece a página sem aplicar desfoque.
@@ -126,13 +126,13 @@ fluxo modal encadeado, em que a superfície permanece aberta e troca de etapa.
   <DialogContent>
     <DialogHeader>
       <DialogNavigation>
-        <Button variant="ghost" size="icon" aria-label="Voltar para a lista">
+        <Button variant="ghost" size="icon-sm" aria-label="Voltar para a lista">
           <ArrowLeft />
         </Button>
       </DialogNavigation>
       <DialogTitle>Evento 4821</DialogTitle>
       <DialogActions>
-        <Button variant="ghost" size="icon" aria-label="Mais ações">
+        <Button variant="ghost" size="icon-sm" aria-label="Mais ações">
           <Ellipsis />
         </Button>
       </DialogActions>
@@ -146,9 +146,10 @@ fluxo modal encadeado, em que a superfície permanece aberta e troca de etapa.
 </Dialog>
 ```
 
-Voltar e ações do cabeçalho usam `Button` `ghost` no tamanho `icon` (2.25rem), o mesmo que a
-[`Presentation`](/ui/presentation) usa no voltar. O botão de fechar é menor: um `CloseButton` no
-quadrado `icon-sm` (1.75rem) por padrão.
+O header compartilha a geometria de Page e Surface delimitada: padding de `1rem` e
+linha mínima de `2rem`, nos dois layouts. Declare `size="sm"` nos botões textuais e
+`size="icon-sm"` nos de ícone (`2rem`), incluindo o retorno. `CloseButton` já usa
+`icon-sm` por padrão. Conteúdo maior pode expandir a linha; rodapés preservam sua escala.
 
 O cabeçalho aceita `DialogDescription` como subheading opcional para orientar sobre a finalidade.
 Omita quando repetir o título. Condições, regras de negócio e consequências necessárias à decisão
@@ -656,3 +657,14 @@ comparar as duas formas em cada `layout`, abra [Composições](/ui/compositions)
 | `id` | `string` | | Identificador para associação acessível explícita. |
 | `className` | `string` | | Ajusta a apresentação do parágrafo. |
 | `…props` | `ComponentProps<"p">` | | Atributos nativos. |
+
+## Espaçamento do corpo
+
+O body separa os blocos diretos por `1rem`. Dialog e Drawer são superfícies delimitadas:
+o conteúdo mantém `1rem` até a borda inferior, mesmo sem uma propriedade `framed`.
+Em `sectioned`, o corpo tem `1rem` entre o conteúdo e cada divisória. Em `continuous`,
+o cabeçalho fornece o intervalo superior; sem cabeçalho, o próprio corpo abre esse recuo.
+Use `flush` quando o conteúdo controlar seus próprios recuos.
+
+Na intro, `DialogTitle` usa a mesma escala de `PageTitle` (`1.875rem`). No header
+compacto, o título conserva a escala de `1.125rem`. O nível semântico não altera essas medidas.

package/src/ui/docs/content/documentation-portal.md

@@ -88,7 +88,45 @@ que a pessoa possa consultar, inclusive aquelas disponíveis por URL direta.
 A adaptação do cabeçalho, da leitura editorial e dos catálogos à largura da tela é uma exceção
 restrita ao portal documental. A UI das aplicações e os componentes dos exemplos vivos preservam
 o contrato desktop a partir de `64rem`. O aplicativo organiza a moldura do portal em telas estreitas;
-`DocBrowser` não muda sozinho a orientação de `Split` nem transforma os exemplos em layouts móveis.
+`DocBrowser` não transforma os exemplos em layouts móveis.
+
+### Navegação em telas estreitas
+
+Em portais autônomos, use `collapsibleNavigation` para oferecer um menu recolhível em telas
+de até `48rem`. O botão Navegação abre a árvore na área disponível, no lugar da leitura.
+Selecionar um destino interno ou pressionar Escape recolhe o menu. A busca global abre
+os resultados quando a consulta muda; uma consulta já preenchida na montagem não abre
+o menu sobre a leitura. Ramos abertos manualmente são preservados. Acima desse limite, a lateral
+permanece visível. Sem essa opção, a composição existente não muda.
+
+```tsx
+<DocBrowser sections={sections} editorial collapsibleNavigation />
+```
+
+Ao adotar a opção, retire do host as regras móveis que limitam a altura ou a dimensão
+inicial de `Split` e `Pane`, como a antiga faixa de `14rem`. O navegador passa a organizar
+essa área; a moldura externa continua sendo do aplicativo. Preserve a mesma instância
+de `DocBrowser` ao trocar de área: uma `key` baseada na área descarta o botão que
+recebeu o foco e os ramos abertos. Áreas com mapas diferentes usam `basePath` distintos:
+cada uma preserva seus próprios ramos, sem expandir capítulos da outra. Catálogos que
+compartilham o mapa mantêm o mesmo `basePath`. Dentro de cada mapa, a ordem dos ramos
+deve permanecer estável durante a navegação. Escape retorna ao botão Navegação e mantém a consulta.
+
+### Histórico fora da sequência de leitura
+
+Um arquivo histórico pode continuar disponível no menu e na busca sem aparecer como próxima
+leitura de um guia vigente. Declare `readingSequence: false` na sua `DocSection`:
+
+```tsx
+const archive: DocSection = {
+  label: 'Registros históricos',
+  readingSequence: false,
+  groups: [{ pages: historicalPages }],
+}
+```
+
+A opção afeta somente os links anterior/próxima. URLs diretas e contexto continuam disponíveis;
+ela não é uma restrição de acesso. Seções sem essa declaração participam da sequência.
 
 ## Consulte decisões e entregas
 
@@ -205,6 +243,7 @@ não define as rotas nem a autorização do aplicativo.
 | `content` | `ReactNode` | — | Conteúdo do host no lugar da página documental, mantendo a lateral. O host resolve rota e título; `null` deixa a leitura vazia. |
 | `sidebarLinks` | `{ label: string; href: string; active?: boolean; newTab?: boolean }[]` | `[]` | Destinos globais fora dos capítulos; `active` marca o catálogo atual e `newTab` abre em outra aba com ícone e descrição acessível. |
 | `sidebarInitiallyCollapsed` | `boolean` | `false` | Seções e grupos nomeados começam recolhidos, inclusive em links diretos. A busca revela resultados temporariamente sem alterar os ramos abertos pela pessoa. |
+| `collapsibleNavigation` | `boolean` | `false` | Em telas de até `48rem`, oferece um botão para alternar entre navegação e leitura, preservando a árvore. |
 
 A entrada histórica `@softize/opus/ui/docs` inclui o catálogo e oferece suas páginas quando
 `sections` é omitida. Para conteúdo próprio, prefira a entrada leve do exemplo.

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

@@ -119,7 +119,7 @@ retorno de um fluxo encadeado, em que o painel permanece aberto e troca de etapa
   <DrawerContent side="right">
     <DrawerHeader>
       <DrawerNavigation>
-        <Button variant="ghost" size="icon" aria-label="Voltar para a lista">
+        <Button variant="ghost" size="icon-sm" aria-label="Voltar para a lista">
           <ArrowLeft />
         </Button>
       </DrawerNavigation>
@@ -130,7 +130,7 @@ retorno de um fluxo encadeado, em que o painel permanece aberto e troca de etapa
       </DrawerMedia>
       <DrawerTitle>ABC-1D23</DrawerTitle>
       <DrawerActions>
-        <Button variant="ghost" size="icon" aria-label="Mais ações">
+        <Button variant="ghost" size="icon-sm" aria-label="Mais ações">
           <Ellipsis />
         </Button>
       </DrawerActions>
@@ -144,9 +144,10 @@ retorno de um fluxo encadeado, em que o painel permanece aberto e troca de etapa
 </Drawer>
 ```
 
-Voltar e ações do cabeçalho usam `Button` `ghost` no tamanho `icon` (2.25rem), o mesmo que a
-[`Presentation`](/ui/presentation) usa no voltar. O botão de fechar é menor: um `CloseButton` no
-quadrado `icon-sm` (1.75rem) por padrão.
+O header compartilha a geometria de Page e Surface delimitada: padding de `1rem` e
+linha mínima de `2rem`, nos dois layouts. Declare `size="sm"` nos botões textuais e
+`size="icon-sm"` nos de ícone (`2rem`), incluindo o retorno. `CloseButton` já usa
+`icon-sm` por padrão. Conteúdo maior pode expandir a linha; rodapés preservam sua escala.
 
 O cabeçalho aceita `DrawerDescription` como subheading opcional para orientar sobre a finalidade.
 Omita quando repetir o título. Condições, regras de negócio e consequências necessárias à decisão
@@ -323,3 +324,14 @@ comparar as duas formas em cada `layout`, abra [Composições](/ui/compositions)
 | `id` | `string` | | Identificador para associação acessível explícita. |
 | `className` | `string` | | Ajusta a apresentação do parágrafo. |
 | `…props` | `ComponentProps<"p">` | | Atributos nativos. |
+
+## Espaçamento do corpo
+
+O body separa os blocos diretos por `1rem`. Dialog e Drawer são superfícies delimitadas:
+o conteúdo mantém `1rem` até a borda inferior, mesmo sem uma propriedade `framed`.
+Em `sectioned`, o corpo tem `1rem` entre o conteúdo e cada divisória. Em `continuous`,
+o cabeçalho fornece o intervalo superior; sem cabeçalho, o próprio corpo abre esse recuo.
+Use `flush` quando o conteúdo controlar seus próprios recuos.
+
+Na intro, `DrawerTitle` usa a mesma escala de `PageTitle` (`1.875rem`). No header
+compacto, o título conserva a escala de `1.125rem`. O nível semântico não altera essas medidas.