@softize/opus 25.5.0 → 25.7.0

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

@@ -0,0 +1,58 @@
+---
+title: Visão geral
+---
+
+# Opus
+
+Opus é um SDK para aplicações TypeScript. Você declara as operações do produto em contratos
+compartilhados, liga a implementação no servidor e usa essas mesmas definições no cliente,
+nos testes e nas ferramentas do projeto.
+
+Uma consulta de mensalidade, por exemplo, recebe o tamanho da equipe e devolve o preço. O
+contrato define o formato dessas duas informações e permite o acesso sem login. O handler
+calcula o valor. A interface importa o contrato para chamar a operação com os mesmos tipos
+e validações usados no servidor.
+
+## O que você precisa entender primeiro
+
+Uma **action** é uma operação do sistema: consultar um preço, listar tarefas, salvar um cadastro
+ou ler um registro. Cada action tem um nome, uma entrada e uma saída.
+
+O **contrato** é a parte compartilhada da action. Ele declara o formato dos dados e as informações
+que seus consumidores precisam conhecer. O **binding** acrescenta o handler que executa a regra
+no servidor. Essa divisão permite importar o contrato na interface sem levar banco ou segredo
+para o navegador.
+
+O **domínio** agrupa actions e dados de um assunto do produto. O **runtime** executa o que foi
+registrado e oferece as dependências configuradas pelo aplicativo, como autenticação, banco ou
+auditoria. Essas dependências entram por adapters; você escolhe as peças necessárias ao projeto.
+
+```text
+Contrato compartilhado ──→ Cliente e interface
+         │
+         └── + handler ──→ Action registrada no runtime
+```
+
+Você escreve a regra de negócio e monta o aplicativo. O Opus fornece as declarações, a execução,
+os componentes de interface e as verificações que trabalham sobre essas declarações.
+
+## Faça uma primeira operação
+
+Em [Primeiros passos](/docs/getting-started), você calcula uma mensalidade, valida a entrada e
+testa o resultado. O exemplo usa uma regra pequena e dispensa banco, servidor HTTP e login.
+
+Depois desse percurso, [Actions e contratos](/docs/actions) explica como a mesma estrutura atende
+a formulários, listas, detalhes e operações com autorização.
+
+## Continue o trabalho que trouxe você até aqui
+
+| Você precisa… | Comece por… |
+| --- | --- |
+| Criar uma operação ou mudar uma regra | [Actions e contratos](/docs/actions) |
+| Publicar uma API e conectar dependências | [Runtime e adapters](/docs/runtime) |
+| Modelar dados persistidos | [Camada de dados](/docs/data) |
+| Construir uma tela | [Como consumir](/ui/como-consumir) |
+| Testar uma operação e suas permissões | [Testes de actions](/docs/testing) |
+| Atualizar a versão usada no projeto | [Atualização do Opus](/docs/upgrading) |
+
+O catálogo de [UI](/ui) tem navegação própria pelo volume de componentes e exemplos visuais.

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

