@mgamadeus/ddd-admin-ui 0.1.0-rc.5 → 0.1.0
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.
- package/.claude/skills/ddd-admin-ui-specialist/SKILL.md +31 -4
- package/CHANGELOG.md +89 -1
- package/README.md +23 -14
- package/STANDARDS.md +95 -21
- package/dist/form/DrawerFooter.d.ts +9 -1
- package/dist/form/DrawerFooter.d.ts.map +1 -1
- package/dist/form/DrawerFooter.js +33 -32
- package/dist/form/DrawerFooter.js.map +1 -1
- package/dist/form/FormActions.d.ts +18 -13
- package/dist/form/FormActions.d.ts.map +1 -1
- package/dist/form/FormActions.js +104 -32
- package/dist/form/FormActions.js.map +1 -1
- package/dist/form/FormDialog.d.ts +52 -0
- package/dist/form/FormDialog.d.ts.map +1 -0
- package/dist/form/FormDialog.js +77 -0
- package/dist/form/FormDialog.js.map +1 -0
- package/dist/form/FormDrawer.d.ts +1 -0
- package/dist/form/FormDrawer.d.ts.map +1 -1
- package/dist/form/FormDrawer.js +3 -1
- package/dist/form/FormDrawer.js.map +1 -1
- package/dist/form/FormHeader.d.ts +6 -1
- package/dist/form/FormHeader.d.ts.map +1 -1
- package/dist/form/FormHeader.js +1 -1
- package/dist/form/FormHeader.js.map +1 -1
- package/dist/form/FormSubmitButton.d.ts +6 -1
- package/dist/form/FormSubmitButton.d.ts.map +1 -1
- package/dist/form/FormSubmitButton.js +5 -2
- package/dist/form/FormSubmitButton.js.map +1 -1
- package/dist/form/index.d.ts +2 -0
- package/dist/form/index.d.ts.map +1 -1
- package/dist/form/index.js +1 -0
- package/dist/form/index.js.map +1 -1
- package/dist/form/linkSubmitButtons.d.ts +7 -0
- package/dist/form/linkSubmitButtons.d.ts.map +1 -0
- package/dist/form/linkSubmitButtons.js +27 -0
- package/dist/form/linkSubmitButtons.js.map +1 -0
- package/dist/form/saveShortcut.d.ts +25 -0
- package/dist/form/saveShortcut.d.ts.map +1 -0
- package/dist/form/saveShortcut.js +59 -0
- package/dist/form/saveShortcut.js.map +1 -0
- package/dist/form/useConfirmDialog.d.ts +3 -2
- package/dist/form/useConfirmDialog.d.ts.map +1 -1
- package/dist/form/useConfirmDialog.js +21 -18
- package/dist/form/useConfirmDialog.js.map +1 -1
- package/dist/i18n/hints.json +2 -0
- package/dist/i18n-keys.json +20 -3
- package/dist/list/EntityListBulkBar.d.ts +7 -1
- package/dist/list/EntityListBulkBar.d.ts.map +1 -1
- package/dist/list/EntityListBulkBar.js +5 -1
- package/dist/list/EntityListBulkBar.js.map +1 -1
- package/dist/logic/index.d.ts +7 -0
- package/dist/logic/index.d.ts.map +1 -1
- package/dist/logic/index.js +4 -0
- package/dist/logic/index.js.map +1 -1
- package/dist/logic/pure/confirm.d.ts +13 -0
- package/dist/logic/pure/confirm.d.ts.map +1 -1
- package/dist/logic/pure/confirm.js +12 -0
- package/dist/logic/pure/confirm.js.map +1 -1
- package/dist/logic/pure/confirmQueue.d.ts +27 -0
- package/dist/logic/pure/confirmQueue.d.ts.map +1 -0
- package/dist/logic/pure/confirmQueue.js +52 -0
- package/dist/logic/pure/confirmQueue.js.map +1 -0
- package/dist/logic/pure/writeAccess.d.ts +18 -0
- package/dist/logic/pure/writeAccess.d.ts.map +1 -0
- package/dist/logic/pure/writeAccess.js +14 -0
- package/dist/logic/pure/writeAccess.js.map +1 -0
- package/dist/logic/react/useConfirm.d.ts +14 -0
- package/dist/logic/react/useConfirm.d.ts.map +1 -0
- package/dist/logic/react/useConfirm.js +16 -0
- package/dist/logic/react/useConfirm.js.map +1 -0
- package/dist/logic/react/writeAccess.d.ts +18 -0
- package/dist/logic/react/writeAccess.d.ts.map +1 -0
- package/dist/logic/react/writeAccess.js +18 -0
- package/dist/logic/react/writeAccess.js.map +1 -0
- package/dist/media/MediaItemPickerDialog.d.ts +1 -0
- package/dist/media/MediaItemPickerDialog.d.ts.map +1 -1
- package/dist/media/MediaItemPickerDialog.js +3 -1
- package/dist/media/MediaItemPickerDialog.js.map +1 -1
- package/dist/page/DetailHeader.d.ts +6 -1
- package/dist/page/DetailHeader.d.ts.map +1 -1
- package/dist/page/DetailHeader.js +3 -3
- package/dist/page/DetailHeader.js.map +1 -1
- package/dist/page/EntityDetailShell.d.ts +7 -1
- package/dist/page/EntityDetailShell.d.ts.map +1 -1
- package/dist/page/EntityDetailShell.js +4 -3
- package/dist/page/EntityDetailShell.js.map +1 -1
- package/dist/page/PageToolbar.d.ts +2 -1
- package/dist/page/PageToolbar.d.ts.map +1 -1
- package/dist/page/PageToolbar.js +6 -2
- package/dist/page/PageToolbar.js.map +1 -1
- package/dist/primitives/alert.d.ts +1 -1
- package/dist/primitives/badge.d.ts +1 -1
- package/dist/primitives/confirmDialogView.d.ts +30 -0
- package/dist/primitives/confirmDialogView.d.ts.map +1 -0
- package/dist/primitives/confirmDialogView.js +65 -0
- package/dist/primitives/confirmDialogView.js.map +1 -0
- package/dist/primitives/descriptionContent.d.ts +8 -0
- package/dist/primitives/descriptionContent.d.ts.map +1 -0
- package/dist/primitives/descriptionContent.js +7 -0
- package/dist/primitives/descriptionContent.js.map +1 -0
- package/dist/primitives/formActionsSlot.d.ts +24 -0
- package/dist/primitives/formActionsSlot.d.ts.map +1 -0
- package/dist/primitives/formActionsSlot.js +51 -0
- package/dist/primitives/formActionsSlot.js.map +1 -0
- package/dist/primitives/index.d.ts +2 -0
- package/dist/primitives/index.d.ts.map +1 -1
- package/dist/primitives/index.js +1 -0
- package/dist/primitives/index.js.map +1 -1
- package/dist/provider/AdminUiProvider.d.ts +4 -3
- package/dist/provider/AdminUiProvider.d.ts.map +1 -1
- package/dist/provider/AdminUiProvider.js +11 -5
- package/dist/provider/AdminUiProvider.js.map +1 -1
- package/dist/provider/ConfirmHost.d.ts +10 -0
- package/dist/provider/ConfirmHost.d.ts.map +1 -0
- package/dist/provider/ConfirmHost.js +19 -0
- package/dist/provider/ConfirmHost.js.map +1 -0
- package/dist/provider/types.d.ts +6 -0
- package/dist/provider/types.d.ts.map +1 -1
- package/dist/showcase/coverage.js +2 -2
- package/dist/showcase/coverage.js.map +1 -1
- package/dist/showcase/sections/FormShowcase.d.ts.map +1 -1
- package/dist/showcase/sections/FormShowcase.js +41 -5
- package/dist/showcase/sections/FormShowcase.js.map +1 -1
- 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
|
|
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 | `
|
|
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
|
|
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
|
@@ -1,7 +1,95 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
3
|
All notable changes to `@mgamadeus/ddd-admin-ui`. 0.x: each minor may break; pin the exact version while the package
|
|
4
|
-
is in 0.x
|
|
4
|
+
is in 0.x.
|
|
5
|
+
|
|
6
|
+
## 0.1.0
|
|
7
|
+
|
|
8
|
+
First stable release: 0.1.0-rc.6 plus the description fix below. Published under the `latest` dist-tag; prereleases
|
|
9
|
+
stay on `next`. In short, the release candidates brought (details in the sections below):
|
|
10
|
+
|
|
11
|
+
- the blocks and their entries `./logic`, `./i18n`, `./primitives`, `./list`, `./page`, `./form`, `./translations`,
|
|
12
|
+
`./media`, `./glass`, `./provider`, `./next`, `./notify-sonner`, the stylesheets `./theme.css` and
|
|
13
|
+
`./components.css`, the manifests `./tokens.json` and `./i18n-keys.json`, the bins and `STANDARDS.md` (rc.2);
|
|
14
|
+
- list tables with column tracks, pinned columns, sortable headers, a row index, and status contexts (rc.3);
|
|
15
|
+
- `SegmentedControl`, the `./showcase` entry and per-column sort cycles (rc.4);
|
|
16
|
+
- Combobox server search, clearing, groups and a create row, selectable rows, `CopyButton`, date input and storage
|
|
17
|
+
helpers, the provider's link component with sticky parameters (rc.5);
|
|
18
|
+
- `FormDialog`, the header slot and the document-level save shortcut of `FormActions`, `useConfirm` on the provider
|
|
19
|
+
with `requirePhrase` and a queue, and write access as a presentation aid (rc.6).
|
|
20
|
+
|
|
21
|
+
Fix:
|
|
22
|
+
|
|
23
|
+
- A description that is not a string or number (two paragraphs, a list, a `<div>`) renders in a `<div>` instead of the
|
|
24
|
+
`<p>` of `DialogDescription` / `SheetDescription`, with the same classes, `data-slot` and `aria-describedby` wiring:
|
|
25
|
+
no `<p>` nested in a `<p>`, no hydration warning. Covers `useConfirm` / `ConfirmOptions.description`,
|
|
26
|
+
`FormDialog.description`, `FormDrawer.description` and `MediaItemPickerDialog.description`. A string description
|
|
27
|
+
renders the same DOM as in 0.1.0-rc.6. Consumer checks in the browser: a block description in `useConfirm`,
|
|
28
|
+
`FormDialog` and `FormDrawer` (a `<div>` referenced by `aria-describedby`, no `<p>` in a `<p>`, no console error or
|
|
29
|
+
hydration warning), a string description still a `<p>`.
|
|
30
|
+
|
|
31
|
+
## 0.1.0-rc.6
|
|
32
|
+
|
|
33
|
+
All additions are optional props or new exports: a caller that uses none of them renders the same DOM as in
|
|
34
|
+
0.1.0-rc.5, proven by a server-render snapshot taken from 0.1.0-rc.5 (`form-actions-snapshot.html`: `FormActions`,
|
|
35
|
+
`FormSubmitButton`, `AddEntityButton`, `EntityListBulkBar`, `EntityDetailShell`, `FormHeader`, `DetailHeader`), next to
|
|
36
|
+
the list snapshot from 0.1.0-rc.2 (`pnpm test:render`; icons are reduced to their own classes, so the snapshot holds
|
|
37
|
+
at every lucide-react the peer range admits).
|
|
38
|
+
|
|
39
|
+
- `FormDialog` in `./form` (type `FormDialogProps`): a form in a dialog with or without a form library. Props `open`,
|
|
40
|
+
`onOpenChange`, `title`, `description`, `children`, `submitLabel`, `pendingLabel`, `cancelLabel`, `isPending`,
|
|
41
|
+
`isDirty` (a close request asks "Discard changes?"), `submitDisabled`, `submitVariant` (`default` / `destructive`),
|
|
42
|
+
`ignoreWriteAccess`, `className`, `onSubmit`, and an optional react-hook-form instance `form` (then `FormField` works
|
|
43
|
+
inside and `onSubmit` gets the parsed values; react-hook-form stays a peer). A real `<form>`: Enter in a text field
|
|
44
|
+
and ⌘S submit it; a dialog opened from it is its own form (its submit never reaches this one). Escape, the backdrop
|
|
45
|
+
and Cancel are ignored while pending or while the promise `onSubmit` returns runs; after a failed submit the dialog
|
|
46
|
+
is usable again. The focus returns to the element that had it when the dialog opened.
|
|
47
|
+
- `FormActions`:
|
|
48
|
+
- ⌘S / Ctrl+S listens on `document`. Inside a dialog or drawer (`[role="dialog"]`, `[role="alertdialog"]`) it answers
|
|
49
|
+
anywhere inside the innermost container holding the focus; elsewhere with focus in the form, on the actions (also
|
|
50
|
+
portalled) or nowhere (`body`). In scope it prevents the default, also while the primary is disabled (then nothing
|
|
51
|
+
submits); an event already `defaultPrevented` is left alone, so of two forms only one answers. It submits with
|
|
52
|
+
`form.requestSubmit(submitter)`, the actions' own submit button linked to the form first, else any submit button the
|
|
53
|
+
form owns. (Before: a listener on the form only; focus on `body` or on a portalled footer did nothing.)
|
|
54
|
+
- `placement: 'auto' | 'row' | 'header'` (`header` is new). `auto` moves the pill into the header slot closest above
|
|
55
|
+
the form when one is mounted, else it stays as before; `header` asks for the slot (without one: as `auto`); `row`
|
|
56
|
+
never moves. In a slot the actions are the same pill, floating under the top bar (`--nav-h`) once the header
|
|
57
|
+
scrolls away while the form is in view; the portalled submit button is linked back with the `form` attribute.
|
|
58
|
+
- Inside a dialog that is not a `FormDrawer` the actions render the plain row by themselves (as `sticky={false}`);
|
|
59
|
+
`sticky` without a value is now "pill on a page, row in a dialog", an explicit `sticky` keeps the pill there.
|
|
60
|
+
- Header slot in `./primitives`: `FormActionsSlotProvider`, `FormActionsSlot` (types `FormActionsSlotProviderProps`,
|
|
61
|
+
`FormActionsSlotProps`); `EntityDetailShell formActionsSlot` (brings its own provider; a nested shell takes the
|
|
62
|
+
actions of its own forms), `FormHeader formActionsSlot` and `DetailHeader formActionsSlot` (inside a provider around
|
|
63
|
+
header and form). Of several slots in one provider the one closest above the form wins.
|
|
64
|
+
- `useConfirm()` in `./logic` (with `ConfirmContext`): `confirm(options): Promise<boolean>` of the nearest
|
|
65
|
+
`AdminUiProvider`, which draws the dialog; nothing to render in the screen. Calls queue; each settles exactly once; an
|
|
66
|
+
unmounted provider settles its pending calls with `false`; Strict Mode safe; the focus returns to the element that
|
|
67
|
+
asked. Without a provider every call answers `false` with one warning outside production. `AdminUiProvider.confirm`
|
|
68
|
+
takes the host's own service (then `useConfirm()` calls it and the package dialog does not render).
|
|
69
|
+
`createConfirmQueue` (types `ConfirmQueue`, `ConfirmQueueEntry`) is the queue behind it. `useConfirmDialog` stays.
|
|
70
|
+
- `ConfirmOptions.requirePhrase` and `requirePhraseLabel`: the confirm button stays off until the phrase is typed
|
|
71
|
+
(trimmed, exact), in `useConfirm` and `useConfirmDialog` alike. `useConfirmDialog` now also returns the focus to the
|
|
72
|
+
element that had it when the dialog opened (before: Radix focused no trigger).
|
|
73
|
+
- Write access in `./logic`: `WriteAccessProvider value={{ allowed, reason? }}` (nestable, a subtree only narrows; no
|
|
74
|
+
provider = allowed), `useWriteAccess()`, `WriteAccessContext`, `narrowWriteAccess`, `WRITE_ACCESS_ALLOWED`, types
|
|
75
|
+
`WriteAccess`, `WriteAccessProviderProps`. Honoured by `FormSubmitButton`, `FormDialog`'s submit, the actions and
|
|
76
|
+
Delete of `EntityListBulkBar` (not Clear) and `AddEntityButton` as a button (never as a link); the reason is the
|
|
77
|
+
disabled control's title. `ignoreWriteAccess` on `FormSubmitButton`, `FormDialog` and `EntityListBulkAction` for a
|
|
78
|
+
control that only reads. A presentation aid: it replaces no handler guard and no server check.
|
|
79
|
+
- Showcase: samples of `FormDialog`, `useConfirm` (with a phrase), the header slot and write access;
|
|
80
|
+
`SHOWCASE_COVERAGE` lists `FormDialog`, `FormActionsSlotProvider`, `FormActionsSlot`.
|
|
81
|
+
- Text keys: new `Cancel__form-dialog`, `Type “%phrase%” to confirm`. `Cancel__confirm-dialog` and
|
|
82
|
+
`Confirm__confirm-dialog` are now used by `primitives/confirmDialogView.tsx` (the shared dialog).
|
|
83
|
+
- DOM of the new paths only: `data-form-actions-slot` on a slot, `data-form-actions-placement="header"` and
|
|
84
|
+
`data-form-actions-floating` on the pill in a slot, `data-confirm-phrase` around the phrase field.
|
|
85
|
+
- Docs: `STANDARDS.md` § 14 (form dialogs and confirmations) and § 15 (write access; the toolbar and bulk sections no
|
|
86
|
+
longer pass the write flag to every control), § 8 header slots; README provider props and confirmations; the skill.
|
|
87
|
+
- Consumer checks: the snapshot from 0.1.0-rc.5 and write access (server render); in the browser `FormDialog` (Enter,
|
|
88
|
+
pending, failed submit, a nested dialog, two forms on a page, focus return), the shortcut (focus on `body`, a drawer
|
|
89
|
+
footer button outside the form, focus in another form, a disabled primary, two nested dialogs), header slots (closest
|
|
90
|
+
slot, nested shells, `row`, the `form` attribute, the floating pill) and `useConfirm` (Escape, focus back to the
|
|
91
|
+
trigger, queue, phrase, inside a drawer, two providers, Strict Mode, unmount); unit tests for the confirm queue, the
|
|
92
|
+
missing-provider answer and the write access merge.
|
|
5
93
|
|
|
6
94
|
## 0.1.0-rc.5
|
|
7
95
|
|
package/README.md
CHANGED
|
@@ -12,7 +12,8 @@ package ships one unbundled JS file and one declaration file per source file.
|
|
|
12
12
|
## Install
|
|
13
13
|
|
|
14
14
|
```bash
|
|
15
|
-
pnpm add
|
|
15
|
+
pnpm add -E @mgamadeus/ddd-admin-ui
|
|
16
|
+
pnpm add @mgamadeus/ddd-web radix-ui react react-dom lucide-react react-hook-form zod
|
|
16
17
|
# optional, per entry: next (./next), sonner (./notify-sonner); the host's Tailwind 4 build compiles the CSS
|
|
17
18
|
```
|
|
18
19
|
|
|
@@ -20,16 +21,16 @@ pnpm add @mgamadeus/ddd-admin-ui @mgamadeus/ddd-web radix-ui react react-dom luc
|
|
|
20
21
|
|
|
21
22
|
| Entry | What it holds | May import (besides React and its peers) |
|
|
22
23
|
|---|---|---|
|
|
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` |
|
|
24
|
+
| `./logic` | pure helpers (`formatDate`, `defineStatusMap`, conditions, schemas, `notify`, `runSequential`), React hooks without markup (`useUrlListState`, `useEntityDrawer`, `useRowSelection`, `useEntityTranslations`, …), browser helpers (`prepareImageFile`, `readStored` / `writeStored`, `buildStorageKey`), date input values (`toDateInputValue`, `fromDateTimeInputValue`, …), `withStickyParams`, `useLatestSearch`, `useConfirm` (the provider's confirmation), `WriteAccessProvider` / `useWriteAccess` | `./i18n` |
|
|
24
25
|
| `./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` |
|
|
26
|
+
| `./primitives` | buttons, inputs, selects, dialogs, sheets, popovers, menus, tooltips, tables, badges, `SegmentedControl`, `cn`, the portal container, the header slot of form actions (`FormActionsSlotProvider`, `FormActionsSlot`) | `./i18n` |
|
|
26
27
|
| `./list` | entity list card, toolbar, search, filters, table, grid, load-more, status badge, cells, multi-select, combobox, bulk bar | logic, i18n, primitives |
|
|
27
28
|
| `./page` | page header and frame, `EntityListPage`, detail shell and header, tabs, section header, definition list, page toolbar, editable card, status callout, entity metadata | logic, i18n, primitives; from list only `EmptyValue`, `EntityListEmpty`, `EntityListCard` |
|
|
28
|
-
| `./form` | `Form`, `FormField`, `FormSection`, `FormActions`, `FormDrawer`, `FormHeader`, `FormWrapper`, `FormJumpBar`, `FormErrors`, `FormSubmitButton`, `useConfirmDialog` | logic, i18n, primitives; from page only `DetailHeader`, `EntityMetadata` |
|
|
29
|
+
| `./form` | `Form`, `FormField`, `FormSection`, `FormActions`, `FormDrawer`, `FormDialog`, `FormHeader`, `FormWrapper`, `FormJumpBar`, `FormErrors`, `FormSubmitButton`, `useConfirmDialog` | logic, i18n, primitives; from page only `DetailHeader`, `EntityMetadata` |
|
|
29
30
|
| `./translations` | `TranslatableInput`, `TranslatableMarkdown` (editor injected), their form-bound variants, `TranslationControls` | logic, i18n, primitives; from form only `fieldLabels`, `useConfirmDialog` |
|
|
30
31
|
| `./media` | `MediaItemField`, `FormMediaItemField`, `MediaItemPickerDialog`, `MediaPreview` | logic, i18n, primitives, list, form |
|
|
31
32
|
| `./glass` | `GlassPill`, `QuickFilterPills`, `CollapsibleCard`, `GlassGroup`, `ActionRow` | logic, i18n, primitives |
|
|
32
|
-
| `./provider` | `AdminUiProvider
|
|
33
|
+
| `./provider` | `AdminUiProvider` (also the dialog behind `useConfirm`), `useAdminUi`, `defaultStorageKey` | logic, i18n, primitives; types only from media and translations |
|
|
33
34
|
| `./next` | Next.js adapters: `useNextUrlStateAdapter`, `useNextDrawerUrlAdapter`, `useListViewParam`, the one URL writer (`queueSearchParamsWrite`) | logic, provider; the only entry importing `next/*` |
|
|
34
35
|
| `./notify-sonner` | `sonnerNotifications` (the notification adapter on `sonner`) and its `Toaster` | logic; the only entry importing `sonner` |
|
|
35
36
|
| `./showcase` | `Showcase`: a development page drawing every block in the host theme, light and dark, one section per entry, the host's sections appended; `SHOWCASE_COVERAGE` | logic, i18n, primitives, list, page, form, translations, media, glass; never `./next` or `./notify-sonner` |
|
|
@@ -156,8 +157,9 @@ It reads the host's `node_modules` (npm and pnpm layouts) and the folders above
|
|
|
156
157
|
default `document.body`), `tooltipDelayMs`, `translations` (a `TranslationAdapter` that feeds the text store from a
|
|
157
158
|
host store), `useUrlStateAdapter`, `useDrawerUrlAdapter`, `upload`, `renderMarkdownEditor`, `aiTranslation`,
|
|
158
159
|
`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)
|
|
160
|
-
notification adapter `notify.*` does nothing and
|
|
160
|
+
block that renders a link; wrap it with `withStickyParams` to keep sticky search parameters), `confirm` (the
|
|
161
|
+
host's confirmation service behind `useConfirm()`). Without a notification adapter `notify.*` does nothing and
|
|
162
|
+
warns once outside production.
|
|
161
163
|
|
|
162
164
|
```tsx
|
|
163
165
|
const StickyLink: PageLinkComponent = ({ href, ...props }) => {
|
|
@@ -167,7 +169,13 @@ It reads the host's `node_modules` (npm and pnpm layouts) and the folders above
|
|
|
167
169
|
<AdminUiProvider linkComponent={StickyLink} …>
|
|
168
170
|
```
|
|
169
171
|
|
|
170
|
-
4. **Confirmations.**
|
|
172
|
+
4. **Confirmations.** Screen code asks with `useConfirm()` (`./logic`): `confirm(options)` of the nearest
|
|
173
|
+
`AdminUiProvider`, which draws the package dialog (calls queue, each settles once, an unmounted provider answers its
|
|
174
|
+
pending calls `false`; `requirePhrase` keeps the confirm button off until a phrase is typed). Without a provider
|
|
175
|
+
every call answers `false` and warns once outside production. A host with its own service passes it as the
|
|
176
|
+
provider's `confirm`; `useConfirm()` then calls it and the package dialog does not render.
|
|
177
|
+
|
|
178
|
+
Blocks that ask before a step open the package's confirm dialog (`useConfirmDialog`). A host
|
|
171
179
|
with its own confirmation service passes it as `confirm` (`(options: ConfirmOptions) => Promise<boolean>`, a stable
|
|
172
180
|
function): `FormDrawer` ("Discard changes?") and `TranslatableInput` / `TranslatableMarkdown` and their form-bound
|
|
173
181
|
variants ("Clear all translations?"). The package dialog then does not render. The host's dialog must come from the
|
|
@@ -256,9 +264,9 @@ project's `.claude/skills/`. Idempotent; repoints an existing symlink, never tou
|
|
|
256
264
|
|
|
257
265
|
## Versioning
|
|
258
266
|
|
|
259
|
-
0.x: each minor may break. Pin the exact version while the package is in 0.x
|
|
260
|
-
|
|
261
|
-
[CHANGELOG.md](CHANGELOG.md).
|
|
267
|
+
0.x: each minor may break. Pin the exact version while the package is in 0.x (`"@mgamadeus/ddd-admin-ui": "0.1.0"`,
|
|
268
|
+
`pnpm add -E` / `npm install -E`); modules peer on the version they were tested with. Stable releases are published
|
|
269
|
+
under the `latest` dist-tag, pre-releases (`x.y.z-…`) under `next`. Changes per release: [CHANGELOG.md](CHANGELOG.md).
|
|
262
270
|
|
|
263
271
|
## Development
|
|
264
272
|
|
|
@@ -267,7 +275,7 @@ pnpm install
|
|
|
267
275
|
pnpm typecheck
|
|
268
276
|
pnpm test # unit tests beside the sources, script tests and a failing fixture per check-package rule
|
|
269
277
|
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
|
|
278
|
+
pnpm test:render # after the build: list snapshot (as in 0.1.0-rc.2), form actions snapshot (as in 0.1.0-rc.5), write access, status contexts, the showcase
|
|
271
279
|
node scripts/check-package.mjs --dir .
|
|
272
280
|
pnpm pack --pack-destination "$TMPDIR" && test/consumer/run.sh "$TMPDIR"/mgamadeus-ddd-admin-ui-*.tgz pnpm "$TMPDIR/consumer-pnpm"
|
|
273
281
|
```
|
|
@@ -277,7 +285,7 @@ pnpm pack --pack-destination "$TMPDIR" && test/consumer/run.sh "$TMPDIR"/mgamade
|
|
|
277
285
|
| `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
286
|
| `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
287
|
| `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 |
|
|
288
|
+
| `pnpm test:render` | server-renders list tables, bodies and badges from the build: without the optional table props the markup equals `test/consumer/fixtures/plain/list-snapshot.html` (taken from 0.1.0-rc.2); `FormActions`, `FormSubmitButton`, `AddEntityButton`, `EntityListBulkBar` and the headers without the props of 0.1.0-rc.6 equal `form-actions-snapshot.html` (taken from 0.1.0-rc.5); `WriteAccessProvider` disables the write controls; a status map's translation context reaches `StatusBadge`; the showcase renders (light, dark, every section) and its coverage list matches the exports |
|
|
281
289
|
| `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
290
|
| `node scripts/check-tokens.mjs <css> [tokens.json]` | the host check above (shipped as `ddd-admin-ui-check-tokens`) |
|
|
283
291
|
| `node scripts/check-radix.mjs [host folder]` | the Radix copy check above (shipped as `ddd-admin-ui-check-radix`) |
|
|
@@ -285,7 +293,8 @@ pnpm pack --pack-destination "$TMPDIR" && test/consumer/run.sh "$TMPDIR"/mgamade
|
|
|
285
293
|
Source files import each other with explicit `.ts` / `.tsx` extensions and never through a directory. The consumer
|
|
286
294
|
tests (`test/consumer/run.sh <tarball> <npm|pnpm> <workDir>`) install the packed tarball into a project without the
|
|
287
295
|
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
|
|
296
|
+
form labels across entries, nested overlays, form dialogs, the save shortcut, header slots and confirmations in
|
|
297
|
+
headless Chrome.
|
|
289
298
|
|
|
290
299
|
## License
|
|
291
300
|
|
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).
|
|
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}
|
|
93
|
+
exportAction={<ExportButton onExport={handleExport} />}
|
|
89
94
|
moreActions={[{ id: 'recalc', label: 'Recalculate totals', icon: <RefreshCw />, onSelect: handleRecalc,
|
|
90
|
-
disabled: !
|
|
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 (!
|
|
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
|
-
|
|
138
|
-
|
|
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={!
|
|
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` (
|
|
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={!
|
|
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={!
|
|
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}
|
|
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,9 +463,12 @@ 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.
|
|
470
|
+
A description (`ConfirmOptions`, `FormDialog`, `FormDrawer`, `MediaItemPickerDialog`) may be block content: a string or
|
|
471
|
+
number renders in the `<p>`, anything else in a `<div>` with the same classes and `aria-describedby` wiring.
|
|
455
472
|
- One column inside the drawer (≤ 760 px): no `md:grid-cols-2` form grids.
|
|
456
473
|
|
|
457
474
|
## 13. One value out of a few — `SegmentedControl`
|
|
@@ -481,3 +498,60 @@ const entity = id ? (query.currentData?.supplier ?? null) : null; // currentDa
|
|
|
481
498
|
- Labels are English UI texts, translated by the control (`context` for an ambiguous word, marked as literal
|
|
482
499
|
`m('Open', { context: 'filter' })`); already translated text (names from the server) passes `translate: false`.
|
|
483
500
|
- A disabled option says why (`disabledReason`); a count goes in `badge` and, when it matters, in `description`.
|
|
501
|
+
|
|
502
|
+
## 14. Short forms in a dialog, confirmations — `FormDialog`, `useConfirm`
|
|
503
|
+
|
|
504
|
+
A form of a few fields that belongs to the screen it is opened from (rename, move, a reason for a delete) is a
|
|
505
|
+
`FormDialog`; anything larger is a drawer (§ 12) or a page.
|
|
506
|
+
|
|
507
|
+
```tsx
|
|
508
|
+
const form = useForm<RenameValues>({ defaultValues: { name: item.name } });
|
|
509
|
+
const rename = useRenameMutation();
|
|
510
|
+
|
|
511
|
+
<FormDialog<RenameValues>
|
|
512
|
+
open={open}
|
|
513
|
+
onOpenChange={setOpen}
|
|
514
|
+
title="Rename item"
|
|
515
|
+
form={form} // optional: FormField works inside; without it, plain state
|
|
516
|
+
onSubmit={async values => {
|
|
517
|
+
try { await rename.mutateAsync(values); setOpen(false); } catch (error) { notify.submitError(toFormSubmitError(error, 'Could not save')); }
|
|
518
|
+
}}
|
|
519
|
+
submitLabel="Save"
|
|
520
|
+
pendingLabel="Saving…"
|
|
521
|
+
isPending={rename.isPending}
|
|
522
|
+
isDirty={form.formState.isDirty} // a close request asks "Discard changes?"
|
|
523
|
+
>
|
|
524
|
+
<FormField<RenameValues, 'name'> name="name" label="Name" required>
|
|
525
|
+
{({ field, control }) => <Input {...control} {...field} />}
|
|
526
|
+
</FormField>
|
|
527
|
+
</FormDialog>
|
|
528
|
+
```
|
|
529
|
+
|
|
530
|
+
- A real `<form>`: Enter in a text field and ⌘S submit it; a dialog opened from it is its own form.
|
|
531
|
+
- While pending (or while the promise `onSubmit` returns runs) Escape, the backdrop and Cancel do nothing. After a
|
|
532
|
+
failed save the handler shows the error and the dialog is usable again; the screen closes it after a success.
|
|
533
|
+
- `submitVariant="destructive"` for an irreversible submit, `submitDisabled` while nothing can be saved.
|
|
534
|
+
|
|
535
|
+
Confirmations ask through the provider: `const confirm = useConfirm()` (`./logic`) and
|
|
536
|
+
`if (!(await confirm({ title, description, confirmLabel, confirmVariant: 'destructive' }))) return;`. Nothing renders
|
|
537
|
+
in the screen; calls queue and each answers once; the focus returns to the control that asked. A deletion that must
|
|
538
|
+
not happen by accident names the entity: `requirePhrase: entity.name` (the confirm button stays off until it is typed,
|
|
539
|
+
`requirePhraseLabel` replaces the label). A host with its own confirmation service passes it as
|
|
540
|
+
`AdminUiProvider confirm`; `useConfirmDialog` stays for a block that renders its own dialog.
|
|
541
|
+
|
|
542
|
+
## 15. Write access — `WriteAccessProvider`
|
|
543
|
+
|
|
544
|
+
```tsx
|
|
545
|
+
<WriteAccessProvider value={{ allowed: canEdit, reason: canEdit ? undefined : 'This workspace is read-only' }}>
|
|
546
|
+
<ProjectScreen />
|
|
547
|
+
</WriteAccessProvider>
|
|
548
|
+
```
|
|
549
|
+
|
|
550
|
+
A presentation aid, set once per screen (or per section; a nested provider can only narrow, never allow again):
|
|
551
|
+
`FormSubmitButton`, `FormDialog`'s submit, the actions and Delete of `EntityListBulkBar` and `AddEntityButton` as a
|
|
552
|
+
button are disabled while `allowed` is `false`, with `reason` as their title. A link never is (`AddEntityButton href`).
|
|
553
|
+
A control that only reads (a search submit, an export bulk action) passes `ignoreWriteAccess`. Other write controls
|
|
554
|
+
read `useWriteAccess()` (`disabled={!writeAccess.allowed}`).
|
|
555
|
+
|
|
556
|
+
It replaces no guard: every write handler keeps its own check (`if (!writeAccess.allowed) return;`), and the server
|
|
557
|
+
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,
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
21
|
-
if (!slot || !anchor || !slot.bodyElement.contains(anchor)) {
|
|
23
|
+
if (!anchor) {
|
|
22
24
|
setTarget(null);
|
|
23
25
|
return;
|
|
24
26
|
}
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
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
|