@studiolxd/brand 49.3.0 → 49.4.0

package/CHANGELOG.md

@@ -7,6 +7,93 @@ 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.
 
+## [49.4.0] — 2026-09-17
+
+> **Minor.** Cuatro huecos que dejó al descubierto la campaña de crudos de bricks: un bocadillo
+> sobre un control apagado, la ranura de acciones de una tarjeta-enlace, dónde aterriza lo que
+> calcula un motor de arrastre, y el HTML que no viene de React.
+
+### `Tooltip disabledTrigger` — el motivo de un control deshabilitado
+
+Un control apagado es el que más necesita explicarse, y es justo el que no puede: un
+`button[disabled]` no recibe eventos de puntero ni foco, así que no dispara nada. Con
+`disabledTrigger`, el bocadillo se dispara desde un envoltorio focusable
+(`span.tooltip__trigger`, `tabIndex={0}`) que pone el propio componente, y el CSS apaga los
+eventos de puntero del hijo deshabilitado para que el hover **sobre el botón** llegue al
+envoltorio. Eso segundo es lo que falta siempre que esto se monta a mano —el `<span tabIndex={0}>`
+casero abre con el teclado pero no con el ratón—, y era el caso de `design-matrix-studio` en
+bricks. El control sigue deshabilitado de verdad; lo único que cambia es quién dispara.
+
+Se descartó la otra forma, un `Button disabledReason`: ataría el átomo más usado del sistema a
+`Tooltip` y a su proveedor, lo obligaría a ser componente de cliente en apps que hoy lo pintan
+desde el servidor, y no serviría para un `Select` o un `Switcher` apagados.
+
+### `Card linkOverlay` y `CardAction isolate` — la tarjeta que navega y lleva acciones
+
+Envolver una tarjeta con menú en el `<a>` del router mete un `<button>` dentro de un `<a>`: no es
+HTML válido, y el lector de pantalla lee un enlace cuyo nombre se traga el título, el estado, el
+pie y la etiqueta del menú. La forma del sistema es `Card linkOverlay`: la tarjeta es contenedora,
+el enlace es el del **título** y estira su área de pulsación a todo el bloque con una capa vacía;
+la ranura de acciones sube por encima y se pulsa sola.
+
+Y para lo que ya existe —una tarjeta envuelta en un enlace, una fila pulsable—, `CardAction`
+**aísla su ranura por defecto** (`isolate`): detiene la propagación y, **solo cuando cuelga de un
+enlace y solo para lo que se pulsa dentro de ella**, cancela la acción por defecto. Las dos cosas
+hacen falta: detener la propagación no cancela la navegación, y acotar el `preventDefault` es lo
+que evita romper un `type="submit"` de una tarjeta contenedora o el ítem de un `Menu`, que se
+pinta en un portal fuera del enlace.
+
+### `Sortable` — dónde aterriza lo que calcula un motor de arrastre
+
+El sistema no trae motor de arrastre y no va a traerlo. Lo que faltaba era dónde deja el motor lo
+que calcula en cada fotograma, porque la respuesta de manual —`style={{ transform: CSS.Transform
+.toString(transform) }}`— es justo lo que el sistema no puede emitir: una app con `style-src
+'self'` descarta el atributo `style` sin dejar ni una violación en consola.
+
+`Sortable` recibe el desplazamiento como **dato** (`transform`, con la forma que devuelven dnd-kit
+y compañía, para pasársela tal cual), lo escribe por el **CSSOM** en `--sortable-x`/`-y` y las dos
+escalas, y publica el estado como atributo (`data-dragging`). El `transform` y la atenuación del
+original (`--opacity-disabled`, sin token nuevo: el original queda fuera de juego) viven en la
+hoja del sistema. Reenvía `ref`, que es lo que el motor necesita para registrar el nodo, y anula
+la transición con `prefers-reduced-motion` —la dicta el motor en una cadena suya, así que no pasa
+por los tokens de duración—.
+
+### `Prose html` — el HTML que no viene de React
+
+`Prose` existía para vestir la semántica cruda de un documento, pero solo aceptaba `children`, así
+que el HTML de un parser de `.docx`/`.pdf` acababa en un `dangerouslySetInnerHTML` sobre un
+`<div>` desnudo —nueve sitios en una sola pantalla de bricks—, fuera de la escala, del ritmo y de
+la medida de lectura. Ahora entra por `html`, **excluyente con `children` por tipo**. El DS **no
+sanea**: la cadena llega ya limpia del consumidor, y por eso la prop es `string` y no un
+`ReactNode`. Se descartó una pieza aparte (`RawHtml`) dentro de `Prose`: obligaría a escribir dos
+componentes para una sola cosa y dejaría el HTML suelto sin vestir cuando se olvidara el de fuera.
+
+### Además
+
+- Norma en Foundations › Opacidad: el original de un arrastre usa `--opacity-disabled`, que es el
+  mismo estado de «fuera de juego» del rol — no es un valor nuevo.
+- `src/index.ts`, `scripts/entry-points.mjs` y `package.json#exports` registran `Sortable`
+  (componente de cliente).
+
+## [49.3.1] — 2026-09-17
+
+> **Patch.** La v49.0.1 estrechó a `:where(.link)` el `inline-size: fit-content` que evita
+> que un enlace suelto se estire dentro de un `Stack` — necesario para no encoger el `<a>`
+> que es pieza de otro componente (`menu__item`, `card`…). Pero dejó fuera el `<a>` de un
+> router de Server Component sin `class="link"` (el `Link` de next-intl, p. ej., que en RSC
+> no admite `render` sobre el `Link` de brand sin romper el prerender): el «← Volver» sobre
+> un `PageIntro` seguía necesitando un `Inline` envolvente para no estirar su subrayado por
+> toda la página.
+
+### El arreglo
+
+Nueva regla en `Link.css`, `:where(.stack > a:not([class]))`, aparte de `:where(.link)`:
+solo alcanza al `<a>` que es hijo DIRECTO de un `Stack` y no lleva ninguna clase. El `<a>`
+que es pieza de otro componente trae siempre su propia clase BEM (barrido en la v49.0.1),
+así que queda fuera sin tocarlo. Story de contrato nueva (`tags: ['!dev']`) en
+`Atoms/Stack` — «enlace suelto sin clase, hijo directo de un Stack, no se estira» — con el
+caso del «← Volver» sobre un `PageIntro` dentro de un `Stack align="stretch"`.
+
 ## [49.3.0] — 2026-09-17
 
 > **Minor.** Norma de redacción cerrada para el estado vacío: `EmptyState.title` nunca

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

