@zuccadev-labs/zuix-zui 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (282) hide show
  1. package/AGENTS.md +96 -37
  2. package/CHANGELOG.md +215 -0
  3. package/README.md +73 -44
  4. package/THIRD_PARTY_NOTICES.md +71 -0
  5. package/dist/esm/components/actions/Button.d.ts +1 -1
  6. package/dist/esm/components/actions/Button.js +2 -2
  7. package/dist/esm/components/actions/Button.js.map +1 -1
  8. package/dist/esm/components/actions/IconButton.d.ts +1 -1
  9. package/dist/esm/components/actions/IconButton.js +2 -2
  10. package/dist/esm/components/actions/IconButton.js.map +1 -1
  11. package/dist/esm/components/actions/Link.d.ts +1 -1
  12. package/dist/esm/components/actions/Link.js +5 -3
  13. package/dist/esm/components/actions/Link.js.map +1 -1
  14. package/dist/esm/components/actions/SegmentedControl.d.ts +6 -3
  15. package/dist/esm/components/actions/SegmentedControl.js +29 -13
  16. package/dist/esm/components/actions/SegmentedControl.js.map +1 -1
  17. package/dist/esm/components/actions/Toggle.d.ts +5 -3
  18. package/dist/esm/components/actions/Toggle.js +8 -3
  19. package/dist/esm/components/actions/Toggle.js.map +1 -1
  20. package/dist/esm/components/carousel/Carousel.js +3 -8
  21. package/dist/esm/components/carousel/Carousel.js.map +1 -1
  22. package/dist/esm/components/carousel/engine.js +11 -10
  23. package/dist/esm/components/carousel/engine.js.map +1 -1
  24. package/dist/esm/components/carousel/lens.js +2 -2
  25. package/dist/esm/components/carousel/lens.js.map +1 -1
  26. package/dist/esm/components/carousel/lensRenderer.d.ts +6 -0
  27. package/dist/esm/components/carousel/lensRenderer.js +32 -4
  28. package/dist/esm/components/carousel/lensRenderer.js.map +1 -1
  29. package/dist/esm/components/carousel/useCarouselTrack.js +1 -0
  30. package/dist/esm/components/carousel/useCarouselTrack.js.map +1 -1
  31. package/dist/esm/components/content/Card.js.map +1 -1
  32. package/dist/esm/components/content/CodeBlock.js.map +1 -1
  33. package/dist/esm/components/content/Panel.js.map +1 -1
  34. package/dist/esm/components/data/Avatar.js +6 -1
  35. package/dist/esm/components/data/Avatar.js.map +1 -1
  36. package/dist/esm/components/data/AvatarGroup.js +1 -1
  37. package/dist/esm/components/data/AvatarGroup.js.map +1 -1
  38. package/dist/esm/components/data/Chip.js +1 -1
  39. package/dist/esm/components/data/Chip.js.map +1 -1
  40. package/dist/esm/components/data/DataTable.js +2 -17
  41. package/dist/esm/components/data/DataTable.js.map +1 -1
  42. package/dist/esm/components/data/Kbd.js +4 -1
  43. package/dist/esm/components/data/Kbd.js.map +1 -1
  44. package/dist/esm/components/data/Meter.js.map +1 -1
  45. package/dist/esm/components/data/Progress.js.map +1 -1
  46. package/dist/esm/components/data/Rating.d.ts +1 -1
  47. package/dist/esm/components/data/Rating.js +10 -6
  48. package/dist/esm/components/data/Rating.js.map +1 -1
  49. package/dist/esm/components/data/StatTile.js.map +1 -1
  50. package/dist/esm/components/data/Table.js.map +1 -1
  51. package/dist/esm/components/feedback/Alert.js.map +1 -1
  52. package/dist/esm/components/feedback/ErrorBoundary.js +1 -1
  53. package/dist/esm/components/feedback/ErrorBoundary.js.map +1 -1
  54. package/dist/esm/components/feedback/LoadingOverlay.js.map +1 -1
  55. package/dist/esm/components/feedback/Skeleton.js +1 -1
  56. package/dist/esm/components/feedback/Skeleton.js.map +1 -1
  57. package/dist/esm/components/feedback/Spinner.js +1 -1
  58. package/dist/esm/components/feedback/Spinner.js.map +1 -1
  59. package/dist/esm/components/forms/Calendar.d.ts +3 -8
  60. package/dist/esm/components/forms/Calendar.js +41 -44
  61. package/dist/esm/components/forms/Calendar.js.map +1 -1
  62. package/dist/esm/components/forms/Checkbox.d.ts +12 -4
  63. package/dist/esm/components/forms/Checkbox.js +17 -5
  64. package/dist/esm/components/forms/Checkbox.js.map +1 -1
  65. package/dist/esm/components/forms/Combobox.js +30 -26
  66. package/dist/esm/components/forms/Combobox.js.map +1 -1
  67. package/dist/esm/components/forms/DateInput.js +2 -7
  68. package/dist/esm/components/forms/DateInput.js.map +1 -1
  69. package/dist/esm/components/forms/DatePicker.js +54 -21
  70. package/dist/esm/components/forms/DatePicker.js.map +1 -1
  71. package/dist/esm/components/forms/Field.d.ts +6 -0
  72. package/dist/esm/components/forms/Field.js +11 -2
  73. package/dist/esm/components/forms/Field.js.map +1 -1
  74. package/dist/esm/components/forms/FileUpload.js +32 -13
  75. package/dist/esm/components/forms/FileUpload.js.map +1 -1
  76. package/dist/esm/components/forms/Input.js.map +1 -1
  77. package/dist/esm/components/forms/NativeSelect.js +1 -1
  78. package/dist/esm/components/forms/NativeSelect.js.map +1 -1
  79. package/dist/esm/components/forms/OTPInput.js +15 -4
  80. package/dist/esm/components/forms/OTPInput.js.map +1 -1
  81. package/dist/esm/components/forms/Radio.d.ts +5 -4
  82. package/dist/esm/components/forms/Radio.js +17 -3
  83. package/dist/esm/components/forms/Radio.js.map +1 -1
  84. package/dist/esm/components/forms/RadioGroup.d.ts +12 -5
  85. package/dist/esm/components/forms/RadioGroup.js +37 -6
  86. package/dist/esm/components/forms/RadioGroup.js.map +1 -1
  87. package/dist/esm/components/forms/SearchInput.js +2 -7
  88. package/dist/esm/components/forms/SearchInput.js.map +1 -1
  89. package/dist/esm/components/forms/Select.d.ts +5 -2
  90. package/dist/esm/components/forms/Select.js +131 -13
  91. package/dist/esm/components/forms/Select.js.map +1 -1
  92. package/dist/esm/components/forms/Slider.d.ts +23 -5
  93. package/dist/esm/components/forms/Slider.js +92 -5
  94. package/dist/esm/components/forms/Slider.js.map +1 -1
  95. package/dist/esm/components/forms/Switch.d.ts +10 -3
  96. package/dist/esm/components/forms/Switch.js +11 -4
  97. package/dist/esm/components/forms/Switch.js.map +1 -1
  98. package/dist/esm/components/forms/Textarea.d.ts +2 -2
  99. package/dist/esm/components/forms/Textarea.js +10 -3
  100. package/dist/esm/components/forms/Textarea.js.map +1 -1
  101. package/dist/esm/components/forms/index.d.ts +1 -1
  102. package/dist/esm/components/forms/index.js +1 -1
  103. package/dist/esm/components/forms/index.js.map +1 -1
  104. package/dist/esm/components/navigation/Accordion.d.ts +3 -2
  105. package/dist/esm/components/navigation/Accordion.js +57 -10
  106. package/dist/esm/components/navigation/Accordion.js.map +1 -1
  107. package/dist/esm/components/navigation/Breadcrumb.js +1 -1
  108. package/dist/esm/components/navigation/Breadcrumb.js.map +1 -1
  109. package/dist/esm/components/navigation/NavList.d.ts +4 -3
  110. package/dist/esm/components/navigation/NavList.js +10 -6
  111. package/dist/esm/components/navigation/NavList.js.map +1 -1
  112. package/dist/esm/components/navigation/Pagination.js +10 -19
  113. package/dist/esm/components/navigation/Pagination.js.map +1 -1
  114. package/dist/esm/components/navigation/Stepper.d.ts +1 -1
  115. package/dist/esm/components/navigation/Stepper.js +2 -2
  116. package/dist/esm/components/navigation/Stepper.js.map +1 -1
  117. package/dist/esm/components/navigation/Tabs.d.ts +4 -3
  118. package/dist/esm/components/navigation/Tabs.js +39 -5
  119. package/dist/esm/components/navigation/Tabs.js.map +1 -1
  120. package/dist/esm/components/navigation/Tree.d.ts +1 -1
  121. package/dist/esm/components/navigation/Tree.js +19 -3
  122. package/dist/esm/components/navigation/Tree.js.map +1 -1
  123. package/dist/esm/components/overlay/CommandPalette.js +34 -36
  124. package/dist/esm/components/overlay/CommandPalette.js.map +1 -1
  125. package/dist/esm/components/overlay/ConfirmDialog.d.ts +6 -2
  126. package/dist/esm/components/overlay/ConfirmDialog.js +23 -6
  127. package/dist/esm/components/overlay/ConfirmDialog.js.map +1 -1
  128. package/dist/esm/components/overlay/ContextMenu.d.ts +2 -1
  129. package/dist/esm/components/overlay/ContextMenu.js +50 -7
  130. package/dist/esm/components/overlay/ContextMenu.js.map +1 -1
  131. package/dist/esm/components/overlay/Drawer.d.ts +3 -2
  132. package/dist/esm/components/overlay/Drawer.js +11 -6
  133. package/dist/esm/components/overlay/Drawer.js.map +1 -1
  134. package/dist/esm/components/overlay/Menu.d.ts +3 -2
  135. package/dist/esm/components/overlay/Menu.js +27 -8
  136. package/dist/esm/components/overlay/Menu.js.map +1 -1
  137. package/dist/esm/components/overlay/Modal.d.ts +3 -2
  138. package/dist/esm/components/overlay/Modal.js +11 -10
  139. package/dist/esm/components/overlay/Modal.js.map +1 -1
  140. package/dist/esm/components/overlay/Popover.d.ts +20 -5
  141. package/dist/esm/components/overlay/Popover.js +53 -4
  142. package/dist/esm/components/overlay/Popover.js.map +1 -1
  143. package/dist/esm/components/overlay/Toast.d.ts +8 -4
  144. package/dist/esm/components/overlay/Toast.js +145 -50
  145. package/dist/esm/components/overlay/Toast.js.map +1 -1
  146. package/dist/esm/components/overlay/Tooltip.d.ts +2 -2
  147. package/dist/esm/components/overlay/Tooltip.js +64 -7
  148. package/dist/esm/components/overlay/Tooltip.js.map +1 -1
  149. package/dist/esm/components/overlay/internal.d.ts +18 -50
  150. package/dist/esm/components/overlay/internal.js +24 -48
  151. package/dist/esm/components/overlay/internal.js.map +1 -1
  152. package/dist/esm/core/accept.d.ts +5 -0
  153. package/dist/esm/core/accept.js +13 -0
  154. package/dist/esm/core/accept.js.map +1 -0
  155. package/dist/esm/core/compare.d.ts +5 -0
  156. package/dist/esm/core/compare.js +27 -0
  157. package/dist/esm/core/compare.js.map +1 -0
  158. package/dist/esm/core/date.d.ts +27 -0
  159. package/dist/esm/core/date.js +59 -0
  160. package/dist/esm/core/date.js.map +1 -0
  161. package/dist/esm/core/dir.d.ts +4 -0
  162. package/dist/esm/core/dir.js +10 -0
  163. package/dist/esm/core/dir.js.map +1 -0
  164. package/dist/esm/core/focus.d.ts +16 -0
  165. package/dist/esm/core/focus.js +50 -0
  166. package/dist/esm/core/focus.js.map +1 -0
  167. package/dist/esm/core/keys.d.ts +6 -0
  168. package/dist/esm/core/keys.js +14 -0
  169. package/dist/esm/core/keys.js.map +1 -0
  170. package/dist/esm/core/layers.d.ts +33 -0
  171. package/dist/esm/core/layers.js +75 -0
  172. package/dist/esm/core/layers.js.map +1 -0
  173. package/dist/esm/core/long-press.d.ts +13 -0
  174. package/dist/esm/core/long-press.js +33 -0
  175. package/dist/esm/core/long-press.js.map +1 -0
  176. package/dist/esm/core/menu-aim.d.ts +17 -0
  177. package/dist/esm/core/menu-aim.js +48 -0
  178. package/dist/esm/core/menu-aim.js.map +1 -0
  179. package/dist/esm/core/modal-host.d.ts +16 -0
  180. package/dist/esm/core/modal-host.js +59 -0
  181. package/dist/esm/core/modal-host.js.map +1 -0
  182. package/dist/esm/core/pagination.d.ts +6 -0
  183. package/dist/esm/core/pagination.js +32 -0
  184. package/dist/esm/core/pagination.js.map +1 -0
  185. package/dist/esm/core/place.d.ts +54 -0
  186. package/dist/esm/core/place.js +97 -0
  187. package/dist/esm/core/place.js.map +1 -0
  188. package/dist/esm/core/presence.d.ts +7 -0
  189. package/dist/esm/core/presence.js +43 -0
  190. package/dist/esm/core/presence.js.map +1 -0
  191. package/dist/esm/core/ref.d.ts +9 -0
  192. package/dist/esm/core/ref.js +25 -0
  193. package/dist/esm/core/ref.js.map +1 -0
  194. package/dist/esm/core/roving.d.ts +6 -0
  195. package/dist/esm/core/roving.js +27 -0
  196. package/dist/esm/core/roving.js.map +1 -0
  197. package/dist/esm/core/scroll-lock.d.ts +2 -0
  198. package/dist/esm/core/scroll-lock.js +33 -0
  199. package/dist/esm/core/scroll-lock.js.map +1 -0
  200. package/dist/esm/core/search.d.ts +4 -0
  201. package/dist/esm/core/search.js +20 -0
  202. package/dist/esm/core/search.js.map +1 -0
  203. package/dist/esm/core/slider.d.ts +20 -0
  204. package/dist/esm/core/slider.js +66 -0
  205. package/dist/esm/core/slider.js.map +1 -0
  206. package/dist/esm/core/swipe.d.ts +18 -0
  207. package/dist/esm/core/swipe.js +78 -0
  208. package/dist/esm/core/swipe.js.map +1 -0
  209. package/dist/esm/core/timer.d.ts +11 -0
  210. package/dist/esm/core/timer.js +38 -0
  211. package/dist/esm/core/timer.js.map +1 -0
  212. package/dist/esm/core/typeahead.d.ts +19 -0
  213. package/dist/esm/core/typeahead.js +33 -0
  214. package/dist/esm/core/typeahead.js.map +1 -0
  215. package/dist/esm/dom/carousel.d.ts +2 -1
  216. package/dist/esm/dom/carousel.js +18 -30
  217. package/dist/esm/dom/carousel.js.map +1 -1
  218. package/dist/esm/dom/collections.d.ts +2 -1
  219. package/dist/esm/dom/collections.js +67 -72
  220. package/dist/esm/dom/collections.js.map +1 -1
  221. package/dist/esm/dom/forms-calendar.d.ts +4 -5
  222. package/dist/esm/dom/forms-calendar.js +74 -72
  223. package/dist/esm/dom/forms-calendar.js.map +1 -1
  224. package/dist/esm/dom/forms-controls.d.ts +2 -1
  225. package/dist/esm/dom/forms-controls.js +84 -65
  226. package/dist/esm/dom/forms-controls.js.map +1 -1
  227. package/dist/esm/dom/forms-listbox.d.ts +2 -1
  228. package/dist/esm/dom/forms-listbox.js +66 -64
  229. package/dist/esm/dom/forms-listbox.js.map +1 -1
  230. package/dist/esm/dom/forms-popup.d.ts +3 -2
  231. package/dist/esm/dom/forms-popup.js +34 -44
  232. package/dist/esm/dom/forms-popup.js.map +1 -1
  233. package/dist/esm/dom/forms.d.ts +2 -1
  234. package/dist/esm/dom/forms.js +2 -2
  235. package/dist/esm/dom/forms.js.map +1 -1
  236. package/dist/esm/dom/index.d.ts +28 -10
  237. package/dist/esm/dom/index.js +500 -296
  238. package/dist/esm/dom/index.js.map +1 -1
  239. package/dist/esm/dom/shared.d.ts +22 -0
  240. package/dist/esm/dom/shared.js +45 -0
  241. package/dist/esm/dom/shared.js.map +1 -0
  242. package/dist/esm/primitives/dialog.d.ts +17 -0
  243. package/dist/esm/primitives/dialog.js +78 -0
  244. package/dist/esm/primitives/dialog.js.map +1 -0
  245. package/dist/esm/primitives/hooks.d.ts +15 -0
  246. package/dist/esm/primitives/hooks.js +65 -0
  247. package/dist/esm/primitives/hooks.js.map +1 -0
  248. package/dist/esm/primitives/menu.d.ts +26 -0
  249. package/dist/esm/primitives/menu.js +249 -0
  250. package/dist/esm/primitives/menu.js.map +1 -0
  251. package/dist/esm/primitives/native-input.d.ts +13 -0
  252. package/dist/esm/primitives/native-input.js +26 -0
  253. package/dist/esm/primitives/native-input.js.map +1 -0
  254. package/dist/esm/primitives/popup.d.ts +51 -0
  255. package/dist/esm/primitives/popup.js +137 -0
  256. package/dist/esm/primitives/popup.js.map +1 -0
  257. package/dist/esm/primitives/radio-context.d.ts +11 -0
  258. package/dist/esm/primitives/radio-context.js +5 -0
  259. package/dist/esm/primitives/radio-context.js.map +1 -0
  260. package/dist/esm/primitives/slot.d.ts +13 -0
  261. package/dist/esm/primitives/slot.js +39 -0
  262. package/dist/esm/primitives/slot.js.map +1 -0
  263. package/dist/esm/refs.d.ts +8 -0
  264. package/dist/esm/refs.js +32 -0
  265. package/dist/esm/refs.js.map +1 -0
  266. package/dist/styles/actions.css +22 -12
  267. package/dist/styles/base.css +216 -9
  268. package/dist/styles/carousel.css +132 -35
  269. package/dist/styles/content.css +13 -7
  270. package/dist/styles/data.css +61 -35
  271. package/dist/styles/feedback.css +17 -6
  272. package/dist/styles/forms.css +75 -20
  273. package/dist/styles/material.css +9 -4
  274. package/dist/styles/native.css +120 -23
  275. package/dist/styles/navigation.css +630 -154
  276. package/dist/styles/overlay.css +625 -188
  277. package/dist/zui.css +315 -150
  278. package/dist/zui.dom.carousel-gl.js +3 -3
  279. package/dist/zui.dom.js +1 -1
  280. package/html.json +19 -23
  281. package/manifest.json +121 -64
  282. package/package.json +9 -10
