orbital-ds 0.41.0 → 0.48.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 (321) hide show
  1. package/AGENTS.md +54 -12
  2. package/CHANGELOG.md +458 -0
  3. package/README.md +2 -2
  4. package/components.manifest.json +6630 -3569
  5. package/dist/hooks/use-esc-close-stack.js +38 -0
  6. package/dist/hooks/use-simulated-progress.js +30 -0
  7. package/dist/lib/brand-allowlist.js +703 -0
  8. package/dist/lib/brand-runtime.js +85 -0
  9. package/dist/lib/echarts-presets.js +152 -1
  10. package/dist/lib/echarts-setup.js +2 -0
  11. package/dist/lib/format.js +177 -0
  12. package/dist/lib/i18n.js +35 -2
  13. package/dist/lib/locales/de.js +536 -0
  14. package/dist/lib/locales/fr.js +536 -0
  15. package/dist/lib/locales/he.js +536 -0
  16. package/dist/lib/locales/it.js +536 -0
  17. package/dist/ui/auth-form.js +13 -6
  18. package/dist/ui/ayuda.js +4 -1
  19. package/dist/ui/breadcrumb.js +1 -1
  20. package/dist/ui/calendar.js +3 -0
  21. package/dist/ui/carousel.js +10 -5
  22. package/dist/ui/context-menu.js +3 -3
  23. package/dist/ui/cta-banner.js +63 -0
  24. package/dist/ui/date-time.js +55 -0
  25. package/dist/ui/description-list.js +86 -0
  26. package/dist/ui/detail-panel.js +2 -2
  27. package/dist/ui/dropdown-menu.js +1 -1
  28. package/dist/ui/faq.js +25 -0
  29. package/dist/ui/feature-grid.js +40 -0
  30. package/dist/ui/hero.js +145 -0
  31. package/dist/ui/landing-section.js +59 -0
  32. package/dist/ui/mfa-challenge.js +1 -1
  33. package/dist/ui/next-step-card.js +92 -0
  34. package/dist/ui/page-header.js +20 -11
  35. package/dist/ui/pagination.js +2 -2
  36. package/dist/ui/pricing-table.js +86 -0
  37. package/dist/ui/quantity.js +27 -0
  38. package/dist/ui/sheet.js +6 -2
  39. package/dist/ui/sidebar.js +7 -3
  40. package/dist/ui/tag-input.js +169 -0
  41. package/dist/ui/testimonial.js +61 -0
  42. package/dist/ui/textarea.js +7 -1
  43. package/dist/ui/usage-meter.js +116 -0
  44. package/dist/ui/week-strip.js +2 -2
  45. package/docs/adr/0001-rtl-clases-logicas.md +14 -1
  46. package/docs/designer/flujo.md +1 -1
  47. package/docs/designer/patrones.md +45 -1
  48. package/manifest/actions.json +364 -0
  49. package/manifest/agents.json +399 -0
  50. package/manifest/ai.json +128 -0
  51. package/manifest/auth.json +1547 -0
  52. package/manifest/chat.json +612 -0
  53. package/manifest/content.json +2793 -0
  54. package/manifest/data.json +2802 -0
  55. package/manifest/feedback.json +1005 -0
  56. package/manifest/forms.json +1954 -0
  57. package/manifest/motion.json +196 -0
  58. package/manifest/navigation.json +1792 -0
  59. package/manifest/overlays.json +934 -0
  60. package/package.json +240 -238
  61. package/scripts/cli.mjs +124 -8
  62. package/scripts/doctor.mjs +153 -2
  63. package/scripts/eslint-plugin.mjs +125 -0
  64. package/scripts/i18n.mjs +1 -1
  65. package/scripts/manifest.mjs +179 -7
  66. package/scripts/upgrade.mjs +126 -0
  67. package/skill/SKILL.md +8 -3
  68. package/dist/hooks/use-ds-messages.d.ts +0 -537
  69. package/dist/hooks/use-ds-motion.d.ts +0 -17
  70. package/dist/hooks/use-in-view.d.ts +0 -9
  71. package/dist/hooks/use-mobile.d.ts +0 -3
  72. package/dist/lib/a2ui-catalog.d.ts +0 -42
  73. package/dist/lib/a2ui.d.ts +0 -289
  74. package/dist/lib/ai-events.d.ts +0 -15
  75. package/dist/lib/auth-better-auth.d.ts +0 -29
  76. package/dist/lib/auth-flow.d.ts +0 -85
  77. package/dist/lib/auth-providers.d.ts +0 -194
  78. package/dist/lib/auth.d.ts +0 -68
  79. package/dist/lib/echarts-presets.d.ts +0 -227
  80. package/dist/lib/echarts-server.d.ts +0 -15
  81. package/dist/lib/echarts-setup.d.ts +0 -8
  82. package/dist/lib/echarts-theme.d.ts +0 -36
  83. package/dist/lib/header-control.d.ts +0 -4
  84. package/dist/lib/i18n.d.ts +0 -545
  85. package/dist/lib/image-upload.d.ts +0 -41
  86. package/dist/lib/motion.d.ts +0 -74
  87. package/dist/lib/presets.d.ts +0 -8
  88. package/dist/lib/template-syntax.d.ts +0 -22
  89. package/dist/lib/utils.d.ts +0 -5
  90. package/dist/motion.css +0 -146
  91. package/dist/styles.css +0 -1737
  92. package/dist/themes/chocolate.css +0 -259
  93. package/dist/themes/chocolate.fonts.css +0 -2
  94. package/dist/themes/chocolate.guide.md +0 -30
  95. package/dist/themes/chocolate.meta.json +0 -61
  96. package/dist/themes/chocolate.scoped.css +0 -259
  97. package/dist/themes/chocolate.tokens.json +0 -49
  98. package/dist/themes/fractalia.css +0 -556
  99. package/dist/themes/fractalia.fonts.css +0 -3
  100. package/dist/themes/fractalia.guide.md +0 -86
  101. package/dist/themes/fractalia.meta.json +0 -112
  102. package/dist/themes/fractalia.scoped.css +0 -556
  103. package/dist/themes/fractalia.tokens.json +0 -39
  104. package/dist/themes/friendly.css +0 -375
  105. package/dist/themes/friendly.fonts.css +0 -2
  106. package/dist/themes/friendly.guide.md +0 -38
  107. package/dist/themes/friendly.meta.json +0 -82
  108. package/dist/themes/friendly.scoped.css +0 -375
  109. package/dist/themes/friendly.tokens.json +0 -45
  110. package/dist/themes/lagoon.css +0 -362
  111. package/dist/themes/lagoon.fonts.css +0 -2
  112. package/dist/themes/lagoon.guide.md +0 -47
  113. package/dist/themes/lagoon.meta.json +0 -85
  114. package/dist/themes/lagoon.scoped.css +0 -362
  115. package/dist/themes/lagoon.tokens.json +0 -49
  116. package/dist/themes/liquid.css +0 -510
  117. package/dist/themes/liquid.fonts.css +0 -7
  118. package/dist/themes/liquid.guide.md +0 -82
  119. package/dist/themes/liquid.meta.json +0 -134
  120. package/dist/themes/liquid.scoped.css +0 -510
  121. package/dist/themes/liquid.tokens.json +0 -47
  122. package/dist/themes/matcha.css +0 -259
  123. package/dist/themes/matcha.fonts.css +0 -2
  124. package/dist/themes/matcha.guide.md +0 -30
  125. package/dist/themes/matcha.meta.json +0 -61
  126. package/dist/themes/matcha.scoped.css +0 -259
  127. package/dist/themes/matcha.tokens.json +0 -49
  128. package/dist/themes/qratia.css +0 -264
  129. package/dist/themes/qratia.fonts.css +0 -2
  130. package/dist/themes/qratia.guide.md +0 -34
  131. package/dist/themes/qratia.meta.json +0 -49
  132. package/dist/themes/qratia.scoped.css +0 -264
  133. package/dist/themes/qratia.tokens.json +0 -49
  134. package/dist/themes/stone.css +0 -263
  135. package/dist/themes/stone.fonts.css +0 -2
  136. package/dist/themes/stone.guide.md +0 -30
  137. package/dist/themes/stone.meta.json +0 -47
  138. package/dist/themes/stone.scoped.css +0 -263
  139. package/dist/themes/stone.tokens.json +0 -49
  140. package/dist/themes/tactile.css +0 -596
  141. package/dist/themes/tactile.fonts.css +0 -3
  142. package/dist/themes/tactile.guide.md +0 -82
  143. package/dist/themes/tactile.meta.json +0 -182
  144. package/dist/themes/tactile.scoped.css +0 -596
  145. package/dist/themes/tactile.tokens.json +0 -42
  146. package/dist/themes/twitter.css +0 -364
  147. package/dist/themes/twitter.fonts.css +0 -6
  148. package/dist/themes/twitter.guide.md +0 -35
  149. package/dist/themes/twitter.meta.json +0 -90
  150. package/dist/themes/twitter.scoped.css +0 -364
  151. package/dist/themes/twitter.tokens.json +0 -45
  152. package/dist/themes/y2k.css +0 -259
  153. package/dist/themes/y2k.fonts.css +0 -2
  154. package/dist/themes/y2k.guide.md +0 -30
  155. package/dist/themes/y2k.meta.json +0 -59
  156. package/dist/themes/y2k.scoped.css +0 -259
  157. package/dist/themes/y2k.tokens.json +0 -49
  158. package/dist/themes/zyro.css +0 -442
  159. package/dist/themes/zyro.fonts.css +0 -2
  160. package/dist/themes/zyro.guide.md +0 -33
  161. package/dist/themes/zyro.meta.json +0 -74
  162. package/dist/themes/zyro.scoped.css +0 -442
  163. package/dist/themes/zyro.tokens.json +0 -46
  164. package/dist/ui/a2ui-renderer.d.ts +0 -33
  165. package/dist/ui/accordion.d.ts +0 -9
  166. package/dist/ui/agent-events.d.ts +0 -32
  167. package/dist/ui/ai-tag.d.ts +0 -8
  168. package/dist/ui/alert-dialog.d.ts +0 -23
  169. package/dist/ui/alert.d.ts +0 -13
  170. package/dist/ui/animated-number.d.ts +0 -9
  171. package/dist/ui/app-bar.d.ts +0 -10
  172. package/dist/ui/aspect-ratio.d.ts +0 -7
  173. package/dist/ui/attachment.d.ts +0 -26
  174. package/dist/ui/auth-backdrop.d.ts +0 -20
  175. package/dist/ui/auth-form.d.ts +0 -113
  176. package/dist/ui/auth-layout.d.ts +0 -72
  177. package/dist/ui/auth-parts.d.ts +0 -43
  178. package/dist/ui/auth-status.d.ts +0 -23
  179. package/dist/ui/avatar.d.ts +0 -16
  180. package/dist/ui/ayuda.d.ts +0 -22
  181. package/dist/ui/badge.d.ts +0 -15
  182. package/dist/ui/banner.d.ts +0 -14
  183. package/dist/ui/bottom-nav.d.ts +0 -15
  184. package/dist/ui/breadcrumb.d.ts +0 -12
  185. package/dist/ui/bubble.d.ts +0 -19
  186. package/dist/ui/button-group.d.ts +0 -15
  187. package/dist/ui/button.d.ts +0 -14
  188. package/dist/ui/calendar.d.ts +0 -15
  189. package/dist/ui/card-stack.d.ts +0 -9
  190. package/dist/ui/card.d.ts +0 -28
  191. package/dist/ui/carousel.d.ts +0 -33
  192. package/dist/ui/chain-of-thought.d.ts +0 -19
  193. package/dist/ui/chart-card.d.ts +0 -28
  194. package/dist/ui/chart.d.ts +0 -46
  195. package/dist/ui/chart.js +0 -254
  196. package/dist/ui/chat-composer.d.ts +0 -39
  197. package/dist/ui/checkbox.d.ts +0 -6
  198. package/dist/ui/choice-card.d.ts +0 -16
  199. package/dist/ui/code-block.d.ts +0 -14
  200. package/dist/ui/collapsible.d.ts +0 -8
  201. package/dist/ui/combobox.d.ts +0 -26
  202. package/dist/ui/command-palette.d.ts +0 -36
  203. package/dist/ui/command.d.ts +0 -22
  204. package/dist/ui/confirm-action.d.ts +0 -18
  205. package/dist/ui/confirm-dialog.d.ts +0 -21
  206. package/dist/ui/connected-accounts.d.ts +0 -25
  207. package/dist/ui/content-card.d.ts +0 -52
  208. package/dist/ui/context-menu.d.ts +0 -31
  209. package/dist/ui/conversation-list.d.ts +0 -24
  210. package/dist/ui/copy-button.d.ts +0 -14
  211. package/dist/ui/data-table.d.ts +0 -198
  212. package/dist/ui/date-picker.d.ts +0 -65
  213. package/dist/ui/detail-panel.d.ts +0 -16
  214. package/dist/ui/dialog.d.ts +0 -19
  215. package/dist/ui/direction.d.ts +0 -1
  216. package/dist/ui/dock.d.ts +0 -13
  217. package/dist/ui/drawer.d.ts +0 -18
  218. package/dist/ui/dropdown-menu.d.ts +0 -31
  219. package/dist/ui/dropzone.d.ts +0 -44
  220. package/dist/ui/echart.d.ts +0 -31
  221. package/dist/ui/empty-state.d.ts +0 -26
  222. package/dist/ui/empty.d.ts +0 -15
  223. package/dist/ui/entity-list.d.ts +0 -25
  224. package/dist/ui/error-page.d.ts +0 -28
  225. package/dist/ui/error-state.d.ts +0 -16
  226. package/dist/ui/eyebrow.d.ts +0 -7
  227. package/dist/ui/field.d.ts +0 -28
  228. package/dist/ui/file-upload.d.ts +0 -42
  229. package/dist/ui/filter-bar.d.ts +0 -38
  230. package/dist/ui/form-layout.d.ts +0 -19
  231. package/dist/ui/gauge.d.ts +0 -40
  232. package/dist/ui/generated-image.d.ts +0 -14
  233. package/dist/ui/generated-table.d.ts +0 -11
  234. package/dist/ui/heatmap-grid.d.ts +0 -39
  235. package/dist/ui/hover-card.d.ts +0 -8
  236. package/dist/ui/i18n-provider.d.ts +0 -11
  237. package/dist/ui/icon-tile.d.ts +0 -11
  238. package/dist/ui/input-group.d.ts +0 -22
  239. package/dist/ui/input-otp.d.ts +0 -13
  240. package/dist/ui/input.d.ts +0 -5
  241. package/dist/ui/instruction-editor.d.ts +0 -64
  242. package/dist/ui/item.d.ts +0 -26
  243. package/dist/ui/kbd.d.ts +0 -6
  244. package/dist/ui/label.d.ts +0 -5
  245. package/dist/ui/legend.d.ts +0 -32
  246. package/dist/ui/level-meter.d.ts +0 -16
  247. package/dist/ui/load-more.d.ts +0 -19
  248. package/dist/ui/loading-state.d.ts +0 -14
  249. package/dist/ui/locale-switcher.d.ts +0 -19
  250. package/dist/ui/markdown.d.ts +0 -14
  251. package/dist/ui/marker.d.ts +0 -13
  252. package/dist/ui/media-card.d.ts +0 -13
  253. package/dist/ui/menubar.d.ts +0 -31
  254. package/dist/ui/message-actions.d.ts +0 -12
  255. package/dist/ui/message-scroller.d.ts +0 -16
  256. package/dist/ui/message.d.ts +0 -12
  257. package/dist/ui/mfa-challenge.d.ts +0 -33
  258. package/dist/ui/mfa-setup.d.ts +0 -29
  259. package/dist/ui/mosaic.d.ts +0 -15
  260. package/dist/ui/motion-provider.d.ts +0 -11
  261. package/dist/ui/native-select.d.ts +0 -10
  262. package/dist/ui/navigation-menu.d.ts +0 -15
  263. package/dist/ui/notice-review.d.ts +0 -32
  264. package/dist/ui/notifications.d.ts +0 -81
  265. package/dist/ui/oauth-consent.d.ts +0 -54
  266. package/dist/ui/page-header.d.ts +0 -22
  267. package/dist/ui/page-loader.d.ts +0 -23
  268. package/dist/ui/page-shell.d.ts +0 -8
  269. package/dist/ui/pagination.d.ts +0 -22
  270. package/dist/ui/panel.d.ts +0 -12
  271. package/dist/ui/passkey-list.d.ts +0 -17
  272. package/dist/ui/password-input.d.ts +0 -5
  273. package/dist/ui/password-strength.d.ts +0 -14
  274. package/dist/ui/popover.d.ts +0 -12
  275. package/dist/ui/progress.d.ts +0 -9
  276. package/dist/ui/proportion-bar.d.ts +0 -27
  277. package/dist/ui/questionnaire.d.ts +0 -24
  278. package/dist/ui/radio-group.d.ts +0 -8
  279. package/dist/ui/reasoning.d.ts +0 -10
  280. package/dist/ui/resizable.d.ts +0 -10
  281. package/dist/ui/reveal.d.ts +0 -11
  282. package/dist/ui/scroll-area.d.ts +0 -7
  283. package/dist/ui/search-box.d.ts +0 -32
  284. package/dist/ui/select.d.ts +0 -19
  285. package/dist/ui/separator.d.ts +0 -6
  286. package/dist/ui/session-list.d.ts +0 -19
  287. package/dist/ui/session-timeout.d.ts +0 -13
  288. package/dist/ui/sheet.d.ts +0 -16
  289. package/dist/ui/shield.d.ts +0 -21
  290. package/dist/ui/show-more.d.ts +0 -12
  291. package/dist/ui/sidebar.d.ts +0 -90
  292. package/dist/ui/sign-out-dialog.d.ts +0 -17
  293. package/dist/ui/skeleton.d.ts +0 -10
  294. package/dist/ui/slider.d.ts +0 -23
  295. package/dist/ui/sonner.d.ts +0 -6
  296. package/dist/ui/sparkline.d.ts +0 -26
  297. package/dist/ui/spinner.d.ts +0 -5
  298. package/dist/ui/stat-group.d.ts +0 -8
  299. package/dist/ui/stat.d.ts +0 -90
  300. package/dist/ui/status-badge.d.ts +0 -39
  301. package/dist/ui/status-hero.d.ts +0 -12
  302. package/dist/ui/step-dots.d.ts +0 -10
  303. package/dist/ui/step-flow.d.ts +0 -48
  304. package/dist/ui/step-ring.d.ts +0 -12
  305. package/dist/ui/stepper.d.ts +0 -20
  306. package/dist/ui/suggestions.d.ts +0 -8
  307. package/dist/ui/switch.d.ts +0 -8
  308. package/dist/ui/table.d.ts +0 -12
  309. package/dist/ui/tabs.d.ts +0 -14
  310. package/dist/ui/task-loader.d.ts +0 -14
  311. package/dist/ui/task-progress.d.ts +0 -18
  312. package/dist/ui/textarea.d.ts +0 -11
  313. package/dist/ui/theme-toggle.d.ts +0 -14
  314. package/dist/ui/timeline.d.ts +0 -29
  315. package/dist/ui/toast.d.ts +0 -19
  316. package/dist/ui/toggle-group.d.ts +0 -14
  317. package/dist/ui/toggle.d.ts +0 -12
  318. package/dist/ui/tool-call.d.ts +0 -15
  319. package/dist/ui/tooltip.d.ts +0 -9
  320. package/dist/ui/week-strip.d.ts +0 -12
  321. package/dist/ui/workflow-run.d.ts +0 -23
