@mgamadeus/ddd-admin-ui 0.1.0-rc.5 → 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 (112) hide show
  1. package/.claude/skills/ddd-admin-ui-specialist/SKILL.md +31 -4
  2. package/CHANGELOG.md +63 -0
  3. package/README.md +18 -10
  4. package/STANDARDS.md +93 -21
  5. package/dist/form/DrawerFooter.d.ts +9 -1
  6. package/dist/form/DrawerFooter.d.ts.map +1 -1
  7. package/dist/form/DrawerFooter.js +33 -32
  8. package/dist/form/DrawerFooter.js.map +1 -1
  9. package/dist/form/FormActions.d.ts +18 -13
  10. package/dist/form/FormActions.d.ts.map +1 -1
  11. package/dist/form/FormActions.js +104 -32
  12. package/dist/form/FormActions.js.map +1 -1
  13. package/dist/form/FormDialog.d.ts +51 -0
  14. package/dist/form/FormDialog.d.ts.map +1 -0
  15. package/dist/form/FormDialog.js +75 -0
  16. package/dist/form/FormDialog.js.map +1 -0
  17. package/dist/form/FormHeader.d.ts +6 -1
  18. package/dist/form/FormHeader.d.ts.map +1 -1
  19. package/dist/form/FormHeader.js +1 -1
  20. package/dist/form/FormHeader.js.map +1 -1
  21. package/dist/form/FormSubmitButton.d.ts +6 -1
  22. package/dist/form/FormSubmitButton.d.ts.map +1 -1
  23. package/dist/form/FormSubmitButton.js +5 -2
  24. package/dist/form/FormSubmitButton.js.map +1 -1
  25. package/dist/form/index.d.ts +2 -0
  26. package/dist/form/index.d.ts.map +1 -1
  27. package/dist/form/index.js +1 -0
  28. package/dist/form/index.js.map +1 -1
  29. package/dist/form/linkSubmitButtons.d.ts +7 -0
  30. package/dist/form/linkSubmitButtons.d.ts.map +1 -0
  31. package/dist/form/linkSubmitButtons.js +27 -0
  32. package/dist/form/linkSubmitButtons.js.map +1 -0
  33. package/dist/form/saveShortcut.d.ts +25 -0
  34. package/dist/form/saveShortcut.d.ts.map +1 -0
  35. package/dist/form/saveShortcut.js +59 -0
  36. package/dist/form/saveShortcut.js.map +1 -0
  37. package/dist/form/useConfirmDialog.d.ts +3 -2
  38. package/dist/form/useConfirmDialog.d.ts.map +1 -1
  39. package/dist/form/useConfirmDialog.js +21 -18
  40. package/dist/form/useConfirmDialog.js.map +1 -1
  41. package/dist/i18n/hints.json +2 -0
  42. package/dist/i18n-keys.json +20 -3
  43. package/dist/list/EntityListBulkBar.d.ts +7 -1
  44. package/dist/list/EntityListBulkBar.d.ts.map +1 -1
  45. package/dist/list/EntityListBulkBar.js +5 -1
  46. package/dist/list/EntityListBulkBar.js.map +1 -1
  47. package/dist/logic/index.d.ts +7 -0
  48. package/dist/logic/index.d.ts.map +1 -1
  49. package/dist/logic/index.js +4 -0
  50. package/dist/logic/index.js.map +1 -1
  51. package/dist/logic/pure/confirm.d.ts +12 -0
  52. package/dist/logic/pure/confirm.d.ts.map +1 -1
  53. package/dist/logic/pure/confirm.js +12 -0
  54. package/dist/logic/pure/confirm.js.map +1 -1
  55. package/dist/logic/pure/confirmQueue.d.ts +27 -0
  56. package/dist/logic/pure/confirmQueue.d.ts.map +1 -0
  57. package/dist/logic/pure/confirmQueue.js +52 -0
  58. package/dist/logic/pure/confirmQueue.js.map +1 -0
  59. package/dist/logic/pure/writeAccess.d.ts +18 -0
  60. package/dist/logic/pure/writeAccess.d.ts.map +1 -0
  61. package/dist/logic/pure/writeAccess.js +14 -0
  62. package/dist/logic/pure/writeAccess.js.map +1 -0
  63. package/dist/logic/react/useConfirm.d.ts +14 -0
  64. package/dist/logic/react/useConfirm.d.ts.map +1 -0
  65. package/dist/logic/react/useConfirm.js +16 -0
  66. package/dist/logic/react/useConfirm.js.map +1 -0
  67. package/dist/logic/react/writeAccess.d.ts +18 -0
  68. package/dist/logic/react/writeAccess.d.ts.map +1 -0
  69. package/dist/logic/react/writeAccess.js +18 -0
  70. package/dist/logic/react/writeAccess.js.map +1 -0
  71. package/dist/page/DetailHeader.d.ts +6 -1
  72. package/dist/page/DetailHeader.d.ts.map +1 -1
  73. package/dist/page/DetailHeader.js +3 -3
  74. package/dist/page/DetailHeader.js.map +1 -1
  75. package/dist/page/EntityDetailShell.d.ts +7 -1
  76. package/dist/page/EntityDetailShell.d.ts.map +1 -1
  77. package/dist/page/EntityDetailShell.js +4 -3
  78. package/dist/page/EntityDetailShell.js.map +1 -1
  79. package/dist/page/PageToolbar.d.ts +2 -1
  80. package/dist/page/PageToolbar.d.ts.map +1 -1
  81. package/dist/page/PageToolbar.js +6 -2
  82. package/dist/page/PageToolbar.js.map +1 -1
  83. package/dist/primitives/alert.d.ts +1 -1
  84. package/dist/primitives/badge.d.ts +1 -1
  85. package/dist/primitives/confirmDialogView.d.ts +29 -0
  86. package/dist/primitives/confirmDialogView.d.ts.map +1 -0
  87. package/dist/primitives/confirmDialogView.js +63 -0
  88. package/dist/primitives/confirmDialogView.js.map +1 -0
  89. package/dist/primitives/formActionsSlot.d.ts +24 -0
  90. package/dist/primitives/formActionsSlot.d.ts.map +1 -0
  91. package/dist/primitives/formActionsSlot.js +51 -0
  92. package/dist/primitives/formActionsSlot.js.map +1 -0
  93. package/dist/primitives/index.d.ts +2 -0
  94. package/dist/primitives/index.d.ts.map +1 -1
  95. package/dist/primitives/index.js +1 -0
  96. package/dist/primitives/index.js.map +1 -1
  97. package/dist/provider/AdminUiProvider.d.ts +4 -3
  98. package/dist/provider/AdminUiProvider.d.ts.map +1 -1
  99. package/dist/provider/AdminUiProvider.js +11 -5
  100. package/dist/provider/AdminUiProvider.js.map +1 -1
  101. package/dist/provider/ConfirmHost.d.ts +10 -0
  102. package/dist/provider/ConfirmHost.d.ts.map +1 -0
  103. package/dist/provider/ConfirmHost.js +19 -0
  104. package/dist/provider/ConfirmHost.js.map +1 -0
  105. package/dist/provider/types.d.ts +6 -0
  106. package/dist/provider/types.d.ts.map +1 -1
  107. package/dist/showcase/coverage.js +2 -2
  108. package/dist/showcase/coverage.js.map +1 -1
  109. package/dist/showcase/sections/FormShowcase.d.ts.map +1 -1
  110. package/dist/showcase/sections/FormShowcase.js +41 -5
  111. package/dist/showcase/sections/FormShowcase.js.map +1 -1
  112. 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
