@mgamadeus/ddd-admin-ui 0.1.0-rc.1 → 0.1.0-rc.2

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 (677) hide show
  1. package/.claude/skills/ddd-admin-ui-specialist/SKILL.md +148 -18
  2. package/CHANGELOG.md +17 -0
  3. package/README.md +196 -88
  4. package/STANDARDS.md +385 -0
  5. package/dist/components.css +167 -22
  6. package/dist/form/DrawerFooter.d.ts +18 -0
  7. package/dist/form/DrawerFooter.d.ts.map +1 -0
  8. package/dist/form/DrawerFooter.js +47 -0
  9. package/dist/form/DrawerFooter.js.map +1 -0
  10. package/dist/form/Form.d.ts +25 -10
  11. package/dist/form/Form.d.ts.map +1 -1
  12. package/dist/form/Form.js +17 -8
  13. package/dist/form/Form.js.map +1 -1
  14. package/dist/form/FormActions.d.ts +35 -0
  15. package/dist/form/FormActions.d.ts.map +1 -0
  16. package/dist/form/FormActions.js +80 -0
  17. package/dist/form/FormActions.js.map +1 -0
  18. package/dist/form/FormDrawer.d.ts +36 -0
  19. package/dist/form/FormDrawer.d.ts.map +1 -0
  20. package/dist/form/FormDrawer.js +31 -0
  21. package/dist/form/FormDrawer.js.map +1 -0
  22. package/dist/form/FormErrors.d.ts +22 -0
  23. package/dist/form/FormErrors.d.ts.map +1 -0
  24. package/dist/form/FormErrors.js +46 -0
  25. package/dist/form/FormErrors.js.map +1 -0
  26. package/dist/form/FormField.d.ts +74 -0
  27. package/dist/form/FormField.d.ts.map +1 -0
  28. package/dist/form/FormField.js +46 -0
  29. package/dist/form/FormField.js.map +1 -0
  30. package/dist/form/FormHeader.d.ts +20 -0
  31. package/dist/form/FormHeader.d.ts.map +1 -0
  32. package/dist/form/FormHeader.js +9 -0
  33. package/dist/form/FormHeader.js.map +1 -0
  34. package/dist/form/FormJumpBar.d.ts +20 -0
  35. package/dist/form/FormJumpBar.d.ts.map +1 -0
  36. package/dist/form/FormJumpBar.js +49 -0
  37. package/dist/form/FormJumpBar.js.map +1 -0
  38. package/dist/form/FormSubmitButton.d.ts +17 -0
  39. package/dist/form/FormSubmitButton.d.ts.map +1 -0
  40. package/dist/form/FormSubmitButton.js +14 -0
  41. package/dist/form/FormSubmitButton.js.map +1 -0
  42. package/dist/form/FormWrapper.d.ts +13 -0
  43. package/dist/form/FormWrapper.d.ts.map +1 -0
  44. package/dist/form/FormWrapper.js +15 -0
  45. package/dist/form/FormWrapper.js.map +1 -0
  46. package/dist/form/drawerSlots.d.ts +10 -0
  47. package/dist/form/drawerSlots.d.ts.map +1 -0
  48. package/dist/form/drawerSlots.js +7 -0
  49. package/dist/form/drawerSlots.js.map +1 -0
  50. package/dist/form/fieldLabels.d.ts +15 -8
  51. package/dist/form/fieldLabels.d.ts.map +1 -1
  52. package/dist/form/fieldLabels.js +18 -6
  53. package/dist/form/fieldLabels.js.map +1 -1
  54. package/dist/form/formPanelClasses.d.ts +3 -0
  55. package/dist/form/formPanelClasses.d.ts.map +1 -0
  56. package/dist/form/formPanelClasses.js +3 -0
  57. package/dist/form/formPanelClasses.js.map +1 -0
  58. package/dist/form/index.d.ts +57 -2
  59. package/dist/form/index.d.ts.map +1 -1
  60. package/dist/form/index.js +33 -2
  61. package/dist/form/index.js.map +1 -1
  62. package/dist/form/useConfirmDialog.d.ts +9 -0
  63. package/dist/form/useConfirmDialog.d.ts.map +1 -0
  64. package/dist/form/useConfirmDialog.js +29 -0
  65. package/dist/form/useConfirmDialog.js.map +1 -0
  66. package/dist/glass/ActionRow.d.ts +27 -0
  67. package/dist/glass/ActionRow.d.ts.map +1 -0
  68. package/dist/glass/ActionRow.js +22 -0
  69. package/dist/glass/ActionRow.js.map +1 -0
  70. package/dist/glass/CollapsibleCard.d.ts +36 -0
  71. package/dist/glass/CollapsibleCard.d.ts.map +1 -0
  72. package/dist/glass/CollapsibleCard.js +27 -0
  73. package/dist/glass/CollapsibleCard.js.map +1 -0
  74. package/dist/glass/GlassGroup.d.ts +26 -0
  75. package/dist/glass/GlassGroup.d.ts.map +1 -0
  76. package/dist/glass/GlassGroup.js +34 -0
  77. package/dist/glass/GlassGroup.js.map +1 -0
  78. package/dist/glass/GlassPill.d.ts +23 -0
  79. package/dist/glass/GlassPill.d.ts.map +1 -0
  80. package/dist/glass/GlassPill.js +20 -0
  81. package/dist/glass/GlassPill.js.map +1 -0
  82. package/dist/glass/QuickFilterPills.d.ts +38 -0
  83. package/dist/glass/QuickFilterPills.d.ts.map +1 -0
  84. package/dist/glass/QuickFilterPills.js +30 -0
  85. package/dist/glass/QuickFilterPills.js.map +1 -0
  86. package/dist/glass/index.d.ts +10 -1
  87. package/dist/glass/index.d.ts.map +1 -1
  88. package/dist/glass/index.js +6 -1
  89. package/dist/glass/index.js.map +1 -1
  90. package/dist/i18n/Translate.d.ts +5 -4
  91. package/dist/i18n/Translate.d.ts.map +1 -1
  92. package/dist/i18n/Translate.js +3 -3
  93. package/dist/i18n/Translate.js.map +1 -1
  94. package/dist/i18n/format.d.ts +13 -0
  95. package/dist/i18n/format.d.ts.map +1 -0
  96. package/dist/i18n/format.js +15 -0
  97. package/dist/i18n/format.js.map +1 -0
  98. package/dist/i18n/hints.json +130 -0
  99. package/dist/i18n/index.d.ts +5 -3
  100. package/dist/i18n/index.d.ts.map +1 -1
  101. package/dist/i18n/index.js +5 -3
  102. package/dist/i18n/index.js.map +1 -1
  103. package/dist/i18n/localeFormat.d.ts +10 -0
  104. package/dist/i18n/localeFormat.d.ts.map +1 -0
  105. package/dist/i18n/localeFormat.js +36 -0
  106. package/dist/i18n/localeFormat.js.map +1 -0
  107. package/dist/i18n/plural.d.ts +15 -0
  108. package/dist/i18n/plural.d.ts.map +1 -0
  109. package/dist/i18n/plural.js +95 -0
  110. package/dist/i18n/plural.js.map +1 -0
  111. package/dist/i18n/serverMessages.d.ts +26 -0
  112. package/dist/i18n/serverMessages.d.ts.map +1 -0
  113. package/dist/i18n/serverMessages.js +146 -0
  114. package/dist/i18n/serverMessages.js.map +1 -0
  115. package/dist/i18n/store.d.ts +28 -16
  116. package/dist/i18n/store.d.ts.map +1 -1
  117. package/dist/i18n/store.js +26 -20
  118. package/dist/i18n/store.js.map +1 -1
  119. package/dist/i18n/useTranslate.d.ts +15 -7
  120. package/dist/i18n/useTranslate.d.ts.map +1 -1
  121. package/dist/i18n/useTranslate.js +17 -7
  122. package/dist/i18n/useTranslate.js.map +1 -1
  123. package/dist/i18n-keys.json +1050 -13
  124. package/dist/list/ChipToggleGroup.d.ts +36 -0
  125. package/dist/list/ChipToggleGroup.d.ts.map +1 -0
  126. package/dist/list/ChipToggleGroup.js +34 -0
  127. package/dist/list/ChipToggleGroup.js.map +1 -0
  128. package/dist/list/Combobox.d.ts +32 -0
  129. package/dist/list/Combobox.d.ts.map +1 -0
  130. package/dist/list/Combobox.js +27 -0
  131. package/dist/list/Combobox.js.map +1 -0
  132. package/dist/list/EmptyValue.d.ts +14 -0
  133. package/dist/list/EmptyValue.d.ts.map +1 -0
  134. package/dist/list/EmptyValue.js +11 -0
  135. package/dist/list/EmptyValue.js.map +1 -0
  136. package/dist/list/EntityListBody.d.ts +27 -0
  137. package/dist/list/EntityListBody.d.ts.map +1 -0
  138. package/dist/list/EntityListBody.js +24 -0
  139. package/dist/list/EntityListBody.js.map +1 -0
  140. package/dist/list/EntityListBulkBar.d.ts +38 -0
  141. package/dist/list/EntityListBulkBar.d.ts.map +1 -0
  142. package/dist/list/EntityListBulkBar.js +19 -0
  143. package/dist/list/EntityListBulkBar.js.map +1 -0
  144. package/dist/list/EntityListCard.d.ts +22 -0
  145. package/dist/list/EntityListCard.d.ts.map +1 -0
  146. package/dist/list/EntityListCard.js +15 -0
  147. package/dist/list/EntityListCard.js.map +1 -0
  148. package/dist/list/EntityListEmpty.d.ts +13 -0
  149. package/dist/list/EntityListEmpty.d.ts.map +1 -0
  150. package/dist/list/EntityListEmpty.js +11 -0
  151. package/dist/list/EntityListEmpty.js.map +1 -0
  152. package/dist/list/EntityListGrid.d.ts +29 -0
  153. package/dist/list/EntityListGrid.d.ts.map +1 -0
  154. package/dist/list/EntityListGrid.js +21 -0
  155. package/dist/list/EntityListGrid.js.map +1 -0
  156. package/dist/list/EntityListLoadMore.d.ts +15 -0
  157. package/dist/list/EntityListLoadMore.d.ts.map +1 -0
  158. package/dist/list/EntityListLoadMore.js +27 -0
  159. package/dist/list/EntityListLoadMore.js.map +1 -0
  160. package/dist/list/EntityListStatus.d.ts +11 -0
  161. package/dist/list/EntityListStatus.d.ts.map +1 -0
  162. package/dist/list/EntityListStatus.js +22 -0
  163. package/dist/list/EntityListStatus.js.map +1 -0
  164. package/dist/list/EntityListTable.d.ts +34 -0
  165. package/dist/list/EntityListTable.d.ts.map +1 -0
  166. package/dist/list/EntityListTable.js +43 -0
  167. package/dist/list/EntityListTable.js.map +1 -0
  168. package/dist/list/EntityListToolbar.d.ts +39 -0
  169. package/dist/list/EntityListToolbar.d.ts.map +1 -0
  170. package/dist/list/EntityListToolbar.js +25 -0
  171. package/dist/list/EntityListToolbar.js.map +1 -0
  172. package/dist/list/EntityListViewToggle.d.ts +17 -0
  173. package/dist/list/EntityListViewToggle.d.ts.map +1 -0
  174. package/dist/list/EntityListViewToggle.js +38 -0
  175. package/dist/list/EntityListViewToggle.js.map +1 -0
  176. package/dist/list/MultiSelect.d.ts +33 -0
  177. package/dist/list/MultiSelect.d.ts.map +1 -0
  178. package/dist/list/MultiSelect.js +60 -0
  179. package/dist/list/MultiSelect.js.map +1 -0
  180. package/dist/list/SearchField.d.ts +24 -0
  181. package/dist/list/SearchField.d.ts.map +1 -0
  182. package/dist/list/SearchField.js +42 -0
  183. package/dist/list/SearchField.js.map +1 -0
  184. package/dist/list/StatusBadge.d.ts +34 -0
  185. package/dist/list/StatusBadge.d.ts.map +1 -0
  186. package/dist/list/StatusBadge.js +44 -0
  187. package/dist/list/StatusBadge.js.map +1 -0
  188. package/dist/list/Tag.d.ts +16 -0
  189. package/dist/list/Tag.d.ts.map +1 -0
  190. package/dist/list/Tag.js +15 -0
  191. package/dist/list/Tag.js.map +1 -0
  192. package/dist/list/cells.d.ts +53 -0
  193. package/dist/list/cells.d.ts.map +1 -0
  194. package/dist/list/cells.js +62 -0
  195. package/dist/list/cells.js.map +1 -0
  196. package/dist/list/filterClasses.d.ts +8 -0
  197. package/dist/list/filterClasses.d.ts.map +1 -0
  198. package/dist/list/filterClasses.js +8 -0
  199. package/dist/list/filterClasses.js.map +1 -0
  200. package/dist/list/filterOptions.d.ts +7 -0
  201. package/dist/list/filterOptions.d.ts.map +1 -0
  202. package/dist/list/filterOptions.js +7 -0
  203. package/dist/list/filterOptions.js.map +1 -0
  204. package/dist/list/filters.d.ts +78 -0
  205. package/dist/list/filters.d.ts.map +1 -0
  206. package/dist/list/filters.js +54 -0
  207. package/dist/list/filters.js.map +1 -0
  208. package/dist/list/index.d.ts +88 -2
  209. package/dist/list/index.d.ts.map +1 -1
  210. package/dist/list/index.js +50 -2
  211. package/dist/list/index.js.map +1 -1
  212. package/dist/list/types.d.ts +59 -0
  213. package/dist/list/types.d.ts.map +1 -0
  214. package/dist/list/types.js +3 -0
  215. package/dist/list/types.js.map +1 -0
  216. package/dist/logic/browser/prepareImageFile.d.ts +18 -0
  217. package/dist/logic/browser/prepareImageFile.d.ts.map +1 -0
  218. package/dist/logic/browser/prepareImageFile.js +26 -0
  219. package/dist/logic/browser/prepareImageFile.js.map +1 -0
  220. package/dist/logic/index.d.ts +56 -5
  221. package/dist/logic/index.d.ts.map +1 -1
  222. package/dist/logic/index.js +37 -4
  223. package/dist/logic/index.js.map +1 -1
  224. package/dist/logic/pure/conditions.d.ts +46 -0
  225. package/dist/logic/pure/conditions.d.ts.map +1 -0
  226. package/dist/logic/pure/conditions.js +39 -0
  227. package/dist/logic/pure/conditions.js.map +1 -0
  228. package/dist/logic/pure/confirm.d.ts +19 -0
  229. package/dist/logic/pure/confirm.d.ts.map +1 -0
  230. package/dist/logic/pure/confirm.js +10 -0
  231. package/dist/logic/pure/confirm.js.map +1 -0
  232. package/dist/logic/pure/displayMode.d.ts +12 -0
  233. package/dist/logic/pure/displayMode.d.ts.map +1 -0
  234. package/dist/logic/pure/displayMode.js +11 -0
  235. package/dist/logic/pure/displayMode.js.map +1 -0
  236. package/dist/logic/pure/entityDrawer.d.ts +24 -0
  237. package/dist/logic/pure/entityDrawer.d.ts.map +1 -0
  238. package/dist/logic/pure/entityDrawer.js +3 -0
  239. package/dist/logic/pure/entityDrawer.js.map +1 -0
  240. package/dist/logic/pure/fieldPath.d.ts +9 -0
  241. package/dist/logic/pure/fieldPath.d.ts.map +1 -0
  242. package/dist/logic/pure/fieldPath.js +17 -0
  243. package/dist/logic/pure/fieldPath.js.map +1 -0
  244. package/dist/logic/pure/formValues.d.ts +14 -0
  245. package/dist/logic/pure/formValues.d.ts.map +1 -0
  246. package/dist/logic/pure/formValues.js +82 -0
  247. package/dist/logic/pure/formValues.js.map +1 -0
  248. package/dist/logic/pure/format.d.ts +14 -14
  249. package/dist/logic/pure/format.d.ts.map +1 -1
  250. package/dist/logic/pure/format.js +50 -29
  251. package/dist/logic/pure/format.js.map +1 -1
  252. package/dist/logic/pure/locales.d.ts +27 -0
  253. package/dist/logic/pure/locales.d.ts.map +1 -0
  254. package/dist/logic/pure/locales.js +50 -0
  255. package/dist/logic/pure/locales.js.map +1 -0
  256. package/dist/logic/pure/notify.d.ts +28 -5
  257. package/dist/logic/pure/notify.d.ts.map +1 -1
  258. package/dist/logic/pure/notify.js +41 -22
  259. package/dist/logic/pure/notify.js.map +1 -1
  260. package/dist/logic/pure/rowActivation.d.ts +6 -0
  261. package/dist/logic/pure/rowActivation.d.ts.map +1 -0
  262. package/dist/logic/pure/rowActivation.js +7 -0
  263. package/dist/logic/pure/rowActivation.js.map +1 -0
  264. package/dist/logic/pure/runSequential.d.ts +31 -0
  265. package/dist/logic/pure/runSequential.d.ts.map +1 -0
  266. package/dist/logic/pure/runSequential.js +47 -0
  267. package/dist/logic/pure/runSequential.js.map +1 -0
  268. package/dist/logic/pure/schemas.d.ts +14 -0
  269. package/dist/logic/pure/schemas.d.ts.map +1 -0
  270. package/dist/logic/pure/schemas.js +6 -0
  271. package/dist/logic/pure/schemas.js.map +1 -0
  272. package/dist/logic/pure/serverViolations.d.ts +35 -0
  273. package/dist/logic/pure/serverViolations.d.ts.map +1 -0
  274. package/dist/logic/pure/serverViolations.js +77 -0
  275. package/dist/logic/pure/serverViolations.js.map +1 -0
  276. package/dist/logic/pure/status.d.ts +21 -0
  277. package/dist/logic/pure/status.d.ts.map +1 -0
  278. package/dist/logic/pure/status.js +3 -0
  279. package/dist/logic/pure/status.js.map +1 -0
  280. package/dist/logic/pure/submitError.d.ts +11 -0
  281. package/dist/logic/pure/submitError.d.ts.map +1 -0
  282. package/dist/logic/pure/submitError.js +9 -0
  283. package/dist/logic/pure/submitError.js.map +1 -0
  284. package/dist/logic/pure/translationState.d.ts +29 -0
  285. package/dist/logic/pure/translationState.d.ts.map +1 -0
  286. package/dist/logic/pure/translationState.js +88 -0
  287. package/dist/logic/pure/translationState.js.map +1 -0
  288. package/dist/logic/pure/urlListState.d.ts +18 -0
  289. package/dist/logic/pure/urlListState.d.ts.map +1 -0
  290. package/dist/logic/pure/urlListState.js +3 -0
  291. package/dist/logic/pure/urlListState.js.map +1 -0
  292. package/dist/logic/react/conditionHooks.d.ts +20 -0
  293. package/dist/logic/react/conditionHooks.d.ts.map +1 -0
  294. package/dist/logic/react/conditionHooks.js +51 -0
  295. package/dist/logic/react/conditionHooks.js.map +1 -0
  296. package/dist/logic/react/useCopyToClipboard.d.ts +9 -0
  297. package/dist/logic/react/useCopyToClipboard.d.ts.map +1 -0
  298. package/dist/logic/react/useCopyToClipboard.js +28 -0
  299. package/dist/logic/react/useCopyToClipboard.js.map +1 -0
  300. package/dist/logic/react/useDebouncedValue.d.ts +3 -0
  301. package/dist/logic/react/useDebouncedValue.d.ts.map +1 -0
  302. package/dist/logic/react/useDebouncedValue.js +12 -0
  303. package/dist/logic/react/useDebouncedValue.js.map +1 -0
  304. package/dist/logic/react/useEntityDrawer.d.ts +54 -0
  305. package/dist/logic/react/useEntityDrawer.d.ts.map +1 -0
  306. package/dist/logic/react/useEntityDrawer.js +81 -0
  307. package/dist/logic/react/useEntityDrawer.js.map +1 -0
  308. package/dist/logic/react/useEntityTranslations.d.ts +57 -0
  309. package/dist/logic/react/useEntityTranslations.d.ts.map +1 -0
  310. package/dist/logic/react/useEntityTranslations.js +50 -0
  311. package/dist/logic/react/useEntityTranslations.js.map +1 -0
  312. package/dist/logic/react/useFormDirty.d.ts +15 -0
  313. package/dist/logic/react/useFormDirty.d.ts.map +1 -0
  314. package/dist/logic/react/useFormDirty.js +17 -0
  315. package/dist/logic/react/useFormDirty.js.map +1 -0
  316. package/dist/logic/react/useGrowingWindowList.d.ts +50 -0
  317. package/dist/logic/react/useGrowingWindowList.d.ts.map +1 -0
  318. package/dist/logic/react/useGrowingWindowList.js +38 -0
  319. package/dist/logic/react/useGrowingWindowList.js.map +1 -0
  320. package/dist/logic/react/useHydrated.d.ts +7 -0
  321. package/dist/logic/react/useHydrated.d.ts.map +1 -0
  322. package/dist/logic/react/useHydrated.js +12 -0
  323. package/dist/logic/react/useHydrated.js.map +1 -0
  324. package/dist/logic/react/useInfiniteScrollSentinel.d.ts +6 -0
  325. package/dist/logic/react/useInfiniteScrollSentinel.d.ts.map +1 -0
  326. package/dist/logic/react/useInfiniteScrollSentinel.js +24 -0
  327. package/dist/logic/react/useInfiniteScrollSentinel.js.map +1 -0
  328. package/dist/logic/react/useLocaleName.d.ts +3 -0
  329. package/dist/logic/react/useLocaleName.d.ts.map +1 -0
  330. package/dist/logic/react/useLocaleName.js +10 -0
  331. package/dist/logic/react/useLocaleName.js.map +1 -0
  332. package/dist/logic/react/useRowActivation.d.ts +12 -0
  333. package/dist/logic/react/useRowActivation.d.ts.map +1 -0
  334. package/dist/logic/react/useRowActivation.js +35 -0
  335. package/dist/logic/react/useRowActivation.js.map +1 -0
  336. package/dist/logic/react/useRowSelection.d.ts +40 -0
  337. package/dist/logic/react/useRowSelection.d.ts.map +1 -0
  338. package/dist/logic/react/useRowSelection.js +70 -0
  339. package/dist/logic/react/useRowSelection.js.map +1 -0
  340. package/dist/logic/react/useTranslationRunner.d.ts +27 -0
  341. package/dist/logic/react/useTranslationRunner.d.ts.map +1 -0
  342. package/dist/logic/react/useTranslationRunner.js +57 -0
  343. package/dist/logic/react/useTranslationRunner.js.map +1 -0
  344. package/dist/logic/react/useUnsavedChangesGuard.d.ts +30 -0
  345. package/dist/logic/react/useUnsavedChangesGuard.d.ts.map +1 -0
  346. package/dist/logic/react/useUnsavedChangesGuard.js +66 -0
  347. package/dist/logic/react/useUnsavedChangesGuard.js.map +1 -0
  348. package/dist/logic/react/useUrlListState.d.ts +39 -0
  349. package/dist/logic/react/useUrlListState.d.ts.map +1 -0
  350. package/dist/logic/react/useUrlListState.js +96 -0
  351. package/dist/logic/react/useUrlListState.js.map +1 -0
  352. package/dist/media/FormMediaItemField.d.ts +38 -0
  353. package/dist/media/FormMediaItemField.d.ts.map +1 -0
  354. package/dist/media/FormMediaItemField.js +35 -0
  355. package/dist/media/FormMediaItemField.js.map +1 -0
  356. package/dist/media/MediaItemField.d.ts +17 -3
  357. package/dist/media/MediaItemField.d.ts.map +1 -1
  358. package/dist/media/MediaItemField.js +11 -7
  359. package/dist/media/MediaItemField.js.map +1 -1
  360. package/dist/media/MediaItemPickerDialog.d.ts +48 -0
  361. package/dist/media/MediaItemPickerDialog.d.ts.map +1 -0
  362. package/dist/media/MediaItemPickerDialog.js +36 -0
  363. package/dist/media/MediaItemPickerDialog.js.map +1 -0
  364. package/dist/media/MediaPreview.d.ts +16 -0
  365. package/dist/media/MediaPreview.d.ts.map +1 -0
  366. package/dist/media/MediaPreview.js +20 -0
  367. package/dist/media/MediaPreview.js.map +1 -0
  368. package/dist/media/index.d.ts +17 -2
  369. package/dist/media/index.d.ts.map +1 -1
  370. package/dist/media/index.js +7 -0
  371. package/dist/media/index.js.map +1 -1
  372. package/dist/media/types.d.ts +23 -6
  373. package/dist/media/types.d.ts.map +1 -1
  374. package/dist/next/index.d.ts +7 -2
  375. package/dist/next/index.d.ts.map +1 -1
  376. package/dist/next/index.js +7 -2
  377. package/dist/next/index.js.map +1 -1
  378. package/dist/next/listViewParam.d.ts +3 -0
  379. package/dist/next/listViewParam.d.ts.map +1 -0
  380. package/dist/next/listViewParam.js +3 -0
  381. package/dist/next/listViewParam.js.map +1 -0
  382. package/dist/next/searchParamsWriter.d.ts +30 -6
  383. package/dist/next/searchParamsWriter.d.ts.map +1 -1
  384. package/dist/next/searchParamsWriter.js +80 -27
  385. package/dist/next/searchParamsWriter.js.map +1 -1
  386. package/dist/next/storage.d.ts +11 -0
  387. package/dist/next/storage.d.ts.map +1 -0
  388. package/dist/next/storage.js +34 -0
  389. package/dist/next/storage.js.map +1 -0
  390. package/dist/next/useListViewParam.d.ts +12 -0
  391. package/dist/next/useListViewParam.d.ts.map +1 -0
  392. package/dist/next/useListViewParam.js +45 -0
  393. package/dist/next/useListViewParam.js.map +1 -0
  394. package/dist/next/useNextDrawerUrlAdapter.d.ts +11 -0
  395. package/dist/next/useNextDrawerUrlAdapter.d.ts.map +1 -0
  396. package/dist/next/useNextDrawerUrlAdapter.js +28 -0
  397. package/dist/next/useNextDrawerUrlAdapter.js.map +1 -0
  398. package/dist/next/useNextUrlStateAdapter.d.ts +20 -0
  399. package/dist/next/useNextUrlStateAdapter.d.ts.map +1 -0
  400. package/dist/next/useNextUrlStateAdapter.js +28 -0
  401. package/dist/next/useNextUrlStateAdapter.js.map +1 -0
  402. package/dist/notify-sonner/Toaster.d.ts +8 -0
  403. package/dist/notify-sonner/Toaster.d.ts.map +1 -0
  404. package/dist/notify-sonner/Toaster.js +24 -0
  405. package/dist/notify-sonner/Toaster.js.map +1 -0
  406. package/dist/notify-sonner/index.d.ts +1 -0
  407. package/dist/notify-sonner/index.d.ts.map +1 -1
  408. package/dist/notify-sonner/index.js +2 -0
  409. package/dist/notify-sonner/index.js.map +1 -1
  410. package/dist/notify-sonner/sonnerNotifications.d.ts +1 -1
  411. package/dist/notify-sonner/sonnerNotifications.d.ts.map +1 -1
  412. package/dist/notify-sonner/sonnerNotifications.js +23 -6
  413. package/dist/notify-sonner/sonnerNotifications.js.map +1 -1
  414. package/dist/page/DefinitionList.d.ts +24 -0
  415. package/dist/page/DefinitionList.d.ts.map +1 -0
  416. package/dist/page/DefinitionList.js +20 -0
  417. package/dist/page/DefinitionList.js.map +1 -0
  418. package/dist/page/DetailHeader.d.ts +26 -0
  419. package/dist/page/DetailHeader.d.ts.map +1 -0
  420. package/dist/page/DetailHeader.js +14 -0
  421. package/dist/page/DetailHeader.js.map +1 -0
  422. package/dist/page/EditableCard.d.ts +39 -0
  423. package/dist/page/EditableCard.d.ts.map +1 -0
  424. package/dist/page/EditableCard.js +21 -0
  425. package/dist/page/EditableCard.js.map +1 -0
  426. package/dist/page/EntityDetailShell.d.ts +48 -0
  427. package/dist/page/EntityDetailShell.d.ts.map +1 -0
  428. package/dist/page/EntityDetailShell.js +25 -0
  429. package/dist/page/EntityDetailShell.js.map +1 -0
  430. package/dist/page/EntityListPage.d.ts +30 -0
  431. package/dist/page/EntityListPage.d.ts.map +1 -0
  432. package/dist/page/EntityListPage.js +12 -0
  433. package/dist/page/EntityListPage.js.map +1 -0
  434. package/dist/page/EntityMetadata.d.ts +21 -0
  435. package/dist/page/EntityMetadata.d.ts.map +1 -0
  436. package/dist/page/EntityMetadata.js +39 -0
  437. package/dist/page/EntityMetadata.js.map +1 -0
  438. package/dist/page/EntityTabs.d.ts +38 -0
  439. package/dist/page/EntityTabs.d.ts.map +1 -0
  440. package/dist/page/EntityTabs.js +51 -0
  441. package/dist/page/EntityTabs.js.map +1 -0
  442. package/dist/page/PageFrame.d.ts +18 -2
  443. package/dist/page/PageFrame.d.ts.map +1 -1
  444. package/dist/page/PageFrame.js +8 -2
  445. package/dist/page/PageFrame.js.map +1 -1
  446. package/dist/page/PageHeader.d.ts +27 -0
  447. package/dist/page/PageHeader.d.ts.map +1 -0
  448. package/dist/page/PageHeader.js +16 -0
  449. package/dist/page/PageHeader.js.map +1 -0
  450. package/dist/page/PageLayout.d.ts +15 -0
  451. package/dist/page/PageLayout.d.ts.map +1 -0
  452. package/dist/page/PageLayout.js +10 -0
  453. package/dist/page/PageLayout.js.map +1 -0
  454. package/dist/page/PageToolbar.d.ts +73 -0
  455. package/dist/page/PageToolbar.d.ts.map +1 -0
  456. package/dist/page/PageToolbar.js +49 -0
  457. package/dist/page/PageToolbar.js.map +1 -0
  458. package/dist/page/SectionHeader.d.ts +27 -0
  459. package/dist/page/SectionHeader.d.ts.map +1 -0
  460. package/dist/page/SectionHeader.js +14 -0
  461. package/dist/page/SectionHeader.js.map +1 -0
  462. package/dist/page/StatusCallout.d.ts +28 -0
  463. package/dist/page/StatusCallout.d.ts.map +1 -0
  464. package/dist/page/StatusCallout.js +35 -0
  465. package/dist/page/StatusCallout.js.map +1 -0
  466. package/dist/page/index.d.ts +28 -1
  467. package/dist/page/index.d.ts.map +1 -1
  468. package/dist/page/index.js +18 -0
  469. package/dist/page/index.js.map +1 -1
  470. package/dist/page/links.d.ts +18 -0
  471. package/dist/page/links.d.ts.map +1 -0
  472. package/dist/page/links.js +4 -0
  473. package/dist/page/links.js.map +1 -0
  474. package/dist/primitives/alert.d.ts +17 -0
  475. package/dist/primitives/alert.d.ts.map +1 -0
  476. package/dist/primitives/alert.js +36 -0
  477. package/dist/primitives/alert.js.map +1 -0
  478. package/dist/primitives/badge.d.ts +10 -0
  479. package/dist/primitives/badge.d.ts.map +1 -0
  480. package/dist/primitives/badge.js +30 -0
  481. package/dist/primitives/badge.js.map +1 -0
  482. package/dist/primitives/breadcrumb.d.ts +12 -0
  483. package/dist/primitives/breadcrumb.d.ts.map +1 -0
  484. package/dist/primitives/breadcrumb.js +33 -0
  485. package/dist/primitives/breadcrumb.js.map +1 -0
  486. package/dist/primitives/button.d.ts +10 -8
  487. package/dist/primitives/button.d.ts.map +1 -1
  488. package/dist/primitives/button.js +41 -10
  489. package/dist/primitives/button.js.map +1 -1
  490. package/dist/primitives/card.d.ts +10 -0
  491. package/dist/primitives/card.d.ts.map +1 -0
  492. package/dist/primitives/card.js +29 -0
  493. package/dist/primitives/card.js.map +1 -0
  494. package/dist/primitives/checkbox.d.ts +5 -0
  495. package/dist/primitives/checkbox.d.ts.map +1 -0
  496. package/dist/primitives/checkbox.js +11 -0
  497. package/dist/primitives/checkbox.js.map +1 -0
  498. package/dist/primitives/cn.d.ts +1 -1
  499. package/dist/primitives/cn.d.ts.map +1 -1
  500. package/dist/primitives/cn.js +1 -1
  501. package/dist/primitives/cn.js.map +1 -1
  502. package/dist/primitives/collapsible.d.ts +6 -0
  503. package/dist/primitives/collapsible.d.ts.map +1 -0
  504. package/dist/primitives/collapsible.js +14 -0
  505. package/dist/primitives/collapsible.js.map +1 -0
  506. package/dist/primitives/command.d.ts +19 -0
  507. package/dist/primitives/command.d.ts.map +1 -0
  508. package/dist/primitives/command.js +38 -0
  509. package/dist/primitives/command.js.map +1 -0
  510. package/dist/primitives/dialog.d.ts +17 -9
  511. package/dist/primitives/dialog.d.ts.map +1 -1
  512. package/dist/primitives/dialog.js +39 -14
  513. package/dist/primitives/dialog.js.map +1 -1
  514. package/dist/primitives/dropdown-menu.d.ts +23 -0
  515. package/dist/primitives/dropdown-menu.d.ts.map +1 -0
  516. package/dist/primitives/dropdown-menu.js +48 -0
  517. package/dist/primitives/dropdown-menu.js.map +1 -0
  518. package/dist/primitives/fieldSurface.d.ts +23 -0
  519. package/dist/primitives/fieldSurface.d.ts.map +1 -0
  520. package/dist/primitives/fieldSurface.js +23 -0
  521. package/dist/primitives/fieldSurface.js.map +1 -0
  522. package/dist/primitives/index.d.ts +24 -5
  523. package/dist/primitives/index.d.ts.map +1 -1
  524. package/dist/primitives/index.js +25 -5
  525. package/dist/primitives/index.js.map +1 -1
  526. package/dist/primitives/input.d.ts +12 -0
  527. package/dist/primitives/input.d.ts.map +1 -0
  528. package/dist/primitives/input.js +20 -0
  529. package/dist/primitives/input.js.map +1 -0
  530. package/dist/primitives/label.d.ts +5 -0
  531. package/dist/primitives/label.d.ts.map +1 -0
  532. package/dist/primitives/label.js +10 -0
  533. package/dist/primitives/label.js.map +1 -0
  534. package/dist/primitives/listSurface.d.ts +8 -0
  535. package/dist/primitives/listSurface.d.ts.map +1 -0
  536. package/dist/primitives/listSurface.js +8 -0
  537. package/dist/primitives/listSurface.js.map +1 -0
  538. package/dist/primitives/popover.d.ts +11 -0
  539. package/dist/primitives/popover.d.ts.map +1 -0
  540. package/dist/primitives/popover.js +31 -0
  541. package/dist/primitives/popover.js.map +1 -0
  542. package/dist/primitives/portal.d.ts +16 -0
  543. package/dist/primitives/portal.d.ts.map +1 -0
  544. package/dist/primitives/portal.js +9 -0
  545. package/dist/primitives/portal.js.map +1 -0
  546. package/dist/primitives/select.d.ts +20 -8
  547. package/dist/primitives/select.d.ts.map +1 -1
  548. package/dist/primitives/select.js +46 -12
  549. package/dist/primitives/select.js.map +1 -1
  550. package/dist/primitives/separator.d.ts +5 -0
  551. package/dist/primitives/separator.d.ts.map +1 -0
  552. package/dist/primitives/separator.js +10 -0
  553. package/dist/primitives/separator.js.map +1 -0
  554. package/dist/primitives/sheet.d.ts +14 -8
  555. package/dist/primitives/sheet.d.ts.map +1 -1
  556. package/dist/primitives/sheet.js +42 -11
  557. package/dist/primitives/sheet.js.map +1 -1
  558. package/dist/primitives/skeleton.d.ts +3 -0
  559. package/dist/primitives/skeleton.d.ts.map +1 -0
  560. package/dist/primitives/skeleton.js +7 -0
  561. package/dist/primitives/skeleton.js.map +1 -0
  562. package/dist/primitives/switch.d.ts +7 -0
  563. package/dist/primitives/switch.d.ts.map +1 -0
  564. package/dist/primitives/switch.js +10 -0
  565. package/dist/primitives/switch.js.map +1 -0
  566. package/dist/primitives/table.d.ts +11 -0
  567. package/dist/primitives/table.d.ts.map +1 -0
  568. package/dist/primitives/table.js +30 -0
  569. package/dist/primitives/table.js.map +1 -0
  570. package/dist/primitives/textarea.d.ts +4 -0
  571. package/dist/primitives/textarea.d.ts.map +1 -0
  572. package/dist/primitives/textarea.js +11 -0
  573. package/dist/primitives/textarea.js.map +1 -0
  574. package/dist/primitives/tooltip.d.ts +8 -0
  575. package/dist/primitives/tooltip.d.ts.map +1 -0
  576. package/dist/primitives/tooltip.js +21 -0
  577. package/dist/primitives/tooltip.js.map +1 -0
  578. package/dist/provider/AdminUiProvider.d.ts +8 -6
  579. package/dist/provider/AdminUiProvider.d.ts.map +1 -1
  580. package/dist/provider/AdminUiProvider.js +37 -22
  581. package/dist/provider/AdminUiProvider.js.map +1 -1
  582. package/dist/provider/adminUiContext.d.ts +6 -0
  583. package/dist/provider/adminUiContext.d.ts.map +1 -0
  584. package/dist/provider/adminUiContext.js +9 -0
  585. package/dist/provider/adminUiContext.js.map +1 -0
  586. package/dist/provider/index.d.ts +4 -2
  587. package/dist/provider/index.d.ts.map +1 -1
  588. package/dist/provider/index.js +4 -1
  589. package/dist/provider/index.js.map +1 -1
  590. package/dist/provider/storageKey.d.ts +4 -0
  591. package/dist/provider/storageKey.d.ts.map +1 -0
  592. package/dist/provider/storageKey.js +3 -0
  593. package/dist/provider/storageKey.js.map +1 -0
  594. package/dist/provider/types.d.ts +38 -6
  595. package/dist/provider/types.d.ts.map +1 -1
  596. package/dist/scripts/build-i18n-manifest.mjs +138 -0
  597. package/dist/scripts/check-radix.mjs +131 -0
  598. package/dist/scripts/check-tokens.mjs +236 -0
  599. package/dist/theme.css +15 -11
  600. package/dist/tokens.json +388 -53
  601. package/dist/translations/FormTranslatableFields.d.ts +30 -0
  602. package/dist/translations/FormTranslatableFields.d.ts.map +1 -0
  603. package/dist/translations/FormTranslatableFields.js +58 -0
  604. package/dist/translations/FormTranslatableFields.js.map +1 -0
  605. package/dist/translations/TranslatableField.d.ts +48 -0
  606. package/dist/translations/TranslatableField.d.ts.map +1 -0
  607. package/dist/translations/TranslatableField.js +44 -0
  608. package/dist/translations/TranslatableField.js.map +1 -0
  609. package/dist/translations/TranslatableInput.d.ts +14 -0
  610. package/dist/translations/TranslatableInput.d.ts.map +1 -0
  611. package/dist/translations/TranslatableInput.js +15 -0
  612. package/dist/translations/TranslatableInput.js.map +1 -0
  613. package/dist/translations/TranslatableMarkdown.d.ts +21 -0
  614. package/dist/translations/TranslatableMarkdown.d.ts.map +1 -0
  615. package/dist/translations/TranslatableMarkdown.js +12 -0
  616. package/dist/translations/TranslatableMarkdown.js.map +1 -0
  617. package/dist/translations/TranslationControls.d.ts +22 -0
  618. package/dist/translations/TranslationControls.d.ts.map +1 -0
  619. package/dist/translations/TranslationControls.js +31 -0
  620. package/dist/translations/TranslationControls.js.map +1 -0
  621. package/dist/translations/index.d.ts +30 -1
  622. package/dist/translations/index.d.ts.map +1 -1
  623. package/dist/translations/index.js +17 -1
  624. package/dist/translations/index.js.map +1 -1
  625. package/package.json +27 -29
  626. package/dist/data/StatTile.d.ts +0 -8
  627. package/dist/data/StatTile.d.ts.map +0 -1
  628. package/dist/data/StatTile.js +0 -6
  629. package/dist/data/StatTile.js.map +0 -1
  630. package/dist/data/index.d.ts +0 -2
  631. package/dist/data/index.d.ts.map +0 -1
  632. package/dist/data/index.js +0 -2
  633. package/dist/data/index.js.map +0 -1
  634. package/dist/glass/GlassPanel.d.ts +0 -7
  635. package/dist/glass/GlassPanel.d.ts.map +0 -1
  636. package/dist/glass/GlassPanel.js +0 -5
  637. package/dist/glass/GlassPanel.js.map +0 -1
  638. package/dist/i18n/m.d.ts +0 -7
  639. package/dist/i18n/m.d.ts.map +0 -1
  640. package/dist/i18n/m.js +0 -7
  641. package/dist/i18n/m.js.map +0 -1
  642. package/dist/list/ClearFiltersButton.d.ts +0 -7
  643. package/dist/list/ClearFiltersButton.d.ts.map +0 -1
  644. package/dist/list/ClearFiltersButton.js +0 -10
  645. package/dist/list/ClearFiltersButton.js.map +0 -1
  646. package/dist/list/DateCell.d.ts +0 -8
  647. package/dist/list/DateCell.d.ts.map +0 -1
  648. package/dist/list/DateCell.js +0 -12
  649. package/dist/list/DateCell.js.map +0 -1
  650. package/dist/logic/pure/errors.d.ts +0 -3
  651. package/dist/logic/pure/errors.d.ts.map +0 -1
  652. package/dist/logic/pure/errors.js +0 -5
  653. package/dist/logic/pure/errors.js.map +0 -1
  654. package/dist/logic/pure/statusMap.d.ts +0 -12
  655. package/dist/logic/pure/statusMap.d.ts.map +0 -1
  656. package/dist/logic/pure/statusMap.js +0 -5
  657. package/dist/logic/pure/statusMap.js.map +0 -1
  658. package/dist/logic/react/useToggle.d.ts +0 -8
  659. package/dist/logic/react/useToggle.d.ts.map +0 -1
  660. package/dist/logic/react/useToggle.js +0 -9
  661. package/dist/logic/react/useToggle.js.map +0 -1
  662. package/dist/next/useNextSearchParam.d.ts +0 -3
  663. package/dist/next/useNextSearchParam.d.ts.map +0 -1
  664. package/dist/next/useNextSearchParam.js +0 -16
  665. package/dist/next/useNextSearchParam.js.map +0 -1
  666. package/dist/primitives/portalContainer.d.ts +0 -8
  667. package/dist/primitives/portalContainer.d.ts.map +0 -1
  668. package/dist/primitives/portalContainer.js +0 -12
  669. package/dist/primitives/portalContainer.js.map +0 -1
  670. package/dist/translations/TranslatableInputField.d.ts +0 -8
  671. package/dist/translations/TranslatableInputField.d.ts.map +0 -1
  672. package/dist/translations/TranslatableInputField.js +0 -12
  673. package/dist/translations/TranslatableInputField.js.map +0 -1
  674. package/docs/README.md +0 -11
  675. package/scripts/check-tokens.mjs +0 -136
  676. package/scripts/lib/i18n-manifest.mjs +0 -91
  677. package/scripts/lib/source-scan.mjs +0 -258
