@studiolxd/brand 46.0.0 → 47.1.0

package/CHANGELOG.md

@@ -7,6 +7,182 @@ El paquete sigue [semver](https://semver.org/lang/es/): **patch** para bug fixes
 regeneración de `dist`, **minor** para componentes/props/variantes/tokens nuevos, **major**
 para breaking changes.
 
+## [47.1.0] — 2026-09-15
+
+> **Minor.** La norma de puntuación de subtítulos y estados vacíos, fijada por escrito en
+> Foundations → Redacción, con el JSDoc de `Hero`, `PageIntro` y `EmptyState` remitiendo a
+> ella. Documentación y ejemplos, sin cambios de comportamiento ni de CSS de por sí — salvo
+> el `fix` suelto que viaja en la misma release: un `Link` dejaba de medir su texto al ser
+> ítem directo de un `Stack align="stretch"`.
+
+### `PageIntro` gana `eyebrow`: la ranura encima del título
+
+Prop nueva, `eyebrow?: ReactNode`: lo que va **encima** del título —una `Tag` de estado,
+una categoría, un `Breadcrumb` corto—, nunca un subtítulo ni una frase larga (para eso
+sigue estando `description`). Con `actions`, el eyebrow se queda en la **columna del
+título**, nunca en la de las acciones: el título y las acciones pasan a compartir fila
+dentro de una nueva `.page-intro__title-group` que agrupa eyebrow y título, y las reglas
+de la fila (ancho flexible, línea base, aire bajo el bloque) se mueven de `.heading` a
+ese grupo. El hueco entre eyebrow y título es `--page-intro-row-gap`, el mismo que ya
+separaba el título de las acciones apiladas — ningún token nuevo. Sin `eyebrow`, el
+marcado es exactamente el de siempre. Story «Con eyebrow» y su test de contrato en
+`Molecules/PageIntro`.
+
+### Redacción: subtítulo y estado vacío terminan en punto
+
+Página nueva, `Foundations/Redacción`: todo subtítulo (`Hero.description`,
+`PageIntro.description`) y toda `EmptyState.description` terminan en punto; el `title` de
+`EmptyState`, los rótulos, los botones y los tags, no. Sin puntos suspensivos ni
+exclamación; el signo de interrogación solo si la frase es una pregunta de verdad. El
+JSDoc de las tres props afectadas remite a la página. `dataTable.empty` del catálogo de
+Storybook (`.storybook/brandMessagesFixture.ts`) llevaba un punto de más: alimenta el
+`title` de `EmptyState` dentro de `DataTable`, y un título no lleva punto.
+
+### Fix: un `Link` directo de un `Stack align="stretch"` no se estira
+
+`Link` fijaba su color, su subrayado y su relleno pero no su ancho: como ítem de un flex en
+columna con `align-items: stretch`, ocupaba todo el ancho del `Stack` y la línea de su
+subrayado cruzaba la página entera —el caso de un «← Volver» sobre un `PageIntro`—. Ahora
+`inline-size: fit-content` en la cara base del enlace (`a:not(.button)`, `.link`): su caja
+vuelve a ser la de su texto, sin tocar el enlace suelto en un párrafo (donde `width` no
+aplica a una caja `inline`) ni el centrado vertical de `Inline` (`align-items: center`),
+que un `align-self` habría descuadrado. Story «El enlace dentro de una columna» en
+`Atoms/Link`, con su test de contrato.
+
+## [47.0.0] — 2026-09-15
+
+> **Major.** Octava familia al proveedor de textos: el cromo de aplicación y la navegación.
+> Catorce espacios nuevos, y con ellos la familia donde más claves ya existían en el
+> catálogo de la suite. Además, los portales dejan de abrirse en la talla equivocada dentro
+> de una página pública, y el `main` de `PublicPageShell` se puede pedir a sangre.
+
+### La navegación lee del proveedor
+
+Catorce espacios nuevos en `BrandMessages`: `menuButton`, `appRoot`, `appShell`, `sidebar`,
+`sidebarNav`, `siteNav`, `siteHeader`, `userMenu`, `orgSwitcher`, `breadcrumb`,
+`tableOfContents`, `prevNextNav`, `publicPageShell` y `onboardingShell`. Mismo orden —**prop
+→ proveedor → error**— y cada texto se lee **donde se pinta**: una barra fuera de un
+`AppShell` no tiene asa y no exige sus dos textos, una navegación sin entradas vacías no
+exige su marca, un menú de cuenta sin contador no exige el plural, un paso sin acciones no
+exige el nombre de su pie.
+
+La frontera se decide por el valor. **Cromo**: el nombre de una región de navegación
+(«Principal», «En esta página», «Migas de pan»), el salto al contenido, qué hace el
+logotipo, la dirección de un par anterior/siguiente. **Contenido**: los ítems de un menú,
+los nombres de las organizaciones, el nombre de la persona, los títulos de destino del
+`PrevNextNav`, el rótulo visible de un índice. `PrevNextNav` es el caso que mejor lo
+enseña: «Anterior» y «Siguiente» son catálogo, pero un par que navega semanas quiere decir
+«Semana anterior» y para eso siguen estando las props, que ganan.
+
+### Tres piezas entran al alcance por arrastre
+
+`MenuButton` es donde vivía el castellano que reenviaban las dos cabeceras: migrarlo deja
+`AppHeader.menuLabel` y `SiteHeader.menuLabel` como **reenvíos puros**, una sola clave en
+vez de tres. `AppRoot` tiene la misma frase de salto que `AppShell` y se habría quedado
+cableada. Y `PublicPageShell` tenía que migrar para que `OnboardingShell.preferencesLabel`
+pudiera ser reenvío puro: es la misma banda y la misma clave.
+
+`Switcher` estaba en la lista y **no entra**: no emite ningún texto propio. Lo nombra la
+etiqueta de su campo.
+
+### Breaking — `MenuButton` abierto dice «cerrar»
+
+El nombre accesible pasa a seguir al estado: cerrado lee `menuButton.open`, abierto lee
+`menuButton.close`. Antes, con el menú abierto el botón seguía llamándose igual salvo que
+el consumidor pasara `closeLabel` a mano, así que la cara de cerrar casi nunca se pintaba.
+Ahora que el catálogo trae las dos, el nombre ya no se queda a medias. **Un test que
+consulte el botón por su nombre con la barra abierta deja de encontrarlo**: es el punto
+donde esto rompe en silencio.
+
+`UserMenu` tenía un texto que ni siquiera era prop —el contador de notificaciones llevaba
+`${count} notificaciones sin leer` escrito en el JSX—. Ahora es `userMenu.unread`, una
+función, y `notifications.unreadCount` de la suite ya la satisface con su plural.
+
+### Los portales heredan la superficie
+
+La v45.1.0 puso los controles en talla `lg` dentro de `.site-shell` por herencia CSS, y
+dejó apuntado lo que no cubría: la lista de un `Select` y el calendario de un `DatePicker`
+los monta un portal en `document.body`, que no es descendiente del bloque. El campo se
+pintaba a 48px/20 y su lista se abría a 40px/16. El tema oscuro no tenía este problema
+porque se activa en `<html>` y cascadea a todo el documento; la superficie de lectura se
+activa a media altura del árbol.
+
+`SiteShell` publica ahora su nodo raíz por `PortalContainerContext`, y todo componente con
+portal lo toma como destino cuando no recibe `container`. La resolución es **prop →
+contexto → `document.body`**, y la prop gana siempre. No hay nada que pasar en cada uso: el
+árbol de React sabe dónde está el shell aunque el árbol del DOM no lo sepa. El nodo viaja
+en **estado y no en una ref**, porque el destino tiene que existir en el render en el que
+el portal se monta — el mismo patrón que `ChatShell` ya usaba para el `container` de su
+cajón. `SiteShell` pasa a ser componente cliente.
+
+Lo consumen por defecto `Select`, `MultiSelect`, `AsyncSelect`, `AsyncMultiSelect`,
+`InputPhone`, `Modal`, `Sheet`, `AppLauncher`, `OrgSwitcher`, `UserMenu` y `Toaster`.
+`Popover`, `Tooltip` y `Menu` **estrenan prop `container`** —son los primitivos
+componibles, y sin ella no había escotilla—, y con ellos heredan sin tocar nada
+`DatePicker`, `DateTimeField`, `TimeSelect`, `TimeField`, `ContextMenu`, `DropdownField`,
+`NotificationButton`, `ConfirmDialog`, `ImageCropDialog`, `AvatarUpload`, `CommandPalette`
+y `Consent`. `FloatingDock` queda intacto: monta su panel dentro de su propia ancla a
+propósito y no pasa por el contexto.
+
+**`AppShell` no provee el contexto, y es deliberado.** La superficie de aplicación es la
+del `:root`, así que `document.body` ya resuelve los mismos valores; meter los portales
+dentro de `.app-shell` —que es `overflow: clip` y de altura fija— solo añadiría riesgo de
+recorte sin arreglar nada. El día que la superficie de aplicación cambie de talla, el
+arreglo es montar ahí el mismo proveedor: una línea.
+
+Los campos `*Field` siguen **sin** reenviar `container`, y también a propósito: obligar a
+cada app a pasar un nodo en cada uso era el problema, no la solución. La escotilla vive en
+el primitivo.
+
+### El `main` de `PublicPageShell` se puede pedir a sangre
+
+`PublicPageShell` montaba su `main` como `Container as="main" space="xl"` fijo. Es lo que
+quiere una página corriente, pero no una **portada**: la que abre con un `Hero` de lado a
+lado no cabía en el molde y tenía que montarse a mano con `SiteShell` + `Container`, que es
+justo lo que el molde único existe para evitar.
+
+El `main` lleva ahora los mismos tres mandos que un `Container` —`mainWidth`, `mainSpace` y
+`mainFlush`—, con el prefijo de la ranura porque el marco tiene cuatro y un `width` pelado
+no diría cuál gobierna. **Los defaults son los de hoy** (`'xl'`, `'xl'`, `false`): quien no
+los toque se pinta exactamente igual, así que esta parte no es breaking. Una portada pide
+`mainWidth="full" mainSpace="none" mainFlush` y apila secciones, poniendo su propio
+`Container` a lo que quiera columna.
+
+El `main` sigue siendo el `main`, con su `id` y su `tabIndex`, así que el enlace de salto al
+contenido llega igual a una portada abierta a sangre.
+
+### Para quien actualice
+
+El catálogo del `BrandMessagesProvider` tiene que crecer con los catorce espacios, o la
+primera pantalla con un `Breadcrumb`, un `AppRoot` o un `MenuButton` **lanza en render**.
+Estas son las claves que hay que aportar:
+
+| Espacio | Claves | Qué es |
+| --- | --- | --- |
+| `menuButton` | `open`, `close` | qué hace el botón de menú, en sus dos caras |
+| `appRoot` | `skipToContent` | el salto al contenido del documento |
+| `appShell` | `skipToContent` | el salto al contenido de la aplicación |
+| `sidebar` | `label`, `resizer`, `resizerValue(width)` | la región, el asa y su ancho hablado |
+| `sidebarNav` | `label`, `empty` | la región y la marca de una entrada sin contenido |
+| `siteNav` | `label` | la región del índice del sitio |
+| `siteHeader` | `logo` | qué hace el logotipo — **lleva la marca dentro** |
+| `userMenu` | `trigger(name)`, `unread(count)` | el botón de cuenta y su contador |
+| `orgSwitcher` | `trigger(name)` | el botón del conmutador de organización |
+| `breadcrumb` | `label` | la región del rastro |
+| `tableOfContents` | `label` | la región del índice de la página |
+| `prevNextNav` | `previous`, `next` | la dirección, no el destino |
+| `publicPageShell` | `preferences` | la banda de idioma y tema |
+| `onboardingShell` | `actions` | el grupo de acciones del pie del alta |
+
+Cuatro de ellas interpolan un dato (`sidebar.resizerValue`, `userMenu.trigger`,
+`userMenu.unread`, `orgSwitcher.trigger`), así que son funciones. `siteHeader.logo` la
+escribe cada producto con su propia marca: el default retirado decía «Studio LXD — ir al
+inicio».
+
+A cambio, dejan de hacer falta para traducir `AppHeader.menuLabel` y `menuCloseLabel`,
+`SiteHeader.menuLabel` y `menuCloseLabel`, y `OnboardingShell.preferencesLabel`: son
+reenvíos puros y siguen existiendo solo como anulación puntual.
+
 ## [46.0.0] — 2026-09-15
 
 > **Major.** Séptima familia al proveedor de textos: los envoltorios de diálogo. `Consent`,

package/dist/_shared/portal-container.js

@@ -0,0 +1,9 @@
+import { createContext as e, useContext as t } from "react";
+//#region src/stories/constants/portal-container.ts
+var n = e(null);
+function r(e) {
+	let r = t(n);
+	return e === void 0 ? r ?? void 0 : e;
+}
+//#endregion
+export { r as n, n as t };

package/dist/_types/atoms/AsyncMultiSelect/AsyncMultiSelect.d.ts

@@ -89,13 +89,14 @@ export interface AsyncMultiSelectProps {
      */
     loadingLabel?: string;
     /**
-     * Nodo DOM donde montar el portal del dropdown (reenviado a Base UI
-     * `Portal.container`). Por defecto se monta en `document.body`, que
-     * hereda el tema activado a nivel raíz (`html.dark`/`[data-theme="dark"]`)
-     * sin configuración adicional. Solo hace falta pasarlo cuando el
-     * AsyncMultiSelect vive dentro de un `.surface-dark` **anidado** (no en
-     * la raíz), ya que ese contexto no llega a `document.body` por la
-     * cascada.
+     * Nodo DOM donde montar el portal del dropdown (reenviado a Base UI `Portal.container`).
+     * Por defecto, el nodo de la superficie que llegue por contexto:
+     * `SiteShell` publica el suyo, de modo que la capa hereda la talla de la
+     * superficie pública en vez de abrirse a la de aplicación. Si no hay
+     * superficie, `document.body` — que ya hereda el tema activado en la raíz
+     * (`html.dark`/`[data-theme="dark"]`) sin configuración adicional. Pásalo
+     * solo para llevar la capa a otro sitio: un `.surface-dark` **anidado**, el
+     * cajón de un shell propio. Gana siempre.
      */
     container?: React.ComponentPropsWithoutRef<typeof BasePopover.Portal>['container'];
 }

package/dist/_types/atoms/AsyncSelect/AsyncSelect.d.ts

@@ -78,12 +78,14 @@ export interface AsyncSelectProps {
      */
     clearLabel?: string;
     /**
-     * Nodo DOM donde montar el portal del dropdown (reenviado a Base UI
-     * `Portal.container`). Por defecto se monta en `document.body`, que
-     * hereda el tema activado a nivel raíz (`html.dark`/`[data-theme="dark"]`)
-     * sin configuración adicional. Solo hace falta pasarlo cuando el
-     * AsyncSelect vive dentro de un `.surface-dark` **anidado** (no en la
-     * raíz), ya que ese contexto no llega a `document.body` por la cascada.
+     * Nodo DOM donde montar el portal del dropdown (reenviado a Base UI `Portal.container`).
+     * Por defecto, el nodo de la superficie que llegue por contexto:
+     * `SiteShell` publica el suyo, de modo que la capa hereda la talla de la
+     * superficie pública en vez de abrirse a la de aplicación. Si no hay
+     * superficie, `document.body` — que ya hereda el tema activado en la raíz
+     * (`html.dark`/`[data-theme="dark"]`) sin configuración adicional. Pásalo
+     * solo para llevar la capa a otro sitio: un `.surface-dark` **anidado**, el
+     * cajón de un shell propio. Gana siempre.
      */
     container?: React.ComponentPropsWithoutRef<typeof BasePopover.Portal>['container'];
 }

package/dist/_types/atoms/InputPhone/InputPhone.d.ts

@@ -47,11 +47,14 @@ export interface InputPhoneProps {
     internationalLabel?: string;
     /**
      * Nodo DOM donde montar el portal del dropdown de país (reenviado a
-     * `Select.Portal` de Base UI). Por defecto se monta en `document.body`, que
-     * hereda el tema activado a nivel raíz (`html.dark`/`[data-theme="dark"]`)
-     * sin configuración adicional. Solo hace falta pasarlo cuando el
-     * InputPhone vive dentro de un `.surface-dark` **anidado** (no en la
-     * raíz), ya que ese contexto no llega a `document.body` por la cascada.
+     * `Select.Portal` de Base UI).
+     * Por defecto, el nodo de la superficie que llegue por contexto:
+     * `SiteShell` publica el suyo, de modo que la capa hereda la talla de la
+     * superficie pública en vez de abrirse a la de aplicación. Si no hay
+     * superficie, `document.body` — que ya hereda el tema activado en la raíz
+     * (`html.dark`/`[data-theme="dark"]`) sin configuración adicional. Pásalo
+     * solo para llevar la capa a otro sitio: un `.surface-dark` **anidado**, el
+     * cajón de un shell propio. Gana siempre.
      */
     container?: React.ComponentPropsWithoutRef<typeof BaseSelect.Portal>['container'];
 }

package/dist/_types/atoms/MenuButton/MenuButton.d.ts

@@ -1,11 +1,31 @@
 import { type ComponentPropsWithoutRef } from 'react';
 import './MenuButton.css';
+/**
+ * Los dos textos del botón de menú, y los dos son **cromo**: no dicen de qué
+ * menú son, dicen qué hace el botón. Son los mismos en la cabecera de la
+ * aplicación y en la del sitio, así que van al catálogo una sola vez y las dos
+ * cabeceras los reenvían sin repetir la clave.
+ */
+export interface MenuButtonMessages {
+    /** Nombre accesible del botón con el menú cerrado. */
+    open: string;
+    /** Nombre accesible del botón con el menú abierto. */
+    close: string;
+}
 export interface MenuButtonProps extends Omit<ComponentPropsWithoutRef<'button'>, 'children'> {
     /** Estado del menú que gobierna. Abierto, el glifo `menu` se convierte en `close`. */
     isOpen?: boolean;
-    /** Texto accesible. Dice qué abre, no qué forma tiene. */
+    /**
+     * Texto accesible con el menú cerrado. Dice qué abre, no qué forma tiene.
+     * **Sin default**: sin él, sale de `menuButton.open` del
+     * `BrandMessagesProvider`.
+     */
     label?: string;
-    /** Texto accesible cuando el menú está abierto («Cerrar menú»). Sin él, se usa `label` con `aria-expanded`. */
+    /**
+     * Texto accesible con el menú abierto. **Sin default**: sin él, sale de
+     * `menuButton.close` del `BrandMessagesProvider`. Solo se lee cuando el menú
+     * está abierto: un botón que nunca se abre no exige esa clave.
+     */
     closeLabel?: string;
     /** Talla del botón: un cuadrado de 32, 40 o 48px. En `lg` el glifo mide 48px. */
     size?: 'sm' | 'md' | 'lg';

package/dist/_types/atoms/MultiSelect/MultiSelect.d.ts

@@ -54,12 +54,14 @@ export interface MultiSelectProps {
      */
     removeLabel?: (label: string) => string;
     /**
-     * Nodo DOM donde montar el portal del dropdown (reenviado a Base UI
-     * `Portal.container`). Por defecto se monta en `document.body`, que
-     * hereda el tema activado a nivel raíz (`html.dark`/`[data-theme="dark"]`)
-     * sin configuración adicional. Solo hace falta pasarlo cuando el
-     * MultiSelect vive dentro de un `.surface-dark` **anidado** (no en la
-     * raíz), ya que ese contexto no llega a `document.body` por la cascada.
+     * Nodo DOM donde montar el portal del dropdown (reenviado a Base UI `Portal.container`).
+     * Por defecto, el nodo de la superficie que llegue por contexto:
+     * `SiteShell` publica el suyo, de modo que la capa hereda la talla de la
+     * superficie pública en vez de abrirse a la de aplicación. Si no hay
+     * superficie, `document.body` — que ya hereda el tema activado en la raíz
+     * (`html.dark`/`[data-theme="dark"]`) sin configuración adicional. Pásalo
+     * solo para llevar la capa a otro sitio: un `.surface-dark` **anidado**, el
+     * cajón de un shell propio. Gana siempre.
      */
     container?: React.ComponentPropsWithoutRef<typeof BasePopover.Portal>['container'];
 }

package/dist/_types/atoms/Popover/Popover.d.ts

@@ -54,6 +54,13 @@ export interface PopoverProps {
      * un `ref`, o una función que lo devuelva. Es la prop de Base UI, tal cual.
      */
     initialFocus?: React.ComponentProps<typeof BasePopover.Popup>['initialFocus'];
+    /**
+     * Nodo DOM donde montar el portal. Por defecto, el nodo de la superficie que
+     * llegue por contexto —`SiteShell` publica el suyo, para que la capa herede
+     * la talla de la superficie pública— y, si no hay ninguna, `document.body`.
+     * Pásalo solo para llevar la capa a otro sitio: gana siempre.
+     */
+    container?: HTMLElement | null;
     /** Clase adicional para el panel. */
     className?: string;
 }
@@ -67,4 +74,4 @@ export interface PopoverProps {
  * mantener el panel abierto cuando el clic cae en algo que el motor no
  * reconoce como suyo.
  */
-export declare function Popover({ trigger, children, label, open, defaultOpen, onOpenChange, onPointerDownOutside, onFocusOutside, onEscapeKeyDown, side, align, sideOffset, initialFocus, className, }: PopoverProps): import("react/jsx-runtime").JSX.Element;
+export declare function Popover({ trigger, children, label, open, defaultOpen, onOpenChange, onPointerDownOutside, onFocusOutside, onEscapeKeyDown, side, align, sideOffset, initialFocus, container, className, }: PopoverProps): import("react/jsx-runtime").JSX.Element;

package/dist/_types/atoms/Select/Select.d.ts

@@ -70,13 +70,14 @@ export interface SelectProps {
     /** Estado de error accesible (lo pone el campo). */
     'aria-invalid'?: boolean;
     /**
-     * Nodo DOM donde montar el portal del dropdown (reenviado a `Select.Portal`
-     * de Base UI). Por defecto el portal se monta en `document.body`, que hereda
-     * el tema activado a nivel raíz (`html.dark`/`[data-theme="dark"]`) sin
-     * configuración adicional. Solo hace falta pasar `container` cuando el Select
-     * vive dentro de un `.surface-dark` **anidado** (no en la raíz): ese contexto
-     * no llega a `document.body` por la cascada, así que hay que montar el portal
-     * dentro del propio contenedor con la clase.
+     * Nodo DOM donde montar el portal del dropdown (reenviado a `Select.Portal` de Base UI).
+     * Por defecto, el nodo de la superficie que llegue por contexto:
+     * `SiteShell` publica el suyo, de modo que la capa hereda la talla de la
+     * superficie pública en vez de abrirse a la de aplicación. Si no hay
+     * superficie, `document.body` — que ya hereda el tema activado en la raíz
+     * (`html.dark`/`[data-theme="dark"]`) sin configuración adicional. Pásalo
+     * solo para llevar la capa a otro sitio: un `.surface-dark` **anidado**, el
+     * cajón de un shell propio. Gana siempre.
      */
     container?: SelectPortalContainer;
 }

package/dist/_types/atoms/Tooltip/Tooltip.d.ts

@@ -41,6 +41,13 @@ export interface TooltipProps extends Omit<React.HTMLAttributes<HTMLElement>, 'c
      * @default true
      */
     describe?: boolean;
+    /**
+     * Nodo DOM donde montar el portal. Por defecto, el nodo de la superficie que
+     * llegue por contexto —`SiteShell` publica el suyo, para que la capa herede
+     * la talla de la superficie pública— y, si no hay ninguna, `document.body`.
+     * Pásalo solo para llevar la capa a otro sitio: gana siempre.
+     */
+    container?: HTMLElement | null;
     /** Clase adicional para el **bocadillo** (no para el disparador). */
     className?: string;
 }

package/dist/_types/constants/portal-container.d.ts

@@ -0,0 +1,42 @@
+/**
+ * El nodo donde montan su portal los componentes que abren una capa flotante
+ * —la lista de un `Select`, el calendario de un `DatePicker`, el panel de un
+ * `Popover`, el velo de un `Modal`— cuando no se les pasa `container`.
+ *
+ * **Por qué hace falta.** Un portal monta en `document.body`, que no es
+ * descendiente de `.site-shell`. El tema oscuro sobrevive a eso porque se
+ * activa en `<html>` y cascadea a todo el documento; la **superficie de
+ * lectura** no: `.site-shell` remapea los tokens de texto y pone los controles
+ * en talla `lg` (v45.1.0) desde una clase que está a media altura del árbol.
+ * Resultado antes de esto: el campo se pintaba a 48px/20 y su lista se abría a
+ * 40px/16, fuera del shell.
+ *
+ * **Cómo se arregla.** `SiteShell` publica su nodo raíz por este contexto y
+ * todo componente con portal lo toma como destino por defecto. No hay nada que
+ * pasar en cada uso: el árbol de React ya sabe dónde está el shell aunque el
+ * árbol del DOM no lo sepa. El valor se guarda en **estado**, no en una ref —
+ * el destino tiene que existir en el render en el que el portal se monta, y
+ * una ref no provoca repintado al rellenarse. Es el patrón que `ChatShell` ya
+ * usaba para el `container` de su cajón.
+ *
+ * La prop `container` sigue existiendo y **gana siempre**: es la salida para
+ * quien quiera otro destino (el ancla de `FloatingDock`, un `.surface-dark`
+ * anidado).
+ *
+ * `AppShell` **no** lo provee, y es deliberado: la superficie de aplicación es
+ * la del `:root`, así que `document.body` ya resuelve los mismos valores y
+ * meter los portales dentro de `.app-shell` —que es `overflow: clip` y de
+ * altura fija— solo añadiría riesgo de recorte sin arreglar nada. El día que
+ * la superficie de aplicación cambie de talla, el arreglo es una línea: montar
+ * este mismo proveedor en `AppShell`.
+ */
+export declare const PortalContainerContext: import("react").Context<HTMLElement | null>;
+/**
+ * Resuelve el destino del portal: la prop si el consumidor la pasa, y si no,
+ * el nodo de la superficie que venga por contexto.
+ *
+ * Se llama **siempre**, con o sin prop —es un hook—, y devuelve `undefined`
+ * cuando no hay ni una cosa ni la otra, que es lo que Base UI entiende por
+ * «monta en `document.body`».
+ */
+export declare function usePortalContainer<T>(container: T): T | HTMLElement | undefined;

package/dist/_types/messages/BrandMessages.d.ts

@@ -31,6 +31,20 @@ import type { AppLauncherMessages } from '../molecules/AppLauncher/AppLauncher';
 import type { FloatingDockMessages } from '../sections/FloatingDock/FloatingDock';
 import type { NotificationButtonMessages } from '../molecules/NotificationButton/NotificationButton';
 import type { NotificationPanelMessages } from '../molecules/NotificationPanel/NotificationPanel';
+import type { MenuButtonMessages } from '../atoms/MenuButton/MenuButton';
+import type { AppRootMessages } from '../sections/AppRoot/AppRoot';
+import type { AppShellMessages } from '../sections/AppShell/AppShell';
+import type { SidebarMessages } from '../sections/Sidebar/Sidebar';
+import type { SidebarNavMessages } from '../molecules/SidebarNav/SidebarNav';
+import type { SiteNavMessages } from '../molecules/SiteNav/SiteNav';
+import type { SiteHeaderMessages } from '../sections/SiteHeader/SiteHeader';
+import type { UserMenuMessages } from '../molecules/UserMenu/UserMenu';
+import type { OrgSwitcherMessages } from '../molecules/OrgSwitcher/OrgSwitcher';
+import type { BreadcrumbMessages } from '../molecules/Breadcrumb/Breadcrumb';
+import type { TableOfContentsMessages } from '../molecules/TableOfContents/TableOfContents';
+import type { PrevNextNavMessages } from '../molecules/PrevNextNav/PrevNextNav';
+import type { PublicPageShellMessages } from '../templates/PublicPageShell/PublicPageShell';
+import type { OnboardingShellMessages } from '../templates/OnboardingShell/OnboardingShell';
 /**
  * El contrato de textos de la librería: un espacio por componente, y dentro
  * de cada espacio **todas las claves obligatorias**.
@@ -86,5 +100,19 @@ export interface BrandMessages {
     floatingDock: FloatingDockMessages;
     notificationButton: NotificationButtonMessages;
     notificationPanel: NotificationPanelMessages;
+    menuButton: MenuButtonMessages;
+    appRoot: AppRootMessages;
+    appShell: AppShellMessages;
+    sidebar: SidebarMessages;
+    sidebarNav: SidebarNavMessages;
+    siteNav: SiteNavMessages;
+    siteHeader: SiteHeaderMessages;
+    userMenu: UserMenuMessages;
+    orgSwitcher: OrgSwitcherMessages;
+    breadcrumb: BreadcrumbMessages;
+    tableOfContents: TableOfContentsMessages;
+    prevNextNav: PrevNextNavMessages;
+    publicPageShell: PublicPageShellMessages;
+    onboardingShell: OnboardingShellMessages;
 }
-export type { PaginationMessages, TableMessages, DataTableMessages, InputFieldMessages, PasswordFieldMessages, SelectMessages, MultiSelectMessages, NumberInputMessages, OtpInputMessages, InputPhoneMessages, AsyncSelectMessages, AsyncMultiSelectMessages, DocsSearchMessages, SearchFormMessages, FilterBarMessages, CalendarMessages, DatePickerMessages, TimeSelectMessages, FileUploadMessages, ImageCropDialogMessages, AvatarUploadMessages, ModalMessages, SheetMessages, ConfirmDialogMessages, AlertMessages, BannerMessages, ToasterMessages, ConsentMessages, CommandPaletteMessages, AppLauncherMessages, FloatingDockMessages, NotificationButtonMessages, NotificationPanelMessages, };
+export type { PaginationMessages, TableMessages, DataTableMessages, InputFieldMessages, PasswordFieldMessages, SelectMessages, MultiSelectMessages, NumberInputMessages, OtpInputMessages, InputPhoneMessages, AsyncSelectMessages, AsyncMultiSelectMessages, DocsSearchMessages, SearchFormMessages, FilterBarMessages, CalendarMessages, DatePickerMessages, TimeSelectMessages, FileUploadMessages, ImageCropDialogMessages, AvatarUploadMessages, ModalMessages, SheetMessages, ConfirmDialogMessages, AlertMessages, BannerMessages, ToasterMessages, ConsentMessages, CommandPaletteMessages, AppLauncherMessages, FloatingDockMessages, NotificationButtonMessages, NotificationPanelMessages, MenuButtonMessages, AppRootMessages, AppShellMessages, SidebarMessages, SidebarNavMessages, SiteNavMessages, SiteHeaderMessages, UserMenuMessages, OrgSwitcherMessages, BreadcrumbMessages, TableOfContentsMessages, PrevNextNavMessages, PublicPageShellMessages, OnboardingShellMessages, };

package/dist/_types/messages/index.d.ts

@@ -2,4 +2,4 @@ export { BrandMessagesProvider } from './BrandMessagesProvider';
 export type { BrandMessagesProviderProps } from './BrandMessagesProvider';
 export { useBrandMessages } from './BrandMessagesContext';
 export type { BrandMessagesReader } from './BrandMessagesContext';
-export type { BrandMessages, PaginationMessages, TableMessages, DataTableMessages, InputFieldMessages, PasswordFieldMessages, SelectMessages, MultiSelectMessages, NumberInputMessages, OtpInputMessages, InputPhoneMessages, AsyncSelectMessages, AsyncMultiSelectMessages, DocsSearchMessages, SearchFormMessages, FilterBarMessages, CalendarMessages, DatePickerMessages, TimeSelectMessages, FileUploadMessages, ImageCropDialogMessages, AvatarUploadMessages, ModalMessages, SheetMessages, ConfirmDialogMessages, AlertMessages, BannerMessages, ToasterMessages, ConsentMessages, CommandPaletteMessages, AppLauncherMessages, FloatingDockMessages, NotificationButtonMessages, NotificationPanelMessages, } from './BrandMessages';
+export type { BrandMessages, PaginationMessages, TableMessages, DataTableMessages, InputFieldMessages, PasswordFieldMessages, SelectMessages, MultiSelectMessages, NumberInputMessages, OtpInputMessages, InputPhoneMessages, AsyncSelectMessages, AsyncMultiSelectMessages, DocsSearchMessages, SearchFormMessages, FilterBarMessages, CalendarMessages, DatePickerMessages, TimeSelectMessages, FileUploadMessages, ImageCropDialogMessages, AvatarUploadMessages, ModalMessages, SheetMessages, ConfirmDialogMessages, AlertMessages, BannerMessages, ToasterMessages, ConsentMessages, CommandPaletteMessages, AppLauncherMessages, FloatingDockMessages, NotificationButtonMessages, NotificationPanelMessages, MenuButtonMessages, AppRootMessages, AppShellMessages, SidebarMessages, SidebarNavMessages, SiteNavMessages, SiteHeaderMessages, UserMenuMessages, OrgSwitcherMessages, BreadcrumbMessages, TableOfContentsMessages, PrevNextNavMessages, PublicPageShellMessages, OnboardingShellMessages, } from './BrandMessages';

package/dist/_types/molecules/Breadcrumb/Breadcrumb.d.ts

@@ -14,10 +14,18 @@ export interface BreadcrumbProps {
     renderLink?: (props: BreadcrumbRenderLinkProps) => ReactNode;
     separator?: ReactNode;
     /**
-     * `aria-label` del `<nav>`. Default: «Migas de pan» (castellano).
-     * Una app multiidioma debe pasarlo traducido.
+     * `aria-label` del `<nav>`. **Sin default**: sin él, sale de
+     * `breadcrumb.label` del `BrandMessagesProvider`.
      */
     ariaLabel?: string;
     className?: string;
 }
+/**
+ * El único texto que las migas dicen por su cuenta, y es **cromo**: el nombre de
+ * la región. Los rótulos del rastro son **contenido** y vienen en `items`.
+ */
+export interface BreadcrumbMessages {
+    /** Nombre accesible del `nav`. */
+    label: string;
+}
 export declare function Breadcrumb({ items, renderLink, separator, ariaLabel, className, }: BreadcrumbProps): import("react/jsx-runtime").JSX.Element;

package/dist/_types/molecules/EmptyState/EmptyState.d.ts

@@ -5,7 +5,9 @@ export interface EmptyStateAction {
     href?: string;
 }
 export interface EmptyStateProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {
+    /** El rótulo del estado: sin punto (ver Foundations → Redacción). */
     title: string;
+    /** La frase que lo explica, opcional: termina en punto (ver Foundations → Redacción). */
     description?: string;
     icon?: React.ReactNode;
     action?: EmptyStateAction;

package/dist/_types/molecules/Menu/Menu.d.ts

@@ -29,6 +29,13 @@ export interface MenuProps {
     maxWidth?: string;
     /** Talla de los ítems, la del disparador (32/40/48): el panel desplegado casa con el control plegado, como en el Select. */
     size?: 'sm' | 'md' | 'lg';
+    /**
+     * Nodo DOM donde montar el portal. Por defecto, el nodo de la superficie que
+     * llegue por contexto —`SiteShell` publica el suyo, para que la capa herede
+     * la talla de la superficie pública— y, si no hay ninguna, `document.body`.
+     * Pásalo solo para llevar la capa a otro sitio: gana siempre.
+     */
+    container?: HTMLElement | null;
     className?: string;
 }
 /**
@@ -36,4 +43,4 @@ export interface MenuProps {
  * (tokens `menu.*`) de todos los menús; `ContextMenu`, `UserMenu`,
  * `OrgSwitcher` o `DropdownField` son este menú con un disparador concreto.
  */
-export declare function Menu({ trigger, items, value, onValueChange, renderLink, open, defaultOpen, onOpenChange, openOnHover, hoverDelay, side, align, sideOffset, minWidth, maxWidth, size, className, }: MenuProps): import("react/jsx-runtime").JSX.Element;
+export declare function Menu({ trigger, items, value, onValueChange, renderLink, open, defaultOpen, onOpenChange, openOnHover, hoverDelay, side, align, sideOffset, minWidth, maxWidth, size, container, className, }: MenuProps): import("react/jsx-runtime").JSX.Element;

package/dist/_types/molecules/Modal/Modal.d.ts

@@ -33,12 +33,14 @@ export interface ModalProps extends Omit<React.ComponentPropsWithoutRef<'div'>,
      */
     fallbackTitle?: string;
     /**
-     * Nodo DOM donde montar el portal del modal (reenviado a Base UI
-     * `Portal.container`). Por defecto se monta en `document.body`, que
-     * hereda el tema activado a nivel raíz (`html.dark`/`[data-theme="dark"]`)
-     * sin configuración adicional. Solo hace falta pasarlo cuando el Modal
-     * vive dentro de un `.surface-dark` **anidado** (no en la raíz), ya que
-     * ese contexto no llega a `document.body` por la cascada.
+     * Nodo DOM donde montar el portal del modal (reenviado a Base UI `Portal.container`).
+     * Por defecto, el nodo de la superficie que llegue por contexto:
+     * `SiteShell` publica el suyo, de modo que la capa hereda la talla de la
+     * superficie pública en vez de abrirse a la de aplicación. Si no hay
+     * superficie, `document.body` — que ya hereda el tema activado en la raíz
+     * (`html.dark`/`[data-theme="dark"]`) sin configuración adicional. Pásalo
+     * solo para llevar la capa a otro sitio: un `.surface-dark` **anidado**, el
+     * cajón de un shell propio. Gana siempre.
      */
     container?: React.ComponentPropsWithoutRef<typeof Dialog.Portal>['container'];
     /**

package/dist/_types/molecules/OrgSwitcher/OrgSwitcher.d.ts

@@ -6,8 +6,22 @@ export interface OrgOption {
     name: string;
     logoUrl?: string;
 }
+/**
+ * El único texto que el conmutador dice por su cuenta, y es **cromo**: cómo se
+ * nombra su botón. Interpola la organización activa, así que es una función.
+ * Los nombres de las organizaciones son **contenido** y vienen en
+ * `organizations`.
+ */
+export interface OrgSwitcherMessages {
+    /** Nombre accesible del botón, a partir del nombre de la organización. */
+    trigger: (name: string) => string;
+}
 export interface OrgSwitcherProps {
-    /** Nombre accesible del botón. Por defecto, «Organización: ‹nombre›». */
+    /**
+     * Nombre accesible del botón. **Sin default**: sin él, sale de
+     * `orgSwitcher.trigger` del `BrandMessagesProvider`, que recibe el nombre de
+     * la organización activa.
+     */
     label?: string;
     /** Ocupa todo el ancho disponible (en la Sidebar). Por defecto mide lo que su contenido. */
     block?: boolean;

package/dist/_types/molecules/PageIntro/PageIntro.d.ts

@@ -2,16 +2,21 @@ import type { ReactNode } from 'react';
 import { type HeadingProps } from '../../atoms/Heading/Heading';
 import './PageIntro.css';
 export interface PageIntroProps {
+    /**
+     * Encima del título: una `Tag` de estado, una categoría, un `Breadcrumb`
+     * corto. No es un subtítulo ni acepta una frase larga —para eso está
+     * `description`—, es una pieza pequeña que sitúa la página antes de
+     * nombrarla. Con `actions`, queda en la columna del título, nunca en la
+     * de las acciones.
+     */
+    eyebrow?: ReactNode;
     /** El título de la página: un `Heading` de nivel 1 (o el que diga `level`). */
     title: ReactNode;
     /**
      * La frase bajo el título, opcional: va como entradilla (`Paragraph
-     * size="large"`, un peldaño por encima del cuerpo).
-     *
-     * **Es una frase y termina con puntuación final** —un punto, o el signo que
-     * le toque—: no es un rótulo ni un subtítulo. Sin el punto, el párrafo se
-     * lee como un `Heading` menor y la jerarquía de la cabecera se deshace. Lo
-     * que no llegue a frase o cabe en el título, o va en `children`.
+     * size="large"`, un peldaño por encima del cuerpo). Termina en punto (ver
+     * Foundations → Redacción). Lo que no llegue a frase, o cabe en el título,
+     * o va en `children`.
      */
     description?: ReactNode;
     /** Más texto bajo la frase (otro `Paragraph`, una lista…): mismo aire. */
@@ -45,4 +50,4 @@ export interface PageIntroProps {
  * Con `actions` sirve además de cabecera de una sección dentro de la página
  * (`level={2}`): el título a la izquierda y la acción principal a la derecha.
  */
-export declare function PageIntro({ title, description, actions, level, size, as: Tag, className, children, }: PageIntroProps): import("react/jsx-runtime").JSX.Element;
+export declare function PageIntro({ eyebrow, title, description, actions, level, size, as: Tag, className, children, }: PageIntroProps): import("react/jsx-runtime").JSX.Element;