@studiolxd/brand 49.17.0 → 49.19.0

package/CHANGELOG.md

@@ -7,6 +7,155 @@ 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.19.0] — 2026-10-04
+
+> **Minor.** Primera versión con **Brand nativo**: tokens, fuentes y componentes para SwiftUI (iOS 17 y macOS 14) y
+> Jetpack Compose (Android), fuera del paquete npm. En React, opciones de fila en `List`/`ListItem`
+> (`showSeparators`, `secondary`, `trailing`, `leading`), `NumberInput` sin valor y el aviso neutro de `Toast` en
+> oscuro. Todo opcional: sin las props nuevas el HTML no cambia.
+
+### React — huecos de la primera app nativa (minor)
+
+Todo opcional: sin las props nuevas el HTML es idéntico al anterior (pruebas con `toMatchInlineSnapshot` generadas
+contra el código de antes, en `InputField.test.tsx`, `NumberInputField.test.tsx`, `PasswordField.test.tsx` y
+`List.test.tsx`).
+
+- **`ListItem` `leading`** (`ReactNode`): accesorio al principio de la fila (icono, avatar), pareja de `trailing`.
+  Clase nueva `list__item-leading`; story «Filas con accesorio inicial».
+- **`NumberInput` / `NumberInputField` sin valor**: `value` y `defaultValue` admiten `null` (campo vacío), y la prop
+  nueva `onEmpty` hace que vaciar el texto sea un valor (sin ella, el campo se comporta como siempre y recupera el
+  último número al salir). Desde vacío, − y + cuentan como si el campo valiera 0 y se ajustan a `min`/`max`.
+  Story «Sin valor».
+- **Foco desde fuera**: el `ref` ya llegaba al `<input>` en `InputField` (también en búsqueda), `NumberInputField` y
+  `PasswordField` (y al botón en `SelectField`); ahora lo fija una prueba y lo documenta `InputField.mdx`.
+- **Documentación de `Button`**: la nota de `destructive` decía que valía para `primary` y `ghost` y mencionaba una
+  variante `accent` que ya no existe; en el código solo `outline` y `text` tienen estilo destructivo. Corregida la
+  nota (y `destructiveIntent` → `destructive`); el comportamiento no cambia.
+
+### Nativo — huecos de la primera app nativa (minor)
+
+- **Generador de Kotlin**: los tamaños de letra de componente cuyo nombre no termina en `font-size`
+  (`empty-state.title-font-size-sm`, `description-font-size-sm`) salían como `Dp`; ahora todo token con `font-size`
+  como segmento es `TextUnit` (`sp`). `BrandEmptyState` deja de convertir a mano. Grupo `password-field` en
+  `NATIVE_COMPONENT_GROUPS`.
+- **`PasswordField` nativo** (`BrandPasswordField`, SwiftUI y Compose): campo con ojo de mostrar u ocultar, etiqueta
+  oculta por defecto como en React, textos accesibles como parámetros. Ficha, capturas y parejas. **Compose: `BrandInputField`
+  pierde el ojo** (`passwordToggle`, `showPasswordLabel`, `hidePasswordLabel`; breaking menor en Compose): quien lo quiera usa `BrandPasswordField`.
+- **Foco desde fuera** en `InputField`, `NumberInputField` y `PasswordField`: SwiftUI `.brandFocused($focus)` /
+  `.brandFocused($focus, equals:)` (un `FocusState` de la app aplicado al texto, no a los botones); Compose
+  `focusRequester: FocusRequester?`.
+- **`NumberInputField` sin valor**: `Binding<Double?>` (SwiftUI; `Binding<Double>` sigue compilando) y `value: Double?`
+  (Compose; **cambio de firma**: `onValueChange` recibe `Double?`). Vacío = `nil`/`null`, con `placeholder` y
+  «Sin valor» (`emptyValueLabel`) para lectores de pantalla; desde vacío − y + parten de 0 y respetan `min`/`max`.
+- **`BrandListItem`**: `leading` en SwiftUI (ya existía en Compose) y `action` (fila pulsable entera) en SwiftUI, pareja de
+  `onClick` de Compose, anotado en la ficha como diferencia deliberada.
+
+### Nativo — Jetpack Compose con los mismos componentes que SwiftUI (minor)
+
+- **Tokens de componente en Kotlin**: `pnpm build:tokens` genera `BrandComponentTokens.kt` (mismos grupos y reglas que
+  `BrandComponentTokens.swift`; los colores y las medidas con par `surface-dark-*` salen como `BrandSchemeValue`, que se
+  resuelve con `.current`). El Swift generado no cambia.
+- **Componentes de Compose** (`native/android/brand`): `BrandButton`, `BrandCloseButton`, `BrandHeading`/`BrandParagraph`/
+  `BrandText`, `BrandIcon` (77 iconos; `pnpm build:native-icons` genera también `BrandIconData.kt`), `BrandInputField`,
+  `BrandNumberInputField`, `BrandSelectField`, `BrandSwitcherField`, `BrandToggleGroup`, `BrandThemeSwitcher`,
+  `BrandList`/`BrandListItem` (`showSeparators`, `secondary`, `trailing`), `BrandTag`, `BrandEmptyState`, `BrandSkeleton`,
+  `BrandSheet`, `BrandConfirmDialog` y `ToastCenter`/`ToastHost`, con estados, escala de fuente, TalkBack, 48 dp, claro y
+  oscuro y «quitar animaciones». Cumplen las fichas de paridad (`ParityTest`), con capturas Paparazzi en claro y oscuro,
+  `@Preview` y parejas React ↔ Compose en `native/android/Comparisons/`. Sin dependencias nuevas en producción.
+- Fichas de paridad: líneas «Android: …» en `differences`. `native/README.md` documenta los componentes de Compose.
+
+### React — `List`/`ListItem` (minor) y `Toast` (patch)
+
+- **`List` `showSeparators`** (default `false`): línea entre filas con los tokens `separator.*`
+  (clase nueva `list--separated`). **`ListItem` `secondary` y `trailing`** (`ReactNode`): línea
+  menor atenuada y accesorio al final de la fila. Sin las props nuevas el HTML es exactamente el
+  de antes; la estructura de fila (`list__item-row`, `list__item-main`, `list__item-secondary`,
+  `list__item-trailing`) solo aparece al usarlas. Tokens nuevos en `text.list.*`
+  (`item-gap`, `secondary-*`, `separator-*`, con pares `surface-dark-*`). Prueba que fija el HTML
+  anterior en `List.test.tsx`.
+- **Fix `Toast` neutro en oscuro**: el neutro (y `info`/`loading`) llevaba `.surface-dark` en la
+  raíz, que volteaba su relleno a blanco incluso sobre página clara y dejaba el aspa en blanco
+  sobre blanco. Ahora, como el `Alert`, la raíz solo la lleva `success`/`error`, y el interior
+  (contenido y aspa) lleva `.surface-invert` (neutro) o `.surface-light` (`warning`).
+
+### Nativo
+
+- `BrandList(showsSeparators:)` pasa a **`showSeparators:`** (mismo nombre que en React; lo nativo
+  aún no se había publicado). `BrandListItem` `secondary`/`trailing` y los separadores leen ahora
+  los tokens `text.list.*`. Fichas `List.json`/`ListItem.json` actualizadas: ya no son «solo nativo».
+
+> Infraestructura nativa (iOS, macOS y Android). **No cambia nada del paquete npm**: lo
+> nativo vive en `native/`, `Package.swift` y `jitpack.yml`, fuera de `package.json#files`.
+
+### Nativo — nuevo (`native/`)
+
+- **Tokens nativos con Style Dictionary**: dos plataformas nuevas en `sd.config.mjs`
+  (`swift`, `kotlin`) con formatos propios en `sd.formats.mjs`. `pnpm build:tokens`
+  genera `native/apple/…/Tokens/BrandTokens.swift` y
+  `native/android/…/tokens/BrandTokens.kt`: colores y roles claro/oscuro (`Color` dinámico
+  en Swift; `BrandColorRoles.light|dark` + `CompositionLocal` en Compose), espaciado,
+  radios, anchos de borde, tallas, opacidad, tipografía, sombras y motion. Los tokens de
+  componente quedan para cuando se porte cada componente.
+- **Paquete SwiftPM** `StudiolxdBrand` (`Package.swift` en la raíz; iOS 17, macOS 14,
+  Swift 6): `registerFonts()`, `BrandTextStyle` y `Font.brand(_:)`.
+- **Módulo Gradle** `com.github.studiolxd:brand` (`native/android`, minSdk 26, publicable
+  por JitPack con `jitpack.yml`): `BrandTheme`, `BrandFontFamily`, `BrandTypography`.
+- **Fuentes**: `pnpm build:native-fonts` descomprime los woff2 variables (Google Sans Flex,
+  Google Sans Code, Libre Bodoni; cara `latin`) a TTF para ambas plataformas.
+- **Paridad con React**: fichas por componente (`native/parity/`), validador
+  (`pnpm native:parity`, con TypeScript y `ajv`) y pruebas de paridad en Swift y Kotlin.
+- **Capturas**: swift-snapshot-testing (Apple) y Paparazzi (Android), con una captura de
+  ejemplo de los roles de color en claro y oscuro.
+- **`release:check`** comprueba que `npm pack` no incluye nada nativo, que los tokens
+  nativos están al día y la paridad; con `--with-native` compila y prueba Swift (macOS e
+  iOS) y Gradle.
+- Documentación en `native/README.md` y en `CLAUDE.md` § «Nativo (iOS y Android)».
+
+### Nativo — componentes de SwiftUI (iOS 17 y macOS 14)
+
+> Los primeros componentes nativos, los que pide Homenize. Mismos nombres de props y casos que React, solo tokens,
+> claro y oscuro con colores dinámicos, tipo dinámico, VoiceOver, zona táctil de 44 pt, puntero y foco de teclado en
+> macOS y «reducir movimiento». Detalle y ejemplos en `native/README.md` § «Componentes de SwiftUI». Compose recibirá los
+> mismos componentes en la tarea siguiente.
+
+- **15 componentes** portados, cada uno con su ficha de paridad (`native/parity/components/`), capturas en claro y
+  oscuro (iOS y macOS), `#Preview` con todas las variantes y la pareja con su story de Storybook
+  (`native/apple/Comparisons/<Componente>/`): `Button` (como `ButtonStyle` + `BrandButton`), `Heading`/`Paragraph`/`Text`,
+  `Icon`, `InputField`, `NumberInputField`, `SelectField`, `SwitcherField`, `ToggleGroup`, `ThemeSwitcher`, `List` +
+  `ListItem`, `Tag`, `EmptyState`, `Skeleton`, `Sheet` (`.sheet` nativo), `ConfirmDialog` y `Toast`/`Toaster`
+  (`ToastCenter` + `toastHost`).
+- **Tokens de componente para Swift**: `pnpm build:tokens` genera también `BrandComponentTokens.swift` (un enum por
+  grupo de `NATIVE_COMPONENT_GROUPS`, con los `surface-dark-*` como `Color` dinámico, también los heredados por
+  referencia). Una medida con par oscuro sale como `BrandSchemeValue`. El CSS puro (`solid`, `vh`, `min()`…) se omite.
+- **`BrandIcon`**: los mismos trazos que el `Icon` de React (77 iconos, retícula de 24), generados desde `Icon.tsx` con
+  `pnpm build:native-icons` (incluido en `build:all`).
+- **Paridad**: las fichas admiten `differences` (lo que se queda a propósito) y `reactOnlyValues` (`block: boolean |
+  'mobile'`), y `native:parity` entiende uniones numéricas (`Heading level: 1 | … | 6`).
+- **Ayudantes**: `brandFont`/`brandLinedFont` (tipo dinámico e interlineado de CSS), `brandHitTarget` (44 pt),
+  `BrandControlSize` y `.brandControlSize(_:)`, `assertBrandSnapshots` (capturas de macOS en sRGB),
+  `native/apple/scripts/capture-story.mjs` y `pair-comparison.sh` (parejas React ↔ SwiftUI a la misma escala).
+- Los ejemplos del README compilan (`ReadmeExamples.swift`).
+
+## [49.18.0] — 2026-10-03
+
+> **Minor.** `RecoveryCodes` deja pasar el aviso de portapapeles roto, y `react-hook-form`
+> pasa a peer opcional.
+
+### `RecoveryCodes` — `labels.error`
+
+- Nueva clave **opcional** `labels.error`: el aviso del botón de copiar cuando el
+  portapapeles falla (contexto no seguro, permiso denegado). Hasta ahora salía solo de
+  `copy.error` del `BrandMessagesProvider`, así que una app que pasara las props sueltas,
+  sin proveedor, lanzaba al fallar la copia (visto en keycloakify-starter al pasar a npm).
+  Sin `labels.error` el comportamiento no cambia.
+
+### `react-hook-form`, peer opcional
+
+- Solo lo importa `@studiolxd/brand/form-field`. Como `react-email`, pasa a
+  `peerDependenciesMeta.optional`: una app que no use ese subpath deja de instalarlo
+  (pnpm con `auto-install-peers` lo traía igualmente). Quien use `form-field` lo sigue
+  necesitando en sus `dependencies`.
+
 ## [49.17.0] — 2026-10-03
 
 > **Minor.** Componente nuevo: `EmbedFrame`, el marco embebido del sistema, y las tres