@@ -1,29 +1,159 @@
1
1
  ---
2
2
  name: ddd-admin-ui-specialist
3
- description: "Build admin screens with @mgamadeus/ddd-admin-ui (React 19, Next 16, Tailwind 4, mgamadeus/ddd backends): which entry to import from (./logic, ./i18n, ./primitives, ./list, ./page, ./form, ./translations, ./media, ./glass, ./data, ./next, ./provider, ./notify-sonner), server-safe helpers versus 'use client' files, the stylesheets theme.css and components.css, the CSS contract in tokens.json (colour roles, custom properties, layer scale), AdminUiProvider and its adapters, translations with m() and i18n-keys.json, and check-tokens for a host's built CSS. Use when adding or changing an admin screen, wiring the package into a host, choosing an import path, fixing missing styles, overlays below a host dialog, untranslated block texts, or a server component that imports a client file."
3
+ description: "Build admin screens with @mgamadeus/ddd-admin-ui on @mgamadeus/ddd-web and extend the package. Covers the entries and their import matrix, host setup (AdminUiProvider above every page, theme.css and components.css after Tailwind, tokens.json with ddd-admin-ui-check-tokens, peers, one Radix copy with ddd-admin-ui-check-radix), list pages with URL filters, grid/table view, selection and bulk actions, detail shells, form drawers with conditions, server errors and the unsaved-changes guard, translations on full locale::style keys, media fields, toasts, layers and the portal container, the text manifest i18n-keys.json, server vs client files, and adding a block (build, pack, check-package). Use when building or reviewing a list, detail or form screen with these blocks, a page fails with Tooltip must be used within TooltipProvider, a colour, layer or overlay misbehaves (two overlays fight over focus or outside clicks), translations lose a style variant, URL filters get lost, or a block is added to the package."
4
+ metadata:
5
+ author: mgamadeus
6
+ version: 0.1.0
4
7
  ---