package/AGENTS.md CHANGED
@@ -3,7 +3,7 @@
3
3
  Sistema de diseño: **estructura común + temas + componentes** sobre Base UI y Tailwind v4.
4
4
  Todo está pensado para que un agente pueda usarlo, ampliarlo y comprobar su trabajo sin
5
5
  adivinar. Lee antes: `README.md`, `docs/CONTRACT.md`, `contract.json` y
6
- `components.manifest.json` (qué componentes hay, cómo se importan y qué `data-slot` exponen).
6
+ `components.manifest.json` (índice para ELEGIR: qué componentes hay, su `group`, su `summary` —qué es y cuándo usarlo—, sus alternativas `see`, cómo se importan y qué `data-slot` exponen; `orbital-ds components --search <intención>` busca en él) y, **por dominio**, `manifest/<dominio>.json` o `orbital-ds components --group <dominio>` (sus **props propias con tipo, valores y si son obligatorias**, notas y **ejemplos mínimos para copiar**: úsalos, no inventes props; `orbital-ds doctor --ui src` avisa de `asChild`, valores fuera de la unión y nombres casi iguales).
7
7
 
8
8
  ## Reglas (obligatorias)
9
9
 
@@ -81,8 +81,8 @@ adivinar. Lee antes: `README.md`, `docs/CONTRACT.md`, `contract.json` y
81
81
 
