@softize/opus 25.5.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,55 @@ 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
+`@softize/opus/ui/docs/links` para resolver caminhos relativos, derivar slugs e normalizar
+fragmentos sem carregar React. A entrada `@softize/opus/ui/docs/browser` também reexporta esses
+utilitários. O renderizador compartilhado usa a mesma normalização nos IDs dos títulos, inclusive
+quando o texto contém hífens cercados por espaços ou repetidos; assim, links e headings deixam de
+divergir nesses casos.
+
+Não há migração geral obrigatória. Links profundos já salvos para títulos com hífen cercado por
+espaços ou com hífens consecutivos precisam usar um único hífen; por exemplo, `a---b` passa a ser
+`a-b`. Consumidores que já implementam essa gramática localmente podem substituí-la pelos
+utilitários compartilhados e continuar decidindo a rota e o espaço de destino. O resolvedor aceita
+fontes `.md` e `.mdx`; o caminho atual é relativo à raiz documental, e apenas `/docs/` com barra
+inicial declara essa raiz num link absoluto.
+
 ## 25.5.0 — 2026-10-07
 
 Aplicações que publicam documentação própria podem usar a nova entrada

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/0056-doc-browser-separa-runtime-leve-do-catalogo.md

@@ -43,6 +43,12 @@ O renderizador compartilhado pode reescrever links e criar IDs estáveis para t
 opções são explícitas; o caminho usado em conversas continua sem IDs e sem tratamento editorial
 quando elas não são pedidas. Frontmatter é removido somente nas superfícies documentais.
 
+O subpath leve `@softize/opus/ui/docs/links` publica a normalização de âncoras, a derivação de slug a
+partir do caminho da fonte e a resolução de links Markdown relativos sem carregar React. A entrada
+`browser` também os reexporta por conveniência. O renderizador e os consumidores usam essas funções
+em comum: uma aplicação decide em qual espaço ou superfície abrir a fonte resolvida, mas não
+reimplementa a gramática de caminhos, prefixos numéricos e fragmentos.
+
 ### 4. A superfície permanece no pacote Opus
 
 O runtime leve continua em `@softize/opus` enquanto compartilha dependências, manutenção e ciclo
@@ -73,5 +79,7 @@ existir evidência operacional para sustentar essa separação.
 - Classificação, autorização e conteúdo permanecem responsabilidade do consumidor.
 - A busca é local e recebe o conteúdo no navegador; ela não substitui filtragem no servidor quando
   houver documentos com audiências diferentes.
+- Links Markdown relativos, slugs e fragmentos seguem uma gramática compartilhada; o consumidor
+  continua responsável por mapear a fonte resolvida para seu espaço, sua rota e sua política.
 - Um teste de arquitetura percorre o grafo do novo subpath e reprova se ele alcançar catálogo,
   exemplos vivos ou o compilador correspondente.

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.5.0",
+  "version": "25.7.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",
@@ -221,6 +221,10 @@
       "types": "./src/ui/docs/browser.tsx",
       "default": "./src/ui/docs/browser.tsx"
     },
+    "./ui/docs/links": {
+      "types": "./src/ui/docs/links.ts",
+      "default": "./src/ui/docs/links.ts"
+    },
     "./ui/docs/standalone": {
       "types": "./src/ui/docs/standalone.tsx",
       "default": "./src/ui/docs/standalone.tsx"

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"

package/src/ui/components/primitives/markdown.tsx

@@ -12,6 +12,7 @@
  */
 import * as React from 'react'
 import MarkdownIt from 'markdown-it'
+import { documentationHeadingAnchor } from '../../docs/links.ts'
 
 /** A instância ÚNICA — a doc (`DocMarkdown`) importa esta mesma. Duas instâncias com
  *  opções próprias divergiriam no primeiro edge case, e "mesmo motor" viraria promessa. */
@@ -60,16 +61,6 @@ function resolveTokenLinks(tokens: ReturnType<typeof markdownIt.parse>, resolveH
   }
 }
 
-function headingId(value: string): string {
-  return value
-    .normalize('NFD')
-    .replace(/[\u0300-\u036f]/g, '')
-    .toLocaleLowerCase('pt-BR')
-    .replace(/[^a-z0-9\s-]/g, '')
-    .trim()
-    .replace(/\s+/g, '-')
-}
-
 function visibleInlineText(tokens: ReturnType<typeof markdownIt.parse>): string {
   return tokens
     .map((token) => {
@@ -87,7 +78,7 @@ function identifyHeadings(tokens: ReturnType<typeof markdownIt.parse>): void {
     const content = tokens[index + 1]
     if (opening?.type !== 'heading_open' || content?.type !== 'inline') continue
     const text = visibleInlineText(content.children ?? [])
-    const base = headingId(text)
+    const base = documentationHeadingAnchor(text)
     if (base === '') continue
     let candidate = base
     let suffix = 1