@softize/opus 26.1.0 → 26.2.0

package/CHANGELOG.md

@@ -7,6 +7,24 @@ 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.
 
+## 26.2.0 — 2026-10-09
+
+Portais podem organizar capítulos em subgrupos e abrir ferramentas relacionadas sem substituir
+a página em leitura.
+
+- `DocGroup.groups` declara subgrupos opcionais. Navegação, busca, URLs diretas e sequência
+  editorial percorrem todos os níveis, com as páginas próprias antes dos subgrupos. A busca
+  preserva os ancestrais dos resultados; no modo inicialmente recolhido, restaura o estado
+  manual ao limpar. No modo expandido, os ancestrais da página ativa são reabertos. Ramos
+  vazios não aparecem, sem sugerir outro termo quando não há consulta.
+- `DocBrowser.sidebarLinks` preserva a navegação nativa para URLs HTTP(S) absolutas.
+- `SidebarItem` e `DocBrowser.sidebarLinks` aceitam `newTab`: o link abre em outra aba com
+  `noopener noreferrer` e informa a abertura no nome acessível. No portal, também exibe
+  um ícone de nova aba. A opção não intercepta a navegação nem chama `onClick`.
+
+As novas propriedades são opcionais. Consumidores sem subgrupos ou `newTab` mantêm seus
+contratos; não há migração obrigatória nesta versão.
+
 ## 26.1.0 — 2026-10-09
 
 Subheadings descrevem a finalidade da superfície; orientações necessárias ficam visíveis no corpo

package/docs/adr/0057-doc-browser-permite-busca-no-chrome-do-consumidor.md

@@ -39,6 +39,19 @@ de ADRs ou versões.
 
 ### Hierarquia e leitura
 