82
82
  ## Gráficos e informes (Apache ECharts)
83
83
 
84
- - **Librería oficial: ECharts** (dependencia opcional). `chart.tsx` (Recharts) se mantiene por compatibilidad,
85
- sin nuevas funciones.
84
+ - **Librería única: ECharts** (dependencia opcional). `chart.tsx` (Recharts) se retiró en 0.48.0; el doctor (`--ui`)
85
+ marca como error un import de `orbital-ds/ui/chart`.
86
86
  - **El tema gobierna el gráfico**: `<EChart option={…} />` (`orbital-ds/ui/echart`) monta un tema de ECharts
87
87
  desde las variables del tema activo y de la marca (paleta `--chart-1…5` + estados, textos, ejes, tooltip,
88
88
  fuentes, ritmo) y se repinta al cambiar de tema o de piel. SVG por defecto; `exportable` descarga SVG/PNG.
@@ -106,9 +106,9 @@ adivinar. Lee antes: `README.md`, `docs/CONTRACT.md`, `contract.json` y
106
106
 
107
107
  - Los textos PROPIOS de los componentes (cerrar, cargando, paginación, carrusel, lateral,
108
108
  cuestionario…) salen de `useDsMessages()` y sus catálogos (`orbital-ds/lib/i18n`: en, es,
109
- pt-BR). **Ningún componente escribe un texto visible o accesible a mano**: el doctor lo rechaza
109
+ pt-BR, fr, it, de y he; los cuatro últimos en `src/lib/locales/<idioma>.ts`). **Ningún componente escribe un texto visible o accesible a mano**: el doctor lo rechaza
110
110
  (`aria-label="…"`, `sr-only`, `?? "…"`, `title="…"`).