5
8
 
6
- # ddd-admin-ui-specialist
9
+ # ddd-admin-ui specialist
7
10
 
8
- Skeleton: the package is a scaffold with sample source. The sections below are filled when the blocks arrive.
11
+ Package docs (read them for setup and the full entry list): `README.md` and `STANDARDS.md` at the root of the
12
+ installed package (`node_modules/@mgamadeus/ddd-admin-ui/`). This skill reaches a project through
13
+ `npx ddd-admin-ui link-skills`.
9
14
 
10
- ## Entries and import rules
15
+ ## Which block for what
11
16
 
12
- - Import from the entry, never from a file inside `dist`.
13
- - `./logic` and `./i18n` run without Tailwind, Radix, icons and Next; server components may call `m()`, the formats
14
- and the status maps.
15
- - `./next` is the only entry that needs `next`; `./notify-sonner` the only one that needs `sonner`.
17
+ | Need | Use | Entry |
18
+ |---|---|---|
19
+ | a list page (header, toolbar, table or card grid) | `EntityListPage` + `EntityListToolbar` + `EntityListBody` | page, list |
20
+ | search and filters in the URL | `useUrlListState` with `useNextUrlStateAdapter` | logic, next |
21
+ | grid / table switch remembered per list | `useListViewParam` + `EntityListViewToggle` | next, list |
22
+ | checkbox column and bulk actions | `useRowSelection` + `EntityListBulkBar` + `runSequentialWithSummary` | logic, list |
23
+ | status pill of an enum | `defineStatusMap` + `StatusBadge` | logic, list |
24
+ | an entity detail with tabs | `EntityDetailShell` (+ `SectionHeader`, `DefinitionList`) | page |
25
+ | a form page or drawer | `Form` + `FormField` / `FormSection` + `FormActions`, in `FormDrawer` | form |
26
+ | drawer state in the URL (`?edit=<id>`, `?create=1`) | `useEntityDrawer` with `useNextDrawerUrlAdapter` | logic, next |
27
+ | a text per content locale | `useEntityTranslations` + `FormTranslatableInput` / `FormTranslatableMarkdown` | logic, translations |
28
+ | a media reference | `FormMediaItemField` (+ the host's `MediaItemPickerDialog`) | media |
29
+ | a confirmation | `useConfirmDialog` (returns `{ confirm, dialog }`) | form |
30
+ | a toast | `notify.success / info / error / loading / submitError` | logic |
16
31
 
17
- ## Host setup
32
+ ## Rules that fail silently
18
33
 
19
- 1. `@import 'tailwindcss';`, then `theme.css` (when the host declares complete colours under the role names), then
20
- `components.css`.
21
- 2. Declare every colour and property of `tokens.json` on `:root`, and the themed ones under `.dark`.
22
- 3. Wrap the app in `AdminUiProvider` (a client component) with the host's adapters.
23
- 4. Run `node node_modules/@mgamadeus/ddd-admin-ui/scripts/check-tokens.mjs <built css…>` after a production build.
34
+ - **Provider above every page.** `AdminUiProvider` renders the tooltip provider, the portal container and registers
35
+ the notification adapter. Without it a date cell throws ("`Tooltip` must be used within `TooltipProvider`") and
36
+ `notify` does nothing (one warning outside production).
37
+ - **CSS and tokens.** `theme.css` and `components.css` after `@import 'tailwindcss'`; every property of `tokens.json`
38
+ on `:root` (themed ones also under `.dark`). Run `ddd-admin-ui-check-tokens <built css>` after a theme change: a
39
+ missing colour role means a utility without a rule, so the element is simply transparent.
40
+ - **One Radix copy.** `radix-ui` is a peer; single `@radix-ui/*` packages of the host match the versions `radix-ui`
41
+ pins. Two copies of one Radix package keep separate focus traps and outside-click layers (an overlay closes the wrong
42
+ one, focus jumps). Run `ddd-admin-ui-check-radix` in the host after dependency changes.
43
+ - **Layers.** Overlays stack with `z-(--layer-overlay)` and `z-(--layer-popover)` (both 50 by default; a later portal
44
+ paints on top), sticky bars with `--layer-sticky` (20), sticky headers with `--layer-raised` (10). A host raises them
45
+ on `:root`; `PortalContainerProvider` / the provider's `portalContainer` moves every portal.
46
+ - **Import boundary.** Blocks import only the entries the matrix in `README.md` allows, never app code. Only `./next`
47
+ imports `next/*`, only `./notify-sonner` imports `sonner`; `./logic` pure files run without React.
48
+ - **Translation keys.** Keys are full `locale::style` (`de::FORMAL`, `de::INFORMAL`). Never collapse them to the
49
+ language: the payload of `useEntityTranslations` sends every loaded key back; a cleared text removes its key.
50
+ - **URL state.** Build requests from `list.debounced`, never `list.values`. All writes (filters, view, drawer) go
51
+ through the one URL writer, so writes in the same tick merge; never `router.replace` the search parameters by hand.
52
+ Screens reading search parameters render inside `<Suspense>`.
53
+ - **Server vs client.** Hooks and context live in files with `'use client'`; pure helpers (`m`, `formatDateTime`,
54
+ `defineStatusMap`, schemas, conditions) may be called in server code and `metadata`.
24
55
 
25
- ## Translations
56
+ ## Patterns
26
57
 
27
- - Texts of the package go through its store; the host feeds it (`setTranslations` or the provider's `translations`
28
- adapter).
29
- - `i18n-keys.json` lists them for the host's translation export.
58
+ ### List page
59
+
60
+ ```tsx
61
+ const LIST_ID = 'admin.items';
62
+ const LIST_KEYS = ['q', 'status'] as const;
63
+
64
+ export const ItemsScreen = () => {
65
+ const list = useUrlListState(LIST_KEYS, { adapter: useNextUrlStateAdapter({ listId: LIST_ID }), uncounted: ['q'] });
66
+ const [displayMode, setDisplayMode] = useListViewParam(LIST_ID, 'table');
67
+ const query = useItemsQuery(list.debounced); // the host's data hook
68
+ return (
69
+ <EntityListPage
70
+ title="Items"
71
+ toolbar={
72
+ <EntityListToolbar
73
+ search={{ value: list.values.q, onChange: value => list.setValue('q', value), placeholder: 'Search' }}
74
+ activeFilterCount={list.activeFilterCount}
75
+ onClearFilters={list.clear}
76
+ viewToggle={<EntityListViewToggle displayMode={displayMode} onDisplayModeChange={setDisplayMode} />}
77
+ />
78
+ }
79
+ >
80
+ <EntityListBody
81
+ displayMode={displayMode}
82
+ columns={COLUMNS}
83
+ items={query.items}
84
+ getRowKey={item => String(item.id)}
85
+ isLoading={query.isLoading}
86
+ isSearchActive={list.isActive}
87
+ onClearSearch={list.clear}
88
+ />
89
+ </EntityListPage>
90
+ );
91
+ };
92
+ ```
93
+
94
+ ### Form in a drawer
95
+
96
+ ```tsx
97
+ const drawer = useEntityDrawer({ adapter: useNextDrawerUrlAdapter() });
98
+ const form = useForm<Values>({ defaultValues });
99
+ const { confirm, dialog } = useConfirmDialog();
100
+ const { confirmDiscard } = useUnsavedChangesGuard(useFormDirty(form), confirm);
101
+
102
+ <FormDrawer open={drawer.isOpen} onClose={drawer.close} title="Edit item">
103
+ <Form form={form} onSubmit={save}>
104
+ <FormField<Values, 'name'> name="name" label="Name" required>
105
+ {({ field, control }) => <Input {...control} {...field} />}
106
+ </FormField>
107
+ <FormActions
108
+ secondary={
109
+ <Button type="button" variant="outline" onClick={async () => (await confirmDiscard()) && drawer.close()}>
110
+ Cancel
111
+ </Button>
112
+ }
113
+ primary={<FormSubmitButton>Save</FormSubmitButton>}
114
+ />
115
+ </Form>
116
+ {dialog}
117
+ </FormDrawer>
118
+ ```
119
+
120
+ ### Translations and media in one form
121
+
122
+ ```tsx
123
+ const tabs = useEntityTranslations({ fields: ['name'], locales: ['en::FORMAL', 'de::FORMAL'], defaultLocale: 'en::FORMAL' });
124
+
125
+ <Form form={form} onSubmit={save}>
126
+ <FormErrors error={submitError} />
127
+ <FormTranslatableInput<Values> name="translations.name" label="Display name" tabs={tabs} />
128
+ <FormMediaItemField<Values> name="image" label="Image" alt="" onOpenPicker={openPicker} />
129
+ </Form>
130
+ ```
131
+
132
+ A server violation on `translations.name` shows with the field's label ("Display name: …").
133
+
134
+ ## Adding a block to the package
135
+
136
+ Work in the package repository (`src/<entry>/`).
137
+
138
+ 1. Pick the entry by layer: no React → `logic/pure`; hooks without markup → `logic/react`; browser API → `logic/browser`;
139
+ markup → the block entry. Respect the import matrix (`README.md`); a new edge needs a matrix change first.
140
+ 2. Relative imports name their file (`./Block.tsx`, `../logic/index.ts`); `'use client'` exactly when the file calls a
141
+ hook, `createContext` or `react-dom`; export the block from the entry's `index.ts`.
142
+ 3. Colours only through role utilities (`bg-card`, `text-muted-foreground`); a new role, property or layer goes into
143
+ `tokens.json` (regenerate the `utilities` lists with `scripts/tokens-utilities.mjs --write`).
144
+ 4. Texts through `t()` / `m()`; add the hint to `i18n/hints.json` and regenerate `i18n-keys.json` with
145
+ `pnpm i18n:manifest`.
146
+ 5. Check:
147
+
148
+ ```sh
149
+ pnpm typecheck && pnpm test && pnpm build
150
+ node scripts/check-package.mjs --dir . # and on the extracted tarball (pnpm pack)
151
+ node scripts/tokens-utilities.mjs && node scripts/build-i18n-manifest.mjs --check
152
+ test/consumer/run.sh <tarball> pnpm <work dir> # consumer tests on the packed tarball
153
+ ```
154
+
155
+ ## References
156
+
157
+ - `README.md` — entries and matrix, peers, host setup, provider props, texts, package commands.
158
+ - `STANDARDS.md` — how list, detail, form and drawer screens are composed, with full examples.
159
+ - `tokens.json` — the host contract; `i18n-keys.json` — the text manifest.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,23 @@
2
2
 
3
3
  All notable changes to `@mgamadeus/ddd-admin-ui`. 0.x: each minor may break; depend on it with `">=0.N <1"`.
4
4
 
5
+ ## 0.1.0-rc.2
6
+
7
+ - The real blocks replace the sample source. Entries: `./logic` (pure helpers, React hooks, browser helpers),
8
+ `./i18n`, `./primitives`, `./list`, `./page`, `./form`, `./translations`, `./media`, `./glass`, `./provider`,
9
+ `./next`, `./notify-sonner`, plus `./theme.css`, `./components.css`, `./tokens.json` (31 colour roles, properties,
10
+ layers, data attributes, utilities per role) and `./i18n-keys.json` (128 texts). `STANDARDS.md` describes how list,
11
+ detail, form and drawer screens are composed.
12
+ - Removed: the `./data` entry (no blocks yet).
13
+ - `radix-ui` is a peer (`^1.8.1`), no longer a dependency: the host installs one Radix copy.
14
+ - Exports use the `default` condition (was `import`).
15
+ - New bins: `ddd-admin-ui-check-tokens`, `ddd-admin-ui-check-radix`, `ddd-admin-ui-i18n-manifest` (scripts shipped in
16
+ `dist/scripts`); `scripts/check-tokens.mjs` at the package root is gone. `ddd-admin-ui link-skills` is unchanged.
17
+ - `check-package` follows the rules as built: client boundaries without a hook are listed, not failed; runtime and
18
+ type-only edges are checked apart, with file limits for `page → list`, `form → page` and `translations → form`;
19
+ the declarations compile in a strict consumer (bundler and nodenext); the text manifest is compared against the
20
+ built JS; the `utilities` lists of `tokens.json` must equal a fresh extraction.
21
+
5
22
  ## 0.1.0-rc.1
6
23
 
7
24
  - First published version of the scaffold (the content of 0.1.0-rc.0).
package/README.md CHANGED
@@ -1,101 +1,200 @@
1
1
  # @mgamadeus/ddd-admin-ui
2
2
 
3
- Admin UI building blocks for React 19 / Next 16 / Tailwind 4 apps built on the
4
- [`mgamadeus/ddd`](https://github.com/ddd-framework/ddd) framework: pure helpers and React hooks, shadcn-style
5
- primitives, list / page / form / translation / media / glass blocks, Next adapters, a provider, two stylesheets and two
6
- JSON manifests.
3
+ DDD-generic admin UI for apps built on `@mgamadeus/ddd-web`: entity lists (table and card grid, filters, selection,
4
+ bulk actions), page frames and detail shells, form shells with conditional fields and server validation, translatable
5
+ inputs on full `locale::style` keys, media pickers, and the shadcn-style primitives they are drawn with. Host specifics
6
+ (columns, labels, endpoints, routing, storage, toasts) come in as props or adapters; the package never imports app
7
+ code. How a screen is built from the blocks: [`STANDARDS.md`](./STANDARDS.md).
7
8
 
8
- > **Status: scaffold.** The build, the package checks, the consumer tests and the release workflow are in place; the
9
- > source is a small set of samples that exercises every rule. The real blocks follow. Nothing is published yet.
10
-
11
- ## Entries
12
-
13
- | Entry | Content | Runs without |
14
- |---|---|---|
15
- | `./logic` | pure helpers (formats, status maps, `notify`, error messages) and React hooks | Tailwind, Radix, icons, Next |
16
- | `./i18n` | the translation store (one per app), `m()`, `useTranslate`, `<Translate>` | Tailwind, Radix, icons, Next |
17
- | `./primitives` | shadcn-style components on Radix (button, dialog, sheet, select, …), `cn` | Next |
18
- | `./list`, `./page`, `./form`, `./translations`, `./media`, `./glass`, `./data` | blocks | Next |
19
- | `./next` | Next adapters: the one URL write queue and URL-state hooks | — (needs `next`) |
20
- | `./provider` | `AdminUiProvider`, `useAdminUi` and the adapter types | Next |
21
- | `./notify-sonner` | the notification adapter for sonner | — (needs `sonner`) |
22
- | `./theme.css` | binds the colour roles of `tokens.json` as Tailwind theme colours | |
23
- | `./components.css` | structure the blocks rely on: surfaces, title utilities, data-attribute rules, the layer scale | |
24
- | `./tokens.json` | the CSS contract: colour roles, custom properties, layers, data attributes | |
25
- | `./i18n-keys.json` | every text the package translates, with context and hint | |
26
-
27
- ESM only. Every file keeps its own `'use client'` directive: files with hooks, contexts or `react-dom` carry it, pure
28
- files do not, so server components can call `m()`, the formats and the status maps directly.
29
-
30
- Allowed imports between entries (run time): `logic → i18n`; `primitives → i18n`; `list → logic, i18n, primitives`;
31
- `page → list, logic, i18n, primitives`; `form → page, logic, i18n, primitives`; `translations → form, logic, i18n,
32
- primitives`; `media → list, form, logic, i18n, primitives`; `glass`, `data`, `provider → logic, i18n, primitives`;
33
- `next → logic, provider`; `notify-sonner → logic`.
9
+ Every import names an entry: `import { EntityListTable } from '@mgamadeus/ddd-admin-ui/list'`. ESM only; the
10
+ package ships one unbundled JS file and one declaration file per source file.
34
11
 
35
12
  ## Install
36
13
 
37
14
  ```bash
38
- pnpm add @mgamadeus/ddd-admin-ui @mgamadeus/ddd-web react react-dom lucide-react react-hook-form zod
39
- # optional, per entry: next (./next), sonner (./notify-sonner), recharts (chart files of ./data)
15
+ pnpm add @mgamadeus/ddd-admin-ui @mgamadeus/ddd-web radix-ui react react-dom lucide-react react-hook-form zod
16
+ # optional, per entry: next (./next), sonner (./notify-sonner); the host's Tailwind 4 build compiles the CSS
40
17
  ```
41
18
 
42
- | Peer | Range |
43
- |---|---|
44
- | `react`, `react-dom` | `^19.0.0` |
45
- | `@mgamadeus/ddd-web` | `>=0.13.0 <1.0.0` |
46
- | `lucide-react` | `>=0.550.0 <2` |
47
- | `react-hook-form` | `^7.65.0` |
48
- | `zod` | `^4.0.0` |
49
- | `next` (optional) | `^16.0.0` |
50
- | `sonner` (optional) | `^2.0.0` |
51
- | `recharts` (optional) | `^3.0.0` |
52
- | `tailwindcss` (optional, host requirement) | `^4.1.0` |
53
-
54
- ## Stylesheets
55
-
56
- ```css
57
- @import 'tailwindcss';
58
- @import '@mgamadeus/ddd-admin-ui/theme.css'; /* hosts that declare complete colours under the role names */
59
- @import '@mgamadeus/ddd-admin-ui/components.css'; /* always */
60
-
61
- :root {
62
- --card: #ffffff;
63
- --nav-h: 4rem;
64
- /* … every colour and property of tokens.json */
65
- }
66
- .dark {
67
- --card: #111827;
68
- /* … every themed entry */
69
- }
19
+ ## Entries
20
+
21
+ | Entry | What it holds | May import (besides React and its peers) |
22
+ |---|---|---|
23
+ | `./logic` | pure helpers (`formatDate`, `defineStatusMap`, conditions, schemas, `notify`, `runSequential`), React hooks without markup (`useUrlListState`, `useEntityDrawer`, `useRowSelection`, `useEntityTranslations`, …), browser helpers (`prepareImageFile`) | `./i18n` |
24
+ | `./i18n` | the UI text store (`m`, `translateText`, `setTranslations`), `useTranslate`, `<Translate>`, number / date formats of the UI locale, server-message translation | — |
25
+ | `./primitives` | buttons, inputs, selects, dialogs, sheets, popovers, menus, tooltips, tables, badges, `cn`, the portal container | `./i18n` |
26
+ | `./list` | entity list card, toolbar, search, filters, table, grid, load-more, status badge, cells, multi-select, combobox, bulk bar | logic, i18n, primitives |
27
+ | `./page` | page header and frame, `EntityListPage`, detail shell and header, tabs, section header, definition list, page toolbar, editable card, status callout, entity metadata | logic, i18n, primitives; from list only `EmptyValue`, `EntityListEmpty`, `EntityListCard` |
28
+ | `./form` | `Form`, `FormField`, `FormSection`, `FormActions`, `FormDrawer`, `FormHeader`, `FormWrapper`, `FormJumpBar`, `FormErrors`, `FormSubmitButton`, `useConfirmDialog` | logic, i18n, primitives; from page only `DetailHeader`, `EntityMetadata` |
29
+ | `./translations` | `TranslatableInput`, `TranslatableMarkdown` (editor injected), their form-bound variants, `TranslationControls` | logic, i18n, primitives; from form only `fieldLabels`, `useConfirmDialog` |
30
+ | `./media` | `MediaItemField`, `FormMediaItemField`, `MediaItemPickerDialog`, `MediaPreview` | logic, i18n, primitives, list, form |
31
+ | `./glass` | `GlassPill`, `QuickFilterPills`, `CollapsibleCard`, `GlassGroup`, `ActionRow` | logic, i18n, primitives |
32
+ | `./provider` | `AdminUiProvider`, `useAdminUi`, `defaultStorageKey` | logic, i18n, primitives; types only from media and translations |
33
+ | `./next` | Next.js adapters: `useNextUrlStateAdapter`, `useNextDrawerUrlAdapter`, `useListViewParam`, the one URL writer (`queueSearchParamsWrite`) | logic, provider; the only entry importing `next/*` |
34
+ | `./notify-sonner` | `sonnerNotifications` (the notification adapter on `sonner`) and its `Toaster` | logic; the only entry importing `sonner` |
35
+ | `./theme.css`, `./components.css` | the Tailwind theme binding and the structural CSS of the blocks | — |
36
+ | `./tokens.json`, `./i18n-keys.json` | the host contract (colour roles, properties, layers, data attributes) and the text manifest | — |
37
+
38
+ Blocks never import `./provider`: screens read `useAdminUi()` and pass adapters to blocks as props. Some barrels still
39
+ re-export names that moved to another entry (for example `EntityListPage` from `./list`, which belongs to `./page`, or
40
+ the conditions and `notify` from `./form`, which belong to `./logic`); they are marked `@deprecated`. Import every name
41
+ from the entry that owns it.
42
+
43
+ ## Peers
44
+
45
+ | Package | Kind | Range |
46
+ |---|---|---|
47
+ | `react`, `react-dom` | peer | `^19.0.0` |
48
+ | `@mgamadeus/ddd-web` | peer | `>=0.13.0 <1` |
49
+ | `lucide-react` | peer | `>=0.550.0 <2` |
50
+ | `react-hook-form` | peer | `^7.65.0` |
51
+ | `zod` | peer | `^4.0.0` |
52
+ | `next` | optional peer | `^16.0.0` — needed by `./next` only |
53
+ | `sonner` | optional peer | `^2.0.0` — needed by `./notify-sonner` only |
54
+ | `tailwindcss` | optional peer | `^4.1.0` — the host's build compiles the CSS |
55
+ | `recharts` | optional peer | `^3.0.0` — reserved; no entry uses it yet |
56
+ | `radix-ui` | peer | `^1.8.1` — one copy per app, as with React (see below) |
57
+ | `class-variance-authority`, `cmdk`, `clsx`, `tailwind-merge` | dependencies | imported inside `./primitives` only |
58
+
59
+ Without `next` or `sonner` every entry except `./next` and `./notify-sonner` imports and type-checks.
60
+
61
+ **One Radix copy.** Radix keeps focus traps, outside-click layers and portals in module state. Two copies of one
62
+ Radix package in an app (the package's dialogs from `radix-ui`, a host dialog from an older single
63
+ `@radix-ui/react-dialog`) do not see each other: one overlay's focus trap does not pause for the other's, and an
64
+ outside click closes the wrong one. So `radix-ui` is a peer, and the host installs it once. A host that also uses single
65
+ `@radix-ui/*` packages aligns them to the exact versions `radix-ui` pins (its `package.json` lists them), with npm
66
+ `overrides` or pnpm `pnpm.overrides` where a dependency asks for another version. `cmdk` asks for its Radix packages
67
+ with caret ranges; in a host without an older single package they resolve to the copies `radix-ui` brings (checked with
68
+ npm and pnpm), and an older single package drags them onto the older copy. Check the install after every dependency
69
+ change, from the host folder:
70
+
71
+ ```sh
72
+ npx ddd-admin-ui-check-radix [host folder]
70
73
  ```
71
74
 
72
- `components.css` carries `@source "./";`, so the host's Tailwind scans the package's built files for class names.
73
- Colours are complete CSS colours (`#fff`, `oklch(…)`, `hsl(0 0% 100%)`), not bare channels. Layers
74
- (`--layer-overlay`, `--layer-popover`, …) default to Tailwind's `z-50` scale and can be raised by the host.
75
+ It reads the host's `node_modules` (npm and pnpm layouts) and the folders above it, and names every `radix-ui` /
76
+ `@radix-ui/*` package installed more than once, with its versions and where each copy sits (exit 1).
77
+
78
+ ## Host setup
79
+
80
+ 1. **Stylesheet**, after Tailwind and an animation plugin that provides `animate-in/out`, `fade-*`, `zoom-*`,
81
+ `slide-in-from-*` (for example `tw-animate-css`):
82
+
83
+ ```css
84
+ @import 'tailwindcss';
85
+ @import 'tw-animate-css';
86
+ @import '@mgamadeus/ddd-admin-ui/theme.css';
87
+ @import '@mgamadeus/ddd-admin-ui/components.css';
88
+
89
+ @custom-variant dark (&:is(.dark *));
90
+ ```
91
+
92
+ `components.css` carries `@source './'`, so Tailwind scans the package's built files without a host `@source` line.
93
+ `theme.css` binds the colour roles for a host whose colours are complete values under bare names (`--card: #fff`);
94
+ a host with another colour encoding provides the same utility names its own way and leaves `theme.css` out.
95
+
96
+ A host on a JavaScript Tailwind config puts the package imports before the `@config` line (Biome's CSS linter
97
+ refuses an `@import` after it; the built CSS is the same either way):
98
+
99
+ ```css
100
+ @import 'tailwindcss';
101
+ @import '@mgamadeus/ddd-admin-ui/theme.css';
102
+ @import '@mgamadeus/ddd-admin-ui/components.css';
103
+ @config '../tailwind.config.js';
104
+ ```
105
+
106
+ Cascade: the surfaces, the glass tones and the table card of a list sit in `@layer components`, so a host's own
107
+ layered rule can restyle them. Six rules of the list card stay unlayered because they must beat utilities on the
108
+ same elements: the list card frame (its overflow and radius utilities), the toolbar row (its bottom rule and padding),
109
+ the toolbar's filter controls (fill, glass shadow, edge colour of pills and outline buttons), the chips of a toolbar
110
+ multi-select, and the grid's scroll padding. A host overrides those with an unlayered rule of at least the same
111
+ specificity, loaded after `components.css`.
112
+
113
+ 2. **Tokens.** Declare on `:root` (and under `.dark` where themed) every property of
114
+ [`tokens.json`](./tokens.json): the 31 colour roles, `--nav-h`, `--content-max`, `--radius`, the surface and glass
115
+ alphas and shadows, `--glass-control-shadow`. Dark mode is a `.dark` class on an ancestor; the default border
116
+ colour is the `border` role. `components.css` sets the four `--layer-*` defaults (`raised` 10, `sticky` 20,
117
+ `overlay` 50, `popover` 50) with zero specificity in the lowest cascade layer, so any host value wins. Check a built
118
+ stylesheet against the contract:
119
+
120
+ ```sh
121
+ npx ddd-admin-ui-check-tokens <built css file or folder> [tokens.json]
122
+ ```
123
+
124
+ It names every missing utility, property, `.dark` value, layer default or data attribute, and every colour value
125
+ that does not fit its use. A role property that the stylesheet reads only inside a channel function
126
+ (`hsl(var(--card))`, `rgb(var(--card) / 0.5)`) may hold channels such as `0 0% 100%` (the bridge of a host whose
127
+ theme stores HSL channels); a property read anywhere else (`background-color: var(--card)`, `color-mix()`,
128
+ `light-dark()`, or passed on to another custom property that is read so) must hold a colour.
129
+
130
+ 3. **Provider** above every page. Blocks draw tooltips (a date cell shows the relative time on hover), so a page
131
+ without the provider fails with "`Tooltip` must be used within `TooltipProvider`".
132
+
133
+ ```tsx
134
+ 'use client';
135
+ import { useNextDrawerUrlAdapter, useNextUrlStateAdapter } from '@mgamadeus/ddd-admin-ui/next';
136
+ import { sonnerNotifications, Toaster } from '@mgamadeus/ddd-admin-ui/notify-sonner';
137
+ import { AdminUiProvider } from '@mgamadeus/ddd-admin-ui/provider';
138
+
139
+ export const Providers = ({ children }: { children: React.ReactNode }) => (
140
+ <AdminUiProvider
141
+ notifications={sonnerNotifications}
142
+ tooltipDelayMs={150}
143
+ useUrlStateAdapter={useNextUrlStateAdapter}
144
+ useDrawerUrlAdapter={useNextDrawerUrlAdapter}
145
+ >
146
+ {children}
147
+ <Toaster />
148
+ </AdminUiProvider>
149
+ );
150
+ ```
151
+
152
+ Props: `notifications` (registered for `notify`), `storageKey` (`(kind, id) => key`; default
153
+ `ddd-admin-ui.<kind>.<id>`), `portalContainer` (where dialogs, sheets, popovers, selects, menus and tooltips mount;
154
+ default `document.body`), `tooltipDelayMs`, `translations` (a `TranslationAdapter` that feeds the text store from a
155
+ host store), `useUrlStateAdapter`, `useDrawerUrlAdapter`, `upload`, `renderMarkdownEditor`, `aiTranslation`,
156
+ `preserveSearchParams` (search parameters the URL writer never removes). Without a notification adapter `notify.*`
157
+ does nothing and warns once outside production.
158
+
159
+ 4. **Confirmations.** Blocks that ask before a step open the package's confirm dialog (`useConfirmDialog`). A host
160
+ with its own confirmation service passes it as `confirm` (`(options: ConfirmOptions) => Promise<boolean>`, a stable
161
+ function): `FormDrawer` ("Discard changes?") and `TranslatableInput` / `TranslatableMarkdown` and their form-bound
162
+ variants ("Clear all translations?"). The package dialog then does not render. The host's dialog must come from the
163
+ same Radix copy as the blocks (see Peers).
164
+
165
+ ## Server and client
166
+
167
+ Every file that calls a hook, `createContext` or `react-dom` starts with `'use client'`; barrels and `./logic`'s pure
168
+ files carry none. Pure helpers therefore work in server code, for example in Next.js `metadata`:
75
169
 
76
- Check a host's built CSS against the package:
170
+ ```tsx
171
+ import { m } from '@mgamadeus/ddd-admin-ui/i18n';
172
+ import { defineStatusMap, formatDateTime } from '@mgamadeus/ddd-admin-ui/logic';
77
173
 
78
- ```bash
79
- node node_modules/@mgamadeus/ddd-admin-ui/scripts/check-tokens.mjs .next/static/css/*.css
174
+ export const metadata = { title: m('Users') };
175
+ const STATUS = defineStatusMap({ ACTIVE: { label: 'Active', tone: 'success' } });
80
176
  ```
81
177
 
82
- ## Provider
178
+ Client components (`DateCell`, `EntityListTable`, `Form`, …) render from server components as long as they get no
179
+ function props there.
83
180
 
84
- ```tsx
85
- 'use client';
86
- import { AdminUiProvider } from '@mgamadeus/ddd-admin-ui/provider';
87
- import { sonnerNotifications } from '@mgamadeus/ddd-admin-ui/notify-sonner';
181
+ A list rendered on the server hydrates without a mismatch: the stored grid/table view (`useListViewParam`) and the
182
+ saved filters of a list (`useUrlListState` with an adapter's `restore`) are read from browser storage only after
183
+ hydration, and applied in the render right after it. A list that mounts on the client (no server HTML) reads them in
184
+ its first render, so it never renders or requests twice. `useHydrated()` (`./logic`) gives the same switch to host
185
+ code.
88
186
 
89
- export const Providers = ({ children }: { children: React.ReactNode }) => (
90
- <AdminUiProvider notifications={sonnerNotifications}>{children}</AdminUiProvider>
91
- );
92
- ```
187
+ ## Texts
93
188
 
94
- ## Translations
189
+ The UI language lives in one store: `setTranslations(languageCode, writingStyle, bundle)` (or the provider's
190
+ `translations` adapter) sets it, `useTranslate().t` and `translateText` read it, `m('…')` marks a text for extraction
191
+ without translating it. A key is the English text, or `<text>__<context>` with a context.
95
192
 
96
- The package translates its own texts through its store (`setTranslations` from `./i18n`, or a `translations` adapter
97
- on the provider). `i18n-keys.json` lists every such text (`key` = text or `text__context`, `hint`, `files`), so a
98
- host's translation export can merge them with its own keys.
193
+ The package ships its texts as [`i18n-keys.json`](./i18n-keys.json) (`./i18n-keys.json`): every key with its text,
194
+ context, translator hint and the files that use it, sorted by key. A host's text export merges this manifest instead of
195
+ scanning the package (one usage per key, the hints with the host's own hint precedence). `ddd-admin-ui-i18n-manifest
196
+ --check` verifies that the installed package's manifest matches its built files (`--dir <package>` checks another
197
+ copy).
99
198
 
100
199
  ## Agent skill
101
200
 
@@ -103,8 +202,8 @@ host's translation export can merge them with its own keys.
103
202
  npx ddd-admin-ui link-skills # or: pnpm exec ddd-admin-ui link-skills
104
203
  ```
105
204
 
106
- Symlinks the skills shipped in `.claude/skills/` of the installed package into the project's `.claude/skills/`.
107
- Idempotent; repoints an existing symlink, never touches a real file or directory.
205
+ Symlinks the skills shipped in `.claude/skills/` of the installed package (`ddd-admin-ui-specialist`) into the
206
+ project's `.claude/skills/`. Idempotent; repoints an existing symlink, never touches a real file or directory.
108
207
 
109
208
  ## Versioning
110
209
 
@@ -116,16 +215,25 @@ Idempotent; repoints an existing symlink, never touches a real file or directory
116
215
  ```bash
117
216
  pnpm install
118
217
  pnpm typecheck
119
- pnpm test # unit tests and the check-package rules (node --test)
120
- pnpm i18n:manifest # after changing a translated text or the version
121
- pnpm build # tsc → dist, declaration specifiers, stylesheets and manifests
122
- node scripts/check-package.mjs .
218
+ pnpm test # unit tests beside the sources, script tests and a failing fixture per check-package rule
219
+ pnpm build # tsc → dist, declaration specifiers, stylesheets, manifests and shipped scripts
220
+ node scripts/check-package.mjs --dir .
123
221
  pnpm pack --pack-destination "$TMPDIR" && test/consumer/run.sh "$TMPDIR"/mgamadeus-ddd-admin-ui-*.tgz pnpm "$TMPDIR/consumer-pnpm"
124
222
  ```
125
223
 
126
- Source files import each other with explicit `.ts` / `.tsx` extensions and never through a directory.
127
- `scripts/check-package.mjs` lists its rules at the top of the file. `CHECK_PACKAGE_DENY` (comma-separated) adds words
128
- that must not appear in shipped files.
224
+ | Command | What it does |
225
+ |---|---|
226
+ | `node scripts/build.mjs` (`pnpm build`) | removes `dist`, `tsc -p tsconfig.build.json` (one JS and declaration file per source file, directives kept, `.js` specifiers), rewrites the declarations' specifiers to `.js`, copies CSS, JSON and the shipped scripts into `dist` |
227
+ | `node scripts/check-package.mjs --dir <package root or extracted tarball>` | the 13 package rules: exports and bins, directives, specifiers, no app alias, deny list (`--deny a,b` or `CHECK_PACKAGE_DENY`; `--require-deny-list` on release), declared dependencies, entry edges and reach, module state once, `files` and `sideEffects`, declarations in a strict consumer, no tests, fresh text manifest, tokens |
228
+ | `node scripts/tokens-utilities.mjs [--write]` | checks (or regenerates) the `utilities` lists of `tokens.json` from the source |
229
+ | `node scripts/build-i18n-manifest.mjs [--check]` (`pnpm i18n:manifest`) | regenerates `i18n-keys.json` from the source and `i18n/hints.json`; run it after changing a text or the version |
230
+ | `node scripts/check-tokens.mjs <css> [tokens.json]` | the host check above (shipped as `ddd-admin-ui-check-tokens`) |
231
+ | `node scripts/check-radix.mjs [host folder]` | the Radix copy check above (shipped as `ddd-admin-ui-check-radix`) |
232
+
233
+ Source files import each other with explicit `.ts` / `.tsx` extensions and never through a directory. The consumer
234
+ tests (`test/consumer/run.sh <tarball> <npm|pnpm> <workDir>`) install the packed tarball into a project without the
235
+ optional peers and into a Next 16 app, and check imports, strict type checks, the production build and CSS, hydration,
236
+ form labels across entries and nested overlays in headless Chrome.
129
237
 
130
238
  ## License
131
239