@aurea-uds/react 0.9.0 → 0.10.1

package/README.md

@@ -1,46 +1,46 @@
 # @aurea-uds/react
 
-React components for **Aurea Universal Design System**.
+Os componentes React do **Aurea Universal Design System**.
 
 ```bash
 pnpm add @aurea-uds/react @aurea-uds/core @aurea-uds/fonts @aurea-uds/icons
 ```
 
-## Use
+## Uso
 
-Load the fonts **before** the stylesheet — the core no longer embeds IBM Plex.
+Carregue as fontes **antes** da folha de estilo — o core não embute mais a IBM Plex.
 
 ```js
 import "@aurea-uds/fonts/css";
 import "@aurea-uds/core/css";
-import {AureaProvider, Button} from "@aurea-uds/react";
+import {AureaProvider, Button, ptBR} from "@aurea-uds/react";
 
 export default () => (
-  <AureaProvider spriteUrl="/aurea-icons.svg">
-    <Button variant="primary">Ship it</Button>
+  <AureaProvider spriteUrl="/aurea-icons.svg" strings={ptBR}>
+    <Button variant="primary">Enviar</Button>
   </AureaProvider>
 );
 ```
 
-`spriteUrl` points at the file from `@aurea-uds/icons` — copy it into whatever your app
-serves as static assets. It is configuration, so it belongs to the provider, not to every
-component that draws an icon.
+`spriteUrl` aponta para o arquivo do `@aurea-uds/icons` — copie-o para onde o seu app serve
+arquivos estáticos. É configuração, então mora no provider, e não em cada componente que desenha
+um ícone. As frases padrão são em inglês; `strings={ptBR}` as troca pelas em português.
 
-## Subpath imports
+## Importar por categoria
 
-The barrel works, but each category is also its own entry point, so you can take a part of
-the system without the rest:
+O entry point principal funciona, mas cada categoria é também um entry point próprio, para você levar uma
+parte do sistema sem o resto:
 
 ```js
 import {Button} from "@aurea-uds/react/actions";
 ```
 
-Six modules carry an optional engine and are therefore **outside the barrel** — importing a
-Button must never pull in a peer you did not install:
+Seis módulos trazem uma engine opcional e por isso ficam **fora do entry point principal** — importar um
+`Button` nunca pode puxar uma dependência que você não instalou:
 
-| Import | Needs you to install |
+| Importe | Exige que você instale |
 |---|---|
-| `@aurea-uds/react/code-editor` | `codemirror` and its `@codemirror/*` packages |
+| `@aurea-uds/react/code-editor` | `codemirror` e os pacotes `@codemirror/*` |
 | `@aurea-uds/react/data-grid` | `@tanstack/react-table` |
 | `@aurea-uds/react/qrcode` | `qr` |
 | `@aurea-uds/react/calendar` | `react-day-picker` |
@@ -49,37 +49,37 @@ Button must never pull in a peer you did not install:
 
 ## Hooks
 
-Four of them are public, and they are the part of the API that has **no page in the catalogue** —
-the catalogue documents components, and a hook is not one. Until that changes, this is where they
-are written down.
+Quatro são públicos, e eles são a parte da API que **não tem página no catálogo** — o catálogo
+documenta componentes, e hook não é componente. Enquanto isso não mudar, é aqui que eles estão
+escritos.
 
 ```js
 import {AureaProvider, useToast} from "@aurea-uds/react";
 
-function SaveButton() {
-  const toast = useToast();                                  // inside AureaProvider
+function BotaoSalvar() {
+  const toast = useToast();                                  // dentro do AureaProvider
   return <Button onClick={() => toast.add({
-    title: "Saved",
-    description: "Two files uploaded.",
+    title: "Salvo",
+    description: "Dois arquivos enviados.",
     type: "success",                                         // info | success | warning | danger
-  })}>Save</Button>;
+  })}>Salvar</Button>;
 }
 ```
 
-The stack renders itself: `AureaProvider` already mounts the viewport, so there is no `<Toaster/>`
-to place and no second provider to install.
+A pilha se desenha sozinha: o `AureaProvider` já monta o viewport dos toasts, então não há
+`<Toaster/>` para posicionar nem um segundo provider para instalar.
 
-| Hook | What it gives you |
+| Hook | O que entrega |
 |---|---|
-| `useToast()` | `add({title, description, type})`, plus `close(id)` and the live list. The queue is Base UI's |
-| `useAureaTheme()` | reads and sets **both** axes on `<html>`: `theme` (`dark`/`light`) and `density`. `theme` is `null` on the server — do not draw theme-dependent UI until it isn't |
-| `useAureaStrings()` | the label dictionary, merged with what you passed to the provider |
-| `useSpriteUrl()` | where the icon sprite is being loaded from |
+| `useToast()` | `add({title, description, type})`, mais `close(id)` e a lista viva. A fila é a do Base UI |
+| `useAureaTheme()` | lê e muda **os dois** eixos no `<html>`: `theme` (`dark`/`light`) e `density`. `theme` é `null` no servidor — não desenhe o que depende do tema até ele deixar de ser |
+| `useAureaStrings()` | o dicionário de frases, somado ao que você passou ao provider |
+| `useSpriteUrl()` | de onde o sprite de ícones está sendo carregado |
 
-## Requirements
+## Requisitos
 
-React 19 or later. `ref` is a plain prop in React 19, and the types depend on that.
+React 19 ou mais novo. No React 19 `ref` é prop comum, e os tipos dependem disso.
 
-## Licence
+## Licença
 
 Apache-2.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/dist/navigation-client.js

@@ -195,7 +195,7 @@ function sidebarList(items, ctx, sub, labelledBy) {
 }
 // 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
-// usuário tocava "Filmes", a página trocava por baixo e a gaveta ficava na frente dela. Material 3,
+// usuário tocava "Relatórios", a página trocava por baixo e a gaveta ficava na frente dela. Material 3,
 // Fluent 2 e o guia de gaveta do iOS fecham ao escolher. O fechamento mora NA LATERAL, e não no
 // item, para valer também para a navegação que o consumidor escreve e passa como `children` — o
 // catálogo é um desses. Fora do popover (desktop, lateral solta) o teste de `:popover-open` falha e

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aurea-uds/react",
-  "version": "0.9.0",
-  "description": "React components for Aurea UDS. Import @aurea-uds/fonts/css and @aurea-uds/core/css alongside.",
+  "version": "0.10.1",
+  "description": "Os componentes React da Aurea UDS. Importe @aurea-uds/fonts/css e @aurea-uds/core/css junto.",
   "keywords": [
     "aurea",
     "design-system",
@@ -15,6 +15,10 @@
     "url": "git+https://github.com/victor1mor/aurea-uds.git",
     "directory": "packages/react"
   },
+  "homepage": "https://github.com/victor1mor/aurea-uds/tree/main/packages/react#readme",
+  "bugs": {
+    "url": "https://github.com/victor1mor/aurea-uds/issues"
+  },
   "publishConfig": {
     "access": "public"
   },