@mgamadeus/ddd-admin-ui 0.1.0-rc.4 → 0.1.0-rc.6

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 (213) hide show
  1. package/.claude/skills/ddd-admin-ui-specialist/SKILL.md +39 -4
  2. package/CHANGELOG.md +111 -0
  3. package/README.md +34 -10
  4. package/STANDARDS.md +118 -22
  5. package/dist/components.css +2 -2
  6. package/dist/form/DrawerFooter.d.ts +9 -1
  7. package/dist/form/DrawerFooter.d.ts.map +1 -1
  8. package/dist/form/DrawerFooter.js +33 -32
  9. package/dist/form/DrawerFooter.js.map +1 -1
  10. package/dist/form/FormActions.d.ts +18 -13
  11. package/dist/form/FormActions.d.ts.map +1 -1
  12. package/dist/form/FormActions.js +110 -33
  13. package/dist/form/FormActions.js.map +1 -1
  14. package/dist/form/FormDialog.d.ts +51 -0
  15. package/dist/form/FormDialog.d.ts.map +1 -0
  16. package/dist/form/FormDialog.js +75 -0
  17. package/dist/form/FormDialog.js.map +1 -0
  18. package/dist/form/FormHeader.d.ts +6 -1
  19. package/dist/form/FormHeader.d.ts.map +1 -1
  20. package/dist/form/FormHeader.js +1 -1
  21. package/dist/form/FormHeader.js.map +1 -1
  22. package/dist/form/FormSubmitButton.d.ts +6 -1
  23. package/dist/form/FormSubmitButton.d.ts.map +1 -1
  24. package/dist/form/FormSubmitButton.js +5 -2
  25. package/dist/form/FormSubmitButton.js.map +1 -1
  26. package/dist/form/index.d.ts +2 -0
  27. package/dist/form/index.d.ts.map +1 -1
  28. package/dist/form/index.js +1 -0
  29. package/dist/form/index.js.map +1 -1
  30. package/dist/form/linkSubmitButtons.d.ts +7 -0
  31. package/dist/form/linkSubmitButtons.d.ts.map +1 -0
  32. package/dist/form/linkSubmitButtons.js +27 -0
  33. package/dist/form/linkSubmitButtons.js.map +1 -0
  34. package/dist/form/saveShortcut.d.ts +25 -0
  35. package/dist/form/saveShortcut.d.ts.map +1 -0
  36. package/dist/form/saveShortcut.js +59 -0
  37. package/dist/form/saveShortcut.js.map +1 -0
  38. package/dist/form/useConfirmDialog.d.ts +3 -2
  39. package/dist/form/useConfirmDialog.d.ts.map +1 -1
  40. package/dist/form/useConfirmDialog.js +21 -18
  41. package/dist/form/useConfirmDialog.js.map +1 -1
  42. package/dist/i18n/hints.json +13 -7
  43. package/dist/i18n-keys.json +64 -10
  44. package/dist/list/Combobox.d.ts +33 -3
  45. package/dist/list/Combobox.d.ts.map +1 -1
  46. package/dist/list/Combobox.js +71 -13
  47. package/dist/list/Combobox.js.map +1 -1
  48. package/dist/list/CopyButton.d.ts +23 -0
  49. package/dist/list/CopyButton.d.ts.map +1 -0
  50. package/dist/list/CopyButton.js +28 -0
  51. package/dist/list/CopyButton.js.map +1 -0
  52. package/dist/list/EntityListBody.d.ts +2 -2
  53. package/dist/list/EntityListBody.d.ts.map +1 -1
  54. package/dist/list/EntityListBody.js +2 -2
  55. package/dist/list/EntityListBody.js.map +1 -1
  56. package/dist/list/EntityListBulkBar.d.ts +7 -1
  57. package/dist/list/EntityListBulkBar.d.ts.map +1 -1
  58. package/dist/list/EntityListBulkBar.js +5 -1
  59. package/dist/list/EntityListBulkBar.js.map +1 -1
  60. package/dist/list/EntityListEmpty.d.ts +6 -1
  61. package/dist/list/EntityListEmpty.d.ts.map +1 -1
  62. package/dist/list/EntityListEmpty.js +4 -1
  63. package/dist/list/EntityListEmpty.js.map +1 -1
  64. package/dist/list/EntityListTable.d.ts +3 -1
  65. package/dist/list/EntityListTable.d.ts.map +1 -1
  66. package/dist/list/EntityListTable.js +4 -4
  67. package/dist/list/EntityListTable.js.map +1 -1
  68. package/dist/list/filters.d.ts +8 -1
  69. package/dist/list/filters.d.ts.map +1 -1
  70. package/dist/list/filters.js +5 -2
  71. package/dist/list/filters.js.map +1 -1
  72. package/dist/list/index.d.ts +2 -0
  73. package/dist/list/index.d.ts.map +1 -1
  74. package/dist/list/index.js +1 -0
  75. package/dist/list/index.js.map +1 -1
  76. package/dist/logic/browser/storage.d.ts +17 -0
  77. package/dist/logic/browser/storage.d.ts.map +1 -0
  78. package/dist/logic/browser/storage.js +40 -0
  79. package/dist/logic/browser/storage.js.map +1 -0
  80. package/dist/logic/index.d.ts +14 -0
  81. package/dist/logic/index.d.ts.map +1 -1
  82. package/dist/logic/index.js +8 -0
  83. package/dist/logic/index.js.map +1 -1
  84. package/dist/logic/pure/confirm.d.ts +16 -0
  85. package/dist/logic/pure/confirm.d.ts.map +1 -1
  86. package/dist/logic/pure/confirm.js +12 -0
  87. package/dist/logic/pure/confirm.js.map +1 -1
  88. package/dist/logic/pure/confirmQueue.d.ts +27 -0
  89. package/dist/logic/pure/confirmQueue.d.ts.map +1 -0
  90. package/dist/logic/pure/confirmQueue.js +52 -0
  91. package/dist/logic/pure/confirmQueue.js.map +1 -0
  92. package/dist/logic/pure/dateInput.d.ts +21 -0
  93. package/dist/logic/pure/dateInput.d.ts.map +1 -0
  94. package/dist/logic/pure/dateInput.js +79 -0
  95. package/dist/logic/pure/dateInput.js.map +1 -0
  96. package/dist/logic/pure/stickyParams.d.ts +10 -0
  97. package/dist/logic/pure/stickyParams.d.ts.map +1 -0
  98. package/dist/logic/pure/stickyParams.js +31 -0
  99. package/dist/logic/pure/stickyParams.js.map +1 -0
  100. package/dist/logic/pure/writeAccess.d.ts +18 -0
  101. package/dist/logic/pure/writeAccess.d.ts.map +1 -0
  102. package/dist/logic/pure/writeAccess.js +14 -0
  103. package/dist/logic/pure/writeAccess.js.map +1 -0
  104. package/dist/logic/react/useConfirm.d.ts +14 -0
  105. package/dist/logic/react/useConfirm.d.ts.map +1 -0
  106. package/dist/logic/react/useConfirm.js +16 -0
  107. package/dist/logic/react/useConfirm.js.map +1 -0
  108. package/dist/logic/react/useLatestSearch.d.ts +18 -0
  109. package/dist/logic/react/useLatestSearch.d.ts.map +1 -0
  110. package/dist/logic/react/useLatestSearch.js +37 -0
  111. package/dist/logic/react/useLatestSearch.js.map +1 -0
  112. package/dist/logic/react/useRowSelection.d.ts +12 -2
  113. package/dist/logic/react/useRowSelection.d.ts.map +1 -1
  114. package/dist/logic/react/useRowSelection.js +16 -8
  115. package/dist/logic/react/useRowSelection.js.map +1 -1
  116. package/dist/logic/react/writeAccess.d.ts +18 -0
  117. package/dist/logic/react/writeAccess.d.ts.map +1 -0
  118. package/dist/logic/react/writeAccess.js +18 -0
  119. package/dist/logic/react/writeAccess.js.map +1 -0
  120. package/dist/next/storage.d.ts +2 -10
  121. package/dist/next/storage.d.ts.map +1 -1
  122. package/dist/next/storage.js +2 -33
  123. package/dist/next/storage.js.map +1 -1
  124. package/dist/page/DefinitionList.d.ts +7 -2
  125. package/dist/page/DefinitionList.d.ts.map +1 -1
  126. package/dist/page/DefinitionList.js +4 -1
  127. package/dist/page/DefinitionList.js.map +1 -1
  128. package/dist/page/DetailHeader.d.ts +6 -1
  129. package/dist/page/DetailHeader.d.ts.map +1 -1
  130. package/dist/page/DetailHeader.js +3 -3
  131. package/dist/page/DetailHeader.js.map +1 -1
  132. package/dist/page/EntityDetailShell.d.ts +8 -2
  133. package/dist/page/EntityDetailShell.d.ts.map +1 -1
  134. package/dist/page/EntityDetailShell.js +6 -4
  135. package/dist/page/EntityDetailShell.js.map +1 -1
  136. package/dist/page/EntityListPage.d.ts +3 -1
  137. package/dist/page/EntityListPage.d.ts.map +1 -1
  138. package/dist/page/EntityListPage.js +1 -1
  139. package/dist/page/EntityListPage.js.map +1 -1
  140. package/dist/page/EntityTabs.d.ts +2 -2
  141. package/dist/page/EntityTabs.d.ts.map +1 -1
  142. package/dist/page/EntityTabs.js +3 -2
  143. package/dist/page/EntityTabs.js.map +1 -1
  144. package/dist/page/PageFrame.d.ts +6 -1
  145. package/dist/page/PageFrame.d.ts.map +1 -1
  146. package/dist/page/PageFrame.js +1 -1
  147. package/dist/page/PageFrame.js.map +1 -1
  148. package/dist/page/PageToolbar.d.ts +4 -3
  149. package/dist/page/PageToolbar.d.ts.map +1 -1
  150. package/dist/page/PageToolbar.js +9 -4
  151. package/dist/page/PageToolbar.js.map +1 -1
  152. package/dist/page/SectionHeader.d.ts +1 -1
  153. package/dist/page/SectionHeader.d.ts.map +1 -1
  154. package/dist/page/links.d.ts +2 -17
  155. package/dist/page/links.d.ts.map +1 -1
  156. package/dist/page/links.js +3 -3
  157. package/dist/page/links.js.map +1 -1
  158. package/dist/primitives/alert.d.ts +1 -1
  159. package/dist/primitives/badge.d.ts +1 -1
  160. package/dist/primitives/breadcrumb.d.ts.map +1 -1
  161. package/dist/primitives/breadcrumb.js +7 -0
  162. package/dist/primitives/breadcrumb.js.map +1 -1
  163. package/dist/primitives/command.js +1 -1
  164. package/dist/primitives/command.js.map +1 -1
  165. package/dist/primitives/confirmDialogView.d.ts +29 -0
  166. package/dist/primitives/confirmDialogView.d.ts.map +1 -0
  167. package/dist/primitives/confirmDialogView.js +63 -0
  168. package/dist/primitives/confirmDialogView.js.map +1 -0
  169. package/dist/primitives/formActionsSlot.d.ts +24 -0
  170. package/dist/primitives/formActionsSlot.d.ts.map +1 -0
  171. package/dist/primitives/formActionsSlot.js +51 -0
  172. package/dist/primitives/formActionsSlot.js.map +1 -0
  173. package/dist/primitives/index.d.ts +3 -0
  174. package/dist/primitives/index.d.ts.map +1 -1
  175. package/dist/primitives/index.js +2 -0
  176. package/dist/primitives/index.js.map +1 -1
  177. package/dist/primitives/link.d.ts +28 -0
  178. package/dist/primitives/link.d.ts.map +1 -0
  179. package/dist/primitives/link.js +15 -0
  180. package/dist/primitives/link.js.map +1 -0
  181. package/dist/primitives/segmented-control.d.ts +8 -0
  182. package/dist/primitives/segmented-control.d.ts.map +1 -1
  183. package/dist/primitives/segmented-control.js +24 -6
  184. package/dist/primitives/segmented-control.js.map +1 -1
  185. package/dist/provider/AdminUiProvider.d.ts +4 -3
  186. package/dist/provider/AdminUiProvider.d.ts.map +1 -1
  187. package/dist/provider/AdminUiProvider.js +12 -5
  188. package/dist/provider/AdminUiProvider.js.map +1 -1
  189. package/dist/provider/ConfirmHost.d.ts +10 -0
  190. package/dist/provider/ConfirmHost.d.ts.map +1 -0
  191. package/dist/provider/ConfirmHost.js +19 -0
  192. package/dist/provider/ConfirmHost.js.map +1 -0
  193. package/dist/provider/types.d.ts +12 -0
  194. package/dist/provider/types.d.ts.map +1 -1
  195. package/dist/showcase/coverage.d.ts.map +1 -1
  196. package/dist/showcase/coverage.js +6 -3
  197. package/dist/showcase/coverage.js.map +1 -1
  198. package/dist/showcase/sections/FormShowcase.d.ts.map +1 -1
  199. package/dist/showcase/sections/FormShowcase.js +41 -5
  200. package/dist/showcase/sections/FormShowcase.js.map +1 -1
  201. package/dist/showcase/sections/ListShowcase.d.ts.map +1 -1
  202. package/dist/showcase/sections/ListShowcase.js +36 -6
  203. package/dist/showcase/sections/ListShowcase.js.map +1 -1
  204. package/dist/showcase/sections/PageShowcase.d.ts.map +1 -1
  205. package/dist/showcase/sections/PageShowcase.js +5 -1
  206. package/dist/showcase/sections/PageShowcase.js.map +1 -1
  207. package/dist/showcase/sections/PrimitivesShowcase.d.ts.map +1 -1
  208. package/dist/showcase/sections/PrimitivesShowcase.js +2 -2
  209. package/dist/showcase/sections/PrimitivesShowcase.js.map +1 -1
  210. package/dist/translations/TranslationControls.d.ts.map +1 -1
  211. package/dist/translations/TranslationControls.js +8 -6
  212. package/dist/translations/TranslationControls.js.map +1 -1
  213. package/package.json +2 -2
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: ddd-admin-ui-specialist
3
- description: "Build admin screens with @mgamadeus/ddd-admin-ui and extend the package. Covers entries, 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), the segmented control, the showcase, detail shells, form drawers, server errors, the unsaved-changes guard, translations on full locale::style keys, media fields, toasts, layers, the portal container, 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."
3
+ description: "Build admin screens with @mgamadeus/ddd-admin-ui and extend the package. Covers entries, import matrix, host setup (AdminUiProvider above every page, theme.css, components.css, tokens.json with ddd-admin-ui-check-tokens, one Radix copy with ddd-admin-ui-check-radix), list pages with URL filters, bulk actions, wide tables (tracks, pins, sort), the segmented control, the showcase, detail shells, form drawers and dialogs (FormDialog), the save shortcut, FormActions in a header slot, useConfirm with typed phrases, write access (WriteAccessProvider), server errors, the unsaved-changes guard, locale::style translations, media fields, layers, i18n-keys.json, server vs client files, adding a block. Use when building or reviewing a list, detail, form or dialog screen, a page fails with Tooltip must be used within TooltipProvider, Cmd+S submits the wrong form or none, a confirm answers false, write controls must go off for read-only users, a table squeezes, an overlay misbehaves, or URL filters get lost."
4
4
  metadata:
5
5
  author: mgamadeus
6
6
  version: 0.1.0
@@ -24,14 +24,22 @@ installed package (`node_modules/@mgamadeus/ddd-admin-ui/`). This skill reaches
24
24
  | a wide table: column tracks, pinned columns, sortable headers, row numbers | `EntityListColumn` `width` / `minWidth` / `pin` / `align` / `sortKey` + `sort` / `onSortChange` / `showRowIndex` | list |
25
25
  | the sort in the URL | `formatListSort` / `parseListSort` / `nextListSort` (`key:asc`; `sortStart`, `sortRequired`) | logic |
26
26
  | one value out of a few (period, scope, view) | `SegmentedControl` (not tabs, not toggle chips) | primitives |
27
+ | a picker over a server search, with clear / create | `Combobox` `onSearch` + `useLatestSearch`, `clearable`, `onRequestCreate` | list, logic |
28
+ | copy a value next to it | `CopyButton` | list |
29
+ | one router link for every block, sticky search parameters | `AdminUiProvider.linkComponent` + `withStickyParams` | provider, logic |
30
+ | a `type="date"` / `datetime-local` value | `toDateInputValue` / `fromDateTimeInputValue` … with `'local'` or `'utc'` | logic |
27
31
  | see every block in the host theme, light and dark | `Showcase` on a development route | showcase |
