@aurea-uds/react 0.42.0 → 0.44.0

package/dist/code-client.d.ts

@@ -1,4 +1,10 @@
 import React from "react";
+/** Uma aba do `CodeBlock` em abas: o nome (o "npm"), o código e, se for outra, a língua dele. */
+export interface CodeBlockTab {
+    label: string;
+    code: string;
+    language?: string;
+}
 /** Um pedaço de uma linha de código, com a classe da cor (`tok-keyword`, `tok-string`…) quando tem cor. */
 export interface CodeToken {
     text: string;
@@ -9,8 +15,8 @@ export type CodeLine = CodeToken[];
 /** Quem colore: recebe o código e a língua e devolve as linhas, ou `null` quando não conhece a língua. O da Aurea é o
  *  `highlightCode` de `@aurea-uds/react/code-highlight`. */
 export type CodeHighlighter = (code: string, language: string) => CodeLine[] | null;
-export declare function CodeBlock({ children, language, copyable, preview, lineNumbers, highlight, className }: {
-    children: string;
+export declare function CodeBlock({ children, language, copyable, preview, lineNumbers, highlight, tabs, className }: {
+    children?: string;
     language?: string;
     copyable?: boolean;
     /** A prévia viva do código: com ela, o bloco vira a caixa de exemplo, com as abas Prévia | Código. */
@@ -19,5 +25,8 @@ export declare function CodeBlock({ children, language, copyable, preview, lineN
     lineNumbers?: boolean;
     /** Colore o código. Passe o `highlightCode` de `@aurea-uds/react/code-highlight` (os analisadores são peer opcional). */
     highlight?: CodeHighlighter;
+    /** As alternativas do mesmo passo, em abas (o comando de instalar em npm, pnpm, yarn e bun): a fileira em cima, dentro
+     *  da caixa, e um código por aba. Com `tabs`, o `children` não é lido. */
+    tabs?: CodeBlockTab[];
     className?: string;
 }): React.JSX.Element;

package/dist/code-client.js

@@ -29,6 +29,26 @@ function CaixaDeExemplo({ preview, codigo, className }) {
     const botao = (a, rotulo) => _jsx("button", { type: "button", role: "tab", id: `${id}-${a}`, ref: a === "preview" ? refPrevia : refCodigo, className: aba === a ? "active" : undefined, "aria-selected": aba === a, "aria-controls": `${id}-${a}-panel`, tabIndex: aba === a ? 0 : -1, onClick: () => setAba(a), onKeyDown: tecla, children: rotulo });
     return _jsxs("div", { className: cx("demo code-preview", className), children: [_jsx("div", { className: "demo-tabs", children: _jsxs("div", { className: "segmented", role: "tablist", children: [botao("preview", s.codeBlockPreview), botao("code", s.codeBlockCode)] }) }), _jsx("div", { className: "demo-panel", "data-panel": "preview", role: "tabpanel", id: `${id}-preview-panel`, "aria-labelledby": `${id}-preview`, tabIndex: 0, hidden: aba !== "preview", children: preview }), _jsx("div", { className: "demo-panel demo-code", "data-panel": "code", role: "tabpanel", id: `${id}-code-panel`, "aria-labelledby": `${id}-code`, tabIndex: 0, hidden: aba !== "code", children: codigo })] });
 }
+// O CÓDIGO EM ABAS (bloco 1, o 3-A — 23/10/2026): as alternativas do MESMO passo, uma de cada vez — o comando de instalar
+// em npm, pnpm, yarn e bun, como na documentação da referência (a fileira em cima, dentro da caixa do código). O estado é
+// do React; os painéis levam `data-aurea-tabpanel` para o `aurea.js` do core trocar também na página que não acende (o
+// site estático). A tecla para aqui (`stopPropagation`): com os dois na página, a seta andaria duas abas.
+function CodigoEmAbas({ tabs, language, copyable, highlight, className }) {
+    const s = useAureaStrings();
+    const id = React.useId();
+    const [aba, setAba] = React.useState(0);
+    const refs = React.useRef([]);
+    const ir = (i) => { setAba(i); refs.current[i]?.focus(); };
+    const tecla = (e) => {
+        const n = tabs.length;
+        if (!["ArrowRight", "ArrowLeft", "Home", "End"].includes(e.key))
+            return;
+        e.preventDefault();
+        e.stopPropagation();
+        ir(e.key === "Home" ? 0 : e.key === "End" ? n - 1 : e.key === "ArrowRight" ? (aba + 1) % n : (aba - 1 + n) % n);
+    };
+    return _jsxs("div", { className: cx("code-tabs", className), children: [_jsx("div", { className: "code-tabs-list", role: "tablist", "aria-label": s.tabsLabel, children: tabs.map((t, i) => _jsx("button", { type: "button", role: "tab", id: `${id}-${i}`, ref: el => { refs.current[i] = el; }, className: cx("code-tab", aba === i && "active"), "aria-selected": aba === i, "aria-controls": `${id}-${i}-panel`, tabIndex: aba === i ? 0 : -1, onClick: () => setAba(i), onKeyDown: tecla, children: t.label }, t.label)) }), tabs.map((t, i) => _jsx("div", { role: "tabpanel", id: `${id}-${i}-panel`, "aria-labelledby": `${id}-${i}`, "data-aurea-tabpanel": "", hidden: aba !== i, children: _jsx(CodeBlock, { language: t.language ?? language, copyable: copyable, highlight: highlight, children: t.code }) }, t.label))] });
+}
 // lineNumbers e highlight (lote V, 20/10/2026): as linhas viram um <span class="code-line"> cada, com o "\n" entre
 // elas — o texto do bloco continua IGUAL ao código (copiar com o mouse traz o mesmo texto), e o número é desenhado pelo
 // CSS, sem entrar no texto nem no leitor de tela. Sem as duas, a marcação é a de antes, sem mudar nada.
@@ -37,7 +57,9 @@ function linhasDoCodigo(codigo, language, highlight) {
     const linhas = highlight?.(codigo, language) ?? codigo.split("\n").map(l => l === "" ? [] : [{ text: l }]);
     return codigo.endsWith("\n") && linhas.length > 1 && linhas[linhas.length - 1].length === 0 ? linhas.slice(0, -1) : linhas;
 }
-export function CodeBlock({ children, language = "text", copyable, preview, lineNumbers, highlight, className }) {
+export function CodeBlock({ children, language = "text", copyable, preview, lineNumbers, highlight, tabs, className }) {
+    if (tabs && tabs.length > 0)
+        return _jsx(CodigoEmAbas, { tabs: tabs, language: language, copyable: copyable, highlight: highlight, className: className });
     if (preview !== undefined)
         return _jsx(CaixaDeExemplo, { preview: preview, className: className, codigo: _jsx(CodeBlock, { language: language, copyable: copyable, lineNumbers: lineNumbers, highlight: highlight, children: children }) });
     const s = useAureaStrings();
@@ -47,6 +69,7 @@ export function CodeBlock({ children, language = "text", copyable, preview, line
     // demo do catálogo já tinha corrigido em 30/07/2026 no lado dele; aqui, na biblioteca, ele
     // seguia aberto e só não aparecia porque nenhuma linha era comprida o bastante. Quem o achou
     // foi o `catalog-sweep` em 10/08/2026, quando o bloco do I1 fez a linha de import crescer.
+    children ??= "";
     const linhas = lineNumbers || highlight ? linhasDoCodigo(children, language, highlight) : null;
     const colorido = linhas != null && highlight != null && linhas.some(l => l.some(p => p.className));
     // Os algarismos da última linha: a coluna do número tem a largura deles (99 → 2, 100 → 3).

package/dist/feedback-client.d.ts

@@ -55,7 +55,7 @@ export declare function Spinner({ size, label, decorative, className, ...props }
     decorative?: boolean;
 }): React.JSX.Element;
 export type DataStateValue = "loading" | "error" | "empty" | UniversalState;
-export type DataStateProps = HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement> & {
+export type DataStateProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & RefAttributes<HTMLDivElement> & {
     state?: DataStateValue;
     message?: ReactNode;
     skeleton?: ReactNode;

package/dist/inputs-client.d.ts

@@ -310,15 +310,17 @@ export declare function OTPField({ length, value, defaultValue, onValueChange, m
     /** `secondary`: o fundo neutro do `Input` secundário, para o campo dentro de um cartão. */
     variant?: "primary" | "secondary";
 }): React.JSX.Element;
-export declare function SegmentedControl({ items, value, onChange, label, fullWidth }: {
+export declare function SegmentedControl({ items, value, onChange, label, fullWidth, size }: {
     items: Array<{
         value: string;
         label: ReactNode;
+        href?: string;
     }>;
     value: string;
-    onChange: (v: string) => void;
+    onChange?: (v: string) => void;
     label?: string;
     fullWidth?: boolean;
+    size?: "sm" | "md";
 }): React.JSX.Element;
 export interface ComboboxOption {
     value: string;

package/dist/inputs-client.js

@@ -763,9 +763,15 @@ export function OTPField({ length, value, defaultValue, onValueChange, mask, dis
 // `fullWidth` (A5, 06/10/2026): o mesmo nome e o mesmo desenho do nativo — o controle ocupa a
 // linha e cada segmento CRESCE a partir do rótulo, sem encolher abaixo dele. É como o grupo
 // de botões alternáveis da referência ocupa a linha.
-export function SegmentedControl({ items, value, onChange, label, fullWidth }) {
+// NAVEGAÇÃO (bloco 1, o 5-A — 23/10/2026): com `href` em TODOS os itens, a cápsula é um <nav> de links — o atual leva
+// `aria-current="page"` —, e não um grupo de escolha: ir para outra página é navegação, e o leitor de tela tem de ouvir
+// "link", não "opção". É a chave Web | Native do site. `size="sm"`: a cápsula baixa da referência (abas de 24).
+export function SegmentedControl({ items, value, onChange, label, fullWidth, size = "md" }) {
     const s = useAureaStrings();
-    return _jsx(BaseRadioGroup, { className: fullWidth ? "segmented segmented-full" : "segmented", "aria-label": label ?? s.optionsLabel, value: value, onValueChange: v => onChange(String(v)), children: items.map(i => _jsx(BaseRadio.Root, { value: i.value, className: i.value === value ? "active" : undefined, nativeButton: true, render: _jsx("button", { type: "button" }), children: i.label }, i.value)) });
+    const classe = cx("segmented", fullWidth && "segmented-full", size === "sm" && "segmented-sm");
+    if (items.length > 0 && items.every(i => i.href != null))
+        return _jsx("nav", { className: classe, "aria-label": label ?? s.optionsLabel, children: items.map(i => _jsx("a", { href: i.href, className: i.value === value ? "active" : undefined, "aria-current": i.value === value ? "page" : undefined, children: i.label }, i.value)) });
+    return _jsx(BaseRadioGroup, { className: classe, "aria-label": label ?? s.optionsLabel, value: value, onValueChange: v => onChange?.(String(v)), children: items.map(i => _jsx(BaseRadio.Root, { value: i.value, className: i.value === value ? "active" : undefined, nativeButton: true, render: _jsx("button", { type: "button" }), children: i.label }, i.value)) });
 }
 const ehAgrupado = (items) => items != null && items.length > 0 && typeof items[0] === "object" && items[0] != null && "items" in items[0];
 // UM renderizador e UMA lista para os dois combobox: duas cópias da mesma árvore é como a

package/dist/inputs.d.ts

@@ -1,3 +1,4 @@
 export * from "./inputs-client.js";
 export { Textarea, Checkbox, Radio, Switch, Range } from "./markup.js";
 export { Label, InputGroup, InputGroupAddon, type AddonSide, type AddonLayout, type FieldSize, type FieldVariant } from "./markup.js";
+export type { ColorSpace, ColorChannel } from "./color.js";

package/dist/layout-client.d.ts

@@ -1,12 +1,12 @@
 import React, { type HTMLAttributes, type RefAttributes, type ReactNode } from "react";
 import { type Orientation, type Responsive } from "./pure.js";
 import { type IconButtonProps } from "./actions.js";
-import { type HeaderVariant, type HeaderTab, type SidebarVariant, type SidebarScrollbar, type SidebarItem } from "./navigation.js";
-declare function AppShellSidebarToggle({ className, ...props }: Omit<IconButtonProps, "icon" | "label" | "onClick">): React.JSX.Element | null;
-export declare function AppShell({ brand, navigation, navItems, currentNavId, navLabel, topbar, topbarVariant, topbarDivider, topbarTabs, topbarCurrentTab, topbarTabsLabel, layout, sidebarVariant, sidebarScrollbar, sidebarFooter, sidebarCollapsed, sidebarCollapsible, defaultSidebarCollapsed, onSidebarCollapsedChange, contentVariant, aside, asideLabel, asideVariant, children, className, ...props }: HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement> & {
+import { type HeaderVariant, type HeaderTab, type SidebarVariant, type SidebarScrollbar, type SidebarEntry, type SidebarCollapsible, type SidebarIndicator } from "./navigation.js";
+declare function AppShellSidebarToggle(props: Omit<IconButtonProps, "icon" | "label" | "onClick" | "variant">): React.JSX.Element;
+export declare function AppShell({ brand, navigation, navItems, currentNavId, navLabel, topbar, topbarVariant, topbarDivider, topbarTabs, topbarCurrentTab, topbarTabsLabel, topbarTabsEnd, layout, sidebarVariant, sidebarScrollbar, sidebarFooter, sidebarCollapsed, sidebarCollapsible, sidebarToggle, sidebarShortcut, sidebarIndicator, sidebarPanel, defaultSidebarCollapsed, onSidebarCollapsedChange, contentVariant, aside, asideLabel, asideVariant, children, className, ...props }: HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement> & {
     brand: ReactNode;
     navigation?: ReactNode;
-    navItems?: SidebarItem[];
+    navItems?: SidebarEntry[];
     currentNavId?: string;
     navLabel?: string;
     topbar?: ReactNode;
@@ -28,6 +28,8 @@ export declare function AppShell({ brand, navigation, navItems, currentNavId, na
     topbarCurrentTab?: string;
     /** O nome da segunda linha para o leitor de tela. Padrão: `"Sections"`. */
     topbarTabsLabel?: string;
+    /** A ponta da linha das áreas (o `tabsEnd` do `Header`): a chave Web | Native da documentação. */
+    topbarTabsEnd?: ReactNode;
     /** 0.32.0: a barra de rolagem da lateral da esquerda — o `scrollbar` da `Sidebar`. Padrão `hover` (clara, só com o
      *  ponteiro em cima); `visible` é a barra sempre à vista. */
     sidebarScrollbar?: SidebarScrollbar;
@@ -42,8 +44,22 @@ export declare function AppShell({ brand, navigation, navItems, currentNavId, na
     asideVariant?: SidebarVariant;
     /** A lateral em trilha de ícones. Controlado: quem passa decide (e o `onSidebarCollapsedChange` avisa). */
     sidebarCollapsed?: boolean;
-    /** AN-01: o botão de recolher na junção do menu com o conteúdo, e a trilha sozinha entre 1024 e 1279 de largura. */
-    sidebarCollapsible?: boolean;
+    /** AN-01: o botão de recolher na junção do menu com o conteúdo, e a trilha sozinha entre 1024 e 1279 de largura.
+     *  Desde o bloco 2 (4-A), também o JEITO de recolher: `true` ou `"icon"` (a trilha), `"capsule"` (a trilha em cápsula) ou
+     *  `"offcanvas"` (a lateral sai da tela). */
+    sidebarCollapsible?: boolean | SidebarCollapsible;
+    /** 4-B: onde o shell põe o botão de recolher. `"edge"` (o padrão): na junção da lateral com o conteúdo (no
+     *  `layout="sidebar"`, no começo da barra do conteúdo). `"none"`: o shell não põe nenhum, e o app põe o `Sidebar.Toggle`
+     *  onde quiser — dentro da lateral, ao lado da marca, ou no pé, como linha (`variant="item"`). */
+    sidebarToggle?: "edge" | "none";
+    /** 4-B: o atalho Ctrl+B (Cmd+B no Mac), que recolhe e abre a lateral (abaixo de 1024, abre e fecha a gaveta). Padrão:
+     *  ligado, com `sidebarCollapsible`. Não age quando a pessoa está digitando num campo. */
+    sidebarShortcut?: boolean;
+    /** 4-H: o desenho do item atual da lateral (o `indicator` da `Sidebar`). */
+    sidebarIndicator?: SidebarIndicator;
+    /** 4-F e 4-G: a trilha das seções com o painel (o `panel` da `Sidebar`) — os itens do primeiro nível de `navItems` viram
+     *  seções. `docked`: o painel ao lado (recolher esconde o painel); `overlay`: o painel abre por cima. */
+    sidebarPanel?: "docked" | "overlay";
     /** AN-01: começa recolhida, sem controlar. A escolha vale até a janela cruzar 1280. */
     defaultSidebarCollapsed?: boolean;
     /** AN-01: avisa cada troca — pelo botão, ou pela largura cruzando 1280. Guardar a preferência é do app. */

package/dist/layout-client.js

@@ -3,7 +3,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 // Fase 9 (achado A5): este arquivo saiu do index.tsx de 970 linhas. Um módulo por categoria
 // do registry — a taxonomia já existia e é gateada. A ordem de import entre eles é um DAG:
 // internal → system → actions → feedback → inputs → navigation → layout → data-display → resto.
-import React, { useEffect, useRef, useState, useSyncExternalStore } from "react";
+import { useEffect, useRef, useState, useSyncExternalStore } from "react";
 import { Separator as BaseSeparator } from "@base-ui/react/separator";
 import { useDirection } from "@base-ui/react/direction-provider";
 import { cx, useAureaStrings } from "./internal.js";
@@ -160,22 +160,24 @@ function useLargura(query) {
 // aprovado"*). No `layout="sidebar"` ele substitui a bolinha da junção: com a barra no conteúdo, o shell o põe no começo
 // dela; sem barra, o app o põe ao lado do próprio título (`AppShell.SidebarToggle`). Abaixo de 1024 ele some — ali a
 // lateral é gaveta, e quem abre é o botão da gaveta.
-const ShellToggleContext = React.createContext(null);
-function AppShellSidebarToggle({ className, ...props }) {
-    const c = React.useContext(ShellToggleContext);
-    if (!c)
-        return null;
-    return _jsx(IconButton, { className: cx("sidebar-collapse-trigger", className), icon: "sidebar-simple", label: c.rotulo, "aria-expanded": !c.efetiva, "aria-controls": SHELL_NAV_ID, onClick: c.alternar, ...props });
+// Desde o bloco 2 (4-B, 25/10/2026), é o `Sidebar.Toggle`: o shell põe a lateral num `Sidebar.Provider`, e o botão lê o estado
+// dele — o mesmo botão serve ao lado do título, dentro da lateral (ao lado da marca) e no pé, como linha.
+function ProvedorDaLateral({ ligado, children, ...p }) {
+    return ligado ? _jsx(Sidebar.Provider, { id: SHELL_NAV_ID, ...p, children: children }) : _jsx(_Fragment, { children: children });
 }
-export function AppShell({ brand, navigation, navItems, currentNavId, navLabel, topbar, topbarVariant = "floating", topbarDivider, topbarTabs, topbarCurrentTab, topbarTabsLabel, layout = "app", sidebarVariant, sidebarScrollbar, sidebarFooter, sidebarCollapsed, sidebarCollapsible, defaultSidebarCollapsed, onSidebarCollapsedChange, contentVariant = "surface", aside, asideLabel, asideVariant, children, className, ...props }) {
+function AppShellSidebarToggle(props) { return _jsx(Sidebar.Toggle, { ...props }); }
+export function AppShell({ brand, navigation, navItems, currentNavId, navLabel, topbar, topbarVariant = "floating", topbarDivider, topbarTabs, topbarCurrentTab, topbarTabsLabel, topbarTabsEnd, layout = "app", sidebarVariant, sidebarScrollbar, sidebarFooter, sidebarCollapsed, sidebarCollapsible, sidebarToggle = "edge", sidebarShortcut = true, sidebarIndicator, sidebarPanel, defaultSidebarCollapsed, onSidebarCollapsedChange, contentVariant = "surface", aside, asideLabel, asideVariant, children, className, ...props }) {
     const s = useAureaStrings();
     const docs = layout === "docs", lateral = layout === "sidebar";
     useGavetaFechaNoDesktop(docs);
     const controlado = sidebarCollapsed !== undefined;
+    // O jeito de recolher (4-A): `true` é a trilha de sempre.
+    const forma = sidebarCollapsible === true ? "icon" : sidebarCollapsible || undefined;
+    const recolhe = !!forma;
     // `null` = ninguém escolheu, e vale a largura.
     const [escolha, setEscolha] = useState(defaultSidebarCollapsed ?? null);
     const media = useLargura(MEDIA_MEDIA), estreita = useLargura(MEDIA_ESTREITA);
-    const recolhida = controlado ? !!sidebarCollapsed : (escolha ?? (!!sidebarCollapsible && media));
+    const recolhida = controlado ? !!sidebarCollapsed : (escolha ?? (recolhe && media));
     // NA GAVETA A LATERAL NUNCA É TRILHA. Abaixo de 1024 ela abre por cima de tudo, com espaço para o
     // nome; recolhida ali, era uma gaveta de ícones sem nome — também para quem já passava
     // `sidebarCollapsed` (medido em 03/10/2026, na mesma conferência).
@@ -185,16 +187,29 @@ export function AppShell({ brand, navigation, navItems, currentNavId, navLabel,
     // Cruzar 1280 é mudar de contexto: a escolha da pessoa sai e a largura volta a mandar. Pelo
     // evento do navegador, e não comparando desenhos, para a hidratação não contar como cruzamento.
     useEffect(() => {
-        if (!sidebarCollapsible || typeof window === "undefined" || typeof window.matchMedia !== "function")
+        if (!recolhe || typeof window === "undefined" || typeof window.matchMedia !== "function")
             return;
         const mq = window.matchMedia(MEDIA_MEDIA);
         const aoCruzar = (e) => { if (!controlado)
             setEscolha(null); aviso.current?.(e.matches); };
         mq.addEventListener?.("change", aoCruzar);
         return () => mq.removeEventListener?.("change", aoCruzar);
-    }, [sidebarCollapsible, controlado]);
-    const alternar = () => { const nova = !recolhida; if (!controlado)
-        setEscolha(nova); onSidebarCollapsedChange?.(nova); };
+    }, [recolhe, controlado]);
+    // QUEM MUDA O ESTADO: o botão da junção, o `Sidebar.Toggle` em qualquer lugar e o Ctrl+B passam todos por aqui (4-B).
+    // Abaixo de 1024 a lateral é a gaveta: recolher ali é abrir ou fechar a gaveta, como o "mobile" da referência.
+    const definir = (nova) => {
+        if (estreita) {
+            try {
+                document.getElementById(SHELL_NAV_ID)?.togglePopover();
+            }
+            catch { /* motor sem popover */ }
+            return;
+        }
+        if (!controlado)
+            setEscolha(nova);
+        onSidebarCollapsedChange?.(nova);
+    };
+    const alternar = () => definir(!recolhida);
     const rotulo = efetiva ? s.sidebarExpand : s.sidebarCollapse;
     // A seta aponta para onde a lateral vai: recolher é para o começo da linha, abrir é para o fim. Na
     // escrita da direita para a esquerda o começo é a direita — pela direção do provedor, e não por
@@ -208,9 +223,9 @@ export function AppShell({ brand, navigation, navItems, currentNavId, navLabel,
     // No arranjo, o topo é o pequeno (`size="sm"`), e o botão também: com o tamanho de sempre ele ficava 4 maior que os
     // vizinhos e fora da linha deles (medido a 375, sem toque; com toque, todos sobem para 44).
     const botaoDaGaveta = _jsx(IconButton, { className: "nav-toggle", icon: "list", label: s.navigationToggle, popoverTarget: SHELL_NAV_ID, ...(docs ? { size: "sm" } : {}) });
-    return _jsx("div", { className: cx("app-shell", layout === "docs" && "app-shell-docs", lateral && "app-shell-lateral", !lateral && topbarVariant === "flush" && "app-shell-flush", sidebarCollapsible && "app-shell-collapsible", aside != null && "app-shell-with-aside", className), ...props, children: _jsxs(ShellToggleContext.Provider, { value: sidebarCollapsible ? { alternar, efetiva, rotulo } : null, children: [_jsx("a", { className: "skip-link", href: `#${SHELL_MAIN_ID}`, children: s.skipToContent }), !lateral && _jsxs(Header, { variant: topbarVariant, divider: topbarDivider, tabs: topbarTabs, currentTab: topbarCurrentTab, tabsLabel: topbarTabsLabel, ...(docs ? { maxWidth: "docs", size: "sm" } : {}), brand: docs ? brand : _jsxs(_Fragment, { children: [botaoDaGaveta, brand] }), children: [topbar, docs && botaoDaGaveta] }), sidebarCollapsible && !lateral && _jsx("div", { className: "sidebar-toggle-slot", children: _jsx(Tooltip, { content: rotulo, side: "right", children: _jsx(IconButton, { className: "sidebar-toggle", size: "xs", icon: paraOComeco === direita ? "caret-right" : "caret-left", label: rotulo, "aria-expanded": !efetiva, "aria-controls": SHELL_NAV_ID, onClick: alternar }) }) }), _jsx(Sidebar, { id: SHELL_NAV_ID, popover: "auto", variant: sidebarVariant, scrollbar: sidebarScrollbar, collapsed: efetiva, items: navItems, current: currentNavId, label: navLabel, onToggle: focoDaGaveta, header: lateral ? brand : undefined, footer: sidebarFooter, children: navigation }), docs && aside != null && _jsx("div", { className: "docs-toc-bar", children: _jsxs("button", { type: "button", className: "docs-toc-toggle", popoverTarget: SHELL_TOC_ID, children: [_jsx(Icon, { name: "list-bullets" }), _jsx("span", { className: "docs-toc-current", "data-toc-current": "", children: asideLabel ?? s.tocLabel }), _jsx(Icon, { name: "caret-down" })] }) }), lateral
+    return _jsx("div", { className: cx("app-shell", layout === "docs" && "app-shell-docs", lateral && "app-shell-lateral", !lateral && topbarVariant === "flush" && "app-shell-flush", recolhe && "app-shell-collapsible", aside != null && "app-shell-with-aside", className), ...props, children: _jsxs(ProvedorDaLateral, { ligado: recolhe, collapsed: efetiva, onCollapsedChange: definir, collapsible: forma, shortcut: sidebarShortcut, children: [_jsx("a", { className: "skip-link", href: `#${SHELL_MAIN_ID}`, children: s.skipToContent }), !lateral && _jsxs(Header, { variant: topbarVariant, divider: topbarDivider, tabs: topbarTabs, currentTab: topbarCurrentTab, tabsLabel: topbarTabsLabel, tabsEnd: topbarTabsEnd, ...(docs ? { maxWidth: "docs", size: "sm" } : {}), brand: docs ? brand : _jsxs(_Fragment, { children: [botaoDaGaveta, brand] }), children: [topbar, docs && botaoDaGaveta] }), recolhe && !lateral && sidebarToggle !== "none" && _jsx("div", { className: "sidebar-toggle-slot", children: _jsx(Tooltip, { content: rotulo, side: "right", children: _jsx(IconButton, { className: "sidebar-toggle", size: "xs", icon: paraOComeco === direita ? "caret-right" : "caret-left", label: rotulo, "aria-expanded": !efetiva, "aria-controls": SHELL_NAV_ID, onClick: alternar }) }) }), _jsx(Sidebar, { id: SHELL_NAV_ID, popover: "auto", variant: sidebarVariant, scrollbar: sidebarScrollbar, collapsed: efetiva, collapsible: forma, indicator: sidebarIndicator, panel: sidebarPanel, items: navItems, current: currentNavId, label: navLabel, onToggle: focoDaGaveta, header: lateral ? brand : undefined, footer: sidebarFooter, children: navigation }), docs && aside != null && _jsx("div", { className: "docs-toc-bar", children: _jsxs("button", { type: "button", className: "docs-toc-toggle", popoverTarget: SHELL_TOC_ID, children: [_jsx(Icon, { name: "list-bullets" }), _jsx("span", { className: "docs-toc-current", "data-toc-current": "", children: asideLabel ?? s.tocLabel }), _jsx(Icon, { name: "caret-down" })] }) }), lateral
                     ? _jsxs("div", { className: "app-shell-column", children: [topbar != null
-                                ? _jsx(Header, { variant: "flush", size: "sm", divider: topbarDivider, brand: _jsxs(_Fragment, { children: [botaoDaGaveta, _jsx(AppShellSidebarToggle, {})] }), children: topbar })
+                                ? _jsx(Header, { variant: "flush", size: "sm", divider: topbarDivider, brand: _jsxs(_Fragment, { children: [botaoDaGaveta, sidebarToggle !== "none" && _jsx(AppShellSidebarToggle, {})] }), children: topbar })
                                 : _jsxs("div", { className: "app-shell-narrow-bar", children: [botaoDaGaveta, brand] }), _jsx("main", { id: SHELL_MAIN_ID, tabIndex: -1, className: cx("content", contentVariant === "plain" && "content-plain"), children: children })] })
                     : _jsx("main", { id: SHELL_MAIN_ID, tabIndex: -1, className: cx("content", contentVariant === "plain" && "content-plain"), children: children }), aside != null && _jsx(Sidebar, { placement: "right", variant: asideVariant ?? sidebarVariant, className: "app-shell-aside", "aria-label": asideLabel ?? s.tocLabel, ...(docs ? { id: SHELL_TOC_ID, popover: "auto", onToggle: focoDaGaveta } : {}), children: aside })] }) });
 }

package/dist/markup.d.ts

@@ -375,6 +375,9 @@ export interface HeaderProps extends HTMLAttributes<HTMLElement>, RefAttributes<
     currentTab?: string;
     /** O nome da segunda linha para o leitor de tela. Padrão: `"Sections"`. */
     tabsLabel?: string;
+    /** O que fica na PONTA da segunda linha, do lado oposto das áreas (bloco 1, o 5-A — 23/10/2026): a chave Web | Native
+     *  da documentação da referência. Some abaixo de 768, como lá. Sem `tabs`, não aparece. */
+    tabsEnd?: ReactNode;
 }
 /** Uma área da segunda linha do `Header`: o nome, o endereço e, se quiser, o ícone (o desenho que o app passa). */
 export interface HeaderTab {
@@ -384,7 +387,7 @@ export interface HeaderTab {
     icon?: ReactNode;
     render?: SidebarItem["render"];
 }
-export declare function Header({ variant, divider, brand, items, current, actions, maxWidth, itemsJustify, size, blurred, menuActions, navLabel, menuLabel, menuId, tabs, currentTab, tabsLabel, children, className, ...props }: HeaderProps): React.JSX.Element;
+export declare function Header({ variant, divider, brand, items, current, actions, maxWidth, itemsJustify, size, blurred, menuActions, navLabel, menuLabel, menuId, tabs, currentTab, tabsLabel, tabsEnd, children, className, ...props }: HeaderProps): React.JSX.Element;
 /** @deprecated `Topbar` é o nome antigo do `Header` (07/10/2026). Continua funcionando, igual; use `Header`. */
 export declare function Topbar(props: HeaderProps): React.JSX.Element;
 export declare function Kbd({ children, className, ...props }: HTMLAttributes<HTMLElement> & RefAttributes<HTMLElement>): React.JSX.Element;

package/dist/markup.js

@@ -206,13 +206,17 @@ function linksDoHeader(items, current) {
             return _jsx("li", { children: it.render ? fundirRender(it.render, p, "a") : _jsx("a", { href: it.href, ...p }) }, it.id);
         }) });
 }
-export function Header({ variant = "floating", divider, brand, items, current, actions, maxWidth, itemsJustify = "end", size = "md", blurred, menuActions, navLabel = "Main", menuLabel = "Menu", menuId = "aurea-header-menu", tabs, currentTab, tabsLabel = "Sections", children, className, ...props }) {
+export function Header({ variant = "floating", divider, brand, items, current, actions, maxWidth, itemsJustify = "end", size = "md", blurred, menuActions, navLabel = "Main", menuLabel = "Menu", menuId = "aurea-header-menu", tabs, currentTab, tabsLabel = "Sections", tabsEnd, children, className, ...props }) {
     const site = !!items && items.length > 0, comAbas = !!tabs && tabs.length > 0;
-    const miolo = _jsxs(_Fragment, { children: [brand != null && _jsx("div", { className: "brand", children: brand }), site && _jsx("nav", { className: "topbar-nav", "aria-label": navLabel, children: linksDoHeader(items, current) }), children, actions != null && _jsx("div", { className: "topbar-actions", children: actions }), site && _jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "btn btn-ghost btn-icon topbar-menu-toggle", popoverTarget: menuId, "aria-label": menuLabel, children: _jsx("span", { className: "topbar-menu-icon", "aria-hidden": "true" }) }), _jsxs("nav", { id: menuId, popover: "auto", className: "topbar-menu-panel", "aria-label": navLabel, children: [linksDoHeader(items, current), menuActions != null && _jsx("div", { className: "topbar-menu-actions", children: menuActions })] })] }), comAbas && _jsx("nav", { className: "topbar-tabs", "aria-label": tabsLabel, children: tabs.map(t => {
-                    const p = { className: "topbar-tab", "aria-current": t.id === currentTab ? "page" : undefined,
-                        children: _jsxs(_Fragment, { children: [t.icon != null && _jsx("span", { className: "topbar-tab-icon", "aria-hidden": "true", children: t.icon }), _jsx("span", { children: t.label })] }) };
-                    return _jsx(React.Fragment, { children: t.render ? fundirRender(t.render, p, "a") : _jsx("a", { href: t.href, ...p }) }, t.id);
-                }) })] });
+    const miolo = _jsxs(_Fragment, { children: [brand != null && _jsx("div", { className: "brand", children: brand }), site && _jsx("nav", { className: "topbar-nav", "aria-label": navLabel, children: linksDoHeader(items, current) }), children, actions != null && _jsx("div", { className: "topbar-actions", children: actions }), site && _jsxs(_Fragment, { children: [_jsx("button", { type: "button", className: "btn btn-ghost btn-icon topbar-menu-toggle", popoverTarget: menuId, "aria-label": menuLabel, children: _jsx("span", { className: "topbar-menu-icon", "aria-hidden": "true" }) }), _jsxs("nav", { id: menuId, popover: "auto", className: "topbar-menu-panel", "aria-label": navLabel, children: [linksDoHeader(items, current), menuActions != null && _jsx("div", { className: "topbar-menu-actions", children: menuActions })] })] }), comAbas && (() => {
+                const abas = _jsx("nav", { className: "topbar-tabs", "aria-label": tabsLabel, children: tabs.map(t => {
+                        const p = { className: "topbar-tab", "aria-current": t.id === currentTab ? "page" : undefined,
+                            children: _jsxs(_Fragment, { children: [t.icon != null && _jsx("span", { className: "topbar-tab-icon", "aria-hidden": "true", children: t.icon }), _jsx("span", { children: t.label })] }) };
+                        return _jsx(React.Fragment, { children: t.render ? fundirRender(t.render, p, "a") : _jsx("a", { href: t.href, ...p }) }, t.id);
+                    }) });
+                // Sem o encaixe, a marcação de sempre; com ele, a linha das áreas e a ponta numa mesma faixa.
+                return tabsEnd == null ? abas : _jsxs("div", { className: "topbar-tabs-row", children: [abas, _jsx("div", { className: "topbar-tabs-end", children: tabsEnd })] });
+            })()] });
     return _jsx("header", { className: cx("topbar", `topbar-${variant}`, divider && variant === "flush" && "topbar-divider", site && "topbar-site", site && itemsJustify === "start" && "topbar-items-start", size === "sm" && "topbar-sm", blurred && variant === "flush" && "topbar-blurred", maxWidth && "topbar-contained", comAbas && "topbar-with-tabs", className), ...props, children: maxWidth ? _jsx("div", { className: cx("container", maxWidth !== "xl" && `container-${maxWidth}`, "topbar-inner"), children: miolo }) : miolo });
 }
 /** @deprecated `Topbar` é o nome antigo do `Header` (07/10/2026). Continua funcionando, igual; use `Header`. */

package/dist/navigation-client.d.ts

@@ -1,6 +1,7 @@
 import React, { type HTMLAttributes, type RefAttributes, type ReactNode, type ReactElement } from "react";
 import { type Responsive } from "./pure.js";
 import { type IconName } from "./system.js";
+import { type IconButtonProps } from "./actions.js";
 export type StepState = "default" | "active" | "done" | "error";
 export interface StepItem {
     label: ReactNode;
@@ -91,21 +92,75 @@ export interface SidebarItem {
     icon?: IconName;
     badge?: ReactNode;
     onClick?: () => void;
-    items?: SidebarItem[];
+    items?: SidebarEntry[];
     /** O link do roteador do app (M-01): `<Link href="/relatorios" />`. Recebe a pele, o estado de página atual e o conteúdo do item. */
     render?: ReactElement;
+    /** A foto ou o logotipo do item (4-E — o time, a pessoa): toma o lugar do `icon`, no mesmo formato da `NavList`. Recolhida, ele
+     *  fica na trilha, e não um vão. */
+    avatar?: {
+        src?: string;
+        fallback?: ReactNode;
+    };
+    /** A ação do item ou do grupo (4-D — o "⋯", o "+"): um `IconButton` pequeno. Mora AO LADO do item, nunca dentro do link (botão
+     *  dentro de link não é HTML válido, e o leitor de tela perde um dos dois). Recolhida, some, como na referência. */
+    action?: ReactNode;
+    /** Só no GRUPO (item com `items` e sem destino): o nome vira um botão que dobra a lista (4-D). */
+    collapsible?: boolean;
+    /** Com `collapsible`: o grupo começa aberto. Padrão: aberto. */
+    defaultOpen?: boolean;
 }
+/** A lista da lateral: os itens e, entre eles, `"separator"` — a divisória entre seções (4-E). Sem linha (ADR-0072): é um vão.
+ *  A lista se parte nela em duas, como os grupos da referência, que se separam fora da lista. */
+export type SidebarEntry = SidebarItem | "separator";
 export type SidebarVariant = "floating" | "flush" | "plain";
 export type SidebarScrollbar = "hover" | "visible";
 export type SidebarPlacement = "left" | "right";
-export declare function Sidebar({ items, current, collapsed, variant, placement, scrollbar, label, header, footer, children, className, onClick, ...props }: HTMLAttributes<HTMLElement> & RefAttributes<HTMLElement> & {
-    items?: SidebarItem[];
+export type SidebarCollapsible = "icon" | "capsule" | "offcanvas";
+export type SidebarIndicator = "brand" | "segment" | "segment-dot" | "segment-line" | "subtle";
+export interface SidebarState {
+    /** Recolhida agora. */
+    collapsed: boolean;
+    setCollapsed: (collapsed: boolean) => void;
+    toggle: () => void;
+    /** O jeito de recolher que o provedor passa à lateral. */
+    collapsible: SidebarCollapsible;
+    /** O `id` da lateral: o botão de recolher aponta para ela (`aria-controls`). */
+    id: string;
+}
+/** O estado da lateral: dentro de um `Sidebar.Provider` ou de um `AppShell` com `sidebarCollapsible`. Fora deles, `null`. */
+export declare function useSidebar(): SidebarState | null;
+declare function SidebarProvider({ collapsed, defaultCollapsed, onCollapsedChange, collapsible, shortcut, id, children }: {
+    /** Recolhida (controlado). */
+    collapsed?: boolean;
+    defaultCollapsed?: boolean;
+    onCollapsedChange?: (collapsed: boolean) => void;
+    /** O jeito de recolher (4-A). Padrão: `icon`, a trilha. */
+    collapsible?: SidebarCollapsible;
+    /** O atalho Ctrl+B (Cmd+B no Mac). Padrão: ligado, como na referência. */
+    shortcut?: boolean;
+    /** O `id` da lateral. Sem ele, um gerado. */
+    id?: string;
+    children?: ReactNode;
+}): React.JSX.Element;
+declare function SidebarToggle({ variant, className, onClick, ...props }: Omit<IconButtonProps, "icon" | "label" | "variant" | "children"> & {
+    variant?: "icon" | "item";
+}): React.JSX.Element | null;
+export declare function Sidebar({ items, current, collapsed, collapsible, indicator, panel, variant, placement, scrollbar, label, header, footer, children, className, onClick, id, ...props }: HTMLAttributes<HTMLElement> & RefAttributes<HTMLElement> & {
+    items?: SidebarEntry[];
     current?: string;
     collapsed?: boolean;
     variant?: SidebarVariant;
     placement?: SidebarPlacement;
     scrollbar?: SidebarScrollbar;
     label?: string;
+    /** O jeito de recolher (4-A): `icon` (a trilha, o padrão), `capsule` (a trilha em cápsula) ou `offcanvas` (sai da tela).
+     *  Dentro de um `Sidebar.Provider`, vem dele. */
+    collapsible?: SidebarCollapsible;
+    /** O desenho do item atual (4-H): `brand` (o de hoje), `segment`, `segment-dot`, `segment-line` ou `subtle`. */
+    indicator?: SidebarIndicator;
+    /** A trilha das seções com o painel (4-F e 4-G): os itens do primeiro nível viram seções, e a lista da seção mora num
+     *  painel — `docked`, ao lado da trilha (recolher esconde só o painel), ou `overlay`, por cima, ao lado do ícone. */
+    panel?: "docked" | "overlay";
     /** O topo fixo (4-C): a marca do app (`Sidebar.Brand`), a busca. Não rola com a lista. */
     header?: ReactNode;
     /** O pé fixo (4-C): a pessoa e o sair (`Sidebar.User`), a lista curta (`Sidebar.Nav`), o cartão de destaque. Não rola com a lista. */
@@ -116,15 +171,19 @@ export declare namespace Sidebar {
     export { SidebarUser as User };
     export { SidebarNav as Nav };
     export { SidebarShow as Show };
+    export { SidebarProvider as Provider };
+    export { SidebarToggle as Toggle };
 }
 /** A marca do app no topo da lateral: o `logo` (a letra, o desenho, a imagem), o nome e o subtítulo. `variant="tile"` (o
  *  padrão, a 11 das quinze) põe o logo num quadrinho na cor primária; `plain` (da 8 à 10) é o desenho solto e o nome
  *  grande. Recolhida, fica só o logo. */
-declare function SidebarBrand({ logo, name, description, variant, className, ...props }: Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+declare function SidebarBrand({ logo, name, description, variant, action, className, ...props }: Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
     logo: ReactNode;
     name: ReactNode;
     description?: ReactNode;
     variant?: "tile" | "plain";
+    /** Uma ação ao lado da marca: o `Sidebar.Toggle`. Recolhida, ela desce para baixo do logo. */
+    action?: ReactNode;
 }): React.JSX.Element;
 /** A pessoa no pé da lateral, numa caixinha: a foto (`avatar`), o nome, o papel e a ação (o sair). Recolhida, a foto e a ação, empilhadas. */
 declare function SidebarUser({ avatar, name, description, action, className, ...props }: Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
@@ -135,7 +194,7 @@ declare function SidebarUser({ avatar, name, description, action, className, ...
 }): React.JSX.Element;
 /** Uma segunda lista com a pele da lateral (a do pé: Suporte, Ajustes). `label` é obrigatório: duas listas com o mesmo nome confundem o leitor de tela. */
 declare function SidebarNav({ items, current, label, className, ...props }: Omit<HTMLAttributes<HTMLElement>, "children"> & {
-    items: SidebarItem[];
+    items: SidebarEntry[];
     current?: string;
     label: string;
 }): React.JSX.Element;
@@ -151,7 +210,7 @@ export type BottomNavWidth = "full" | "content";
 export type BottomNavVariantLegacy = "flat" | "surface" | "pill" | "dock";
 export type BottomNavVariantAny = BottomNavVariant | BottomNavVariantLegacy;
 export declare function BottomNav({ items, current, variant, indicator, width, label, className, ...props }: HTMLAttributes<HTMLElement> & RefAttributes<HTMLElement> & {
-    items: SidebarItem[];
+    items: SidebarEntry[];
     current?: string;
     variant?: BottomNavVariantAny;
     indicator?: BottomNavIndicator;

package/dist/navigation-client.js

@@ -8,11 +8,12 @@ import { Tabs as BaseTabs } from "@base-ui/react/tabs";
 import { useDirection } from "@base-ui/react/direction-provider";
 import { Autocomplete as BaseAutocomplete } from "@base-ui/react/autocomplete";
 import { Dialog as BaseDialog } from "@base-ui/react/dialog";
+import { Popover as BasePopover } from "@base-ui/react/popover";
 import { useValorResponsivo } from "./responsivo-runtime.js";
 import { cx, fundirRender, useAureaStrings, usePortalContainer } from "./internal.js";
 import { Kbd } from "./markup.js";
 import { Icon } from "./system.js";
-import { Button } from "./actions.js";
+import { Button, IconButton } from "./actions.js";
 import { Badge, Spinner } from "./feedback.js";
 import { SearchField } from "./inputs.js";
 // `overlays` PASSOU A VIR ANTES de `navigation` no DAG (18/08/2026, MAP.md §DAG). Ele só
@@ -219,30 +220,57 @@ export function TreeView({ items, defaultExpandedIds, onSelect, onExpand, select
         }) }));
     return renderNodes(items, 1);
 }
-function sidebarList(items, ctx, sub, labelledBy) {
-    return _jsx("ul", { className: cx("sidebar-list", sub && "sidebar-sub"), "aria-labelledby": labelledBy, children: items.map(it => {
-            const lid = ctx.baseId + it.id;
-            const filhos = it.items?.length ? it.items : undefined;
-            // Rótulo escondido vira `.sr-only` em vez de sumir do DOM: na lateral recolhida o item
-            // continua tendo nome para quem usa leitor de tela. Ícone sozinho não nomeia nada.
-            const oculto = (no) => ctx.collapsed ? _jsx("span", { className: "sr-only", children: no }) : no;
-            if (filhos && !it.href && !it.onClick && !it.render)
-                return _jsxs("li", { children: [_jsx("p", { id: lid, className: cx("sidebar-group-label", ctx.collapsed && "sr-only"), children: it.label }), sidebarList(filhos, ctx, false, lid)] }, it.id);
-            const ativo = it.id === ctx.current;
-            // O item escolhido desenha o ícone CHEIO (ADR-0053).
-            const miolo = _jsxs(_Fragment, { children: [it.icon && _jsx(Icon, { name: it.icon, weight: ativo ? "fill" : undefined }), _jsx("span", { className: cx("sidebar-label", ctx.collapsed && "sr-only"), children: it.label }), it.badge != null && oculto(it.badge)] });
-            const alvo = it.render
-                ? fundirRender(it.render, { id: lid, className: "sidebar-item", "aria-current": ativo ? "page" : undefined, onClick: it.onClick, children: miolo }, "a")
-                : it.href
-                    ? _jsx("a", { id: lid, href: it.href, className: "sidebar-item", "aria-current": ativo ? "page" : undefined, onClick: it.onClick, children: miolo })
-                    : _jsx("button", { id: lid, type: "button", className: "sidebar-item", "aria-current": ativo ? "page" : undefined, onClick: it.onClick, children: miolo });
-            // NO TRILHO O NOME SÓ EXISTE NO TOOLTIP. Recolhida, a lateral manda o rótulo para `.sr-only`: quem
-            // usa leitor de tela continua ouvindo, e quem ENXERGA fica com um ícone mudo. A referência resolve
-            // isso com tooltip no botão de navegação dela, e é o que falta para um trilho de ícone não virar adivinhação.
-            // Só quando recolhida: com o rótulo visível ao lado, o tooltip repetiria o que já está na tela.
-            // `side="right"` porque a lateral encosta na borda esquerda — para cima o balão sairia do trilho.
-            return _jsxs("li", { children: [ctx.collapsed ? _jsx(Tooltip, { content: it.label, side: "right", children: alvo }) : alvo, filhos && sidebarList(filhos, ctx, true, lid)] }, it.id);
-        }) });
+// A DIVISÓRIA PARTE A LISTA (4-E, 25/10/2026). Na referência ela mora ENTRE grupos, fora das listas — então aqui cada trecho
+// entre duas divisórias é uma lista própria, e a divisória é um vão entre elas. Um `<li>` vazio de papel apagado no meio da
+// lista confundiria a conta de itens do leitor de tela ("3 de 9").
+function sidebarList(entradas, ctx, sub, labelledBy) {
+    const trechos = [[]];
+    for (const e of entradas)
+        e === "separator" ? trechos.push([]) : trechos[trechos.length - 1].push(e);
+    const listas = trechos.filter(t => t.length > 0);
+    const ul = (itens, k) => _jsx("ul", { className: cx("sidebar-list", sub && "sidebar-sub"), "aria-labelledby": labelledBy, children: itens.map(it => sidebarEntry(it, ctx)) }, k);
+    return listas.length < 2 ? ul(listas[0] ?? [], 0) : _jsx(_Fragment, { children: listas.map((t, k) => _jsxs(React.Fragment, { children: [k > 0 && _jsx("div", { className: "sidebar-separator", "aria-hidden": "true" }), ul(t, k)] }, k)) });
+}
+function sidebarEntry(it, ctx) {
+    const lid = ctx.baseId + it.id;
+    const filhos = it.items?.length ? it.items : undefined;
+    // Rótulo escondido vira `.sr-only` em vez de sumir do DOM: na lateral recolhida o item
+    // continua tendo nome para quem usa leitor de tela. Ícone sozinho não nomeia nada.
+    const oculto = (no) => ctx.collapsed ? _jsx("span", { className: "sr-only", children: no }) : no;
+    if (filhos && !it.href && !it.onClick && !it.render)
+        return _jsx(SidebarGroup, { item: it, filhos: filhos, lid: lid, ctx: ctx }, it.id);
+    const ativo = it.id === ctx.current;
+    // O item escolhido desenha o ícone CHEIO (ADR-0053). Com `avatar`, a foto toma o lugar do ícone (4-E).
+    const miolo = _jsxs(_Fragment, { children: [it.avatar ? _jsx(Avatar, { src: it.avatar.src, fallback: it.avatar.fallback, className: "sidebar-avatar" }) : it.icon && _jsx(Icon, { name: it.icon, weight: ativo ? "fill" : undefined }), _jsx("span", { className: cx("sidebar-label", ctx.collapsed && "sr-only"), children: it.label }), it.badge != null && oculto(it.badge)] });
+    const alvo = it.render
+        ? fundirRender(it.render, { id: lid, className: "sidebar-item", "aria-current": ativo ? "page" : undefined, onClick: it.onClick, children: miolo }, "a")
+        : it.href
+            ? _jsx("a", { id: lid, href: it.href, className: "sidebar-item", "aria-current": ativo ? "page" : undefined, onClick: it.onClick, children: miolo })
+            : _jsx("button", { id: lid, type: "button", className: "sidebar-item", "aria-current": ativo ? "page" : undefined, onClick: it.onClick, children: miolo });
+    // NO TRILHO O NOME SÓ EXISTE NO TOOLTIP. Recolhida, a lateral manda o rótulo para `.sr-only`: quem
+    // usa leitor de tela continua ouvindo, e quem ENXERGA fica com um ícone mudo. A referência resolve
+    // isso com tooltip no botão de navegação dela, e é o que falta para um trilho de ícone não virar adivinhação.
+    // Só quando recolhida: com o rótulo visível ao lado, o tooltip repetiria o que já está na tela.
+    // `side="right"` porque a lateral encosta na borda esquerda — para cima o balão sairia do trilho.
+    // A SUBLISTA SOME NA TRILHA (2-A, o achado 13 do item 106): recolhido, o subitem sem ícone virava um botão vazio. A
+    // referência esconde a sublista quando a lateral recolhe; o item pai continua, com o nome na dica.
+    const acao = it.action != null && !ctx.collapsed;
+    return _jsxs("li", { className: cx(acao && "sidebar-item-with-action"), children: [ctx.collapsed ? _jsx(Tooltip, { content: it.label, side: "right", children: alvo }) : alvo, acao && _jsx("span", { className: "sidebar-item-action", children: it.action }), filhos && !ctx.collapsed && sidebarList(filhos, ctx, true, lid)] }, it.id);
+}
+// O GRUPO QUE DOBRA (4-D, 25/10/2026). O nome do grupo vira o botão de abrir e fechar — o padrão de divulgação (o mesmo
+// do `Collapsible`): `aria-expanded` no botão e `aria-controls` na lista, que fica no DOM com `hidden` quando fechada. A
+// seta aponta para baixo aberto e para o fim da linha fechado, como a do grupo que dobra da referência principal. A ação do grupo (o "+") fica ao lado do nome. Recolhida, o
+// nome vai para o leitor de tela e a lista aparece inteira, como o grupo de sempre: na trilha não há onde dobrar.
+function SidebarGroup({ item, filhos, lid, ctx }) {
+    const [aberto, setAberto] = React.useState(item.defaultOpen ?? true);
+    const direita = useDirection() === "rtl";
+    const dobra = !!item.collapsible && !ctx.collapsed;
+    const acao = item.action != null && !ctx.collapsed;
+    const nome = dobra
+        ? _jsxs("button", { id: lid, type: "button", className: "sidebar-group-label sidebar-group-toggle", "aria-expanded": aberto, "aria-controls": lid + "-lista", onClick: () => setAberto(v => !v), children: [_jsx("span", { children: item.label }), _jsx(Icon, { name: aberto ? "caret-down" : direita ? "caret-left" : "caret-right", size: "sm", className: "sidebar-group-caret" })] })
+        : _jsx("p", { id: lid, className: cx("sidebar-group-label", ctx.collapsed && "sr-only"), children: item.label });
+    const lista = sidebarList(filhos, ctx, false, lid);
+    return _jsxs("li", { children: [acao || dobra ? _jsxs("div", { className: "sidebar-group-head", children: [nome, acao && _jsx("span", { className: "sidebar-group-action", children: item.action })] }) : nome, dobra ? _jsx("div", { id: lid + "-lista", hidden: !aberto, children: lista }) : lista] });
 }
 // A GAVETA FECHA AO ESCOLHER (A-06, 23/09/2026). Abaixo de lg a lateral do `AppShell` é popover,
 // e a biblioteca a abria e NUNCA a fechava por código: `hidePopover` tinha zero ocorrências. O
@@ -271,22 +299,121 @@ function fecharGavetaAoEscolher(e) {
 // `Sidebar.Nav`, `Sidebar.Show`) sabem se a lateral está recolhida por este contexto, interno: o estado de recolher
 // com gancho, para o app, é o 4-B.
 const SidebarContext = React.createContext({ collapsed: false });
-export function Sidebar({ items, current, collapsed, variant = "floating", placement = "left", scrollbar = "hover", label, header, footer, children, className, onClick, ...props }) {
+const SidebarStateContext = React.createContext(null);
+/** O estado da lateral: dentro de um `Sidebar.Provider` ou de um `AppShell` com `sidebarCollapsible`. Fora deles, `null`. */
+export function useSidebar() { return React.useContext(SidebarStateContext); }
+// O ATALHO, como o da referência: Ctrl+B, e Cmd+B no Mac. A DIVERGÊNCIA, com o motivo: na referência ele vale até dentro de um
+// campo, e rouba o negrito de quem escreve num editor; aqui ele não age onde se digita.
+const ONDE_SE_DIGITA = "input,textarea,select,[contenteditable]:not([contenteditable=false])";
+function SidebarProvider({ collapsed, defaultCollapsed = false, onCollapsedChange, collapsible = "icon", shortcut = true, id, children }) {
+    const [interno, setInterno] = React.useState(defaultCollapsed);
+    const controlado = collapsed !== undefined;
+    const valor = controlado ? !!collapsed : interno;
+    const gerado = React.useId();
+    const aviso = useRef(onCollapsedChange);
+    aviso.current = onCollapsedChange;
+    const setCollapsed = React.useCallback((v) => { if (!controlado)
+        setInterno(v); aviso.current?.(v); }, [controlado]);
+    const toggle = React.useCallback(() => setCollapsed(!valor), [setCollapsed, valor]);
+    const alternar = useRef(toggle);
+    alternar.current = toggle;
+    React.useEffect(() => {
+        if (!shortcut || typeof window === "undefined")
+            return;
+        const f = (e) => {
+            if (e.defaultPrevented || e.altKey || e.shiftKey || !(e.ctrlKey || e.metaKey) || e.key.toLowerCase() !== "b")
+                return;
+            if (e.target?.closest?.(ONDE_SE_DIGITA))
+                return;
+            e.preventDefault();
+            alternar.current();
+        };
+        window.addEventListener("keydown", f);
+        return () => window.removeEventListener("keydown", f);
+    }, [shortcut]);
+    const estado = React.useMemo(() => ({ collapsed: valor, setCollapsed, toggle, collapsible, id: id ?? "aurea-sidebar" + gerado.replace(/:/g, "") }), [valor, setCollapsed, toggle, collapsible, id, gerado]);
+    return _jsx(SidebarStateContext.Provider, { value: estado, children: children });
+}
+// O BOTÃO DE RECOLHER EM QUALQUER LUGAR (4-B). `icon`: o botão de ícone das quinze (o desenho de lateral, sem fundo) — ao lado
+// do título (1 e 12) ou dentro da lateral, ao lado da marca (13 a 15). `item`: uma linha da lista, "Recolher o menu", no pé da
+// lateral (a 11). Fora de um provedor, não desenha nada.
+// O `variant` aqui é o jeito do botão ("icon" ou "item"); a aparência é sempre a do botão fantasma, como o das quinze.
+function SidebarToggle({ variant = "icon", className, onClick, ...props }) {
+    const estado = React.useContext(SidebarStateContext);
+    const { collapsed } = React.useContext(SidebarContext);
+    const s = useAureaStrings();
+    if (!estado)
+        return null;
+    const rotulo = estado.collapsed ? s.sidebarExpand : s.sidebarCollapse;
+    const comum = { "aria-expanded": !estado.collapsed, "aria-controls": estado.id, onClick: (e) => { onClick?.(e); if (!e.defaultPrevented)
+            estado.toggle(); } };
+    if (variant === "item") {
+        // A linha é um botão do HTML: o que só o `IconButton` entende (tamanho, aparência, ocupado) não passa para ele.
+        const { size: _t, appearance: _a, tone: _o, loading: _l, leadingIcon: _li, trailingIcon: _ti, href: _h, fullWidth: _f, quiet: _q, grow: _g, render: _r, target: _tg, rel: _rl, download: _d, pressed: _p, share: _s, kbd: _k, ...html } = props;
+        const linha = _jsxs("button", { type: "button", ...html, ...comum, className: cx("sidebar-item", "sidebar-toggle-item", className), children: [_jsx(Icon, { name: "sidebar-simple" }), _jsx("span", { className: cx("sidebar-label", collapsed && "sr-only"), children: rotulo })] });
+        return collapsed ? _jsx(Tooltip, { content: rotulo, side: "right", children: linha }) : linha;
+    }
+    return _jsx(IconButton, { ...props, ...comum, className: cx("sidebar-collapse-trigger", className), icon: "sidebar-simple", label: rotulo });
+}
+// A TRILHA DAS SEÇÕES E O PAINEL (4-F e 4-G, 25/10/2026 — as 6 e 7 das quinze). Com `panel`, os itens do primeiro nível são
+// SEÇÕES: a trilha mostra o ícone de cada uma, e a lista da seção mora num painel. `docked` (a 6): o painel fica ao lado da
+// trilha, e recolher a lateral esconde só o painel. `overlay` (a 7): o painel abre POR CIMA, ao lado do ícone, numa janelinha
+// que segura o foco e fecha com o Esc ou com um clique fora (a janelinha da Aurea, o motor dela). A referência faz a 6 com duas
+// laterais lado a lado (a trilha que escolhe e a lista da escolhida); a 7 não tem nela — vem da bancada das quinze.
+// A seção da página atual leva `aria-current="true"` (a "atual de um conjunto"), e não `page`: ela não é a página.
+const contem = (it, id) => !!id && (it.id === id || !!it.items?.some(f => f !== "separator" && contem(f, id)));
+function SidebarSectionButton({ sec, ctx, aberta, painelId, onEscolher, recolhida }) {
+    return _jsx(Tooltip, { content: sec.label, side: "right", children: _jsxs("button", { type: "button", className: "sidebar-item", "aria-current": contem(sec, ctx.current) ? "true" : undefined, "aria-expanded": !recolhida && aberta, "aria-controls": painelId, onClick: onEscolher, children: [sec.avatar ? _jsx(Avatar, { src: sec.avatar.src, fallback: sec.avatar.fallback, className: "sidebar-avatar" }) : sec.icon && _jsx(Icon, { name: sec.icon, weight: contem(sec, ctx.current) ? "fill" : undefined }), _jsx("span", { className: "sidebar-label sr-only", children: sec.label })] }) });
+}
+function SidebarSectionFlyout({ sec, ctx }) {
+    const portal = usePortalContainer();
+    const atual = contem(sec, ctx.current);
+    const tituloId = ctx.baseId + sec.id + "-titulo";
+    return _jsxs(BasePopover.Root, { children: [_jsx(Tooltip, { content: sec.label, side: "right", children: _jsxs(BasePopover.Trigger, { render: _jsx("button", { type: "button", className: "sidebar-item", "aria-current": atual ? "true" : undefined }), children: [sec.avatar ? _jsx(Avatar, { src: sec.avatar.src, fallback: sec.avatar.fallback, className: "sidebar-avatar" }) : sec.icon && _jsx(Icon, { name: sec.icon, weight: atual ? "fill" : undefined }), _jsx("span", { className: "sidebar-label sr-only", children: sec.label })] }) }), _jsx(BasePopover.Portal, { container: portal, children: _jsx(BasePopover.Positioner, { className: "positioner", side: "right", align: "start", sideOffset: 8, children: _jsxs(BasePopover.Popup, { className: "popover sidebar-flyout", "aria-labelledby": tituloId, children: [_jsx("p", { id: tituloId, className: "sidebar-panel-title", children: sec.label }), _jsx("nav", { className: "sidebar-nav", "aria-labelledby": tituloId, children: sidebarList(sec.items ?? [], { ...ctx, collapsed: false }) })] }) }) })] });
+}
+export function Sidebar({ items, current, collapsed, collapsible, indicator = "brand", panel, variant = "floating", placement = "left", scrollbar = "hover", label, header, footer, children, className, onClick, id, ...props }) {
     const s = useAureaStrings();
     const baseId = React.useId();
-    const lista = items && items.length > 0 && _jsx("nav", { className: "sidebar-nav", "aria-label": label ?? s.sidebarLabel, children: sidebarList(items, { baseId, current, collapsed }) });
+    // Dentro de um provedor, a lateral segue o estado dele; a prop escrita ganha (quem escreveu as duas quis a prop).
+    const estado = React.useContext(SidebarStateContext);
+    const recolhida = collapsed ?? estado?.collapsed ?? false;
+    const forma = collapsible ?? estado?.collapsible ?? "icon";
+    const lista = items && items.length > 0 && _jsx("nav", { className: "sidebar-nav", "aria-label": label ?? s.sidebarLabel, children: sidebarList(items, { baseId, current, collapsed: recolhida }) });
     const partes = header != null || footer != null;
-    const contexto = React.useMemo(() => ({ collapsed: !!collapsed, current }), [collapsed, current]);
-    return _jsx("aside", { className: cx("sidebar", variant !== "floating" && `sidebar-${variant}`, collapsed && "sidebar-collapsed", placement === "right" && "sidebar-right", scrollbar === "visible" && "sidebar-scrollbar-visible", partes && "sidebar-with-parts", className), "data-placement": placement, onClick: e => { onClick?.(e); fecharGavetaAoEscolher(e); }, ...props, children: _jsx(SidebarContext.Provider, { value: contexto, children: partes
+    const contexto = React.useMemo(() => ({ collapsed: recolhida, current }), [recolhida, current]);
+    const secoes = panel ? (items ?? []).filter((it) => it !== "separator") : [];
+    const [escolhida, setEscolhida] = React.useState(() => secoes.find(x => contem(x, current))?.id ?? secoes[0]?.id);
+    const naTrilha = React.useMemo(() => ({ collapsed: true, current }), [current]);
+    if (panel) {
+        const secao = secoes.find(x => x.id === escolhida) ?? secoes[0];
+        const painelId = baseId.replace(/:/g, "") + "-painel";
+        const ctxTrilha = { baseId, current, collapsed: true };
+        const trilha = _jsx("nav", { className: "sidebar-nav", "aria-label": label ?? s.sidebarLabel, children: _jsx("ul", { className: "sidebar-list", children: secoes.map(sec => _jsx("li", { children: panel === "overlay"
+                        ? _jsx(SidebarSectionFlyout, { sec: sec, ctx: ctxTrilha })
+                        : _jsx(SidebarSectionButton, { sec: sec, ctx: ctxTrilha, aberta: sec.id === secao?.id, painelId: painelId, recolhida: recolhida, onEscolher: () => { setEscolhida(sec.id); if (recolhida)
+                                estado?.setCollapsed(false); } }) }, sec.id)) }) });
+        return _jsxs("aside", { id: id ?? estado?.id, className: cx("sidebar", variant !== "floating" && `sidebar-${variant}`, `sidebar-panel-${panel}`, recolhida && "sidebar-collapsed", indicator !== "brand" && `sidebar-indicator-${indicator}`, placement === "right" && "sidebar-right", scrollbar === "visible" && "sidebar-scrollbar-visible", className), "data-placement": placement, onClick: e => { onClick?.(e); fecharGavetaAoEscolher(e); }, ...props, children: [_jsx("div", { className: "sidebar-rail-box", children: _jsxs(SidebarContext.Provider, { value: naTrilha, children: [header != null && _jsx("div", { className: "sidebar-header", children: header }), _jsxs("div", { className: "sidebar-body", children: [trilha, children] }), footer != null && _jsx("div", { className: "sidebar-footer", children: footer })] }) }), panel === "docked" && secao && _jsxs("div", { className: "sidebar-panel", id: painelId, hidden: recolhida, children: [_jsx("p", { className: "sidebar-panel-title", id: painelId + "-titulo", children: secao.label }), _jsx("nav", { className: "sidebar-nav", "aria-labelledby": painelId + "-titulo", children: sidebarList(secao.items ?? [], { baseId, current, collapsed: false }) })] })] });
+    }
+    return _jsx("aside", { id: id ?? estado?.id, className: cx("sidebar", variant !== "floating" && `sidebar-${variant}`, recolhida && "sidebar-collapsed", forma !== "icon" && `sidebar-collapse-${forma}`, indicator !== "brand" && `sidebar-indicator-${indicator}`, placement === "right" && "sidebar-right", scrollbar === "visible" && "sidebar-scrollbar-visible", partes && "sidebar-with-parts", className), "data-placement": placement, onClick: e => { onClick?.(e); fecharGavetaAoEscolher(e); }, ...props, children: _jsx(SidebarContext.Provider, { value: contexto, children: partes
                 ? _jsxs(_Fragment, { children: [header != null && _jsx("div", { className: "sidebar-header", children: header }), _jsxs("div", { className: "sidebar-body", children: [lista, children] }), footer != null && _jsx("div", { className: "sidebar-footer", children: footer })] })
                 : _jsxs(_Fragment, { children: [lista, children] }) }) });
 }
+// As partes moram LOGO DEPOIS da lateral (as funções sobem no módulo): assim a leitura do check 46 alcança, a partir da
+// `Sidebar`, os ícones fixos delas — o `sidebar-simple` do `Sidebar.Toggle` ficava sem ficha que o alcançasse.
+Sidebar.Brand = SidebarBrand;
+Sidebar.User = SidebarUser;
+Sidebar.Nav = SidebarNav;
+Sidebar.Show = SidebarShow;
+Sidebar.Provider = SidebarProvider;
+Sidebar.Toggle = SidebarToggle;
 /** A marca do app no topo da lateral: o `logo` (a letra, o desenho, a imagem), o nome e o subtítulo. `variant="tile"` (o
  *  padrão, a 11 das quinze) põe o logo num quadrinho na cor primária; `plain` (da 8 à 10) é o desenho solto e o nome
  *  grande. Recolhida, fica só o logo. */
-function SidebarBrand({ logo, name, description, variant = "tile", className, ...props }) {
+// `action` (o bloco 2, 0.44.0): o botão de recolher ao lado da marca, dentro da lateral (as 13, 14 e 15 das quinze) — o mesmo
+// lugar que a `Sidebar.User` dá ao "sair". Recolhida, ele desce para baixo do logo.
+function SidebarBrand({ logo, name, description, variant = "tile", action, className, ...props }) {
     const { collapsed } = React.useContext(SidebarContext);
-    return _jsxs("div", { className: cx("sidebar-brand", variant === "plain" && "sidebar-brand-plain", className), ...props, children: [_jsx("span", { className: "sidebar-brand-logo", "aria-hidden": "true", children: logo }), _jsxs("span", { className: cx("sidebar-brand-text", collapsed && "sr-only"), children: [_jsx("strong", { className: "sidebar-brand-name", children: name }), description != null && _jsx("span", { className: "sidebar-brand-description", children: description })] })] });
+    return _jsxs("div", { className: cx("sidebar-brand", variant === "plain" && "sidebar-brand-plain", action != null && "sidebar-brand-with-action", className), ...props, children: [_jsx("span", { className: "sidebar-brand-logo", "aria-hidden": "true", children: logo }), _jsxs("span", { className: cx("sidebar-brand-text", collapsed && "sr-only"), children: [_jsx("strong", { className: "sidebar-brand-name", children: name }), description != null && _jsx("span", { className: "sidebar-brand-description", children: description })] }), action] });
 }
 /** A pessoa no pé da lateral, numa caixinha: a foto (`avatar`), o nome, o papel e a ação (o sair). Recolhida, a foto e a ação, empilhadas. */
 function SidebarUser({ avatar, name, description, action, className, ...props }) {
@@ -304,10 +431,6 @@ function SidebarShow({ when, children }) {
     const { collapsed } = React.useContext(SidebarContext);
     return (when === "collapsed") === collapsed ? _jsx(_Fragment, { children: children }) : null;
 }
-Sidebar.Brand = SidebarBrand;
-Sidebar.User = SidebarUser;
-Sidebar.Nav = SidebarNav;
-Sidebar.Show = SidebarShow;
 const LEGADO = {
     flat: ["edge", "none"], surface: ["floating", "circle"], pill: ["floating", "pill"], dock: ["floating", "circle"]
 };
@@ -316,7 +439,7 @@ export function BottomNav({ items, current, variant = "floating", indicator = "n
     const [layout, marca0] = variant in LEGADO ? LEGADO[variant] : [variant, indicator];
     // O indicador explícito ganha do que o nome legado implica: quem escreveu os dois quis os dois.
     const ind = indicator !== "none" ? indicator : marca0;
-    return _jsx("nav", { className: cx("bottom-nav", layout === "edge" && "bottom-nav-edge", layout !== "edge" && width === "content" && "bottom-nav-content", `bottom-nav-ind-${ind}`, className), "aria-label": label ?? s.bottomNavLabel, ...props, children: items.map(it => {
+    return _jsx("nav", { className: cx("bottom-nav", layout === "edge" && "bottom-nav-edge", layout !== "edge" && width === "content" && "bottom-nav-content", `bottom-nav-ind-${ind}`, className), "aria-label": label ?? s.bottomNavLabel, ...props, children: items.filter((it) => it !== "separator").map(it => {
             const ativo = it.id === current;
             // O CONTADOR PENDURA NO ÍCONE, e é por isso que existe esta caixa. Pendurado no ITEM (a
             // primeira versão), `50%` cai no meio do RÓTULO quando o item é linha — o Victor viu o número

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aurea-uds/react",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "description": "Os componentes React da Aurea UDS. Importe @aurea-uds/fonts/css e @aurea-uds/core/css junto.",
   "keywords": [
     "aurea",