111
- - Un texto nuevo = una clave nueva en los TRES catálogos (el tipo obliga a tenerla en todos).
111
+ - Un texto nuevo = una clave nueva en TODOS los catálogos (el tipo obliga a tenerla en todos).
112
112
  - La app pasa su idioma una vez: `<DsI18nProvider locale={i18n.language}>` (con i18next,
113
113
  `useTranslation().i18n.language`). Un texto concreto se sobrescribe con `messages`. Sin
114
114
  provider, inglés. Otro idioma cae a su base (`es-CO` → `es`) o al inglés.
@@ -121,13 +121,16 @@ adivinar. Lee antes: `README.md`, `docs/CONTRACT.md`, `contract.json` y
121
121
  los idiomas de la app y ejecuta `pnpm exec orbital-ds-i18n`. Si orbital-ds no trae ese idioma, deja
122
122
  el inglés y LISTA las claves pendientes: tradúcelas en el JSON hasta que `--check` pase.
123
123
  - **RTL**: `dsDirection(idioma)` (`orbital-ds/lib/i18n`) da `ltr`/`rtl`; la app lo pone en `<html dir>` y
124
- `DsI18nProvider` lo pasa a Base UI. La conversión de los componentes a clases lógicas
125
- (`ms-`/`ps-`/`start-`/`text-start` en lugar de `ml-`/`pl-`/`left-`/`text-left`) es una fase pendiente: decisión y plan en `docs/adr/0001-rtl-clases-logicas.md`.
124
+ `DsI18nProvider` lo pasa a Base UI. Los componentes usan clases lógicas (`ms-`/`ps-`/`start-`/`text-start`; el doctor
125
+ rechaza las físicas), las flechas de dirección llevan `rtl:rotate-180` y `Sheet`/`Sidebar`/`DetailPanel` usan por defecto
126
+ `side="start"` (lateral) o `"end"` (paneles), que siguen la lectura (`left`/`right` son físicos); los menús contextuales salen hacia `inline-end`. Lo que dibuja el navegador (lista de `<select>`, calendario nativo) sigue
127
+ el modo claro/oscuro del tema por `color-scheme`. Decisión: `docs/adr/0001-rtl-clases-logicas.md`.
126
128
 