package/AGENTS.md CHANGED
@@ -1,30 +1,41 @@
1
1
  # Zui · guía para agentes
2
2
 
3
- Formato: reglas → patrones → verificación. Un cambio está terminado cuando la verificación pasa.
3
+ Guía para los agentes de IA que usan o extienden `@zuccadev-labs/zuix-zui`. Formato: reglas → patrones →
4
+ verificación. Un cambio está terminado cuando la verificación pasa.
4
5
 
5
6
  ## Reglas
6
7
 
7
8
  0. **El contrato es el marcado, no React.** Un componente es HTML con clases `z-*` y atributos de estado,
8
9
  más su CSS. El `.tsx` es el binding de React que produce ese marcado. Toda la apariencia tiene que
9
- funcionar copiando el HTML a una página sin React (`zui/html.json`, `docs/agents/04-otros-frameworks.md`).
10
-
10
+ funcionar copiando el HTML a una página sin React (`html.json`).
11
11
  1. **Solo tokens.** El CSS lee `var(--z-*)`. Nunca un color literal (`#hex`, `rgb()`, `hsl()`), nunca un
12
- primitivo de marca (`--zp-*`). La lista de tokens está en `tokens/dist/tokens.json`.
13
- 2. **Sin apariencia en línea.** `style={{…}}` solo admite maquetación calculada (posición, tamaño,
12
+ primitivo de marca (`--zp-*`). La lista de tokens está en `tokens.json`, en `@zuccadev-labs/zuix-tokens`.
13
+ 2. **Un token por uso del color.** Texto de color: `--z-accent-text`, `--z-danger-text`… Fondo con texto
14
+ encima: `--z-accent-solid`, `--z-danger-solid`… con `--z-fg-on-accent`. `--z-accent`, `--z-success`,
15
+ `--z-warning`, `--z-danger` e `--z-info` son para rellenos, bordes e iconos. `pnpm tokens` lee las hojas,
16
+ mide cada par y falla si el texto no llega a 4.5:1 o un indicador a 3:1.
17
+ 3. **Sin apariencia en línea.** `style={{…}}` solo admite maquetación calculada (posición, tamaño,
14
18
  transformaciones) y variables locales (`"--z-algo": valor`). Color, fondo, borde, sombra, radio y
15
19
  fuente van en la hoja de estilos.
16
- 3. **Iconos de `@zuccadev-labs/zuix-zicon`.** `<Icon name="…" />`. Sin emojis, sin SVG incrustado a mano. Si no existe un
17
- icono para el concepto, se informa; no se inventa.
18
- 4. **Clases con prefijo `z-`**, estilo BEM: `.z-btn`, `.z-btn__icon`, `.z-btn--primary`. Estado por atributo:
20
+ 4. **Iconos de `@zuccadev-labs/zuix-zicon`.** `<Icon name="…" />`. Sin emojis, sin SVG incrustado a mano. Si
21
+ no existe un icono para el concepto, se informa; no se inventa.
22
+ 5. **Clases con prefijo `z-`**, estilo BEM: `.z-btn`, `.z-btn__spinner`, `.z-btn--primary`. Estado por atributo:
19
23
  `[data-state]`, `[data-size]`, `[aria-selected]`, `[disabled]`.
20
- 5. **Cristal solo en el cromo.** `.z-liquid` para paneles, barras, menús y diálogos. Texto denso sobre
24
+ 6. **Propiedades lógicas.** `margin-inline-start`, `inset-inline-end`, `padding-block`. Nunca `left`, `right`,
25
+ `margin-left`. Un icono direccional se refleja en `[dir="rtl"]`.
26
+ 7. **Cristal solo en el cromo.** `.z-liquid` para paneles, barras, menús y diálogos. Texto denso sobre
21
27
  `.z-solid`.
22
- 6. **Accesibilidad no opcional.** Lo interactivo complejo (diálogos, menús, pestañas, popovers) usa las
23
- primitivas de `radix-ui`. Todo control tiene nombre accesible, foco visible y uso con teclado.
24
- 7. **Sin dominio.** Pagos, reservas, mapas o clima viven en la aplicación, no aquí.
25
- 8. **Sin dependencias nuevas** sin justificarlo en el informe del cambio.
26
- 9. **Texto visible por props.** Los componentes no fijan idioma: las etiquetas llegan por props, con valor
27
- por defecto en inglés.
28
+ 8. **Accesibilidad no opcional.** Lo interactivo complejo (diálogos, menús, pestañas, popovers) usa las
29
+ primitivas de `src/primitives/` sobre la lógica de `src/core/`, según el patrón de
30
+ [APG](https://www.w3.org/WAI/ARIA/apg/) de cada widget. Todo control tiene nombre accesible, foco visible
31
+ (también con `forced-colors`) y uso con teclado.
32
+ 9. **Sin dependencias.** El paquete solo depende de `@zuccadev-labs/zuix-tokens`. No se añade una biblioteca
33
+ de UI; el linter rechaza su importación. Cualquier otra dependencia nueva necesita mi aprobación.
34
+ 10. **Sin dominio.** Pagos, reservas, mapas o clima viven en la aplicación, no aquí.
35
+ 11. **Texto visible por props.** Los componentes no fijan idioma: las etiquetas llegan por props, con valor
36
+ por defecto en inglés.
37
+ 12. **`"use client"`** en la primera línea de un módulo con hooks, contexto o manejadores de eventos propios.
38
+ Un componente de solo marcado no lo lleva: así se renderiza en un Server Component.
28
39
 
29
40
  ## Estructura
30
41
 
@@ -34,15 +45,21 @@ src/components/<grupo>/<Componente>.manifest.json contrato legible por máquina
34
45
  src/components/<grupo>/index.ts exportaciones del grupo
35
46
  src/styles/<grupo>.css estilos del grupo, dentro de @layer zui.<grupo>
36
47
  src/styles/native.css neutraliza <dialog>, [popover] y <button> para el contrato HTML
37
- src/dom/index.ts comportamiento sin framework (@zuccadev-labs/zuix-zui/dom)
48
+ src/core/*.ts lógica compartida, sin React ni efectos al importar: colocación,
49
+ foco itinerante, búsqueda por letra, capas, foco, presencia, fechas…
50
+ src/primitives/* primitivas de React sobre core: diálogo (<dialog>), capa
51
+ (popover), menú, slot, hooks, campo nativo oculto
52
+ src/dom/*.ts comportamiento sin framework (@zuccadev-labs/zuix-zui/dom), sobre core
38
53
  ```
39
54
 
40
55
  Grupos: `actions`, `forms`, `data`, `feedback`, `content`, `overlay`, `navigation`, `carousel`.
41
56
 
42
- ## Patrón de componente
57
+ ## Patrones
58
+
59
+ ### Componente de solo marcado
43
60
 
44
61
  ```tsx
45
- import type { ButtonHTMLAttributes, ReactNode } from "react";
62
+ import type { ButtonHTMLAttributes, ReactNode, Ref } from "react";
46
63
  import { Icon, type IconName } from "@zuccadev-labs/zuix-zicon/core";
47
64
  import { cx } from "../../cx";
48
65
 
@@ -51,10 +68,11 @@ export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
51
68
  size?: "sm" | "md" | "lg";
52
69
  icon?: IconName;
53
70
  loading?: boolean;
71
+ ref?: Ref<HTMLButtonElement>;
54
72
  children?: ReactNode;
55
73
  }
56
74
 
57
- export function Button({ variant = "secondary", size = "md", icon, loading, className, children, ...rest }: ButtonProps) {
75
+ export function Button({ variant = "secondary", size = "md", icon, loading, className, children, disabled, onClick, ...rest }: ButtonProps) {
58
76
  return (
59
77
  <button
60
78
  type="button"
@@ -63,7 +81,9 @@ export function Button({ variant = "secondary", size = "md", icon, loading, clas
63
81
  data-size={size}
64
82
  data-loading={loading || undefined}
65
83
  aria-busy={loading || undefined}
66
- disabled={rest.disabled || loading}
84
+ aria-disabled={loading || undefined}
85
+ disabled={disabled}
86
+ {...(loading ? { type: "button" as const, onClick: undefined } : { onClick })}
67
87
  >
68
88
  {icon ? <Icon name={icon} size={16} /> : null}
69
89
  {children}
@@ -72,24 +92,47 @@ export function Button({ variant = "secondary", size = "md", icon, loading, clas
72
92
  }
73
93
  ```
74
94
 
95
+ - `ref` es una prop más: React 19, sin `forwardRef`.
96
+ - En carga el botón lleva `aria-disabled`, no `disabled`: conserva el foco. No hay manejador propio, así que
97
+ el módulo no necesita `"use client"`.
98
+
75
99
  ```css
76
100
  @layer zui.actions {
77
101
  .z-btn {
78
102
  display: inline-flex; align-items: center; justify-content: center; gap: var(--z-space-2);
79
- height: var(--z-control-height-md); padding: 0 var(--z-space-4);
103
+ height: var(--z-control-height-md); padding-inline: var(--z-space-4);
80
104
  border-radius: var(--z-button-radius); border: 1px solid var(--z-line);
81
- background: var(--z-surface); color: var(--z-fg);
105
+ background: var(--z-surface-2); color: var(--z-fg);
82
106
  font-weight: var(--z-weight-semibold); font-size: var(--z-text-body);
83
107
  transition: background var(--z-duration-fast) var(--z-ease-standard);
84
108
  }
85
- .z-btn:hover:not(:disabled) { background: var(--z-surface-2); }
109
+ @media (hover: hover) { .z-btn:hover:not(:disabled) { background: var(--z-surface-3); } }
86
110
  .z-btn:focus-visible { outline: none; box-shadow: var(--z-focus-ring); }
87
111
  .z-btn--primary { background: var(--z-button-primary-bg); color: var(--z-button-primary-fg); border-color: transparent; }
112
+ .z-btn--danger { background: var(--z-danger-soft); color: var(--z-danger-text); }
88
113
  .z-btn[data-size="sm"] { height: var(--z-control-height-sm); }
89
114
  }
90
115
  ```
91
116
 
92
- ## Manifiesto
117
+ - `:hover` va dentro de `@media (hover: hover)`.
118
+ - El foco se dibuja con `box-shadow: var(--z-focus-ring)`. Con colores forzados el navegador quita las
119
+ sombras: `base.css` devuelve entonces un contorno del sistema a todo lo enfocable dentro de `.z-root`. Un
120
+ estado que solo cambia el fondo necesita además su regla en `@media (forced-colors: active)`.
121
+ - Texto de peligro con `--z-danger-text` sobre `--z-danger-soft`.
122
+
123
+ ### Lógica compartida
124
+
125
+ - Una sola lógica para React y para el modo DOM: lo que no depende de React vive en `src/core/` y lo consumen
126
+ `src/primitives/`, `src/components/` y `src/dom/`. No se duplica un cálculo en los dos lados.
127
+ - `src/core/` no importa React ni toca el documento al cargarse. Un módulo nuevo lleva su prueba en
128
+ `tests/unit/` y su entrada en la lista `COVERED` de `tests/unit/run.mjs`.
129
+ - Plataforma primero: `<dialog>` + `showModal()` para lo modal, `popover="manual"` para lo flotante, `useId`.
130
+ El marcado que emite React es el del contrato (`html.json`).
131
+ - La dirección (RTL) se lee del DOM (`core/dir`), no de una prop ni de un proveedor.
132
+ - El modo DOM escribe el texto de la aplicación con `textContent` y su marcado propio con `setMarkup`
133
+ (`src/dom/shared.ts`). Un atributo que nombra otro elemento se resuelve con `byRef`.
134
+
135
+ ### Manifiesto
93
136
 
94
137
  ```json
95
138
  {
@@ -104,25 +147,36 @@ export function Button({ variant = "secondary", size = "md", icon, loading, clas
104
147
  { "name": "loading", "type": "boolean", "default": false }
105
148
  ],
106
149
  "states": ["rest", "hover", "focus", "active", "disabled", "loading"],
107
- "tokens": ["button-radius", "button-primary-bg", "button-primary-fg", "surface", "surface-2", "line", "fg", "focus-ring", "control-height-md"],
150
+ "tokens": ["button-radius", "button-primary-bg", "button-primary-fg", "surface-2", "surface-3", "line", "fg", "focus-ring", "control-height-md"],
108
151
  "classes": ["z-btn"],
109
- "a11y": "Elemento button nativo. Con `loading` expone aria-busy y queda deshabilitado.",
152
+ "a11y": "Elemento button nativo. Con `loading` expone aria-busy y aria-disabled: no actúa, pero conserva el foco.",
110
153
  "examples": [
111
154
  { "title": "Primario con icono", "code": "<Button variant=\"primary\" icon=\"plus\">New project</Button>" }
112
- ],
113
- "origin": "Button de un design system previo; variantes de zutool."
155
+ ]
114
156
  }
115
157
  ```
116
158
 
117
159
  Campos obligatorios: `name`, `group`, `description`, `import`, `props`, `tokens`, `classes`, `examples`.
118
160
 
119
161
  Campos del contrato HTML: `behavior` (`none` | `dom` | `react`; se deduce si falta) y `html` (lista de
120
- `{ title, code, script? }`) cuando el marcado no sale del render estático, como en lo que va por portal.
162
+ `{ title, code, script? }`) cuando el marcado no sale del render estático.
163
+
164
+ ## No hacer
165
+
166
+ | En lugar de | Usa |
167
+ |---|---|
168
+ | `color: var(--z-accent)` en un texto | `var(--z-accent-text)` |
169
+ | `background: var(--z-success)` con texto encima | `var(--z-success-solid)` y `var(--z-fg-on-accent)` |
170
+ | `margin-left`, `right: 0`, `text-align: left` | `margin-inline-start`, `inset-inline-end: 0`, `text-align: start` |
171
+ | Un foco sin indicador | `box-shadow: var(--z-focus-ring)` en `:focus-visible` |
172
+ | Un `div` flotante con `z-index` | Un elemento `popover` con las primitivas de `src/primitives/` |
173
+ | `disabled` para un botón en carga | `aria-disabled` |
174
+ | `forwardRef` | `ref` como prop |
175
+ | Una clase suelta en la pantalla | Una variante en el componente y en su manifiesto |
121
176
 
122
- ## Si falta algo
177
+ ## Cuando falta algo
123
178
 
124
- - **Falta una variante:** se añade al componente y a su manifiesto. No se resuelve con una clase suelta en
125
- la pantalla.
179
+ - **Falta una variante:** se añade al componente y a su manifiesto.
126
180
  - **Falta un token:** se propone en `tokens/src/base.json` (nivel `component`), referenciando un semántico.
127
181
  No se escribe el valor literal.
128
182
  - **Falta un icono:** se informa.
@@ -132,9 +186,14 @@ Campos del contrato HTML: `behavior` (`none` | `dom` | `react`; se deduce si fal
132
186
  Desde la raíz de zuix:
133
187
 
134
188
  ```
135
- pnpm style-audit # color, prim, token, emoji, inline: todo en 0
136
- pnpm typecheck # sin errores
137
- pnpm manifest # todo componente exportado tiene manifiesto válido
138
- pnpm html # el contrato HTML se regenera
139
- pnpm test:html # si tocaste zui/dom, native.css o un componente con behavior "dom"
189
+ pnpm tokens # el contraste de los pares que usan las hojas
190
+ pnpm style-audit # color, prim, token, emoji, inline: todo en 0
191
+ pnpm lint # Biome y la regla de "use client"
192
+ pnpm typecheck # sin errores
193
+ pnpm manifest # todo componente exportado tiene manifiesto válido
194
+ pnpm barrels # todo componente con manifiesto se exporta desde la raíz del paquete
195
+ pnpm html # el contrato HTML se regenera
196
+ pnpm test:unit # si tocaste src/core o lógica cubierta
197
+ pnpm test:html # si tocaste src/dom, native.css o un componente con behavior "dom"
198
+ pnpm test:browser # si tocaste el binding de un componente interactivo
140
199
  ```
package/CHANGELOG.md CHANGED
@@ -5,6 +5,221 @@ versión en toda la suite ([Versionado](https://github.com/zuccadev-labs/zuix/bl
5
5
 
6
6
  ## [Sin publicar]
7
7
 
8
+ ## [0.2.0] - 2026-11-18
9
+
10
+ Esta versión trae cambios incompatibles. Qué hay que tocar en una aplicación está en la
11
+ [guía de actualización](https://github.com/zuccadev-labs/zuix/blob/main/docs/users/08-actualizar-de-0-1-a-0-2.md).
12
+
13
+ El paquete ya no depende de ninguna biblioteca de UI: `radix-ui` se retira y el binding de React usa
14
+ primitivas propias sobre la plataforma (`<dialog>`, Popover API), con la misma lógica que
15
+ `@zuccadev-labs/zuix-zui/dom`. En ejecución solo necesita `@zuccadev-labs/zuix-tokens`;
16
+ `@zuccadev-labs/zuix-zicon` es un peer obligatorio y React y React DOM 19, peers opcionales. Un proyecto que
17
+ solo usa el contrato HTML y `zui/dom` deja de instalar los más de setenta paquetes que llegaban por esa
18
+ dependencia.
19
+
20
+ ### Cambios incompatibles
21
+
22
+ Entorno:
23
+
24
+ - Node 22.12 o posterior (antes, 20). Node 20 terminó su soporte el 2026-04-30.
25
+ - Navegadores admitidos: Chrome y Edge 116, Firefox 125, Safari 17 y Safari de iOS 18.3. Lo marca la Popover
26
+ API.
27
+
28
+ Marcado y CSS:
29
+
30
+ - `Modal`, `Drawer`, `ConfirmDialog` y `CommandPalette` de React pintan un `<dialog>` abierto con
31
+ `showModal()` (antes un `div[role=dialog]` y un `div.z-overlay-scrim` aparte). **La clase `z-overlay-scrim`
32
+ y sus modificadores desaparecen**: el velo es `dialog::backdrop`. Un selector `.z-modal[role=dialog]` pasa
33
+ a `dialog.z-modal`. Sin `title`, el nombre va en `aria-label` (antes un `h2.z-sr-only`).
34
+ - Variables CSS renombradas: `--radix-select-trigger-width` → `--z-anchor-width`;
35
+ `--radix-*-content-available-height` → `--z-available-height`; `--radix-*-content-available-width` →
36
+ `--z-available-width`; `--radix-toast-swipe-move-x|y` y `--radix-toast-swipe-end-x|y` →
37
+ `--z-toast-swipe-…`; `--radix-accordion-content-height` → `--z-accordion-content-height`. No queda ningún
38
+ `--radix-*`, `data-radix-*` ni id `radix-…`.
39
+ - Toast de React: la región es `div.z-toast-viewport[role=region]` con nombre y cada aviso un
40
+ `div.z-toast[role=status|alert]` (antes `ol` y `li`). `toast()` del modo DOM genera el mismo `div`. La
41
+ región solo existe mientras hay avisos.
42
+ - Menús de React: cada entrada es un `button[role=menuitem]` (antes `div`), el separador lleva
43
+ `role="separator"` y el atributo `data-elevated` desaparece: todo va en la capa superior.
44
+ - `Popover modal` de React es un `<dialog>` abierto con `showModal()` (antes un `div[role=dialog]`). Un
45
+ selector `.z-popover[role=dialog]` pasa a `dialog.z-popover` para el modal; el no modal sigue siendo un
46
+ `div`.
47
+ - `Select` de React: `role="listbox"` va en `.z-listbox__viewport`, dentro de `.z-listbox`, y las opciones
48
+ llevan `data-value`. Con `name` o `required`, el campo de formulario es un `<select>` nativo oculto
49
+ (`.z-native-input`), no un `input[type=hidden]`.
50
+ - `Checkbox`, `Switch` y `Radio`: el campo nativo oculto lleva la clase `z-native-input` (antes estilos en
51
+ línea) y está siempre en el marcado. `RadioGroup` y `SegmentedControl` ya no llevan `dir` ni `tabindex` en
52
+ el grupo.
53
+ - `Tabs`: los ids son `…-tab-<valor>` y `…-panel-<valor>`; cada pestaña lleva `data-value`.
54
+ - `Accordion`: la cabecera es un `h2`…`h6` real según `headingLevel` (antes `h3` con `aria-level`); el
55
+ contenido de una sección cerrada sigue montado, oculto con `hidden`; `.z-accordion` lleva `data-type`.
56
+ - `Slider` de React: los tiradores son hijos directos de `.z-slider` y la pista se sitúa con
57
+ `inset-inline-start` y `-end`; el contenedor lleva `data-min`, `data-max`, `data-step` y `data-value`.
58
+
59
+ Props y tipos:
60
+
61
+ - `Popover`: el nombre accesible es obligatorio en los tipos: `label`, o `aria-labelledby` con el id de un
62
+ encabezado del panel.
63
+ - `ToastProvider`: `label` se sustituye por `regionLabel` (nombre de la región, por defecto
64
+ `Notifications (F8)`).
65
+ - `CheckboxProps`, `SwitchProps`, `RadioProps`, `RadioGroupProps`, `SliderProps` y `ToggleProps` son los
66
+ atributos del elemento más las props propias (`checked`, `defaultChecked`, `onCheckedChange`, `value`,
67
+ `onValueChange`, `pressed`, `onPressedChange`…). Desaparecen `asChild`, `dir`, `loop` y `forceMount`, y
68
+ con ellas tres props que la suite no usaba: `form` en `RadioGroup`, `checked` y `required` en `Radio` (los
69
+ decide el grupo) y `preserveThumbOrder` en `Slider`. `RadioGroup value` ya no admite `null`.
70
+ - `Slider` con varios tiradores envía un campo por tirador con el mismo `name` (antes `name[]`).
71
+
72
+ Comportamiento:
73
+
74
+ - `Button` e `IconButton` con `loading`: `aria-disabled="true"` en lugar de `disabled`. El botón no ejecuta
75
+ `onClick` ni envía el formulario (pasa a `type="button"` mientras carga), pero conserva el foco del
76
+ teclado.
77
+ - `confirm()` de `zui/dom`: **Escape cancela** (resuelve `false`), igual que `ConfirmDialog` en React y que
78
+ el patrón de diálogo modal de APG. Antes Escape no hacía nada. El clic en el velo sigue sin cerrar.
79
+ - `ConfirmDialog`: cerrar con Escape llama a `onCancel`, además de a `onOpenChange(false)`.
80
+ - La dirección se lee del DOM: dentro de `dir="rtl"`, `Tabs`, `Menu`, `Slider`, `RadioGroup` y
81
+ `SegmentedControl` de React reflejan las flechas sin proveedor ni prop.
82
+ - Escape cierra solo la capa de arriba y respeta un evento ya cancelado: en un `SearchInput` con texto dentro
83
+ de un `Modal`, la primera pulsación limpia el campo y la segunda cierra el diálogo. En un submenú cierra
84
+ ese nivel.
85
+ - `SegmentedControl` y `RadioGroup`: las flechas mueven el foco y la selección, con vuelta al otro extremo.
86
+ - `Menu` y `ContextMenu` de React: al abrir, el foco va a la primera entrada, también con el puntero (antes,
87
+ con el puntero, lo recibía el menú sin resaltar ninguna). Es el patrón de botón de menú de APG y lo que ya
88
+ hacía `zui/dom`. Las flechas dan la vuelta del último al primero.
89
+ - `Popover` no modal: salir con Tab por un extremo lo cierra y devuelve el foco al disparador. `Popover
90
+ modal`: retiene el foco (Tab da la vuelta), bloquea el desplazamiento de la página y el resto queda inerte
91
+ para el puntero, el teclado y los lectores de pantalla; una pulsación fuera solo lo cierra, sin llegar a
92
+ lo que hay debajo.
93
+ - `DatePicker required`: el botón ya no lleva `aria-required` (su rol no lo admite); la obligatoriedad la
94
+ valida un campo nativo oculto, que impide enviar el formulario vacío.
95
+ - Tooltip (React y `data-z-tooltip`): la burbuja recibe el puntero. Se puede pasar del disparador a ella sin
96
+ que se cierre, y Escape la cierra (WCAG 1.4.13). Antes llevaba `pointer-events: none`.
97
+ - `Link disabled` ya no ejecuta `onClick`.
98
+ - `z:close` se emite también cuando un `<dialog>` de zui se cierra con `dialog.close()` o con
99
+ `<form method="dialog">`, y `data-state` pasa a `closed`. Antes solo al cerrar con `closeDialog()`.
100
+ - Casilla (`role="checkbox"`) en modo DOM: Intro ya no la cambia; se marca con Espacio, como en React.
101
+ - Clic en el velo de un `<dialog>`: solo cierra si la pulsación empezó también en el velo.
102
+ - Los diálogos bloquean el desplazamiento de la página también en el modo DOM, y Tab da la vuelta dentro del
103
+ diálogo en lugar de salir a la interfaz del navegador.
104
+ - `Pagination`: `page` se redondea y un `pageCount` no numérico cuenta como una página. `DataTable`: los
105
+ `NaN` se ordenan al final.
106
+
107
+ Color:
108
+
109
+ - Los pares de color de las hojas que no llegaban al mínimo de WCAG 2.2 AA usan los tokens nuevos de
110
+ `@zuccadev-labs/zuix-tokens`: `--z-*-text` para texto y `--z-*-solid` para fondos con texto encima.
111
+ `--z-accent`, `--z-success`, `--z-warning`, `--z-danger` e `--z-info` quedan para rellenos, bordes e
112
+ iconos. Cambia el tono de:
113
+ - el texto con acento: `.z-link` (el hover se distingue por el subrayado pleno), `.z-table__sort[data-active]`,
114
+ `.z-chip[data-selected]`, las iniciales de `Avatar`, `.z-toggle[data-state="on"]`, `IconButton active`,
115
+ el día de hoy del calendario y los iconos de `FileUpload` y `ConfirmDialog`;
116
+ - el texto de peligro: `Button variant="danger"`, `.z-field__required`, `.z-field__error`,
117
+ `.z-menu__item[data-danger]` y el icono de `ErrorState` y de `ConfirmDialog intent="danger"`;
118
+ - `Badge`: la variante suave y `outline` usan `--z-*-text`; la sólida, `--z-*-solid` de fondo. `StatTile`:
119
+ el delta usa `--z-*-text`, y los textos secundarios de la variante sólida dejan de atenuarse;
120
+ - `Rating`: las estrellas vacías usan `--z-control-border`;
121
+ - `LoadingOverlay`: el velo es del color del lienzo, con el texto normal encima;
122
+ - el botón de peligro de los diálogos usa `--z-danger-solid` de fondo.
123
+
124
+ ### Añadido
125
+
126
+ - Una sola lógica para React y para `zui/dom`: colocación, foco itinerante, búsqueda por letra, dirección,
127
+ capas y cierre al interactuar fuera, foco, bloqueo de desplazamiento, presencia, deslizar para descartar,
128
+ fechas, paginación, orden de tabla, búsqueda sin acentos y aritmética del Slider. El HTML que emite React
129
+ es el del contrato (`html.json`): se puede copiar a una página sin React.
130
+ - `init()` de `zui/dom` devuelve `destroy`, y `destroy()` se exporta: retira todos los listeners del
131
+ documento y de la ventana. `init()` se puede volver a llamar.
132
+ - `zui/dom`: Rating de entrada (`.z-rating[data-interactive]`). Clic y flechas rellenan las estrellas y
133
+ emiten `z:change { value }`. `Rating` de React: Inicio y Fin.
134
+ - `zui/dom`: el acordeón emite `z:change { value }` con las secciones abiertas, como `onValueChange` en
135
+ React. En React y en DOM: flechas, Inicio y Fin entre cabeceras; la altura se anima con
136
+ `--z-accordion-content-height`.
137
+ - `toast()` y Toast de React: el cierre automático se detiene mientras el puntero o el foco están en el
138
+ aviso, y con la ventana sin foco (WCAG 2.2.1); F8 lleva el foco al aviso más reciente y Escape lo descarta.
139
+ La región tiene `role="region"` y nombre (`regionLabel`).
140
+ - `openPopover(el, ancla, placement, { follow })`: un popover anclado a un elemento lo sigue al desplazar o
141
+ redimensionar la página. `follow: false` lo deja donde se abrió. `place()` escribe `data-align`,
142
+ `--z-available-width` y `--z-available-height`.
143
+ - RTL: propiedades lógicas en todas las hojas, iconos direccionales reflejados y teclado reflejado en Tabs,
144
+ RadioGroup, Calendar, Tree, Rating, Slider y submenús, en React y en el modo DOM. El submenú abre hacia la
145
+ izquierda y los popovers alinean `start` con el borde derecho del ancla.
146
+ - `forced-colors: active` (contraste alto de Windows): foco siempre visible y estados seleccionado, marcado,
147
+ resaltado y deshabilitado con colores del sistema. `prefers-contrast: more`: cristal a superficie sólida,
148
+ bordes fuertes y foco más grueso.
149
+ - `Field` nombra también los controles que `<label for>` no puede etiquetar (`RadioGroup`, `OTPInput`,
150
+ `Slider`) con `aria-labelledby`. `useFieldLabel()` lo expone para controles propios.
151
+ - `Select required` participa en la validación nativa del formulario; `Select`, `Checkbox`, `Switch`,
152
+ `RadioGroup` y `DatePicker` vuelven a su valor inicial con `form.reset()`.
153
+ - `Slider`: `inverted` en los dos ejes (`data-inverted` en el modo DOM).
154
+ - Submenús (React y DOM): zona de gracia del puntero al ir en diagonal hacia el submenú.
155
+ - `Tree` de React: búsqueda por letra, como en el modo DOM. `Calendar`: atributo `data-month="YYYY-MM"`.
156
+ OTPInput (React y DOM): Supr borra el carácter de la casilla.
157
+ - `CommandPalette` (React y DOM): la búsqueda ignora acentos.
158
+ - Trusted Types: `zui/dom` escribe su marcado a través de la política `zuix-zui` (`trusted-types zuix-zui` en
159
+ la política de seguridad de contenido).
160
+ - `Popover modal`: la inercia del resto de la página la pone el navegador (`<dialog>`), no atributos
161
+ `aria-hidden` repartidos por el documento.
162
+ - Las hojas usan los tokens nuevos `--z-layer-raised`, `--z-layer-below`, `--z-space-1-5` y `--z-space-2-5`
163
+ de `@zuccadev-labs/zuix-tokens` donde antes había un `z-index` o un espacio literal.
164
+ - `THIRD_PARTY_NOTICES.md` en el paquete.
165
+
166
+ ### Corregido
167
+
168
+ - `Slider`: con un `max` que no es un paso desde `min` (`min` 0, `max` 10, `step` 3), el tope es el último
169
+ paso que cabe (9), como en `<input type="range">`. Antes se podía arrastrar hasta 10 y el valor volvía a 9
170
+ al redibujarse.
171
+ - `CommandPalette`: la coincidencia por subsecuencia cuenta caracteres, no unidades UTF-16. Una búsqueda con
172
+ un emoji o una letra fuera del plano básico ya encuentra la entrada que los contiene.
173
+
174
+ Seguridad del modo DOM:
175
+
176
+ - `data-z-open`, `data-z-context`, `data-z-submenu` y `data-raster` se resuelven por id. Un valor que no es
177
+ un selector válido ya no lanza una excepción en cada clic, y funcionan los ids con caracteres especiales,
178
+ como los de `useId` de React.
179
+ - El icono de la opción elegida en Select y Combobox se copia nodo a nodo, sin volver a interpretar marcado;
180
+ todo el marcado propio pasa por un único punto.
181
+ - Un disparador `data-z-open` deshabilitado (`disabled`, `aria-disabled`, `data-disabled`) no abre.
182
+ - Los eventos `keydown` sin `key` (autocompletado del navegador) ya no lanzan.
183
+
184
+ Accesibilidad:
185
+
186
+ - `confirm()`: el diálogo tiene nombre y descripción accesibles.
187
+ - Tooltip en modo DOM: aparece también en controles que ya tenían `aria-describedby` y la conserva; dentro de
188
+ un diálogo modal se inserta en el diálogo, donde no queda inerte.
189
+ - `Rating` de entrada: cada estrella mide al menos 24 × 24 px (WCAG 2.5.8); en `sm` y `md` medía 18 y 22 px.
190
+ Con `value` mayor que `max` sigue siendo alcanzable con el teclado.
191
+ - `NavLink disabled` con `href` lleva `role="link"`, y `NavLink` admite atributos HTML (`data-*`, `aria-*`,
192
+ `id`). `Slider` dentro de un `Field` queda descrito por su ayuda y su error.
193
+
194
+ Comportamiento:
195
+
196
+ - Avisos con un diálogo modal abierto (React y `toast()`): la región se muda al diálogo de arriba y vuelve a
197
+ `<body>` cuando se cierra, sin repetir la animación de entrada ni reiniciar el temporizador. Fuera del
198
+ diálogo el navegador la deja inerte: el aviso se veía, pero no se podía pulsar, enfocar ni leer. En React
199
+ la región vive en un contenedor `div[data-z-toast-root]` (`display: contents`), que es lo que se mueve.
200
+ - Carousel: un clic en un slide lateral cuando la tira está terminando de asentarse cuenta como clic. Antes
201
+ se tomaba por «parar la tira» y se perdía, sobre todo con pocos fotogramas por segundo.
202
+ - Carousel en `zui/dom`: un `.z-carousel__viewport` escrito a mano sin `.z-carousel__stage` o sin
203
+ `.z-carousel__track` lanza un error que lo dice, en lugar de un `TypeError` más adelante.
204
+ - Modo DOM: el cierre pedido por el sistema (gesto atrás) cierra el diálogo con su animación. Un acordeón
205
+ anidado ya no cierra las secciones del exterior.
206
+ - `Calendar` sin `value`, `month` ni `defaultMonth`: sin desajuste de hidratación cuando el reloj del
207
+ servidor y el del navegador caen en meses distintos. Fechas con año menor que 100 en `Calendar` y
208
+ `DatePicker`.
209
+ - `NativeSelect`: el `placeholder` se muestra sin tener que pasar `defaultValue=""`.
210
+ - `FileUpload` con `name`: el campo conserva los archivos aceptados y el formulario los envía. Pasar el
211
+ arrastre sobre un hijo de la zona ya no apaga `data-dragging`.
212
+ - `CommandPalette`: si los grupos cambian con la paleta abierta, el comando activo se acota a la lista; al
213
+ reabrirla no se llega a pintar la búsqueda anterior.
214
+ - `Textarea autoRows` crece también sin controlar. `Avatar` detecta una imagen que falló antes de hidratar.
215
+ - Refs fusionadas (`SearchInput`, `DateInput`, `Combobox`, `Carousel`): respetan la función de limpieza de
216
+ las refs de React 19 y no se reconectan en cada render.
217
+ - `DataTable`: reconoce fechas creadas en otro realm (un iframe), y una celda sin cifras en una columna
218
+ numérica se ordena al final en lugar de contar como cero.
219
+ - `setPage(nav, NaN)` deja la página actual; `setSliderValue(el, NaN)` no mueve el tirador.
220
+ - Carousel en modo `gl`: si el navegador no ofrece WebGL2, se pregunta una sola vez por página.
221
+ - Contrato: el ejemplo «Activable» de Card y el «En línea» de Field producen marcado utilizable sin React.
222
+
8
223
  ## [0.1.0] - 2026-11-14
9
224
 
10
225
  Primera versión publicada.
package/README.md CHANGED
@@ -1,30 +1,36 @@
1
1
  # @zuccadev-labs/zuix-zui
2
2
 
3
- Sistema de componentes de la suite zuix: 64 componentes accesibles en 8 grupos. Cada componente es un
4
- contrato de HTML y CSS sobre tokens; el comportamiento sin framework está en `@zuccadev-labs/zuix-zui/dom` y el
5
- binding de React en la entrada principal.
3
+ The component system of the zuix suite: 64 accessible components in 8 groups. Each component is an HTML and
4
+ CSS contract on top of tokens; the framework-free behavior lives in `@zuccadev-labs/zuix-zui/dom` and the
5
+ React binding in the main entry.
6
6
 
7
- | Capa | Entrada | Depende de |
7
+ | Layer | Entry | Depends on |
8
8
  |---|---|---|
9
- | Contrato | `@zuccadev-labs/zuix-zui/styles.css`, `@zuccadev-labs/zuix-zui/html.json` | `@zuccadev-labs/zuix-tokens` |
10
- | Comportamiento | `@zuccadev-labs/zuix-zui/dom` | El navegador (`<dialog>`, `popover`) |
11
- | Binding de React | `@zuccadev-labs/zuix-zui` | React 19 y Radix |
9
+ | Contract | `@zuccadev-labs/zuix-zui/styles.css`, `@zuccadev-labs/zuix-zui/html.json` | `@zuccadev-labs/zuix-tokens` |
10
+ | Behavior | `@zuccadev-labs/zuix-zui/dom` | The browser (`<dialog>`, Popover API) |
11
+ | React binding | `@zuccadev-labs/zuix-zui` | React 19 |
12
12
 
13
- ## Instalación
13
+ There is no third-party UI library underneath. Dialogs are a native `<dialog>` opened with `showModal()`,
14
+ floating layers are `popover` elements, and the keyboard and focus logic follows the
15
+ [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/). React and the framework-free mode share
16
+ one implementation of that logic, and React emits exactly the markup of the contract.
17
+
18
+ ## Install
14
19
 
15
20
  ```
16
21
  pnpm add @zuccadev-labs/zuix-zui @zuccadev-labs/zuix-tokens @zuccadev-labs/zuix-zicon
17
22
  ```
18
23
 
19
- `@zuccadev-labs/zuix-zicon` es un peer obligatorio (los componentes dibujan sus iconos con la copia de la
20
- aplicación). `react` y `react-dom` 19 son peers opcionales: solo los necesita el binding
21
- (`pnpm add react react-dom`). Los paquetes de la suite se instalan y se actualizan juntos, en la misma versión.
24
+ `@zuccadev-labs/zuix-zicon` is a required peer (components draw their icons with the application's copy).
25
+ `react` and `react-dom` 19 are optional peers: only the binding needs them (`pnpm add react react-dom`).
26
+ React 18 is not supported. The only runtime dependency is `@zuccadev-labs/zuix-tokens`. The suite packages
27
+ are installed and upgraded together, at the same version. Requires Node 22.12 or later.
22
28
 
23
- Para instalarlo todo con una sola dependencia: [`@zuccadev-labs/zuix`](https://www.npmjs.com/package/@zuccadev-labs/zuix).
29
+ To install everything with a single dependency: [`@zuccadev-labs/zuix`](https://www.npmjs.com/package/@zuccadev-labs/zuix).
24
30
 
25
- ## Uso sin React
31
+ ## Without React
26
32
 
27
- Con un bundler:
33
+ With a bundler:
28
34
 
29
35
  ```js
30
36
  import "@zuccadev-labs/zuix-tokens/tokens.css";
@@ -52,19 +58,20 @@ toast({ title: "Ready", intent: "success" });
52
58
  </body>
53
59
  ```
54
60
 
55
- - `z-root` aplica tipografía y foco; `z-canvas` pinta el fondo.
56
- - `data-z-dom` activa pestañas, acordeón y controles dentro de ese contenedor.
57
- - El marcado de cada componente está en `@zuccadev-labs/zuix-zui/html.json`. Cada componente declara su `behavior`:
58
- `none` (solo CSS), `dom` (necesita `@zuccadev-labs/zuix-zui/dom`) o `react` (hoy solo en el binding de React).
61
+ - `z-root` applies typography and focus; `z-canvas` paints the background.
62
+ - `data-z-dom` enables tabs, accordion and form controls inside that container.
63
+ - The markup of every component is in `@zuccadev-labs/zuix-zui/html.json`. Each component declares its
64
+ `behavior`: `none` (CSS only) or `dom` (needs `@zuccadev-labs/zuix-zui/dom`).
65
+ - `init()` returns a `destroy` function that removes every listener.
59
66
 
60
- Sin bundler se enlazan `dist/zui.css` y `dist/zui.dom.js`, incluidos en el paquete.
67
+ Without a bundler, link `dist/zui.css` and `dist/zui.dom.js`, both included in the package.
61
68
 
62
- ## Uso con React
69
+ ## With React
63
70
 
64
71
  ```tsx
65
72
  import "@zuccadev-labs/zuix-tokens/tokens.css";
66
73
  import "@zuccadev-labs/zuix-zui/styles.css";
67
- import "@zuccadev-labs/zuix-zicon/all"; // registra los iconos
74
+ import "@zuccadev-labs/zuix-zicon/all"; // registers the icons
68
75
 
69
76
  import { Button } from "@zuccadev-labs/zuix-zui";
70
77
 
@@ -73,37 +80,59 @@ export function NewProject() {
73
80
  }
74
81
  ```
75
82
 
76
- En `<html>` va `data-theme="dark"` o `"light"`, y en el contenedor de la aplicación, `class="z-root z-canvas"`.
83
+ Put `data-theme="dark"` or `"light"` on `<html>`, and `class="z-root z-canvas"` on the application
84
+ container.
85
+
86
+ Modules with hooks, context or their own event handlers declare `"use client"`. Those that only produce
87
+ markup (`Button`, `Badge`, `Card`…) do not, so they render as Server Components.
88
+
89
+ ## Accessibility and security
77
90
 
78
- Los componentes con hooks, contexto o Radix declaran `"use client"`. Los que solo producen marcado
79
- (`Button`, `Badge`, `Card`…) no lo llevan.
91
+ - WCAG 2.2 AA contrast is measured on every change: the token build reads the color pairs these stylesheets
92
+ use and fails below 4.5:1 for text or 3:1 for non-text.
93
+ - Right-to-left works through logical properties and a mirrored keyboard, with the direction read from the
94
+ DOM. `forced-colors`, `prefers-contrast`, `prefers-reduced-motion` and `prefers-reduced-transparency`
95
+ are handled. Controls grow to 40 px with a coarse pointer.
96
+ - The framework-free mode writes application text with `textContent`, and works under a strict Content
97
+ Security Policy with Trusted Types (policy name: `zuix-zui`).
98
+ - Browsers: Chrome and Edge 116, Firefox 125, Safari 17, iOS Safari 18.3.
80
99
 
81
- ## Entradas
100
+ ## Entry points
82
101
 
83
- | Entrada | Contenido |
102
+ | Entry | Contents |
84
103
  |---|---|
85
- | `@zuccadev-labs/zuix-zui` | Componentes de React y sus tipos `*Props` |
86
- | `@zuccadev-labs/zuix-zui/dom` | Comportamiento sin framework: `init`, `hydrate`, `toast`, `confirm`… |
87
- | `@zuccadev-labs/zuix-zui/styles.css` | Todos los estilos |
88
- | `@zuccadev-labs/zuix-zui/styles/*` | Hojas sueltas por grupo |
89
- | `@zuccadev-labs/zuix-zui/manifest.json` | Componentes, props, clases y ejemplos, para herramientas y agentes |
90
- | `@zuccadev-labs/zuix-zui/html.json` | Marcado de cada ejemplo |
91
- | `@zuccadev-labs/zuix-zui/dist/zui.css`, `@zuccadev-labs/zuix-zui/dist/zui.dom.js` | Bundles para enlazar sin bundler |
104
+ | `@zuccadev-labs/zuix-zui` | React components and their `*Props` types |
105
+ | `@zuccadev-labs/zuix-zui/dom` | Framework-free behavior: `init`, `destroy`, `hydrate`, `toast`, `confirm`… |
106
+ | `@zuccadev-labs/zuix-zui/dom/carousel-gl` | WebGL mode of the carousel, loaded on demand |
107
+ | `@zuccadev-labs/zuix-zui/styles.css` | All the styles |
108
+ | `@zuccadev-labs/zuix-zui/styles/*` | Single stylesheets per group |
109
+ | `@zuccadev-labs/zuix-zui/manifest.json` | Components, props, classes and examples, for tools and agents |
110
+ | `@zuccadev-labs/zuix-zui/html.json` | The markup of every example |
111
+ | `@zuccadev-labs/zuix-zui/dist/zui.css`, `@zuccadev-labs/zuix-zui/dist/zui.dom.js` | Bundles to link without a bundler |
112
+
113
+ ## Rules
114
+
115
+ 1. Components only read tokens: no literal colors, radii or shadows.
116
+ 2. Icons are requested by name; emojis are not used as icons.
117
+ 3. If a variant, a token or an icon is missing, it is added to the system.
118
+
119
+ ## Documentation
92
120
 
93
- ## Reglas
121
+ The guides are written in Spanish.
94
122
 
95
- 1. Los componentes solo leen tokens: sin colores, radios ni sombras literales.
96
- 2. Los iconos se piden por nombre; no se usan emojis como iconos.
97
- 3. Si falta una variante, un token o un icono, se añade al sistema.
123
+ - [Components guide](https://github.com/zuccadev-labs/zuix/blob/main/docs/users/03-zui.md)
124
+ - [Using zuix with other frameworks, or with none](https://github.com/zuccadev-labs/zuix/blob/main/docs/users/06-frameworks.md)
125
+ - [Upgrading from 0.1 to 0.2](https://github.com/zuccadev-labs/zuix/blob/main/docs/users/08-actualizar-de-0-1-a-0-2.md)
126
+ - [Accessibility](https://github.com/zuccadev-labs/zuix/blob/main/docs/users/09-accesibilidad.md) and [CSP and Trusted Types](https://github.com/zuccadev-labs/zuix/blob/main/docs/users/11-csp-y-trusted-types.md)
127
+ - [Public contract](https://github.com/zuccadev-labs/zuix/blob/main/docs/package/03-contrato-publico.md): what counts as public surface
128
+ - [Changelog](https://github.com/zuccadev-labs/zuix/blob/main/zui/CHANGELOG.md)
129
+ - Rules for AI agents: `AGENTS.md`, included in the package. Third-party notices: `THIRD_PARTY_NOTICES.md`.
98
130
 
99
- ## Documentación
131
+ ## Español
100
132
 
101
- - [Guía de componentes](https://github.com/zuccadev-labs/zuix/blob/main/docs/users/03-zui.md)
102
- - [Uso con otros frameworks o sin ninguno](https://github.com/zuccadev-labs/zuix/blob/main/docs/users/06-frameworks.md)
103
- - [Contrato público](https://github.com/zuccadev-labs/zuix/blob/main/docs/package/03-contrato-publico.md): qué es superficie pública
104
- - [Cambios](https://github.com/zuccadev-labs/zuix/blob/main/zui/CHANGELOG.md)
105
- - Reglas para agentes de IA: `AGENTS.md`, incluido en el paquete.
133
+ Sistema de componentes de la suite zuix: 64 componentes sobre un contrato de HTML y CSS, sin bibliotecas de
134
+ UI de terceros. La guía está en español en [`docs/users/03-zui.md`](https://github.com/zuccadev-labs/zuix/blob/main/docs/users/03-zui.md).
106
135
 
107
- ## Licencia
136
+ ## License
108
137
 
109
138
  [MIT](https://github.com/zuccadev-labs/zuix/blob/main/LICENSE).