@softize/opus 25.6.0 → 25.7.0

package/src/ui/docs/DocCatalog.tsx

@@ -0,0 +1,255 @@
+import { useEffect, type ReactElement, type ReactNode } from "react";
+import { Search } from "lucide-react";
+import { Input } from "../components/primitives/input.tsx";
+import { Badge } from "../components/primitives/badge.tsx";
+import {
+  Alert,
+  AlertHeader,
+  AlertTitle,
+  AlertDescription,
+} from "../components/primitives/alert.tsx";
+import { Markdown, markdownIt } from "../components/primitives/markdown.tsx";
+import {
+  filterDocumentationRecords,
+  type DocumentationRecord,
+} from "./records.ts";
+import { navigate } from "../router.ts";
+
+function follow(
+  event: React.MouseEvent<HTMLAnchorElement>,
+  href: string,
+): void {
+  if (
+    event.button !== 0 ||
+    event.metaKey ||
+    event.ctrlKey ||
+    event.shiftKey ||
+    event.altKey
+  )
+    return;
+  event.preventDefault();
+  navigate(href);
+}
+
+function DocumentationLink({
+  href,
+  children,
+}: {
+  href: string;
+  children: ReactNode;
+}): ReactElement {
+  return (
+    <a
+      href={href}
+      onClick={(event) => follow(event, href)}
+      className="underline-offset-4 hover:underline"
+    >
+      {children}
+    </a>
+  );
+}
+
+/** O resumo orienta a escolha; links e formatação continuam no documento completo. */
+function summaryText(source: string): string {
+  return (markdownIt.parseInline(source, {})[0]?.children ?? [])
+    .map((token) =>
+      token.type === "softbreak" || token.type === "hardbreak"
+        ? " "
+        : token.content,
+    )
+    .join("");
+}
+
+export interface DocCatalogProps {
+  title: string;
+  description: string;
+  records: readonly DocumentationRecord[];
+  /** Consulta local do catálogo, independente da busca documental do cabeçalho. */
+  query: string;
+  onQueryChange: (query: string) => void;
+  kind: "decisions" | "releases";
+}
+
+/** Leitura dos arquivos publicados, com busca textual e sem controles de coleção. */
+export function DocCatalog({
+  title,
+  description,
+  records,
+  query,
+  onQueryChange,
+  kind,
+}: DocCatalogProps): ReactElement {
+  const filtered = filterDocumentationRecords(records, query).sort(
+    (left, right) =>
+      kind === "decisions"
+        ? Number(right.id) - Number(left.id)
+        : right.id.localeCompare(left.id, "en", { numeric: true }),
+  );
+  return (
+    <div data-slot="doc-catalog" className="h-full overflow-y-auto">
+      <section className="mx-auto w-full max-w-3xl px-4 py-8 md:px-8 md:py-12">
+        <h1 className="text-3xl font-semibold tracking-tight">{title}</h1>
+        <p className="mt-3 text-base text-muted-foreground">{description}</p>
+        <div className="mt-6 max-w-[28rem]">
+          <Input
+            type="search"
+            icon={<Search aria-hidden="true" />}
+            aria-label={
+              kind === "decisions" ? "Buscar nas ADRs" : "Buscar no changelog"
+            }
+            placeholder={
+              kind === "decisions" ? "Buscar nas ADRs…" : "Buscar no changelog…"
+            }
+            value={query}
+            onChange={(event) => onQueryChange(event.target.value)}
+          />
+        </div>
+        <p
+          role="status"
+          aria-live="polite"
+          aria-atomic="true"
+          className={
+            query.trim() ? "mt-5 text-sm text-muted-foreground" : "sr-only"
+          }
+        >
+          {filtered.length} de {records.length} registros
+        </p>
+        <div className="mt-10 space-y-10">
+          {filtered.map((record) => (
+            <article
+              key={record.href}
+              data-slot="doc-catalog-entry"
+              className="border-t border-border/60 pt-6"
+            >
+              <div className="flex flex-wrap items-baseline gap-x-3 gap-y-2">
+                <h2 className="text-xl font-semibold tracking-tight">
+                  <DocumentationLink href={record.href}>
+                    {kind === "decisions"
+                      ? `ADR ${record.id} — ${record.title}`
+                      : record.id}
+                  </DocumentationLink>
+                </h2>
+                {kind === "releases" && (
+                  <span className="text-sm text-muted-foreground">
+                    {record.date ?? "Data não informada"}
+                  </span>
+                )}
+                {kind === "releases" && record.breaking !== undefined && (
+                  <Badge context="danger" variant="solid">
+                    Incompatível
+                  </Badge>
+                )}
+              </div>
+              {kind === "decisions" ? (
+                <>
+                  <p className="mt-2 text-sm text-muted-foreground">
+                    {record.date ?? "Data não informada"} ·{" "}
+                    {record.status ?? "Status não informado"}
+                  </p>
+                  {record.summary && (
+                    <p className="mt-3 text-sm leading-7">
+                      {summaryText(record.summary)}
+                    </p>
+                  )}
+                </>
+              ) : (
+                <>
+                  <div className="mt-3">
+                    <Markdown
+                      content={record.content ?? record.body}
+                      resolveHref={(href) =>
+                        href.startsWith("#") ? `${record.href}${href}` : href
+                      }
+                    />
+                  </div>
+                  {record.breaking !== undefined && (
+                    <Alert context="danger" role="note" className="mt-4">
+                      <AlertHeader>
+                        <AlertTitle>Breaking: cuidados ao atualizar</AlertTitle>
+                        <AlertDescription>
+                          <Markdown
+                            content={record.breaking}
+                            resolveHref={(href) =>
+                              href.startsWith("#") ? `${record.href}${href}` : href
+                            }
+                          />
+                        </AlertDescription>
+                      </AlertHeader>
+                    </Alert>
+                  )}
+                  {record.afterBreaking && (
+                    <div className="mt-3">
+                      <Markdown
+                        content={record.afterBreaking}
+                        resolveHref={(href) =>
+                          href.startsWith("#") ? `${record.href}${href}` : href
+                        }
+                      />
+                    </div>
+                  )}
+                </>
+              )}
+            </article>
+          ))}
+          {filtered.length === 0 && (
+            <p className="border-t border-border/60 pt-6 text-sm text-muted-foreground">
+              Nenhum registro encontrado. Tente outro termo.
+            </p>
+          )}
+        </div>
+      </section>
+    </div>
+  );
+}
+
+export interface DocRecordDetailProps {
+  catalogLabel: string;
+  children: ReactNode;
+}
+
+export function DocRecordDetail({
+  catalogLabel,
+  children,
+}: DocRecordDetailProps): ReactElement {
+  useEffect(() => {
+    let frame: number | undefined;
+    let locationKey: string | undefined;
+    const scrollToFragment = () => {
+      const nextKey = window.location.pathname + window.location.hash;
+      if (nextKey === locationKey) return;
+      locationKey = nextKey;
+      if (frame !== undefined) cancelAnimationFrame(frame);
+      if (!window.location.hash) return;
+      frame = requestAnimationFrame(() => {
+        let id = window.location.hash.slice(1);
+        try {
+          id = decodeURIComponent(id);
+        } catch {
+          /* Um fragmento inválido não interrompe a leitura. */
+        }
+        document.getElementById(id)?.scrollIntoView({ block: "start" });
+      });
+    };
+    scrollToFragment();
+    window.addEventListener("popstate", scrollToFragment);
+    window.addEventListener("hashchange", scrollToFragment);
+    return () => {
+      if (frame !== undefined) cancelAnimationFrame(frame);
+      window.removeEventListener("popstate", scrollToFragment);
+      window.removeEventListener("hashchange", scrollToFragment);
+    };
+  }, []);
+  return (
+    <div data-slot="doc-record-detail" className="h-full overflow-y-auto">
+      <div className="mx-auto max-w-3xl px-4 py-8 md:px-8">
+        <p
+          data-slot="doc-record-context"
+          className="mb-3 text-sm text-muted-foreground"
+        >
+          {catalogLabel}
+        </p>
+        <article>{children}</article>
+      </div>
+    </div>
+  );
+}