+> **Emenda — 2026-10-08, protótipo local:** `DocGroup.groups` permite subgrupos
+> opcionais. Um assunto como Integrações pode pertencer a Domínios e ainda reunir
+> páginas por sistema. A navegação, a busca, a seleção direta e a sequência de
+> leitura percorrem os mesmos grupos aninhados. Páginas próprias aparecem antes
+> dos subgrupos; ramos sem resultados somem da busca, sem perder a abertura manual.
+> O contrato anterior continua válido quando `groups` é omitido. Uma árvore paralela
+> no host e rótulos artificiais para simular profundidade foram descartados por
+> duplicar comportamento ou perder a hierarquia. Testes de links diretos, busca,
+> grupos vazios, rótulos repetidos e continuidade verificam a extensão.
+
+> **Consolidação — 2026-10-09:** a extensão de subgrupos compõe o candidato da versão
+> 26.2.0, sobre a base 26.1.0. Publicação e adoção permanecem etapas separadas.
+
 `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
@@ -52,6 +65,16 @@ Esses destinos usam `SidebarItem.href`, não uma cópia do estilo da linha. A ex
 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.
 
+> **Emenda — 2026-10-09:** destinos HTTP(S) absolutos em `sidebarLinks` usam a navegação
+> nativa, pois podem apontar para outra aplicação. `newTab` é opcional em `SidebarItem`
+> e `sidebarLinks`: com `href`, declara `target="_blank"`, `rel="noopener noreferrer"`
+> e a abertura no nome acessível, sem chamar `onClick`. Sem `href`, não muda o botão.
+> O portal acrescenta o ícone pelo slot `badge` do item canônico. Interceptar esses
+> destinos no roteador ou copiar a linha no host foi descartado: o primeiro impede
+> a navegação entre aplicações e o segundo duplica foco, acessibilidade e composição.
+> Testes verificam links internos e absolutos, modificadores, nome acessível, ícone
+> nos dois modos iniciais do portal e comportamento do item aberto ou recolhido.
+
 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
@@ -143,6 +166,10 @@ e separa a consulta documental da consulta local.
 
 - 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.
+- Regressões da extensão: espaçamento dos grupos sem rótulo em diferentes níveis, acervo vazio
+  sem consulta, modificadores em links absolutos e ícone de nova aba nos dois modos iniciais.
+- Testes de `SidebarItem`: nova aba com modificadores, botão habilitado sem `href`, estado
+  desabilitado e preservação do badge textual no nome acessível do item aberto.
 - 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softize/opus",
-  "version": "26.1.0",
+  "version": "26.2.0",
   "description": "End-to-end action protocol for TypeScript. Single package with subpath exports (core + adapters).",
   "license": "MIT",
   "type": "module",

package/src/ui/components/patterns/sidebar.tsx

@@ -79,6 +79,8 @@ export interface SidebarItemProps {
   className?: string;
   /** Destino nativo. Com onClick, intercepta somente a navegação simples; preserva novas abas. */
   href?: string;
+  /** Abre o destino em nova aba, sem interceptar a navegação nativa. */
+  newTab?: boolean;
   onClick?: () => void;
 }
 
@@ -98,11 +100,19 @@ export function SidebarItem({
   className,
   onClick,
   href,
+  newTab = false,
 }: SidebarItemProps): React.ReactElement {
   const collapsed = useSidebarCollapsed();
   const Target = href !== undefined && !disabled ? "a" : "button";
   const targetProps =
-    Target === "a" ? { href } : { type: "button" as const, disabled };
+    Target === "a"
+      ? {
+          href,
+          ...(newTab ? { target: "_blank", rel: "noopener noreferrer" } : {}),
+        }
+      : { type: "button" as const, disabled };
+  const accessibleLabel =
+    Target === "a" && newTab ? `${label} (abre em nova aba)` : label;
   const activate = (
     event: React.MouseEvent<HTMLAnchorElement | HTMLButtonElement>,
   ) => {
@@ -113,6 +123,7 @@ export function SidebarItem({
         event.ctrlKey ||
         event.shiftKey ||
         event.altKey ||
+        newTab ||
         !onClick
       )
         return;
@@ -129,7 +140,7 @@ export function SidebarItem({
     const button = (
       <Target
         {...targetProps}
-        aria-label={label}
+        aria-label={accessibleLabel}
         aria-current={active ? "page" : undefined}
         onClick={activate}
         className={cn(
@@ -156,7 +167,7 @@ export function SidebarItem({
         <Tooltip>
           <TooltipTrigger asChild>{button}</TooltipTrigger>
           <TooltipContent side="right">
-            {label}
+            {accessibleLabel}
             {tooltipHint}
           </TooltipContent>
         </Tooltip>
@@ -275,6 +286,9 @@ export function SidebarItem({
             {badge}
           </span>
         )}
+        {Target === "a" && newTab && (
+          <span className="sr-only"> (abre em nova aba)</span>
+        )}
       </Target>
       {hasActions && (
         <div

package/src/ui/docs/DocBrowser.tsx

@@ -12,8 +12,15 @@
  * 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, useRef, useState, type ReactNode } from "react";
-import { ArrowLeft, ArrowRight, Search } from "lucide-react";
+import {
+  Fragment,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import { ArrowLeft, ArrowRight, ExternalLink, 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";
@@ -33,14 +40,28 @@ import {
 } from "../components/patterns/sidebar.tsx";
 import { navigate, usePathname } from "../router.ts";
 
+function documentEntries(
+  sections: DocSection[],
+): Array<{ entry: DocEntry; context: string }> {
+  const entriesFrom = (
+    groups: DocGroup[],
+    parent: string,
+  ): Array<{ entry: DocEntry; context: string }> =>
+    groups.flatMap((group) => {
+      const context = group.label?.trim() || parent;
+      return [
+        ...group.pages.map((entry) => ({ entry, context })),
+        ...entriesFrom(group.groups ?? [], context),
+      ];
+    });
+  return sections.flatMap((section) =>
+    entriesFrom(section.groups, section.label),
+  );
+}
+
 function findPage(sections: DocSection[], slug: string): DocEntry | undefined {
-  for (const s of sections) {
-    for (const g of s.groups) {
-      const p = g.pages.find((p) => p.slug === slug);
-      if (p) return p;
-    }
-  }
-  return undefined;
+  return documentEntries(sections).find(({ entry }) => entry.slug === slug)
+    ?.entry;
 }
 
 interface DocBrowserSearchCopy {
@@ -58,7 +79,7 @@ export interface DocBrowserProps {
   basePath?: string;
   /** Path controlado pelo host (modo Maestro). Ausente = standalone (gerencia o próprio). */
   path?: string;
-  /** Seções a exibir (seção → grupo → página). */
+  /** Seções a exibir; grupos podem conter páginas e subgrupos. */
   sections: DocSection[];
   /** Slugs antigos que devem abrir e substituir a URL pela página canônica. */
   redirects?: Readonly<Record<string, string>>;
@@ -79,8 +100,13 @@ export interface DocBrowserProps {
   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 }>;
+  /** Destinos fora dos capítulos; `newTab` abre em nova aba com ícone e descrição acessível. */
+  sidebarLinks?: Array<{
+    label: string;
+    href: string;
+    active?: boolean;
+    newTab?: boolean;
+  }>;
   /** Seções e grupos começam recolhidos; a busca revela resultados sem mudar a escolha manual. */
   sidebarInitiallyCollapsed?: boolean;
 }
@@ -116,14 +142,7 @@ function EditorialDocument({
   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 entries = documentEntries(sections);
   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;
@@ -271,9 +290,14 @@ function searchable(value: string): string {
     .toLocaleLowerCase("pt-BR");
 }
 
+type SidebarGroup = Omit<DocGroup, "groups"> & {
+  navigationKey: string;
+  groups: SidebarGroup[];
+};
+
 type SidebarSection = Omit<DocSection, "groups"> & {
   navigationKey: string;
-  groups: Array<DocGroup & { navigationKey: string }>;
+  groups: SidebarGroup[];
 };
 
 function filterSections(
@@ -282,25 +306,35 @@ function filterSections(
 ): SidebarSection[] {
   const terms = searchable(query).split(/\s+/).filter(Boolean);
   // Identidade vem do manifesto completo, antes de remover ramos pela busca.
+  const indexGroups = (groups: DocGroup[], parent: string): SidebarGroup[] =>
+    groups.map((group, index) => {
+      const navigationKey = `${parent}:${index}`;
+      return {
+        ...group,
+        navigationKey,
+        groups: indexGroups(group.groups ?? [], navigationKey),
+      };
+    });
   const indexedSections = sections.map((section, sectionIndex) => ({
     ...section,
     navigationKey: `section:${sectionIndex}`,
-    groups: section.groups.map((group, groupIndex) => ({
-      ...group,
-      navigationKey: `group:${sectionIndex}:${groupIndex}`,
-    })),
+    groups: indexGroups(section.groups, `group:${sectionIndex}`),
   }));
-  if (terms.length === 0) return indexedSections;
-  return indexedSections.flatMap((section) => {
-    const groups = section.groups.flatMap((group) => {
+  const matchingGroups = (groups: SidebarGroup[]): SidebarGroup[] =>
+    groups.flatMap((group) => {
       const pages = group.pages.filter((page) => {
         const text = searchable(
           `${page.title}\n${page.navigationTitle ?? ""}\n${page.badge ?? ""}\n${page.searchText ?? ""}`,
         );
         return terms.every((term) => text.includes(term));
       });
-      return pages.length === 0 ? [] : [{ ...group, pages }];
+      const children = matchingGroups(group.groups);
+      return pages.length === 0 && children.length === 0
+        ? []
+        : [{ ...group, pages, groups: children }];
     });
+  return indexedSections.flatMap((section) => {
+    const groups = matchingGroups(section.groups);
     return groups.length === 0 ? [] : [{ ...section, groups }];
   });
 }
@@ -327,22 +361,21 @@ function DocSidebarTree({
 
   useEffect(() => {
     if (forceExpanded || initiallyCollapsed) return;
-    const activeGroup = sections
-      .flatMap((section) =>
-        section.groups.map((group) => ({
-          key: group.navigationKey,
-          group,
-        })),
-      )
-      .find(({ group }) =>
-        group.pages.some((page) => page.slug === activeSlug),
-      );
-
-    if (activeGroup === undefined) return;
+    const activePath = (groups: SidebarGroup[]): string[] => {
+      for (const group of groups) {
+        if (group.pages.some((page) => page.slug === activeSlug))
+          return [group.navigationKey];
+        const children = activePath(group.groups);
+        if (children.length > 0) return [group.navigationKey, ...children];
+      }
+      return [];
+    };
+    const keys = sections.flatMap((section) => activePath(section.groups));
+    if (keys.length === 0) return;
     setToggledBranches((current) => {
-      if (!current.has(activeGroup.key)) return current;
+      if (!keys.some((key) => current.has(key))) return current;
       const next = new Set(current);
-      next.delete(activeGroup.key);
+      keys.forEach((key) => next.delete(key));
       return next;
     });
   }, [activeSlug, forceExpanded, sections, initiallyCollapsed]);
@@ -372,6 +405,36 @@ function DocSidebarTree({
     />
   );
 
+  const renderGroup = (group: SidebarGroup): ReactNode => {
+    const key = group.navigationKey;
+    const children = [
+      ...group.pages.map(renderPage),
+      ...group.groups.map(renderGroup),
+    ];
+    if ((group.label ?? "").trim() === "") {
+      return <Fragment key={key}>{children}</Fragment>;
+    }
+    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)}
+          onClick={() => {
+            if (!forceExpanded) toggleGroup(key);
+          }}
+        />
+        {expanded && <SidebarTreeGroup>{children}</SidebarTreeGroup>}
+      </div>
+    );
+  };
+
   return (
     <nav
       aria-label="Navegação da documentação"
@@ -384,38 +447,7 @@ function DocSidebarTree({
           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 ||
-            (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>
-          );
-        });
+        const groups = section.groups.map(renderGroup);
         return (
           <div key={sectionBranch} className="space-y-0.5">
             {collapsibleSection ? (
@@ -452,9 +484,24 @@ function DocSidebarTree({
               key={link.href}
               href={link.href}
               active={link.active}
-              onClick={() => navigate(link.href)}
+              newTab={link.newTab}
+              badge={
+                link.newTab ? (
+                  <ExternalLink
+                    aria-hidden="true"
+                    className="size-3.5 text-muted-foreground"
+                  />
+                ) : undefined
+              }
+              onClick={
+                link.newTab || /^https?:\/\//i.test(link.href)
+                  ? undefined
+                  : () => navigate(link.href)
+              }
               label={link.label}
-              icon={initiallyCollapsed ? <span aria-hidden="true" /> : undefined}
+              icon={
+                initiallyCollapsed ? <span aria-hidden="true" /> : undefined
+              }
             />
           ))}
         </div>
@@ -485,8 +532,8 @@ export function DocBrowser({
   // hooks); o que muda é quem vence no `??`.
   const livePath = usePathname();
   const path = controlledPath ?? livePath;
-  // Default = 1ª página do 1º grupo da 1ª seção (a doc abre na 1ª página).
-  const defaultSlug = sections[0]?.groups[0]?.pages[0]?.slug ?? "";
+  // Abre na primeira página do percurso, inclusive dentro de subgrupos.
+  const defaultSlug = documentEntries(sections)[0]?.entry.slug ?? "";
   // Slug = TODOS os segmentos após o basePath, unidos (rota aninhada: `/docs/guias/deploy`
   // → `guias/deploy`). Slug flat de 1 segmento continua igual (`join` de 1 elemento = ele).
   const rel = path.startsWith(basePath) ? path.slice(basePath.length) : "";
@@ -567,14 +614,14 @@ export function DocBrowser({
             <div className="min-h-0 flex-1 overflow-y-auto px-3 py-6">
               <p
                 className={
-                  visibleSections.length === 0
+                  query.trim() !== "" && 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
+                {query.trim() !== "" && visibleSections.length === 0
                   ? (searchOptions.emptyMessage ??
                     "Nenhum documento encontrado. Tente outro termo.")
                   : ""}

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

@@ -46,6 +46,36 @@ conceitos relacionados, não para reproduzir automaticamente a árvore de arquiv
 tem `slug`, `title` e `render`; `searchText` acrescenta conteúdo à busca e `navigationTitle` permite
 um rótulo lateral curto sem mudar o título completo.
 
+Um grupo pode conter páginas próprias e subgrupos em `groups`. Por exemplo, uma documentação
+por domínio pode reunir as conexões externas em Integrações e manter um grupo por sistema:
+
+```tsx
+const sections: DocSection[] = [{
+  label: 'Domínios',
+  groups: [{
+    label: 'Integrações',
+    pages: [{ slug: 'integrations', title: 'Integrações', render: () => <p>Conexões com sistemas externos.</p> }],
+    groups: [{
+      label: 'Insider',
+      pages: [{ slug: 'integrations/insider', title: 'Insider', render: () => <p>Envio de atributos e eventos.</p> }],
+    }],
+  }],
+}]
+```
+
+As páginas próprias vêm antes dos subgrupos na sequência de leitura. Um grupo com `pages: []`
+pode reunir somente subgrupos; ramos sem páginas em nenhum nível não aparecem na lateral.
+O contexto editorial usa o grupo nomeado mais próximo. A busca revela os ancestrais dos
+resultados e, no modo `sidebarInitiallyCollapsed`, restaura os ramos abertos manualmente
+quando a consulta é limpa. No modo expandido padrão, os ancestrais da página ativa são
+reabertos para mantê-la visível. `groups` é opcional:
+as declarações existentes continuam válidas. Essa hierarquia é uma escolha de leitura do host,
+não exige mover arquivos nem muda a descoberta por pastas.
+
+Se o host também percorre as páginas para montar índices ou resolver links, esse percurso
+precisa visitar `group.groups` recursivamente. Achatar somente `section.groups[].pages`
+não inclui as páginas dos subgrupos.
+
 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;
@@ -64,6 +94,19 @@ o contrato desktop a partir de `64rem`. O aplicativo organiza a moldura do porta
 
 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.
+Destinos com URL HTTP(S) absoluta usam navegação nativa, inclusive para outro aplicativo;
+destinos relativos usam o roteamento compartilhado.
+
+Para abrir uma ferramenta sem substituir a leitura atual, declare `newTab` no destino:
+
+```tsx
+<DocBrowser sections={sections}
+  sidebarLinks={[{ label: 'Lente', href: '/lens', newTab: true }]} />
+```
+
+O link exibe um ícone de nova aba, informa a abertura no nome acessível e usa
+`rel="noopener noreferrer"`. Sem `newTab`, mantém a navegação na aba atual.
+
 `DocCatalog` recebe registros derivados dos Markdown e uma consulta local independente do cabeçalho.
 Passe o catálogo em `content` para preservar a lateral:
 
@@ -148,7 +191,7 @@ não define as rotas nem a autorização do aplicativo.
 
 | Propriedade | Tipo | Padrão | Uso |
 | --- | --- | --- | --- |
-| `sections` | `DocSection[]` | Obrigatória na entrada leve | Seções, grupos e páginas na ordem de leitura. |
+| `sections` | `DocSection[]` | Obrigatória na entrada leve | Seções, grupos, subgrupos opcionais 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. |
@@ -160,7 +203,7 @@ não define as rotas nem a autorização do aplicativo.
 | `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. |