@@ -69,6 +69,10 @@ render(
 Use `SidebarNav` quando grupos e itens já puderem ser descritos como dados. Use `SidebarItem`
 diretamente quando a composição precisar de controles, badges ou hierarquia particular.
 
+`SidebarItem` aceita `href` para destinos nativos, mantendo foco e abertura em outra aba.
+Quando o host usa um roteador, forneça também `onClick`: somente o clique simples é interceptado;
+cliques com modificadores preservam o comportamento do link. Sem `href`, o item continua sendo um botão.
+
 ## Colapso
 
 `collapsed` informa o estado compacto aos itens. Forneça labels acessíveis mesmo quando somente os

package/src/ui/docs/folder.tsx

@@ -20,6 +20,7 @@
  * históricas injetam o renderizador de exemplos vivos em `catalog-folder.tsx`.
  */
 import { Markdown } from '../components/primitives/markdown.tsx'
+import { documentationSlugFromSourcePath } from './links.ts'
 import type { DocEntry, DocGroup, DocSection } from './types.ts'
 
 interface FrontMatter {
@@ -123,7 +124,7 @@ export function docSectionsFromFolder(files: Record<string, string>, options: Fo
     const file = splitOrder(segs[segs.length - 1]!)
     const dirs = segs.slice(0, -1).map(splitOrder)
     rows.push({
-      slug: [...dirs.map((d) => d.name), file.name].join('/'),
+      slug: documentationSlugFromSourcePath(sourcePath),
       title: data.title ?? firstH1(body) ?? humanize(file.name),
       body,
       sourcePath,

package/src/ui/docs/index.ts

@@ -7,7 +7,14 @@
  *    `@softize/opus/ui/docs/standalone` — não passa por aqui.
  */
 export { DocBrowser } from './CatalogDocBrowser.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 } from './CatalogDocBrowser.tsx'
+export type { DocBrowserSearchOptions } from './DocBrowser.tsx'
 export { DOC_SECTIONS, PROTOCOL_SECTIONS, UI_SECTIONS } from './registry.tsx'
 export type { DocEntry, DocGroup, DocSection } from './types.ts'
 export { docSectionsFromFolder } from './catalog-folder.tsx'
@@ -17,5 +24,5 @@ export { Example, CodeBlock, DocPage } from './doc.tsx'
 // Renderer de markdown do DocBrowser: prosa + fence ```tsx preview vira componente vivo.
 export { DocMarkdown } from './markdown.tsx'
 export type { DocMarkdownProps } from './markdown.tsx'
-// O changelog do pacote, pronto pra montar (o site o usa como página do menu superior).
+// O changelog do pacote, pronto para montar em um destino global ou no catálogo embutido.
 export { OpusChangelog, ChangelogView } from './changelog.tsx'

package/src/ui/docs/links.ts

@@ -0,0 +1,102 @@
+export interface DocumentationLinkTarget {
+  sourcePath: string
+  anchor?: string
+}
+
+function decodePathSegment(segment: string): string {
+  try {
+    return decodeURIComponent(segment)
+  } catch {
+    return segment
+  }
+}
+
+function normalizeDocumentationPath(path: string): string | null {
+  const segments: string[] = []
+  for (const encodedSegment of path.split('/')) {
+    const segment = decodePathSegment(encodedSegment)
+    if (segment === '' || segment === '.') continue
+    if (segment === '..') {
+      if (segments.length === 0) return null
+      segments.pop()
+      continue
+    }
+    if (segment.includes('/') || segment.includes('\\')) return null
+    segments.push(segment)
+  }
+  return segments.join('/')
+}
+
+function normalizeDocumentationAnchor(value: string, decodeUri: boolean): string {
+  let decoded = value
+  if (decodeUri) {
+    try {
+      decoded = decodeURIComponent(value)
+    } catch {
+      // Fragmentos malformados continuam navegáveis pela normalização conservadora.
+    }
+  }
+  return decoded
+    .normalize('NFD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .toLocaleLowerCase('pt-BR')
+    .replace(/[^a-z0-9\s-]/g, '')
+    .trim()
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+}
+
+/** Normaliza um fragmento URI para a âncora usada pela documentação. */
+export function documentationAnchor(value: string): string {
+  return normalizeDocumentationAnchor(value, true)
+}
+
+/** Normaliza o texto visível de um título sem interpretar sequências percentuais como URI. */
+export function documentationHeadingAnchor(value: string): string {
+  return normalizeDocumentationAnchor(value, false)
+}
+
+/** Deriva o slug de um caminho já relativo à raiz documental do consumidor. */
+export function documentationSlugFromSourcePath(sourcePath: string): string {
+  return sourcePath
+    .replace(/^\/+/, '')
+    .replace(/\.mdx?$/i, '')
+    .split('/')
+    .filter(Boolean)
+    .map((segment) => segment.replace(/^\d+[-_](.+)$/, '$1'))
+    .join('/')
+}
+
+/**
+ * Resolve links Markdown internos. `currentSourcePath` deve ser relativo à raiz documental.
+ * `/docs/` indica essa raiz em um link absoluto; `docs/` sem a barra inicial é uma pasta normal.
+ * Retorna `null` para protocolos, arquivos que não são Markdown e caminhos fora da raiz.
+ */
+export function resolveDocumentationLinkTarget(
+  currentSourcePath: string,
+  href: string,
+): DocumentationLinkTarget | null {
+  if (/^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(href)) return null
+
+  const current = normalizeDocumentationPath(currentSourcePath.replace(/^\/+/, ''))
+  if (current === null) return null
+  if (href.startsWith('#')) {
+    return { sourcePath: current, anchor: documentationAnchor(href.slice(1)) }
+  }
+
+  const fragmentIndex = href.indexOf('#')
+  const target = fragmentIndex < 0 ? href : href.slice(0, fragmentIndex)
+  const fragment = fragmentIndex < 0 ? undefined : href.slice(fragmentIndex + 1)
+  if (target.startsWith('/') && !target.startsWith('/docs/')) return null
+  const currentDirectory = current.slice(0, current.lastIndexOf('/') + 1)
+  const candidate = normalizeDocumentationPath(
+    target.startsWith('/docs/')
+      ? target.slice('/docs/'.length)
+      : `${currentDirectory}${target}`,
+  )
+  if (candidate === null || !/\.mdx?$/i.test(candidate)) return null
+  return {
+    sourcePath: candidate,
+    ...(fragment === undefined ? {} : { anchor: documentationAnchor(fragment) }),
+  }
+}

package/src/ui/docs/markdown.tsx

@@ -88,9 +88,11 @@ export interface DocMarkdownProps {
   /** Reescreve links do Markdown antes da renderização. Útil para resolver caminhos relativos
    *  quando o documento é publicado sob uma rota do aplicativo. */
   resolveHref?: (href: string) => string
+  /** Mantém código didático aberto quando false; exemplos vivos preservam sua composição. */
+  codeCollapsible?: boolean
 }
 
-export function DocMarkdown({ content, scope, resolveHref }: DocMarkdownProps): React.ReactElement {
+export function DocMarkdown({ content, scope, resolveHref, codeCollapsible = true }: DocMarkdownProps): React.ReactElement {
   // O `scope` ESTENDE o default (não substitui): o pattern injeta o palco doc-client
   // (DocBrowserActionProvider + contratos) sem perder o opus/ui + lucide + hooks. Memoiza pra
   // não re-avaliar os LiveBlocks a cada render (o scope injetado é estável no chamador).
@@ -135,7 +137,7 @@ export function DocMarkdown({ content, scope, resolveHref }: DocMarkdownProps):
           {/\b(preview|live)\b/.test(info) ? (
             <LiveBlock code={t.content} scope={liveScope} previewClassName={previewClassName} />
           ) : (
-            <CodeBlock code={t.content.replace(/\n$/, '')} lang={lang} />
+            <CodeBlock code={t.content.replace(/\n$/, '')} lang={lang} collapsible={codeCollapsible} />
           )}
         </div>,
       )
@@ -144,5 +146,5 @@ export function DocMarkdown({ content, scope, resolveHref }: DocMarkdownProps):
     }
   }
   flush()
-  return <div className="prose prose-sm max-w-none space-y-4">{parts}</div>
+  return <div data-slot="markdown" className="prose prose-sm max-w-none space-y-4">{parts}</div>
 }

package/src/ui/docs/records.ts

@@ -0,0 +1,144 @@
+export interface DocumentationRecord {
+  id: string;
+  title: string;
+  href: string;
+  date?: string;
+  status?: string;
+  searchText: string;
+  body: string;
+  summary?: string;
+  content?: string;
+  breaking?: string;
+  afterBreaking?: string;
+}
+
+export interface ChangelogVersion {
+  version: string;
+  date?: string;
+  body: string;
+  breaking?: string;
+  beforeBreaking?: string;
+  afterBreaking?: string;
+  /** Corpo original, com a ordem das seções preservada para a leitura integral. */
+  sourceBody?: string;
+}
+
+export interface ParsedChangelog {
+  intro: string;
+  versions: ChangelogVersion[];
+}
+
+/** Preserva a convenção publicada: `## versão — data` e seção `### Breaking`. */
+export function parseChangelog(source: string): ParsedChangelog {
+  const chunks = `\n${source.trim()}`.split(/\n## /);
+  const versions = chunks.slice(1).map((chunk) => {
+    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 sourceBody = rest.trim();
+    const breakingSection =
+      /^### Breaking[\t ]*\r?\n([\s\S]*?)(?=^###[\t ]|(?![\s\S]))/m.exec(sourceBody);
+    const body = breakingSection
+      ? sourceBody.slice(0, breakingSection.index) +
+        sourceBody.slice(breakingSection.index + breakingSection[0].length)
+      : sourceBody;
+    return {
+      version: (version ?? header).trim(),
+      ...(date !== undefined ? { date: date.trim() } : {}),
+      body: (body ?? "").trim(),
+      sourceBody,
+      ...(breakingSection
+        ? {
+            breaking: breakingSection[1]!.trim(),
+            beforeBreaking: sourceBody.slice(0, breakingSection.index).trim(),
+            afterBreaking: sourceBody
+              .slice(breakingSection.index + breakingSection[0].length)
+              .trim(),
+          }
+        : {}),
+    };
+  });
+  return { intro: chunks[0]?.trim() ?? "", versions };
+}
+
+/** Extrai só os campos declarados; a ausência de metadata não vira uma decisão presumida. */
+export function decisionRecord(
+  source: string,
+  href: string,
+): DocumentationRecord | undefined {
+  const heading = source.match(/^#\s+ADR\s+(\d+)\s*[—–:-]\s*(.+)$/m);
+  if (!heading) return undefined;
+  const header = source.split(/^##\s/m)[0] ?? "";
+  const metadata = (name: string): string | undefined => {
+    const value = header.match(
+      new RegExp(`^[\\t ]*-?[\\t ]*\\*\\*${name}:?\\*\\*:?[\\t ]*(.+)$`, "mi"),
+    )?.[1];
+    return value?.trim().replace(/\.$/, "");
+  };
+  const declaredStatus = metadata("Status");
+  // O estado resume a metadata; ressalvas e andamento permanecem no texto integral da decisão.
+  const status =
+    declaredStatus?.match(
+      /^(parcialmente (?:substituída|supersedida)|substituída|supersedida|aceita(?: para (?:protótipo|implementação(?: local)?|candidato local)| como primeiro corte)?|proposta|implementada|rejeitada)\b/i,
+    )?.[1] ?? declaredStatus;
+  const context = source
+    .match(/^##[\t ]+Contexto\b[^\n]*\n([\s\S]*)/im)?.[1]
+    ?.split(/^##[\t ]/m)[0];
+  return {
+    id: heading[1]!,
+    title: heading[2]!.trim(),
+    href,
+    date: metadata("Data"),
+    status,
+    summary:
+      context
+        ?.replace(/^#{1,6}[\t ].*(?:\r?\n|$)/gm, "")
+        .trim()
+        .split(/\n\s*\n/)[0]
+        ?.trim() || undefined,
+    searchText: source,
+    body: source,
+  };
+}
+
+export function releaseRecords(
+  source: string,
+  basePath: string,
+): DocumentationRecord[] {
+  return parseChangelog(source).versions.map((release) => {
+    return {
+      id: release.version,
+      title: release.version,
+      href: `${basePath}/${encodeURIComponent(release.version)}`,
+      date: release.date,
+      content: release.beforeBreaking ?? release.body,
+      breaking: release.breaking,
+      afterBreaking: release.afterBreaking,
+      body: `# ${release.version}\n\n${release.date ?? ""}\n\n${release.sourceBody}`,
+      searchText: `${release.version} ${release.date ?? ""} ${release.sourceBody}`,
+    };
+  });
+}
+
+function searchable(value: string): string {
+  return value
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLocaleLowerCase("pt-BR");
+}
+
+export function filterDocumentationRecords(
+  records: readonly DocumentationRecord[],
+  query: string,
+): DocumentationRecord[] {
+  const terms = searchable(query).trim().split(/\s+/).filter(Boolean);
+  return records.filter(
+    (record) =>
+      terms.every((term) =>
+        searchable(
+          `${record.id} ${record.title} ${record.status ?? ""} ${record.searchText}`,
+        ).includes(term),
+      ),
+  );
+}