@@ -0,0 +1,66 @@
+import './Sortable.css';
+/** Elementos con los que puede montarse el envoltorio ordenable. */
+export type SortableElement = 'div' | 'li';
+/**
+ * Desplazamiento que la biblioteca de arrastre calcula en cada fotograma, en
+ * píxeles. Es la forma que devuelven los motores de arrastre al uso (dnd-kit
+ * entre ellos), así que se les pasa tal cual: el DS no depende de ninguno.
+ */
+export interface SortableTransform {
+    x: number;
+    y: number;
+    scaleX?: number;
+    scaleY?: number;
+}
+export interface SortableProps extends Omit<React.ComponentPropsWithoutRef<'div'>, 'style'> {
+    /** Elemento del envoltorio. `div` por defecto; `li` dentro de una lista. */
+    as?: SortableElement;
+    /**
+     * Desplazamiento del elemento mientras se reordena la lista, tal y como lo
+     * devuelve el motor de arrastre. `null` (o ausente) es la posición de
+     * reposo. Se escribe por el CSSOM en `--sortable-x`/`--sortable-y` (y las
+     * dos escalas), que es lo que consume el `transform` de la hoja.
+     */
+    transform?: SortableTransform | null;
+    /**
+     * Transición que acompaña al desplazamiento, la que dicte el motor (`transform
+     * 200ms ease`). `null` o ausente: sin transición. Con
+     * `prefers-reduced-motion` la hoja la anula.
+     */
+    transition?: string | null;
+    /**
+     * El elemento es el que se está arrastrando ahora mismo. Pone
+     * `data-dragging` —de donde cuelga el CSS— y atenúa el original, que se
+     * queda como hueco mientras la copia viaja con el puntero.
+     */
+    dragging?: boolean;
+}
+/**
+ * Envoltorio de un elemento **ordenable por arrastre**.
+ *
+ * El sistema no trae motor de arrastre y no va a traerlo: quien lo pone es la
+ * aplicación (dnd-kit, en la suite). Lo que faltaba era dónde aterriza lo que
+ * ese motor calcula en tiempo de ejecución, porque la respuesta evidente —un
+ * `style` inline con el `transform`— es justo lo que el sistema no puede
+ * emitir: una app servida con `style-src 'self'` descarta el atributo `style`
+ * sin dejar ni una violación en consola, y el arrastre se queda quieto sin
+ * que nadie sepa por qué.
+ *
+ * `Sortable` es ese aterrizaje: recibe el desplazamiento como **dato**, lo
+ * escribe por el CSSOM (que la CSP sí permite) en las variables que consume su
+ * hoja, y publica el estado como atributo (`data-dragging`). El aspecto —qué
+ * `transform` se aplica, cuánto se atenúa el original— vive en el CSS del
+ * sistema, no en la app.
+ *
+ * Reenvía `ref`: es lo que necesita el motor para medir y registrar el nodo
+ * (`setNodeRef` de dnd-kit).
+ *
+ * ```tsx
+ * const { attributes, listeners, setNodeRef, transform, transition, isDragging } = useSortable({ id });
+ *
+ * <Sortable ref={setNodeRef} transform={transform} transition={transition} dragging={isDragging}>
+ *   <Card>…</Card>
+ * </Sortable>
+ * ```
+ */
+export declare const Sortable: import("react").ForwardRefExoticComponent<SortableProps & import("react").RefAttributes<HTMLElement>>;

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

