@mgamadeus/ddd-admin-ui 0.1.0-rc.2 → 0.1.0-rc.4
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 +20 -2
- package/CHANGELOG.md +67 -1
- package/README.md +42 -6
- package/STANDARDS.md +132 -58
- package/dist/components.css +63 -3
- package/dist/i18n/hints.json +2 -1
- package/dist/i18n/index.d.ts +1 -1
- package/dist/i18n/index.d.ts.map +1 -1
- package/dist/i18n/index.js.map +1 -1
- package/dist/i18n/store.d.ts +10 -2
- package/dist/i18n/store.d.ts.map +1 -1
- package/dist/i18n/store.js +6 -2
- package/dist/i18n/store.js.map +1 -1
- package/dist/i18n-keys.json +9 -1
- package/dist/list/EntityListBody.d.ts +10 -3
- package/dist/list/EntityListBody.d.ts.map +1 -1
- package/dist/list/EntityListBody.js +9 -3
- package/dist/list/EntityListBody.js.map +1 -1
- package/dist/list/EntityListTable.d.ts +42 -2
- package/dist/list/EntityListTable.d.ts.map +1 -1
- package/dist/list/EntityListTable.js +158 -6
- package/dist/list/EntityListTable.js.map +1 -1
- package/dist/list/StatusBadge.d.ts +1 -1
- package/dist/list/StatusBadge.d.ts.map +1 -1
- package/dist/list/StatusBadge.js +3 -2
- package/dist/list/StatusBadge.js.map +1 -1
- package/dist/logic/index.d.ts +5 -1
- package/dist/logic/index.d.ts.map +1 -1
- package/dist/logic/index.js +2 -0
- package/dist/logic/index.js.map +1 -1
- package/dist/logic/pure/listSort.d.ts +29 -0
- package/dist/logic/pure/listSort.d.ts.map +1 -0
- package/dist/logic/pure/listSort.js +35 -0
- package/dist/logic/pure/listSort.js.map +1 -0
- package/dist/logic/pure/listTracks.d.ts +90 -0
- package/dist/logic/pure/listTracks.d.ts.map +1 -0
- package/dist/logic/pure/listTracks.js +139 -0
- package/dist/logic/pure/listTracks.js.map +1 -0
- package/dist/logic/pure/status.d.ts +23 -2
- package/dist/logic/pure/status.d.ts.map +1 -1
- package/dist/logic/pure/status.js +23 -2
- package/dist/logic/pure/status.js.map +1 -1
- package/dist/primitives/index.d.ts +1 -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/primitives/segmented-control.d.ts +57 -0
- package/dist/primitives/segmented-control.d.ts.map +1 -0
- package/dist/primitives/segmented-control.js +206 -0
- package/dist/primitives/segmented-control.js.map +1 -0
- package/dist/primitives/segmentedControlNavigation.d.ts +31 -0
- package/dist/primitives/segmentedControlNavigation.d.ts.map +1 -0
- package/dist/primitives/segmentedControlNavigation.js +65 -0
- package/dist/primitives/segmentedControlNavigation.js.map +1 -0
- package/dist/scripts/build-i18n-manifest.mjs +9 -3
- package/dist/showcase/Showcase.d.ts +35 -0
- package/dist/showcase/Showcase.d.ts.map +1 -0
- package/dist/showcase/Showcase.js +47 -0
- package/dist/showcase/Showcase.js.map +1 -0
- package/dist/showcase/coverage.d.ts +11 -0
- package/dist/showcase/coverage.d.ts.map +1 -0
- package/dist/showcase/coverage.js +77 -0
- package/dist/showcase/coverage.js.map +1 -0
- package/dist/showcase/index.d.ts +6 -0
- package/dist/showcase/index.d.ts.map +1 -0
- package/dist/showcase/index.js +5 -0
- package/dist/showcase/index.js.map +1 -0
- package/dist/showcase/sections/FormShowcase.d.ts +3 -0
- package/dist/showcase/sections/FormShowcase.d.ts.map +1 -0
- package/dist/showcase/sections/FormShowcase.js +26 -0
- package/dist/showcase/sections/FormShowcase.js.map +1 -0
- package/dist/showcase/sections/GlassShowcase.d.ts +3 -0
- package/dist/showcase/sections/GlassShowcase.d.ts.map +1 -0
- package/dist/showcase/sections/GlassShowcase.js +19 -0
- package/dist/showcase/sections/GlassShowcase.js.map +1 -0
- package/dist/showcase/sections/ListShowcase.d.ts +13 -0
- package/dist/showcase/sections/ListShowcase.d.ts.map +1 -0
- package/dist/showcase/sections/ListShowcase.js +67 -0
- package/dist/showcase/sections/ListShowcase.js.map +1 -0
- package/dist/showcase/sections/MediaShowcase.d.ts +3 -0
- package/dist/showcase/sections/MediaShowcase.d.ts.map +1 -0
- package/dist/showcase/sections/MediaShowcase.js +28 -0
- package/dist/showcase/sections/MediaShowcase.js.map +1 -0
- package/dist/showcase/sections/OptionalShowcase.d.ts +14 -0
- package/dist/showcase/sections/OptionalShowcase.d.ts.map +1 -0
- package/dist/showcase/sections/OptionalShowcase.js +32 -0
- package/dist/showcase/sections/OptionalShowcase.js.map +1 -0
- package/dist/showcase/sections/PageShowcase.d.ts +3 -0
- package/dist/showcase/sections/PageShowcase.d.ts.map +1 -0
- package/dist/showcase/sections/PageShowcase.js +37 -0
- package/dist/showcase/sections/PageShowcase.js.map +1 -0
- package/dist/showcase/sections/PrimitivesShowcase.d.ts +13 -0
- package/dist/showcase/sections/PrimitivesShowcase.d.ts.map +1 -0
- package/dist/showcase/sections/PrimitivesShowcase.js +40 -0
- package/dist/showcase/sections/PrimitivesShowcase.js.map +1 -0
- package/dist/showcase/sections/TranslationsShowcase.d.ts +3 -0
- package/dist/showcase/sections/TranslationsShowcase.d.ts.map +1 -0
- package/dist/showcase/sections/TranslationsShowcase.js +30 -0
- package/dist/showcase/sections/TranslationsShowcase.js.map +1 -0
- package/dist/tokens.json +37 -1
- package/package.json +7 -6
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: ddd-admin-ui-specialist
|
|
3
|
-
description: "Build admin screens with @mgamadeus/ddd-admin-ui
|
|
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."
|
|
4
4
|
metadata:
|
|
5
5
|
author: mgamadeus
|
|
6
6
|
version: 0.1.0
|
|
@@ -20,7 +20,12 @@ installed package (`node_modules/@mgamadeus/ddd-admin-ui/`). This skill reaches
|
|
|
20
20
|
| search and filters in the URL | `useUrlListState` with `useNextUrlStateAdapter` | logic, next |
|
|
21
21
|
| grid / table switch remembered per list | `useListViewParam` + `EntityListViewToggle` | next, list |
|
|
22
22
|
| checkbox column and bulk actions | `useRowSelection` + `EntityListBulkBar` + `runSequentialWithSummary` | logic, list |
|
|
23
|
-
| status pill of an enum | `defineStatusMap` + `StatusBadge` | logic, list |
|
|
23
|
+
| status pill of an enum | `defineStatusMap` + `StatusBadge` (a `context` for an ambiguous word) | logic, list |
|
|
24
|
+
| a wide table: column tracks, pinned columns, sortable headers, row numbers | `EntityListColumn` `width` / `minWidth` / `pin` / `align` / `sortKey` + `sort` / `onSortChange` / `showRowIndex` | list |
|
|
25
|
+
| the sort in the URL | `formatListSort` / `parseListSort` / `nextListSort` (`key:asc`; `sortStart`, `sortRequired`) | logic |
|
|
26
|
+
| one value out of a few (period, scope, view) | `SegmentedControl` (not tabs, not toggle chips) | primitives |
|
|
27
|
+
| see every block in the host theme, light and dark | `Showcase` on a development route | showcase |
|
|
28
|
+
| a view that loads its own data (a tree) in the list card | `EntityListBody.renderOwnView` | list |
|
|
24
29
|
| an entity detail with tabs | `EntityDetailShell` (+ `SectionHeader`, `DefinitionList`) | page |
|
|
25
30
|
| a form page or drawer | `Form` + `FormField` / `FormSection` + `FormActions`, in `FormDrawer` | form |
|
|
26
31
|
| drawer state in the URL (`?edit=<id>`, `?create=1`) | `useEntityDrawer` with `useNextDrawerUrlAdapter` | logic, next |
|
|
@@ -50,6 +55,18 @@ installed package (`node_modules/@mgamadeus/ddd-admin-ui/`). This skill reaches
|
|
|
50
55
|
- **URL state.** Build requests from `list.debounced`, never `list.values`. All writes (filters, view, drawer) go
|
|
51
56
|
through the one URL writer, so writes in the same tick merge; never `router.replace` the search parameters by hand.
|
|
52
57
|
Screens reading search parameters render inside `<Suspense>`.
|
|
58
|
+
- **Wide tables.** Tracks are opt-in per table: one `width` gives every column a track (default `1fr`, minimum 120
|
|
59
|
+
px); the table then scrolls sideways inside its card instead of squeezing. `pin: 'end'` always holds; `pin: 'start'`
|
|
60
|
+
only while the table overflows by 120 px or more and the pinned columns stay under a third of the visible width. The
|
|
61
|
+
table never sorts rows: map `sortKey` to the request. Sizes are measured after hydration only.
|
|
62
|
+
- **SegmentedControl** is a radio group: exactly one value, one tab stop, arrows select (`activation="manual"`: Space /
|
|
63
|
+
Enter). Tooltips (`iconOnly`, `disabledReason`) need `AdminUiProvider`. Corner and slide come from
|
|
64
|
+
`--segmented-control-radius` / `--segmented-control-duration`.
|
|
65
|
+
- **Showcase** needs no optional peer: pass `loadNotifySonner={() => import('@mgamadeus/ddd-admin-ui/notify-sonner')}`
|
|
66
|
+
only when sonner is installed. A new block gets a showcase sample and a `SHOWCASE_COVERAGE` entry, or the checks fail.
|
|
67
|
+
- **Text contexts are literals.** `m('Failed', { context: 'import-status' })`: extractors (the package manifest and
|
|
68
|
+
host exports) read the text and the context as string literals; a context only on the status map or in a variable is
|
|
69
|
+
not exported. Put the same context on the definition or the map so `StatusBadge` translates with it.
|
|
53
70
|
- **Server vs client.** Hooks and context live in files with `'use client'`; pure helpers (`m`, `formatDateTime`,
|
|
54
71
|
`defineStatusMap`, schemas, conditions) may be called in server code and `metadata`.
|
|
55
72
|
|
|
@@ -65,6 +82,7 @@ export const ItemsScreen = () => {
|
|
|
65
82
|
const list = useUrlListState(LIST_KEYS, { adapter: useNextUrlStateAdapter({ listId: LIST_ID }), uncounted: ['q'] });
|
|
66
83
|
const [displayMode, setDisplayMode] = useListViewParam(LIST_ID, 'table');
|
|
67
84
|
const query = useItemsQuery(list.debounced); // the host's data hook
|
|
85
|
+
// wide tables: columns with width / pin / sortKey, then sort={sort} onSortChange={setSort} showRowIndex on the body
|
|
68
86
|
return (
|
|
69
87
|
<EntityListPage
|
|
70
88
|
title="Items"
|
package/CHANGELOG.md
CHANGED
|
@@ -1,6 +1,72 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
-
All notable changes to `@mgamadeus/ddd-admin-ui`. 0.x: each minor may break;
|
|
3
|
+
All notable changes to `@mgamadeus/ddd-admin-ui`. 0.x: each minor may break; pin the exact version while the package
|
|
4
|
+
is in 0.x prereleases.
|
|
5
|
+
|
|
6
|
+
## 0.1.0-rc.4
|
|
7
|
+
|
|
8
|
+
- `SegmentedControl` in `./primitives`: one value out of a few. Props `value`, `onValueChange`, `options` (`value`,
|
|
9
|
+
`label`, `icon`, `badge`, `description`, `disabled`, `disabledReason`, `className`), `aria-label` (required),
|
|
10
|
+
`height` (32 / 36 / 40 / 48), `iconOnly`, `fullWidth`, `selection` (`surface` / `primary`), `tone`
|
|
11
|
+
(`default` / `onBrand`), `activation` (`automatic` / `manual`), `className`; types `SegmentedControlProps`,
|
|
12
|
+
`SegmentedControlOption`. A radio group (`role="radiogroup"`, `role="radio"` + `aria-checked`, one tab stop): arrows,
|
|
13
|
+
Home and End move and select (manual: move the focus, Space / Enter select), right to left aware, disabled options
|
|
14
|
+
skipped with their reason announced and shown as a tooltip, `description` announced through `aria-describedby`,
|
|
15
|
+
`badge` hidden from assistive technology, `iconOnly` keeps the label as name and tooltip. A sliding indicator,
|
|
16
|
+
measured after layout, without motion under reduced motion; at least a 44 px target on coarse pointers. Pressing and
|
|
17
|
+
dragging across the options previews the choice; the value changes once on release; Escape or a cancelled pointer
|
|
18
|
+
restores it; a touch drag starts only after a sideways movement. New optional properties in `tokens.json`:
|
|
19
|
+
`--segmented-control-radius` (9999px) and `--segmented-control-duration` (200ms), defaults in `components.css`.
|
|
20
|
+
- New entry `./showcase`: `Showcase` draws every block of the package in the host's theme, light and dark, one section
|
|
21
|
+
per entry, with the host's sections appended (`sections`, `themes`, `omit`); `SHOWCASE_COVERAGE` lists the drawn
|
|
22
|
+
components per entry. It needs none of the optional peers: `./notify-sonner` loads lazily through `loadNotifySonner`
|
|
23
|
+
and is skipped without it or when the import fails; `./next` is described, never imported. Its texts stay out of
|
|
24
|
+
`i18n-keys.json` (the manifest builder skips the entry). `check-package` allows the entry the block entries only.
|
|
25
|
+
- List table sort: `EntityListColumn.sortStart` (`'asc'` / `'desc'`, the first direction when the column becomes
|
|
26
|
+
sorted) and `sortRequired` on `EntityListTable` / `EntityListBody` (never unsorted: the third click returns to the
|
|
27
|
+
first direction). `nextListSort(current, key, { start, required })` takes the same cycle (new type `ListSortCycle`);
|
|
28
|
+
calls without it keep the old cycle. A sortable header with `align: 'end'` puts the arrow before the label.
|
|
29
|
+
- Consumer checks: SegmentedControl in the browser (roles, both activation modes, right to left, disabled reason,
|
|
30
|
+
description, icon-only name and tooltip, drag preview with one change on release and none on Escape or cancel); the
|
|
31
|
+
showcase rendered on the server, bundled for the browser without optional peers and hydrated in the Next app; the
|
|
32
|
+
sort cycle with `sortStart` on an end-aligned column. The fixture app sets its UI language in one shared module.
|
|
33
|
+
|
|
34
|
+
## 0.1.0-rc.3
|
|
35
|
+
|
|
36
|
+
- List table, all optional (a table without the new props renders the same DOM and classes as 0.1.0-rc.2, proven by
|
|
37
|
+
a server-render snapshot taken from 0.1.0-rc.2, `pnpm test:render`):
|
|
38
|
+
- Column tracks: `EntityListColumn.width` (`'1fr'`, `'2fr'`, `'120px'`), `minWidth` (px, default 120), `align`
|
|
39
|
+
(`start` / `center` / `end`). One column with a width gives every column a track (default `1fr`); share columns
|
|
40
|
+
never go below their minimum, and when the minimums exceed the visible width the table scrolls sideways inside its
|
|
41
|
+
card. A table with tracks is one CSS grid (every row a subgrid, table roles kept); without any width the layout
|
|
42
|
+
stays content-sized.
|
|
43
|
+
- Pinned columns: `pin: 'start' | 'end'`. `end` always holds; `start` only while the table overflows by 120 px or
|
|
44
|
+
more and the pinned columns take less than a third of the visible width. In a table using tracks, pins or the row
|
|
45
|
+
index, the selection column and the row index always pin. A pinned cell paints the card surface and its edge only
|
|
46
|
+
while content scrolls under it.
|
|
47
|
+
- Sortable headers: `sortKey` on the column, `sort` / `onSortChange` on `EntityListTable` and `EntityListBody`;
|
|
48
|
+
not sorted → ascending → descending → not sorted, `aria-sort`, the header content is a button. The table never
|
|
49
|
+
sorts rows itself.
|
|
50
|
+
- Row index: `showRowIndex`, a leading `#` column, 1-based among the loaded rows (new text `Row number`).
|
|
51
|
+
- Sizes are measured after hydration only (server and hydration render use the CSS form of the same tracks).
|
|
52
|
+
- `EntityListBody.renderOwnView(mode)`: a view that owns its data and states, drawn in the list card as is, without
|
|
53
|
+
the paged list's skeletons, empty and error states and tail. `renderExtraView` is unchanged.
|
|
54
|
+
- `./logic`: `nextListSort`, `parseListSort`, `formatListSort` (`key:asc`), `EntityListSort`, `ListSortDirection`; the
|
|
55
|
+
pure track and pin mechanics `computeListTracks`, `listTrackTemplate`, `minimumListWidth`, `hasListTracks`,
|
|
56
|
+
`resolveListPins`, `shouldHonourStartPins`, `LIST_COLUMN_MIN_WIDTH`, `LIST_PIN_MAX_VISIBLE_SHARE`,
|
|
57
|
+
`LIST_PIN_MIN_OVERFLOW` and their types (`ListColumnWidth`, `ListColumnPin`, `ListColumnAlign`, `ListTrack`,
|
|
58
|
+
`ListTrackLayout`, `ListPinRequest`, `ListPinPlacement`, `ListPinMeasure`, `ListPinLayout`).
|
|
59
|
+
- Status contexts: `StatusDefinition.context` and `defineStatusMap(map, { context })` (`StatusMapOptions`; the
|
|
60
|
+
definition's context wins). `StatusBadge` translates label and description with it. `m()` takes an optional
|
|
61
|
+
`{ context }` (`MarkOptions`) that text exports read: `m('Failed', { context: 'import-status' })` → key
|
|
62
|
+
`Failed__import-status`. Existing calls are unchanged.
|
|
63
|
+
- `tokens.json`: data attributes `data-list-tracks`, `data-list-pin`, `data-list-pin-edge`, `data-list-overflow-start`,
|
|
64
|
+
`data-list-overflow-end` (read by `components.css`). No new colour role or custom property.
|
|
65
|
+
- Removed the optional peer `recharts` (no entry used it).
|
|
66
|
+
- Docs: pin the exact version while the package is in 0.x prereleases; neutral examples in `STANDARDS.md`; the list
|
|
67
|
+
section and the skill describe the new table props.
|
|
68
|
+
- Consumer checks: the no-prop snapshot and the status context (server render), and a list page with tracks, pins, sort
|
|
69
|
+
and row index in the browser (pin guard at three widths, sideways scroll inside the card at 390 px, sort cycle).
|
|
4
70
|
|
|
5
71
|
## 0.1.0-rc.2
|
|
6
72
|
|
package/README.md
CHANGED
|
@@ -22,7 +22,7 @@ pnpm add @mgamadeus/ddd-admin-ui @mgamadeus/ddd-web radix-ui react react-dom luc
|
|
|
22
22
|
|---|---|---|
|
|
23
23
|
| `./logic` | pure helpers (`formatDate`, `defineStatusMap`, conditions, schemas, `notify`, `runSequential`), React hooks without markup (`useUrlListState`, `useEntityDrawer`, `useRowSelection`, `useEntityTranslations`, …), browser helpers (`prepareImageFile`) | `./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, `cn`, the portal container | `./i18n` |
|
|
25
|
+
| `./primitives` | buttons, inputs, selects, dialogs, sheets, popovers, menus, tooltips, tables, badges, `SegmentedControl`, `cn`, the portal container | `./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
28
|
| `./form` | `Form`, `FormField`, `FormSection`, `FormActions`, `FormDrawer`, `FormHeader`, `FormWrapper`, `FormJumpBar`, `FormErrors`, `FormSubmitButton`, `useConfirmDialog` | logic, i18n, primitives; from page only `DetailHeader`, `EntityMetadata` |
|
|
@@ -32,6 +32,7 @@ pnpm add @mgamadeus/ddd-admin-ui @mgamadeus/ddd-web radix-ui react react-dom luc
|
|
|
32
32
|
| `./provider` | `AdminUiProvider`, `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
|
+
| `./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` |
|
|
35
36
|
| `./theme.css`, `./components.css` | the Tailwind theme binding and the structural CSS of the blocks | — |
|
|
36
37
|
| `./tokens.json`, `./i18n-keys.json` | the host contract (colour roles, properties, layers, data attributes) and the text manifest | — |
|
|
37
38
|
|
|
@@ -52,7 +53,6 @@ from the entry that owns it.
|
|
|
52
53
|
| `next` | optional peer | `^16.0.0` — needed by `./next` only |
|
|
53
54
|
| `sonner` | optional peer | `^2.0.0` — needed by `./notify-sonner` only |
|
|
54
55
|
| `tailwindcss` | optional peer | `^4.1.0` — the host's build compiles the CSS |
|
|
55
|
-
| `recharts` | optional peer | `^3.0.0` — reserved; no entry uses it yet |
|
|
56
56
|
| `radix-ui` | peer | `^1.8.1` — one copy per app, as with React (see below) |
|
|
57
57
|
| `class-variance-authority`, `cmdk`, `clsx`, `tailwind-merge` | dependencies | imported inside `./primitives` only |
|
|
58
58
|
|
|
@@ -114,7 +114,9 @@ It reads the host's `node_modules` (npm and pnpm layouts) and the folders above
|
|
|
114
114
|
[`tokens.json`](./tokens.json): the 31 colour roles, `--nav-h`, `--content-max`, `--radius`, the surface and glass
|
|
115
115
|
alphas and shadows, `--glass-control-shadow`. Dark mode is a `.dark` class on an ancestor; the default border
|
|
116
116
|
colour is the `border` role. `components.css` sets the four `--layer-*` defaults (`raised` 10, `sticky` 20,
|
|
117
|
-
`overlay` 50, `popover` 50)
|
|
117
|
+
`overlay` 50, `popover` 50) and the two optional properties of `SegmentedControl` (`--segmented-control-radius`
|
|
118
|
+
9999px, `--segmented-control-duration` 200ms) with zero specificity in the lowest cascade layer, so any host value
|
|
119
|
+
wins. Check a built
|
|
118
120
|
stylesheet against the contract:
|
|
119
121
|
|
|
120
122
|
```sh
|
|
@@ -178,6 +180,30 @@ const STATUS = defineStatusMap({ ACTIVE: { label: 'Active', tone: 'success' } })
|
|
|
178
180
|
Client components (`DateCell`, `EntityListTable`, `Form`, …) render from server components as long as they get no
|
|
179
181
|
function props there.
|
|
180
182
|
|
|
183
|
+
## Showcase
|
|
184
|
+
|
|
185
|
+
`./showcase` is a development page, not a screen block: mount it on a route of the host, below `AdminUiProvider`, to
|
|
186
|
+
see every block in the host's theme and tokens, light and dark side by side (each pane's dialogs and menus open inside
|
|
187
|
+
it).
|
|
188
|
+
|
|
189
|
+
```tsx
|
|
190
|
+
'use client';
|
|
191
|
+
import { Showcase } from '@mgamadeus/ddd-admin-ui/showcase';
|
|
192
|
+
|
|
193
|
+
export const ShowcaseScreen = () => (
|
|
194
|
+
<Showcase
|
|
195
|
+
// only a host with the optional peer sonner passes it; without it the section says it is skipped
|
|
196
|
+
loadNotifySonner={() => import('@mgamadeus/ddd-admin-ui/notify-sonner')}
|
|
197
|
+
sections={[{ id: 'host', title: 'Host blocks', content: <HostBlocks /> }]}
|
|
198
|
+
/>
|
|
199
|
+
);
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
It needs none of the optional peers: `./notify-sonner` loads only through `loadNotifySonner` (lazily, skipped when the
|
|
203
|
+
import fails), `./next` is described, never imported. `themes` limits the panes, `omit` leaves package sections out.
|
|
204
|
+
Its texts are developer-facing English and not part of `i18n-keys.json`. `SHOWCASE_COVERAGE` lists per entry the
|
|
205
|
+
components it draws and why the others are not drawn alone; the package's checks compare it with the exports.
|
|
206
|
+
|
|
181
207
|
A list rendered on the server hydrates without a mismatch: the stored grid/table view (`useListViewParam`) and the
|
|
182
208
|
saved filters of a list (`useUrlListState` with an adapter's `restore`) are read from browser storage only after
|
|
183
209
|
hydration, and applied in the render right after it. A list that mounts on the client (no server HTML) reads them in
|
|
@@ -190,7 +216,14 @@ The UI language lives in one store: `setTranslations(languageCode, writingStyle,
|
|
|
190
216
|
`translations` adapter) sets it, `useTranslate().t` and `translateText` read it, `m('…')` marks a text for extraction
|
|
191
217
|
without translating it. A key is the English text, or `<text>__<context>` with a context.
|
|
192
218
|
|
|
193
|
-
|
|
219
|
+
A text rendered with a context is marked with it: `m('Failed', { context: 'import-status' })` (`m` returns the text;
|
|
220
|
+
the context reaches the renderer separately, e.g. as `StatusDefinition.context` or the map context of
|
|
221
|
+
`defineStatusMap(map, { context })`). Extractors read the call statically: the first argument of `t(…)`,
|
|
222
|
+
`translateText(…)` or `m(…)` as a string literal, an optional second argument `{ … }` without nested braces whose
|
|
223
|
+
`context:` is a string literal, and `<Translate context="…">text</Translate>`; the key is `<text>__<context>`. A
|
|
224
|
+
context held in a variable, or only on the map, is invisible to an extractor, so each label carries its literal.
|
|
225
|
+
|
|
226
|
+
The package ships its texts (all entries except `./showcase`) as [`i18n-keys.json`](./i18n-keys.json) (`./i18n-keys.json`): every key with its text,
|
|
194
227
|
context, translator hint and the files that use it, sorted by key. A host's text export merges this manifest instead of
|
|
195
228
|
scanning the package (one usage per key, the hints with the host's own hint precedence). `ddd-admin-ui-i18n-manifest
|
|
196
229
|
--check` verifies that the installed package's manifest matches its built files (`--dir <package>` checks another
|
|
@@ -207,8 +240,9 @@ project's `.claude/skills/`. Idempotent; repoints an existing symlink, never tou
|
|
|
207
240
|
|
|
208
241
|
## Versioning
|
|
209
242
|
|
|
210
|
-
0.x: each minor may break.
|
|
211
|
-
(`x.y.z-…`) are published under the `next` dist-tag. Changes per release:
|
|
243
|
+
0.x: each minor may break. Pin the exact version while the package is in 0.x prereleases; modules peer on the version
|
|
244
|
+
they were tested with. Pre-releases (`x.y.z-…`) are published under the `next` dist-tag. Changes per release:
|
|
245
|
+
[CHANGELOG.md](CHANGELOG.md).
|
|
212
246
|
|
|
213
247
|
## Development
|
|
214
248
|
|
|
@@ -217,6 +251,7 @@ pnpm install
|
|
|
217
251
|
pnpm typecheck
|
|
218
252
|
pnpm test # unit tests beside the sources, script tests and a failing fixture per check-package rule
|
|
219
253
|
pnpm build # tsc → dist, declaration specifiers, stylesheets, manifests and shipped scripts
|
|
254
|
+
pnpm test:render # after the build: list snapshot (as in 0.1.0-rc.2), status contexts, the showcase
|
|
220
255
|
node scripts/check-package.mjs --dir .
|
|
221
256
|
pnpm pack --pack-destination "$TMPDIR" && test/consumer/run.sh "$TMPDIR"/mgamadeus-ddd-admin-ui-*.tgz pnpm "$TMPDIR/consumer-pnpm"
|
|
222
257
|
```
|
|
@@ -226,6 +261,7 @@ pnpm pack --pack-destination "$TMPDIR" && test/consumer/run.sh "$TMPDIR"/mgamade
|
|
|
226
261
|
| `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` |
|
|
227
262
|
| `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 |
|
|
228
263
|
| `node scripts/tokens-utilities.mjs [--write]` | checks (or regenerates) the `utilities` lists of `tokens.json` from the source |
|
|
264
|
+
| `pnpm test:render` | server-renders list tables, bodies and badges from the build: without the optional table props the markup equals `test/consumer/fixtures/plain/list-snapshot.html` (taken from 0.1.0-rc.2); a status map's translation context reaches `StatusBadge`; the showcase renders (light, dark, every section) and its coverage list matches the exports |
|
|
229
265
|
| `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 |
|
|
230
266
|
| `node scripts/check-tokens.mjs <css> [tokens.json]` | the host check above (shipped as `ddd-admin-ui-check-tokens`) |
|
|
231
267
|
| `node scripts/check-radix.mjs [host folder]` | the Radix copy check above (shipped as `ddd-admin-ui-check-radix`) |
|
package/STANDARDS.md
CHANGED
|
@@ -8,12 +8,12 @@ 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` |
|
|
11
|
+
| `@mgamadeus/ddd-admin-ui/logic` | `useUrlListState`, `useRowSelection`, `useEntityDrawer`, `drawerKey`, `defineStatusMap`, `formatDate`, `formatDateTime`, `runSequentialWithSummary`, `nextListSort`, `parseListSort`, `formatListSort` |
|
|
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
14
|
| `@mgamadeus/ddd-admin-ui/form` | `FormDrawer`, `FormActions`, `FormField`, `FormSection`, `useConfirmDialog` |
|
|
15
15
|
| `@mgamadeus/ddd-admin-ui/glass` | `QuickFilterPills`, `CollapsibleCard`, `GlassGroup`, `ActionRow` |
|
|
16
|
-
| `@mgamadeus/ddd-admin-ui/primitives` | `Button`, `Card`, `CardContent` |
|
|
16
|
+
| `@mgamadeus/ddd-admin-ui/primitives` | `Button`, `Card`, `CardContent`, `SegmentedControl` |
|
|
17
17
|
| `@mgamadeus/ddd-admin-ui/next` | `useNextUrlStateAdapter`, `useNextDrawerUrlAdapter`, `useListViewParam` |
|
|
18
18
|
|
|
19
19
|
Every screen renders below `AdminUiProvider`.
|
|
@@ -26,9 +26,9 @@ One hook for search + filters, in the URL, 350 ms debounce. Keys = URL parameter
|
|
|
26
26
|
import { useUrlListState } from '@mgamadeus/ddd-admin-ui/logic';
|
|
27
27
|
import { useNextUrlStateAdapter } from '@mgamadeus/ddd-admin-ui/next'; // or the host's own `UrlStateAdapter`
|
|
28
28
|
|
|
29
|
-
const LIST_KEYS = ['q', '
|
|
29
|
+
const LIST_KEYS = ['q', 'workspaceId', 'status', 'createdFrom', 'createdTo'] as const;
|
|
30
30
|
|
|
31
|
-
const list = useUrlListState(LIST_KEYS, { adapter: useNextUrlStateAdapter({ listId: 'admin.
|
|
31
|
+
const list = useUrlListState(LIST_KEYS, { adapter: useNextUrlStateAdapter({ listId: 'admin.projects' }), uncounted: ['q'] });
|
|
32
32
|
// inputs: list.values.q / list.setValue('q', value)
|
|
33
33
|
// request: build the filter string from list.debounced (never from list.values)
|
|
34
34
|
// multi: list.getList('status') / list.setList('status', next) → `?status=RUNNING,PAUSED`
|
|
@@ -50,8 +50,8 @@ below. Filters go **only** in the panel (never in `trailing`, never as an inline
|
|
|
50
50
|
filters={
|
|
51
51
|
<FilterPanel>
|
|
52
52
|
<FilterText label="ID" inputMode="numeric" value={list.values.id} onChange={value => list.setValue('id', value)} />
|
|
53
|
-
<FilterSelect label="
|
|
54
|
-
onChange={value => list.setValue('
|
|
53
|
+
<FilterSelect label="Workspace" allLabel="All workspaces" options={workspaceOptions} value={list.values.workspaceId}
|
|
54
|
+
onChange={value => list.setValue('workspaceId', value)} />
|
|
55
55
|
<FilterMultiSelect label="Status" options={STATUS_OPTIONS} value={list.getList('status')}
|
|
56
56
|
onChange={next => list.setList('status', next)} />
|
|
57
57
|
<FilterDateRange label="Created" from={list.values.createdFrom} to={list.values.createdTo}
|
|
@@ -68,6 +68,8 @@ below. Filters go **only** in the panel (never in `trailing`, never as an inline
|
|
|
68
68
|
- `FilterSelect`: `''` = All (`allLabel`), searchable automatically from 10 options (`searchable` to force).
|
|
69
69
|
- Yes / No filters: `options={YES_NO_FILTER_OPTIONS}` (`'1'` / `'0'`).
|
|
70
70
|
- Body: `isSearchActive={list.isActive}` and `onClearSearch={list.clear}` on `EntityListBody`.
|
|
71
|
+
- A view that owns its data and states (a tree with its own query): `EntityListBody.renderOwnView(mode)`, drawn in the
|
|
72
|
+
card as is. While an own view is shown the host omits search, filters and clear from the toolbar.
|
|
71
73
|
- Search modes (e.g. an AI search next to the text search): the mode switch goes in `search.leading` (it replaces the
|
|
72
74
|
magnifier at the same spot, ≤ 24 px), Enter / Escape in `search.onKeyDown`. Never lay a control over the field from
|
|
73
75
|
outside.
|
|
@@ -80,13 +82,13 @@ fit, already translated). Every write control `disabled={!writesAllowed}`.
|
|
|
80
82
|
|
|
81
83
|
```tsx
|
|
82
84
|
<EntityListPage
|
|
83
|
-
title="
|
|
85
|
+
title="Projects"
|
|
84
86
|
headerActions={
|
|
85
87
|
<PageToolbar
|
|
86
88
|
exportAction={<ExportButton onExport={handleExport} disabled={!writesAllowed} />}
|
|
87
|
-
moreActions={[{ id: 'recalc', label: 'Recalculate
|
|
89
|
+
moreActions={[{ id: 'recalc', label: 'Recalculate totals', icon: <RefreshCw />, onSelect: handleRecalc,
|
|
88
90
|
disabled: !writesAllowed }]}
|
|
89
|
-
primaryAction={<AddEntityButton entity="
|
|
91
|
+
primaryAction={<AddEntityButton entity="Project" href="/projects/create" linkComponent={Link}
|
|
90
92
|
disabled={!writesAllowed} />}
|
|
91
93
|
>
|
|
92
94
|
<Button variant="outline" onClick={openImport}>Import</Button>
|
|
@@ -103,17 +105,17 @@ fit, already translated). Every write control `disabled={!writesAllowed}`.
|
|
|
103
105
|
```tsx
|
|
104
106
|
const selection = useRowSelection({
|
|
105
107
|
items: list.items, // useGrowingWindowList().items
|
|
106
|
-
getKey:
|
|
108
|
+
getKey: task => toNumericId(task.id), // a host helper
|
|
107
109
|
resetKey: filterString ?? '', // new filters → empty selection
|
|
108
110
|
disabled: busy,
|
|
109
111
|
});
|
|
110
112
|
|
|
111
113
|
const handleBulkDelete = async () => {
|
|
112
|
-
if (!writesAllowed || !(await confirm({ title: `Delete ${selection.count}
|
|
114
|
+
if (!writesAllowed || !(await confirm({ title: `Delete ${selection.count} task(s)?`, confirmVariant: 'destructive',
|
|
113
115
|
confirmLabel: 'Delete' }))) return;
|
|
114
116
|
setBusy(true);
|
|
115
|
-
await runSequentialWithSummary(selection.selectedKeys, id =>
|
|
116
|
-
{ progress: 'Deleting', done: 'Deleted', noun: '
|
|
117
|
+
await runSequentialWithSummary(selection.selectedKeys, id => deleteTask({ taskId: id }).unwrap(),
|
|
118
|
+
{ progress: 'Deleting', done: 'Deleted', noun: 'task' });
|
|
117
119
|
setBusy(false);
|
|
118
120
|
selection.clear();
|
|
119
121
|
};
|
|
@@ -140,15 +142,15 @@ Order: [select] → image → **ID** → name (link) → relations → type / at
|
|
|
140
142
|
**Created / Updated** → **Actions**. Title Case headers. Every table with a detail route sets `rowAction`.
|
|
141
143
|
|
|
142
144
|
```tsx
|
|
143
|
-
const columns: EntityListColumn<
|
|
145
|
+
const columns: EntityListColumn<Project>[] = [
|
|
144
146
|
{ id: 'image', header: 'Image', cell: c => <ImageCell src={mediaSizedUrl(c.coverImage?.publicUrl, 'SMALL')} alt="" />,
|
|
145
147
|
className: 'w-16' },
|
|
146
148
|
{ id: 'id', header: 'ID', cell: c => <IdCell id={c.id} copyable />, className: 'w-20' },
|
|
147
|
-
{ id: 'name', header: 'Name', cell: c => <Link href={
|
|
149
|
+
{ id: 'name', header: 'Name', cell: c => <Link href={projectRoute(c.id)} className="font-medium hover:underline">
|
|
148
150
|
{c.name}</Link> },
|
|
149
|
-
{ id: '
|
|
150
|
-
{ id: 'status', header: 'Status', cell: c => <StatusBadge value={c.status} map={
|
|
151
|
-
{ id: '
|
|
151
|
+
{ id: 'workspace', header: 'Workspace', cell: c => orEmpty(c.workspace?.name) },
|
|
152
|
+
{ id: 'status', header: 'Status', cell: c => <StatusBadge value={c.status} map={PROJECT_STATUS} /> },
|
|
153
|
+
{ id: 'archived', header: 'Archived', cell: c => <BooleanCell value={c.archived} /> },
|
|
152
154
|
{ id: 'start', header: 'Start', cell: c => <DateCell value={c.startDate} format="date" /> },
|
|
153
155
|
{ id: 'created', header: 'Created', cell: c => <DateCell value={c.changeHistory?.createdTime} /> },
|
|
154
156
|
{ id: 'updated', header: 'Updated', cell: c => <DateCell value={c.changeHistory?.modifiedTime} /> },
|
|
@@ -168,15 +170,64 @@ const columns: EntityListColumn<Campaign>[] = [
|
|
|
168
170
|
- Numbers and ids: the host's formatters (one per kind), never ad-hoc `toFixed` calls.
|
|
169
171
|
- Copy next to a value outside the ID column: a copy button on `useCopyToClipboard`.
|
|
170
172
|
|
|
173
|
+
### Wide tables: tracks, pins, sort, row index
|
|
174
|
+
|
|
175
|
+
All optional; a table that uses none of them keeps the content-sized layout.
|
|
176
|
+
|
|
177
|
+
```tsx
|
|
178
|
+
const [sort, setSort] = useState<EntityListSort | null>(() => parseListSort(list.values.sort, ['name', 'created']));
|
|
179
|
+
// or in the URL list state: list.setValue('sort', formatListSort(next))
|
|
180
|
+
|
|
181
|
+
const columns: EntityListColumn<Project>[] = [
|
|
182
|
+
{ id: 'id', header: 'ID', cell: c => <IdCell id={c.id} />, width: '96px', pin: 'start', sortKey: 'id' },
|
|
183
|
+
{ id: 'name', header: 'Name', cell: c => c.name, width: '2fr', minWidth: 200, sortKey: 'name' },
|
|
184
|
+
{ id: 'owner', header: 'Owner', cell: c => orEmpty(c.owner?.name), width: '1fr' },
|
|
185
|
+
{ id: 'created', header: 'Created', cell: c => <DateCell value={c.changeHistory?.createdTime} />, width: '160px',
|
|
186
|
+
sortKey: 'created' },
|
|
187
|
+
{ id: 'actions', header: <span className="sr-only">Actions</span>, cell: c => <RowActions project={c} />,
|
|
188
|
+
width: '96px', pin: 'end', align: 'end' },
|
|
189
|
+
];
|
|
190
|
+
|
|
191
|
+
<EntityListBody … columns={columns} sort={sort} onSortChange={setSort} showRowIndex selection={selection} />
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
- **Tracks.** One column with `width` gives every column a track (default `1fr`): share columns (`'2fr'`) divide the
|
|
195
|
+
free width and never go below `minWidth` (default 120 px), fixed columns (`'120px'`) keep their length. When the
|
|
196
|
+
minimums exceed the visible width the table scrolls sideways inside its card; the page never does. In a table with
|
|
197
|
+
tracks a width class in `className` does not size the column, and cell text wraps inside its track.
|
|
198
|
+
- **Pins.** `pin: 'end'` always holds (a row's actions). `pin: 'start'` is a request: honoured only while the table
|
|
199
|
+
overflows (by 120 px or more) and the pinned columns take less than a third of the visible width; otherwise the column
|
|
200
|
+
scrolls like the others. The selection column and the row index always pin in a table that uses tracks, pins or the
|
|
201
|
+
row index. A pinned cell paints the card surface and its edge only while content scrolls under it.
|
|
202
|
+
- **Sort.** `sortKey` makes the header a button (with `aria-sort` on the sorted header); a click moves the sort on: not
|
|
203
|
+
sorted → ascending → descending → not sorted (`null`: the request's default order). `sortStart: 'desc'` on a column
|
|
204
|
+
starts it descending (dates: newest first); `sortRequired` on the table never returns to unsorted (the third click
|
|
205
|
+
goes back to the first direction). An end-aligned sortable header puts the arrow before the label, so the label lines
|
|
206
|
+
up with the numbers. The table never sorts rows itself; the screen maps the key to its request. One sort at a time;
|
|
207
|
+
keep it in the URL list state as one value (`formatListSort` / `parseListSort`, `key:asc`; `nextListSort` takes the
|
|
208
|
+
same cycle).
|
|
209
|
+
- **Row index.** `showRowIndex`: a leading `#` column, 1-based among the loaded rows.
|
|
210
|
+
- `align: 'center' | 'end'` aligns header and cells (numbers and actions `end`).
|
|
211
|
+
|
|
171
212
|
## 6. Status badges
|
|
172
213
|
|
|
173
|
-
One family map per enum, defined once in the host with `defineStatusMap` (e.g. `
|
|
174
|
-
a `
|
|
214
|
+
One family map per enum, defined once in the host with `defineStatusMap` (e.g. `PROJECT_STATUS`, `SYNC_STATUS` +
|
|
215
|
+
a `syncStatusOf` mapper for a boolean). A new enum gets a map there.
|
|
216
|
+
|
|
217
|
+
```tsx
|
|
218
|
+
<StatusBadge value={task.status} map={TASK_STATUS} />
|
|
219
|
+
<StatusBadge value={syncStatusOf(job.succeeded)} map={SYNC_STATUS} />
|
|
220
|
+
<StatusBadge tone="highlight" label="Featured" icon={Zap} /> // one-off flag
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
A word that means something else elsewhere (`Failed`, `Open`) gets a translation context, on the map or on one
|
|
224
|
+
definition (the definition's wins), and every label is marked with the same context so text exports find the key:
|
|
175
225
|
|
|
176
226
|
```tsx
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
227
|
+
const IMPORT_STATUS = defineStatusMap(
|
|
228
|
+
{ FAILED: { label: m('Failed', { context: 'import-status' }), tone: 'danger', icon: CircleX }, … },
|
|
229
|
+
{ context: 'import-status' },
|
|
230
|
+
);
|
|
180
231
|
```
|
|
181
232
|
|
|
182
233
|
Tones: `neutral` not started / inactive · `info` finished / informational · `success` running / active / done ·
|
|
@@ -186,7 +237,7 @@ Always with an icon.
|
|
|
186
237
|
## 7. Multi-select inputs
|
|
187
238
|
|
|
188
239
|
- Filters: `FilterMultiSelect` (above).
|
|
189
|
-
- Forms (roles,
|
|
240
|
+
- Forms (roles, teams, languages): `MultiSelect` inside `FormField`; a short fixed set (≤ ~8, fully visible):
|
|
190
241
|
`ChipToggleGroup`.
|
|
191
242
|
|
|
192
243
|
```tsx
|
|
@@ -205,28 +256,28 @@ Single searchable select (not a filter): `Combobox`.
|
|
|
205
256
|
|
|
206
257
|
## 8. Detail screens — `EntityDetailShell`
|
|
207
258
|
|
|
208
|
-
Every entity detail
|
|
209
|
-
|
|
210
|
-
|
|
259
|
+
Every entity detail uses the shell: back + centred title + description + actions, `EntityMetadata` (ID, Created,
|
|
260
|
+
Updated), centred segmented route tabs, loading and error. Full width (§ 10); the header is `DetailHeader`, `nested`
|
|
261
|
+
inside another shell.
|
|
211
262
|
|
|
212
263
|
```tsx
|
|
213
|
-
export const
|
|
264
|
+
export const ProjectShell = ({ projectId, children }: ProjectShellProps) => {
|
|
214
265
|
const pathname = usePathname();
|
|
215
|
-
const query =
|
|
216
|
-
const
|
|
266
|
+
const query = useProjectQuery(projectId);
|
|
267
|
+
const project = query.data?.project;
|
|
217
268
|
return (
|
|
218
269
|
<EntityDetailShell
|
|
219
|
-
title={
|
|
220
|
-
fallbackTitle={`
|
|
221
|
-
description={
|
|
222
|
-
back={{ href: '/
|
|
270
|
+
title={project?.name}
|
|
271
|
+
fallbackTitle={`Project #${projectId}`}
|
|
272
|
+
description={project?.workspace?.name}
|
|
273
|
+
back={{ href: '/projects', label: 'Back to projects' }}
|
|
223
274
|
linkComponent={Link}
|
|
224
|
-
metadata={{ id:
|
|
225
|
-
tabs={
|
|
275
|
+
metadata={{ id: project?.id, changeHistory: project?.changeHistory }}
|
|
276
|
+
tabs={PROJECT_TABS.map(tab => ({ id: tab.segment, label: tab.label, href: projectRoute(projectId, tab.segment) }))}
|
|
226
277
|
currentPath={pathname}
|
|
227
|
-
tabsLabel="
|
|
278
|
+
tabsLabel="Project sections"
|
|
228
279
|
isLoading={query.isLoading}
|
|
229
|
-
error={!query.isLoading && !
|
|
280
|
+
error={!query.isLoading && !project ? (query.isError ? 'This project could not be loaded.' : 'Project not found.') : undefined}
|
|
230
281
|
actions={<PageToolbar moreActions={…} />}
|
|
231
282
|
>
|
|
232
283
|
{children}
|
|
@@ -238,15 +289,15 @@ export const CampaignShell = ({ campaignId, children }: CampaignShellProps) => {
|
|
|
238
289
|
Inside a tab:
|
|
239
290
|
|
|
240
291
|
```tsx
|
|
241
|
-
<SectionHeader title="
|
|
242
|
-
tabs={[{ id: '
|
|
243
|
-
activeTab={tab} onTabSelect={setTab} actions={<ExportButton onExport={
|
|
292
|
+
<SectionHeader title="Members" description="People working on this project"
|
|
293
|
+
tabs={[{ id: 'people', label: 'People' }, { id: 'teams', label: 'Teams' }]}
|
|
294
|
+
activeTab={tab} onTabSelect={setTab} actions={<ExportButton onExport={exportMembers} />} />
|
|
244
295
|
|
|
245
296
|
<Card><CardContent>
|
|
246
297
|
<DefinitionList columns={3} items={[
|
|
247
|
-
{ label: 'Access Code', value:
|
|
248
|
-
{ label: 'Start', value: <DateCell value={
|
|
249
|
-
{ label: 'Description', value:
|
|
298
|
+
{ label: 'Access Code', value: workspace.accessCode },
|
|
299
|
+
{ label: 'Start', value: <DateCell value={workspace.startDate} format="date" /> },
|
|
300
|
+
{ label: 'Description', value: workspace.description, wide: true },
|
|
250
301
|
]} />
|
|
251
302
|
</CardContent></Card>
|
|
252
303
|
```
|
|
@@ -281,7 +332,7 @@ The look lives in the blocks; a screen never re-draws it.
|
|
|
281
332
|
- **Tabs** are the segmented pill control: `EntityDetailShell` centres them under the centred title; standalone tab
|
|
282
333
|
bars use `EntityTabs` as is; sub-tabs of a section are `SectionHeader tabs`
|
|
283
334
|
(compact). Never a hand-made underline or pill bar.
|
|
284
|
-
- **Two-tone titles**: wrap the brand part in `<em>` — `title={<>
|
|
335
|
+
- **Two-tone titles**: wrap the brand part in `<em>` — `title={<>Item <em>Types</em></>}` (pass `label="Item Types"` to
|
|
285
336
|
`EntityListPage` then). Only where a title earns it (Home, section headers), not on every list.
|
|
286
337
|
- **Sticky glass bars**: page forms get them from `FormActions` (`sticky={false}` inside a dialog); the bulk bar from
|
|
287
338
|
`EntityListBulkBar`.
|
|
@@ -293,8 +344,8 @@ The look lives in the blocks; a screen never re-draws it.
|
|
|
293
344
|
<CardGrid>
|
|
294
345
|
<EditableCard title="Access" onEdit={openAccessForm} editLabel="Edit access" editDisabled={!writesAllowed}>
|
|
295
346
|
<IconValueRow>
|
|
296
|
-
<IconValue icon={<KeyRound />}>{
|
|
297
|
-
<IconValue icon={<Calendar />}><DateCell value={
|
|
347
|
+
<IconValue icon={<KeyRound />}>{workspace.accessCode ?? <EmptyValue />}</IconValue>
|
|
348
|
+
<IconValue icon={<Calendar />}><DateCell value={workspace.startDate} format="date" /></IconValue>
|
|
298
349
|
</IconValueRow>
|
|
299
350
|
</EditableCard>
|
|
300
351
|
<EditableCard title="Languages" onEdit={openLanguagesForm} editLabel="Edit languages" editDisabled={!writesAllowed}>
|
|
@@ -329,10 +380,10 @@ Blocks in `glass/`.
|
|
|
329
380
|
</CollapsibleCard>
|
|
330
381
|
|
|
331
382
|
// A grouped to-do list on the clouds: glass group (no shadow) + solid rows.
|
|
332
|
-
<GlassGroup title="Running" count={cards.length} limit={8} emptyText="No
|
|
383
|
+
<GlassGroup title="Running" count={cards.length} limit={8} emptyText="No tasks">
|
|
333
384
|
{cards.map(card => (
|
|
334
385
|
<Link key={card.id} href={…}><ActionRow as="span" interactive title={card.name} description={card.context}
|
|
335
|
-
tone={
|
|
386
|
+
tone={TASK_STATUS[card.status].tone} toneLabel={TASK_STATUS[card.status].label} /></Link>
|
|
336
387
|
))}
|
|
337
388
|
</GlassGroup>
|
|
338
389
|
```
|
|
@@ -351,19 +402,19 @@ button).
|
|
|
351
402
|
// The list screen (inside <Suspense>): drawer state in the URL next to the filters — `?edit=<id>` / `?create=1`.
|
|
352
403
|
const drawer = useEntityDrawer({ adapter: useNextDrawerUrlAdapter() }); // ./next, or the host's own adapter
|
|
353
404
|
|
|
354
|
-
<AddEntityButton entity="
|
|
355
|
-
rowAction={
|
|
356
|
-
<Link href={
|
|
357
|
-
<
|
|
405
|
+
<AddEntityButton entity="Supplier" onClick={drawer.openCreate} disabled={!writesAllowed} />
|
|
406
|
+
rowAction={supplier => () => drawer.openEdit(id)}
|
|
407
|
+
<Link href={supplierEditRoute(id)} onClick={drawer.editLinkClick(id)}>{supplier.name}</Link> // middle click = new tab
|
|
408
|
+
<SupplierFormDrawer drawer={drawer} />
|
|
358
409
|
|
|
359
410
|
// The module's drawer: loads the entity for the header, renders the existing form inside.
|
|
360
411
|
const shown = drawer.shown; // stays set while the close animation runs
|
|
361
412
|
const id = shown?.mode === 'edit' ? shown.id : undefined;
|
|
362
413
|
const query = useGet…Query({ …, id: id ?? '' }, { skip: id === undefined });
|
|
363
|
-
const entity = id ? (query.currentData?.
|
|
364
|
-
<FormDrawer open={drawer.isOpen} onClose={drawer.close} title={entity?.name ?? `
|
|
414
|
+
const entity = id ? (query.currentData?.supplier ?? null) : null; // currentData: never the previous row's
|
|
415
|
+
<FormDrawer open={drawer.isOpen} onClose={drawer.close} title={entity?.name ?? `Supplier #${id}`}
|
|
365
416
|
metadata={entity ? { id: entity.id, changeHistory: entity.changeHistory } : undefined}>
|
|
366
|
-
<
|
|
417
|
+
<SupplierForm key={drawerKey(shown)} supplier={entity} onClose={drawer.close} />
|
|
367
418
|
</FormDrawer>
|
|
368
419
|
```
|
|
369
420
|
|
|
@@ -372,14 +423,37 @@ const entity = id ? (query.currentData?.sponsor ?? null) : null; // currentDat
|
|
|
372
423
|
`onClose()`. `FormActions` moves into the drawer's pinned footer by itself (change status left, buttons right); the
|
|
373
424
|
✕, Esc and an overlay click ask "Discard changes?" through `useUnsavedChangesGuard`. Request bodies stay as they are.
|
|
374
425
|
- **Header**: entity title + `EntityMetadata variant="inline"` (ID · Created · Updated, one line) via `metadata`;
|
|
375
|
-
create passes a `description` instead. Entity actions that are no save (e.g. "Open as
|
|
426
|
+
create passes a `description` instead. Entity actions that are no save (e.g. "Open as customer", "Reset password")
|
|
376
427
|
go into `headerActions` (outline `sm` buttons at the right end of the header); the save stays in the footer.
|
|
377
428
|
- **History**: opening pushes an entry (Back closes the drawer); `close()` pops it when this page opened the drawer and
|
|
378
429
|
removes the parameter otherwise (a link, a reload). A create that turns into the new entity's edit uses
|
|
379
430
|
`openEdit(newId, { replace: true })`. The writes are shallow (`history.pushState`): the list stays mounted.
|
|
380
431
|
- **Detail routes** (`/<entity>/:id`, `/create`) can stay as redirects to the list with the parameter. Route helpers
|
|
381
|
-
(`
|
|
432
|
+
(`supplierEditRoute`) live in a non-client file (a server page calls them).
|
|
382
433
|
- A list hosting two drawers passes its own `editKey` / `createKey`.
|
|
383
434
|
- **Confirm**: the drawer asks through the package dialog; a host with its own confirmation service passes
|
|
384
435
|
`confirm={hostConfirm}` (stable function, same Radix copy). The same prop exists on the translatable fields.
|
|
385
436
|
- One column inside the drawer (≤ 760 px): no `md:grid-cols-2` form grids.
|
|
437
|
+
|
|
438
|
+
## 13. One value out of a few — `SegmentedControl`
|
|
439
|
+
|
|
440
|
+
| Need | Use |
|
|
441
|
+
|---|---|
|
|
442
|
+
| switch what one area shows, without own panels or routes (a period, a scope, a chart metric, a view mode) | `SegmentedControl` (`./primitives`) |
|
|
443
|
+
| sections of an entity with their own content or route | `EntityTabs` / `EntityDetailShell` tabs / `SectionHeader tabs` |
|
|
444
|
+
| quick filters on the clouds, "All" allowed, counts | `QuickFilterPills` |
|
|
445
|
+
| several values on at once (languages, weekdays) | `ChipToggleGroup` (or `MultiSelect` when the set grows) |
|
|
446
|
+
| the list's grid / table switch | `EntityListViewToggle` |
|
|
447
|
+
|
|
448
|
+
```tsx
|
|
449
|
+
<SegmentedControl aria-label="Period" value={period} onValueChange={setPeriod} options={[
|
|
450
|
+
{ value: 'week', label: 'Week' },
|
|
451
|
+
{ value: 'month', label: 'Month', description: 'Calendar month' },
|
|
452
|
+
{ value: 'year', label: 'Year', disabled: !hasYearData, disabledReason: 'Not enough data yet' },
|
|
453
|
+
]} />
|
|
454
|
+
```
|
|
455
|
+
|
|
456
|
+
- Always exactly one value; 2–5 short options. More, or long labels: a select.
|
|
457
|
+
- `activation="manual"` when a change is expensive (loads data): arrows move the focus, Space / Enter select.
|
|
458
|
+
- `iconOnly` keeps the label as the accessible name and shows it as a tooltip (needs `AdminUiProvider`).
|
|
459
|
+
- A disabled option says why (`disabledReason`); a count goes in `badge` and, when it matters, in `description`.
|