@softize/opus 27.0.0 → 27.1.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ Depois de qualquer bump, rode os gates (`typecheck` · `test` · `opus check` ·
 `opus copy --check` · `base copy check` · `manifest:check`) — eles apontam o que a
 mudança cobra do seu código.
 
+## 27.1.0 — 2026-10-13
+
+Portais documentais podem oferecer navegação recolhível em telas estreitas com
+`DocBrowser.collapsibleNavigation`. O menu ocupa a área disponível, preserva os ramos
+abertos e mostra os resultados da busca; selecionar um destino interno ou pressionar
+Escape retorna à leitura. A composição desktop e consumidores sem a opção não mudam.
+
+**Ao adotar:** remova as regras CSS móveis do host que limitavam `Split` e `Pane` a
+uma faixa curta. Preserve a instância de `DocBrowser` entre áreas, sem uma `key`
+que remonte o navegador a cada troca; isso mantém a busca, os ramos abertos e o foco.
+Mapas distintos usam `basePath` distintos para preservar a abertura dos ramos de cada
+área. Uma consulta já preenchida na montagem não abre o menu; editar a busca revela
+os resultados.
+
+`DocSection.readingSequence: false` mantém uma seção na navegação e na busca, mas a retira
+dos links de leitura anterior/próxima. Isso permite consultar registros históricos sem
+apresentá-los como continuidade de guias vigentes.
+
 ## 27.0.0 — 2026-10-13
 
 O aplicativo passa a saber, na recusa de um anexo, o que entrou na mesma ação, e o glob do runtime

package/docs/adr/0017-ui-assumes-a-fixed-desktop-layout.md

@@ -2,7 +2,7 @@
 
 - **Status:** aceita.
 - **Data:** 2026-09-15.
-- **Emenda:** 2026-10-07; portal documental delimitado pela ADR 0057.
+- **Emendas:** 2026-10-07 e 2026-10-13; portal documental delimitado pela ADR 0057.
 
 ## Contexto
 
@@ -32,8 +32,9 @@ nesse caso, o cancelamento usa `outline`.
 ### Exceção: portal de documentação
 
 O portal documental tem uma jornada de leitura distinta da UI operacional das aplicações. Conforme
-a ADR 0057, `DocHeader`, a leitura editorial de `DocBrowser` e `DocCatalog`/`DocRecordDetail`
-podem adaptar cabeçalho, espaçamento e sumário à largura da tela. A exceção foi aprovada para
+a ADR 0057, `DocHeader`, a leitura editorial e a navegação móvel opcional de `DocBrowser`,
+além de `DocCatalog`/`DocRecordDetail`, podem adaptar cabeçalho, navegação, espaçamento e
+sumário à largura da tela. A exceção foi aprovada para
 preservar a composição validada nos portais do Opus e da Grand Brasil.
 
 A exceção não torna responsivos `Split`, `Sidebar`, formulários, tabelas ou outros componentes da
@@ -41,9 +42,13 @@ UI das aplicações. O host documental continua responsável pela composição d
 estreita. Exemplos vivos usam o mesmo contrato desktop dos componentes demonstrados; o portal não
 promete que todos os exemplos sejam adequados a telas menores que `64rem`.
 
-O gate permite variantes de viewport somente nos três arquivos documentais identificados na ADR
-0057. Arquivos novos, mesmo dentro de `docs/`, continuam sujeitos à regra até uma decisão explícita.
-Container queries não entram na exceção.
+O gate permite variantes de viewport somente nas funções editoriais identificadas pela ADR 0057.
+A consulta direta de largura via `matchMedia` tem uma exceção separada: somente os helpers
+`subscribeCompactNavigation` e `compactNavigationSnapshot` de `DocBrowser.tsx` podem consultar
+a constante `compactNavigationQuery`, fixada em `(max-width: 48rem)`. Isso não libera variantes
+na função `DocBrowser`. Chamadas diretas com consultas dinâmicas não identificáveis são recusadas;
+preferências explícitas continuam permitidas. Arquivos novos, mesmo dentro de `docs/`, seguem
+a regra. Container queries não entram na exceção.
 
 ## Consequências
 
@@ -67,7 +72,8 @@ Container queries não entram na exceção.
 ## Verificação
 
 - Um teste de inventário reprova variantes de largura e container queries na UI viva.
-- O mesmo teste delimita a exceção documental por arquivo e comprova que ela não alcança componentes
-  da aplicação, outros arquivos documentais ou container queries.
+- O mesmo teste delimita a exceção documental por função e verifica chamadas diretas de `matchMedia`,
+  inclusive constantes e consultas dinâmicas. Mutações fora dos helpers, do arquivo ou do breakpoint
+  documentados reprovam; a exceção não alcança componentes da aplicação nem container queries.
 - Testes estruturais fixam layouts, larguras de modal e distribuição dos footers.
 - Documentação pública declara a largura mínima, o default por conteúdo e a exceção `equal`.

package/docs/adr/0057-doc-browser-permite-busca-no-chrome-do-consumidor.md

@@ -1,8 +1,37 @@
 # ADR 0057 — Portal documental compartilha navegação, busca e leitura
 