@@ -41,6 +41,23 @@ export interface TooltipProps extends Omit<React.HTMLAttributes<HTMLElement>, 'c
      * @default true
      */
     describe?: boolean;
+    /**
+     * El disparador está **deshabilitado** y el bocadillo es justo lo que
+     * explica por qué. Un `button[disabled]` no sirve de disparador: el
+     * navegador no le manda eventos de puntero ni lo deja recibir foco, así que
+     * el bocadillo no se abre ni con el ratón ni con el teclado — y quien no
+     * puede pulsar es precisamente quien necesita leer el motivo.
+     *
+     * Con `disabledTrigger` el bocadillo se dispara desde un envoltorio
+     * focusable (`span.tooltip__trigger`, `tabIndex={0}`) que pone el propio
+     * componente: es él quien recibe hover, foco y el `aria-describedby`,
+     * mientras el control de dentro sigue deshabilitado de verdad. El CSS
+     * apaga los eventos de puntero del hijo deshabilitado para que el hover
+     * sobre el botón llegue al envoltorio en vez de perderse.
+     *
+     * @default false
+     */
+    disabledTrigger?: 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

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

@@ -67,6 +67,23 @@ export interface CardProps extends Omit<React.ComponentPropsWithoutRef<'div'>, '
     color?: CardColor;
     /** Maqueta de la tarjeta. Default: `'default'`. */
     variant?: CardVariant;