@@ -32,10 +32,14 @@ installed package (`node_modules/@mgamadeus/ddd-admin-ui/`). This skill reaches
32
32
  | a view that loads its own data (a tree) in the list card | `EntityListBody.renderOwnView` | list |
33
33
  | an entity detail with tabs | `EntityDetailShell` (+ `SectionHeader`, `DefinitionList`) | page |
34
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 |
35
37
  | drawer state in the URL (`?edit=<id>`, `?create=1`) | `useEntityDrawer` with `useNextDrawerUrlAdapter` | logic, next |
36
38
  | a text per content locale | `useEntityTranslations` + `FormTranslatableInput` / `FormTranslatableMarkdown` | logic, translations |
37
39
  | a media reference | `FormMediaItemField` (+ the host's `MediaItemPickerDialog`) | media |
38
- | 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 |
39
43
  | a toast | `notify.success / info / error / loading / submitError` | logic |
40
44
 
41
45
  ## Rules that fail silently
@@ -70,6 +74,18 @@ installed package (`node_modules/@mgamadeus/ddd-admin-ui/`). This skill reaches
70
74
  terms); the block debounces and never shows the previous term's options. A picked value outside the results needs
71
75
  `selectedOption`.
72
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.
73
89
  - **Showcase** needs no optional peer: pass `loadNotifySonner={() => import('@mgamadeus/ddd-admin-ui/notify-sonner')}`