-- **Status:** aceita para implementação local; publicação pendente.
+- **Status:** aceita; composição original em 25.7.0, subgrupos e abertura em nova aba em 26.2.0,
+  navegação recolhível e sequência de leitura em 27.1.0.
 - **Data:** 2026-10-07.
 
+> **Emenda — 2026-10-13, versão 27.1.0:** a composição anterior reúne as entregas
+> das versões 25.7.0 e 26.2.0. Esta extensão separa presença no mapa de participação na leitura:
+> `DocSection.readingSequence: false` retira a seção dos links anterior/próxima, mas
+> preserva busca, contexto e URLs. A omissão mantém a sequência existente. Excluir o
+> arquivo histórico da árvore impediria sua descoberta; duplicar o mapa para calcular
+> continuidade criaria duas ordens concorrentes.
+>
+> `DocBrowser.collapsibleNavigation` é opcional e começa desligado. Quando ligado, em
+> telas de até `48rem`, oferece um botão de navegação e começa recolhido. Ao abrir,
+> a árvore ocupa a área disponível no lugar da leitura, sem a faixa fixa de `14rem`.
+> A seleção de um destino interno e a tecla Escape recolhem o menu; editar a busca revela
+> seus resultados. A consulta preenchida na montagem não abre o menu sobre a leitura.
+> A árvore permanece montada para preservar ramos abertos. Acima
+> desse limite, a lateral continua visível. `Split` e `Sidebar` não mudam de contrato.
+> O host preserva a instância também entre Documentação e UI: remontá-la descartaria
+> o botão que recebeu o foco e o estado dos ramos. Mapas distintos usam `basePath`
+> distintos; as chaves dos ramos incluem essa identidade antes da posição no mapa.
+> Assim, abrir um capítulo em Documentação não abre outro na mesma posição em UI,
+> e voltar restaura a abertura manual. A ordem interna de cada mapa permanece estável.
+> Escape retorna
+> o foco ao botão Navegação, inclusive quando acionado pela busca externa; a consulta
+> permanece para permitir retomar os mesmos resultados.
+> Esta composição substitui os ajustes CSS duplicados nos dois portais, estendendo
+> a exceção documental à montagem do navegador, não aos exemplos ou demais telas.
+> A alternativa de manter uma lateral curta preservaria a rolagem que esconde destinos
+> globais. Testes de teclado, redimensionamento, busca, rotas e sequência de leitura,
+> além de inspeção visual nos dois consumidores, verificam a extensão antes de publicar.
+
 ## Contexto
 
 Portais de documentação precisam apresentar guias, decisões e entregas sem trocar o mapa de
@@ -114,10 +143,14 @@ A composição documental é uma exceção explícita à ADR 0017: `DocHeader.ts
 (na leitura editorial) e `DocCatalog.tsx` (incluindo `DocRecordDetail`) podem usar variantes de
 viewport para organizar cabeçalho, sumário e espaçamento. A exceção fica restrita a esses arquivos;
 não libera toda a pasta `docs/` nem container queries. O gate verifica as funções de composição
-permitidas, sem liberar outras funções ou a montagem de `Split` no mesmo arquivo.
+permitidas. A emenda de 13/10 admite a consulta de largura via `matchMedia` apenas nos helpers
+`subscribeCompactNavigation` e `compactNavigationSnapshot`, em `DocBrowser.tsx`, usando a
+constante `compactNavigationQuery` fixada em `(max-width: 48rem)`. Variantes de viewport
+continuam proibidas na função `DocBrowser`; consultas diretas dinâmicas não identificáveis
+também reprovam. Preferências explícitas de acessibilidade e tema permanecem permitidas.
 
 Essa adaptação foi aprovada para o portal de leitura, não para a UI das aplicações. O host organiza
-sua moldura em telas estreitas; `Split`, `Sidebar` e os exemplos vivos não ganham um contrato
+sua moldura; o navegador pode oferecer sua navegação móvel opcional. `Split`, `Sidebar` e os exemplos vivos não ganham um contrato
 responsivo por estarem dentro da documentação. Manter o portal inteiramente desktop descartaria
 a composição já validada; ampliar a exceção para toda a UI alteraria uma decisão fora deste escopo.
 
@@ -159,8 +192,9 @@ e separa a consulta documental da consulta local.
 - Os dois portais compartilham cabeçalho e catálogos sem compartilhar sua taxonomia específica.
 - Guias, índices e fontes acessíveis por URL direta precisam ser filtrados antes de chegar ao
   navegador quando houver restrição de acesso. Esta composição não é uma fronteira de segurança.
-- A consolidação é um candidato local. A publicação e a adoção pela Grand Brasil são etapas
-  distintas, posteriores à revisão independente.
+- A composição original integra a versão 25.7.0; subgrupos e abertura em nova aba, a 26.2.0;
+  a navegação recolhível e a sequência de leitura, a 27.1.0. A adoção por cada portal é uma
+  etapa própria.
 
 ## Verificação
 

package/package.json

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

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/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/types.ts

@@ -25,4 +25,6 @@ export interface DocGroup {
 export interface DocSection {
   label: string
   groups: DocGroup[]
+  /** False exclui a seção da leitura anterior/próxima, sem retirá-la da navegação ou busca. */
+  readingSequence?: boolean
 }