@aurea-uds/react 0.40.1 → 0.42.0

package/dist/layout-client.d.ts

@@ -1,7 +1,9 @@
-import { type HTMLAttributes, type RefAttributes, type ReactNode } from "react";
+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";
-export declare function AppShell({ brand, navigation, navItems, currentNavId, navLabel, topbar, topbarVariant, topbarDivider, topbarTabs, topbarCurrentTab, topbarTabsLabel, layout, sidebarVariant, sidebarScrollbar, sidebarCollapsed, sidebarCollapsible, defaultSidebarCollapsed, onSidebarCollapsedChange, contentVariant, aside, asideLabel, asideVariant, children, className, ...props }: HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement> & {
+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> & {
     brand: ReactNode;
     navigation?: ReactNode;
     navItems?: SidebarItem[];
@@ -13,8 +15,13 @@ export declare function AppShell({ brand, navigation, navItems, currentNavId, na
     sidebarVariant?: SidebarVariant;
     /** O arranjo (lote T, 17/10/2026): `"app"` (o padrão, o de sempre) ou `"docs"`, o da documentação da referência — um
      *  bloco CENTRALIZADO de 1400 com a lateral de 220, o texto e o índice de 268 (de 1280 para cima), a barra de cima de 56
-     *  com a linha das áreas (`topbarTabs`) embaixo. A lateral fica onde a variante dela mandar (`plain`: sem caixa). */
-    layout?: "app" | "docs";
+     *  com a linha das áreas (`topbarTabs`) embaixo. A lateral fica onde a variante dela mandar (`plain`: sem caixa).
+     *  `"sidebar"` (MNT-34, 0.42.0): a lateral até o topo, com a marca (`brand`) no topo dela; a barra de cima só existe se o
+     *  app passar `topbar`, e fica só em cima do conteúdo. Com `sidebarVariant` (flutuante ou de canto), as quatro formas da
+     *  bancada; sem `layout`, a de sempre. */
+    layout?: "app" | "docs" | "sidebar";
+    /** O pé fixo da lateral (4-C): a pessoa e o sair (`Sidebar.User`), a lista curta (`Sidebar.Nav`). Só o meio rola. */
+    sidebarFooter?: ReactNode;
     /** A segunda linha da barra de cima: as áreas do site, com ícone (o `tabs` do `Header`). */
     topbarTabs?: HeaderTab[];
     /** O `id` da área atual da segunda linha. */
@@ -42,9 +49,13 @@ export declare function AppShell({ brand, navigation, navItems, currentNavId, na
     /** AN-01: avisa cada troca — pelo botão, ou pela largura cruzando 1280. Guardar a preferência é do app. */
     onSidebarCollapsedChange?: (collapsed: boolean) => void;
     contentVariant?: "surface" | "plain";
-}): import("react").JSX.Element;
+}): React.JSX.Element;
+export declare namespace AppShell {
+    export { AppShellSidebarToggle as SidebarToggle };
+}
 export type SeparatorSpacing = "none" | "tight" | "normal" | "loose";
 export declare function Separator({ orientation, spacing, className, ...props }: HTMLAttributes<HTMLHRElement> & RefAttributes<HTMLHRElement> & {
     orientation?: Responsive<Orientation>;
     spacing?: SeparatorSpacing;
-}): import("react").JSX.Element;
+}): React.JSX.Element;
+export {};

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 { useEffect, useRef, useState, useSyncExternalStore } from "react";
+import React, { 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";
@@ -155,9 +155,21 @@ function useLargura(query) {
         return () => mq.removeEventListener?.("change", avisar);
     }, () => typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia(query).matches, () => false);
 }
-export function AppShell({ brand, navigation, navItems, currentNavId, navLabel, topbar, topbarVariant = "floating", topbarDivider, topbarTabs, topbarCurrentTab, topbarTabsLabel, layout = "app", sidebarVariant, sidebarScrollbar, sidebarCollapsed, sidebarCollapsible, defaultSidebarCollapsed, onSidebarCollapsedChange, contentVariant = "surface", aside, asideLabel, asideVariant, children, className, ...props }) {
+// O BOTÃO DE RECOLHER AO LADO DO TÍTULO (MNT-34, 0.42.0) — o desenho das quinze laterais que o Victor aprovou (o botão
+// de ícone, sem fundo, com o desenho de lateral, a 12 do título da página; *"quero o botão de recolher conforme eu tinha
+// 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 });
+}
+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 }) {
     const s = useAureaStrings();
-    const docs = layout === "docs";
+    const docs = layout === "docs", lateral = layout === "sidebar";
     useGavetaFechaNoDesktop(docs);
     const controlado = sidebarCollapsed !== undefined;
     // `null` = ninguém escolheu, e vale a largura.
@@ -196,8 +208,13 @@ 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 _jsxs("div", { className: cx("app-shell", layout === "docs" && "app-shell-docs", topbarVariant === "flush" && "app-shell-flush", sidebarCollapsible && "app-shell-collapsible", aside != null && "app-shell-with-aside", className), ...props, children: [_jsx("a", { className: "skip-link", href: `#${SHELL_MAIN_ID}`, children: s.skipToContent }), _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 && _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, 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" })] }) }), _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 })] });
+    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
+                    ? _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 })
+                                : _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 })] }) });
 }
