@softize/opus 25.6.0 → 25.7.0

package/src/ui/docs/DocBrowser.tsx

@@ -12,11 +12,19 @@
  * Nos dois, navegar emite `popstate`: host que guarda o path por conta própria acompanha.
  * `basePath` adapta o prefixo das URLs (`/docs` no Maestro, `/__docs` nos apps).
  */
-import { useEffect, useMemo, useState } from "react";
-import { Search } from "lucide-react";
-import type { DocEntry, DocSection } from "./types.ts";
-import { Pane, Split } from "../components/patterns/split.tsx";
+import { useEffect, useMemo, useRef, useState, type ReactNode } from "react";
+import { ArrowLeft, ArrowRight, Search } from "lucide-react";
+import type { DocEntry, DocGroup, DocSection } from "./types.ts";
+import { Pane, Split, type PaneSize } from "../components/patterns/split.tsx";
 import { Input } from "../components/primitives/input.tsx";
+import {
+  Breadcrumb,
+  BreadcrumbList,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbSeparator,
+  BreadcrumbPage,
+} from "../components/primitives/breadcrumb.tsx";
 import {
   Sidebar,
   SidebarGroupLabel,
@@ -35,6 +43,16 @@ function findPage(sections: DocSection[], slug: string): DocEntry | undefined {
   return undefined;
 }
 
+interface DocBrowserSearchCopy {
+  label?: string;
+  placeholder?: string;
+  emptyMessage?: string;
+}
+
+export type DocBrowserSearchOptions =
+  | (DocBrowserSearchCopy & { placement?: "sidebar" })
+  | (DocBrowserSearchCopy & { placement: "external"; value: string });
+
 export interface DocBrowserProps {
   /** Prefixo das rotas da doc. Default `/docs` (Maestro); `/__docs` na rota dev dos apps. */
   basePath?: string;
@@ -48,7 +66,202 @@ export interface DocBrowserProps {
    *  Ausente = não mexe no title. */
   documentTitle?: (pageTitle: string) => string;
   /** Busca local por título, badge e `searchText` das páginas. Omitida = sem campo de busca. */
-  search?: boolean | { label?: string; placeholder?: string; emptyMessage?: string };
+  search?: boolean | DocBrowserSearchOptions;
+  /** Largura inicial da navegação. Preserva `14rem` quando omitida. */
+  sidebarSize?: PaneSize;
+  /** Exibe a navegação lateral. Default `true`; destinos globais de uma página podem omiti-la. */
+  sidebar?: boolean;
+  /** Compõe leitura com contexto, sumário das seções e continuidade entre páginas. */
+  editorial?: boolean;
+  /** Nome da área no contexto da leitura editorial. */
+  navigationLabel?: string;
+  /** Páginas acessíveis por URL direta, mas fora da árvore e da sequência de leitura. */
+  additionalPages?: DocEntry[];
+  /** Substitui a leitura, mantendo a árvore; o host resolve conteúdo, título e rota. */
+  content?: ReactNode;
+  /** Destinos fora dos capítulos; não participam da sequência de leitura. */
+  sidebarLinks?: Array<{ label: string; href: string; active?: boolean }>;
+  /** Seções e grupos começam recolhidos; a busca revela resultados sem mudar a escolha manual. */
+  sidebarInitiallyCollapsed?: boolean;
+}
+
+function documentNavigation(
+  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 EditorialDocument({
+  page,
+  sections,
+  basePath,
+  navigationLabel,
+}: {
+  page: DocEntry;
+  sections: DocSection[];
+  basePath: string;
+  navigationLabel: string;
+}): React.ReactElement {
+  const articleRef = useRef<HTMLElement>(null);
+  const [headings, setHeadings] = useState<
+    Array<{ id: string; title: string }>
+  >([]);
+  const entries = sections.flatMap((section) =>
+    section.groups.flatMap((group) =>
+      group.pages.map((entry) => ({
+        entry,
+        context: group.label || section.label,
+      })),
+    ),
+  );
+  const index = entries.findIndex(({ entry }) => entry.slug === page.slug);
+  const previous = index > 0 ? entries[index - 1]?.entry : undefined;
+  const next = index >= 0 ? entries[index + 1]?.entry : undefined;
+  const context = entries[index]?.context;
+
+  useEffect(() => {
+    const article = articleRef.current;
+    if (!article) return;
+    const collect = (): void => {
+      const nextHeadings = Array.from(
+        article.querySelectorAll<HTMLHeadingElement>("h2[id]"),
+      ).map((heading) => ({
+        id: heading.id,
+        title: heading.textContent ?? "",
+      }));
+      // Blocos renderizados podem renovar o DOM sem mudar o sumário. Não realimentar esse ciclo.
+      setHeadings((current) =>
+        current.length === nextHeadings.length &&
+        current.every(
+          (heading, index) =>
+            heading.id === nextHeadings[index]?.id &&
+            heading.title === nextHeadings[index]?.title,
+        )
+          ? current
+          : nextHeadings,
+      );
+    };
+    collect();
+    const observer = new MutationObserver(collect);
+    observer.observe(article, { childList: true, subtree: true });
+    if (window.location.hash) {
+      const heading = Array.from(
+        article.querySelectorAll<HTMLElement>("[id]"),
+      ).find(
+        (element) =>
+          `#${encodeURIComponent(element.id)}` === window.location.hash ||
+          `#${element.id}` === window.location.hash,
+      );
+      heading?.scrollIntoView?.();
+    }
+    return () => observer.disconnect();
+  }, [page.slug]);
+
+  const chapterLink = (
+    entry: DocEntry,
+    direction: "previous" | "next",
+  ): React.ReactElement => {
+    const href = `${basePath}/${entry.slug}`;
+    return (
+      <a
+        href={href}
+        onClick={(event) => documentNavigation(event, href)}
+        className={`group flex flex-col gap-2 rounded-lg border border-border p-5 text-sm transition-colors hover:border-primary/40 hover:bg-muted/30 ${direction === "next" ? "text-right" : ""}`}
+      >
+        <span className="text-xs text-muted-foreground">
+          {direction === "previous" ? "Leitura anterior" : "Próxima leitura"}
+        </span>
+        <span
+          className={`flex items-center gap-2 font-medium ${direction === "next" ? "justify-end" : ""}`}
+        >
+          {direction === "previous" && (
+            <ArrowLeft aria-hidden="true" className="size-4" />
+          )}
+          {entry.title}
+          {direction === "next" && (
+            <ArrowRight aria-hidden="true" className="size-4" />
+          )}
+        </span>
+      </a>
+    );
+  };
+
+  return (
+    <div
+      data-slot="doc-editorial"
+      className="mx-auto grid max-w-[78rem] grid-cols-1 gap-12 px-8 py-10 xl:grid-cols-[minmax(0,1fr)_12rem] xl:px-12"
+    >
+      <div className="min-w-0">
+        <Breadcrumb className="mb-8">
+          <BreadcrumbList>
+            <BreadcrumbItem>
+              <BreadcrumbLink
+                href={basePath}
+                onClick={(event) => documentNavigation(event, basePath)}
+              >
+                {navigationLabel}
+              </BreadcrumbLink>
+            </BreadcrumbItem>
+            {context && (
+              <>
+                <BreadcrumbSeparator />
+                <BreadcrumbItem>
+                  <BreadcrumbPage>{context}</BreadcrumbPage>
+                </BreadcrumbItem>
+              </>
+            )}
+          </BreadcrumbList>
+        </Breadcrumb>
+        <article
+          ref={articleRef}
+          aria-label={page.title}
+          className="min-w-0 [&_h1]:text-[2.25rem] [&_h1]:leading-tight [&_h1]:tracking-tight [&_h2]:mt-12 [&_h2]:scroll-mt-8 [&_h2]:text-xl [&_h3]:scroll-mt-8 [&_[data-slot=markdown]]:text-base [&_[data-slot=markdown]]:leading-[1.8] [&_pre]:text-sm [&_table]:text-sm"
+        >
+          {page.render()}
+        </article>
+        {(previous || next) && (
+          <nav
+            aria-label="Sequência de leitura"
+            className="mt-14 grid grid-cols-2 gap-4 border-t border-border pt-8"
+          >
+            {previous ? chapterLink(previous, "previous") : <span />}
+            {next && chapterLink(next, "next")}
+          </nav>
+        )}
+      </div>
+      {headings.length > 0 && (
+        <aside className="hidden xl:block">
+          <nav
+            aria-label="Nesta página"
+            className="sticky top-8 border-l border-border pl-5"
+          >
+            <p className="mb-4 text-xs font-semibold text-foreground">
+              Nesta página
+            </p>
+            <ul className="space-y-3 text-xs leading-relaxed text-muted-foreground">
+              {headings.map((heading) => (
+                <li key={heading.id}>
+                  <a href={`#${heading.id}`} className="hover:text-foreground">
+                    {heading.title}
+                  </a>
+                </li>
+              ))}
+            </ul>
+          </nav>
+        </aside>
+      )}
+    </div>
+  );
 }
 
 function searchable(value: string): string {
@@ -58,14 +271,31 @@ function searchable(value: string): string {
     .toLocaleLowerCase("pt-BR");
 }
 
-function filterSections(sections: DocSection[], query: string): DocSection[] {
+type SidebarSection = Omit<DocSection, "groups"> & {
+  navigationKey: string;
+  groups: Array<DocGroup & { navigationKey: string }>;
+};
+
+function filterSections(
+  sections: DocSection[],
+  query: string,
+): SidebarSection[] {
   const terms = searchable(query).split(/\s+/).filter(Boolean);
-  if (terms.length === 0) return sections;
-  return sections.flatMap((section) => {
+  // Identidade vem do manifesto completo, antes de remover ramos pela busca.
+  const indexedSections = sections.map((section, sectionIndex) => ({
+    ...section,
+    navigationKey: `section:${sectionIndex}`,
+    groups: section.groups.map((group, groupIndex) => ({
+      ...group,
+      navigationKey: `group:${sectionIndex}:${groupIndex}`,
+    })),
+  }));
+  if (terms.length === 0) return indexedSections;
+  return indexedSections.flatMap((section) => {
     const groups = section.groups.flatMap((group) => {
       const pages = group.pages.filter((page) => {
         const text = searchable(
-          `${page.title}\n${page.badge ?? ""}\n${page.searchText ?? ""}`,
+          `${page.title}\n${page.navigationTitle ?? ""}\n${page.badge ?? ""}\n${page.searchText ?? ""}`,
         );
         return terms.every((term) => text.includes(term));
       });
@@ -80,22 +310,27 @@ function DocSidebarTree({
   activeSlug,
   onSelect,
   forceExpanded = false,
+  initiallyCollapsed = false,
+  links = [],
 }: {
-  sections: DocSection[];
+  sections: SidebarSection[];
   activeSlug?: string;
   onSelect: (slug: string) => void;
   forceExpanded?: boolean;
+  initiallyCollapsed?: boolean;
+  links?: DocBrowserProps["sidebarLinks"];
 }): React.ReactElement {
-  const [closedGroups, setClosedGroups] = useState<Set<string>>(
+  // O conjunto guarda os ramos alterados pela pessoa em relação ao estado inicial.
+  const [toggledBranches, setToggledBranches] = useState<Set<string>>(
     () => new Set(),
   );
 
   useEffect(() => {
-    if (forceExpanded) return;
+    if (forceExpanded || initiallyCollapsed) return;
     const activeGroup = sections
-      .flatMap((section, sectionIndex) =>
-        section.groups.map((group, groupIndex) => ({
-          key: `${sectionIndex}:${groupIndex}`,
+      .flatMap((section) =>
+        section.groups.map((group) => ({
+          key: group.navigationKey,
           group,
         })),
       )
@@ -104,16 +339,16 @@ function DocSidebarTree({
       );
 
     if (activeGroup === undefined) return;
-    setClosedGroups((current) => {
+    setToggledBranches((current) => {
       if (!current.has(activeGroup.key)) return current;
       const next = new Set(current);
       next.delete(activeGroup.key);
       return next;
     });
-  }, [activeSlug, forceExpanded, sections]);
+  }, [activeSlug, forceExpanded, sections, initiallyCollapsed]);
 
   const toggleGroup = (key: string): void => {
-    setClosedGroups((current) => {
+    setToggledBranches((current) => {
       const next = new Set(current);
       if (next.has(key)) next.delete(key);
       else next.add(key);
@@ -124,7 +359,7 @@ function DocSidebarTree({
   const renderPage = (page: DocEntry): React.ReactElement => (
     <SidebarItem
       key={page.slug}
-      label={page.title}
+      label={page.navigationTitle ?? page.title}
       badge={
         page.badge === undefined ? undefined : (
           <span className="rounded border border-border/60 px-1 font-mono text-[0.625rem] leading-tight text-muted-foreground/60">
@@ -138,42 +373,92 @@ function DocSidebarTree({
   );
 
   return (
-    <nav aria-label="Navegação da documentação" className="space-y-4 p-2">
-      {sections.map((section, sectionIndex) => (
-        <div key={`${section.label}:${sectionIndex}`} className="space-y-0.5">
-          {section.label.trim() !== "" && (
-            <SidebarGroupLabel>{section.label}</SidebarGroupLabel>
-          )}
-          {section.groups.map((group, groupIndex) => {
-            const key = `${sectionIndex}:${groupIndex}`;
-            if (group.pages.length === 0) return null;
-            if ((group.label ?? "").trim() === "") {
-              return group.pages.map((page) => renderPage(page));
-            }
+    <nav
+      aria-label="Navegação da documentação"
+      hidden={sections.length === 0 && links.length === 0}
+      className={initiallyCollapsed ? "space-y-0.5 p-2" : "space-y-4 p-2"}
+    >
+      {sections.map((section) => {
+        const sectionBranch = section.navigationKey;
+        const collapsibleSection =
+          initiallyCollapsed && section.label.trim() !== "";
+        const sectionExpanded =
+          forceExpanded || toggledBranches.has(sectionBranch);
+        const groups = section.groups.map((group) => {
+          const key = group.navigationKey;
+          if (group.pages.length === 0) return null;
+          if ((group.label ?? "").trim() === "") {
+            return group.pages.map((page) => renderPage(page));
+          }
 
-            const expanded = forceExpanded || !closedGroups.has(key);
-            return (
-              <div key={key} className="space-y-0.5">
+          const expanded =
+            forceExpanded ||
+            (initiallyCollapsed
+              ? toggledBranches.has(key)
+              : !toggledBranches.has(key));
+          return (
+            <div key={key} className="space-y-0.5">
+              <SidebarItem
+                label={group.label!}
+                icon={group.icon}
+                expanded={expanded}
+                onToggle={forceExpanded ? undefined : () => toggleGroup(key)}
+                // Durante a busca, o grupo é contexto dos resultados e permanece aberto.
+                onClick={() => {
+                  if (!forceExpanded) toggleGroup(key);
+                }}
+              />
+              {expanded && (
+                <SidebarTreeGroup>
+                  {group.pages.map((page) => renderPage(page))}
+                </SidebarTreeGroup>
+              )}
+            </div>
+          );
+        });
+        return (
+          <div key={sectionBranch} className="space-y-0.5">
+            {collapsibleSection ? (
+              <>
                 <SidebarItem
-                  label={group.label!}
-                  icon={group.icon}
-                  expanded={expanded}
-                  onToggle={forceExpanded ? undefined : () => toggleGroup(key)}
-                  // Durante a busca, o grupo é contexto dos resultados e permanece aberto.
+                  label={section.label}
+                  expanded={sectionExpanded}
+                  onToggle={
+                    forceExpanded ? undefined : () => toggleGroup(sectionBranch)
+                  }
                   onClick={() => {
-                    if (!forceExpanded) toggleGroup(key);
+                    if (!forceExpanded) toggleGroup(sectionBranch);
                   }}
                 />
-                {expanded && (
-                  <SidebarTreeGroup>
-                    {group.pages.map((page) => renderPage(page))}
-                  </SidebarTreeGroup>
+                {sectionExpanded && (
+                  <SidebarTreeGroup>{groups}</SidebarTreeGroup>
                 )}
-              </div>
-            );
-          })}
+              </>
+            ) : (
+              <>
+                {section.label.trim() !== "" && (
+                  <SidebarGroupLabel>{section.label}</SidebarGroupLabel>
+                )}
+                {groups}
+              </>
+            )}
+          </div>
+        );
+      })}
+      {links.length > 0 && (
+        <div className="space-y-0.5">
+          {links.map((link) => (
+            <SidebarItem
+              key={link.href}
+              href={link.href}
+              active={link.active}
+              onClick={() => navigate(link.href)}
+              label={link.label}
+              icon={initiallyCollapsed ? <span aria-hidden="true" /> : undefined}
+            />
+          ))}
         </div>
-      ))}
+      )}
     </nav>
   );
 }
@@ -185,8 +470,16 @@ export function DocBrowser({
   redirects = {},
   documentTitle,
   search = false,
+  sidebarSize = "14rem",
+  sidebar = true,
+  editorial = false,
+  navigationLabel = "Documentação",
+  additionalPages = [],
+  content,
+  sidebarLinks = [],
+  sidebarInitiallyCollapsed = false,
 }: DocBrowserProps): React.ReactElement {
-  const [query, setQuery] = useState("");
+  const [sidebarQuery, setSidebarQuery] = useState("");
   // Standalone: o path vem do router da casa (`usePathname` — pathname É o estado).
   // Controlado: o host manda, e este valor é ignorado. O hook roda sempre (regra dos
   // hooks); o que muda é quem vence no `??`.
@@ -199,30 +492,65 @@ export function DocBrowser({
   const rel = path.startsWith(basePath) ? path.slice(basePath.length) : "";
   const requestedSlug = rel.split("/").filter(Boolean).join("/") || defaultSlug;
   const slug = redirects[requestedSlug] ?? requestedSlug;
-  const page = findPage(sections, slug) ?? findPage(sections, defaultSlug);
-  const visibleSections = useMemo(() => filterSections(sections, query), [query, sections]);
   const searchOptions = typeof search === "object" ? search : {};
+  const query =
+    searchOptions.placement === "external" ? searchOptions.value : sidebarQuery;
+  const visibleSections = useMemo(
+    () => filterSections(sections, query),
+    [query, sections],
+  );
+  const hasCustomContent = content !== undefined;
+  const page = hasCustomContent
+    ? undefined
+    : (findPage(sections, slug) ??
+      additionalPages.find((entry) => entry.slug === slug) ??
+      findPage(sections, defaultSlug));
 
   // `navigate` emite `popstate`, então o host é notificado nos dois modos — inclusive o
   // que ainda escuta o evento na unha, que era como este componente avisava antes.
   const go = (to: string): void => navigate(to);
 
   useEffect(() => {
-    if (requestedSlug !== slug)
+    if (!hasCustomContent && requestedSlug !== slug)
       navigate(`${basePath}/${slug}`, { replace: true });
-  }, [basePath, requestedSlug, slug]);
+  }, [basePath, requestedSlug, slug, hasCustomContent]);
 
   // O title da aba acompanha a página atual (quando o host fornece o formato).
   useEffect(() => {
     if (page && documentTitle) document.title = documentTitle(page.title);
   }, [page, documentTitle]);
 
+  if (!sidebar) {
+    return (
+      <div className="h-full overflow-y-auto">
+        {hasCustomContent ? (
+          content
+        ) : (
+          <div className="mx-auto max-w-3xl px-8 py-8">{page?.render()}</div>
+        )}
+      </div>
+    );
+  }
+
+  const readingContent = hasCustomContent ? (
+    content
+  ) : editorial && page ? (
+    <EditorialDocument
+      page={page}
+      sections={sections}
+      basePath={basePath}
+      navigationLabel={navigationLabel}
+    />
+  ) : (
+    <div className="mx-auto max-w-3xl px-8 py-8">{page?.render()}</div>
+  );
+
   return (
     <Split className="h-full">
-      <Pane initialSize="14rem">
+      <Pane initialSize={sidebarSize}>
         <Sidebar className="w-full">
           <div className="flex min-h-0 flex-1 flex-col">
-            {search !== false && (
+            {search !== false && searchOptions.placement !== "external" && (
               <div className="shrink-0 border-b border-border p-3">
                 <Input
                   type="search"
@@ -231,37 +559,44 @@ export function DocBrowser({
                   placeholder={
                     searchOptions.placeholder ?? "Buscar na documentação…"
                   }
-                  value={query}
-                  onChange={(event) => setQuery(event.target.value)}
+                  value={sidebarQuery}
+                  onChange={(event) => setSidebarQuery(event.target.value)}
                 />
               </div>
             )}
             <div className="min-h-0 flex-1 overflow-y-auto px-3 py-6">
               <p
                 className={
-                  visibleSections.length === 0 ? "px-2 text-sm text-muted-foreground" : "sr-only"
+                  visibleSections.length === 0
+                    ? "px-2 text-sm text-muted-foreground"
+                    : "sr-only"
                 }
                 role={search === false ? undefined : "status"}
                 aria-atomic={search === false ? undefined : "true"}
               >
                 {visibleSections.length === 0
-                  ? searchOptions.emptyMessage ?? "Nenhum documento encontrado. Tente outro termo."
+                  ? (searchOptions.emptyMessage ??
+                    "Nenhum documento encontrado. Tente outro termo.")
                   : ""}
               </p>
-              {visibleSections.length > 0 && (
-                <DocSidebarTree
-                  sections={visibleSections}
-                  activeSlug={page?.slug}
-                  forceExpanded={query.trim() !== ""}
-                  onSelect={(nextSlug) => go(`${basePath}/${nextSlug}`)}
-                />
-              )}
+              <DocSidebarTree
+                sections={visibleSections}
+                activeSlug={page?.slug}
+                forceExpanded={query.trim() !== ""}
+                initiallyCollapsed={sidebarInitiallyCollapsed}
+                links={sidebarLinks}
+                onSelect={(nextSlug) => go(`${basePath}/${nextSlug}`)}
+              />
             </div>
           </div>
         </Sidebar>
       </Pane>
-      <Pane key={page?.slug} grow className="overflow-y-auto">
-        <div className="mx-auto max-w-3xl px-8 py-8">{page?.render()}</div>
+      <Pane
+        key={hasCustomContent ? path : page?.slug}
+        grow
+        className="overflow-y-auto"
+      >
+        {readingContent}
       </Pane>
     </Split>
   );