package/src/ui/docs/DocHeader.tsx

@@ -0,0 +1,74 @@
+import type {
+  ComponentProps,
+  CSSProperties,
+  ReactElement,
+  ReactNode,
+} from "react";
+import { cn } from "../lib/cn.ts";
+
+export interface DocHeaderProps extends Omit<
+  ComponentProps<"header">,
+  "children"
+> {
+  brand: ReactNode;
+  search?: ReactNode;
+  actions?: ReactNode;
+  navigation?: ReactNode;
+  /** Largura da coluna de marca, normalmente igual à lateral. Default: 17rem. */
+  brandWidth?: string;
+}
+
+/** Topo documental: controles alinhados e navegação global em uma linha própria. */
+export function DocHeader({
+  brand,
+  search,
+  actions,
+  navigation,
+  brandWidth = "17rem",
+  className,
+  style,
+  ...props
+}: DocHeaderProps): ReactElement {
+  return (
+    <header
+      data-slot="doc-header"
+      className={cn("shrink-0 border-b border-border bg-background", className)}
+      style={
+        { "--doc-header-brand-width": brandWidth, ...style } as CSSProperties
+      }
+      {...props}
+    >
+      <div
+        data-slot="doc-header-controls"
+        className="grid min-h-[4.25rem] grid-cols-[minmax(0,1fr)_auto] items-center gap-x-8 gap-y-4 px-4 py-3 md:px-8 lg:grid-cols-[var(--doc-header-brand-width)_minmax(0,1fr)_var(--doc-header-brand-width)]"
+      >
+        <div data-slot="doc-header-brand" className="min-w-0">
+          {brand}
+        </div>
+        <div
+          data-slot="doc-header-search"
+          className={cn(
+            "col-span-2 row-start-2 min-w-0 lg:col-span-1 lg:col-start-2 lg:row-start-1",
+            search == null && "hidden lg:block",
+          )}
+        >
+          <div className="mx-auto w-full max-w-[22rem]">{search}</div>
+        </div>
+        <div
+          data-slot="doc-header-actions"
+          className="col-start-2 row-start-1 flex items-center justify-end gap-1 lg:col-start-3"
+        >
+          {actions}
+        </div>
+      </div>
+      {navigation != null && (
+        <div
+          data-slot="doc-header-navigation"
+          className="overflow-x-auto px-4 md:px-8"
+        >
+          {navigation}
+        </div>
+      )}
+    </header>
+  );
+}

