@mgamadeus/ddd-admin-ui 0.1.0 → 0.2.1

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 (553) hide show
  1. package/.claude/skills/ddd-admin-ui-specialist/SKILL.md +56 -2
  2. package/CHANGELOG.md +217 -0
  3. package/README.md +262 -23
  4. package/STANDARDS.md +171 -2
  5. package/dist/components.css +27 -3
  6. package/dist/data/DeltaText.d.ts +29 -0
  7. package/dist/data/DeltaText.d.ts.map +1 -0
  8. package/dist/data/DeltaText.js +36 -0
  9. package/dist/data/DeltaText.js.map +1 -0
  10. package/dist/data/MetricGrid.d.ts +15 -0
  11. package/dist/data/MetricGrid.d.ts.map +1 -0
  12. package/dist/data/MetricGrid.js +17 -0
  13. package/dist/data/MetricGrid.js.map +1 -0
  14. package/dist/data/MetricTile.d.ts +32 -0
  15. package/dist/data/MetricTile.d.ts.map +1 -0
  16. package/dist/data/MetricTile.js +13 -0
  17. package/dist/data/MetricTile.js.map +1 -0
  18. package/dist/data/NoteList.d.ts +19 -0
  19. package/dist/data/NoteList.d.ts.map +1 -0
  20. package/dist/data/NoteList.js +23 -0
  21. package/dist/data/NoteList.js.map +1 -0
  22. package/dist/data/delta.d.ts +40 -0
  23. package/dist/data/delta.d.ts.map +1 -0
  24. package/dist/data/delta.js +40 -0
  25. package/dist/data/delta.js.map +1 -0
  26. package/dist/data/index.d.ts +6 -0
  27. package/dist/data/index.d.ts.map +1 -0
  28. package/dist/data/index.js +7 -0
  29. package/dist/data/index.js.map +1 -0
  30. package/dist/design-studio/contract.d.ts +162 -0
  31. package/dist/design-studio/contract.d.ts.map +1 -0
  32. package/dist/design-studio/contract.js +2 -0
  33. package/dist/design-studio/contract.js.map +1 -0
  34. package/dist/design-studio/index.d.ts +45 -0
  35. package/dist/design-studio/index.d.ts.map +1 -0
  36. package/dist/design-studio/index.js +47 -0
  37. package/dist/design-studio/index.js.map +1 -0
  38. package/dist/form/ColorValueField.d.ts +37 -0
  39. package/dist/form/ColorValueField.d.ts.map +1 -0
  40. package/dist/form/ColorValueField.js +74 -0
  41. package/dist/form/ColorValueField.js.map +1 -0
  42. package/dist/form/FormDrawer.d.ts +11 -1
  43. package/dist/form/FormDrawer.d.ts.map +1 -1
  44. package/dist/form/FormDrawer.js +7 -2
  45. package/dist/form/FormDrawer.js.map +1 -1
  46. package/dist/form/index.d.ts +2 -0
  47. package/dist/form/index.d.ts.map +1 -1
  48. package/dist/form/index.js +2 -0
  49. package/dist/form/index.js.map +1 -1
  50. package/dist/glass/QuickFilterPills.d.ts +7 -0
  51. package/dist/glass/QuickFilterPills.d.ts.map +1 -1
  52. package/dist/glass/QuickFilterPills.js +4 -3
  53. package/dist/glass/QuickFilterPills.js.map +1 -1
  54. package/dist/i18n/format.d.ts +3 -2
  55. package/dist/i18n/format.d.ts.map +1 -1
  56. package/dist/i18n/format.js +3 -2
  57. package/dist/i18n/format.js.map +1 -1
  58. package/dist/i18n/formatLocale.d.ts +8 -0
  59. package/dist/i18n/formatLocale.d.ts.map +1 -0
  60. package/dist/i18n/formatLocale.js +10 -0
  61. package/dist/i18n/formatLocale.js.map +1 -0
  62. package/dist/i18n/hints.json +498 -1
  63. package/dist/i18n/index.d.ts +1 -0
  64. package/dist/i18n/index.d.ts.map +1 -1
  65. package/dist/i18n/index.js +1 -0
  66. package/dist/i18n/index.js.map +1 -1
  67. package/dist/i18n-keys.json +4444 -351
  68. package/dist/list/ActionsHeaderText.d.ts +5 -0
  69. package/dist/list/ActionsHeaderText.d.ts.map +1 -0
  70. package/dist/list/ActionsHeaderText.js +9 -0
  71. package/dist/list/ActionsHeaderText.js.map +1 -0
  72. package/dist/list/Combobox.d.ts +11 -1
  73. package/dist/list/Combobox.d.ts.map +1 -1
  74. package/dist/list/Combobox.js +10 -7
  75. package/dist/list/Combobox.js.map +1 -1
  76. package/dist/list/EntityListBody.d.ts +9 -1
  77. package/dist/list/EntityListBody.d.ts.map +1 -1
  78. package/dist/list/EntityListBody.js +5 -3
  79. package/dist/list/EntityListBody.js.map +1 -1
  80. package/dist/list/EntityListBulkBar.d.ts +45 -3
  81. package/dist/list/EntityListBulkBar.d.ts.map +1 -1
  82. package/dist/list/EntityListBulkBar.js +31 -5
  83. package/dist/list/EntityListBulkBar.js.map +1 -1
  84. package/dist/list/EntityListEmpty.d.ts +9 -3
  85. package/dist/list/EntityListEmpty.d.ts.map +1 -1
  86. package/dist/list/EntityListEmpty.js +3 -3
  87. package/dist/list/EntityListEmpty.js.map +1 -1
  88. package/dist/list/EntityListTable.d.ts +3 -2
  89. package/dist/list/EntityListTable.d.ts.map +1 -1
  90. package/dist/list/EntityListTable.js +12 -8
  91. package/dist/list/EntityListTable.js.map +1 -1
  92. package/dist/list/EntityListToolbar.d.ts +30 -0
  93. package/dist/list/EntityListToolbar.d.ts.map +1 -1
  94. package/dist/list/EntityListToolbar.js +18 -4
  95. package/dist/list/EntityListToolbar.js.map +1 -1
  96. package/dist/list/EntityListViewToggle.d.ts +4 -1
  97. package/dist/list/EntityListViewToggle.d.ts.map +1 -1
  98. package/dist/list/EntityListViewToggle.js +15 -4
  99. package/dist/list/EntityListViewToggle.js.map +1 -1
  100. package/dist/list/cells.d.ts +10 -2
  101. package/dist/list/cells.d.ts.map +1 -1
  102. package/dist/list/cells.js +15 -6
  103. package/dist/list/cells.js.map +1 -1
  104. package/dist/list/columns.d.ts +85 -0
  105. package/dist/list/columns.d.ts.map +1 -0
  106. package/dist/list/columns.js +88 -0
  107. package/dist/list/columns.js.map +1 -0
  108. package/dist/list/filters.d.ts +19 -1
  109. package/dist/list/filters.d.ts.map +1 -1
  110. package/dist/list/filters.js +47 -3
  111. package/dist/list/filters.js.map +1 -1
  112. package/dist/list/index.d.ts +6 -0
  113. package/dist/list/index.d.ts.map +1 -1
  114. package/dist/list/index.js +3 -0
  115. package/dist/list/index.js.map +1 -1
  116. package/dist/logic/browser/normalizeImage.d.ts +69 -0
  117. package/dist/logic/browser/normalizeImage.d.ts.map +1 -0
  118. package/dist/logic/browser/normalizeImage.js +147 -0
  119. package/dist/logic/browser/normalizeImage.js.map +1 -0
  120. package/dist/logic/index.d.ts +25 -2
  121. package/dist/logic/index.d.ts.map +1 -1
  122. package/dist/logic/index.js +15 -1
  123. package/dist/logic/index.js.map +1 -1
  124. package/dist/logic/pure/colorValue.d.ts +22 -0
  125. package/dist/logic/pure/colorValue.d.ts.map +1 -0
  126. package/dist/logic/pure/colorValue.js +34 -0
  127. package/dist/logic/pure/colorValue.js.map +1 -0
  128. package/dist/logic/pure/dateRangePresets.d.ts +33 -0
  129. package/dist/logic/pure/dateRangePresets.d.ts.map +1 -0
  130. package/dist/logic/pure/dateRangePresets.js +41 -0
  131. package/dist/logic/pure/dateRangePresets.js.map +1 -0
  132. package/dist/logic/pure/format.d.ts +3 -3
  133. package/dist/logic/pure/format.d.ts.map +1 -1
  134. package/dist/logic/pure/format.js +13 -12
  135. package/dist/logic/pure/format.js.map +1 -1
  136. package/dist/logic/pure/imageCrop.d.ts +99 -0
  137. package/dist/logic/pure/imageCrop.d.ts.map +1 -0
  138. package/dist/logic/pure/imageCrop.js +198 -0
  139. package/dist/logic/pure/imageCrop.js.map +1 -0
  140. package/dist/logic/pure/injectedApi.d.ts +83 -0
  141. package/dist/logic/pure/injectedApi.d.ts.map +1 -0
  142. package/dist/logic/pure/injectedApi.js +87 -0
  143. package/dist/logic/pure/injectedApi.js.map +1 -0
  144. package/dist/logic/pure/listTracks.d.ts +14 -2
  145. package/dist/logic/pure/listTracks.d.ts.map +1 -1
  146. package/dist/logic/pure/listTracks.js +15 -4
  147. package/dist/logic/pure/listTracks.js.map +1 -1
  148. package/dist/logic/pure/locales.d.ts +22 -0
  149. package/dist/logic/pure/locales.d.ts.map +1 -1
  150. package/dist/logic/pure/locales.js +43 -0
  151. package/dist/logic/pure/locales.js.map +1 -1
  152. package/dist/logic/pure/navigation.d.ts +159 -0
  153. package/dist/logic/pure/navigation.d.ts.map +1 -0
  154. package/dist/logic/pure/navigation.js +158 -0
  155. package/dist/logic/pure/navigation.js.map +1 -0
  156. package/dist/logic/pure/runSequential.d.ts +42 -0
  157. package/dist/logic/pure/runSequential.d.ts.map +1 -1
  158. package/dist/logic/pure/runSequential.js +65 -13
  159. package/dist/logic/pure/runSequential.js.map +1 -1
  160. package/dist/logic/pure/textLimits.d.ts +18 -0
  161. package/dist/logic/pure/textLimits.d.ts.map +1 -0
  162. package/dist/logic/pure/textLimits.js +14 -0
  163. package/dist/logic/pure/textLimits.js.map +1 -0
  164. package/dist/logic/react/textLimits.d.ts +8 -0
  165. package/dist/logic/react/textLimits.d.ts.map +1 -0
  166. package/dist/logic/react/textLimits.js +9 -0
  167. package/dist/logic/react/textLimits.js.map +1 -0
  168. package/dist/logic/react/useEntityTranslations.d.ts +16 -1
  169. package/dist/logic/react/useEntityTranslations.d.ts.map +1 -1
  170. package/dist/logic/react/useEntityTranslations.js +18 -4
  171. package/dist/logic/react/useEntityTranslations.js.map +1 -1
  172. package/dist/logic/react/useMediaQuery.d.ts +14 -0
  173. package/dist/logic/react/useMediaQuery.d.ts.map +1 -0
  174. package/dist/logic/react/useMediaQuery.js +24 -0
  175. package/dist/logic/react/useMediaQuery.js.map +1 -0
  176. package/dist/logic/react/useMemoryUrlState.d.ts +13 -0
  177. package/dist/logic/react/useMemoryUrlState.d.ts.map +1 -0
  178. package/dist/logic/react/useMemoryUrlState.js +41 -0
  179. package/dist/logic/react/useMemoryUrlState.js.map +1 -0
  180. package/dist/logic/react/useOptimisticRowPatches.d.ts +16 -0
  181. package/dist/logic/react/useOptimisticRowPatches.d.ts.map +1 -0
  182. package/dist/logic/react/useOptimisticRowPatches.js +39 -0
  183. package/dist/logic/react/useOptimisticRowPatches.js.map +1 -0
  184. package/dist/markdown/MarkdownEditor.d.ts +36 -0
  185. package/dist/markdown/MarkdownEditor.d.ts.map +1 -0
  186. package/dist/markdown/MarkdownEditor.js +36 -0
  187. package/dist/markdown/MarkdownEditor.js.map +1 -0
  188. package/dist/markdown/MarkdownPreview.d.ts +15 -0
  189. package/dist/markdown/MarkdownPreview.d.ts.map +1 -0
  190. package/dist/markdown/MarkdownPreview.js +17 -0
  191. package/dist/markdown/MarkdownPreview.js.map +1 -0
  192. package/dist/markdown/index.d.ts +7 -0
  193. package/dist/markdown/index.d.ts.map +1 -0
  194. package/dist/markdown/index.js +9 -0
  195. package/dist/markdown/index.js.map +1 -0
  196. package/dist/markdown/loadMarkdownLibrary.d.ts +28 -0
  197. package/dist/markdown/loadMarkdownLibrary.d.ts.map +1 -0
  198. package/dist/markdown/loadMarkdownLibrary.js +40 -0
  199. package/dist/markdown/loadMarkdownLibrary.js.map +1 -0
  200. package/dist/markdown/markdownPipeline.d.ts +20 -0
  201. package/dist/markdown/markdownPipeline.d.ts.map +1 -0
  202. package/dist/markdown/markdownPipeline.js +50 -0
  203. package/dist/markdown/markdownPipeline.js.map +1 -0
  204. package/dist/markdown/renderMarkdownEditor.d.ts +18 -0
  205. package/dist/markdown/renderMarkdownEditor.d.ts.map +1 -0
  206. package/dist/markdown/renderMarkdownEditor.js +14 -0
  207. package/dist/markdown/renderMarkdownEditor.js.map +1 -0
  208. package/dist/markdown/useMarkdownLibrary.d.ts +24 -0
  209. package/dist/markdown/useMarkdownLibrary.d.ts.map +1 -0
  210. package/dist/markdown/useMarkdownLibrary.js +47 -0
  211. package/dist/markdown/useMarkdownLibrary.js.map +1 -0
  212. package/dist/media/ImageCropDialog.d.ts +48 -0
  213. package/dist/media/ImageCropDialog.d.ts.map +1 -0
  214. package/dist/media/ImageCropDialog.js +203 -0
  215. package/dist/media/ImageCropDialog.js.map +1 -0
  216. package/dist/media/MediaItemField.d.ts.map +1 -1
  217. package/dist/media/MediaItemField.js +3 -1
  218. package/dist/media/MediaItemField.js.map +1 -1
  219. package/dist/media/index.d.ts +2 -0
  220. package/dist/media/index.d.ts.map +1 -1
  221. package/dist/media/index.js +2 -0
  222. package/dist/media/index.js.map +1 -1
  223. package/dist/next/index.d.ts +1 -0
  224. package/dist/next/index.d.ts.map +1 -1
  225. package/dist/next/index.js +1 -0
  226. package/dist/next/index.js.map +1 -1
  227. package/dist/next/useNextPathname.d.ts +7 -0
  228. package/dist/next/useNextPathname.d.ts.map +1 -0
  229. package/dist/next/useNextPathname.js +9 -0
  230. package/dist/next/useNextPathname.js.map +1 -0
  231. package/dist/page/DetailHeader.d.ts.map +1 -1
  232. package/dist/page/DetailHeader.js +3 -1
  233. package/dist/page/DetailHeader.js.map +1 -1
  234. package/dist/page/MaintenanceActionCard.d.ts +29 -0
  235. package/dist/page/MaintenanceActionCard.d.ts.map +1 -0
  236. package/dist/page/MaintenanceActionCard.js +21 -0
  237. package/dist/page/MaintenanceActionCard.js.map +1 -0
  238. package/dist/page/PageHeader.d.ts.map +1 -1
  239. package/dist/page/PageHeader.js +3 -1
  240. package/dist/page/PageHeader.js.map +1 -1
  241. package/dist/page/RouteError.d.ts +26 -0
  242. package/dist/page/RouteError.d.ts.map +1 -0
  243. package/dist/page/RouteError.js +35 -0
  244. package/dist/page/RouteError.js.map +1 -0
  245. package/dist/page/RouteLoading.d.ts +16 -0
  246. package/dist/page/RouteLoading.d.ts.map +1 -0
  247. package/dist/page/RouteLoading.js +17 -0
  248. package/dist/page/RouteLoading.js.map +1 -0
  249. package/dist/page/SectionHeader.d.ts.map +1 -1
  250. package/dist/page/SectionHeader.js +3 -1
  251. package/dist/page/SectionHeader.js.map +1 -1
  252. package/dist/page/index.d.ts +6 -0
  253. package/dist/page/index.d.ts.map +1 -1
  254. package/dist/page/index.js +5 -0
  255. package/dist/page/index.js.map +1 -1
  256. package/dist/primitives/alert.d.ts +1 -1
  257. package/dist/primitives/badge.d.ts +1 -1
  258. package/dist/primitives/index.d.ts +1 -0
  259. package/dist/primitives/index.d.ts.map +1 -1
  260. package/dist/primitives/index.js +1 -0
  261. package/dist/primitives/index.js.map +1 -1
  262. package/dist/primitives/pathname.d.ts +22 -0
  263. package/dist/primitives/pathname.d.ts.map +1 -0
  264. package/dist/primitives/pathname.js +23 -0
  265. package/dist/primitives/pathname.js.map +1 -0
  266. package/dist/primitives/segmented-control.d.ts +37 -3
  267. package/dist/primitives/segmented-control.d.ts.map +1 -1
  268. package/dist/primitives/segmented-control.js +45 -10
  269. package/dist/primitives/segmented-control.js.map +1 -1
  270. package/dist/provider/AdminUiProvider.d.ts +2 -2
  271. package/dist/provider/AdminUiProvider.d.ts.map +1 -1
  272. package/dist/provider/AdminUiProvider.js +14 -3
  273. package/dist/provider/AdminUiProvider.js.map +1 -1
  274. package/dist/provider/index.d.ts +1 -1
  275. package/dist/provider/index.d.ts.map +1 -1
  276. package/dist/provider/types.d.ts +19 -0
  277. package/dist/provider/types.d.ts.map +1 -1
  278. package/dist/scripts/check-contrast.mjs +353 -0
  279. package/dist/shell/AccountMenu.d.ts +51 -0
  280. package/dist/shell/AccountMenu.d.ts.map +1 -0
  281. package/dist/shell/AccountMenu.js +34 -0
  282. package/dist/shell/AccountMenu.js.map +1 -0
  283. package/dist/shell/AppShell.d.ts +68 -0
  284. package/dist/shell/AppShell.d.ts.map +1 -0
  285. package/dist/shell/AppShell.js +56 -0
  286. package/dist/shell/AppShell.js.map +1 -0
  287. package/dist/shell/LanguageMenu.d.ts +36 -0
  288. package/dist/shell/LanguageMenu.d.ts.map +1 -0
  289. package/dist/shell/LanguageMenu.js +33 -0
  290. package/dist/shell/LanguageMenu.js.map +1 -0
  291. package/dist/shell/NavItemMarks.d.ts +21 -0
  292. package/dist/shell/NavItemMarks.d.ts.map +1 -0
  293. package/dist/shell/NavItemMarks.js +30 -0
  294. package/dist/shell/NavItemMarks.js.map +1 -0
  295. package/dist/shell/ShellBreadcrumbs.d.ts +26 -0
  296. package/dist/shell/ShellBreadcrumbs.d.ts.map +1 -0
  297. package/dist/shell/ShellBreadcrumbs.js +78 -0
  298. package/dist/shell/ShellBreadcrumbs.js.map +1 -0
  299. package/dist/shell/ShellDocumentTitle.d.ts +27 -0
  300. package/dist/shell/ShellDocumentTitle.d.ts.map +1 -0
  301. package/dist/shell/ShellDocumentTitle.js +50 -0
  302. package/dist/shell/ShellDocumentTitle.js.map +1 -0
  303. package/dist/shell/ShellMobileMenu.d.ts +33 -0
  304. package/dist/shell/ShellMobileMenu.d.ts.map +1 -0
  305. package/dist/shell/ShellMobileMenu.js +33 -0
  306. package/dist/shell/ShellMobileMenu.js.map +1 -0
  307. package/dist/shell/ShellNavLink.d.ts +18 -0
  308. package/dist/shell/ShellNavLink.d.ts.map +1 -0
  309. package/dist/shell/ShellNavLink.js +16 -0
  310. package/dist/shell/ShellNavLink.js.map +1 -0
  311. package/dist/shell/ShellNavList.d.ts +18 -0
  312. package/dist/shell/ShellNavList.d.ts.map +1 -0
  313. package/dist/shell/ShellNavList.js +45 -0
  314. package/dist/shell/ShellNavList.js.map +1 -0
  315. package/dist/shell/ShellNavRail.d.ts +11 -0
  316. package/dist/shell/ShellNavRail.d.ts.map +1 -0
  317. package/dist/shell/ShellNavRail.js +97 -0
  318. package/dist/shell/ShellNavRail.js.map +1 -0
  319. package/dist/shell/ShellSidebar.d.ts +32 -0
  320. package/dist/shell/ShellSidebar.d.ts.map +1 -0
  321. package/dist/shell/ShellSidebar.js +29 -0
  322. package/dist/shell/ShellSidebar.js.map +1 -0
  323. package/dist/shell/ShellTopBar.d.ts +23 -0
  324. package/dist/shell/ShellTopBar.d.ts.map +1 -0
  325. package/dist/shell/ShellTopBar.js +25 -0
  326. package/dist/shell/ShellTopBar.js.map +1 -0
  327. package/dist/shell/index.d.ts +28 -0
  328. package/dist/shell/index.d.ts.map +1 -0
  329. package/dist/shell/index.js +19 -0
  330. package/dist/shell/index.js.map +1 -0
  331. package/dist/shell/navClasses.d.ts +12 -0
  332. package/dist/shell/navClasses.d.ts.map +1 -0
  333. package/dist/shell/navClasses.js +14 -0
  334. package/dist/shell/navClasses.js.map +1 -0
  335. package/dist/shell/shellContext.d.ts +30 -0
  336. package/dist/shell/shellContext.d.ts.map +1 -0
  337. package/dist/shell/shellContext.js +7 -0
  338. package/dist/shell/shellContext.js.map +1 -0
  339. package/dist/shell/useShellShortcut.d.ts +12 -0
  340. package/dist/shell/useShellShortcut.d.ts.map +1 -0
  341. package/dist/shell/useShellShortcut.js +42 -0
  342. package/dist/shell/useShellShortcut.js.map +1 -0
  343. package/dist/shell/useSidebarCollapsed.d.ts +10 -0
  344. package/dist/shell/useSidebarCollapsed.d.ts.map +1 -0
  345. package/dist/shell/useSidebarCollapsed.js +49 -0
  346. package/dist/shell/useSidebarCollapsed.js.map +1 -0
  347. package/dist/shell-background/ShaderBackground.d.ts +27 -0
  348. package/dist/shell-background/ShaderBackground.d.ts.map +1 -0
  349. package/dist/shell-background/ShaderBackground.js +92 -0
  350. package/dist/shell-background/ShaderBackground.js.map +1 -0
  351. package/dist/shell-background/ShaderCanvas.d.ts +16 -0
  352. package/dist/shell-background/ShaderCanvas.d.ts.map +1 -0
  353. package/dist/shell-background/ShaderCanvas.js +197 -0
  354. package/dist/shell-background/ShaderCanvas.js.map +1 -0
  355. package/dist/shell-background/index.d.ts +5 -0
  356. package/dist/shell-background/index.d.ts.map +1 -0
  357. package/dist/shell-background/index.js +5 -0
  358. package/dist/shell-background/index.js.map +1 -0
  359. package/dist/shell-background/shader.d.ts +81 -0
  360. package/dist/shell-background/shader.d.ts.map +1 -0
  361. package/dist/shell-background/shader.js +194 -0
  362. package/dist/shell-background/shader.js.map +1 -0
  363. package/dist/showcase/Showcase.d.ts +12 -2
  364. package/dist/showcase/Showcase.d.ts.map +1 -1
  365. package/dist/showcase/Showcase.js +24 -6
  366. package/dist/showcase/Showcase.js.map +1 -1
  367. package/dist/showcase/coverage.d.ts.map +1 -1
  368. package/dist/showcase/coverage.js +55 -4
  369. package/dist/showcase/coverage.js.map +1 -1
  370. package/dist/showcase/fixtures.d.ts +9 -0
  371. package/dist/showcase/fixtures.d.ts.map +1 -0
  372. package/dist/showcase/fixtures.js +268 -0
  373. package/dist/showcase/fixtures.js.map +1 -0
  374. package/dist/showcase/index.d.ts +2 -0
  375. package/dist/showcase/index.d.ts.map +1 -1
  376. package/dist/showcase/index.js +1 -0
  377. package/dist/showcase/index.js.map +1 -1
  378. package/dist/showcase/sections/DataShowcase.d.ts +3 -0
  379. package/dist/showcase/sections/DataShowcase.d.ts.map +1 -0
  380. package/dist/showcase/sections/DataShowcase.js +15 -0
  381. package/dist/showcase/sections/DataShowcase.js.map +1 -0
  382. package/dist/showcase/sections/FormAdditionsShowcase.d.ts +3 -0
  383. package/dist/showcase/sections/FormAdditionsShowcase.d.ts.map +1 -0
  384. package/dist/showcase/sections/FormAdditionsShowcase.js +15 -0
  385. package/dist/showcase/sections/FormAdditionsShowcase.js.map +1 -0
  386. package/dist/showcase/sections/FormShowcase.d.ts.map +1 -1
  387. package/dist/showcase/sections/FormShowcase.js +2 -1
  388. package/dist/showcase/sections/FormShowcase.js.map +1 -1
  389. package/dist/showcase/sections/ListAdditionsShowcase.d.ts +3 -0
  390. package/dist/showcase/sections/ListAdditionsShowcase.d.ts.map +1 -0
  391. package/dist/showcase/sections/ListAdditionsShowcase.js +61 -0
  392. package/dist/showcase/sections/ListAdditionsShowcase.js.map +1 -0
  393. package/dist/showcase/sections/ListShowcase.d.ts.map +1 -1
  394. package/dist/showcase/sections/ListShowcase.js +2 -1
  395. package/dist/showcase/sections/ListShowcase.js.map +1 -1
  396. package/dist/showcase/sections/MarkdownShowcase.d.ts +21 -0
  397. package/dist/showcase/sections/MarkdownShowcase.d.ts.map +1 -0
  398. package/dist/showcase/sections/MarkdownShowcase.js +28 -0
  399. package/dist/showcase/sections/MarkdownShowcase.js.map +1 -0
  400. package/dist/showcase/sections/MediaCropShowcase.d.ts +3 -0
  401. package/dist/showcase/sections/MediaCropShowcase.d.ts.map +1 -0
  402. package/dist/showcase/sections/MediaCropShowcase.js +56 -0
  403. package/dist/showcase/sections/MediaCropShowcase.js.map +1 -0
  404. package/dist/showcase/sections/MediaShowcase.d.ts.map +1 -1
  405. package/dist/showcase/sections/MediaShowcase.js +2 -1
  406. package/dist/showcase/sections/MediaShowcase.js.map +1 -1
  407. package/dist/showcase/sections/PageAdditionsShowcase.d.ts +3 -0
  408. package/dist/showcase/sections/PageAdditionsShowcase.d.ts.map +1 -0
  409. package/dist/showcase/sections/PageAdditionsShowcase.js +7 -0
  410. package/dist/showcase/sections/PageAdditionsShowcase.js.map +1 -0
  411. package/dist/showcase/sections/PageShowcase.d.ts.map +1 -1
  412. package/dist/showcase/sections/PageShowcase.js +4 -3
  413. package/dist/showcase/sections/PageShowcase.js.map +1 -1
  414. package/dist/showcase/sections/PrimitivesAdditionsShowcase.d.ts +3 -0
  415. package/dist/showcase/sections/PrimitivesAdditionsShowcase.d.ts.map +1 -0
  416. package/dist/showcase/sections/PrimitivesAdditionsShowcase.js +20 -0
  417. package/dist/showcase/sections/PrimitivesAdditionsShowcase.js.map +1 -0
  418. package/dist/showcase/sections/PrimitivesShowcase.d.ts.map +1 -1
  419. package/dist/showcase/sections/PrimitivesShowcase.js +3 -2
  420. package/dist/showcase/sections/PrimitivesShowcase.js.map +1 -1
  421. package/dist/showcase/sections/ShellShowcase.d.ts +3 -0
  422. package/dist/showcase/sections/ShellShowcase.d.ts.map +1 -0
  423. package/dist/showcase/sections/ShellShowcase.js +71 -0
  424. package/dist/showcase/sections/ShellShowcase.js.map +1 -0
  425. package/dist/showcase/sections/TranslationsShowcase.d.ts +2 -0
  426. package/dist/showcase/sections/TranslationsShowcase.d.ts.map +1 -1
  427. package/dist/showcase/sections/TranslationsShowcase.js +5 -1
  428. package/dist/showcase/sections/TranslationsShowcase.js.map +1 -1
  429. package/dist/showcase/sections/WorkersShowcase.d.ts +3 -0
  430. package/dist/showcase/sections/WorkersShowcase.d.ts.map +1 -0
  431. package/dist/showcase/sections/WorkersShowcase.js +15 -0
  432. package/dist/showcase/sections/WorkersShowcase.js.map +1 -0
  433. package/dist/tokens.json +276 -5
  434. package/dist/translations/AppTranslationKeyDrawer.d.ts +14 -0
  435. package/dist/translations/AppTranslationKeyDrawer.d.ts.map +1 -0
  436. package/dist/translations/AppTranslationKeyDrawer.js +197 -0
  437. package/dist/translations/AppTranslationKeyDrawer.js.map +1 -0
  438. package/dist/translations/AppTranslationsScreen.d.ts +25 -0
  439. package/dist/translations/AppTranslationsScreen.d.ts.map +1 -0
  440. package/dist/translations/AppTranslationsScreen.js +139 -0
  441. package/dist/translations/AppTranslationsScreen.js.map +1 -0
  442. package/dist/translations/ConfigImportCards.d.ts +26 -0
  443. package/dist/translations/ConfigImportCards.d.ts.map +1 -0
  444. package/dist/translations/ConfigImportCards.js +59 -0
  445. package/dist/translations/ConfigImportCards.js.map +1 -0
  446. package/dist/translations/LanguagesScreen.d.ts +20 -0
  447. package/dist/translations/LanguagesScreen.d.ts.map +1 -0
  448. package/dist/translations/LanguagesScreen.js +110 -0
  449. package/dist/translations/LanguagesScreen.js.map +1 -0
  450. package/dist/translations/LocalesScreen.d.ts +22 -0
  451. package/dist/translations/LocalesScreen.d.ts.map +1 -0
  452. package/dist/translations/LocalesScreen.js +92 -0
  453. package/dist/translations/LocalesScreen.js.map +1 -0
  454. package/dist/translations/TranslatableField.d.ts +13 -2
  455. package/dist/translations/TranslatableField.d.ts.map +1 -1
  456. package/dist/translations/TranslatableField.js +23 -5
  457. package/dist/translations/TranslatableField.js.map +1 -1
  458. package/dist/translations/TranslatableInput.d.ts.map +1 -1
  459. package/dist/translations/TranslatableInput.js +4 -1
  460. package/dist/translations/TranslatableInput.js.map +1 -1
  461. package/dist/translations/TranslatableMarkdown.d.ts +2 -0
  462. package/dist/translations/TranslatableMarkdown.d.ts.map +1 -1
  463. package/dist/translations/TranslatableMarkdown.js +12 -7
  464. package/dist/translations/TranslatableMarkdown.js.map +1 -1
  465. package/dist/translations/TranslationCompleteness.d.ts +11 -0
  466. package/dist/translations/TranslationCompleteness.d.ts.map +1 -0
  467. package/dist/translations/TranslationCompleteness.js +73 -0
  468. package/dist/translations/TranslationCompleteness.js.map +1 -0
  469. package/dist/translations/adminFormat.d.ts +27 -0
  470. package/dist/translations/adminFormat.d.ts.map +1 -0
  471. package/dist/translations/adminFormat.js +39 -0
  472. package/dist/translations/adminFormat.js.map +1 -0
  473. package/dist/translations/adminTypes.d.ts +136 -0
  474. package/dist/translations/adminTypes.d.ts.map +1 -0
  475. package/dist/translations/adminTypes.js +9 -0
  476. package/dist/translations/adminTypes.js.map +1 -0
  477. package/dist/translations/api.d.ts +225 -0
  478. package/dist/translations/api.d.ts.map +1 -0
  479. package/dist/translations/api.js +132 -0
  480. package/dist/translations/api.js.map +1 -0
  481. package/dist/translations/focusOverLimit.d.ts +7 -0
  482. package/dist/translations/focusOverLimit.d.ts.map +1 -0
  483. package/dist/translations/focusOverLimit.js +23 -0
  484. package/dist/translations/focusOverLimit.js.map +1 -0
  485. package/dist/translations/index.d.ts +22 -0
  486. package/dist/translations/index.d.ts.map +1 -1
  487. package/dist/translations/index.js +13 -0
  488. package/dist/translations/index.js.map +1 -1
  489. package/dist/translations/useContentLocales.d.ts +17 -0
  490. package/dist/translations/useContentLocales.d.ts.map +1 -0
  491. package/dist/translations/useContentLocales.js +33 -0
  492. package/dist/translations/useContentLocales.js.map +1 -0
  493. package/dist/translations/useEntityTranslator.d.ts +34 -0
  494. package/dist/translations/useEntityTranslator.d.ts.map +1 -0
  495. package/dist/translations/useEntityTranslator.js +49 -0
  496. package/dist/translations/useEntityTranslator.js.map +1 -0
  497. package/dist/workers/WorkerRestartButton.d.ts +19 -0
  498. package/dist/workers/WorkerRestartButton.d.ts.map +1 -0
  499. package/dist/workers/WorkerRestartButton.js +59 -0
  500. package/dist/workers/WorkerRestartButton.js.map +1 -0
  501. package/dist/workers/WorkerTransportScreen.d.ts +24 -0
  502. package/dist/workers/WorkerTransportScreen.d.ts.map +1 -0
  503. package/dist/workers/WorkerTransportScreen.js +121 -0
  504. package/dist/workers/WorkerTransportScreen.js.map +1 -0
  505. package/dist/workers/WorkersOverviewScreen.d.ts +30 -0
  506. package/dist/workers/WorkersOverviewScreen.d.ts.map +1 -0
  507. package/dist/workers/WorkersOverviewScreen.js +61 -0
  508. package/dist/workers/WorkersOverviewScreen.js.map +1 -0
  509. package/dist/workers/api.d.ts +113 -0
  510. package/dist/workers/api.d.ts.map +1 -0
  511. package/dist/workers/api.js +73 -0
  512. package/dist/workers/api.js.map +1 -0
  513. package/dist/workers/charts.d.ts +94 -0
  514. package/dist/workers/charts.d.ts.map +1 -0
  515. package/dist/workers/charts.js +238 -0
  516. package/dist/workers/charts.js.map +1 -0
  517. package/dist/workers/format.d.ts +96 -0
  518. package/dist/workers/format.d.ts.map +1 -0
  519. package/dist/workers/format.js +231 -0
  520. package/dist/workers/format.js.map +1 -0
  521. package/dist/workers/history.d.ts +20 -0
  522. package/dist/workers/history.d.ts.map +1 -0
  523. package/dist/workers/history.js +84 -0
  524. package/dist/workers/history.js.map +1 -0
  525. package/dist/workers/index.d.ts +24 -0
  526. package/dist/workers/index.d.ts.map +1 -0
  527. package/dist/workers/index.js +19 -0
  528. package/dist/workers/index.js.map +1 -0
  529. package/dist/workers/overview.d.ts +72 -0
  530. package/dist/workers/overview.d.ts.map +1 -0
  531. package/dist/workers/overview.js +323 -0
  532. package/dist/workers/overview.js.map +1 -0
  533. package/dist/workers/status.d.ts +11 -0
  534. package/dist/workers/status.d.ts.map +1 -0
  535. package/dist/workers/status.js +106 -0
  536. package/dist/workers/status.js.map +1 -0
  537. package/dist/workers/transport.d.ts +78 -0
  538. package/dist/workers/transport.d.ts.map +1 -0
  539. package/dist/workers/transport.js +407 -0
  540. package/dist/workers/transport.js.map +1 -0
  541. package/dist/workers/types.d.ts +234 -0
  542. package/dist/workers/types.d.ts.map +1 -0
  543. package/dist/workers/types.js +8 -0
  544. package/dist/workers/types.js.map +1 -0
  545. package/dist/workers/useWorkersWindow.d.ts +12 -0
  546. package/dist/workers/useWorkersWindow.d.ts.map +1 -0
  547. package/dist/workers/useWorkersWindow.js +38 -0
  548. package/dist/workers/useWorkersWindow.js.map +1 -0
  549. package/dist/workers/window.d.ts +30 -0
  550. package/dist/workers/window.d.ts.map +1 -0
  551. package/dist/workers/window.js +39 -0
  552. package/dist/workers/window.js.map +1 -0
  553. package/package.json +39 -4
