@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.
Files changed (101) hide show
  1. package/.claude/skills/ddd-admin-ui-specialist/SKILL.md +20 -2
  2. package/CHANGELOG.md +67 -1
  3. package/README.md +42 -6
  4. package/STANDARDS.md +132 -58
  5. package/dist/components.css +63 -3
  6. package/dist/i18n/hints.json +2 -1
  7. package/dist/i18n/index.d.ts +1 -1
  8. package/dist/i18n/index.d.ts.map +1 -1
  9. package/dist/i18n/index.js.map +1 -1
  10. package/dist/i18n/store.d.ts +10 -2
  11. package/dist/i18n/store.d.ts.map +1 -1
  12. package/dist/i18n/store.js +6 -2
  13. package/dist/i18n/store.js.map +1 -1
  14. package/dist/i18n-keys.json +9 -1
  15. package/dist/list/EntityListBody.d.ts +10 -3
  16. package/dist/list/EntityListBody.d.ts.map +1 -1
  17. package/dist/list/EntityListBody.js +9 -3
  18. package/dist/list/EntityListBody.js.map +1 -1
  19. package/dist/list/EntityListTable.d.ts +42 -2
  20. package/dist/list/EntityListTable.d.ts.map +1 -1
  21. package/dist/list/EntityListTable.js +158 -6
  22. package/dist/list/EntityListTable.js.map +1 -1
  23. package/dist/list/StatusBadge.d.ts +1 -1
  24. package/dist/list/StatusBadge.d.ts.map +1 -1
  25. package/dist/list/StatusBadge.js +3 -2
  26. package/dist/list/StatusBadge.js.map +1 -1
  27. package/dist/logic/index.d.ts +5 -1
  28. package/dist/logic/index.d.ts.map +1 -1
  29. package/dist/logic/index.js +2 -0
  30. package/dist/logic/index.js.map +1 -1
  31. package/dist/logic/pure/listSort.d.ts +29 -0
  32. package/dist/logic/pure/listSort.d.ts.map +1 -0
  33. package/dist/logic/pure/listSort.js +35 -0
  34. package/dist/logic/pure/listSort.js.map +1 -0
  35. package/dist/logic/pure/listTracks.d.ts +90 -0
  36. package/dist/logic/pure/listTracks.d.ts.map +1 -0
  37. package/dist/logic/pure/listTracks.js +139 -0
  38. package/dist/logic/pure/listTracks.js.map +1 -0
  39. package/dist/logic/pure/status.d.ts +23 -2
  40. package/dist/logic/pure/status.d.ts.map +1 -1
  41. package/dist/logic/pure/status.js +23 -2
  42. package/dist/logic/pure/status.js.map +1 -1
  43. package/dist/primitives/index.d.ts +1 -0
  44. package/dist/primitives/index.d.ts.map +1 -1
  45. package/dist/primitives/index.js +1 -0
  46. package/dist/primitives/index.js.map +1 -1
  47. package/dist/primitives/segmented-control.d.ts +57 -0
  48. package/dist/primitives/segmented-control.d.ts.map +1 -0
  49. package/dist/primitives/segmented-control.js +206 -0
  50. package/dist/primitives/segmented-control.js.map +1 -0
  51. package/dist/primitives/segmentedControlNavigation.d.ts +31 -0
  52. package/dist/primitives/segmentedControlNavigation.d.ts.map +1 -0
  53. package/dist/primitives/segmentedControlNavigation.js +65 -0
  54. package/dist/primitives/segmentedControlNavigation.js.map +1 -0
  55. package/dist/scripts/build-i18n-manifest.mjs +9 -3
  56. package/dist/showcase/Showcase.d.ts +35 -0
  57. package/dist/showcase/Showcase.d.ts.map +1 -0
  58. package/dist/showcase/Showcase.js +47 -0
  59. package/dist/showcase/Showcase.js.map +1 -0
  60. package/dist/showcase/coverage.d.ts +11 -0
  61. package/dist/showcase/coverage.d.ts.map +1 -0
  62. package/dist/showcase/coverage.js +77 -0
  63. package/dist/showcase/coverage.js.map +1 -0
  64. package/dist/showcase/index.d.ts +6 -0
  65. package/dist/showcase/index.d.ts.map +1 -0
  66. package/dist/showcase/index.js +5 -0
  67. package/dist/showcase/index.js.map +1 -0
  68. package/dist/showcase/sections/FormShowcase.d.ts +3 -0
  69. package/dist/showcase/sections/FormShowcase.d.ts.map +1 -0
  70. package/dist/showcase/sections/FormShowcase.js +26 -0
  71. package/dist/showcase/sections/FormShowcase.js.map +1 -0
  72. package/dist/showcase/sections/GlassShowcase.d.ts +3 -0
  73. package/dist/showcase/sections/GlassShowcase.d.ts.map +1 -0
  74. package/dist/showcase/sections/GlassShowcase.js +19 -0
  75. package/dist/showcase/sections/GlassShowcase.js.map +1 -0
  76. package/dist/showcase/sections/ListShowcase.d.ts +13 -0
  77. package/dist/showcase/sections/ListShowcase.d.ts.map +1 -0
  78. package/dist/showcase/sections/ListShowcase.js +67 -0
  79. package/dist/showcase/sections/ListShowcase.js.map +1 -0
  80. package/dist/showcase/sections/MediaShowcase.d.ts +3 -0
  81. package/dist/showcase/sections/MediaShowcase.d.ts.map +1 -0
  82. package/dist/showcase/sections/MediaShowcase.js +28 -0
  83. package/dist/showcase/sections/MediaShowcase.js.map +1 -0
  84. package/dist/showcase/sections/OptionalShowcase.d.ts +14 -0
  85. package/dist/showcase/sections/OptionalShowcase.d.ts.map +1 -0
  86. package/dist/showcase/sections/OptionalShowcase.js +32 -0
  87. package/dist/showcase/sections/OptionalShowcase.js.map +1 -0
  88. package/dist/showcase/sections/PageShowcase.d.ts +3 -0
  89. package/dist/showcase/sections/PageShowcase.d.ts.map +1 -0
  90. package/dist/showcase/sections/PageShowcase.js +37 -0
  91. package/dist/showcase/sections/PageShowcase.js.map +1 -0
  92. package/dist/showcase/sections/PrimitivesShowcase.d.ts +13 -0
  93. package/dist/showcase/sections/PrimitivesShowcase.d.ts.map +1 -0
  94. package/dist/showcase/sections/PrimitivesShowcase.js +40 -0
  95. package/dist/showcase/sections/PrimitivesShowcase.js.map +1 -0
  96. package/dist/showcase/sections/TranslationsShowcase.d.ts +3 -0
  97. package/dist/showcase/sections/TranslationsShowcase.d.ts.map +1 -0
  98. package/dist/showcase/sections/TranslationsShowcase.js +30 -0
  99. package/dist/showcase/sections/TranslationsShowcase.js.map +1 -0
  100. package/dist/tokens.json +37 -1
  101. 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 on @mgamadeus/ddd-web and extend the package. Covers the entries and their import matrix, host setup (AdminUiProvider above every page, theme.css and components.css after Tailwind, tokens.json with ddd-admin-ui-check-tokens, peers, one Radix copy with ddd-admin-ui-check-radix), list pages with URL filters, grid/table view, selection and bulk actions, detail shells, form drawers with conditions, server errors and the unsaved-changes guard, translations on full locale::style keys, media fields, toasts, layers and the portal container, the text manifest i18n-keys.json, server vs client files, and adding a block (build, pack, check-package). 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 colour, layer or overlay misbehaves (two overlays fight over focus or outside clicks), translations lose a style variant, URL filters get lost, or a block is added to the package."
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; depend on it with `">=0.N <1"`.
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) with zero specificity in the lowest cascade layer, so any host value wins. Check a built
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
- The package ships its texts as [`i18n-keys.json`](./i18n-keys.json) (`./i18n-keys.json`): every key with its text,
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. Depend on it with an explicit range, `">=0.N <1"`, never a caret on 0.x. Pre-releases
211
- (`x.y.z-…`) are published under the `next` dist-tag. Changes per release: [CHANGELOG.md](CHANGELOG.md).
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', 'worldId', 'status', 'createdFrom', 'createdTo'] as const;
29
+ const LIST_KEYS = ['q', 'workspaceId', 'status', 'createdFrom', 'createdTo'] as const;
30
30
 