28
32
  | a view that loads its own data (a tree) in the list card | `EntityListBody.renderOwnView` | list |
29
33
  | an entity detail with tabs | `EntityDetailShell` (+ `SectionHeader`, `DefinitionList`) | page |
30
34
  | a form page or drawer | `Form` + `FormField` / `FormSection` + `FormActions`, in `FormDrawer` | form |
35
+ | the Save / Cancel pill in the page header | `EntityDetailShell formActionsSlot`, or `FormHeader formActionsSlot` / a host `FormActionsSlot` inside one `FormActionsSlotProvider` | page, form, primitives |
36
+ | a short form in a dialog (rename, a reason) | `FormDialog` (`form` optional: react-hook-form or plain state) | form |
31
37
  | drawer state in the URL (`?edit=<id>`, `?create=1`) | `useEntityDrawer` with `useNextDrawerUrlAdapter` | logic, next |
32
38
  | a text per content locale | `useEntityTranslations` + `FormTranslatableInput` / `FormTranslatableMarkdown` | logic, translations |
33
39
  | a media reference | `FormMediaItemField` (+ the host's `MediaItemPickerDialog`) | media |
34
- | a confirmation | `useConfirmDialog` (returns `{ confirm, dialog }`) | form |
40
+ | a confirmation from screen code | `useConfirm()` → `confirm(options)` (the provider draws it; `requirePhrase` for a typed name) | logic |
41
+ | a confirmation inside a block with its own dialog | `useConfirmDialog` (returns `{ confirm, dialog }`) | form |
42
+ | write controls off for a read-only user | `WriteAccessProvider value={{ allowed, reason }}`, `useWriteAccess()`, `ignoreWriteAccess` on reading controls | logic |
35
43
  | a toast | `notify.success / info / error / loading / submitError` | logic |
36
44
 
37
45
  ## Rules that fail silently
@@ -62,6 +70,22 @@ installed package (`node_modules/@mgamadeus/ddd-admin-ui/`). This skill reaches
62
70
  - **SegmentedControl** is a radio group: exactly one value, one tab stop, arrows select (`activation="manual"`: Space /
63
71
  Enter). Tooltips (`iconOnly`, `disabledReason`) need `AdminUiProvider`. Corner and slide come from
64
72
  `--segmented-control-radius` / `--segmented-control-duration`.
73
+ - **Combobox server search**: pass `onSearch` and `isSearching` (from `useLatestSearch`, which drops answers to older
74
+ terms); the block debounces and never shows the previous term's options. A picked value outside the results needs
75
+ `selectedOption`.
76
+ - **Links**: set `linkComponent` once on `AdminUiProvider`; without it blocks render plain `<a>` (full page loads).
77
+ - **⌘S / Ctrl+S** (`FormActions`, `FormDialog`) listens on `document`: in a dialog or drawer it answers anywhere inside
78
+ the innermost one holding the focus; on a page with focus in the form, on its actions (also portalled) or nowhere.
79
+ It prevents the default whenever it is in scope (also with a disabled primary, then nothing submits); an event
80
+ already prevented is left alone, so of two forms only the first answers. It submits with `requestSubmit` through the
81
+ actions' own submit button, so a form needs a `type="submit"` button it owns.
82
+ - **FormActions placement**: inside a dialog that is not a `FormDrawer` the plain row comes by itself; `auto` moves the
83
+ pill into the slot closest above the form when the page mounts one (else as before); `row` never moves.
84
+ - **Confirmations** ask through `useConfirm()`: no dialog to render; without `AdminUiProvider` every call answers
85
+ `false` (one warning outside production). A host service goes into the provider's `confirm`.
86
+ - **Write access is a presentation aid.** `WriteAccessProvider` disables `FormSubmitButton`, `FormDialog`'s submit, the
87
+ bulk bar's actions and `AddEntityButton` as a button (never a link); a nested provider only narrows. Handlers keep
88
+ their guard and the server its check.
65
89
  - **Showcase** needs no optional peer: pass `loadNotifySonner={() => import('@mgamadeus/ddd-admin-ui/notify-sonner')}`
66
90
  only when sonner is installed. A new block gets a showcase sample and a `SHOWCASE_COVERAGE` entry, or the checks fail.
67
91
  - **Text contexts are literals.** `m('Failed', { context: 'import-status' })`: extractors (the package manifest and
@@ -114,7 +138,7 @@ export const ItemsScreen = () => {
114
138
  ```tsx
115
139
  const drawer = useEntityDrawer({ adapter: useNextDrawerUrlAdapter() });
116
140
  const form = useForm<Values>({ defaultValues });
117
- const { confirm, dialog } = useConfirmDialog();
141
+ const confirm = useConfirm(); // ./logic: the provider's dialog
118
142
  const { confirmDiscard } = useUnsavedChangesGuard(useFormDirty(form), confirm);
119
143
 
120
144
  <FormDrawer open={drawer.isOpen} onClose={drawer.close} title="Edit item">
@@ -131,10 +155,21 @@ const { confirmDiscard } = useUnsavedChangesGuard(useFormDirty(form), confirm);
131
155
  primary={<FormSubmitButton>Save</FormSubmitButton>}
132
156
  />
133
157
  </Form>
134
- {dialog}
135
158
  </FormDrawer>
136
159
  ```
137
160
 
161
+ ### Form in a dialog, a typed confirmation
162
+
163
+ ```tsx
164
+ <FormDialog<Values> open={open} onOpenChange={setOpen} title="Rename item" form={form}
165
+ onSubmit={async values => { await rename(values); setOpen(false); }}
166
+ submitLabel="Save" pendingLabel="Saving…" isPending={isRenaming} isDirty={form.formState.isDirty}>
167
+ <FormField<Values, 'name'> name="name" label="Name">{({ field, control }) => <Input {...control} {...field} />}</FormField>
168
+ </FormDialog>
169
+
170
+ if (await confirm({ title: `Delete ${site.name}?`, confirmVariant: 'destructive', confirmLabel: 'Delete', requirePhrase: site.name })) …
171
+ ```
172
+
138
173
  ### Translations and media in one form
139
174
 
140
175
  ```tsx
package/CHANGELOG.md CHANGED
@@ -3,6 +3,117 @@
3
3
  All notable changes to `@mgamadeus/ddd-admin-ui`. 0.x: each minor may break; pin the exact version while the package
4
4
  is in 0.x prereleases.
5
5
 
6
+ ## 0.1.0-rc.6
7
+
8
+ All additions are optional props or new exports: a caller that uses none of them renders the same DOM as in
9
+ 0.1.0-rc.5, proven by a server-render snapshot taken from 0.1.0-rc.5 (`form-actions-snapshot.html`: `FormActions`,
10
+ `FormSubmitButton`, `AddEntityButton`, `EntityListBulkBar`, `EntityDetailShell`, `FormHeader`, `DetailHeader`), next to
11
+ the list snapshot from 0.1.0-rc.2 (`pnpm test:render`; icons are reduced to their own classes, so the snapshot holds
12
+ at every lucide-react the peer range admits).
13
+
14
+ - `FormDialog` in `./form` (type `FormDialogProps`): a form in a dialog with or without a form library. Props `open`,
15
+ `onOpenChange`, `title`, `description`, `children`, `submitLabel`, `pendingLabel`, `cancelLabel`, `isPending`,
16
+ `isDirty` (a close request asks "Discard changes?"), `submitDisabled`, `submitVariant` (`default` / `destructive`),
17
+ `ignoreWriteAccess`, `className`, `onSubmit`, and an optional react-hook-form instance `form` (then `FormField` works
18
+ inside and `onSubmit` gets the parsed values; react-hook-form stays a peer). A real `<form>`: Enter in a text field
19
+ and ⌘S submit it; a dialog opened from it is its own form (its submit never reaches this one). Escape, the backdrop
20
+ and Cancel are ignored while pending or while the promise `onSubmit` returns runs; after a failed submit the dialog
21
+ is usable again. The focus returns to the element that had it when the dialog opened.
22
+ - `FormActions`:
23
+ - ⌘S / Ctrl+S listens on `document`. Inside a dialog or drawer (`[role="dialog"]`, `[role="alertdialog"]`) it answers
24
+ anywhere inside the innermost container holding the focus; elsewhere with focus in the form, on the actions (also
25
+ portalled) or nowhere (`body`). In scope it prevents the default, also while the primary is disabled (then nothing
26
+ submits); an event already `defaultPrevented` is left alone, so of two forms only one answers. It submits with
27
+ `form.requestSubmit(submitter)`, the actions' own submit button linked to the form first, else any submit button the
28
+ form owns. (Before: a listener on the form only; focus on `body` or on a portalled footer did nothing.)
29
+ - `placement: 'auto' | 'row' | 'header'` (`header` is new). `auto` moves the pill into the header slot closest above
30
+ the form when one is mounted, else it stays as before; `header` asks for the slot (without one: as `auto`); `row`
31
+ never moves. In a slot the actions are the same pill, floating under the top bar (`--nav-h`) once the header
32
+ scrolls away while the form is in view; the portalled submit button is linked back with the `form` attribute.
33
+ - Inside a dialog that is not a `FormDrawer` the actions render the plain row by themselves (as `sticky={false}`);
34
+ `sticky` without a value is now "pill on a page, row in a dialog", an explicit `sticky` keeps the pill there.
35
+ - Header slot in `./primitives`: `FormActionsSlotProvider`, `FormActionsSlot` (types `FormActionsSlotProviderProps`,
36
+ `FormActionsSlotProps`); `EntityDetailShell formActionsSlot` (brings its own provider; a nested shell takes the
37
+ actions of its own forms), `FormHeader formActionsSlot` and `DetailHeader formActionsSlot` (inside a provider around
38
+ header and form). Of several slots in one provider the one closest above the form wins.
39
+ - `useConfirm()` in `./logic` (with `ConfirmContext`): `confirm(options): Promise<boolean>` of the nearest
40
+ `AdminUiProvider`, which draws the dialog; nothing to render in the screen. Calls queue; each settles exactly once; an
41
+ unmounted provider settles its pending calls with `false`; Strict Mode safe; the focus returns to the element that
42
+ asked. Without a provider every call answers `false` with one warning outside production. `AdminUiProvider.confirm`
43
+ takes the host's own service (then `useConfirm()` calls it and the package dialog does not render).
44
+ `createConfirmQueue` (types `ConfirmQueue`, `ConfirmQueueEntry`) is the queue behind it. `useConfirmDialog` stays.
45
+ - `ConfirmOptions.requirePhrase` and `requirePhraseLabel`: the confirm button stays off until the phrase is typed
46
+ (trimmed, exact), in `useConfirm` and `useConfirmDialog` alike. `useConfirmDialog` now also returns the focus to the
47
+ element that had it when the dialog opened (before: Radix focused no trigger).
48
+ - Write access in `./logic`: `WriteAccessProvider value={{ allowed, reason? }}` (nestable, a subtree only narrows; no
49
+ provider = allowed), `useWriteAccess()`, `WriteAccessContext`, `narrowWriteAccess`, `WRITE_ACCESS_ALLOWED`, types
50
+ `WriteAccess`, `WriteAccessProviderProps`. Honoured by `FormSubmitButton`, `FormDialog`'s submit, the actions and
51
+ Delete of `EntityListBulkBar` (not Clear) and `AddEntityButton` as a button (never as a link); the reason is the
52
+ disabled control's title. `ignoreWriteAccess` on `FormSubmitButton`, `FormDialog` and `EntityListBulkAction` for a
53
+ control that only reads. A presentation aid: it replaces no handler guard and no server check.
54
+ - Showcase: samples of `FormDialog`, `useConfirm` (with a phrase), the header slot and write access;
55
+ `SHOWCASE_COVERAGE` lists `FormDialog`, `FormActionsSlotProvider`, `FormActionsSlot`.
56
+ - Text keys: new `Cancel__form-dialog`, `Type “%phrase%” to confirm`. `Cancel__confirm-dialog` and
57
+ `Confirm__confirm-dialog` are now used by `primitives/confirmDialogView.tsx` (the shared dialog).
58
+ - DOM of the new paths only: `data-form-actions-slot` on a slot, `data-form-actions-placement="header"` and
59
+ `data-form-actions-floating` on the pill in a slot, `data-confirm-phrase` around the phrase field.
60
+ - Docs: `STANDARDS.md` § 14 (form dialogs and confirmations) and § 15 (write access; the toolbar and bulk sections no
61
+ longer pass the write flag to every control), § 8 header slots; README provider props and confirmations; the skill.
62
+ - Consumer checks: the snapshot from 0.1.0-rc.5 and write access (server render); in the browser `FormDialog` (Enter,
63
+ pending, failed submit, a nested dialog, two forms on a page, focus return), the shortcut (focus on `body`, a drawer
64
+ footer button outside the form, focus in another form, a disabled primary, two nested dialogs), header slots (closest
65
+ slot, nested shells, `row`, the `form` attribute, the floating pill) and `useConfirm` (Escape, focus back to the
66
+ trigger, queue, phrase, inside a drawer, two providers, Strict Mode, unmount); unit tests for the confirm queue, the
67
+ missing-provider answer and the write access merge.
68
+
69
+ ## 0.1.0-rc.5
70
+
71
+ - `EntityListTable` / `EntityListBody`: `rowClassName(item, index)` for extra row classes.
72
+ - `useRowSelection`: `isSelectable(item)`. A row it refuses gets a disabled checkbox; "Select all loaded", the header
73
+ state, the count and `selectedKeys` take selectable rows only. `EntityListSelection` gains the optional
74
+ `isItemSelectionDisabled` (a row without a key still gets no checkbox).
75
+ - `Combobox`: `clearable` (a clear control; re-picking the picked option clears; without it the value is kept, as
76
+ before), `onSearch` (server search: no client filtering, debounced 300 ms, `''` on close; the list never shows the
77
+ previous term's options) with `isSearching`, option `group` (headings in first-appearance order) and `badge`,
78
+ `onRequestCreate` (a "Create “…”" row while no label equals the trimmed term), `selectedOption` (the label of a picked
79
+ value outside the options), `popoverClassName`; `COMBOBOX_SEARCH_DEBOUNCE_MS`. With `clearable`, `className` sizes a
80
+ wrapper around trigger and clear control.
81
+ - `./logic`: `useLatestSearch` (only the answer to the last term counts; aborts the previous request), date input
82
+ values `toDateInputValue`, `fromDateInputValue`, `toDateTimeInputValue`, `fromDateTimeInputValue` with an explicit
83
+ `'local' | 'utc'` zone (`DateInputZone`), `withStickyParams(href, names, currentSearch)`, the guarded storage helpers
84
+ `readStored` / `writeStored` (`StorageArea`, moved from the Next adapters, which use them from here) and
85
+ `buildStorageKey(prefix, area, name)` → `<prefix>.<area>.<name>`.
86
+ - `CopyButton` in `./list`: `value`, `label`, `reveal` (`always` / `hover`), `notify` (a toast through `notify`).
87
+ - Links: `AdminUiProvider.linkComponent` sets the router link of every block that renders a link (`EntityTabs`,
88
+ `SectionHeader` tabs, `EntityDetailShell` back link, `AddEntityButton`, and `BreadcrumbLink` with an `href`); a
89
+ block's own `linkComponent` still wins. Without the provider prop every link renders as before.
90
+ The link contract (`PageLinkProps`, `PageLinkComponent`, `AnchorLink`) moved to `./primitives` with
91
+ `LinkComponentContext`, `LinkComponentProvider`, `useLinkComponent`; `./page` still exports the old names.
92
+ - `EntityListEmpty size="compact"`: one inline line. `DefinitionList layout="rows"`: divided rows, label left, value
93
+ right. `FilterDateRange hideLabel` with `fromLabel` / `toLabel` (and `className`) for an inline range.
94
+ - `PageFrame` / `EntityListPage` `asSpecimen`: no `data-page-frame`, no full-height frame (used by the showcase, so a
95
+ host rule keyed to the attribute no longer fires there).
96
+ - `SegmentedControl`: a control wider than its container scrolls inside itself, keeping the selected and the focused
97
+ option in view (touch swipes scroll then, the drag preview stays for mouse and pen); options no longer shrink.
98
+ Options take `context` (passed to `t()`) and `translate: false` for already translated text.
99
+ - `ConfirmOptions.description`: documented — may be a React node; the package's own confirmations pass plain text.
100
+ - Showcase: samples of the new props and blocks; specimen cells shrink (`min-w-0`), so a wide specimen does not widen
101
+ the page at 390 px.
102
+ - DOM change: `FormActions` renders `data-form-actions="admin-ui"` (was an empty value), and `components.css` selects
103
+ that value only, so a host's own action bar with a bare `data-form-actions` is no longer restyled.
104
+ - Text keys changed (move host translations):
105
+ - `Search for a command to run...` → `Search for a command to run…`
106
+ - the translation progress statuses got the context `translation-status`: `Waiting`, `Translating`, `Done`,
107
+ `Failed`, `Cancelled` → `Waiting__translation-status`, `Translating__translation-status`,
108
+ `Done__translation-status`, `Failed__translation-status`, `Cancelled__translation-status`.
109
+ `Translating…` (the running button label) stays a separate key: a button text, not a status word.
110
+ - new: `Clear`, `Copied`, `Could not copy`, `Create “%term%”`.
111
+ - Consumer checks: Combobox in the browser (out-of-order answers, picked label outside the results, reset on close,
112
+ keyboard through groups and the create row, clearing), selectable rows, SegmentedControl in a 358 px container, the
113
+ showcase at 390 px without page scroll and without `data-page-frame`, links through the provider's link component
114
+ keeping sticky parameters; unit tests for the date values (UTC and Europe/Berlin around midnight and both clock
115
+ changes), `withStickyParams` and the storage helpers.
116
+
6
117
  ## 0.1.0-rc.4
7
118
 
8
119
  - `SegmentedControl` in `./primitives`: one value out of a few. Props `value`, `onValueChange`, `options` (`value`,
package/README.md CHANGED
@@ -20,16 +20,16 @@ pnpm add @mgamadeus/ddd-admin-ui @mgamadeus/ddd-web radix-ui react react-dom luc
20
20
 
21
21
  | Entry | What it holds | May import (besides React and its peers) |
22
22
  |---|---|---|
23
- | `./logic` | pure helpers (`formatDate`, `defineStatusMap`, conditions, schemas, `notify`, `runSequential`), React hooks without markup (`useUrlListState`, `useEntityDrawer`, `useRowSelection`, `useEntityTranslations`, …), browser helpers (`prepareImageFile`) | `./i18n` |
23
+ | `./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
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, `SegmentedControl`, `cn`, the portal container | `./i18n` |
25
+ | `./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` |
26
26
  | `./list` | entity list card, toolbar, search, filters, table, grid, load-more, status badge, cells, multi-select, combobox, bulk bar | logic, i18n, primitives |
27
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` |
28
+ | `./form` | `Form`, `FormField`, `FormSection`, `FormActions`, `FormDrawer`, `FormDialog`, `FormHeader`, `FormWrapper`, `FormJumpBar`, `FormErrors`, `FormSubmitButton`, `useConfirmDialog` | logic, i18n, primitives; from page only `DetailHeader`, `EntityMetadata` |
29
29
  | `./translations` | `TranslatableInput`, `TranslatableMarkdown` (editor injected), their form-bound variants, `TranslationControls` | logic, i18n, primitives; from form only `fieldLabels`, `useConfirmDialog` |
30
30
  | `./media` | `MediaItemField`, `FormMediaItemField`, `MediaItemPickerDialog`, `MediaPreview` | logic, i18n, primitives, list, form |
31
31
  | `./glass` | `GlassPill`, `QuickFilterPills`, `CollapsibleCard`, `GlassGroup`, `ActionRow` | logic, i18n, primitives |
32
- | `./provider` | `AdminUiProvider`, `useAdminUi`, `defaultStorageKey` | logic, i18n, primitives; types only from media and translations |
32
+ | `./provider` | `AdminUiProvider` (also the dialog behind `useConfirm`), `useAdminUi`, `defaultStorageKey` | logic, i18n, primitives; types only from media and translations |
33
33
  | `./next` | Next.js adapters: `useNextUrlStateAdapter`, `useNextDrawerUrlAdapter`, `useListViewParam`, the one URL writer (`queueSearchParamsWrite`) | logic, provider; the only entry importing `next/*` |
34
34
  | `./notify-sonner` | `sonnerNotifications` (the notification adapter on `sonner`) and its `Toaster` | logic; the only entry importing `sonner` |
35
35
  | `./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` |
@@ -155,10 +155,26 @@ It reads the host's `node_modules` (npm and pnpm layouts) and the folders above
155
155
  `ddd-admin-ui.<kind>.<id>`), `portalContainer` (where dialogs, sheets, popovers, selects, menus and tooltips mount;
156
156
  default `document.body`), `tooltipDelayMs`, `translations` (a `TranslationAdapter` that feeds the text store from a
157
157
  host store), `useUrlStateAdapter`, `useDrawerUrlAdapter`, `upload`, `renderMarkdownEditor`, `aiTranslation`,
158
- `preserveSearchParams` (search parameters the URL writer never removes). Without a notification adapter `notify.*`
159
- does nothing and warns once outside production.
158
+ `preserveSearchParams` (search parameters the URL writer never removes), `linkComponent` (the router link of every
159
+ block that renders a link; wrap it with `withStickyParams` to keep sticky search parameters), `confirm` (the
160
+ host's confirmation service behind `useConfirm()`). Without a notification adapter `notify.*` does nothing and
161
+ warns once outside production.
160
162
 
161
- 4. **Confirmations.** Blocks that ask before a step open the package's confirm dialog (`useConfirmDialog`). A host
163
+ ```tsx
164
+ const StickyLink: PageLinkComponent = ({ href, ...props }) => {
165
+ const search = useSearchParams();
166
+ return <Link href={withStickyParams(href, ['workspace', 'debug'], search)} {...props} />;
167
+ };
168
+ <AdminUiProvider linkComponent={StickyLink} …>
169
+ ```
170
+
171
+ 4. **Confirmations.** Screen code asks with `useConfirm()` (`./logic`): `confirm(options)` of the nearest
172
+ `AdminUiProvider`, which draws the package dialog (calls queue, each settles once, an unmounted provider answers its
173
+ pending calls `false`; `requirePhrase` keeps the confirm button off until a phrase is typed). Without a provider
174
+ every call answers `false` and warns once outside production. A host with its own service passes it as the
175
+ provider's `confirm`; `useConfirm()` then calls it and the package dialog does not render.
176
+
177
+ Blocks that ask before a step open the package's confirm dialog (`useConfirmDialog`). A host
162
178
  with its own confirmation service passes it as `confirm` (`(options: ConfirmOptions) => Promise<boolean>`, a stable
163
179
  function): `FormDrawer` ("Discard changes?") and `TranslatableInput` / `TranslatableMarkdown` and their form-bound
164
180
  variants ("Clear all translations?"). The package dialog then does not render. The host's dialog must come from the
@@ -180,6 +196,13 @@ const STATUS = defineStatusMap({ ACTIVE: { label: 'Active', tone: 'success' } })
180
196
  Client components (`DateCell`, `EntityListTable`, `Form`, …) render from server components as long as they get no
181
197
  function props there.
182
198
 
199
+ ## Dates in native inputs
200
+
201
+ `<input type="date">` and `type="datetime-local"` hold wall-clock text. Translate it with an explicit zone, `'local'`
202
+ (the browser's clock) or `'utc'`: `toDateInputValue(date, zone)` / `fromDateInputValue(text, zone)` and
203
+ `toDateTimeInputValue` / `fromDateTimeInputValue` (`./logic`). Empty or invalid gives `''` / `null`; no arithmetic. A
204
+ local time skipped when the clocks go forward resolves an hour later, a repeated one to its first occurrence.
205
+
183
206
  ## Showcase
184
207
 
185
208
  `./showcase` is a development page, not a screen block: mount it on a route of the host, below `AdminUiProvider`, to
@@ -251,7 +274,7 @@ pnpm install
251
274
  pnpm typecheck
252
275
  pnpm test # unit tests beside the sources, script tests and a failing fixture per check-package rule
253
276
  pnpm build # tsc → dist, declaration specifiers, stylesheets, manifests and shipped scripts
254
- pnpm test:render # after the build: list snapshot (as in 0.1.0-rc.2), status contexts, the showcase
277
+ 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
255
278
  node scripts/check-package.mjs --dir .
256
279
  pnpm pack --pack-destination "$TMPDIR" && test/consumer/run.sh "$TMPDIR"/mgamadeus-ddd-admin-ui-*.tgz pnpm "$TMPDIR/consumer-pnpm"
257
280
  ```
@@ -261,7 +284,7 @@ pnpm pack --pack-destination "$TMPDIR" && test/consumer/run.sh "$TMPDIR"/mgamade
261
284
  | `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` |
262
285
  | `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 |
263
286
  | `node scripts/tokens-utilities.mjs [--write]` | checks (or regenerates) the `utilities` lists of `tokens.json` from the source |
264
- | `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`; the showcase renders (light, dark, every section) and its coverage list matches the exports |
287
+ | `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 |
265
288
  | `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 |
266
289
  | `node scripts/check-tokens.mjs <css> [tokens.json]` | the host check above (shipped as `ddd-admin-ui-check-tokens`) |
267
290
  | `node scripts/check-radix.mjs [host folder]` | the Radix copy check above (shipped as `ddd-admin-ui-check-radix`) |
@@ -269,7 +292,8 @@ pnpm pack --pack-destination "$TMPDIR" && test/consumer/run.sh "$TMPDIR"/mgamade
269
292
  Source files import each other with explicit `.ts` / `.tsx` extensions and never through a directory. The consumer
270
293
  tests (`test/consumer/run.sh <tarball> <npm|pnpm> <workDir>`) install the packed tarball into a project without the
271
294
  optional peers and into a Next 16 app, and check imports, strict type checks, the production build and CSS, hydration,
272
- form labels across entries and nested overlays in headless Chrome.
295
+ form labels across entries, nested overlays, form dialogs, the save shortcut, header slots and confirmations in
296
+ headless Chrome.
273
297
 
274
298
  ## License
275
299
 
package/STANDARDS.md CHANGED
@@ -8,15 +8,16 @@ Where the names below come from (setup and the entry list: [`README.md`](./READM
8
8
 
9
9
  | Entry | Names used here |
10
10
  |---|---|
11
- | `@mgamadeus/ddd-admin-ui/logic` | `useUrlListState`, `useRowSelection`, `useEntityDrawer`, `drawerKey`, `defineStatusMap`, `formatDate`, `formatDateTime`, `runSequentialWithSummary`, `nextListSort`, `parseListSort`, `formatListSort` |
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
13
  | `@mgamadeus/ddd-admin-ui/page` | `EntityListPage`, `PageToolbar`, `ExportButton`, `AddEntityButton`, `EntityDetailShell`, `SectionHeader`, `DefinitionList`, `EditableCard`, `IconValue`, `IconValueRow`, `PageSections`, `CardGrid`, `PageFrame`, `PageHeader` |
14
- | `@mgamadeus/ddd-admin-ui/form` | `FormDrawer`, `FormActions`, `FormField`, `FormSection`, `useConfirmDialog` |
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
- | `@mgamadeus/ddd-admin-ui/primitives` | `Button`, `Card`, `CardContent`, `SegmentedControl` |
16
+ | `@mgamadeus/ddd-admin-ui/primitives` | `Button`, `Card`, `CardContent`, `SegmentedControl`, `FormActionsSlotProvider`, `FormActionsSlot` |
17
17
  | `@mgamadeus/ddd-admin-ui/next` | `useNextUrlStateAdapter`, `useNextDrawerUrlAdapter`, `useListViewParam` |
18
18
 
19
- Every screen renders below `AdminUiProvider`.
19
+ Every screen renders below `AdminUiProvider`. A screen that may not write sets that once with `WriteAccessProvider`
20
+ (§ 15).
20
21
 
21
22
  ## 1. List state — `useUrlListState`
22
23
 
@@ -78,18 +79,21 @@ below. Filters go **only** in the panel (never in `trailing`, never as an inline
78
79
 
79
80
  Order: outline secondaries → `ExportButton` → `MoreActionsMenu` (rare / maintenance) → **one** primary
80
81
  `AddEntityButton` ("Add <Entity>", singular, top right; `label` replaces the whole text when an entity name does not
81
- fit, already translated). Every write control `disabled={!writesAllowed}`.
82
+ fit, already translated). Write controls follow the screen's `WriteAccessProvider` (§ 15); a write the blocks cannot
83
+ know (a menu item, a row button) takes `disabled={!writeAccess.allowed}` from `useWriteAccess()`. Reading controls
84
+ (Export) stay enabled.
82
85
 
83
86
  ```tsx
87
+ const writeAccess = useWriteAccess(); // from the screen's WriteAccessProvider (§ 15)
88
+
84
89
  <EntityListPage
85
90
  title="Projects"
86
91
  headerActions={
87
92
  <PageToolbar
88
- exportAction={<ExportButton onExport={handleExport} disabled={!writesAllowed} />}
93
+ exportAction={<ExportButton onExport={handleExport} />}
89
94
  moreActions={[{ id: 'recalc', label: 'Recalculate totals', icon: <RefreshCw />, onSelect: handleRecalc,
90
- disabled: !writesAllowed }]}
91
- primaryAction={<AddEntityButton entity="Project" href="/projects/create" linkComponent={Link}
92
- disabled={!writesAllowed} />}
95
+ disabled: !writeAccess.allowed }]}
96
+ primaryAction={<AddEntityButton entity="Project" href="/projects/create" linkComponent={Link} />}
93
97
  >
94
98
  <Button variant="outline" onClick={openImport}>Import</Button>
95
99
  </PageToolbar>
@@ -98,7 +102,9 @@ fit, already translated). Every write control `disabled={!writesAllowed}`.
98
102
  >
99
103
  ```
100
104
 
101
- `ExportButton` label defaults to "Export to Excel"; a returned promise shows the spinner.
105
+ `ExportButton` label defaults to "Export to Excel"; a returned promise shows the spinner. `AddEntityButton` with `href`
106
+ is a link and stays enabled whatever the write access (the create screen guards itself); with `onClick` it is a button
107
+ and follows the write access.
102
108
 
103
109
  ## 4. Selection and bulk actions
104
110
 
@@ -108,10 +114,12 @@ const selection = useRowSelection({
108
114
  getKey: task => toNumericId(task.id), // a host helper
109
115
  resetKey: filterString ?? '', // new filters → empty selection
110
116
  disabled: busy,
117
+ isSelectable: canDelete, // optional: other rows get a disabled checkbox, "select all" skips them
111
118
  });
112
119
 
120
+ const confirm = useConfirm(); // the provider's dialog: nothing to render in the screen
113
121
  const handleBulkDelete = async () => {
114
- if (!writesAllowed || !(await confirm({ title: `Delete ${selection.count} task(s)?`, confirmVariant: 'destructive',
122
+ if (!writeAccess.allowed || !(await confirm({ title: `Delete ${selection.count} task(s)?`, confirmVariant: 'destructive',
115
123
  confirmLabel: 'Delete' }))) return;
116
124
  setBusy(true);
117
125
  await runSequentialWithSummary(selection.selectedKeys, id => deleteTask({ taskId: id }).unwrap(),
@@ -125,7 +133,6 @@ const bulkBar = (
125
133
  selection={selection}
126
134
  actions={[{ id: 'recreate', label: 'Recreate', icon: <RotateCcw />, onClick: handleBulkRecreate }]}
127
135
  onDelete={handleBulkDelete}
128
- disabled={!writesAllowed}
129
136
  busy={busy}
130
137
  />
131
138
  );
@@ -133,8 +140,9 @@ const bulkBar = (
133
140
  <EntityListBody … selection={selection} />
134
141
  ```
135
142
 
136
- Never a hand-made checkbox column, never `Promise.all` for bulk writes. A job that needs a result summary or a typed
137
- confirmation uses the host's dialogs.
143
+ The bar's actions and Delete follow the write access; an action that only reads (export, copy ids) passes
144
+ `ignoreWriteAccess`. Never a hand-made checkbox column, never `Promise.all` for bulk writes. A typed confirmation is
145
+ `confirm({ …, requirePhrase: entity.name })`; a job that needs a result summary uses the host's dialogs.
138
146
 
139
147
  ## 5. Columns and cells
140
148
 
@@ -158,7 +166,7 @@ const columns: EntityListColumn<Project>[] = [
158
166
  <div className="flex justify-end gap-1">
159
167
  <Button variant="ghost" size="icon-sm" aria-label={`Edit ${c.name}`} …><Pencil /></Button>
160
168
  <Button variant="ghost" size="icon-sm" aria-label={`Delete ${c.name}`} className="text-destructive"
161
- disabled={!writesAllowed} …><Trash2 /></Button>
169
+ disabled={!writeAccess.allowed} …><Trash2 /></Button>
162
170
  </div>
163
171
  ) },
164
172
  ];
@@ -168,7 +176,10 @@ const columns: EntityListColumn<Project>[] = [
168
176
  - Dates: `DateCell` in tables, `formatDateTime` / `formatDate` in text. Never raw strings, never
169
177
  `toLocaleString()`, never `new Date(value)`.
170
178
  - Numbers and ids: the host's formatters (one per kind), never ad-hoc `toFixed` calls.
171
- - Copy next to a value outside the ID column: a copy button on `useCopyToClipboard`.
179
+ - Copy next to a value outside the ID column: `CopyButton` (`value`, `label`, `reveal="hover"` in rows, `notify` for a
180
+ toast).
181
+ - A row that looks different (archived, muted): `rowClassName={(item, index) => …}` on the table or body.
182
+ - Small lists inside a card or section: `EntityListEmpty size="compact"` (one inline line, no 64 px block).
172
183
 
173
184
  ### Wide tables: tracks, pins, sort, row index
174
185
 
@@ -254,6 +265,13 @@ Always with an icon.
254
265
 
255
266
  Single searchable select (not a filter): `Combobox`.
256
267
 
268
+ - Long or server-side lists: `onSearch` + `isSearching` with `useLatestSearch` (the block debounces, never shows a stale
269
+ term's options, resets the search on close); a picked value outside the current results passes `selectedOption`.
270
+ - `clearable` for an optional value (a clear control; picking the picked option clears it); without it a pick is kept.
271
+ An option whose value is `''` and means something ("No parent") stays an ordinary option.
272
+ - Headings with `group`, a count or status after the label with `badge`, a "Create “…”" row with `onRequestCreate`.
273
+ - A date range in a toolbar row or table header: `FilterDateRange hideLabel` with `fromLabel` / `toLabel`.
274
+
257
275
  ## 8. Detail screens — `EntityDetailShell`
258
276
 
259
277
  Every entity detail uses the shell: back + centred title + description + actions, `EntityMetadata` (ID, Created,
@@ -302,6 +320,19 @@ Inside a tab:
302
320
  </CardContent></Card>
303
321
  ```
304
322
 
323
+ A summary card or side panel lists facts as divided rows, label left and value right: `layout="rows"`.
324
+
325
+ Every link a block renders (tabs, the back link, the Add button, breadcrumb links) goes through the host's link component, set once as
326
+ `AdminUiProvider.linkComponent` (a block's own `linkComponent` prop still wins). A host with sticky search parameters
327
+ wraps its router link with `withStickyParams(href, names, currentSearch)`.
328
+
329
+ Edit screens put the form's actions into the header with `formActionsSlot` on the shell: `FormActions` (default
330
+ `placement="auto"`) portals there as the pill, after `actions`, and floats under the top bar once the header scrolls
331
+ away (while the form is in view); the portalled Save stays linked to its form (`form` attribute), ⌘S still submits.
332
+ A nested shell with `formActionsSlot` takes the actions of its own forms. A form page with `FormHeader formActionsSlot`
333
+ (or a host header rendering `FormActionsSlot`) wraps header and form in one `FormActionsSlotProvider`; of several
334
+ slots the one closest above the form wins. `placement="row"` keeps the actions in the form.
335
+
305
336
  Create screens: no `metadata` id yet → the strip renders nothing. Edit screens outside a shell keep
306
337
  `<EntityMetadata id={…} changeHistory={…} />` right under their `FormHeader`.
307
338
 
@@ -334,21 +365,21 @@ The look lives in the blocks; a screen never re-draws it.
334
365
  (compact). Never a hand-made underline or pill bar.
335
366
  - **Two-tone titles**: wrap the brand part in `<em>` — `title={<>Item <em>Types</em></>}` (pass `label="Item Types"` to
336
367
  `EntityListPage` then). Only where a title earns it (Home, section headers), not on every list.
337
- - **Sticky glass bars**: page forms get them from `FormActions` (`sticky={false}` inside a dialog); the bulk bar from
338
- `EntityListBulkBar`.
368
+ - **Sticky glass bars**: page forms get them from `FormActions` (in a header slot when the page has one, § 8; inside a
369
+ dialog the plain row comes by itself); the bulk bar from `EntityListBulkBar`.
339
370
 
340
371
  ```tsx
341
372
  <PageSections>
342
373
  <section>
343
374
  <SectionHeader title={<>General <em>settings</em></>} />
344
375
  <CardGrid>
345
- <EditableCard title="Access" onEdit={openAccessForm} editLabel="Edit access" editDisabled={!writesAllowed}>
376
+ <EditableCard title="Access" onEdit={openAccessForm} editLabel="Edit access" editDisabled={!writeAccess.allowed}>
346
377
  <IconValueRow>
347
378
  <IconValue icon={<KeyRound />}>{workspace.accessCode ?? <EmptyValue />}</IconValue>
348
379
  <IconValue icon={<Calendar />}><DateCell value={workspace.startDate} format="date" /></IconValue>
349
380
  </IconValueRow>
350
381
  </EditableCard>
351
- <EditableCard title="Languages" onEdit={openLanguagesForm} editLabel="Edit languages" editDisabled={!writesAllowed}>
382
+ <EditableCard title="Languages" onEdit={openLanguagesForm} editLabel="Edit languages" editDisabled={!writeAccess.allowed}>
352
383
  <div className="flex flex-wrap gap-2">
353
384
  {locales.map(locale => <Tag key={locale} tone={locale === defaultLocale ? 'primary' : 'default'}>{locale}</Tag>)}
354
385
  </div>
@@ -402,7 +433,7 @@ button).
402
433
  // The list screen (inside <Suspense>): drawer state in the URL next to the filters — `?edit=<id>` / `?create=1`.
403
434
  const drawer = useEntityDrawer({ adapter: useNextDrawerUrlAdapter() }); // ./next, or the host's own adapter
404
435
 
405
- <AddEntityButton entity="Supplier" onClick={drawer.openCreate} disabled={!writesAllowed} />
436
+ <AddEntityButton entity="Supplier" onClick={drawer.openCreate} /> // a button: follows the write access
406
437
  rowAction={supplier => () => drawer.openEdit(id)}
407
438
  <Link href={supplierEditRoute(id)} onClick={drawer.editLinkClick(id)}>{supplier.name}</Link> // middle click = new tab
408
439
  <SupplierFormDrawer drawer={drawer} />
@@ -432,7 +463,10 @@ const entity = id ? (query.currentData?.supplier ?? null) : null; // currentDa
432
463
  (`supplierEditRoute`) live in a non-client file (a server page calls them).
433
464
  - A list hosting two drawers passes its own `editKey` / `createKey`.
434
465
  - **Confirm**: the drawer asks through the package dialog; a host with its own confirmation service passes
435
- `confirm={hostConfirm}` (stable function, same Radix copy). The same prop exists on the translatable fields.
466
+ `confirm={hostConfirm}` (stable function, same Radix copy). The same prop exists on the translatable fields. Screen
467
+ code asks with `useConfirm()` (§ 14).
468
+ `ConfirmOptions.description` may be a React node; the package's own confirmations always pass plain text, so a
469
+ service that renders text only can show them.
436
470
  - One column inside the drawer (≤ 760 px): no `md:grid-cols-2` form grids.
437
471
 
438
472
  ## 13. One value out of a few — `SegmentedControl`
@@ -456,4 +490,66 @@ const entity = id ? (query.currentData?.supplier ?? null) : null; // currentDa
456
490
  - Always exactly one value; 2–5 short options. More, or long labels: a select.
457
491
  - `activation="manual"` when a change is expensive (loads data): arrows move the focus, Space / Enter select.
458
492
  - `iconOnly` keeps the label as the accessible name and shows it as a tooltip (needs `AdminUiProvider`).
493
+ - In a row with form controls use `height={36}` (the height of a select trigger).
494
+ - On a phone the control keeps its size and scrolls inside itself (the selected and the focused option stay in view);
495
+ with more than three options or long labels prefer `fullWidth` with short labels, or a select.
496
+ - Labels are English UI texts, translated by the control (`context` for an ambiguous word, marked as literal
497
+ `m('Open', { context: 'filter' })`); already translated text (names from the server) passes `translate: false`.
459
498
  - A disabled option says why (`disabledReason`); a count goes in `badge` and, when it matters, in `description`.
499
+
500
+ ## 14. Short forms in a dialog, confirmations — `FormDialog`, `useConfirm`
501
+
502
+ A form of a few fields that belongs to the screen it is opened from (rename, move, a reason for a delete) is a
503
+ `FormDialog`; anything larger is a drawer (§ 12) or a page.
504
+
505
+ ```tsx
506
+ const form = useForm<RenameValues>({ defaultValues: { name: item.name } });
507
+ const rename = useRenameMutation();
508
+
509
+ <FormDialog<RenameValues>
510
+ open={open}
511
+ onOpenChange={setOpen}
512
+ title="Rename item"
513
+ form={form} // optional: FormField works inside; without it, plain state
514
+ onSubmit={async values => {
515
+ try { await rename.mutateAsync(values); setOpen(false); } catch (error) { notify.submitError(toFormSubmitError(error, 'Could not save')); }
516
+ }}
517
+ submitLabel="Save"
518
+ pendingLabel="Saving…"
519
+ isPending={rename.isPending}
520
+ isDirty={form.formState.isDirty} // a close request asks "Discard changes?"
521
+ >
522
+ <FormField<RenameValues, 'name'> name="name" label="Name" required>
523
+ {({ field, control }) => <Input {...control} {...field} />}
524
+ </FormField>
525
+ </FormDialog>
526
+ ```
527
+
528
+ - A real `<form>`: Enter in a text field and ⌘S submit it; a dialog opened from it is its own form.
529
+ - While pending (or while the promise `onSubmit` returns runs) Escape, the backdrop and Cancel do nothing. After a
530
+ failed save the handler shows the error and the dialog is usable again; the screen closes it after a success.
531
+ - `submitVariant="destructive"` for an irreversible submit, `submitDisabled` while nothing can be saved.
532
+
533
+ Confirmations ask through the provider: `const confirm = useConfirm()` (`./logic`) and
534
+ `if (!(await confirm({ title, description, confirmLabel, confirmVariant: 'destructive' }))) return;`. Nothing renders
535
+ in the screen; calls queue and each answers once; the focus returns to the control that asked. A deletion that must
536
+ not happen by accident names the entity: `requirePhrase: entity.name` (the confirm button stays off until it is typed,
537
+ `requirePhraseLabel` replaces the label). A host with its own confirmation service passes it as
538
+ `AdminUiProvider confirm`; `useConfirmDialog` stays for a block that renders its own dialog.
539
+
540
+ ## 15. Write access — `WriteAccessProvider`
541
+
542
+ ```tsx
543
+ <WriteAccessProvider value={{ allowed: canEdit, reason: canEdit ? undefined : 'This workspace is read-only' }}>
544
+ <ProjectScreen />
545
+ </WriteAccessProvider>
546
+ ```
547
+
548
+ A presentation aid, set once per screen (or per section; a nested provider can only narrow, never allow again):
549
+ `FormSubmitButton`, `FormDialog`'s submit, the actions and Delete of `EntityListBulkBar` and `AddEntityButton` as a
550
+ button are disabled while `allowed` is `false`, with `reason` as their title. A link never is (`AddEntityButton href`).
551
+ A control that only reads (a search submit, an export bulk action) passes `ignoreWriteAccess`. Other write controls
552
+ read `useWriteAccess()` (`disabled={!writeAccess.allowed}`).
553
+
554
+ It replaces no guard: every write handler keeps its own check (`if (!writeAccess.allowed) return;`), and the server
555
+ checks every request. Without a provider writes are allowed.
@@ -101,11 +101,11 @@
101
101
  }
102
102
  /* Sticky glass bars (bulk bar, form action bar). */
103
103
  /* Form actions at the top of the form: written last, shown first, sticky under the chrome. */
104
- form:has(> [data-form-actions]) {
104
+ form:has(> [data-form-actions='admin-ui']) {
105
105
  display: flex;
106
106
  flex-direction: column;
107
107
  }
108
- form > [data-form-actions] {
108
+ form > [data-form-actions='admin-ui'] {
109
109
  order: -1;
110
110
  }
111
111
  .glass-bar {
@@ -1,4 +1,4 @@
1
- import { type ReactNode } from 'react';
1
+ import { type ReactNode, type Ref } from 'react';
2
2
  export interface DrawerFooterProps {
3
3
  children: ReactNode;
4
4
  /** Classes for the content once it sits in the drawer's pinned footer. */
@@ -8,6 +8,14 @@ export interface DrawerFooterProps {
8
8
  /** Extra attributes for the inline wrapper (a `data-*` hook for layout CSS). */
9
9
  inlineProps?: Record<`data-${string}`, string>;
10
10
  }
11
+ export interface DrawerFooterViewProps extends DrawerFooterProps {
12
+ /** The hidden anchor where the footer is written (inside the form); kept across every placement. */
13
+ anchorRef?: Ref<HTMLSpanElement>;
14
+ /** Outside a drawer: portal the content into this element (a header slot) instead of rendering it inline. */
15
+ portalInto?: HTMLElement | null;
16
+ }
17
+ /** `DrawerFooter` with the anchor and a second portal target, for `FormActions`. */
18
+ export declare const DrawerFooterView: ({ children, className, inlineClassName, inlineProps, anchorRef: externalAnchorRef, portalInto, }: DrawerFooterViewProps) => import("react").JSX.Element;
11
19
  /**
12
20
  * Pins its content (a form's Save and Cancel) to the bottom of the `FormDrawer` it is rendered in; outside a drawer (a page, a dialog opened from the drawer) it renders where it is written.
13
21
  *
@@ -1 +1 @@
1
- {"version":3,"file":"DrawerFooter.d.ts","sourceRoot":"","sources":["../../src/form/DrawerFooter.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,SAAS,EAAwD,MAAM,OAAO,CAAC;AAK7F,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,SAAS,CAAC;IACpB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gGAAgG;IAChG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC,QAAQ,MAAM,EAAE,EAAE,MAAM,CAAC,CAAC;CAChD;AAOD;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,uDAAuD,iBAAiB,gCAoDpG,CAAC"}
1
+ {"version":3,"file":"DrawerFooter.d.ts","sourceRoot":"","sources":["../../src/form/DrawerFooter.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,GAAG,EAAqE,MAAM,OAAO,CAAC;AAMpH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,SAAS,CAAC;IACpB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gGAAgG;IAChG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gFAAgF;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC,QAAQ,MAAM,EAAE,EAAE,MAAM,CAAC,CAAC;CAChD;AAED,MAAM,WAAW,qBAAsB,SAAQ,iBAAiB;IAC9D,oGAAoG;IACpG,SAAS,CAAC,EAAE,GAAG,CAAC,eAAe,CAAC,CAAC;IACjC,6GAA6G;IAC7G,UAAU,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CACjC;AAOD,oFAAoF;AACpF,eAAO,MAAM,gBAAgB,GAAI,kGAO9B,qBAAqB,gCAmDvB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,uDAAuD,iBAAiB,gCAIpG,CAAC"}