package/README.md CHANGED
@@ -21,19 +21,25 @@ pnpm add @mgamadeus/ddd-web radix-ui react react-dom lucide-react react-hook-for
21
21
 
22
22
  | Entry | What it holds | May import (besides React and its peers) |
23
23
  |---|---|---|
24
- | `./logic` | pure helpers (`formatDate`, `defineStatusMap`, conditions, schemas, `notify`, `runSequential`), React hooks without markup (`useUrlListState`, `useEntityDrawer`, `useRowSelection`, `useEntityTranslations`, …), browser helpers (`prepareImageFile`, `readStored` / `writeStored`, `buildStorageKey`), date input values (`toDateInputValue`, `fromDateTimeInputValue`, …), `withStickyParams`, `useLatestSearch`, `useConfirm` (the provider's confirmation), `WriteAccessProvider` / `useWriteAccess` | `./i18n` |
24
+ | `./logic` | pure helpers (`formatDate`, `defineStatusMap`, conditions, schemas, `notify`, `runSequential`, the navigation model with `resolveCrumbs`, `resolveDocumentTitle`, `filterNavigation`, `findActiveNavigation`), React hooks without markup (`useUrlListState`, `useEntityDrawer`, `useRowSelection`, `useEntityTranslations`, …), browser helpers (`prepareImageFile`, `readStored` / `writeStored`, `buildStorageKey`), date input values (`toDateInputValue`, `fromDateTimeInputValue`, …), `withStickyParams`, `useLatestSearch`, `useConfirm` (the provider's confirmation), `WriteAccessProvider` / `useWriteAccess`, date range presets, bulk summaries with skipped rows (`skipSequential`, `bulkSummaryText`), text limits (`countCodePoints`, `overLimitKeys`), colour values, `useMediaQuery`, the image normaliser (`normalizeImage`) and crop geometry, the api injection of the screen entries (`InjectableBaseApi`, `ApiQueryHook`, `staticQueryHook`, …), `useMemoryUrlState`, `useOptimisticRowPatches` | `./i18n` |
25
25
  | `./i18n` | the UI text store (`m`, `translateText`, `setTranslations`), `useTranslate`, `<Translate>`, number / date formats of the UI locale, server-message translation | — |
26
- | `./primitives` | buttons, inputs, selects, dialogs, sheets, popovers, menus, tooltips, tables, badges, `SegmentedControl`, `cn`, the portal container, the header slot of form actions (`FormActionsSlotProvider`, `FormActionsSlot`) | `./i18n` |
27
- | `./list` | entity list card, toolbar, search, filters, table, grid, load-more, status badge, cells, multi-select, combobox, bulk bar | logic, i18n, primitives |
28
- | `./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` |
29
- | `./form` | `Form`, `FormField`, `FormSection`, `FormActions`, `FormDrawer`, `FormDialog`, `FormHeader`, `FormWrapper`, `FormJumpBar`, `FormErrors`, `FormSubmitButton`, `useConfirmDialog` | logic, i18n, primitives; from page only `DetailHeader`, `EntityMetadata` |
30
- | `./translations` | `TranslatableInput`, `TranslatableMarkdown` (editor injected), their form-bound variants, `TranslationControls` | logic, i18n, primitives; from form only `fieldLabels`, `useConfirmDialog` |
31
- | `./media` | `MediaItemField`, `FormMediaItemField`, `MediaItemPickerDialog`, `MediaPreview` | logic, i18n, primitives, list, form |
26
+ | `./primitives` | buttons, inputs, selects, dialogs, sheets, popovers, menus, tooltips, tables, badges, `SegmentedControl`, `cn`, the portal container, the link component and pathname hook contexts, the header slot of form actions (`FormActionsSlotProvider`, `FormActionsSlot`) | `./i18n` |
27
+ | `./list` | entity list card, toolbar, search, filters, table, grid, load-more, status badge, cells, multi-select, combobox, bulk bar, column factories (`textColumn`, `moneyColumn`, `actionsColumn`, …), the toolbar's filter toggle, count and clear as blocks | logic, i18n, primitives |
28
+ | `./page` | page header and frame, `EntityListPage`, detail shell and header, tabs, section header, definition list, page toolbar, editable card, status callout, entity metadata, route states (`RouteError`, `RouteLoading`), `MaintenanceActionCard` | logic, i18n, primitives; from list only `EmptyValue`, `EntityListEmpty`, `EntityListCard` |
29
+ | `./form` | `Form`, `FormField`, `FormSection`, `FormActions`, `FormDrawer`, `FormDialog`, `FormHeader`, `FormWrapper`, `FormJumpBar`, `FormErrors`, `FormSubmitButton`, `useConfirmDialog`, `ColorValueField` | logic, i18n, primitives; from page only `DetailHeader`, `EntityMetadata` |
30
+ | `./translations` | `TranslatableInput`, `TranslatableMarkdown` (editor injected), their form-bound variants, `TranslationControls`, `focusFirstOverLimitTranslation`; the admin screens on the host's api (`createTranslationsApi`): `AppTranslationsScreen` with `AppTranslationKeyDrawer` and `TranslationCompleteness`, `LanguagesScreen`, `LocalesScreen`, `ConfigImportCard`, `useEntityTranslator`, `useContentLocales` | logic, i18n, primitives, list, page; from form only `fieldLabels`, `useConfirmDialog`, `Form`, `FormActions`, `FormDrawer`, `FormField`, `FormSubmitButton` |
31
+ | `./workers` | the screens of the worker monitoring on the host's api (`createWorkersApi`): `WorkersOverviewScreen`, `WorkerTransportScreen` and their parts (tiles, live panel, throughput and transport tables, history charts as SVG, message runs, processes, restart request), the status maps, the payload types | logic, i18n, primitives, list, page |
32
+ | `./media` | `MediaItemField`, `FormMediaItemField`, `MediaItemPickerDialog`, `MediaPreview`, `ImageCropDialog` (crop surface: file and aspect options in; cropped blob, skip or cancel out) | logic, i18n, primitives, list, form |
32
33
  | `./glass` | `GlassPill`, `QuickFilterPills`, `CollapsibleCard`, `GlassGroup`, `ActionRow` | logic, i18n, primitives |
34
+ | `./shell` | the application frame `AppShell` (top bar with slots, sidebar with groups, badges and locks, the icon rail and its `[` shortcut, the mobile menu, the content frame), `ShellBreadcrumbs`, `ShellDocumentTitle`, `AccountMenu`, `LanguageMenu`, their parts and hooks (`useSidebarCollapsed`, `useShellShortcut`) | logic, i18n, primitives |
35
+ | `./shell-background` | `ShaderBackground`: the animated WebGL background (loaded lazily; a host that does not import the entry pays nothing) | — |
33
36
  | `./provider` | `AdminUiProvider` (also the dialog behind `useConfirm`), `useAdminUi`, `defaultStorageKey` | logic, i18n, primitives; types only from media and translations |
34
- | `./next` | Next.js adapters: `useNextUrlStateAdapter`, `useNextDrawerUrlAdapter`, `useListViewParam`, the one URL writer (`queueSearchParamsWrite`) | logic, provider; the only entry importing `next/*` |
37
+ | `./next` | Next.js adapters: `useNextUrlStateAdapter`, `useNextDrawerUrlAdapter`, `useNextPathname`, `useListViewParam`, the one URL writer (`queueSearchParamsWrite`) | logic, provider; the only entry importing `next/*` |
35
38
  | `./notify-sonner` | `sonnerNotifications` (the notification adapter on `sonner`) and its `Toaster` | logic; the only entry importing `sonner` |
36
- | `./showcase` | `Showcase`: a development page drawing every block in the host theme, light and dark, one section per entry, the host's sections appended; `SHOWCASE_COVERAGE` | logic, i18n, primitives, list, page, form, translations, media, glass; never `./next` or `./notify-sonner` |
39
+ | `./showcase` | `Showcase`: a development page drawing every block in the host theme, light and dark, one section per entry, the host's sections appended; `SHOWCASE_COVERAGE`; the sample payloads of the screens (`showcaseWorkersData`, `showcaseTranslationsData`) | logic, i18n, primitives, list, page, form, translations, media, glass, data, workers, shell, shell-background; never `./next`, `./notify-sonner` or `./markdown` (its section loads through `loadMarkdown`) |
40
+ | `./data` | key figures: `MetricTile` (label, value, delta, hint, sparkline slot, skeleton), `MetricTileSkeleton`, `MetricGrid`, `DeltaText`, `NoteList`, the delta helpers `resolveDelta`, `relativeChange`, `deltaDirectionOf`, `deltaToneOf` | logic, i18n, primitives |
41
+ | `./markdown` | `MarkdownEditor`, `MarkdownPreview` (sanitised), `renderMarkdownEditor` (the `renderEditor` slot of `./translations` and `AdminUiProvider.renderMarkdownEditor`); loads `@uiw/react-md-editor` and `rehype-sanitize` after hydration | logic, i18n, primitives; translations type-only; the only entry reaching its optional peers |
42
+ | `./design-studio` | `designStudioComponents`: the `components` of `@mgamadeus/ddd-design-studio`'s provider, every slot mapped to the block of the same name; the slot types (`DesignStudioComponentsContract`, structural copy) | primitives, list, page, glass; never imports the studio |
37
43
  | `./theme.css`, `./components.css` | the Tailwind theme binding and the structural CSS of the blocks | — |
38
44
  | `./tokens.json`, `./i18n-keys.json` | the host contract (colour roles, properties, layers, data attributes) and the text manifest | — |
39
45
 
@@ -54,10 +60,14 @@ from the entry that owns it.
54
60
  | `next` | optional peer | `^16.0.0` — needed by `./next` only |
55
61
  | `sonner` | optional peer | `^2.0.0` — needed by `./notify-sonner` only |
56
62
  | `tailwindcss` | optional peer | `^4.1.0` — the host's build compiles the CSS |
63
+ | `@uiw/react-md-editor` | optional peer | `^4.1.0` — needed by `./markdown` only |
64
+ | `rehype-sanitize` | optional peer | `^6.0.0` — needed by `./markdown` only |
57
65
  | `radix-ui` | peer | `^1.8.1` — one copy per app, as with React (see below) |
58
66
  | `class-variance-authority`, `cmdk`, `clsx`, `tailwind-merge` | dependencies | imported inside `./primitives` only |
59
67
 
60
- Without `next` or `sonner` every entry except `./next` and `./notify-sonner` imports and type-checks.
68
+ Without `next` or `sonner` every entry except `./next` and `./notify-sonner` imports and type-checks. `./markdown`
69
+ imports its two peers only after hydration (a dynamic import), so it loads without them and a host that never imports
70
+ it never bundles them.
61
71
 
62
72
  **One Radix copy.** Radix keeps focus traps, outside-click layers and portals in module state. Two copies of one
63
73
  Radix package in an app (the package's dialogs from `radix-ui`, a host dialog from an older single
@@ -114,10 +124,12 @@ It reads the host's `node_modules` (npm and pnpm layouts) and the folders above
114
124
  2. **Tokens.** Declare on `:root` (and under `.dark` where themed) every property of
115
125
  [`tokens.json`](./tokens.json): the 31 colour roles, `--nav-h`, `--content-max`, `--radius`, the surface and glass
116
126
  alphas and shadows, `--glass-control-shadow`. Dark mode is a `.dark` class on an ancestor; the default border
117
- colour is the `border` role. `components.css` sets the four `--layer-*` defaults (`raised` 10, `sticky` 20,
118
- `overlay` 50, `popover` 50) and the two optional properties of `SegmentedControl` (`--segmented-control-radius`
119
- 9999px, `--segmented-control-duration` 200ms) with zero specificity in the lowest cascade layer, so any host value
120
- wins. Check a built
127
+ colour is the `border` role. `components.css` sets the five `--layer-*` defaults (`raised` 10, `sticky` 20, `chrome`
128
+ 30, `overlay` 50, `popover` 50), the two optional properties of `SegmentedControl` (`--segmented-control-radius`
129
+ 9999px, `--segmented-control-duration` 200ms) and the two of `AppShell` (`--sidebar-w` 16rem, `--sidebar-rail-w`
130
+ 5rem) with zero specificity in the lowest cascade layer, so any host value wins. `ShaderBackground` reads
131
+ `--shell-background-base`, `--shell-background-blob-1` and `--shell-background-blob-2` (optional; fallbacks
132
+ `--background`, `--brand-light`, `--accent`). Check a built
121
133
  stylesheet against the contract:
122
134
 
123
135
  ```sh
@@ -130,12 +142,42 @@ It reads the host's `node_modules` (npm and pnpm layouts) and the folders above
130
142
  theme stores HSL channels); a property read anywhere else (`background-color: var(--card)`, `color-mix()`,
131
143
  `light-dark()`, or passed on to another custom property that is read so) must hold a colour.
132
144
 
145
+ Check the contrast of the pairs `tokens.json` declares (`contrast.pairs`: text and UI roles on their backgrounds,
146
+ 4.5:1 for text, 3:1 for large text and UI parts), light and dark:
147
+
148
+ ```sh
149
+ npx ddd-admin-ui-check-contrast <built css file or folder> [tokens.json] [--exceptions <file.json>] [--allow-unevaluated]
150
+ ```
151
+
152
+ It prints each pair's ratio per theme and exits 1 on a pair below its minimum that no exception list names: the
153
+ package's (`contrast.exceptions` of `tokens.json`) merged with the host's file passed as `--exceptions`. A background
154
+ `role/NN` is that role at NN % over the card (status badges). Values it cannot compute (named colours, `color-mix()`,
155
+ `lab()`, `light-dark()`, …) count as failures unless `--allow-unevaluated` is passed. Run it in the host's CI on its
156
+ built CSS, like `ddd-admin-ui-check-tokens`.
157
+
158
+ An exception file is an array (or `{ "exceptions": [...] }`) of entries in the format of the package's list; `theme`
159
+ is optional (both themes when absent), `reason` is required:
160
+
161
+ ```json
162
+ [
163
+ { "foreground": "muted-foreground", "background": "card", "theme": "dark", "reason": "captions only, large text" }
164
+ ]
165
+ ```
166
+
167
+ The package lists the light status pairs (`success` on `card`, and `success`, `warning`, `destructive`, `info` on
168
+ their 15 % tints): status colours used as text or on their tint, themed by each host, until an emphasis role exists.
169
+
170
+ **Layers checklist.** The package's dialogs, sheets and drawers open at layer 50 (`--layer-overlay`), its popovers,
171
+ selects, menus and tooltips at 50 too (`--layer-popover`). A host whose own overlay scale is higher (a dialog at
172
+ 9999, toasts at 100) raises them on `:root` (`--layer-overlay: 10000; --layer-popover: 10001`), or the package's
173
+ dialogs open under the host's chrome.
174
+
133
175
  3. **Provider** above every page. Blocks draw tooltips (a date cell shows the relative time on hover), so a page
134
176
  without the provider fails with "`Tooltip` must be used within `TooltipProvider`".
135
177
 
136
178
  ```tsx
137
179
  'use client';
138
- import { useNextDrawerUrlAdapter, useNextUrlStateAdapter } from '@mgamadeus/ddd-admin-ui/next';
180
+ import { useNextDrawerUrlAdapter, useNextPathname, useNextUrlStateAdapter } from '@mgamadeus/ddd-admin-ui/next';
139
181
  import { sonnerNotifications, Toaster } from '@mgamadeus/ddd-admin-ui/notify-sonner';
140
182
  import { AdminUiProvider } from '@mgamadeus/ddd-admin-ui/provider';
141
183
 
@@ -145,6 +187,7 @@ It reads the host's `node_modules` (npm and pnpm layouts) and the folders above
145
187
  tooltipDelayMs={150}
146
188
  useUrlStateAdapter={useNextUrlStateAdapter}
147
189
  useDrawerUrlAdapter={useNextDrawerUrlAdapter}
190
+ usePathname={useNextPathname}
148
191
  >
149
192
  {children}
150
193
  <Toaster />
@@ -157,9 +200,12 @@ It reads the host's `node_modules` (npm and pnpm layouts) and the folders above
157
200
  default `document.body`), `tooltipDelayMs`, `translations` (a `TranslationAdapter` that feeds the text store from a
158
201
  host store), `useUrlStateAdapter`, `useDrawerUrlAdapter`, `upload`, `renderMarkdownEditor`, `aiTranslation`,
159
202
  `preserveSearchParams` (search parameters the URL writer never removes), `linkComponent` (the router link of every
160
- block that renders a link; wrap it with `withStickyParams` to keep sticky search parameters), `confirm` (the
161
- host's confirmation service behind `useConfirm()`). Without a notification adapter `notify.*` does nothing and
162
- warns once outside production.
203
+ block that renders a link; wrap it with `withStickyParams` to keep sticky search parameters), `usePathname` (the
204
+ router's pathname hook for the shell's active entry, breadcrumbs and title: `useNextPathname` from `./next`; without
205
+ it `location.pathname` after hydration), `confirm` (the host's confirmation service behind `useConfirm()`),
206
+ `formatLocale` (the `Intl` locale date cells format in, when it differs from the UI language's), `textLimits`
207
+ (`{ singleLine, multiline }`: default length limits of translatable text fields, in code points). Without a
208
+ notification adapter `notify.*` does nothing and warns once outside production.
163
209
 
164
210
  ```tsx
165
211
  const StickyLink: PageLinkComponent = ({ href, ...props }) => {
@@ -181,6 +227,13 @@ It reads the host's `node_modules` (npm and pnpm layouts) and the folders above
181
227
  variants ("Clear all translations?"). The package dialog then does not render. The host's dialog must come from the
182
228
  same Radix copy as the blocks (see Peers).
183
229
 
230
+ 5. **Markdown** (optional): with `@uiw/react-md-editor` and `rehype-sanitize` installed, pass
231
+ `renderMarkdownEditor({ rows: 8 })` from `./markdown` as `AdminUiProvider.renderMarkdownEditor` or as a field's
232
+ `renderEditor`. The editor loads after hydration (the server draws a skeleton, no `next/*`); its stylesheet comes
233
+ with the library's module, and a bundler that cannot import CSS from `node_modules` adds
234
+ `@import '@uiw/react-md-editor/markdown-editor.css'`. If the editor cannot be loaded at run time, the field is a plain
235
+ text area.
236
+
184
237
  ## Server and client
185
238
 
186
239
  Every file that calls a hook, `createContext` or `react-dom` starts with `'use client'`; barrels and `./logic`'s pure
@@ -204,6 +257,134 @@ function props there.
204
257
  `toDateTimeInputValue` / `fromDateTimeInputValue` (`./logic`). Empty or invalid gives `''` / `null`; no arithmetic. A
205
258
  local time skipped when the clocks go forward resolves an hour later, a repeated one to its first occurrence.
206
259
 
260
+ ## Screens on the host's API
261
+
262
+ `./workers` and `./translations` bring whole admin screens for endpoints of the framework. They never import a host
263
+ SDK and never reach RTK at run time: the host passes the RTK Query api it already has (`createApi` from
264
+ `@reduxjs/toolkit/query/react`, its base query carrying origin, session and refresh, e.g. `createDddBaseQuery` of
265
+ `@mgamadeus/ddd-web/api`), the entry injects its operations once and returns the hooks; every screen takes them as
266
+ `api`.
267
+
268
+ ```ts
269
+ // adminApi.ts — module scope, once
270
+ import { createTranslationsApi } from '@mgamadeus/ddd-admin-ui/translations';
271
+ import { createWorkersApi } from '@mgamadeus/ddd-admin-ui/workers';
272
+
273
+ export const workersApi = createWorkersApi({ baseApi: adminApi, apiPrefix: '/api/admin/maintenance/workers' });
274
+ export const translationsApi = createTranslationsApi({ baseApi: adminApi, apiPrefix: '/api/admin/common' });
275
+ ```
276
+
277
+ A second call with the same api and prefix returns the first result. The cache tags are the entry's own
278
+ (`AdminUiWorkers`, `AdminUiAppTranslations`, `AdminUiLanguages`, `AdminUiLocales`); a write invalidates what it
279
+ changes. The screens follow the host's setup: links through `AdminUiProvider.linkComponent`, writes (restart,
280
+ generation, toggles, imports, saves) disabled under `WriteAccessProvider` with its reason, confirmations through
281
+ `useConfirm`, toasts through `notify`. Filters, tabs, windows and the drawer live in the URL when the host passes its
282
+ adapters (`urlStateAdapter`, `drawerUrlAdapter`), in component state otherwise. `createStaticWorkersApi` /
283
+ `createStaticTranslationsApi` answer fixed payloads (the showcase's `showcaseWorkersData` /
284
+ `showcaseTranslationsData`) for design reviews and tests.
285
+
286
+ ### `./workers`
287
+
288
+ The screens of the worker monitoring, on Core's `WorkersControllerTrait` (mgamadeus/ddd **3.23.1** or later: the
289
+ endpoints since 3.18.0, throughput windows since 3.20.0, the recent window of a transport since 3.23.1). Since 3.35.1
290
+ the trait calls `throwForbiddenUnlessWorkersAccessAllowed()` first in every action: an application whose access rule is
291
+ not a role overrides it on its controller; the screens need nothing for it (a 403 shows as the screen's error).
292
+
293
+ | Hook | Endpoint (below `apiPrefix`) |
294
+ |---|---|
295
+ | `useOverviewQuery` | `GET /overview` |
296
+ | `useHistoryQuery` | `GET /history?from&to&stepSeconds` |
297
+ | `useTransportDetailQuery` | `GET /transports/{transport}?from&to&stepSeconds` |
298
+ | `useMessageRunsQuery`, `useProcessesQuery` | `GET /transports/{transport}/messageRuns`, `/processes` (QueryOptions) |
299
+ | `useRestartMutation` | `POST /restart` with `{}` or `{ transport }` (invalidates the live reads) |
300
+
301
+ ```tsx
302
+ 'use client';
303
+ // app/maintenance/workers/page.tsx and app/maintenance/workers/[transport]/page.tsx
304
+ import { useNextUrlStateAdapter } from '@mgamadeus/ddd-admin-ui/next';
305
+ import { WorkersOverviewScreen, WorkerTransportScreen } from '@mgamadeus/ddd-admin-ui/workers';
306
+
307
+ const transportHref = (transport: string, tab?: string) =>
308
+ `/maintenance/workers/${encodeURIComponent(transport)}${tab ? `?tab=${tab}` : ''}`;
309
+
310
+ export const WorkersPage = () => (
311
+ <WorkersOverviewScreen api={workersApi} transportHref={transportHref} urlStateAdapter={useNextUrlStateAdapter({ listId: 'workers' })} />
312
+ );
313
+ export const TransportPage = ({ transport }: { transport: string }) => (
314
+ <WorkerTransportScreen
315
+ api={workersApi}
316
+ transport={transport}
317
+ backHref="/maintenance/workers"
318
+ urlStateAdapter={useNextUrlStateAdapter({ listId: `workers.${transport}` })}
319
+ />
320
+ );
321
+ ```
322
+
323
+ The overview refreshes every 10 s and the history every minute while the tab is visible; the only action is the
324
+ restart request (no scaling control). The charts are SVG drawn by the entry (no chart library, no optional peer), in
325
+ the colour roles of `tokens.json`; a step without a reading is a gap, never a 0.
326
+
327
+ ### `./translations` (admin screens)
328
+
329
+ The app translation keys and values with their completeness, the languages and locales, and the entity translation,
330
+ on the application's admin controllers: the modules ship the entities and services, not controller traits
331
+ (**mgamadeus/ddd-common-translations** 1.0.7 or later for the completeness and the generation, checked with 1.1.1;
332
+ **mgamadeus/ddd-common-political** 1.0.0 or later for `Language` / `Locale`, checked with 1.0.19). The paths below
333
+ `apiPrefix` are those of these controllers; `paths` renames a segment
334
+ (`createTranslationsApi({ …, paths: { appTranslations: 'appTranslations' } })`).
335
+
336
+ | Hook | Endpoint (below `apiPrefix`, default segments) |
337
+ |---|---|
338
+ | `useAppTranslationKeysQuery`, `useAppTranslationKeyQuery` | `GET app-translations/keys/list`, `GET app-translations/keys/{id}?expand=appTranslationValues` |
339
+ | `useUpdateAppTranslationKeyMutation`, `useDeleteAppTranslationKeyMutation` | `PATCH app-translations/keys` (`{ appTranslationKey }`), `DELETE app-translations/keys/{id}` |
340
+ | `useUpdateAppTranslationValueMutation`, `useDeleteAppTranslationValueMutation` | `PATCH app-translations/values` (`{ appTranslationValue }`), `DELETE app-translations/values/{id}` |
341
+ | `useAppTranslationCompletenessQuery` | `GET app-translations/keys/completeness` |
342
+ | `useGenerateAppTranslationsMutation`, `useGenerateAllAppTranslationsMutation` | `GET app-translations/keys/generate/{localeId}?writingStyle=`, `GET app-translations/keys/generate-all` |
343
+ | `useLanguagesQuery`, `useUpdateLanguageMutation`, `useImportLanguagesFromConfigMutation` | `GET languages/list`, `PATCH languages` (`{ language }`), `GET languages/importFromConfig` |
344
+ | `useLocalesQuery`, `useUpdateLocaleMutation`, `useImportLocalesFromConfigMutation` | `GET locales/list`, `PATCH locales` (`{ locale }`), `GET locales/importFromConfig` |
345
+ | `useTranslateEntitiesMutation` | `POST translations/translateEntities` (`{ entitiesToTranslate, localesToTranslate }`) |
346
+
347
+ ```tsx
348
+ 'use client';
349
+ import { useNextDrawerUrlAdapter, useNextUrlStateAdapter } from '@mgamadeus/ddd-admin-ui/next';
350
+ import { AppTranslationsScreen, ConfigImportCard, LocalesScreen } from '@mgamadeus/ddd-admin-ui/translations';
351
+
352
+ export const AppTranslationsPage = () => (
353
+ <AppTranslationsScreen
354
+ api={translationsApi}
355
+ urlStateAdapter={useNextUrlStateAdapter({ listId: 'appTranslations' })}
356
+ drawerUrlAdapter={useNextDrawerUrlAdapter()}
357
+ />
358
+ );
359
+ export const LocalesPage = () => <LocalesScreen api={translationsApi} urlStateAdapter={useNextUrlStateAdapter({ listId: 'locales' })} />;
360
+ export const ImportsPage = () => <ConfigImportCard api={translationsApi} kind="languages" />;
361
+ ```
362
+
363
+ `useEntityTranslator(translationsApi)` translates an entity draft into one locale per request and feeds
364
+ `useTranslationRunner` (`./logic`); `useContentLocales(translationsApi, { fallback })` gives the content locale keys of
365
+ the active locales. `ConfigImportCard` is a `MaintenanceActionCard` (`./page`): title, description, run, the outcome of
366
+ the last run.
367
+
368
+ ## Design studio
369
+
370
+ `./design-studio` exports `designStudioComponents`, the `components` value the provider of
371
+ `@mgamadeus/ddd-design-studio` takes (targets studio **0.7.x**, checked against 0.7.3). Every slot maps to the block of
372
+ the same name: the shadcn-style primitives (`Button` … `DropdownMenuSeparator`), `Combobox`, `SearchField` and
373
+ `StatusBadge` from `./list`, `QuickFilterPills` from `./glass`, `PageHeader`, `StatusCallout`, `CardGrid` and
374
+ `PageSections` from `./page`.
375
+
376
+ ```tsx
377
+ import { designStudioComponents } from '@mgamadeus/ddd-admin-ui/design-studio';
378
+
379
+ <DesignStudioProvider components={designStudioComponents} /* api, router, paths, … */ />;
380
+ // one slot of your own: components={{ ...designStudioComponents, Button: MyButton }}
381
+ ```
382
+
383
+ The entry never imports the studio and adds no dependency: `DesignStudioComponentsContract` is a structural copy of
384
+ the studio's `DesignStudioComponents`, and the map is typed against it; the studio passes a subset of each block's
385
+ props, so the map is assignable to the studio's own type. A later studio minor that adds or changes a slot needs a new
386
+ release of this entry. The host's `TooltipProvider` (part of `AdminUiProvider`) and theme apply as for every block.
387
+
207
388
  ## Showcase
208
389
 
209
390
  `./showcase` is a development page, not a screen block: mount it on a route of the host, below `AdminUiProvider`, to
@@ -234,6 +415,63 @@ hydration, and applied in the render right after it. A list that mounts on the c
234
415
  its first render, so it never renders or requests twice. `useHydrated()` (`./logic`) gives the same switch to host
235
416
  code.
236
417
 
418
+ ## Shell and navigation
419
+
420
+ `./shell` is the application frame; its content comes from the host. ONE navigation tree (types in `./logic`) feeds
421
+ the sidebar, the mobile menu, the breadcrumbs and the document title:
422
+
423
+ ```tsx
424
+ 'use client';
425
+ import { m } from '@mgamadeus/ddd-admin-ui/i18n';
426
+ import type { NavigationItem } from '@mgamadeus/ddd-admin-ui/logic';
427
+ import { AccountMenu, AppShell, LanguageMenu, type UseEntityLabel } from '@mgamadeus/ddd-admin-ui/shell';
428
+
429
+ const NAVIGATION: NavigationItem<'item'>[] = [
430
+ { key: 'home', label: m('Home'), href: '/', exact: true, icon: House },
431
+ {
432
+ key: 'catalog', label: m('Catalog'), icon: Boxes, children: [
433
+ { key: 'items', label: m('Items'), href: '/items', icon: Shapes, badge: waiting, crumbs: [
434
+ { segment: 'create', label: m('Create item') },
435
+ { segment: ':itemId', entity: 'item', children: [{ segment: 'details', label: m('Details') }] },
436
+ ] },
437
+ { key: 'reports', label: m('Reports'), href: '/reports', lockedReason: m('Not in your plan') },
438
+ ],
439
+ },
440
+ { key: 'old', label: m('Old screen'), href: 'https://old.example/screen', external: true },
441
+ ];
442
+ // the page's own query, so the crumb sends no request of its own
443
+ const useEntityLabel: UseEntityLabel<'item'> = ({ id }) => { const query = useItemQuery(id); return { text: query.data?.name, isLoading: query.isLoading }; };
444
+
445
+ <AppShell navigation={NAVIGATION} canAccess={item => rights.allows(item.key)} useEntityLabel={useEntityLabel}
446
+ brand={<Link href="/" aria-label="Home"><Logo /></Link>} documentTitle={{ appName: 'Admin' }}
447
+ topBarEnd={<><LanguageMenu languages={languages} current={code} onChange={setCode} /><AccountMenu name={user.name} entries={accountEntries} /></>}>
448
+ {children}
449
+ </AppShell>
450
+ ```
451
+
452
+ - **Entries**: a leaf has `href` (`exact` for an overview whose siblings live below it), optional `badge` (work
453
+ waiting), `lockedReason` (a commercial lock: still a link, marked), `external` (a plain `<a>`, marked "Opens outside
454
+ this app"); a group has `children` (groups nest) and optionally its own `href` (its label links, the caret toggles).
455
+ Labels are UI texts, translated when rendered.
456
+ - **Breadcrumbs** (`resolveCrumbs`): the groups as text (a link when a group has its own page), the entry as a link,
457
+ then per leaf `crumbs` — child segments as literals or `:params` (a literal wins), each with a fixed `label`, a
458
+ `label(segment, t, params)`, or an `entity` key named by the host's `useEntityLabel` hook (the id while it loads). A
459
+ route without label adds no crumb; `link: false` keeps a crumb as text. Narrow trails fold into an ellipsis menu
460
+ (container queries, no measurement).
461
+ - **Rights**: `canAccess(item)` hides refused items from the sidebar (a group left empty disappears); the breadcrumbs
462
+ resolve against the whole tree and show a refused crumb as text. Presentation only: the server still checks.
463
+ - **Pathname and links**: the provider's `usePathname` (`useNextPathname`) and `linkComponent` (sticky parameters with
464
+ `withStickyParams`); no router import in the blocks. `AppShell.pathname` overrides.
465
+ - **Collapse**: the foot row and `[` toggle the icon rail (not while typing or in a dialog or menu, not below `lg`),
466
+ remembered in localStorage per `collapsedStorageKey`, applied right after hydration (the server renders the full
467
+ column). The rail shows groups as flyout menus.
468
+ - **Document title**: `documentTitle={{ appName }}` keeps `document.title` on the page (`Details · Blue widget · Admin`);
469
+ `resolveDocumentTitle(pathname, navigation, { appName })` gives the same text on the server.
470
+ - **Background**: `background={<ShaderBackground />}` from `./shell-background` (lazy WebGL, nothing with reduced
471
+ motion or without WebGL). The page background then sits on `<html>`.
472
+ - **RTL**: logical sides throughout; with Radix's `Direction.Provider dir="rtl"` the menus and the mobile sheet open
473
+ from the right.
474
+
237
475
  ## Texts
238
476
 
239
477
  The UI language lives in one store: `setTranslations(languageCode, writingStyle, bundle)` (or the provider's
@@ -264,7 +502,7 @@ project's `.claude/skills/`. Idempotent; repoints an existing symlink, never tou
264
502
 
265
503
  ## Versioning
266
504
 
267
- 0.x: each minor may break. Pin the exact version while the package is in 0.x (`"@mgamadeus/ddd-admin-ui": "0.1.0"`,
505
+ 0.x: each minor may break. Pin the exact version while the package is in 0.x (`"@mgamadeus/ddd-admin-ui": "0.2.1"`,
268
506
  `pnpm add -E` / `npm install -E`); modules peer on the version they were tested with. Stable releases are published
269
507
  under the `latest` dist-tag, pre-releases (`x.y.z-…`) under `next`. Changes per release: [CHANGELOG.md](CHANGELOG.md).
270
508
 
@@ -275,7 +513,7 @@ pnpm install
275
513
  pnpm typecheck
276
514
  pnpm test # unit tests beside the sources, script tests and a failing fixture per check-package rule
277
515
  pnpm build # tsc → dist, declaration specifiers, stylesheets, manifests and shipped scripts
278
- pnpm test:render # after the build: list snapshot (as in 0.1.0-rc.2), form actions snapshot (as in 0.1.0-rc.5), write access, status contexts, the showcase
516
+ pnpm test:render # after the build: list snapshot (as in 0.1.0-rc.2), form actions snapshot (as in 0.1.0-rc.5), write access, status contexts, the showcase, the shell
279
517
  node scripts/check-package.mjs --dir .
280
518
  pnpm pack --pack-destination "$TMPDIR" && test/consumer/run.sh "$TMPDIR"/mgamadeus-ddd-admin-ui-*.tgz pnpm "$TMPDIR/consumer-pnpm"
281
519
  ```
@@ -285,16 +523,17 @@ pnpm pack --pack-destination "$TMPDIR" && test/consumer/run.sh "$TMPDIR"/mgamade
285
523
  | `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` |
286
524
  | `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 |
287
525
  | `node scripts/tokens-utilities.mjs [--write]` | checks (or regenerates) the `utilities` lists of `tokens.json` from the source |
288
- | `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); `FormActions`, `FormSubmitButton`, `AddEntityButton`, `EntityListBulkBar` and the headers without the props of 0.1.0-rc.6 equal `form-actions-snapshot.html` (taken from 0.1.0-rc.5); `WriteAccessProvider` disables the write controls; a status map's translation context reaches `StatusBadge`; the showcase renders (light, dark, every section) and its coverage list matches the exports |
526
+ | `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); `FormActions`, `FormSubmitButton`, `AddEntityButton`, `EntityListBulkBar` and the headers without the props of 0.1.0-rc.6 equal `form-actions-snapshot.html` (taken from 0.1.0-rc.5); `WriteAccessProvider` disables the write controls; a status map's translation context reaches `StatusBadge`; the showcase renders (light, dark, every section) and its coverage list matches the exports; the `./workers` and `./translations` screens render on the sample payloads and write access disables their writes; the shell renders from one navigation (sidebar, breadcrumbs, title, rights predicate) |
289
527
  | `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 |
290
528
  | `node scripts/check-tokens.mjs <css> [tokens.json]` | the host check above (shipped as `ddd-admin-ui-check-tokens`) |
291
529
  | `node scripts/check-radix.mjs [host folder]` | the Radix copy check above (shipped as `ddd-admin-ui-check-radix`) |
530
+ | `node scripts/check-contrast.mjs <css> [tokens.json]` | the contrast check above (shipped as `ddd-admin-ui-check-contrast`) |
292
531
 
293
532
  Source files import each other with explicit `.ts` / `.tsx` extensions and never through a directory. The consumer
294
533
  tests (`test/consumer/run.sh <tarball> <npm|pnpm> <workDir>`) install the packed tarball into a project without the
295
534
  optional peers and into a Next 16 app, and check imports, strict type checks, the production build and CSS, hydration,
296
- form labels across entries, nested overlays, form dialogs, the save shortcut, header slots and confirmations in
297
- headless Chrome.
535
+ form labels across entries, nested overlays, form dialogs, the save shortcut, header slots, confirmations and the
536
+ shell (collapse, shortcut, mobile menu, breadcrumbs, title, RTL) in headless Chrome.
298
537
 
299
538
  ## License
300
539
 
package/STANDARDS.md CHANGED
@@ -10,11 +10,17 @@ Where the names below come from (setup and the entry list: [`README.md`](./READM
10
10
  |---|---|
11
11
  | `@mgamadeus/ddd-admin-ui/logic` | `useUrlListState`, `useRowSelection`, `useEntityDrawer`, `drawerKey`, `defineStatusMap`, `formatDate`, `formatDateTime`, `runSequentialWithSummary`, `nextListSort`, `parseListSort`, `formatListSort`, `useConfirm`, `WriteAccessProvider`, `useWriteAccess` |
12
12
  | `@mgamadeus/ddd-admin-ui/list` | `EntityListToolbar`, `EntityListBody`, `EntityListTable`, `EntityListViewToggle`, `EntityListBulkBar`, `FilterPanel`, `FilterText`, `FilterSelect`, `FilterMultiSelect`, `FilterDateRange`, `YES_NO_FILTER_OPTIONS`, `StatusBadge`, `IdCell`, `DateCell`, `BooleanCell`, `ImageCell`, `EmptyValue`, `orEmpty`, `MultiSelect`, `ChipToggleGroup`, `Combobox`, `Tag` |
13
- | `@mgamadeus/ddd-admin-ui/page` | `EntityListPage`, `PageToolbar`, `ExportButton`, `AddEntityButton`, `EntityDetailShell`, `SectionHeader`, `DefinitionList`, `EditableCard`, `IconValue`, `IconValueRow`, `PageSections`, `CardGrid`, `PageFrame`, `PageHeader` |
13
+ | `@mgamadeus/ddd-admin-ui/page` | `EntityListPage`, `PageToolbar`, `ExportButton`, `AddEntityButton`, `EntityDetailShell`, `SectionHeader`, `DefinitionList`, `EditableCard`, `IconValue`, `IconValueRow`, `PageSections`, `CardGrid`, `PageFrame`, `PageHeader`, `MaintenanceActionCard` |
14
14
  | `@mgamadeus/ddd-admin-ui/form` | `FormDrawer`, `FormDialog`, `FormActions`, `FormField`, `FormSection`, `FormHeader`, `useConfirmDialog` |
15
15
  | `@mgamadeus/ddd-admin-ui/glass` | `QuickFilterPills`, `CollapsibleCard`, `GlassGroup`, `ActionRow` |
16
16
  | `@mgamadeus/ddd-admin-ui/primitives` | `Button`, `Card`, `CardContent`, `SegmentedControl`, `FormActionsSlotProvider`, `FormActionsSlot` |
17
- | `@mgamadeus/ddd-admin-ui/next` | `useNextUrlStateAdapter`, `useNextDrawerUrlAdapter`, `useListViewParam` |
17
+ | `@mgamadeus/ddd-admin-ui/workers` | `createWorkersApi`, `WorkersOverviewScreen`, `WorkerTransportScreen` |
18
+ | `@mgamadeus/ddd-admin-ui/translations` | `createTranslationsApi`, `AppTranslationsScreen`, `LanguagesScreen`, `LocalesScreen` |
19
+ | `@mgamadeus/ddd-admin-ui/next` | `useNextUrlStateAdapter`, `useNextDrawerUrlAdapter`, `useListViewParam`, `useNextPathname` |
20
+ | `@mgamadeus/ddd-admin-ui/shell` | `AppShell`, `ShellBreadcrumbs`, `ShellDocumentTitle`, `AccountMenu`, `LanguageMenu`, `LanguageMenuSub`, `UseEntityLabel` |
21
+ | `@mgamadeus/ddd-admin-ui/shell-background` | `ShaderBackground` |
22
+ | `@mgamadeus/ddd-admin-ui/data` | `MetricTile`, `MetricGrid`, `DeltaText`, `NoteList`, `relativeChange` |
23
+ | `@mgamadeus/ddd-admin-ui/markdown` | `renderMarkdownEditor`, `MarkdownEditor`, `MarkdownPreview` |
18
24
 
19
25
  Every screen renders below `AdminUiProvider`. A screen that may not write sets that once with `WriteAccessProvider`
20
26
  (§ 15).
@@ -555,3 +561,166 @@ read `useWriteAccess()` (`disabled={!writeAccess.allowed}`).
555
561
 
556
562
  It replaces no guard: every write handler keeps its own check (`if (!writeAccess.allowed) return;`), and the server
557
563
  checks every request. Without a provider writes are allowed.
564
+
565
+ ## 16. Date presets, bulk menus, column factories, table breakpoint
566
+
567
+ ```tsx
568
+ // A date filter with presets: all time, today, last 7 / 30 days, custom (or the host's list). One write per pick.
569
+ <FilterDateRange label="Created" presets from={list.values.createdFrom} to={list.values.createdTo}
570
+ onFromChange={value => list.setValue('createdFrom', value)} onToChange={value => list.setValue('createdTo', value)}
571
+ onRangeChange={range => { list.setValue('createdFrom', range.from); list.setValue('createdTo', range.to); }} />
572
+
573
+ // Columns from factories: id, sort key and filter are separate inputs; formats are explicit.
574
+ const columns = [
575
+ idColumn<Order>({ id: 'id', header: 'ID', value: o => o.id, width: '88px' }),
576
+ textColumn<Order>({ id: 'customer', header: 'Customer', value: o => o.customer?.name, sortKey: 'customer.name', width: '2fr' }),
577
+ moneyColumn<Order>({ id: 'total', header: 'Total', value: o => o.total, currency: o => o.currency, width: '120px' }),
578
+ dateColumn<Order>({ id: 'created', header: 'Created', value: o => o.changeHistory?.createdTime, sortKey: 'created', sortStart: 'desc' }),
579
+ actionsColumn<Order>({ cell: o => <RowActions order={o} /> }), // width 'content', pinned to the end
580
+ ];
581
+
582
+ // Bulk actions with sub-choices, a confirmation with the count, a hint on a disabled action.
583
+ <EntityListBulkBar selection={selection} moreOnServer={list.hasMore} actions={[
584
+ { id: 'move', label: 'Move', choices: sections, choicesLabel: 'Move to', onChoose: choice => moveSelected(choice.id),
585
+ confirm: { title: m('Move %count% rows?'), confirmLabel: m('Move') } },
586
+ { id: 'activate', label: 'Activate', disabled: allActive, hint: m('Every selected row is active already'), onClick: activate },
587
+ ]} />
588
+ ```
589
+
590
+ - **Date presets** write the same `YYYY-MM-DD` bounds as typed dates, so "Clear filters" (both bounds `''`) is "All time"
591
+ and the URL keeps two keys. The filter derives the preset from the bounds (a range that matches no preset is custom);
592
+ a host that wants "Last 7 days" to roll forward keeps `preset` / `onPresetChange` itself. "Today" is the viewer's
593
+ local day (`today` overrides it).
594
+ - **Bulk summaries**: a run returns `skipSequential(reason)` for a row it leaves alone; the toast says
595
+ `Deleted 3 of 5 tracks · 2 skipped` (or the host's clauses per reason through `skipReasons`). A bulk endpoint's
596
+ answer uses `bulkSummaryText({ succeeded, failed, skipped }, labels)`.
597
+ - **Factories** return plain `EntityListColumn`s; mix them with hand-written columns. `moneyColumn` requires a currency,
598
+ `numberColumn` takes explicit `Intl.NumberFormatOptions` or the host's formatter; nothing falls back to a locale
599
+ default. A column with `width: 'content'` is as wide as its widest cell (a row's actions).
600
+ - **Breakpoint**: a list with cards shows the table from `md`; `tableBreakpoint="lg"` (many columns) or `"always"` on
601
+ `EntityListBody`, and the same value on `EntityListViewToggle`.
602
+ - **Outside the package toolbar** (a host filter sheet, a custom row): `FilterToggleButton`, `FilterCountBadge`,
603
+ `ClearFiltersButton` are the toolbar's own controls.
604
+ - `EntityListEmpty`: the built-in "Clear search" is an outline `sm` button (`xs` when compact); give a host `action` the
605
+ same size, or set `clearSearchSize`.
606
+ - `DateCell` formats in the provider's `formatLocale` when set (a cell's `locale` wins); `ImageCell` takes `bordered`
607
+ and `objectFit`.
608
+
609
+ ## 17. Translatable texts: language tabs and limits
610
+
611
+ ```tsx
612
+ const tabs = useEntityTranslations({ fields: ['name', 'description'], locales, defaultLocale: 'en::FORMAL',
613
+ tabModel: 'language', initialLocale: uiLanguageCode });
614
+
615
+ <FormTranslatableInput<Values> name="translations.name" label="Name" tabs={tabs} maxLength={80} />
616
+ // on submit: refuse when overLimitKeys(values.translations.name, 80).length > 0, then
617
+ focusFirstOverLimitTranslation(formElement);
618
+ ```
619
+
620
+ - **Keys stay full** (`locale::style`, the backend's `#[Translatable]` keys). With `tabModel: 'language'` each tab edits
621
+ one key, chosen the same way every time (the default locale for its language, else a stored key before an offered
622
+ one, in `styleOrder`) and named on the tab when it is not FORMAL (`DE · Informal`); the language's other keys stay in
623
+ the value and go back unchanged. Every loaded key is sent back; a cleared text removes only its key.
624
+ - **Limits** count code points (`countCodePoints`; `countText` for another count). The counter sits under the field, an
625
+ over-limit tab is marked, the field is `aria-invalid`; nothing is cut and a stored value over the limit stays. The
626
+ host sets defaults once (`AdminUiProvider textLimits={{ singleLine: 120, multiline: 2000 }}`); a field's
627
+ `maxLength` wins. The helper searches only the container it gets (the form or dialog that was submitted).
628
+
629
+ ## 18. Key figures — `MetricTile`, `MetricGrid`, `DeltaText`, `NoteList`
630
+
631
+ ```tsx
632
+ <MetricGrid columns={4} isLoading={query.isLoading}>
633
+ <MetricTile label="Visitors" icon={<Users aria-hidden />} value={formatUiNumber(stats.visitors)}
634
+ delta={<DeltaText value={relativeChange(stats.visitors, stats.previousVisitors)} format="percent"
635
+ title="Against the previous 30 days" />}
636
+ hint={`Previous: ${formatUiNumber(stats.previousVisitors)}`} sparkline={<HostSparkline points={stats.series} />} />
637
+ <MetricTile label="Errors" value={formatUiNumber(stats.errors)} delta={<DeltaText value={stats.errorChange} preference="lower" />} />
638
+ </MetricGrid>
639
+ <NoteList notes={[{ id: 'sampled', text: 'Figures are sampled every 15 minutes.' }]} />
640
+ ```
641
+
642
+ - Values come formatted (`formatUiNumber`, the host's money formatter); a tile never formats or loads.
643
+ - `DeltaText`: `preference="lower"` where down is good (costs, errors, durations), `"none"` where neither side is;
644
+ zero is neutral; `format="percent"` takes a fraction (`relativeChange`), a currency passes its code explicitly.
645
+ Arrow, sign and a hidden word carry the direction, never the colour alone.
646
+ - The sparkline is the host's chart in the `sparkline` slot; the package ships no chart library.
647
+ - Notes qualify the figures (sampling, a missing source); a state of the page is a `StatusCallout`.
648
+ - After a palette change run `ddd-admin-ui-check-contrast <built css>`: the declared pairs must reach AA in both themes.
649
+
650
+ ## 19. Markdown, route states, image crop, colour values, the drawer beside the page
651
+
652
+ - **Markdown fields**: `renderEditor={renderMarkdownEditor({ rows: 12 })}` from `./markdown` (or once as
653
+ `AdminUiProvider.renderMarkdownEditor`); read-only text: `MarkdownPreview`, the same sanitising (raw HTML parsed, then
654
+ GitHub's rules plus images; a single newline is a line break). Never `dangerouslySetInnerHTML` for user markdown.
655
+ - **Route states**: Next `error.tsx` renders `<RouteError onRetry={reset} onReport={host report} />` inside the shell;
656
+ `loading.tsx` renders `<RouteLoading variant="list" | "detail" | "form" />`. Layouts above them stay mounted.
657
+ - **Image crop**: a picked image goes through `ImageCropDialog` (aspect options from the host, `allowSkip` for "Use
658
+ original"); `onResult` gives a blob for the host's upload adapter. Minimum sizes and per-use presets are checked by the
659
+ host on the result; heavy normalisation can run in a host worker through `output.runInWorker`, whose worker calls
660
+ `renderNormalizedImage`.
661
+ - **Colour values**: `ColorValueField` with an explicit `format` (`hex`, or `hex-alpha` when the backend stores an
662
+ alpha); it writes normalised values only (`#rrggbb` / `#rrggbbaa`), `null` for none with `clearable`.
663
+ - **Master-detail drawer**: `FormDrawer modal={false}` from `md` up (`nonModalFrom`) sits beside the page without an
664
+ overlay; the page stays clickable, picking another row swaps the drawer's content, a click outside never closes it.
665
+ Below that width it is the modal drawer.
666
+ - **Server texts in pickers**: `translate={false}` on `Combobox`, `QuickFilterPills` or `SegmentedControl` (and per
667
+ option) for names from the server; UI texts stay translated.
668
+
669
+ ## 20. Framework screens — `./workers`, `./translations`
670
+
671
+ The worker monitoring and the translation admin are package screens: mount them, do not rebuild them.
672
+
673
+ ```tsx
674
+ // once, at module scope: the operations are injected into the host's RTK Query api
675
+ export const workersApi = createWorkersApi({ baseApi: adminApi, apiPrefix: '/api/admin/maintenance/workers' });
676
+ export const translationsApi = createTranslationsApi({ baseApi: adminApi, apiPrefix: '/api/admin/common' });
677
+
678
+ <WorkersOverviewScreen api={workersApi} transportHref={transportHref} urlStateAdapter={useNextUrlStateAdapter({ listId: 'workers' })} />
679
+ <LocalesScreen api={translationsApi} urlStateAdapter={useNextUrlStateAdapter({ listId: 'locales' })} />
680
+ ```
681
+
682
+ - Pass the host's URL adapters (`urlStateAdapter`, `drawerUrlAdapter`), so windows, tabs, filters and drawers are
683
+ links; without them the state is local to the screen.
684
+ - Gate writes with the screen's `WriteAccessProvider` like any other screen: restart, generation, toggles, imports and
685
+ saves follow it.
686
+ - A maintenance action of the host (a backfill, an import) is a `MaintenanceActionCard` (`./page`): the screen owns the
687
+ request and the confirmation (`useConfirm`), the card shows run, pending and the last outcome.
688
+ - Charts of the workers screens are the entry's SVG charts (`WorkerTimeChart`, `WorkerSparkline`): a `null` reading
689
+ is a gap, never a 0; no chart library is added for them.
690
+ ## 21. Application frame — `AppShell` and one navigation
691
+
692
+ One module of the host owns the navigation tree (`NavigationItem[]`, a module constant with `m()`-marked labels); the
693
+ area layout renders `AppShell` with it once, so route changes keep the frame mounted. Never a second list for the
694
+ breadcrumbs, the mobile menu or the tab title: they all resolve the same tree.
695
+
696
+ ```tsx
697
+ // area layout (client): the frame, its slots, the rights predicate, the entity names
698
+ <AppShell
699
+ navigation={ADMIN_NAVIGATION}
700
+ canAccess={canSee} // stable: useCallback over the session's rights
701
+ useEntityLabel={useAdminEntityLabel} // module-level hook: the page's own query per entity kind
702
+ collapsedStorageKey="admin.sidebar.collapsed" // one per area
703
+ brand={<HomeLink />}
704
+ topBarEnd={<><LanguageMenu … /><AccountMenu … /></>}
705
+ mobileMenuFooter={<AccountSummary name={user.name} />}
706
+ documentTitle={{ appName: t('Admin') }}
707
+ >
708
+ {children}
709
+ </AppShell>
710
+ ```
711
+
712
+ - **Crumbs live on the leaf** (`crumbs`): every page below an entry adds its segment there — `create`, `:itemId` with
713
+ `entity: 'item'`, the tabs as literal children. A page that is only a redirect gets `link: false`. A new entry or
714
+ segment in the tree gets its crumb and its title for free.
715
+ - **Entity names** come from the host hook with the same arguments as the page's own query (one cache entry, no extra
716
+ request); while it loads the crumb shows a skeleton, without a name the id.
717
+ - **Rights**: `canAccess` removes what the viewer may not open from the sidebar; the crumb of such a page stays as
718
+ text. Hiding is presentation — the server refuses the request.
719
+ - **Locks and badges**: `lockedReason` for a commercial lock (the entry stays a link, its page explains), `badge` only
720
+ for work with a deadline (a zero renders nothing).
721
+ - **Links and pathname** come from the provider (`linkComponent` with `withStickyParams`, `usePathname={useNextPathname}`);
722
+ the frame imports no router.
723
+ - **Background**: `ShaderBackground` from `./shell-background`, passed as `background`; a host without it never loads
724
+ it.
725
+ - **Page widths and insets** stay the page's (`PageFrame`, `EntityListPage`): `<main>` has no padding of its own.
726
+