74
90
  only when sonner is installed. A new block gets a showcase sample and a `SHOWCASE_COVERAGE` entry, or the checks fail.
75
91
  - **Text contexts are literals.** `m('Failed', { context: 'import-status' })`: extractors (the package manifest and
@@ -122,7 +138,7 @@ export const ItemsScreen = () => {
122
138
  ```tsx
123
139
  const drawer = useEntityDrawer({ adapter: useNextDrawerUrlAdapter() });
124
140
  const form = useForm<Values>({ defaultValues });
125
- const { confirm, dialog } = useConfirmDialog();
141
+ const confirm = useConfirm(); // ./logic: the provider's dialog
126
142
  const { confirmDiscard } = useUnsavedChangesGuard(useFormDirty(form), confirm);
127
143
 
128
144
  <FormDrawer open={drawer.isOpen} onClose={drawer.close} title="Edit item">
@@ -139,10 +155,21 @@ const { confirmDiscard } = useUnsavedChangesGuard(useFormDirty(form), confirm);
139
155
  primary={<FormSubmitButton>Save</FormSubmitButton>}
140
156
  />
141
157
  </Form>
142
- {dialog}
143
158
  </FormDrawer>
144
159
  ```
145
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
+
146
173
  ### Translations and media in one form
147
174
 
148
175
  ```tsx
package/CHANGELOG.md CHANGED
@@ -3,6 +3,69 @@
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
+
6
69
  ## 0.1.0-rc.5
7
70
 
8
71
  - `EntityListTable` / `EntityListBody`: `rowClassName(item, index)` for extra row classes.
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`, `readStored` / `writeStored`, `buildStorageKey`), date input values (`toDateInputValue`, `fromDateTimeInputValue`, …), `withStickyParams`, `useLatestSearch` | `./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` |
@@ -156,8 +156,9 @@ It reads the host's `node_modules` (npm and pnpm layouts) and the folders above
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
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). Without a
160
- notification adapter `notify.*` does nothing and warns once outside production.
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.
161
162
 
162
163
  ```tsx
163
164
  const StickyLink: PageLinkComponent = ({ href, ...props }) => {
@@ -167,7 +168,13 @@ It reads the host's `node_modules` (npm and pnpm layouts) and the folders above
167
168
  <AdminUiProvider linkComponent={StickyLink} …>
168
169
  ```
169
170
 
170
- 4. **Confirmations.** Blocks that ask before a step open the package's confirm dialog (`useConfirmDialog`). A host
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
171
178
  with its own confirmation service passes it as `confirm` (`(options: ConfirmOptions) => Promise<boolean>`, a stable
172
179
  function): `FormDrawer` ("Discard changes?") and `TranslatableInput` / `TranslatableMarkdown` and their form-bound