+    /**
+     * Modo contenedor: el enlace del **título** cubre toda la tarjeta. La
+     * tarjeta sigue siendo un `<div>` con contenido interactivo dentro —un menú
+     * en `CardAction`, un botón en el pie—, y quien navega es el `<a>` del
+     * título, que estira su área de pulsación a todo el bloque con una capa
+     * vacía (`::after`).
+     *
+     * Es la forma correcta de una «tarjeta que es enlace **y** lleva acciones»:
+     * meter un `<button>` dentro de un `<a>` —envolviendo la tarjeta en el
+     * `Link` del router— no es HTML válido, y un lector de pantalla anuncia un
+     * enlace cuyo nombre se come el título, el estado, el pie y la etiqueta del
+     * menú de una sentada. Con `linkOverlay` cada control conserva su papel: un
+     * enlace con el nombre del título, y un botón de menú aparte.
+     *
+     * La ranura de acciones queda por encima de la capa, así que se pulsa sola.
+     */
+    linkOverlay?: boolean;
     /**
      * Modo contenedor: la tarjeta entera es la opción de un grupo. Dentro va
      * un `RadioField` (o `CheckboxField`) del DS, que la tarjeta extiende a todo
@@ -136,8 +153,38 @@ export interface CardDescriptionProps extends Omit<ParagraphProps, 'children'> {
  * hereda el cuerpo de la superficie en la que viva la tarjeta.
  */
 export declare const CardDescription: import("react").ForwardRefExoticComponent<CardDescriptionProps & import("react").RefAttributes<HTMLParagraphElement>>;