package/src/ui/docs/browser.tsx

@@ -3,7 +3,16 @@
  * Opus, o compilador de exemplos TSX nem os componentes usados apenas por esses exemplos.
  */
 export { DocBrowser } from './DocBrowser.tsx'
-export type { DocBrowserProps } from './DocBrowser.tsx'
+export { DocHeader } from './DocHeader.tsx'
+export { DocCatalog, DocRecordDetail } from './DocCatalog.tsx'
+export type { DocCatalogProps, DocRecordDetailProps } from './DocCatalog.tsx'
+export { decisionRecord, releaseRecords, parseChangelog, filterDocumentationRecords } from './records.ts'
+export type { DocumentationRecord } from './records.ts'
+export type { DocHeaderProps } from './DocHeader.tsx'
+export type {
+  DocBrowserProps,
+  DocBrowserSearchOptions,
+} from './DocBrowser.tsx'
 export { docSectionsFromFolder } from './folder.tsx'
 export type { FolderOptions, FolderPage } from './folder.tsx'
 export {

package/src/ui/docs/changelog.tsx

@@ -5,43 +5,13 @@
  * O parser é convenção-fina sobre o markdown (`## <versão> — <data>` + `### Breaking`);
  * o corpo de cada trecho segue renderizado pelo DocMarkdown (fidelidade total).
  */
-import { Badge } from '../react.tsx'
+import { Alert, AlertHeader, AlertTitle, AlertDescription, Badge } from '../react.tsx'
 import { DocMarkdown } from './markdown.tsx'
 // A fonte é o CHANGELOG DO PACOTE (raiz) — a mesma que viaja em node_modules.
 import changelogMd from '../../../CHANGELOG.md?raw'
-
-export interface ChangelogVersion {
-  version: string
-  date?: string
-  body: string
-  breaking?: string
-}
-
-export interface ParsedChangelog {
-  intro: string
-  versions: ChangelogVersion[]
-}
-
-/** Parseia o changelog: intro (antes do 1º `## `) + versões (`## x — data`, `### Breaking`). */
-export function parseChangelog(source: string): ParsedChangelog {
-  const chunks = `\n${source.trim()}`.split(/\n## /)
-  const intro = chunks[0]?.trim() ?? ''
-  const versions: ChangelogVersion[] = []
-  for (const chunk of chunks.slice(1)) {
-    const nl = chunk.indexOf('\n')
-    const header = (nl === -1 ? chunk : chunk.slice(0, nl)).trim()
-    const rest = nl === -1 ? '' : chunk.slice(nl + 1)
-    const [version, date] = header.split(/\s+—\s+/)
-    const [body, breaking] = rest.split(/\n### Breaking\s*\n/)
-    versions.push({
-      version: (version ?? header).trim(),
-      ...(date !== undefined ? { date: date.trim() } : {}),
-      body: (body ?? '').trim(),
-      ...(breaking !== undefined ? { breaking: breaking.trim() } : {}),
-    })
-  }
-  return { intro, versions }
-}
+import { parseChangelog } from './records.ts'
+export { parseChangelog } from './records.ts'
+export type { ChangelogVersion, ParsedChangelog } from './records.ts'
 
 export function ChangelogView({ source }: { source: string }): React.ReactElement {
   const { intro, versions } = parseChangelog(source)
@@ -56,16 +26,21 @@ export function ChangelogView({ source }: { source: string }): React.ReactElemen
               {v.date !== undefined && <span className="text-sm text-muted-foreground">{v.date}</span>}
               {v.breaking !== undefined && <Badge context="danger" variant="solid">Incompatível</Badge>}
             </div>
-            {v.body.length > 0 && (
+            {(v.beforeBreaking ?? v.body).length > 0 && (
               <div className="mt-3">
-                <DocMarkdown content={v.body} />
+                <DocMarkdown content={v.beforeBreaking ?? v.body} />
               </div>
             )}
             {v.breaking !== undefined && (
-              <div className="mt-4 rounded-md border border-destructive/30 bg-destructive/5 px-4 py-3">
-                <div className="mb-2 text-xs font-medium text-destructive">Breaking — o que fazer</div>
-                <DocMarkdown content={v.breaking} />
-              </div>
+              <Alert context="danger" role="note" className="mt-4">
+                <AlertHeader>
+                  <AlertTitle>Breaking: cuidados ao atualizar</AlertTitle>
+                  <AlertDescription><DocMarkdown content={v.breaking} /></AlertDescription>
+                </AlertHeader>
+              </Alert>
+            )}
+            {v.afterBreaking && (
+              <div className="mt-3"><DocMarkdown content={v.afterBreaking} /></div>
             )}
           </section>
         ))}
@@ -74,7 +49,7 @@ export function ChangelogView({ source }: { source: string }): React.ReactElemen
   )
 }
 
-/** O changelog do Opus pronto pra montar (site: página de topo; Maestro: página da doc). */
+/** O changelog do Opus pronto para montar no portal ou na documentação embutida. */
 export function OpusChangelog(): React.ReactElement {
   return <ChangelogView source={changelogMd} />
 }

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

@@ -222,7 +222,7 @@ receber só `{ id }`: o `id`, do tipo texto, é o único campo obrigatório da e
 se houver, têm valor padrão ou são opcionais. Os caminhos usam ponto para descer em objetos; um
 caminho que passa por uma lista vale para cada item, e um campo intermediário `null` aparece como
 `null`. Declare em `context` só o que orienta a conversa: o exemplo deixa fora contato, documento e
-endereço, e o nome já vai como `title`. Um caminho que termina num objeto ou numa lista leva tudo o
+endereço, e o nome já vai como `title`. Um caminho que termina em um objeto ou em uma lista leva tudo o
 que está abaixo dele, inclusive campos acrescentados depois à saída; para conferir num teste o que
 cada caminho alcança, use `assistantContextLeaves`, de `@softize/opus/assistant-schema`, sobre o
 schema de saída do manifest. Ela devolve, por caminho, as folhas em `leaves` e, em `open`, os pontos
@@ -272,7 +272,7 @@ caracteres. Um caminho que falta na saída em execução é omitido com o motivo
 aviso no log, sem falhar a leitura. Quem recebe a saída por outro canal, como o MCP, aplica a mesma
 projeção com `projectAssistantContext(assistant, output)`.
 
-Entregue o dado ao modelo como bloco delimitado, numa mensagem de dado, nunca no prompt de sistema.
+Entregue o dado ao modelo como bloco delimitado, em uma mensagem de dado, nunca no prompt de sistema.
 `resourceDataBlock`, de `@softize/opus/ai`, monta o bloco com o tipo, o id, o título, os dados e,
 quando houve corte ou ausência, `truncated` e `omitted`, e escapa dentro dos valores o que poderia
 fechar o delimitador. Quando o modelo chama a action dona como ferramenta, recebe a saída completa
@@ -326,7 +326,7 @@ de uma action que não existe, ou dois cenários para a mesma action, impedem o
 subir, e o erro lista os nomes.
 
 O Opus não decide onde os cenários ficam nem se entram no repositório. Eles não fazem parte da
-aplicação: podem ficar numa pasta ignorada pelo git e ser escritos durante a sessão de design,
+aplicação: podem ficar em uma pasta ignorada pelo git e ser escritos durante a sessão de design,
 quando forem necessários.
 
 Dados de design não pertencem ao contrato. Quando uma resposta específica importar para a revisão

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

@@ -168,7 +168,7 @@ componente da feature em vez de copiá-lo.
 
 ## Largura mínima e densidade
 
-O Opus oferece suporte a partir de `64rem` e não muda a composição conforme a largura da viewport.
+A UI das aplicações oferece suporte a partir de `64rem` e não muda a composição conforme a largura da viewport.
 Props de tamanho, como `size="sm"`, escolhem a densidade do componente; não representam
 breakpoints. Overflow e limites contra a janela continuam protegendo o conteúdo.
 
@@ -176,6 +176,10 @@ Não adicione em `className` uma adaptação isolada por viewport ou container.
 futura precisa começar pelo shell e formar um contrato comum para navegação, splits, tabelas e
 componentes.
 
+O [portal de documentação](/docs/documentation-portal) tem uma exceção própria para adaptar
+cabeçalho, leitura editorial e catálogos em telas estreitas. Essa exceção não altera o contrato
+dos componentes demonstrados nos exemplos vivos nem autoriza adaptações isoladas na aplicação.
+
 ## O que fica fora das alavancas
 
 Alguns detalhes fazem parte da identidade visual do Opus e são iguais em todo projeto: a faixa do

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

@@ -0,0 +1,190 @@
+# Publicação de documentação
+
+Quando uma aplicação precisa publicar seus próprios Markdown, use a superfície leve
+`@softize/opus/ui/docs/browser`. Ela oferece cabeçalho, navegação e leitura sem incluir o catálogo
+do Opus nem o compilador de exemplos vivos.
+
+## Componha o portal
+
+O aplicativo escolhe a marca, as seções, as rotas e as ações. `DocHeader` alinha os controles no
+topo; `DocBrowser` pesquisa as páginas e organiza a leitura. O valor da busca é compartilhado,
+mas o campo aparece somente no cabeçalho:
+
+```tsx
+import { useState } from 'react'
+import { DocBrowser, DocHeader, type DocSection } from '@softize/opus/ui/docs/browser'
+import { Input } from '@softize/opus/ui/react'
+
+export function Documentation({ sections }: { sections: DocSection[] }) {
+  const [query, setQuery] = useState('')
+  return (
+    <div className="flex h-dvh flex-col">
+      <DocHeader
+        brand={<a href="/docs">Meu produto</a>}
+        search={<Input type="search" aria-label="Buscar na documentação"
+          value={query} onChange={(event) => setQuery(event.target.value)} />}
+      />
+      <main className="min-h-0 flex-1">
+        <DocBrowser sections={sections} sidebarSize="17rem" editorial sidebarInitiallyCollapsed
+          search={{ placement: 'external', value: query }} />
+      </main>
+    </div>
+  )
+}
+```
+
+Marca, busca e ações usam o mesmo alinhamento vertical. O campo tem até `22rem` e fica centralizado
+no cabeçalho, com colunas de mesma largura nas extremidades. A navegação superior é opcional; quando
+for necessária, ocupa uma linha própria. Em telas menores que `64rem`, a busca ganha sua própria linha. Não é necessário
+copiar esse grid no aplicativo. Links e controles mantêm seu comportamento nativo: o aplicativo
+continua responsável por navegar, trocar tema ou abrir o repositório.
+
+## Declare um percurso de leitura
+
+As `sections` organizam grupos e páginas na ordem declarada. Use essa ordem para aproximar
+conceitos relacionados, não para reproduzir automaticamente a árvore de arquivos. Cada página
+tem `slug`, `title` e `render`; `searchText` acrescenta conteúdo à busca e `navigationTitle` permite
+um rótulo lateral curto sem mudar o título completo.
+
+Com `editorial`, a leitura recebe contexto, sumário dos títulos renderizados e links de página
+anterior e seguinte. `additionalPages` preserva destinos diretos que não entram nessa sequência.
+A busca documental do topo mantém seu rótulo, valor e função ao navegar para catálogos e detalhes;
+continua pesquisando os guias na lateral. Consultas locais ficam no conteúdo da própria página e
+não substituem nem alteram esse campo.
+
+O portal organiza a descoberta; não é uma fronteira de autorização. Só envie ao navegador fontes
+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.
+
+## Consulte decisões e entregas
+
+ADRs e changelog mantêm o mapa dos guias, sem acrescentar uma árvore para cada registro. Use `sidebarLinks` para oferecer entradas
+no mesmo nível dos grupos, após os capítulos, sem incluí-las na sequência anterior/próxima.
+`DocCatalog` recebe registros derivados dos Markdown e uma consulta local independente do cabeçalho.
+Passe o catálogo em `content` para preservar a lateral:
+
+```tsx
+import { useEffect, useState } from 'react'
+import { DocBrowser, DocHeader, DocCatalog, DocRecordDetail, releaseRecords, type DocSection } from '@softize/opus/ui/docs/browser'
+import { Input, Markdown, usePathname } from '@softize/opus/ui/react'
+
+export function DocumentationPortal({ source, sections }: {
+  source: string; sections: DocSection[]
+}) {
+  const path = usePathname()
+  const [documentationQuery, setDocumentationQuery] = useState('')
+  const [catalogQuery, setCatalogQuery] = useState('')
+  const isChangelog = path === '/changelog' || path.startsWith('/changelog/')
+  const records = releaseRecords(source, '/changelog')
+  const record = records.find((entry) => entry.href === path)
+  useEffect(() => {
+    if (!isChangelog) setCatalogQuery('')
+  }, [isChangelog])
+  return <div className="flex h-dvh flex-col">
+    <DocHeader brand={<a href="/docs">Meu produto</a>}
+      search={<Input type="search" aria-label="Buscar na documentação"
+        value={documentationQuery} onChange={(event) => setDocumentationQuery(event.target.value)} />} />
+    <main className="min-h-0 flex-1">
+    <DocBrowser sections={sections} sidebarInitiallyCollapsed
+    search={{ placement: 'external', value: documentationQuery }}
+    sidebarLinks={[{ label: 'Changelog', href: '/changelog', active: isChangelog }]}
+    content={isChangelog ? (
+      record ? <DocRecordDetail catalogLabel="Changelog"><Markdown content={record.body} /></DocRecordDetail>
+      : path === '/changelog' ? <DocCatalog title="Changelog" description="Mudanças por versão."
+          kind="releases" records={records} query={catalogQuery} onQueryChange={setCatalogQuery} />
+      : <DocRecordDetail catalogLabel="Changelog"><Markdown content="# Registro não encontrado" /></DocRecordDetail>
+    ) : undefined} />
+    </main>
+  </div>
+}
+```
+
+O catálogo oferece busca textual sobre o conteúdo completo e apresenta os registros mais recentes
+primeiro, sem tabela, filtros, controles de ordenação ou paginação. Decisões mostram título, data,
+estado declarado e o primeiro parágrafo do contexto. Changelog retoma a leitura das versões com
+texto integral e cuidados de atualização em destaque.
+
+Não faz chamadas de rede: o aplicativo fornece os arquivos descobertos no build. Esse
+índice estático não substitui `ActionList` em coleções de recursos servidas por uma action.
+A consulta local pesquisa somente os registros; a busca do cabeçalho continua alimentando a árvore.
+O host controla os dois valores separadamente. Preserve a consulta local ao abrir um registro e
+voltar, e limpe-a ao trocar de catálogo; não limpe a consulta documental pela navegação.
+
+`decisionRecord(source, href)` extrai número, título, data e status declarados no cabeçalho de uma
+ADR. A lista apresenta o estado declarado; ressalvas e andamento continuam no texto integral.
+Ausência de data ou status aparece como não informada; títulos que não identificam uma ADR
+não geram registros. `releaseRecords(source, basePath)` preserva a convenção `## versão — data` do
+changelog e suas instruções de incompatibilidade. Histórico dentro de uma versão não vira uma
+release inventada.
+
+`content`, `breaking` e `afterBreaking` preservam a sequência da versão no resumo: texto inicial,
+cuidados de atualização e seções seguintes. O detalhe usa `body`, com o Markdown integral.
+
+O aplicativo resolve a URL do registro e passa seu conteúdo para `DocRecordDetail`, também no
+slot `content`. O registro mostra `catalogLabel` antes do título, sem breadcrumb. A navegação fica
+na lateral; `active` identifica o catálogo aberto. Preserve a mesma instância de `DocBrowser`
+entre guias, catálogo e registro para manter os ramos abertos pela pessoa.
+
+Quando recebe `content`, o navegador não escolhe uma página dos guias, não aplica seus redirects
+e não atualiza o título da aba. O aplicativo resolve a rota e o título desse conteúdo. O catálogo
+não define as rotas nem a autorização do aplicativo.
+
+## Propriedades de DocHeader
+
+| Propriedade | Tipo | Padrão | Uso |
+| --- | --- | --- | --- |
+| `brand` | `ReactNode` | Obrigatória | Marca ou link de entrada. |
+| `navigation` | `ReactNode` | — | Navegação opcional; sem ela, não há segunda linha de abas. |
+| `search` | `ReactNode` | — | Campo de busca controlado pelo aplicativo. |
+| `actions` | `ReactNode` | — | Controles como tema e repositório. |
+| `brandWidth` | `string` | `17rem` | Coluna da marca, normalmente igual à lateral. |
+| `className`, `style` e atributos de `header` | Atributos HTML | — | Identificação e ajustes locais sem substituir a composição. |
+
+## Propriedades de DocBrowser
+
+| Propriedade | Tipo | Padrão | Uso |
+| --- | --- | --- | --- |
+| `sections` | `DocSection[]` | Obrigatória na entrada leve | Seções, grupos e páginas na ordem de leitura. |
+| `basePath` | `string` | `/docs` | Prefixo das rotas. |
+| `path` | `string` | Rota compartilhada | Caminho controlado por um host externo. |
+| `redirects` | `Record<string, string>` | `{}` | Slugs anteriores e seus destinos canônicos. |
+| `documentTitle` | `(title: string) => string` | — | Título da aba a partir da página ativa. |
+| `search` | `boolean` ou `DocBrowserSearchOptions` | `false` | Busca lateral ou valor externo; consulta título, rótulo, badge e `searchText`. |
+| `sidebarSize` | `PaneSize` | `14rem` | Largura inicial da navegação. |
+| `sidebar` | `boolean` | `true` | Exibe a árvore; `false` mantém uma leitura simples sem lateral. |
+| `editorial` | `boolean` | `false` | Contexto, sumário e sequência, quando a lateral está presente. |
+| `navigationLabel` | `string` | `Documentação` | Nome da área no contexto editorial; por exemplo, `UI` para o catálogo de componentes. |
+| `additionalPages` | `DocEntry[]` | `[]` | Destinos diretos fora da árvore e da sequência. |
+| `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 }[]` | `[]` | Destinos globais fora dos capítulos; `active` marca o catálogo atual. |
+| `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. |
+
+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.
+
+`DocBrowserSearchOptions` é exportado pelas duas entradas documentais. Com `placement: 'sidebar'`
+(ou sem `placement`), o navegador mantém a consulta local. Com `placement: 'external'`, `value`
+é obrigatório e o host fornece o campo. Nos dois modos, `label`, `placeholder` e `emptyMessage`
+são opcionais; os dois primeiros só afetam o campo lateral.
+
+## Propriedades de DocCatalog
+
+| Propriedade | Tipo | Padrão | Uso |
+| --- | --- | --- | --- |
+| `title` | `string` | Obrigatória | Título do catálogo. |
+| `description` | `string` | Obrigatória | Contexto para a consulta. |
+| `records` | `readonly DocumentationRecord[]` | Obrigatória | Índice estático com identidade, título, URL, corpo e texto pesquisável. Data, status, `summary`, `content`, `breaking` e `afterBreaking` são opcionais: contexto da ADR e partes do resumo da versão. |
+| `query` | `string` | Obrigatória | Valor do campo local, independente da busca documental do topo. |
+| `onQueryChange` | `(query: string) => void` | Obrigatória | Atualiza a consulta controlada pelo host quando a pessoa escreve no campo local. |
+| `kind` | `'decisions' \| 'releases'` | Obrigatória | Lista de decisões com contexto ou leitura contínua das versões. |
+
+## Propriedades de DocRecordDetail
+
+| Propriedade | Tipo | Padrão | Uso |
+| --- | --- | --- | --- |
+| `catalogLabel` | `string` | Obrigatória | Nome do catálogo antes do título, sem breadcrumb. |
+| `children` | `ReactNode` | Obrigatória | Conteúdo completo do registro. |