127
129
  ## Instalar en una app
128
130
 
129
131
  **Orden única: `pnpm exec orbital-ds`** (menú) · `orbital-ds init` (configuración inicial) · `orbital-ds theme [tema]`
130
- (cambiar de tema conservando marca y extras) · `orbital-ds doctor` · `orbital-ds i18n` · `orbital-ds help [orden]`.
132
+ (cambiar de tema conservando marca y extras) · `orbital-ds doctor` · `orbital-ds i18n` · `orbital-ds upgrade` (qué cambió desde
133
+ tu versión anterior y qué revisar) · `orbital-ds help [orden]`.
131
134
  Las órdenes sueltas (`orbital-ds-init`, `-doctor`, `-i18n`) siguen valiendo como atajos.
132
135
 
133
136
  `orbital-ds init` (= `pnpm exec orbital-ds-init`): elige tema (enseña su ficha: esencia, paleta, gesto, excepciones de
@@ -175,8 +178,8 @@ en cualquier proyecto. Vocabulario común en `src/lib/presets.ts` (`DsDensity`,
175
178
  4. **El diseño sigue el ancho del contenedor** (container query), no el dispositivo ni la presentación.
176
179
  5. **Aviso en desarrollo** (`dsWarn`, mensaje en inglés) si la combinación no cuadra.
177
180
  6. **Ganchos del DOM**: `data-slot` y `data-preset` (más `data-presentation`/`data-density` si aplica).
178
- 7. **Un `@note`** que diga cuándo usar cada preset. Catálogo hoy: `Sidebar` (app · workspace · admin · focus, con `density`), `ChartCard` (glance · standard · focus · dense), `ContentCard` (basic · feature · media · horizontal, con `emphasis` elevated · outlined · filled · ghost), `Mosaic` (even · bento · trio), `PageShell` (content · detail · canvas), `PageHeader` (page · compact · canvas), `FilterBar` (inline · compact · stacked), `DataTable` (browse · manage · compact · grouped · tree), `LoadingState` (list · card · table · detail), `PageLoader` (splash · route · section · overlay), `CommandPalette` (go · actions · search), `FileUpload` (drop · button), `ErrorPage` (not-found · forbidden · server-error · offline · maintenance, con `tone` neutral · playful), `DetailPanel` (side · bottom · full), `EntityList` (list · grid · compact), `StepFlow` (quick · activation · long), `FormLayout`
179
- (inline · sectioned · settings), `NoticeReview` (read · acknowledge · resolve · respond), `EmptyState` (first-use · no-results · error · forbidden), `StatGroup` (overview ·
181
+ 7. **Un `@note`** que diga cuándo usar cada preset. Catálogo hoy: `Sidebar` (app · workspace · admin · focus, con `density`), `ChartCard` (glance · standard · focus · dense), `ContentCard` (basic · feature · media · horizontal, con `emphasis` elevated · outlined · filled · ghost), `Mosaic` (even · bento · trio), `Hero` (landing · split · media · section), `PageShell` (content · detail · canvas), `PageHeader` (page · compact · canvas), `FilterBar` (inline · compact · stacked), `DataTable` (browse · manage · compact · grouped · tree), `LoadingState` (list · card · table · detail), `PageLoader` (splash · route · section · overlay), `CommandPalette` (go · actions · search), `FileUpload` (drop · button), `ErrorPage` (not-found · forbidden · server-error · offline · maintenance, con `tone` neutral · playful), `DetailPanel` (side · bottom · full), `EntityList` (list · grid · compact), `StepFlow` (quick · activation · long), `FormLayout`
182
+ (inline · sectioned · settings), `NoticeReview` (read · acknowledge · resolve · respond), `EmptyState` (first-use · no-results · error · forbidden), `NextStepCard` (activate · open · resolve · inactive), `StatGroup` (overview ·
180
183
  compact · comparison · strip) `ConfirmAction` (simple · typed) y, en el acceso (P13), `AuthLayout` (centered · split · cover · banner · minimal),
181
184
  `AuthForm` (sign-in · social · sign-up · magic-link · email-code · sso · forgot-password · reset-password),
182
185
  `MfaChallenge` (totp · sms · email · backup-code · passkey), `MfaSetup` (totp · sms · backup-codes), `OAuthConsent`
@@ -186,6 +189,37 @@ en cualquier proyecto. Vocabulario común en `src/lib/presets.ts` (`DsDensity`,
186
189
 
187
190
  **Densidad global.** `--ds-density` (1 por defecto; 0.8 más denso, 1.2 más aireado) escala el relleno de celdas y la separación de secciones y listas; la app lo ajusta en `brand.css`.
188
191
 
192
+ ## Paneles de servicio y valores con unidad (0.42)
193
+
194
+ - **Nunca formatees a mano** un valor con unidad, una fecha o un «hace 5 minutos»: `Quantity` (unidades UCUM: `By`,
195
+ `GBy`, `%`, `d`, `{device}`; `system="binary"` para GiB), `DateTime` y `RelativeTime` (`orbital-ds/ui/date-time`),
196
+ o sus funciones en `orbital-ds/lib/format` fuera de React. Un nulo es «sin dato», nunca 0.
197
+ - **Uso frente a lo contratado**: `UsageMeter` (avisa al 80 %, crítico al 100 %, `limit={null}` = ilimitado). Nunca una
198
+ barra a mano. **Límites y atributos**: `DescriptionList`. **Estado y siguiente paso**: `NextStepCard`
199
+ (`activate` · `open` · `resolve` · `inactive`). Receta completa: P14 en `docs/designer/patrones.md`.
200
+ - `PageHeader` y `SectionHeader` aceptan `title`, `description` y `actions` como props (atajo de las piezas).
201
+
202
+ ## Webs públicas y portadas (0.46)
203
+
204
+ - **Portada**: `Hero` (P15). **Debajo**, cada bloque dentro de `LandingSection` (antetítulo, título, texto y acción; mismo
205
+ ancho y ritmo): `FeatureGrid`/`Feature`, `Testimonial`/`TestimonialGrid`, `PricingTable`/`PricingPlan`/`PricingFeature`,
206
+ `Faq` (sobre Accordion; `structuredData` = JSON-LD FAQPage) y `CtaBanner` al pie. Siguen el ancho del contenedor;
207
+ medidas en `--ds-landing-*`, `--ds-pricing-*`, `--ds-testimonial-*` y `--ds-cta-*`. Todo el texto lo pone la app.
208
+ - **Hooks**: `useSimulatedProgress(activo, { expectedMs })` (`orbital-ds/hooks/use-simulated-progress`) da un 0–100 creíble
209
+ cuando la tarea no informa de su avance; `useEscCloseStack(open, onClose)` (`orbital-ds/hooks/use-esc-close-stack`) hace
210
+ que Escape cierre solo la capa propia de arriba (Dialog, Sheet, Popover y Menu ya lo resuelven con Base UI).
211
+
212
+ ## Marca en datos (0.47)
213
+
214
+ - **Una app que guarda su marca en base de datos** (por cliente, desde un panel de ajustes) la valida y la pinta con
215
+ `orbital-ds/lib/brand-runtime`: `validateBrandTokens(fila, { base })` admite solo variables públicas (contrato + `--ds-*`
216
+ de la estructura, lista generada en `src/lib/brand-allowlist.ts` por `pnpm manifest`), rechaza valores que no sean un
217
+ único valor CSS seguro y mide el contraste AA de los pares que toca contra `base` (colores resueltos del tema, p. ej. de
218
+ `<tema>.tokens.json` o de su ficha). `brandTokensToCss(resultado)` da el CSS (`:root:root` y `.dark`) para un `<style>`
219
+ en el `<head>`, también en SSR; lanza si hay errores. Forma de la fila: `{ light: {…}, dark: {…} }` o un objeto plano.
220
+ - Es el mismo nivel que `brand.css`: ajusta la marca **encima** del tema. El tema se sigue eligiendo con su `@import`.
221
+ Guarda en la base de datos solo nombres públicos; nunca CSS libre.
222
+
189
223
  ## Acceso y autenticación
190
224
 
191
225
  - **Agnóstico del proveedor; Better Auth como referencia.** orbital-ds pinta, valida y anuncia; la app conecta su
@@ -203,7 +237,7 @@ Se elige el canal por **urgencia** y **persistencia**; cada app no lo decide a m
203
237
 
204
238
  | Intención | Canal | Persiste | Interrumpe |
205
239
  |---|---|---|---|
206
- | Confirmar una acción de la persona | toast (`Toaster`/`Toast`) | no | no |
240
+ | Confirmar una acción de la persona | toast (`Toaster` + `toast.add`, de `orbital-ds/ui/toast`; `sonner` solo por compatibilidad) | no | no |
207
241
  | Aviso de una sección | `Alert` | sí | no |
208
242
  | Aviso que afecta a toda la página | `Banner` | hasta resolver | no |
209
243
  | Asunto con seguimiento o decisión | campana (`NotificationCenter`) + `NoticeReview` | sí, con estado | solo si es crítico |
@@ -213,13 +247,17 @@ Mismo vocabulario en todos: tono `info | success | warning | danger` y estado `n
213
247
  `NotificationItem onSelect` abre la revisión; `NoticeReview` tiene presets `read | acknowledge | resolve | respond`
214
248
  (modal o `presentation="sheet"`).
215
249
 
250
+ **En la app, en el editor:** `import orbital from "orbital-ds/eslint"; export default [orbital.configs.recommended];` (config plana de ESLint, sin dependencias): `no-as-child`, `system-styles` (nada de colores, z-index, duraciones ni paleta Tailwind en `className`/`cn()`) `logical-direction` (clases físicas) y `logical-side` (`side="left"|"right"` en laterales, paneles y flotantes: usa `start`/`end` o `inline-start`/`inline-end`). El doctor (`--ui`) avisa de lo mismo y rechaza un lado físico por defecto en un componente del paquete.
251
+
216
252
  ## Cómo comprobar tu trabajo
217
253
 
218
254
  ```bash
219
255
  pnpm check:ds # contrato, repetidos, sombras, fugas, valores fijos, personalidad, familias, contraste y demos
220
256
  pnpm verify # doctor + typecheck + build + check:bundle
221
257
  pnpm check:charts # cada constructor de gráfico: sin colores y dibuja SVG en servidor
258
+ pnpm test # pruebas de lógica sin navegador (node:test sobre dist/: i18n, format, brand-runtime, auth-flow, plantillas, upgrade)
222
259
  pnpm check:bundle # empaqueta un consumidor de EChart (navegador y servidor) y comprueba que dibuja
260
+ pnpm domains # dominios tocados por tu rama y su lista de revisión para el PR (base: origin/main)
223
261
  pnpm manifest # regenera components.manifest.json tras añadir componentes
224
262
  pnpm showcase # escaparate: todos los componentes × todos los temas × claro/oscuro × marca
225
263
  pnpm showcase:typecheck # tipos de las demos
@@ -240,7 +278,11 @@ Si `pnpm check:ds` falla, **corrige la causa**; no lo desactives ni lo rodees.
240
278
  ## Añadir un componente
241
279
 
242
280
  1. Fichero en `src/ui/<nombre>.tsx` (un componente = un fichero; sin barril).
243
- 2. `data-slot="<nombre>"` en su raíz y en las partes relevantes.
281
+ 2. `data-slot="<nombre>"` en su raíz y en las partes relevantes. Y `/** @group <dominio> */` en la cabecera (obligatorio; uno de `actions`, `forms`, `feedback`, `overlays`, `navigation`, `data`, `content`, `motion`, `chat`, `agents`, `ai`, `auth`): va al manifiesto como `group`, y la sección de su demo en el escaparate debe ser la de ese dominio (el doctor lo comprueba).
282
+ En ese MISMO bloque, la **ficha para agentes** (obligatoria, el doctor la exige): `@summary` (una línea: qué es y cuándo
283
+ usarlo), `@see <otro> — <cuándo usar ese en su lugar>` (0–3, hacia componentes que existen) y `@example <título>` (1–3,
284
+ una idea cada uno, JSX mínimo con props reales, sin `asChild` ni comentarios JSX). Más `@note` con sus reglas de uso.
285
+ Referencia: `src/ui/button.tsx`.
244
286
  3. Solo tokens. Importa `cn` de `../lib/utils.js`; los demás componentes, de `./<otro>.js`. **Los imports relativos llevan
245
287
  siempre `.js`**: el paquete es `"type": "module"` y Node (tests, SSR sin bundler) no completa la ruta; `check:pack`
246
288
  importa cada export con Node puro.