173
180
  variants ("Clear all translations?"). The package dialog then does not render. The host's dialog must come from the
@@ -267,7 +274,7 @@ pnpm install
267
274
  pnpm typecheck
268
275
  pnpm test # unit tests beside the sources, script tests and a failing fixture per check-package rule
269
276
  pnpm build # tsc → dist, declaration specifiers, stylesheets, manifests and shipped scripts
270
- 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
271
278
  node scripts/check-package.mjs --dir .
272
279
  pnpm pack --pack-destination "$TMPDIR" && test/consumer/run.sh "$TMPDIR"/mgamadeus-ddd-admin-ui-*.tgz pnpm "$TMPDIR/consumer-pnpm"
273
280
  ```
@@ -277,7 +284,7 @@ pnpm pack --pack-destination "$TMPDIR" && test/consumer/run.sh "$TMPDIR"/mgamade
277
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` |
278
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 |
279
286
  | `node scripts/tokens-utilities.mjs [--write]` | checks (or regenerates) the `utilities` lists of `tokens.json` from the source |
280
- | `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 |
281
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 |
282
289
  | `node scripts/check-tokens.mjs <css> [tokens.json]` | the host check above (shipped as `ddd-admin-ui-check-tokens`) |
283
290
  | `node scripts/check-radix.mjs [host folder]` | the Radix copy check above (shipped as `ddd-admin-ui-check-radix`) |
@@ -285,7 +292,8 @@ pnpm pack --pack-destination "$TMPDIR" && test/consumer/run.sh "$TMPDIR"/mgamade
285
292
  Source files import each other with explicit `.ts` / `.tsx` extensions and never through a directory. The consumer
286
293
  tests (`test/consumer/run.sh <tarball> <npm|pnpm> <workDir>`) install the packed tarball into a project without the
287
294
  optional peers and into a Next 16 app, and check imports, strict type checks, the production build and CSS, hydration,
288
- 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.
289
297
 
290
298
  ## License
291
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
 
@@ -111,8 +117,9 @@ const selection = useRowSelection({
111
117
  isSelectable: canDelete, // optional: other rows get a disabled checkbox, "select all" skips them
112
118
  });
113
119
 
120
+ const confirm = useConfirm(); // the provider's dialog: nothing to render in the screen
114
121
  const handleBulkDelete = async () => {
115
- 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',
116
123
  confirmLabel: 'Delete' }))) return;
117
124
  setBusy(true);
118
125
  await runSequentialWithSummary(selection.selectedKeys, id => deleteTask({ taskId: id }).unwrap(),
@@ -126,7 +133,6 @@ const bulkBar = (
126
133
  selection={selection}
127
134
  actions={[{ id: 'recreate', label: 'Recreate', icon: <RotateCcw />, onClick: handleBulkRecreate }]}
128
135
  onDelete={handleBulkDelete}
129
- disabled={!writesAllowed}
130
136
  busy={busy}
131
137
  />
132
138
  );
@@ -134,8 +140,9 @@ const bulkBar = (
134
140
  <EntityListBody … selection={selection} />
135
141
  ```
136
142
 
137
- Never a hand-made checkbox column, never `Promise.all` for bulk writes. A job that needs a result summary or a typed
138
- 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.
139
146
 
140
147
  ## 5. Columns and cells
141
148
 
@@ -159,7 +166,7 @@ const columns: EntityListColumn<Project>[] = [
159
166
  <div className="flex justify-end gap-1">
160
167
  <Button variant="ghost" size="icon-sm" aria-label={`Edit ${c.name}`} …><Pencil /></Button>
161
168
  <Button variant="ghost" size="icon-sm" aria-label={`Delete ${c.name}`} className="text-destructive"
162
- disabled={!writesAllowed} …><Trash2 /></Button>
169
+ disabled={!writeAccess.allowed} …><Trash2 /></Button>
163
170
  </div>
164
171
  ) },
