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

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