31
- const list = useUrlListState(LIST_KEYS, { adapter: useNextUrlStateAdapter({ listId: 'admin.campaigns' }), uncounted: ['q'] });
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="World" allLabel="All Worlds" options={worldOptions} value={list.values.worldId}
54
- onChange={value => list.setValue('worldId', value)} />
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="Campaigns"
85
+ title="Projects"
84
86
  headerActions={
85
87
  <PageToolbar
86
88
  exportAction={<ExportButton onExport={handleExport} disabled={!writesAllowed} />}
87
- moreActions={[{ id: 'recalc', label: 'Recalculate rankings', icon: <RefreshCw />, onSelect: handleRecalc,
89
+ moreActions={[{ id: 'recalc', label: 'Recalculate totals', icon: <RefreshCw />, onSelect: handleRecalc,
88
90
  disabled: !writesAllowed }]}
89
- primaryAction={<AddEntityButton entity="Campaign" href="/campaigns/create" linkComponent={Link}
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: track => toNumericId(track.id), // a host helper
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} track(s)?`, confirmVariant: 'destructive',
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 => deleteTrack({ trackId: id }).unwrap(),
116
- { progress: 'Deleting', done: 'Deleted', noun: 'track' });
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<Campaign>[] = [
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={campaignRoute(c.id)} className="font-medium hover:underline">
149
+ { id: 'name', header: 'Name', cell: c => <Link href={projectRoute(c.id)} className="font-medium hover:underline">
148
150
  {c.name}</Link> },
149
- { id: 'world', header: 'World', cell: c => orEmpty(c.world?.name) },
150
- { id: 'status', header: 'Status', cell: c => <StatusBadge value={c.status} map={CAMPAIGN_STATUS} /> },
151
- { id: 'landingpage', header: 'Landing Page', cell: c => <BooleanCell value={c.landingpageEnabled} /> },
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. `CAMPAIGN_STATUS`, `DELIVERY_STATUS` +
174
- a `deliveryStatusOf` mapper for a boolean). A new enum gets a map there.
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
- <StatusBadge value={challenge.status} map={CHALLENGE_STATUS} />
178
- <StatusBadge value={deliveryStatusOf(push.sentSuccessfully)} map={DELIVERY_STATUS} />
179
- <StatusBadge tone="highlight" label="Electric" icon={Zap} /> // one-off flag
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, worlds, languages): `MultiSelect` inside `FormField`; a short fixed set (≤ ~8, fully visible):
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 (World, Campaign, Challenge, Account, Partner, Track, Ticket …) uses the shell: back + centred
209
- title + description + actions, `EntityMetadata` (ID, Created, Updated), centred segmented route tabs, loading and
210
- error. Full width (§ 10); the header is `DetailHeader`, `nested` inside another shell.
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 CampaignShell = ({ campaignId, children }: CampaignShellProps) => {
264
+ export const ProjectShell = ({ projectId, children }: ProjectShellProps) => {
214
265
  const pathname = usePathname();
215
- const query = useCampaignQuery(campaignId);
216
- const campaign = query.data?.campaign;
266
+ const query = useProjectQuery(projectId);
267
+ const project = query.data?.project;
217
268
  return (
218
269
  <EntityDetailShell
219
- title={campaign?.name}
220
- fallbackTitle={`Campaign #${campaignId}`}
221
- description={campaign?.world?.name}
222
- back={{ href: '/campaigns', label: 'Back to campaigns' }}
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: campaign?.id, changeHistory: campaign?.changeHistory }}
225
- tabs={CAMPAIGN_TABS.map(tab => ({ id: tab.segment, label: tab.label, href: campaignRoute(campaignId, tab.segment) }))}
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="Campaign sections"
278
+ tabsLabel="Project sections"
228
279
  isLoading={query.isLoading}
229
- error={!query.isLoading && !campaign ? (query.isError ? 'This campaign could not be loaded.' : 'Campaign not found.') : undefined}
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="Rankings" description="Top riders of this challenge"
242
- tabs={[{ id: 'accounts', label: 'Accounts' }, { id: 'teams', label: 'Teams' }]}
243
- activeTab={tab} onTabSelect={setTab} actions={<ExportButton onExport={exportRankings} />} />
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: world.accessCode },
248
- { label: 'Start', value: <DateCell value={world.startDate} format="date" /> },
249
- { label: 'Description', value: world.description, wide: true },
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={<>Bike <em>Types</em></>}` (pass `label="Bike Types"` to
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 />}>{world.accessCode ?? <EmptyValue />}</IconValue>
297
- <IconValue icon={<Calendar />}><DateCell value={world.startDate} format="date" /></IconValue>
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 challenges">
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={CHALLENGE_STATUS[card.status].tone} toneLabel={CHALLENGE_STATUS[card.status].label} /></Link>
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="Sponsor" onClick={drawer.openCreate} disabled={!writesAllowed} />
355
- rowAction={sponsor => () => drawer.openEdit(id)}
356
- <Link href={sponsorEditRoute(id)} onClick={drawer.editLinkClick(id)}>{sponsor.name}</Link> // middle click = new tab
357
- <SponsorFormDrawer drawer={drawer} />
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?.sponsor ?? null) : null; // currentData: never the previous row's
364
- <FormDrawer open={drawer.isOpen} onClose={drawer.close} title={entity?.name ?? `Sponsor #${id}`}
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
- <SponsorForm key={drawerKey(shown)} sponsor={entity} onClose={drawer.close} />
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 partner", "Reset password")
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
- (`sponsorEditRoute`) live in a non-client file (a server page calls them).
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`.