165
172
  ];
@@ -319,6 +326,13 @@ Every link a block renders (tabs, the back link, the Add button, breadcrumb link
319
326
  `AdminUiProvider.linkComponent` (a block's own `linkComponent` prop still wins). A host with sticky search parameters
320
327
  wraps its router link with `withStickyParams(href, names, currentSearch)`.
321
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
+
322
336
  Create screens: no `metadata` id yet → the strip renders nothing. Edit screens outside a shell keep
323
337
  `<EntityMetadata id={…} changeHistory={…} />` right under their `FormHeader`.
324
338
 
@@ -351,21 +365,21 @@ The look lives in the blocks; a screen never re-draws it.
351
365
  (compact). Never a hand-made underline or pill bar.
352
366
  - **Two-tone titles**: wrap the brand part in `<em>` — `title={<>Item <em>Types</em></>}` (pass `label="Item Types"` to
353
367
  `EntityListPage` then). Only where a title earns it (Home, section headers), not on every list.
354
- - **Sticky glass bars**: page forms get them from `FormActions` (`sticky={false}` inside a dialog); the bulk bar from
355
- `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`.
356
370
 
357
371
  ```tsx
358
372
  <PageSections>
359
373
  <section>
360
374
  <SectionHeader title={<>General <em>settings</em></>} />
361
375
  <CardGrid>
362
- <EditableCard title="Access" onEdit={openAccessForm} editLabel="Edit access" editDisabled={!writesAllowed}>
376
+ <EditableCard title="Access" onEdit={openAccessForm} editLabel="Edit access" editDisabled={!writeAccess.allowed}>
363
377
  <IconValueRow>
364
378
  <IconValue icon={<KeyRound />}>{workspace.accessCode ?? <EmptyValue />}</IconValue>
365
379
  <IconValue icon={<Calendar />}><DateCell value={workspace.startDate} format="date" /></IconValue>
366
380
  </IconValueRow>
367
381
  </EditableCard>
368
- <EditableCard title="Languages" onEdit={openLanguagesForm} editLabel="Edit languages" editDisabled={!writesAllowed}>
382
+ <EditableCard title="Languages" onEdit={openLanguagesForm} editLabel="Edit languages" editDisabled={!writeAccess.allowed}>
369
383
  <div className="flex flex-wrap gap-2">
370
384
  {locales.map(locale => <Tag key={locale} tone={locale === defaultLocale ? 'primary' : 'default'}>{locale}</Tag>)}
371
385
  </div>
@@ -419,7 +433,7 @@ button).
419
433
  // The list screen (inside <Suspense>): drawer state in the URL next to the filters — `?edit=<id>` / `?create=1`.
420
434
  const drawer = useEntityDrawer({ adapter: useNextDrawerUrlAdapter() }); // ./next, or the host's own adapter
421
435
 
422
- <AddEntityButton entity="Supplier" onClick={drawer.openCreate} disabled={!writesAllowed} />
436
+ <AddEntityButton entity="Supplier" onClick={drawer.openCreate} /> // a button: follows the write access
423
437
  rowAction={supplier => () => drawer.openEdit(id)}
424
438
  <Link href={supplierEditRoute(id)} onClick={drawer.editLinkClick(id)}>{supplier.name}</Link> // middle click = new tab
425
439
  <SupplierFormDrawer drawer={drawer} />
@@ -449,7 +463,8 @@ const entity = id ? (query.currentData?.supplier ?? null) : null; // currentDa
449
463
  (`supplierEditRoute`) live in a non-client file (a server page calls them).
450
464
  - A list hosting two drawers passes its own `editKey` / `createKey`.
451
465
  - **Confirm**: the drawer asks through the package dialog; a host with its own confirmation service passes
452
- `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).
453
468
  `ConfirmOptions.description` may be a React node; the package's own confirmations always pass plain text, so a
454
469
  service that renders text only can show them.
455
470
  - One column inside the drawer (≤ 760 px): no `md:grid-cols-2` form grids.
@@ -481,3 +496,60 @@ const entity = id ? (query.currentData?.supplier ?? null) : null; // currentDa
481
496
  - Labels are English UI texts, translated by the control (`context` for an ambiguous word, marked as literal
482
497
  `m('Open', { context: 'filter' })`); already translated text (names from the server) passes `translate: false`.
483
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.
@@ -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"}
@@ -1,47 +1,48 @@
1
1
  'use client';
2
2
  import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
3
- import { useContext, useId, useLayoutEffect, useRef, useState } from 'react';
3
+ import { useCallback, useContext, useId, useLayoutEffect, useRef, useState } from 'react';
4
4
  import { createPortal } from 'react-dom';
5
5
  import { DrawerFooterSlotContext } from "./drawerSlots.js";
6
- /**
7
- * 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.
8
- *
9
- * The portalled footer sits outside the `<form>` in the DOM, so every submit button in it is linked back to its form
10
- * with the `form` attribute: Save, and Enter in a field, still submit the form.
11
- */
12
- export const DrawerFooter = ({ children, className, inlineClassName, inlineProps }) => {
6
+ import { useLinkedSubmitButtons } from "./linkSubmitButtons.js";
7
+ /** `DrawerFooter` with the anchor and a second portal target, for `FormActions`. */
8
+ export const DrawerFooterView = ({ children, className, inlineClassName, inlineProps, anchorRef: externalAnchorRef, portalInto, }) => {
13
9
  const slot = useContext(DrawerFooterSlotContext);
14
10
  const fallbackFormId = useId();
15
11
  const anchorRef = useRef(null);
16
- const contentRef = useRef(null);
12
+ const [content, setContent] = useState(null);
17
13
  const [target, setTarget] = useState(null);
14
+ const setAnchor = useCallback((element) => {
15
+ anchorRef.current = element;
16
+ if (typeof externalAnchorRef === 'function')
17
+ externalAnchorRef(element);
18
+ else if (externalAnchorRef)
19
+ externalAnchorRef.current = element;
20
+ }, [externalAnchorRef]);
18
21
  useLayoutEffect(() => {
19
22
  const anchor = anchorRef.current;
20
- // A dialog opened from inside the drawer still sees the drawer's context, but its DOM is portalled to <body>.
21
- if (!slot || !anchor || !slot.bodyElement.contains(anchor)) {
23
+ if (!anchor) {
22
24
  setTarget(null);
23
25
  return;
24
26
  }
25
- setTarget({ footerElement: slot.footerElement, formElement: anchor.closest('form') });
26
- }, [slot]);
27
- const formElement = target?.formElement ?? null;
28
- useLayoutEffect(() => {
29
- const content = contentRef.current;
30
- if (!formElement || !content)
31
- return;
32
- if (!formElement.id)
33
- formElement.id = fallbackFormId;
34
- const linkSubmitButtons = () => {
35
- for (const button of content.querySelectorAll('button')) {
36
- if (button.type === 'submit' && !button.hasAttribute('form'))
37
- button.setAttribute('form', formElement.id);
38
- }
39
- };
40
- linkSubmitButtons();
41
- const observer = new MutationObserver(linkSubmitButtons);
42
- observer.observe(content, { childList: true, subtree: true });
43
- return () => observer.disconnect();
44
- }, [formElement, fallbackFormId]);
45
- return (_jsxs(_Fragment, { children: [_jsx("span", { ref: anchorRef, hidden: true }), target ? (createPortal(_jsx("div", { ref: contentRef, className: className, children: children }), target.footerElement)) : (_jsx("div", { className: inlineClassName, ...inlineProps, children: children }))] }));
27
+ // A dialog opened from inside the drawer still sees the drawer's context, but its DOM is portalled to <body>.
28
+ if (slot && slot.bodyElement.contains(anchor)) {
29
+ setTarget({ footerElement: slot.footerElement, formElement: anchor.closest('form') });
30
+ }
31
+ else if (portalInto) {
32
+ setTarget({ footerElement: portalInto, formElement: anchor.closest('form') });
33
+ }
34
+ else {
35
+ setTarget(null);
36
+ }
37
+ }, [slot, portalInto]);
38
+ useLinkedSubmitButtons(content, target?.formElement ?? null, fallbackFormId);
39
+ return (_jsxs(_Fragment, { children: [_jsx("span", { ref: setAnchor, hidden: true }), target ? (createPortal(_jsx("div", { ref: setContent, className: className, children: children }), target.footerElement)) : (_jsx("div", { className: inlineClassName, ...inlineProps, children: children }))] }));
46
40
  };
41
+ /**
42
+ * 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.
43
+ *
44
+ * The portalled footer sits outside the `<form>` in the DOM, so every submit button in it is linked back to its form
45
+ * with the `form` attribute: Save, and Enter in a field, still submit the form.
46
+ */
47
+ export const DrawerFooter = ({ children, className, inlineClassName, inlineProps }) => (_jsx(DrawerFooterView, { className: className, inlineClassName: inlineClassName, inlineProps: inlineProps, children: children }));
47
48
  //# sourceMappingURL=DrawerFooter.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"DrawerFooter.js","sourceRoot":"","sources":["../../src/form/DrawerFooter.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,EAAkB,UAAU,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAC7F,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAiB3D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAqB,EAAE,EAAE;IACvG,MAAM,IAAI,GAAG,UAAU,CAAC,uBAAuB,CAAC,CAAC;IACjD,MAAM,cAAc,GAAG,KAAK,EAAE,CAAC;IAC/B,MAAM,SAAS,GAAG,MAAM,CAAkB,IAAI,CAAC,CAAC;IAChD,MAAM,UAAU,GAAG,MAAM,CAAiB,IAAI,CAAC,CAAC;IAChD,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAsB,IAAI,CAAC,CAAC;IAEhE,eAAe,CAAC,GAAG,EAAE;QACnB,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC;QACjC,8GAA8G;QAC9G,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3D,SAAS,CAAC,IAAI,CAAC,CAAC;YAChB,OAAO;QACT,CAAC;QACD,SAAS,CAAC,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACxF,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;IAEX,MAAM,WAAW,GAAG,MAAM,EAAE,WAAW,IAAI,IAAI,CAAC;IAEhD,eAAe,CAAC,GAAG,EAAE;QACnB,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC;QACnC,IAAI,CAAC,WAAW,IAAI,CAAC,OAAO;YAAE,OAAO;QACrC,IAAI,CAAC,WAAW,CAAC,EAAE;YAAE,WAAW,CAAC,EAAE,GAAG,cAAc,CAAC;QAErD,MAAM,iBAAiB,GAAG,GAAG,EAAE;YAC7B,KAAK,MAAM,MAAM,IAAI,OAAO,CAAC,gBAAgB,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACxD,IAAI,MAAM,CAAC,IAAI,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC;oBAAE,MAAM,CAAC,YAAY,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,CAAC,CAAC;YAC5G,CAAC;QACH,CAAC,CAAC;QACF,iBAAiB,EAAE,CAAC;QACpB,MAAM,QAAQ,GAAG,IAAI,gBAAgB,CAAC,iBAAiB,CAAC,CAAC;QACzD,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9D,OAAO,GAAG,EAAE,CAAC,QAAQ,CAAC,UAAU,EAAE,CAAC;IACrC,CAAC,EAAE,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC,CAAC;IAElC,OAAO,CACL,8BACE,eAAM,GAAG,EAAE,SAAS,EAAE,MAAM,SAAG,EAC9B,MAAM,CAAC,CAAC,CAAC,CACR,YAAY,CACV,cAAK,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,YACvC,QAAQ,GACL,EACN,MAAM,CAAC,aAAa,CACrB,CACF,CAAC,CAAC,CAAC,CACF,cAAK,SAAS,EAAE,eAAe,KAAM,WAAW,YAC7C,QAAQ,GACL,CACP,IACA,CACJ,CAAC;AACJ,CAAC,CAAC"}
1
+ {"version":3,"file":"DrawerFooter.js","sourceRoot":"","sources":["../../src/form/DrawerFooter.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AAEb,OAAO,EAA4B,WAAW,EAAE,UAAU,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AACpH,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,sBAAsB,EAAE,MAAM,wBAAwB,CAAC;AAwBhE,oFAAoF;AACpF,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,EAC/B,QAAQ,EACR,SAAS,EACT,eAAe,EACf,WAAW,EACX,SAAS,EAAE,iBAAiB,EAC5B,UAAU,GACY,EAAE,EAAE;IAC1B,MAAM,IAAI,GAAG,UAAU,CAAC,uBAAuB,CAAC,CAAC;IACjD,MAAM,cAAc,GAAG,KAAK,EAAE,CAAC;IAC/B,MAAM,SAAS,GAAG,MAAM,CAAyB,IAAI,CAAC,CAAC;IACvD,MAAM,CAAC,OAAO,EAAE,UAAU,CAAC,GAAG,QAAQ,CAAwB,IAAI,CAAC,CAAC;IACpE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAsB,IAAI,CAAC,CAAC;IAEhE,MAAM,SAAS,GAAG,WAAW,CAC3B,CAAC,OAA+B,EAAE,EAAE;QAClC,SAAS,CAAC,OAAO,GAAG,OAAO,CAAC;QAC5B,IAAI,OAAO,iBAAiB,KAAK,UAAU;YAAE,iBAAiB,CAAC,OAAO,CAAC,CAAC;aACnE,IAAI,iBAAiB;YAAE,iBAAiB,CAAC,OAAO,GAAG,OAAO,CAAC;IAClE,CAAC,EACD,CAAC,iBAAiB,CAAC,CACpB,CAAC;IAEF,eAAe,CAAC,GAAG,EAAE;QACnB,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC;QACjC,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,SAAS,CAAC,IAAI,CAAC,CAAC;YAChB,OAAO;QACT,CAAC;QACD,8GAA8G;QAC9G,IAAI,IAAI,IAAI,IAAI,CAAC,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC9C,SAAS,CAAC,EAAE,aAAa,EAAE,IAAI,CAAC,aAAa,EAAE,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QACxF,CAAC;aAAM,IAAI,UAAU,EAAE,CAAC;YACtB,SAAS,CAAC,EAAE,aAAa,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAChF,CAAC;aAAM,CAAC;YACN,SAAS,CAAC,IAAI,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;IAEvB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,IAAI,IAAI,EAAE,cAAc,CAAC,CAAC;IAE7E,OAAO,CACL,8BACE,eAAM,GAAG,EAAE,SAAS,EAAE,MAAM,SAAG,EAC9B,MAAM,CAAC,CAAC,CAAC,CACR,YAAY,CACV,cAAK,GAAG,EAAE,UAAU,EAAE,SAAS,EAAE,SAAS,YACvC,QAAQ,GACL,EACN,MAAM,CAAC,aAAa,CACrB,CACF,CAAC,CAAC,CAAC,CACF,cAAK,SAAS,EAAE,eAAe,KAAM,WAAW,YAC7C,QAAQ,GACL,CACP,IACA,CACJ,CAAC;AACJ,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,eAAe,EAAE,WAAW,EAAqB,EAAE,EAAE,CAAC,CACxG,KAAC,gBAAgB,IAAC,SAAS,EAAE,SAAS,EAAE,eAAe,EAAE,eAAe,EAAE,WAAW,EAAE,WAAW,YAC/F,QAAQ,GACQ,CACpB,CAAC"}