@aurea-uds/react 0.9.0 → 0.10.0

package/dist/inputs-client.d.ts

@@ -9,11 +9,17 @@ export interface FieldProps extends HTMLAttributes<HTMLDivElement>, RefAttribute
     label: string;
     hint?: ReactNode;
     error?: ReactNode;
+    /** B-12 (24/09/2026): texto de ajuda que precisa de uma FRASE — mora embaixo do controle, onde
+     *  cabe, e não divide a linha do rótulo. O `hint` continua o que é: nota curta ao lado do rótulo
+     *  ("opcional", "em MB"). É o lugar do `Description` do HeroUI e da `description` que o
+     *  `Checkbox` desta casa já tem. Entra no `aria-describedby` na ordem da tela: hint, descrição,
+     *  erro. */
+    description?: ReactNode;
     name?: string;
     orientation?: Responsive<FieldOrientation>;
     labelWidth?: FieldLabelWidth;
 }
-export declare function Field({ label, hint, error, children, className, id, name, orientation, labelWidth, style, ...props }: FieldProps): React.JSX.Element;
+export declare function Field({ label, hint, description, error, children, className, id, name, orientation, labelWidth, style, ...props }: FieldProps): React.JSX.Element;
 export declare function Form({ errors, onSubmit, children, className, ...props }: Omit<React.FormHTMLAttributes<HTMLFormElement>, "onSubmit"> & RefAttributes<HTMLFormElement> & {
     errors?: Record<string, string | string[]>;
     onSubmit?: (values: Record<string, unknown>) => void;

package/dist/inputs-client.js

@@ -79,7 +79,7 @@ function elementoRotulavel(tipo) {
     // regra que os outros: recebe `id` e espalha `...props` no `Input`, que é o nó focal.
     return [Input, Select, Textarea, SearchField, PasswordField, Checkbox, Radio, Switch, Range, Combobox, MultiCombobox].includes(tipo);
 }
-export function Field({ label, hint, error, children, className, id, name, orientation, labelWidth, style, ...props }) {
+export function Field({ label, hint, description, error, children, className, id, name, orientation, labelWidth, style, ...props }) {
     const auto = React.useId();
     // Fragment não cria nó no DOM. Um Fragment com um só controle é só sintaxe; com vários,
     // Field precisa voltar para grupo em vez de pendurar `htmlFor` num id que nunca existirá.
@@ -100,8 +100,9 @@ export function Field({ label, hint, error, children, className, id, name, orien
     const idControle = unico?.props.id ?? id ?? `${auto}-control`;
     const idRotulo = `${auto}-label`;
     const idHint = hint ? `${auto}-hint` : undefined;
+    const idDescricao = description ? `${auto}-description` : undefined;
     const idErro = error ? `${auto}-error` : undefined;
-    const descrito = [idHint, idErro].filter(Boolean).join(" ") || undefined;
+    const descrito = [idHint, idDescricao, idErro].filter(Boolean).join(" ") || undefined;
     // As chaves de aria só entram quando têm VALOR. Passar `undefined` explícito não é o mesmo que
     // não passar: quando o filho vira `Field.Control` do motor (ramo do `name`), a prop explícita
     // do elemento vence a mesclagem, e o `aria-invalid` que o motor calculou a partir do erro
@@ -124,7 +125,7 @@ export function Field({ label, hint, error, children, className, id, name, orien
     // árvore de acessibilidade enquanto a frase de erro aparece na tela. Pior que não mostrar.
     const controleFinal = name ? _jsx(BaseField.Control, { render: controle }) : controle;
     const estilo = labelWidth ? { ...style, "--field-label-width": labelWidth === "auto" ? "max-content" : labelWidth } : style;
-    const corpo = _jsxs("div", { className: cx("field", peleDoEixo("field", orientation, "vertical", "field"), className), ...(nomeAqui ? {} : { role: "group", "aria-labelledby": idRotulo, ...(rotulavel ? {} : { "aria-describedby": descrito }) }), style: estilo, ...props, children: [_jsxs("span", { className: "label", children: [nomeAqui ? _jsx("label", { htmlFor: idControle, children: label }) : _jsx("span", { id: idRotulo, children: label }), hint && _jsx("span", { className: "hint", id: idHint, children: hint })] }), controleFinal, error && _jsx("span", { className: "field-error", id: idErro, children: error }), name && _jsx(BaseField.Error, { className: "field-error" })] });
+    const corpo = _jsxs("div", { className: cx("field", peleDoEixo("field", orientation, "vertical", "field"), className), ...(nomeAqui ? {} : { role: "group", "aria-labelledby": idRotulo, ...(rotulavel ? {} : { "aria-describedby": descrito }) }), style: estilo, ...props, children: [_jsxs("span", { className: "label", children: [nomeAqui ? _jsx("label", { htmlFor: idControle, children: label }) : _jsx("span", { id: idRotulo, children: label }), hint && _jsx("span", { className: "hint", id: idHint, children: hint })] }), controleFinal, description && _jsx("span", { className: "field-description", id: idDescricao, children: description }), error && _jsx("span", { className: "field-error", id: idErro, children: error }), name && _jsx(BaseField.Error, { className: "field-error" })] });
     // `Field.Root` do motor entra SÓ quando há `name`: é ele que liga o campo à chave de `errors`
     // do formulário. Ele não desenha nada — é contexto — então a pele não muda.
     return name ? _jsx(BaseField.Root, { name: name, invalid: error ? true : undefined, render: corpo }) : corpo;

package/dist/layout-client.d.ts

@@ -1,7 +1,7 @@
 import { type HTMLAttributes, type RefAttributes, type ReactNode } from "react";
 import { type Orientation, type Responsive } from "./pure.js";
 import { type TopbarVariant, type SidebarVariant, type SidebarItem } from "./navigation.js";
-export declare function AppShell({ brand, navigation, navItems, currentNavId, navLabel, topbar, topbarVariant, sidebarVariant, sidebarCollapsed, children, className, ...props }: HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement> & {
+export declare function AppShell({ brand, navigation, navItems, currentNavId, navLabel, topbar, topbarVariant, topbarDivider, sidebarVariant, sidebarCollapsed, contentVariant, children, className, ...props }: HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement> & {
     brand: ReactNode;
     navigation?: ReactNode;
     navItems?: SidebarItem[];
@@ -9,8 +9,10 @@ export declare function AppShell({ brand, navigation, navItems, currentNavId, na
     navLabel?: string;
     topbar?: ReactNode;
     topbarVariant?: Exclude<TopbarVariant, "pill">;
+    topbarDivider?: boolean;
     sidebarVariant?: SidebarVariant;
     sidebarCollapsed?: boolean;
+    contentVariant?: "surface" | "plain";
 }): import("react").JSX.Element;
 export type SeparatorSpacing = "none" | "tight" | "normal" | "loose";
 export declare function Separator({ orientation, spacing, className, ...props }: HTMLAttributes<HTMLHRElement> & RefAttributes<HTMLHRElement> & {

package/dist/layout-client.js

@@ -116,10 +116,14 @@ function useGavetaFechaNoDesktop() {
 // texto ("8.174" virava "8.17"), medido num app real a 1400px. `navItems`/`currentNavId` vão para o
 // Sidebar que o shell já cria, e a caixa dupla deixa de ser o único caminho. `navigation` continua
 // valendo para quem escreve a navegação à mão, e as duas se somam: a lista vem antes.
-export function AppShell({ brand, navigation, navItems, currentNavId, navLabel, topbar, topbarVariant = "floating", sidebarVariant, sidebarCollapsed, children, className, ...props }) {
+// B-10 (24/09/2026): `contentVariant="plain"` tira a caixa do `.content`. Ela é um cartão (mesmo
+// fundo, borda e raio do `.card`), e todo `Card` lá dentro virava caixa dentro de caixa igual — um
+// app gastou 14 `!important` para apagá-la. `surface`, a caixa, continua o padrão.
+// B-07: `topbarDivider` repassa a linha de baixo para a barra `flush` que o shell monta.
+export function AppShell({ brand, navigation, navItems, currentNavId, navLabel, topbar, topbarVariant = "floating", topbarDivider, sidebarVariant, sidebarCollapsed, contentVariant = "surface", children, className, ...props }) {
     const s = useAureaStrings();
     useGavetaFechaNoDesktop();
-    return _jsxs("div", { className: cx("app-shell", topbarVariant === "flush" && "app-shell-flush", className), ...props, children: [_jsx("a", { className: "skip-link", href: `#${SHELL_MAIN_ID}`, children: s.skipToContent }), _jsx(Topbar, { variant: topbarVariant, brand: _jsxs(_Fragment, { children: [_jsx(IconButton, { className: "nav-toggle", icon: "menu", label: s.navigationToggle, popoverTarget: SHELL_NAV_ID }), brand] }), children: topbar }), _jsx(Sidebar, { id: SHELL_NAV_ID, popover: "auto", variant: sidebarVariant, collapsed: sidebarCollapsed, items: navItems, current: currentNavId, label: navLabel, onToggle: focoDaGaveta, children: navigation }), _jsx("main", { id: SHELL_MAIN_ID, tabIndex: -1, className: "content", children: children })] });
+    return _jsxs("div", { className: cx("app-shell", topbarVariant === "flush" && "app-shell-flush", className), ...props, children: [_jsx("a", { className: "skip-link", href: `#${SHELL_MAIN_ID}`, children: s.skipToContent }), _jsx(Topbar, { variant: topbarVariant, divider: topbarDivider, brand: _jsxs(_Fragment, { children: [_jsx(IconButton, { className: "nav-toggle", icon: "menu", label: s.navigationToggle, popoverTarget: SHELL_NAV_ID }), brand] }), children: topbar }), _jsx(Sidebar, { id: SHELL_NAV_ID, popover: "auto", variant: sidebarVariant, collapsed: sidebarCollapsed, items: navItems, current: currentNavId, label: navLabel, onToggle: focoDaGaveta, children: navigation }), _jsx("main", { id: SHELL_MAIN_ID, tabIndex: -1, className: cx("content", contentVariant === "plain" && "content-plain"), children: children })] });
 }
 export function Separator({ orientation, spacing = "none", className, ...props }) {
     const ancora = useRef(null);

package/dist/markup.d.ts

@@ -6,6 +6,7 @@ export type AvatarSize = "sm" | "md" | "lg";
 export type TopbarVariant = "floating" | "flush" | "pill";
 type CardBase = HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement> & {
     padding?: "normal" | "none";
+    orientation?: "vertical" | "horizontal";
 };
 export type CardProps = CardBase & ({
     variant?: "base" | "raised" | "inset" | "selected" | "danger";
@@ -14,7 +15,15 @@ export type CardProps = CardBase & ({
     variant: "interactive";
     render: ReactElement;
 });
-export declare function Card({ variant, padding, className, render, ...props }: CardProps): ReactElement<unknown, string | React.JSXElementConstructor<any>>;
+export declare function Card({ variant, padding, orientation, className, render, ...props }: CardProps): ReactElement<unknown, string | React.JSXElementConstructor<any>>;
+export declare namespace Card {
+    export { CardMedia as Media };
+}
+/** A mídia do cartão — a primeira das partes da especificação do `Card` (A-14). No vertical,
+ *  primeira filha, ela SANGRA até a borda de cima e dos lados; no horizontal, fica à esquerda com a
+ *  largura de miniatura, dentro do respiro, com o raio que sai da conta da casa (ADR-0033: raio do
+ *  cartão menos o respiro dele). O que vai dentro — `Image`, vídeo — é do app. */
+declare function CardMedia({ className, ...props }: HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>): React.JSX.Element;
 export type LayoutGap = "tight" | "normal" | "loose";
 export type StackAlign = "start" | "center" | "end" | "stretch";
 export type ClusterAlign = "start" | "center" | "end" | "baseline";
@@ -124,9 +133,10 @@ export declare function LogStream({ lines }: {
     }>;
 }): React.JSX.Element;
 export declare function MediaPlayerShell({ children, className, ...props }: HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>): React.JSX.Element;
-export declare function Topbar({ variant, brand, children, className, ...props }: HTMLAttributes<HTMLElement> & RefAttributes<HTMLElement> & {
+export declare function Topbar({ variant, divider, brand, children, className, ...props }: HTMLAttributes<HTMLElement> & RefAttributes<HTMLElement> & {
     variant?: TopbarVariant;
     brand?: ReactNode;
+    divider?: boolean;
 }): React.JSX.Element;
 export declare function Kbd({ children, className, ...props }: HTMLAttributes<HTMLElement> & RefAttributes<HTMLElement>): React.JSX.Element;
 export interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement>, RefAttributes<HTMLTextAreaElement> {

package/dist/markup.js

@@ -37,9 +37,15 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 // tocar motor. Na dúvida, ele NÃO entra — cliente a mais é lento, servidor a mais é quebrado.
 import React, { forwardRef } from "react";
 import { cx, fundirRender, peleDoEixo } from "./pure.js";
-export function Card({ variant = "base", padding = "normal", className, render, ...props }) {
-    return fundirRender(render, { className: cx("card", variant !== "base" && `card-${variant}`, padding === "none" && "card-flush", className), ...props });
+export function Card({ variant = "base", padding = "normal", orientation = "vertical", className, render, ...props }) {
+    return fundirRender(render, { className: cx("card", variant !== "base" && `card-${variant}`, padding === "none" && "card-flush", orientation === "horizontal" && "card-horizontal", className), ...props });
 }
+/** A mídia do cartão — a primeira das partes da especificação do `Card` (A-14). No vertical,
+ *  primeira filha, ela SANGRA até a borda de cima e dos lados; no horizontal, fica à esquerda com a
+ *  largura de miniatura, dentro do respiro, com o raio que sai da conta da casa (ADR-0033: raio do
+ *  cartão menos o respiro dele). O que vai dentro — `Image`, vídeo — é do app. */
+function CardMedia({ className, ...props }) { return _jsx("div", { className: cx("card-media", className), ...props }); }
+Card.Media = CardMedia;
 export function Stack({ gap, align, className, ...props }) { return _jsx("div", { className: cx("stack", gap && gap !== "normal" && `stack-gap-${gap}`, align && align !== "stretch" && `stack-align-${align}`, className), ...props }); }
 export function Cluster({ gap, align, justify, wrap, className, ...props }) { return _jsx("div", { className: cx("cluster", gap && gap !== "normal" && `cluster-gap-${gap}`, align && align !== "center" && `cluster-align-${align}`, justify && justify !== "start" && `cluster-justify-${justify}`, wrap === false && "cluster-nowrap", className), ...props }); }
 export function Grid({ gap, min, columns, className, style, ...props }) {
@@ -99,7 +105,10 @@ export function LogStream({ lines }) { return _jsx("div", { className: "log-stre
 // ── Media ────────────────────────────────────────────────────────────────────────────────────
 export function MediaPlayerShell({ children, className, ...props }) { return _jsx("div", { className: cx("media-player", className), ...props, children: children }); }
 // ── Navigation ───────────────────────────────────────────────────────────────────────────────
-export function Topbar({ variant = "floating", brand, children, className, ...props }) { return _jsxs("header", { className: cx("topbar", `topbar-${variant}`, className), ...props, children: [brand != null && _jsx("div", { className: "brand", children: brand }), children] }); }
+// B-07 (24/09/2026): `divider` põe a linha de baixo na `flush`. Ela é fundo igual ao da página e
+// gruda no topo; sem linha, o conteúdo passa por baixo dela e nada diz onde a barra acaba. Só na
+// `flush`: a `floating` e a `pill` são caixas com borda própria.
+export function Topbar({ variant = "floating", divider, brand, children, className, ...props }) { return _jsxs("header", { className: cx("topbar", `topbar-${variant}`, divider && variant === "flush" && "topbar-divider", className), ...props, children: [brand != null && _jsx("div", { className: "brand", children: brand }), children] }); }
 // ── System / interno ─────────────────────────────────────────────────────────────────────────
 // Kbd — representação de tecla/atalho. <kbd> é o elemento HTML certo; a pele é nossa. Ele já
 // morava fora da casa dele (no `internal.tsx`, por causa do `Button`); agora mora aqui, pelo

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aurea-uds/react",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "React components for Aurea UDS. Import @aurea-uds/fonts/css and @aurea-uds/core/css alongside.",
   "keywords": [
     "aurea",