@softize/opus 25.6.0 → 25.7.0

package/CHANGELOG.md

@@ -1,4 +1,4 @@
-# Changelog do @softize/opus
+# Changelog
 
 O que muda em cada versão — e, quando quebra, **o que fazer**. Regras de leitura:
 minor = novidade compatível; major = breaking (a seção **Breaking** diz a migração).
@@ -7,6 +7,39 @@ 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.
 
+## 25.7.0 — 2026-10-07
+
+Portais de documentação podem manter o mesmo mapa lateral em guias, ADRs e changelog. A superfície
+leve `@softize/opus/ui/docs/browser` passa a oferecer `DocHeader`, `DocCatalog`, `DocRecordDetail`
+e parsers de decisões e versões, sem carregar o catálogo do SDK nem o compilador de exemplos.
+O host continua responsável por fontes, rotas e autorização.
+
+`DocBrowser` aceita busca externa controlada, largura inicial da lateral, grupos inicialmente
+recolhidos, destinos globais, páginas fora da árvore e conteúdo do host no lugar de um guia. O modo
+editorial acrescenta contexto, sumário dos títulos renderizados e continuidade entre páginas.
+A busca revela resultados sem perder a escolha manual dos ramos abertos. As novas propriedades
+são opcionais: os consumidores existentes preservam a composição e os defaults anteriores.
+
+O cabeçalho compartilhado mantém a busca documental compacta e centralizada. Os catálogos têm
+busca textual própria dentro da página, independente do topo. ADRs apresentam contexto curto;
+changelog mantém o texto das versões e destaca cuidados de atualização. Não há tabela, filtros,
+controles de ordenação ou paginação nesses índices estáticos.
+
+A adaptação à largura da tela é restrita ao cabeçalho, à leitura editorial e aos catálogos do
+portal documental. A UI das aplicações e os componentes demonstrados nos exemplos vivos continuam
+com o contrato desktop a partir de `64rem` da ADR 0017.
+
+O portal do Opus passa a abrir pela documentação, com Visão geral, Instalação e Primeiros passos
+antes das referências. ADRs e Changelog entram na lateral; os endereços anteriores dos guias e do
+catálogo de UI são preservados. Não há migração obrigatória para quem não adotar essas composições.
+
+Links de `SidebarItem` podem declarar `href`, com o tratamento de foco dos botões e abertura em
+outra aba; sem esse campo, o item continua sendo um botão. A consulta do topo preserva a posição
+de leitura dos registros. O changelog limita os cuidados de atualização à seção `Breaking`, sem
+incluir novidades ou correções seguintes; resumos e detalhes preservam a ordem original das seções.
+O changelog embutido usa **Breaking: cuidados ao atualizar** no lugar de **Breaking — o que fazer**.
+O catálogo usa esse mesmo rótulo.
+
 ## 25.6.0 — 2026-10-07
 
 Aplicações que apresentam Markdown do próprio produto podem usar

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

@@ -2,6 +2,7 @@
 
 - **Status:** aceita.
 - **Data:** 2026-09-15.
+- **Emenda:** 2026-10-07; portal documental delimitado pela ADR 0057.
 
 ## Contexto
 
