@softize/opus 25.5.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,9 +3,25 @@
  * 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 {
+  documentationAnchor,
+  documentationHeadingAnchor,
+  documentationSlugFromSourcePath,
+  resolveDocumentationLinkTarget,
+} from './links.ts'
+export type { DocumentationLinkTarget } from './links.ts'
 export type { DocEntry, DocGroup, DocSection } from './types.ts'
 export { Markdown } from '../components/primitives/markdown.tsx'
 export type { MarkdownProps } from '../components/primitives/markdown.tsx'

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