+AppShell.SidebarToggle = AppShellSidebarToggle;
 export function Separator({ orientation, spacing = "none", className, ...props }) {
     const ancora = useRef(null);
     const resolvida = useValorResponsivo(orientation, "horizontal", ancora);

package/dist/navigation-client.d.ts

@@ -98,7 +98,7 @@ export interface SidebarItem {
 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, children, className, onClick, ...props }: HTMLAttributes<HTMLElement> & RefAttributes<HTMLElement> & {
+export declare function Sidebar({ items, current, collapsed, variant, placement, scrollbar, label, header, footer, children, className, onClick, ...props }: HTMLAttributes<HTMLElement> & RefAttributes<HTMLElement> & {
     items?: SidebarItem[];
     current?: string;
     collapsed?: boolean;
@@ -106,7 +106,44 @@ export declare function Sidebar({ items, current, collapsed, variant, placement,
     placement?: SidebarPlacement;
     scrollbar?: SidebarScrollbar;
     label?: string;
+    /** 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. */
+    footer?: ReactNode;
 }): React.JSX.Element;
+export declare namespace Sidebar {
+    export { SidebarBrand as Brand };
+    export { SidebarUser as User };
+    export { SidebarNav as Nav };
+    export { SidebarShow as Show };
+}
+/** 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"> & {
+    logo: ReactNode;
+    name: ReactNode;
+    description?: ReactNode;
+    variant?: "tile" | "plain";
+}): 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"> & {
+    avatar: ReactNode;
+    name: ReactNode;
+    description?: ReactNode;
+    action?: ReactNode;
+}): 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[];
+    current?: string;
+    label: string;
+}): React.JSX.Element;
+/** O que só aparece com a lateral aberta (`when="expanded"`: a busca, o cartão de destaque) ou só recolhida (`when="collapsed"`: o botão da lupa). */
+declare function SidebarShow({ when, children }: {
+    when: "expanded" | "collapsed";
+    children?: ReactNode;
+}): React.JSX.Element | null;
 export type BottomNavVariant = "floating" | "edge";
 export type BottomNavIndicator = "none" | "subtle" | "pill" | "circle" | "circle-raised" | "circle-bold" | "circle-outline" | "capsule" | "expand";
 export type BottomNavWidth = "full" | "content";
@@ -177,3 +214,4 @@ export declare function CommandPaletteShell({ open, query, onQueryChange, onClos
     label?: string;
     children?: ReactNode;
 }): React.JSX.Element;
+export {};

package/dist/navigation-client.js

@@ -265,11 +265,49 @@ function fecharGavetaAoEscolher(e) {
     }
     catch { /* motor sem popover: não há gaveta */ }
 }
-export function Sidebar({ items, current, collapsed, variant = "floating", placement = "left", scrollbar = "hover", label, children, className, onClick, ...props }) {
+// O TOPO E O PÉ FIXOS (4-C, o item 107 — as quinze laterais aprovadas pelo Victor em 21/10/2026, e o PV-15 de um
+// segundo app). `header` e `footer` ficam presos; só o meio (a lista e o que vier em `children`) rola. Sem eles, a
+// lateral continua a caixa de sempre — o mesmo HTML. As partes que moram neles (`Sidebar.Brand`, `Sidebar.User`,
+// `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 s = useAureaStrings();
     const baseId = React.useId();
-    return _jsxs("aside", { className: cx("sidebar", variant !== "floating" && `sidebar-${variant}`, collapsed && "sidebar-collapsed", placement === "right" && "sidebar-right", scrollbar === "visible" && "sidebar-scrollbar-visible", className), "data-placement": placement, onClick: e => { onClick?.(e); fecharGavetaAoEscolher(e); }, ...props, children: [items && items.length > 0 && _jsx("nav", { className: "sidebar-nav", "aria-label": label ?? s.sidebarLabel, children: sidebarList(items, { baseId, current, collapsed }) }), children] });
+    const lista = items && items.length > 0 && _jsx("nav", { className: "sidebar-nav", "aria-label": label ?? s.sidebarLabel, children: sidebarList(items, { baseId, current, collapsed }) });
+    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
+                ? _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] }) }) });
 }
+/** 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 }) {
+    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 })] })] });
+}
+/** 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 }) {
+    const { collapsed } = React.useContext(SidebarContext);
+    return _jsxs("div", { className: cx("sidebar-user", className), ...props, children: [avatar, _jsxs("span", { className: cx("sidebar-user-text", collapsed && "sr-only"), children: [_jsx("strong", { className: "sidebar-user-name", children: name }), description != null && _jsx("span", { className: "sidebar-user-description", children: description })] }), action] });
+}
+/** 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. */
+function SidebarNav({ items, current, label, className, ...props }) {
+    const ctx = React.useContext(SidebarContext);
+    const baseId = React.useId();
+    return _jsx("nav", { className: cx("sidebar-nav", className), "aria-label": label, ...props, children: sidebarList(items, { baseId, current: current ?? ctx.current, collapsed: ctx.collapsed }) });
+}
+/** O que só aparece com a lateral aberta (`when="expanded"`: a busca, o cartão de destaque) ou só recolhida (`when="collapsed"`: o botão da lupa). */
+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"]
 };

package/package.json

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