+| `sidebarLinks` | `{ label: string; href: string; active?: boolean; newTab?: boolean }[]` | `[]` | Destinos globais fora dos capítulos; `active` marca o catálogo atual e `newTab` abre em outra aba com ícone e descrição acessível. |
 | `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

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

@@ -73,6 +73,10 @@ diretamente quando a composição precisar de controles, badges ou hierarquia pa
 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.
 
+Para manter a página atual aberta ao visitar outro destino, declare `newTab` junto de `href`.
+O link usa `target="_blank"` e `rel="noopener noreferrer"`, não chama `onClick` e informa
+“abre em nova aba” no nome acessível, inclusive no rail recolhido. Sem `href`, `newTab` não tem efeito.
+
 ## Colapso
 
 `collapsed` informa o estado compacto aos itens. Forneça labels acessíveis mesmo quando somente os
@@ -99,3 +103,22 @@ render(
 - `Sidebar` oferece a coluna de navegação.
 - `SidebarNav`, `SidebarItem` e elementos nativos organizam o conteúdo interno.
 - `Surface` oferece anatomia e tratamento visual quando a região não é uma sidebar.
+
+## Propriedades de SidebarItem
+
+| Propriedade | Tipo | Padrão | Uso |
+| --- | --- | --- | --- |
+| `label` | `string` | Obrigatória | Nome do destino, também usado no modo recolhido. |
+| `href` | `string` | — | Renderiza um link nativo quando o item está habilitado; sem ela, renderiza um botão. |
+| `newTab` | `boolean` | `false` | Com `href`, abre em outra aba, informa a abertura no nome acessível e não chama `onClick`. |
+| `onClick` | `() => void` | — | Ativa o botão ou intercepta o clique simples do link, exceto com `newTab`. |
+| `icon`, `badge` | `ReactNode` | — | Ícone e complemento visual da linha. O modo recolhido mostra somente o ícone. |
+| `active` | `boolean` | `false` | Destaca o destino atual e declara `aria-current="page"`. |
+| `disabled` | `boolean` | `false` | Desabilita o alvo principal e impede que seja um link. |
+| `actions` | `ReactNode` | — | Controles irmãos do alvo principal, no modo aberto. |
+| `onToggle` | `() => void` | — | Exibe um controle separado para expandir ou recolher descendentes no modo aberto. |
+| `expanded` | `boolean` | `false` | Estado visual e acessível do controle de expansão. |
+| `dropPosition` | `'before' \| 'inside' \| 'after'` | — | Indicação visual de posição durante arraste, no modo aberto. |
+| `dragProps` | `HTMLAttributes<HTMLDivElement>` | — | Eventos e atributos de arraste aplicados à linha. |
+| `tooltipHint` | `ReactNode` | — | Complementa o tooltip do modo recolhido. |
+| `className` | `string` | — | Classes da linha nos dois modos. |

package/src/ui/docs/types.ts

@@ -18,6 +18,8 @@ export interface DocGroup {
   label?: string
   icon?: React.ReactNode
   pages: DocEntry[]
+  /** Subgrupos opcionais; páginas próprias vêm antes dos grupos na sequência de leitura. */
+  groups?: DocGroup[]
 }
 
 export interface DocSection {