@@ -28,6 +29,22 @@ Footers de formulário modal dimensionam as ações pelo conteúdo e usam `Cance
 `distribution="equal"` permanece uma escolha explícita para decisões de peso equivalente e,
 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
+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
+UI das aplicações. O host documental continua responsável pela composição de sua moldura em tela
+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.
+
 ## Consequências
 
 - O mesmo componente preserva a composição a partir de `64rem`, inclusive dentro de panes,
@@ -50,5 +67,7 @@ nesse caso, o cancelamento usa `outline`.
 ## 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.
 - 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

@@ -0,0 +1,152 @@
+# ADR 0057 — Portal documental compartilha navegação, busca e leitura
+
+- **Status:** aceita para implementação local; publicação pendente.
+- **Data:** 2026-10-07.
+
+## Contexto
+
+Portais de documentação precisam apresentar guias, decisões e entregas sem trocar o mapa de
+navegação a cada destino. O `DocBrowser` já organiza páginas, busca e árvore, mas sua composição
+original mantém o campo na lateral e não permite usar o cabeçalho ou substituir a leitura por um
+catálogo. Os portais do Opus e da Grand Brasil precisam dessas variações.
+
+Copiar a árvore, a filtragem e o grid em cada aplicação cria comportamentos concorrentes e repete
+defeitos de layout. Incorporar marca, rotas e autorização ao navegador, por outro lado, faria o SDK
+assumir decisões do produto hospedeiro. A extensão precisa compartilhar a composição sem transferir
+essas responsabilidades.
+
+## Decisão vigente
+
+A superfície leve `@softize/opus/ui/docs/browser` oferece navegação, cabeçalho e leitura para fontes
+fornecidas pelo host, sem importar o catálogo do Opus nem o compilador de exemplos vivos. A entrada
+histórica `@softize/opus/ui/docs` mantém o catálogo completo e reexporta a mesma composição.
+
+### Cabeçalho e busca documental
+
+`DocHeader` recebe marca, busca, ações e navegação opcional. Centraliza a geometria do topo, com
+busca compacta de até `22rem`, colunas simétricas nas extremidades e uma linha própria para o campo
+em telas menores que `64rem`. Não conhece tema, repositório, rotas ou estado de pesquisa.
+
+`DocBrowser.search` mantém duas composições:
+
+- `placement: "sidebar"` preserva o campo e o estado local existentes.
+- `placement: "external"` recebe o valor controlado pelo host, filtra a mesma árvore e não
+  renderiza um segundo campo.
+
+Nos dois portais, a busca documental mantém rótulo, apresentação, valor e função em guias,
+catálogos e registros. Pesquisa os guias na lateral; não se transforma silenciosamente numa busca
+de ADRs ou versões.
+
+### Hierarquia e leitura
+
+`sidebarSize` configura a largura inicial usando o `PaneSize` do `Split`. A omissão preserva
+`14rem`. `sidebarInitiallyCollapsed` permite começar com seções e grupos nomeados recolhidos,
+inclusive quando a pessoa abre uma página por URL direta. A busca revela os resultados
+temporariamente; limpá-la restaura os ramos abertos manualmente.
+
+`sidebarLinks` apresenta destinos globais após os capítulos, no mesmo nível visual e fora da
+sequência anterior/próxima. `active` identifica o catálogo atual. `navigationTitle` oferece um
+rótulo curto para uma página sem alterar seu título completo ou os termos pesquisáveis.
+
+Esses destinos usam `SidebarItem.href`, não uma cópia do estilo da linha. A extensão preserva o
+botão quando `href` é omitido, o foco nos dois modos e a abertura nativa em outra aba. Quando há
+`onClick`, somente a navegação simples é interceptada; o host mantém a decisão de roteamento.
+
+O modo opcional `editorial` acrescenta contexto, sumário dos headings realmente renderizados e
+links de continuidade segundo a ordem declarada. `additionalPages` preserva URLs de páginas fora
+da árvore e da sequência. O renderer de exemplos aceita `codeCollapsible={false}` quando ocultar
+o código interromperia uma explicação didática.
+
+### Catálogos e registros
+
+`content` substitui a área de leitura sem desmontar a árvore. Quando esse slot é fornecido, o
+host resolve rota e título; o navegador não escolhe uma página dos guias nem aplica seus redirects.
+`null` representa uma leitura intencionalmente vazia. `sidebar={false}` permite atender
+consumidores que precisem de uma página isolada, mas os dois portais mantêm a lateral em
+guias, catálogos e registros.
+
+`DocCatalog` oferece leitura editorial de registros estáticos, sem tabela, filtros, ordenação
+configurável ou paginação. ADRs apresentam número, título, metadata declarada e o primeiro
+parágrafo do contexto. Changelog apresenta texto integral por versão, com data e cuidados de
+atualização em destaque. Os registros mais recentes aparecem primeiro.
+
+Cada catálogo tem um campo textual na própria página. `query` e `onQueryChange` são controlados
+pelo host, independentemente da busca documental. Os portais preservam a consulta local ao abrir
+um registro e voltar, e a limpam ao trocar de catálogo; não limpam a consulta do topo pela navegação.
+
+`DocRecordDetail` apresenta somente o nome do catálogo antes do título, sem breadcrumb ou retorno
+duplicado. A navegação permanece na lateral. Para preservar os ramos abertos, o host mantém a mesma
+instância de `DocBrowser` entre guia, catálogo e registro.
+
+Os parsers projetam as mesmas fontes Markdown, sem cadastro editorial paralelo. Não inferem data
+ou status ausentes, resumo sem seção de contexto ou releases anteriores ao versionamento.
+Ressalvas do status permanecem no texto integral da ADR.
+
+Este índice estático é uma exceção deliberada ao uso de `ActionList`: publica arquivos versionados
+e funciona sem API da aplicação. Não substitui coleções de recursos servidas por actions.
+
+### Relação com o contrato desktop da UI
+
+A composição documental é uma exceção explícita à ADR 0017: `DocHeader.tsx`, `DocBrowser.tsx`
+(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.
+
+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
+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.
+
+## Alternativas consideradas
+
+### Manter campo, largura e leitura fixos
+
+Preservaria uma API menor, mas obrigaria portais autônomos a copiar a árvore ou adotar a composição
+do catálogo embutido. As novas propriedades são opcionais e mantêm os defaults existentes.
+
+### Compor todo o portal dentro de DocBrowser
+
+Centralizaria a implementação, ao custo de misturar identidade visual, navegação global,
+autorização e rotas do host com a leitura documental. `DocHeader` compartilha somente a geometria;
+`content` compartilha o mapa sem decidir os destinos.
+
+### Copiar grids e filtragem nos consumidores
+
+Evitaria a extensão do pacote, mas os primeiros consumidores já repetiram um desalinhamento do
+cabeçalho. `PageHeader` e `PageShell` organizam páginas de recursos, não o topo de um portal
+documental. Manter essas cópias deixaria o mesmo defeito com duas correções locais.
+
+### Tabela para decisões e entregas
+
+Foi implementada no protótipo com filtro, ordenação e paginação, mas rejeitada na avaliação visual.
+ADRs precisam de contexto para escolher a leitura; changelog precisa manter a continuidade do texto.
+A busca textual atende a consulta sem acrescentar controles de coleção.
+
+### Ocultar a lateral e trocar o alcance da busca no catálogo
+
+Também foi experimentado e substituído após avaliação. Ocultar a lateral interrompia o mapa;
+trocar o alcance do campo superior tornava a pesquisa ambígua. A decisão vigente mantém a lateral
+e separa a consulta documental da consulta local.
+
+## Consequências
+
+- Consumidores existentes preservam campo lateral, largura de `14rem` e composição não editorial.
+- A biblioteca mantém uma árvore e uma regra de busca; o host mantém conteúdo, rotas e autorização.
+- 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.
+
+## Verificação
+
+- Testes de `DocBrowser`: busca local e externa, vazio, largura configurável, lateral opcional,
+  persistência de grupos, expansão temporária, conteúdo do host, redirects e leitura editorial.
+- Testes de `DocHeader`: slots, atributos nativos e composição com ou sem busca e navegação.
+- Testes de `DocCatalog`: busca local controlada, independência do topo, ausência de controles de
+  coleção, texto integral das versões, incompatibilidades e abertura nativa em outra aba.
+- Testes dos parsers: metadata ausente, resumo canônico, acentos e termos combinados, texto integral
+  e ausência de versões retroativas fabricadas.
+- Inspeção dos dois portais: largura estreita, alinhamento do topo, lateral persistente, busca,
+  URLs diretas, ida ao registro e retorno ao catálogo.

package/docs/adr/README.md

@@ -0,0 +1,12 @@
+---
+title: Decisões arquiteturais
+order: -1
+---
+# Decisões arquiteturais
+
+As ADRs registram o contexto, as alternativas e as consequências das decisões estruturais do
+Opus. Use a Documentação para compreender o contrato vigente; consulte esta área quando precisar
+entender por que uma restrição existe ou como ela evoluiu.
+
+Uma ADR preserva seu contexto histórico mesmo quando é substituída. O comportamento vigente deve
+estar documentado na superfície correspondente, sem exigir a reconstrução dessa sequência.

package/package.json

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

package/src/ui/components/patterns/sidebar.tsx

@@ -77,7 +77,9 @@ export interface SidebarItemProps {
   /** Complemento do tooltip no rail recolhido. */
   tooltipHint?: ReactNode;
   className?: string;
-  onClick: () => void;
+  /** Destino nativo. Com onClick, intercepta somente a navegação simples; preserva novas abas. */
+  href?: string;
+  onClick?: () => void;
 }
 
 /** Linha única de navegação: o alvo principal e seus controles são irmãos, nunca botões aninhados. */
@@ -95,8 +97,29 @@ export function SidebarItem({
   tooltipHint,
   className,
   onClick,
+  href,
 }: SidebarItemProps): React.ReactElement {
   const collapsed = useSidebarCollapsed();
+  const Target = href !== undefined && !disabled ? "a" : "button";
+  const targetProps =
+    Target === "a" ? { href } : { type: "button" as const, disabled };
+  const activate = (
+    event: React.MouseEvent<HTMLAnchorElement | HTMLButtonElement>,
+  ) => {
+    if (href !== undefined) {
+      if (
+        event.button !== 0 ||
+        event.metaKey ||
+        event.ctrlKey ||
+        event.shiftKey ||
+        event.altKey ||
+        !onClick
+      )
+        return;
+      event.preventDefault();
+    }
+    onClick?.();
+  };
   const hasActions = actions !== undefined && actions !== null;
   // O rótulo cortado esmaece em vez de terminar em reticências; a medição do transbordo
   // mantém a máscara fora do rótulo que cabe inteiro na linha.
@@ -104,12 +127,11 @@ export function SidebarItem({
     useOverflowing<HTMLSpanElement>(label);
   if (collapsed) {
     const button = (
-      <button
-        type="button"
-        disabled={disabled}
+      <Target
+        {...targetProps}
         aria-label={label}
         aria-current={active ? "page" : undefined}
-        onClick={onClick}
+        onClick={activate}
         className={cn(
           "mx-auto grid size-10 place-items-center rounded-md transition-colors disabled:pointer-events-none disabled:opacity-40",
           "outline-none",
@@ -125,7 +147,7 @@ export function SidebarItem({
         >
           {icon}
         </span>
-      </button>
+      </Target>
     );
     // `className` vai no MESMO elemento nos dois modos — a linha —, senão a prop mudaria de alvo
     // conforme o rail estivesse recolhido, e o consumidor não teria como saber o que estilizou.
@@ -209,11 +231,10 @@ export function SidebarItem({
           )}
         </span>
       )}
-      <button
-        type="button"
-        disabled={disabled}
+      <Target
+        {...targetProps}
         aria-current={active ? "page" : undefined}
-        onClick={onClick}
+        onClick={activate}
         className={cn(
           "flex min-w-0 flex-1 items-center gap-2.5 rounded-md px-2.5 py-1.5 text-left text-sm disabled:pointer-events-none",
           "outline-none",
@@ -254,7 +275,7 @@ export function SidebarItem({
             {badge}
           </span>
         )}
-      </button>
+      </Target>
       {hasActions && (
         <div
           data-slot="sidebar-item-actions"