-/** Acción alineada al extremo de la cabecera (menú, botón…). */
-export declare const CardAction: import("react").ForwardRefExoticComponent<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
+export interface CardActionProps extends CardPartProps {
+    /**
+     * La ranura **aísla sus eventos** de la tarjeta que la contiene, que es lo
+     * que se quiere siempre que la tarjeta sea a la vez un enlace (`Card href`,
+     * `Card render`, o un `<Link>` del router envolviéndola): pulsar el menú de
+     * la cabecera abre el menú, no navega.
+     *
+     * Hace dos cosas, y las dos hacen falta:
+     *
+     * - `stopPropagation`, para que el clic no llegue a un manejador que la
+     *   tarjeta o la fila tengan puesto más arriba;
+     * - `preventDefault` **solo cuando la ranura cuelga de un enlace** —se
+     *   comprueba en el DOM, buscando un `a[href]` por encima del propio nodo—
+     *   y **solo para lo que se pulsa dentro de ella**. Sin esto no basta:
+     *   detener la propagación no cancela la acción por defecto del navegador,
+     *   que sigue el enlace igual. Y acotarlo evita romper lo que sí depende de
+     *   su acción por defecto: un `type="submit"` dentro de una tarjeta
+     *   contenedora, o el ítem de un `Menu` que se pinta en un portal fuera del
+     *   enlace.
+     *
+     * `false` para la tarjeta que quiere lo contrario: que pulsar la acción
+     * cuente también como pulsar la tarjeta.
+     *
+     * @default true
+     */
+    isolate?: boolean;
+}
+/**
+ * Acción alineada al extremo de la cabecera (menú, botón…). Por defecto aísla
+ * sus eventos de la tarjeta-enlace que la contiene: ver `isolate`.
+ */
+export declare const CardAction: import("react").ForwardRefExoticComponent<CardActionProps & import("react").RefAttributes<HTMLDivElement>>;
 /** Cuerpo de la tarjeta. */
 export declare const CardContent: import("react").ForwardRefExoticComponent<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & import("react").RefAttributes<HTMLDivElement>>;
 export interface CardFooterProps extends CardPartProps {

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

@@ -2,7 +2,7 @@ import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
 import './Prose.css';
 /** Elementos con los que puede montarse el contenedor de texto largo. */
 export type ProseElement = 'div' | 'article' | 'section' | 'main' | 'aside';
-export interface ProseProps extends ComponentPropsWithoutRef<'div'> {
+interface ProseBaseProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children' | 'dangerouslySetInnerHTML'> {
     /**
      * Elemento del contenedor. `div` por defecto; `article` cuando el bloque es
      * el documento en sí (una página de documentación, un texto legal).
@@ -16,8 +16,32 @@ export interface ProseProps extends ComponentPropsWithoutRef<'div'> {
      * anchas o figuras a sangre.
      */
     measure?: boolean;
-    children: ReactNode;
 }
+export type ProseProps = (ProseBaseProps & {
+    /** Contenido en nodos de React. Excluyente con `html`. */
+    children: ReactNode;
+    html?: never;
+}) | (ProseBaseProps & {
+    /**
+     * Cadena de **HTML ya saneado**, para el contenido que no viene de React: lo
+     * que devuelve un parser de `.docx`/`.pdf`, un campo de un CMS, un markdown ya
+     * compilado. Excluyente con `children`.
+     *
+     * Es la misma excepción que ya justifica a `Prose` —el contenido no trae
+     * clases porque no lo escribió nadie del sistema— llevada a su forma real: sin
+     * esta prop, cada aplicación acababa poniendo su propio
+     * `dangerouslySetInnerHTML` en un `<div>` desnudo, fuera de la hoja del
+     * sistema, y ese texto salía sin escala, sin ritmo y sin medida de lectura.
+     *
+     * **El sistema no sanea.** No lleva sanitizador ni va a llevarlo: la política
+     * de lo que se permite depende de la aplicación y de dónde venga el HTML. Lo
+     * que llega aquí tiene que venir ya limpio del consumidor (`sanitize-html`,
+     * DOMPurify, lo que use), y por eso la prop se declara `string` y no un
+     * `ReactNode`: es una frontera, y se cruza a conciencia.
+     */
+    html: string;
+    children?: never;
+});
 /**
  * Contenedor de contenido largo: viste la semántica cruda que sale de un
  * markdown o de un CMS (`h2`–`h6`, `p`, `ul`/`ol`, `blockquote`, `pre`/`code`,
@@ -30,7 +54,11 @@ export interface ProseProps extends ComponentPropsWithoutRef<'div'> {
  * siendo de componentes (el único otro caso, mucho menor, es el `<mark>` del
  * extracto de `DocsSearch`).
  *
+ * El contenido entra de una de dos formas, **nunca de las dos**: `children`
+ * (nodos de React) o `html` (una cadena ya saneada). Ver la prop `html`.
+ *
  * Reenvía el resto de props del elemento (`data-*`, `aria-*`, `id`…) y
  * concatena `className` tras las clases propias.
  */
 export declare const Prose: import("react").ForwardRefExoticComponent<ProseProps & import("react").RefAttributes<HTMLDivElement>>;
+export {};

package/dist/app-shell.js

@@ -2,8 +2,8 @@
 import './app-shell.css';
 import { n as e } from "./_shared/brandmessagescontext.js";
 import { SkipLink as t } from "./skip-link.js";
-import { TooltipProvider as n } from "./tooltip.js";
-import { t as r } from "./_shared/css-properties.js";
+import { t as n } from "./_shared/css-properties.js";
+import { TooltipProvider as r } from "./tooltip.js";
 import { n as i, t as a } from "./_shared/appshellcontext.js";
 import { useCallback as o, useEffect as s, useMemo as c, useState as l } from "react";
 import { jsx as u, jsxs as d } from "react/jsx-runtime";
@@ -49,10 +49,10 @@ function m({ header: i, sidebar: f, children: m, defaultSidebar: h = "open", sid
 		j,
 		M,
 		S
-	]), F = r({ "--app-shell-sidebar-width": D ? `${D}px` : void 0 }), I = !S && T;
+	]), F = n({ "--app-shell-sidebar-width": D ? `${D}px` : void 0 }), I = !S && T;
 	return /* @__PURE__ */ u(a.Provider, {
 		value: P,
-		children: /* @__PURE__ */ d(n, { children: [/* @__PURE__ */ u(t, {
+		children: /* @__PURE__ */ d(r, { children: [/* @__PURE__ */ u(t, {
 			href: "#main-content",
 			children: x("skipToContent", b)
 		}), /* @__PURE__ */ d("div", {