package/README.md

@@ -11,10 +11,10 @@ y el catálogo de Storybook es su fuente de verdad.
 pnpm add @studiolxd/brand
 ```
 
-El paquete declara como peer dependencies `react` y `react-dom` (>=18) y
-`react-hook-form` (>=7), del que dependen el `Form` y todos los campos que se
-atan a él. `react-email` (>=6) es un peer **opcional**: solo hace falta si se
-consume el subpath `@studiolxd/brand/email`.
+El paquete declara como peer dependencies `react` y `react-dom` (>=18). Hay
+dos peers **opcionales**, que solo hacen falta si se consume el subpath que
+los importa: `react-hook-form` (>=7) para `@studiolxd/brand/form-field`, y
+`react-email` (>=6) para `@studiolxd/brand/email`.
 
 ## Uso
 

package/dist/_shared/tokens.js

@@ -1905,6 +1905,13 @@ var e = {
 	"--text-list-letter-spacing": "0em",
 	"--text-list-gap": "0.5rem",
 	"--text-list-padding-inline-start": "2rem",
+	"--text-list-item-gap": "0.75rem",
+	"--text-list-secondary-font-size": "0.875rem",
+	"--text-list-secondary-line-height": "1.65",
+	"--text-list-secondary-color": "#4a4a4a",
+	"--text-list-separator-color": "#111e30",
+	"--text-list-separator-thickness": "1px",
+	"--text-list-separator-spacing": "0.5rem",
 	"--textarea-border-radius": "0px",
 	"--textarea-border-width": "1px",
 	"--textarea-border-style": "solid",

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

@@ -8,10 +8,30 @@ export interface ListItemProps extends React.ComponentPropsWithoutRef<'li'> {
      */
     as?: React.ElementType;
     children?: React.ReactNode;
+    /**
+     * Accesorio al principio de la fila: un icono, un avatar. Pareja de
+     * `trailing`; no se encoge ni parte línea y se centra con el bloque de texto.
+     */
+    leading?: React.ReactNode;
+    /**
+     * Línea menor bajo el contenido, atenuada y un peldaño por debajo del cuerpo
+     * (`text.paragraph.small`): la descripción de una fila de datos o de ajustes.
+     */
+    secondary?: React.ReactNode;
+    /**
+     * Accesorio al final de la fila, alineado a la derecha: un icono, un valor,
+     * un interruptor. No se encoge ni parte línea.
+     */
+    trailing?: React.ReactNode;
 }
 export interface ListProps extends React.ComponentPropsWithoutRef<'ul'> {
     /** Tipo de lista: con viñetas, numerada o sin decoración. */
     type?: ListType;
+    /**
+     * Dibuja una línea entre filas con los tokens `separator.*`, con su aire a
+     * cada lado en lugar del `text.list.gap`. Default `false`: sin línea.
+     */
+    showSeparators?: boolean;
     children: React.ReactNode;
 }
 /**

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

@@ -11,8 +11,13 @@ export interface NumberInputMessages {
     increment: string;
 }
 export interface NumberInputProps extends Omit<ComponentPropsWithoutRef<'input'>, 'size' | 'type' | 'value' | 'defaultValue' | 'onChange'> {
-    value?: number;
-    defaultValue?: number;
+    /**
+     * Valor controlado. `null` es «sin valor»: el campo se muestra vacío (y el
+     * `placeholder` se ve). Sigue siendo controlado; `undefined` es no controlado.
+     */
+    value?: number | null;
+    /** Valor inicial no controlado (default `0`). `null` arranca vacío. */
+    defaultValue?: number | null;
     min?: number;
     max?: number;
     step?: number;
@@ -40,6 +45,13 @@ export interface NumberInputProps extends Omit<ComponentPropsWithoutRef<'input'>
      */
     incrementLabel?: string;
     onChange?: (value: number) => void;
+    /**
+     * Se llama cuando quien teclea deja el campo vacío. Sin ella el campo se
+     * comporta como siempre (vaciar no emite nada y al salir recupera el último
+     * número); con ella, vaciar **es** un valor: el campo pasa a «sin valor» y
+     * esta función avisa de ello.
+     */
+    onEmpty?: () => void;
     onBlur?: React.FocusEventHandler<HTMLInputElement>;
     onFocus?: React.FocusEventHandler<HTMLInputElement>;
 }

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

@@ -11,8 +11,9 @@ export interface NumberInputFieldProps extends Omit<ComponentPropsWithoutRef<'in
      * es la primera de la lista, la etiqueta se oculta sola.
      */
     labelHidden?: boolean;
-    value?: number;
-    defaultValue?: number;
+    /** `null` es «sin valor»: el campo se muestra vacío. Ver `NumberInput`. */
+    value?: number | null;
+    defaultValue?: number | null;
     min?: number;
     max?: number;
     step?: number;
@@ -27,6 +28,8 @@ export interface NumberInputFieldProps extends Omit<ComponentPropsWithoutRef<'in
     size?: 'sm' | 'md' | 'lg';
     /** Recibe el valor ya normalizado, no el evento. */
     onChange?: (value: number) => void;
+    /** Quien teclea dejó el campo vacío; con ella, vaciar es un valor (`null`). Ver `NumberInput`. */
+    onEmpty?: () => void;
     /** Se añade DESPUÉS de las clases propias (el consumidor añade, no sustituye). */
     className?: string;
 }

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

@@ -7,6 +7,12 @@ export interface RecoveryCodesLabels {
     copy: string;
     /** Acuse del botón de copiar, mientras dura. */
     copied: string;
+    /**
+     * Aviso del botón de copiar si el portapapeles falla (contexto no seguro,
+     * permiso denegado). Opcional: sin él sale de `copy.error` del
+     * `BrandMessagesProvider`, y sin ninguno de los dos el componente lanza.
+     */
+    error?: string;
 }
 export interface RecoveryCodesProps {
     /** Los códigos, en el orden en que se numeran. */