@gemboss/ui 0.48.0 → 0.51.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/CHANGELOG.md +457 -0
  2. package/README.md +280 -12
  3. package/catalog/editor.html +25 -12
  4. package/catalog/index.html +641 -99
  5. package/gemboss-ui.css +3 -3
  6. package/package.json +29 -2
  7. package/parts/components.css +3 -3
  8. package/parts/core.css +1 -1
  9. package/parts/shell.css +2 -2
  10. package/src/app-shell.css +1 -1
  11. package/src/assistant/chat.tsx +50 -6
  12. package/src/assistant/host.tsx +19 -7
  13. package/src/assistant/index.ts +1 -1
  14. package/src/assistant/sessions.tsx +2 -1
  15. package/src/assistant-chat.css +1 -1
  16. package/src/assistant.css +1 -1
  17. package/src/auth-extras.css +1 -0
  18. package/src/auth-footer.css +1 -0
  19. package/src/auth-footer.tsx +71 -0
  20. package/src/auth-signin-plain.js +1 -0
  21. package/src/auth-sso-plain.js +1 -1
  22. package/src/auth-steps.css +1 -0
  23. package/src/auth-steps.tsx +179 -0
  24. package/src/auth.css +1 -1
  25. package/src/auth.tsx +239 -14
  26. package/src/briefing-card.css +1 -1
  27. package/src/collections.css +1 -1
  28. package/src/create-shell.css +1 -0
  29. package/src/create-shell.tsx +221 -0
  30. package/src/dialog.tsx +3 -0
  31. package/src/editor/color-picker.tsx +183 -0
  32. package/src/editor/controls.tsx +49 -33
  33. package/src/editor/index.ts +8 -0
  34. package/src/editor/picker-grid.tsx +186 -0
  35. package/src/editor/picker.tsx +275 -0
  36. package/src/editor/popover.tsx +160 -0
  37. package/src/editor/swatch.ts +2 -1
  38. package/src/editor-color.css +1 -0
  39. package/src/editor-insert.css +1 -0
  40. package/src/editor-picker-grid.css +1 -0
  41. package/src/editor-picker.css +1 -0
  42. package/src/editor-plain.js +1 -1
  43. package/src/editor-popover.css +1 -0
  44. package/src/editor.css +1 -1
  45. package/src/empty-stage.css +1 -0
  46. package/src/empty-stage.tsx +31 -0
  47. package/src/icons.tsx +6 -0
  48. package/src/index-table.tsx +7 -4
  49. package/src/index.ts +19 -2
  50. package/src/kit-plain.css +1 -1
  51. package/src/kit-plain.js +1 -1
  52. package/src/language-switcher.tsx +10 -41
  53. package/src/list-page.css +1 -0
  54. package/src/list-page.tsx +239 -0
  55. package/src/menu-extras.css +1 -0
  56. package/src/menu-keys.ts +199 -0
  57. package/src/menu-layer.ts +2 -1
  58. package/src/menu-plain.js +1 -0
  59. package/src/menu.css +1 -0
  60. package/src/menu.tsx +83 -35
  61. package/src/pager-extras.css +1 -0
  62. package/src/pager.css +1 -0
  63. package/src/pager.tsx +88 -0
  64. package/src/portal.css +1 -1
  65. package/src/segmented.tsx +12 -2
  66. package/src/selection.tsx +3 -1
  67. package/src/session-rail-plain.js +1 -1
  68. package/src/settings-dialog.tsx +29 -2
  69. package/src/shell.css +1 -1
  70. package/src/stage-path.css +1 -0
  71. package/src/stage-path.tsx +89 -0
  72. package/src/stage.css +1 -0
  73. package/src/stage.tsx +52 -0
  74. package/src/starting-point.css +1 -0
  75. package/src/starting-point.tsx +93 -0
  76. package/src/status-list.css +1 -0
  77. package/src/status-list.tsx +65 -0
  78. package/src/status-matrix.css +1 -0
  79. package/src/status-matrix.tsx +131 -0
  80. package/src/team-chat.css +1 -1
  81. package/src/theme.tsx +13 -3
  82. package/src/translation-row.css +1 -0
  83. package/src/translation-row.tsx +113 -0
  84. package/src/ui.css +1 -1
package/README.md CHANGED
@@ -54,9 +54,13 @@ its CSS out of the build with it (`sideEffects`). gzip of the minified file, as
54
54
  | Part | Import (Node / bundler) | File in the tarball | What | gzip | Who loads it |
55
55
  |---|---|---|---|---:|---|
56
56
  | core | `@gemboss/ui/core.css` | `parts/core.css` | the box-sizing reset + the tokens | 1.0 KB | every surface, first |
57
- | components | `@gemboss/ui/components.css` | `parts/components.css` | the kit (`ui.css`), the field look, the plain-HTML primitives (`kit-plain.css`: menu, chips, report pieces, popup body) | 8.2 KB | every surface, second |
57
+ | components | `@gemboss/ui/components.css` | `parts/components.css` | the kit (`ui.css`), the field look, the ⋯ menu and the icon button (`menu.css`), the plain-HTML primitives (`kit-plain.css`: chips, report pieces, popup body) | 8.2 KB | every surface, second |
58
+ | menu | `@gemboss/ui/menu.css` | `packages/ui/src/menu.css` | the ⋯ menu and its icon button (23/10/2026, moved out of `kit-plain.css`, same rules): part of the core (components, just before `kit-plain.css`, where its rules stood) AND its own file | 0.6 KB | `Menu` imports it, so a surface without the core draws the menu: the admin loads `ui.css` and the shell, never `kit-plain.css` |
58
59
  | shell | `@gemboss/ui/shell.css` | `parts/shell.css` | rail, topbar, main, mobile drawer, the thread rail, topbar slots, base text, page widths (`app-shell.css`) | 5.5 KB | every surface, third |
59
60
  | auth | `@gemboss/ui/auth.css` | `packages/ui/src/auth.css` | the sign-in screen (+ the grid backdrop, 0.30.0) | 2.8 KB | `AuthLayout` & co. import it |
61
+ | auth-extras | `@gemboss/ui/auth-extras.css` | `packages/ui/src/auth-extras.css` | what the sign-in screen gained after the bundle froze (24/10/2026): the panel's screenshot window, "Forgot password?" on the Password row, the place of the row under the card | 0.7 KB | auth.tsx imports it beside auth.css; a plain page links it after auth.css |
62
+ | auth-footer | `@gemboss/ui/auth-footer.css` | `packages/ui/src/auth-footer.css` | `AuthFooter`: theme, language, Help · Terms · Privacy under the sign-in card (24/10/2026) | 0.5 KB | `AuthFooter` imports it (and, through ThemeToggle and LanguageSwitcher, portal.css, theme-dark.css, language-switcher.css) |
63
+ | auth-steps | `@gemboss/ui/auth-steps.css` | `packages/ui/src/auth-steps.css` | `AuthSteps`, `AuthStepActions`, `AuthChoices`, `AuthChips`: a sign-up of several steps (24/10/2026) | 1.0 KB | those components import it, with auth.css |
60
64
  | assistant | `@gemboss/ui/assistant.css` | `packages/ui/src/assistant.css` | the dock and the launcher | 2.2 KB | `AssistantHost`, the launcher import it |
61
65
  | portal | `@gemboss/ui/portal.css` | `packages/ui/src/portal.css` | `TopbarNav`, `SearchDialog`, `Avatar`, `Leaderboard`, `Podium`, the `ThemeToggle` button | 2.1 KB | those components import it |
62
66
  | topnav-fold | `@gemboss/ui/topnav-fold.css` | `packages/ui/src/topnav-fold.css` | `TopbarNav`'s folded menu after the frozen bundle (unreleased): `foot`, `foldAt={760}`, `gb-topnav-unfolded`, the open tab's ellipsis | 0.3 KB | `TopbarNav` imports it (after portal.css) |
@@ -66,6 +70,7 @@ its CSS out of the build with it (`sideEffects`). gzip of the minified file, as
66
70
  | editor | `@gemboss/ui/editor.css` | `packages/ui/src/editor.css` | the editors | 7.9 KB | the `@gemboss/ui/editor` components import it |
67
71
  | editor-repeater | `@gemboss/ui/editor-repeater.css` | `packages/ui/src/editor-repeater.css` | `RepeaterList`: a setting that is a list, as rows | 0.9 KB | `RepeaterList` imports it |
68
72
  | editor-tiles | `@gemboss/ui/editor-tiles.css` | `packages/ui/src/editor-tiles.css` | `ChoiceTiles`: a closed choice of shapes as picture tiles | 0.5 KB | `ChoiceTiles` imports it |
73
+ | editor-insert | `@gemboss/ui/editor-insert.css` | `packages/ui/src/editor-insert.css` | the page editor's insert menu (the + on a picked element) | 0.6 KB | admin `InsertElementMenu` imports it |
69
74
  | reactions | `@gemboss/ui/reactions.css` | `packages/ui/src/reactions.css` | the emoji reactions and their picker | 0.8 KB | `Reactions` / `ReactionPicker` import it |
70
75
  | assistant-engine | `@gemboss/ui/assistant-engine.css` | `packages/ui/src/assistant-engine.css` | the engine picker (chip + Engine/Setup/Status popup) and the bridge notice | 1.9 KB | `EnginePicker` / `EnginePanel` / `BridgeNotice` import it |
71
76
  | chat | `@gemboss/ui/chat.css` + `chat-composer.css` | `packages/ui/src/chat.css`, `packages/ui/src/chat-composer.css` | the chat body, the composer | 3.0 + 0.9 KB | the chat components (0.29.0); a page writing the markup links them |
@@ -82,6 +87,10 @@ its CSS out of the build with it (`sideEffects`). gzip of the minified file, as
82
87
  | progress-ring | `@gemboss/ui/progress-ring.css` | `packages/ui/src/progress-ring.css` | `ProgressRing`: "3 of 5" as a ring (0.43.0) | 0.2 KB | `ProgressRing` imports it |
83
88
  | spot-art | `@gemboss/ui/spot-art.css` | `packages/ui/src/spot-art.css` | `SpotArt`: six brand pictures for pauses and empty states (0.43.0) | 0.4 KB | `SpotArt` imports it |
84
89
  | logo-sheet | `@gemboss/ui/logo-sheet.css` | `packages/ui/src/logo-sheet.css` | `LogoSheet`: one logo as a person judges it, the mark on a checkerboard, the lockup on a light and a dark header, the favicon at its real 32px (unreleased) | 0.5 KB | `LogoSheet` imports it |
90
+ | stage-path | `@gemboss/ui/stage-path.css` | `packages/ui/src/stage-path.css` | `StagePath`: stages that unlock in order, each a card with its number (✓ when done), its count and a thin bar; the current one in ink (unreleased) | 0.7 KB | `StagePath` imports it; a plain-HTML page links it (README "Review pieces") |
91
+ | status-matrix | `@gemboss/ui/status-matrix.css` | `packages/ui/src/status-matrix.css` | `StatusMatrix`: rows × columns of "live / total" cells on the kit table, all live or has drafts (unreleased) | 0.3 KB | `StatusMatrix` imports it; a plain-HTML page links it |
92
+ | translation-row | `@gemboss/ui/translation-row.css` | `packages/ui/src/translation-row.css` | `TranslationRow`: one string under review, source beside target, the checks and the action (unreleased) | 0.6 KB | `TranslationRow` imports it; a plain-HTML page links it |
93
+ | status-list | `@gemboss/ui/status-list.css` | `packages/ui/src/status-list.css` | `StatusList`: a quiet system-health strip, a dot, a name and one sentence each (unreleased) | 0.5 KB | `StatusList` imports it; a plain-HTML page links it |
85
94
  | bundle | `@gemboss/ui/gemboss-ui.css` | `gemboss-ui.css` | core + components + shell + auth + assistant + chat + portal + theme-dark | 21.9 KB | compatibility only (see CHANGELOG 0.23.0) |
86
95
 
87
96
  The core alone is 14.7 KB against 21.7 for the bundle (each part opens with a short header naming the gemboss commit, kept through minify, so a surface serving the parts can still say which commit its CSS is); a list page adds collections (4.6), a sign-in page auth (2.6).
@@ -130,7 +139,7 @@ in order and reversed, and holds every element's computed style to the bundle's
130
139
  CI; negative control: two entries that only agree by order). An entry loaded BEFORE the core is not supported: measured,
131
140
  `.ui-empty--no-match` loses its 32px padding to `.ui-empty`. Two kit-plain.css rules that overrode shell.css by coming
132
141
  after it (the menu row's flex, the thread rail's 44px buttons at phone width) moved to the end of app-shell.css, same
133
- weight, so they still follow it.
142
+ weight, so they still follow it. (The menu row's flex is shell.css's own since 23/10/2026: one owner for the row.)
134
143
 
135
144
  **A new component** gets its own entry: a file in `src/`, listed in `ENTRIES` in `packages/ui/scripts/parts.mjs`, exported,
136
145
  imported by the component that draws it, with a ceiling in `weight-budget.json`. It never goes into the core or into
@@ -142,6 +151,37 @@ component that draws an entry's class without importing it.
142
151
  built part now). Its editor, assistant and sign-in modules already imported the same entry files the components now
143
152
  import, so nothing moves.
144
153
 
154
+ ## ListPage (23/10/2026): the frame of a list page
155
+
156
+ One component for a page that lists one kind of thing (the admin's Rules first; the other lists move one PR at a time):
157
+
158
+ ```tsx
159
+ <ListPage title="Rules" subtitle="12 rules · 9 on." back={{ href: "/app/content", label: "Types" }} linkAs={Link}
160
+ primaryAction={<Button variant="primary">New rule</Button>}
161
+ secondaryActions={[{ content: "Simulator", onAction }, { content: "Export CSV", url: "/export" }]}
162
+ notices={<Banner …/>} toolbar={<ListToolbar …/>}
163
+ state={saved === null ? (unread ? "error" : "loading") : saved.length ? "ready" : "empty"}
164
+ empty={<EmptyStage …/>} noMatch={{ onClear }} error={{ title: "Your rules couldn’t be read.", message, onRetry }}
165
+ cardTitle="Your rules" after={<PlaybookLibrary …/>}>
166
+ {rows}
167
+ </ListPage>
168
+ ```
169
+
170
+ - The page says WHICH state its list is in; the kit draws it, the same on every list: placeholder rows while loading, the
171
+ page's own empty state, "Nothing matches" + Clear filters, a read that failed + Try again. A change that failed over a list
172
+ that IS there is a notice, not the error state.
173
+ - `primaryAction` is the page's own button (so a Publish button that counts changes stays itself). Secondary actions are data:
174
+ two stand as buttons from a 560px page column, the rest are behind ⋯; under 560 or below 768px, all are behind ⋯.
175
+ - `cardLead`: rows at the top of the card in every state, before the state's loading, empty or error (a row that does not
176
+ wait for the list's read, as Funnels' Website). A page with a lead always has its card, so the row stays the same element.
177
+ `card={false}` is for a list that draws its own cards (a grid); `cardProps` stay on the card in every state (a drop zone).
178
+ - `actionGroups`: choices of one kind (a cadence, a view) behind ⋯ at every width, titled, the one that is on `active`; never
179
+ header buttons. The rows are `MenuItem checked` in a `MenuGroup` (`menuitemradio`, a check before the chosen one).
180
+ - Numbers: Polaris Page in the admin (title 20/24/700 on a 28px row, the line under it 12/16 muted 2px below, actions 28px 8
181
+ apart, 24px above and under the header from 768, 16 below). Below 768 the header is two rows and its controls are 44px.
182
+ Colours are Polaris' where Polaris is loaded (`--p-color-text`, `--p-color-text-secondary`, `--p-color-bg-fill-tertiary`),
183
+ the kit's tokens elsewhere.
184
+
145
185
  ## Page width (0.8.1)
146
186
 
147
187
  Chris, 04/10/2026: the rail on the left, and on the right a content column with the same max width on every
@@ -228,6 +268,56 @@ that writes the markup puts `gb-auth-panel--grid` (or `--none`) beside `gb-auth-
228
268
  panel={{ eyebrow: "gemform · GemBoss Ops", heading: "Every Gem registration, in one place." }}>…</AuthLayout>
229
269
  ```
230
270
 
271
+ ### The standard sign-in and sign-up (24/10/2026)
272
+
273
+ Chris's design canvas (24/10/2026) gives GemBoss, GemCommunity and GemBoss Affiliates one sign-in and one sign-up. The
274
+ card keeps its mark, name and tagline, Email, Password, the button, "or" and the GemBoss / Google doors and one switch
275
+ line; four things are new:
276
+
277
+ - **`panel.shot`**: a real screenshot of the product (`{ src, alt, caption?, width?, height? }`) in a white window under
278
+ the panel's words: 12px corners, a 28px bar with three grey dots, a soft shadow. Lazy, so a phone (no panel) never
279
+ downloads it; cropped from the top-left before the panel would cut it; gone under 600px of height. Re-tune it with
280
+ `--gb-shot-bg`, `--gb-shot-bar`, `--gb-shot-line`, `--gb-shot-dot`, `--gb-shot-shadow` on `.gb-auth`.
281
+ - **`PasswordField` `forgot`** (`{ href, label?, onClick? }`, and `AuthSignIn` `forgot`): "Forgot password?" on the
282
+ Password label's row, at its right end. It comes AFTER the field in the page, so Tab goes Email, Password, then the link.
283
+ - **`footer` + `AuthFooter`**: the row at the bottom of the form's column, outside the card: the kit's `ThemeToggle`
284
+ (`followsSystem`, because the screen follows the OS until a choice is made), the kit's `LanguageSwitcher` (the ghost
285
+ `topbar` variant; pass `language.variant` for another), then Help · Terms · Privacy. Every control and link 44 x 44.
286
+ Gone with the keyboard up (under 400px of height). Put `themeScript` in `<head>` so a stored choice is on before the
287
+ first paint; `theme={false}` on a product with no dark theme behind its sign-in.
288
+ - **A sign-up of several steps** (auth-steps.tsx): `AuthSteps` ("Step 1 of 3", the step's name, one segment a step, the
289
+ current one `aria-current="step"`), `AuthChoices` (one answer: radio cards with a title, a line and an iris note; the
290
+ chosen one has a 2px ink edge), `AuthChips` (several answers: checkboxes in 44px pills) and `AuthStepActions` (Back
291
+ beside Continue; Continue is the step form's submit, and on the last step its words say what it sends).
292
+
293
+ ```tsx
294
+ import { AuthChoices, AuthFooter, AuthForm, AuthLayout, AuthSignIn, AuthStepActions, AuthSteps } from "@gemboss/ui";
295
+
296
+ const footer = <AuthFooter language={{ value: lang, onChange: setLang }} help="/help" terms="/terms" privacy="/privacy" />;
297
+
298
+ <AuthLayout brand="GemBoss Affiliates" tagline="Earn 30% for every merchant you bring." backdrop="grid" footer={footer}
299
+ panel={{ eyebrow: "GemBoss Affiliates", heading: "Every sale you send, counted.", body: "Your links, your clicks and what they earned.",
300
+ shot: { src: "/auth/earnings.png", alt: "This month's earnings, day by day", width: 1200, height: 750 } }}>
301
+ <AuthSignIn onSignIn={signIn} forgot={{ href: "/forgot" }} foot={<>Not an affiliate yet? <a href="/apply">Apply →</a></>} />
302
+ </AuthLayout>
303
+
304
+ // A step of the sign-up: one question, Back + Continue.
305
+ <AuthForm onSubmit={(e) => { e.preventDefault(); next(); }}>
306
+ <AuthSteps steps={["Account", "About you", "Payout"]} step={2} />
307
+ <AuthChoices name="role" legend="You join as" value={role} onChange={setRole} options={[
308
+ { value: "affiliate", title: "Affiliate", line: "You share your link with your audience.", note: "30% recurring for 12 months" },
309
+ { value: "agency", title: "Agency", line: "You set up GemBoss for the stores you run.", note: "From 3 client stores" }]} />
310
+ <AuthStepActions onBack={back}>Continue</AuthStepActions>
311
+ </AuthForm>
312
+ ```
313
+
314
+ Their CSS is in three entries of their own (auth.css rides in the frozen bundle, which had no room): the components bring
315
+ them. A plain-HTML page links `auth-extras.css` (and `auth-footer.css`, `auth-steps.css`, `language-switcher.css` when it
316
+ draws those) after `auth.css` and writes the markup each file's header shows; the catalog's "Đăng nhập" section renders
317
+ all of it. `initSignIn()` (auth-signin-plain.js) draws the forgot link from `data-forgot` (`data-forgot-label` for its
318
+ words). The footer's theme button has no plain twin yet (kit-plain.js carries no ThemeToggle): a plain page wires its
319
+ button to `data-theme` and the `gemboss-theme` key itself, or leaves it out.
320
+
231
321
  ## The assistant frame
232
322
 
233
323
  ```tsx
@@ -822,7 +912,7 @@ import { ColorControl, EdgeBox, Field, ImageControl, InspectorGroup, PanelAction
822
912
  | `InspectorGroup` | `.gemboss-ei-grp` › `button.gemboss-ei-gh` (13px / 650, the chevron at its end, `note` as `.gemboss-ei-gh-note`) + the body | `aria-expanded`, `data-open`; closed, CSS hides everything after the header (the body stays mounted; an inline `display` on the body's first element would win over that, so give it a bare wrapper). Controlled (`open` + `onOpenChange`, which receives the NEXT state) or not (`defaultOpen`). `attrs`: `data-*` on the group itself, so a page that finds groups by an attribute needs no wrapper (a wrapper drops the divider between groups). `collapsible={false}`: the schema form's static group, `section.gemboss-ei-group` › `h4.gemboss-ei-grouphead` + `hint`. |
823
913
  | `Field` | `.gemboss-ei-fld` › `label` (13px / 500; `htmlFor`; `labelValue` as `.gemboss-ei-rangeval` at its right edge) · control · `hint` | No label when `label` is undefined / null. `className` (the admin's `togrow`), `style`. |
824
914
  | `Seg` | `.gemboss-ei-seg[role=group]` › `button[aria-pressed][data-value]` (`.on`) | A click hands back the option's value; `label` names the group; `style` on the group. |
825
- | `ColorControl` | `.gemboss-ei-color` › `input[type=color].gemboss-ei-swatch` + text box | The swatch commits on every change; the text box keeps a draft and commits on blur (every blur) or Enter. Anything but a 6-digit hex disables the swatch, with a title saying why (`swatchState`). |
915
+ | `ColorControl` | `.gemboss-ei-color` › `button.gemboss-ei-swatch` + text box | The swatch opens the kit's picker (Popover + ColorPicker), which commits on every pick (a drag at most every 80 ms). The text box keeps a draft, each key sent to `onDraft` for a host that holds unsaved edits, and commits on blur (every blur) or Enter. A value the swatch cannot show (a token, a gradient) disables it and says why under it (`swatchState`). |
826
916
  | `RangeControl` | `input[type=range].gemboss-ei-range` | Every change, as a number (drag, arrows, Home / End). Show the value with `Field`'s `labelValue`. |
827
917
  | `EdgeBox` | `.gemboss-ei-edgebox` › four `.gemboss-ei-edge` (box + T / R / B / L) | `onChange(side, raw)` per keystroke, `onCommit()` on blur; Enter blurs. Boxes named "<label> top / right / bottom / left". `narrow` (default) adds `gemboss-field--narrow`; `placeholders`, `ids` per side. What an empty edge means is the caller's. |
828
918
  | `ImageControl`, `ChipButton` | `.gemboss-ei-img` › 52px thumbnail (— when empty) · URL box · `.gemboss-ei-img-actions` (`actions`, then Clear while there is a value) | Commits on blur / Enter only when the box changed; Clear commits "". The box's text can be the caller's (`draft` + `onDraftChange`) to put a picked URL in it at once. The thumbnail's `url()` is quoted (`cssUrl`, 0.20.1), so a URL with ")" or a space still shows. |
@@ -924,6 +1014,16 @@ gembossUI.initShell(); // AppShell markup written by hand: ☰ drawer,
924
1014
  gembossUI.initPasswordFields(); // the sign-in's reveal button; resetPasswordFields() on sign-out
925
1015
  ```
926
1016
 
1017
+ Menus (23/10/2026): a menu's keys are a SECOND script, `menu-plain.js`, loaded after this one (`<script src>`, inlined, or
1018
+ `import "@gemboss/ui/menu-plain.js"` after the kit-plain.js import): kit-plain.js has no room for them under its weight
1019
+ ceiling. It runs by itself and gives every `details.ui-menu` what the React `Menu` does (README "Menu"): the roles its
1020
+ markup leaves out, the keys on a row (↑ ↓ wrapping past disabled rows, Home End, Escape with focus back on ⋯, Tab leaves;
1021
+ ↓ / ↑ on ⋯ open it), the first row focused on an opening by a click, Enter or Space, one menu open at a time. Without it a
1022
+ plain menu works as before (Tab walks its rows). `initMenus()` (opt-in, as before) closes a menu on a chosen row, now with
1023
+ focus back on ⋯ BEFORE the row's own handler, and on an outside click, the window's blur and Escape from anywhere; a page
1024
+ that never calls it keeps its menus open on a chosen row. Both scripts return at once where there is no DOM, so a Next
1025
+ client module that imports them renders on the server (`plain-ssr.test.ts`).
1026
+
927
1027
  In a bundled app (Next, Vite) load it once with a bare `import "@gemboss/ui/kit-plain.js";` in a client module: the
928
1028
  package lists the file in `sideEffects`, so the bundler keeps it (before 0.5.0 it dropped it and `gembossUI` was
929
1029
  undefined in production builds). Loading it writes nothing on `<html>` (0.37.1): the `data-gb-menus` flag kit-plain.css
@@ -1568,6 +1668,99 @@ import { ChoiceTiles } from "@gemboss/ui/editor";
1568
1668
  rectangle drawn to fit 26px: wide by its width, tall by its height) · `.gemboss-ei-tile-label`. 4 to a row, 56px tall. The caller
1569
1669
  owns the value; a click calls `onChange`. Its own part (`editor-tiles.css`).
1570
1670
 
1671
+ ## Picker grid (24/10/2026): `PickerGrid`
1672
+
1673
+ PickerList's search box and states for things chosen by their picture: the shop's images, an icon library.
1674
+
1675
+ ```tsx
1676
+ import { PickerGrid } from "@gemboss/ui/editor";
1677
+
1678
+ <PickerGrid label="Your images" tiles={tiles} selected={key} onSelect={setKey} onActivate={use}
1679
+ search={{ value: q, onChange: setQ, placeholder: "Search by name" }} state={rows ? "ready" : "loading"} />
1680
+ ```
1681
+
1682
+ - `size="photo"` (default): square pictures 120px wide at least (two to a row at a phone's width), the name and a line at 12/16;
1683
+ `fit: "contain"` and `checker` for a logo or a cut-out. `size="icon"`: a 26px drawing (`picture`) over its name (two lines at most), 88px+, 56px+ tall.
1684
+ - ↓ ↑ move by a row (as many columns as are laid out) to the tile nearest the column in the next row holding a choice; ← → Home
1685
+ End along it. In the search box those three are the caret's until ↓ or ↑ steps into the grid, and again after the next keystroke
1686
+ typed (the WAI-ARIA grid combobox). Enter uses with `onActivate` (else selects), Space and a click select, a double click uses.
1687
+ `status: { busy }` / `{ error }`: an upload shown as a tile, not a choice, announced from live regions outside the grid (an
1688
+ option's children are presentational).
1689
+ - The states and the search box are PickerList's (see below). Its own part (`editor-picker-grid.css`, 1.1 KB gzip).
1690
+
1691
+ ## Picker list (24/10/2026): `PickerList`
1692
+
1693
+ The body of a popup that picks one thing (a link's page or section, a video, a font): Polaris' Combobox over a Listbox. The
1694
+ caller owns the popup (the kit's `Dialog`), any tabs above (`Segmented`), the filtering, and what a pick does.
1695
+
1696
+ ```tsx
1697
+ import { PickerList } from "@gemboss/ui/editor";
1698
+
1699
+ <PickerList label="Sections" current={stored} onPick={write}
1700
+ search={{ value: q, onChange: setQ, placeholder: "Search sections" }}
1701
+ state={failed ? "error" : rows === null ? "loading" : asking ? "reloading" : "ready"}
1702
+ error={{ message: "The page could not be read.", onRetry: reread }}
1703
+ empty={{ title: "This page has no sections yet." }}
1704
+ items={(rows ?? []).map((s) => ({ key: s.href, title: s.title, subtitle: s.href, icon: "layout",
1705
+ note: s.popup ? "Opens the popup" : undefined }))} />
1706
+ ```
1707
+
1708
+ `.gemboss-ei-pick` › `.gemboss-ei-pick-search` (the `gemboss-field` box, a search icon, ✕ Clear search) · `ul.gemboss-ei-pick-list
1709
+ [role=listbox]` › `li.gemboss-ei-pick-row[role=option][aria-selected]` › `.gemboss-ei-pick-media` (an `img`, an empty square, or
1710
+ an icon) · `.gemboss-ei-pick-text` › `.gemboss-ei-pick-head` (`.gemboss-ei-pick-title` + `ui-tag`) and `.gemboss-ei-pick-sub`
1711
+ (`.gemboss-ei-pick-note` that never shrinks, then `.gemboss-ei-pick-rest` cut with "…") · `.gemboss-ei-pick-check`.
1712
+
1713
+ - The box and the list are 12 apart (the dialog's field→field rhythm); rows touch, as the kit Menu's do. A row is 56px:
1714
+ `--ui-space-2` around a 40px picture (the kit thumb), the title on a 20px line at `--ui-fs-body` / 650 and the second line
1715
+ 20px muted (both the kit list's). 8 around, not a list page's 12: a Listbox option, not a ResourceItem. Every number is a
1716
+ `--ui-*` token, so the picker follows the kit's theme.
1717
+ - `note` is what to know before picking ("Draft: opens once it is active"); it comes first on the second line, so the ellipsis
1718
+ takes the path after it, never the note. `disabledReason` shows a row that cannot be picked and says why, in red.
1719
+ - `badge` is a short status as a pill, toned `neutral` · `info` · `success` · `warning` · `critical` (`ui-tag` modifiers).
1720
+ - `picture` is a drawn picture of the caller's (an SVG the kit has no icon for) in the 40px tile; `drill` marks a row that opens
1721
+ a list of its own (the page picker's Products), drawn with a chevron instead of the check; current, it has the chosen row's tint.
1722
+ - `search.autoFocus`: the box takes the focus as the list appears (a popover opening on a picker; a new `key` is a new list).
1723
+ - **One way to open a picker** (24/10/2026). Every picker in the editors opens in the kit's `Dialog` (link, video, font, image,
1724
+ icon) or `Popover` (the page picker, under its trigger), and every one sets `search.autoFocus`: the box carries
1725
+ `[data-autofocus]`, which both containers focus as they open (a `Dialog` without one gives the focus to its ✕). Under a finger
1726
+ (`(pointer: coarse)`) the box does not take the focus by itself: the on-screen keyboard would cover the list. Escape in a box
1727
+ with words clears them; in a list inside a list (the Popover's `onBack`) it steps back, as ← Back; otherwise the container
1728
+ closes and the focus goes back to what opened it.
1729
+ - Keys: ↑ ↓ move the highlight past locked rows, Enter picks; in the box Escape clears the words before the popup closes;
1730
+ with no box the list is one tab stop and Home / End work too. One click picks.
1731
+ - States: `loading` (skeleton rows, a first read), `reloading` (the last answer's rows kept, dimmed and `aria-busy`, nothing
1732
+ pickable from them while the next search is read), `error` (the kit's danger notice, Try again with `onRetry`), no match
1733
+ (Clear search, the focus back in the box), `empty`, `more` (Show more, after the list).
1734
+
1735
+ Its own part (`editor-picker.css`, 1.0 KB gzip).
1736
+
1737
+ ## Popover and the colour picker (24/10/2026): `Popover`, `ColorPicker`
1738
+
1739
+ A setting that needs more room than its row opens a `Popover` beside the settings column, over the canvas, so the column does not
1740
+ grow. `ColorControl`'s swatch opens one holding the `ColorPicker`; nothing else is needed for a colour field.
1741
+
1742
+ ```tsx
1743
+ import { Popover } from "@gemboss/ui/editor";
1744
+
1745
+ <Popover open={open} anchor={rowRef.current} returnTo={buttonRef.current} title="Shadow" onClose={() => setOpen(false)}>
1746
+ …the setting's controls…
1747
+ </Popover>
1748
+ ```
1749
+
1750
+ - Placed beside the column the anchor scrolls in (its nearest vertically scrolling ancestor), on the side with room (right first),
1751
+ its top at the anchor's row and kept on screen; neither side has room: under the anchor. Placed again on a scroll or resize outside
1752
+ it. At phone width (`max-width: 47.9975em`) a sheet along the bottom.
1753
+ - `placement="below"`: under the anchor instead, from its left edge (a menu from a top bar, the editor's page picker). The sheet at
1754
+ phone width is the same.
1755
+ - Head: title (13/20/650), ← Back with `onBack` (a nested panel), ✕; 28px buttons under a mouse, 44 under a finger.
1756
+ - Escape steps back in a nested panel (`onBack`, as ← Back; the focus stays inside), else closes it and goes no further; a press
1757
+ outside it and its anchor closes it; the focus goes in (`[data-autofocus]`, else the
1758
+ layer) and back to `returnTo` (else the anchor) on Escape or ✕.
1759
+ - The `ColorPicker`: square (pointer and keys), hue, opacity, hex box, eyedropper (`EyeDropper`), Theme / Recent (`ColorChoice.group`),
1760
+ None. A pick keeps the value's alpha and format (`pickSwatch`); a drag writes at most every 80 ms and once at its end.
1761
+
1762
+ Their own parts: `editor-popover.css` (0.6 KB gzip), `editor-color.css` (1.2 KB gzip, the swatch button too).
1763
+
1571
1764
  ## Resizable panels
1572
1765
 
1573
1766
  `ui-resizer` is the seam a person drags between two panels; `ui-resizing` on `<body>` is the drag in
@@ -1663,9 +1856,23 @@ import { AppShell, BrandLockup, AccountMenu, AccountMenuItem, Icon, RailItem } f
1663
1856
  outranks an attribute on the `<svg>` itself and paints an outline icon solid.
1664
1857
  - `Menu` / `MenuItem` / `MenuSeparator` (0.2.1): the "⋯" action menu. Same `<details>` rule as the account
1665
1858
  menu (works as plain markup; with React it closes on an outside click, on Escape with focus back on the
1666
- trigger, and after a button row's handler). Rows share the account menu's row style. `MenuItem` is a link
1667
- (`href`) or a button; `disabled` on a link drops the href and sets `aria-disabled`; `className` is added
1859
+ trigger, and after a row is chosen). Rows share the account menu's row style. `MenuItem` is a link
1860
+ (`href`, `target`, `rel`) or a button; `disabled` on a link drops the href and sets `aria-disabled`; `className` is added
1668
1861
  to the row's class.
1862
+ A menu (23/10/2026, `menu-keys.ts`, shared with `LanguageSwitcher`; `menu-plain.js` after kit-plain.js for plain markup):
1863
+
1864
+ | | |
1865
+ |---|---|
1866
+ | Semantics | the list is `role="menu"` named by `label` (the trigger's name), the trigger `aria-haspopup="menu"`, each row `role="menuitem"` with `tabindex="-1"`: the arrows move between rows, Tab does not |
1867
+ | Opening | a click, Enter or Space on ⋯ puts focus on the first row that can act; ↓ on ⋯ opens on the first, ↑ on the last; a script's `open = true` moves no focus |
1868
+ | Keys | on a ROW (a field or a checkbox in the list keeps its own): ↑ ↓ wrap and skip disabled rows (`disabled`, `aria-disabled="true"`); Home / End; Enter and Space act on the row (Space on a link row too); Escape closes with focus back on ⋯ and is taken (a popup around the menu stays open); Tab / Shift+Tab close it and focus goes on from ⋯ |
1869
+ | Choosing | focus goes back on ⋯ BEFORE the row's handler (a popup it opens returns focus there, not to a hidden row; a handler that moves focus on purpose keeps it), then the menu closes, link rows included. Plain markup: with `initMenus()`, opt-in as before |
1870
+ | One open | opening a menu closes every other open `details.ui-menu`, by a click, a key or a script (a key is not a click outside); a menu that holds the one opening (a menu in a menu, a kit menu in the account menu) stays open |
1871
+ | Listeners | one page-wide set for every mounted `Menu` (`registerMenu`): outside click, Escape, the float on its toggle, one open. A 100-row table has 100 Menus and one set of listeners, not 200 |
1872
+ | In a row that opens on click | `IndexTable` rows with `href` and `tr[data-href]` leave the menu be: opening, moving and choosing never follow the row |
1873
+ | CSS | `menu.css`, imported by `menu.tsx`: placement, the floated list, hint, separator, disabled row, the square ⋯ (`ui-btn--icon`). The surface and the row are shell.css's (which the admin loads too): `.ui-menu__item` a flex row (label, then the hint on the right; the account menu's `.gemboss-account-menu-item` stays a block), 32px under a mouse, 44 under a finger or below 768. So a page with `ui.css` + `shell.css` + `menu.css` and no `app-shell.css` (the admin), in either order, draws what the core draws |
1874
+
1875
+ `menu-browser.test.ts` runs each of these on `Menu` and on plain markup with kit-plain.js, each with a negative control.
1669
1876
 
1670
1877
  ## Topbar search (0.6.3)
1671
1878
 
@@ -1759,6 +1966,12 @@ import { Avatar, Dialog, Leaderboard, Podium, SearchDialog, ThemeToggle, themeSc
1759
1966
 
1760
1967
  ## The public site layer (0.40.0): `SiteHeader`, `SiteBrand`, links, buttons, footer
1761
1968
 
1969
+ **Deprecated (24/10/2026).** Public websites now use **`@gemboss/website-ui`** (source: [packages/website-ui](https://github.com/chriskoh26/gemboss-www/tree/main/packages/website-ui) in
1970
+ chriskoh26/gemboss-www, published on npm): the whole site kit (tokens from one `system.json`, header with the mega
1971
+ menu, footer, sections, the rules Claude Code follows in `AGENTS.md`, and a CLI that checks a site and reports gaps).
1972
+ Chris chose it on 24/10/2026 so GemPages, Gemians and every other GemCommerce website follow one kit. This layer stays
1973
+ until the pages still on it (news.gemboss.ai, the community home) move over; do not adopt it on a new page.
1974
+
1762
1975
  **Which layer.** A PUBLIC page (gemboss.ai, the docs, news, a product's home page before sign-in) uses this layer. An APP
1763
1976
  surface (the admin, a portal behind sign-in, GemFeedback's board) keeps `Topbar` + `BrandLockup`. Chris 20/10/2026: "có gemboss
1764
1977
  ui thì có gemboss website ui"; measured the same day, the public pages had drifted on the same detail: the logo name 18px on
@@ -2602,6 +2815,41 @@ thumb and at phone width.
2602
2815
  ]} />
2603
2816
  ```
2604
2817
 
2818
+ ## Review pieces (unreleased, after 0.49.0): `StagePath`, `StatusMatrix`, `TranslationRow`, `StatusList`
2819
+
2820
+ GemPress's redesign (Chris approved it 23/10/2026) drew four things with its own CSS (`gp-unlock`, `gp-cov`, `gp-str`, `gp-sys`)
2821
+ that are not about GemPress: a path of stages that unlock in order, a map of "how much is live" per row and column, one string
2822
+ under review, and a strip of system health. GemNews and GemCommunity translations review the same way, and every service has a
2823
+ health line to show, so they live here. Each is its own entry, presentational and server-renderable (no state, no effect, no
2824
+ inline style), painted by tokens (the dark palette follows), and usable from plain HTML: link `@gemboss/ui/<name>.css` beside the
2825
+ core and write the classes listed at the top of that file. The tests hold those lists to the components' markup.
2826
+
2827
+ | Piece | What it draws |
2828
+ | --- | --- |
2829
+ | `StagePath` | `stages` (`{ key, name, done, total, unit?, href? }`) as an `<ol>` of cards in a grid (`repeat(auto-fit, minmax(190px, 1fr))`): a number badge (a green ✓ once `done >= total`; a stage with nothing in it is done), the name (a link when `href`, the whole card its target), "3 / 35 pages approved" and a thin `<progress>` bar (hidden from a screen reader: the words say it). `current` (default the first stage not done, `null` for none) has an ink outline and an ink number, and is `aria-current="step"`. `label` names the list (default "Unlock path"); `caption` and `format` make the words the surface's. `stagePathDone` is the rule, pure. |
2830
+ | `StatusMatrix` | the kit table (`ui-table-wrap` + `ui-table`) with `columns` across and `rows` down, each row's name its `th scope="row"` (a link when `href`). A cell is "**live** / total" with a second line for what waits ("5 draft · 2 changed", "3 missing"); its tone is all live (green number) or has drafts (amber number), never colour alone. A `null` or absent cell, or a row whose `total` is 0, is "—". `rowHeading`, `totalHeading` (a column of the rows' totals, e.g. the source language), `caption` (what the numbers mean, under the table), `format`, `labels`. `statusMatrixTone` is the rule, pure. |
2831
+ | `TranslationRow` | one string: a head (`keyName` in code, `state` as a kit badge: `draft` "To review", `approved`, `stale` "Source changed", `missing` "Not translated"; `by`), the `source` beside the `target` (two columns; one under 900px, or when the row is narrower than 600px: it is a size container), and a foot with `checks` (`{ ok, text }`: a green "✓ …" or the problems in amber words) on the left and the surface's `action` on the right. The editable control is the surface's: `target` is a node, or a function given the ids of the key, the source and the checks so the field can say `aria-describedby`. `current` draws an ink border and a 3px ink bar inside the left edge (`aria-current`). The row is `tabIndex={-1}`: a J / K list moves focus to it (pass `id`, or find it by `data-*` the row passes through), and it is never a Tab stop. `as="li"` inside an `<ol>`. |
2832
+ | `StatusList` | `items` (`{ key, label, text, tone, href? }`) as a grid (`repeat(auto-fill, minmax(260px, 1fr))`): a dot, a bold name, one muted sentence (a link when `href`). `ok`, `warning`, `critical` fill the dot with the success, warning and danger tokens; `muted` is an empty ring (off, not applicable); an unknown tone is muted. |
2833
+ | `stage-path.css`, `status-matrix.css`, `translation-row.css`, `status-list.css` | one entry each, loaded by its component; `status-matrix.css` needs the core's table (`ui.css`), and `TranslationRow`'s badge tones are the core's (`kit-plain.css`, in `components.css`) |
2834
+
2835
+ **Quiet when fine, a banner is for when a person must act.** The status list is the line a page ends on: nothing in it asks for
2836
+ anything. Something a person must do today goes in a `ui-banner` above the page, not in an amber dot at the bottom of it.
2837
+
2838
+ ```tsx
2839
+ import { StagePath, StatusMatrix, TranslationRow, StatusList } from "@gemboss/ui";
2840
+
2841
+ <StagePath label="Unlock path" stages={[
2842
+ { key: "frame", name: "Header & footer", done: 2, total: 2, unit: "parts" },
2843
+ { key: "pages", name: "Pages", done: 3, total: 35, unit: "pages", href: "#/review?stage=pages" },
2844
+ ]} />
2845
+ <StatusMatrix rowHeading="Collection" totalHeading="EN" caption="Live / published." columns={[{ key: "vi", label: "VI" }]}
2846
+ rows={[{ key: "pages", label: "Pages", total: 35, cells: { vi: { live: 30, draft: 5, changed: 2 } } }]} />
2847
+ <TranslationRow as="li" id="vi-hero" keyName="hero.title" state="draft" source="Ship in 3 days" sourceLang="en" by="gpt-4o" current={at === 0}
2848
+ target={(ids) => <textarea className="ui-textarea" lang="vi" aria-describedby={`${ids.source} ${ids.checks}`} value={text} onChange={…} />}
2849
+ checks={{ ok: true, text: "Numbers and tags match" }} action={<button className="ui-btn ui-btn--sm" onClick={approve}>Approve</button>} />
2850
+ <StatusList label="System" items={[{ key: "backups", label: "Backups", text: "nightly · last 22 Oct", tone: "ok", href: "#/settings" }]} />
2851
+ ```
2852
+
2605
2853
  ## Collections (0.13.0): tables, lists, grids, boards
2606
2854
 
2607
2855
  Chris settled these on 05/10/2026 after an inventory of 136 hand-made collections on 11 surfaces (86 tables scrolling
@@ -2643,17 +2891,28 @@ the admin's first load (`kit-plain-bundles.test.ts` checks the shell import carr
2643
2891
 
2644
2892
  ### The rules, and what checks them
2645
2893
 
2894
+ - **One header for both tables (23/10/2026).** An index table's header is the data table's: the surface, 13px regular, 12px
2895
+ above and below (45 tall), opaque so the sticky headers hide what scrolls under them; its cells 8px 6px. The index table
2896
+ takes these from the data table's rules (ui.css), so the two cannot drift. Polaris draws an index header as a grey 12px /
2897
+ 550 band over 6px cells; the admin's unselectable Polaris IndexTables (all of them on 23/10/2026) take the kit's instead
2898
+ (gemboss-shell.css, #5185).
2899
+
2646
2900
  - **The whole row opens the item; the title stays a real link** (Cmd-click, a screen reader). A click on a checkbox, a
2647
2901
  button, the ⋯ menu, a select or a second link does only that; so does a click that ends a text selection. A row with
2648
2902
  two or more in-place editors is not linked (only its title is). HTML: `tr[data-href]` + kit-plain.js; React:
2649
2903
  `IndexTable` rows with `href`; a resource list's title link covers its row (no script).
2904
+ - **The referrer is the page's to set, not the row's.** A row opens with `noopener` and the browser's default policy
2905
+ (`strict-origin-when-cross-origin`): another site learns this site's origin, never the path. A surface whose rows open
2906
+ other sites and must send nothing sets it once for every link: `Referrer-Policy: same-origin` (header) or
2907
+ `<meta name="referrer" content="same-origin">`. Per-link `noreferrer` in the kit was tried (#5176, then #5180's first
2908
+ draft) and dropped: it missed ways in (a Cmd-click straight on the title is the browser's) and every other link type.
2650
2909
  - **One visible button per row at most**, the rest in the ⋯ menu (`ui-menu`). **Never shown only on hover.**
2651
2910
  - **An open ⋯ menu is never cut by its frame (0.18.0).** It floats in the browser's top layer (`popover="manual"`,
2652
2911
  `position: fixed` against its button): below the button, above it when the room below is short and the room above is
2653
2912
  larger, 8px from the viewport's edges, scrolling inside when taller than the room. It closes when a scroll moves its
2654
2913
  button (the page, or a frame around the menu) or the window resizes; a scroll inside the list or elsewhere (a log
2655
- following its output) does not count. Tab order, Escape (focus back on ⋯) and "a click in the
2656
- menu is not a click on the row" are unchanged: the list is still the details' child. React `Menu` does it itself;
2914
+ following its output) does not count. The keys (README "Menu", 23/10/2026: arrows, Escape with focus back on ⋯) and "a
2915
+ click in the menu is not a click on the row" are unchanged: the list is still the details' child. React `Menu` does it itself;
2657
2916
  plain HTML gets it from kit-plain.js (`initMenuLayer()`, runs by itself). No popover API (Safari < 17) or no script:
2658
2917
  the absolute list, as before. GemFactory Members (#197) is the case: at 820 / 900 / 1280 the last rows' menus were
2659
2918
  half hidden inside the table's scrolling frame.
@@ -2667,7 +2926,8 @@ the admin's first load (`kit-plain-bundles.test.ts` checks the shell import carr
2667
2926
  activity's detail wrap instead of ending in "…", because the cut text's `title` is mouse-only. A side rail of short
2668
2927
  labels keeps one line. `CompactItem.body` (activity only) is the event's own text under them (`.ui-list__content`,
2669
2928
  body size, never cut; paragraphs as `<p>`); `labelText` puts the full label in `title`.
2670
- - **Below 768 of its container an index table becomes a list** (title line; the other cells on one caption line,
2929
+ - **Below 768 of its container an index table becomes a list** (title line: a linked title is cut, an unlinked one and free
2930
+ text under it wrap, a long token breaks; the other cells on one caption line,
2671
2931
  `data-label` prefixes, `data-condensed="hide"` drops; checkbox and actions kept; rows ≥ 44); sort moves to the chips
2672
2932
  of `ui-index__sortbar`. **A data table never folds:** it scrolls in its frame with `--sticky-first`.
2673
2933
  - **A data table reads from the top of its rows (0.16.0)**, as Polaris DataTable (`verticalAlign` "top"): one-line
@@ -2678,7 +2938,8 @@ the admin's first load (`kit-plain-bundles.test.ts` checks the shell import carr
2678
2938
  `minWidth` (DataTable) is the floor of a column whose cells wrap, and replaces the row header's (`0` for a row
2679
2939
  header that is always short: a date, an id). A link alone on its
2680
2940
  line is 24px in the row header and in a list inside a cell (`li > a`), as `td > a` already was.
2681
- - **A data table in a card is `flush` (0.34.0)**, as a resource list in a card: the card is the frame, so the wrap drops its
2941
+ - **A data table or an index table in a card is `flush`** (DataTable 0.34.0; IndexTable unreleased, its bulk bar
2942
+ then lies on the card's top edge), as a resource list in a card: the card is the frame, so the wrap drops its
2682
2943
  own border, radius and shadow (two frames otherwise). The last row has no bottom rule, row header included. The card
2683
2944
  clips its corners (`overflow: hidden`, as GemWatcher's Panel): the last row's hover, the totals and the footer are square.
2684
2945
  - **A media card is 16:10, 4:3 or 1:1 (0.18.0)** (`MediaCard ratio`, `data-ratio="4/3" | "1/1"`): 1:1 for a square
@@ -2766,6 +3027,11 @@ gap. Under 576px only Previous · the current page · Next stay and the range wr
2766
3027
  took three to four rows at 320). The old form `<span aria-current="page">2 / 9</span>` keeps its muted look. The surface computes which numbers to
2767
3028
  show (first, last, current ± 1, a gap only where it hides two or more pages: GemFactory `pageWindow`).
2768
3029
 
3030
+ React: `<Pager page pageCount range href={(n) => \`?p=${n}\`} linkAs={Link} />` draws that markup (`pageWindow` is exported
3031
+ too). A list that pages in STATE (its search and filters not in the URL, as the admin's Products) passes `onPage` instead of
3032
+ `href` and gets buttons with the same look (pager-extras.css), Previous / Next marked `data-rel`; `busy` while a page is on its
3033
+ way. The rules are `pager.css` (in the core, moved out of kit-plain.css 24/10/2026 with Chris's OK) and `pager-extras.css`.
3034
+
2769
3035
  `ui-more`: one centred row. Idle: a `ui-btn` ("Show 24 more"). Loading: `<span class="ui-spinner" aria-hidden="true">` +
2770
3036
  `<span role="status">Loading…</span>`. Error: `<span role="alert">Couldn't load.</span>` + "Try again". End: a line. As an
2771
3037
  IntersectionObserver sentinel it has height from its padding; zero the padding and it has none.
@@ -2817,10 +3083,12 @@ something the base cannot express, add a token or a prop here, and every surface
2817
3083
  | Path | What |
2818
3084
  |---|---|
2819
3085
  | `parts/core.css`, `parts/components.css`, `parts/shell.css` | 0.23.0: the core, built by `packages/ui/scripts/build-css.mjs` from the same sections as `gemboss-ui.css` (see "Load only what you use"). |
2820
- | `gemboss-ui.css` | built at stage time and shipped minified (0.19.0); since 0.23.0 the COMPATIBILITY BUNDLE, frozen: `apps/admin/scripts/export-ui-css.mjs` (tokens + kit + field + `packages/ui/src/shell.css`, with Polaris `--p-*` resolved to their fallbacks) + `packages/ui/src/app-shell.css` + `auth.css` + `assistant.css` + `kit-plain.css` + `chat.css` + `chat-composer.css` (`packages/ui/scripts/build-css.mjs`) |
3086
+ | `gemboss-ui.css` | built at stage time and shipped minified (0.19.0); since 0.23.0 the COMPATIBILITY BUNDLE, frozen: `apps/admin/scripts/export-ui-css.mjs` (tokens + kit + field + `packages/ui/src/shell.css`, with Polaris `--p-*` resolved to their fallbacks) + `packages/ui/src/app-shell.css` + `auth.css` + `assistant.css` + `menu.css` + `kit-plain.css` + `chat.css` + `chat-composer.css` (`packages/ui/scripts/build-css.mjs`) |
2821
3087
  | `packages/ui/src/shell.css` | the SHARED SHELL (rail, topbar, main, mobile drawer, the assistant's thread rail, popover surface, account chip). Exported as `@gemboss/ui/shell-source.css` since 0.23.0 (`@gemboss/ui/shell.css` is the built part). The admin's `gemboss-shell.css` @imports it on line 2; the export refuses a shared-shell rule in the admin's sheet or an admin-only rule here (one owner). |
2822
- | `packages/ui/src/kit-plain.css` | primitives for surfaces that render plain HTML, not React (0.2.1): menu, key/value list, icon button; 0.3.0 adds `ui-link` / `ui-prose`, the media card (`ui-card--media`, `__media`, `__body`, `__foot`) and the popup's `ui-modal__body` / `__foot`. Shipped inside `gemboss-ui.css`; the admin does not import it (its first-load CSS budget has ~0.1 KB headroom).; (0.4.0) report pages: delta, large KPI grid, bar list, column chart, legend, funnel, card grid, section head. |
2823
- | `packages/ui/src/kit-plain.js` | 0.3.0: the behaviour those surfaces each wrote by hand: `gembossUI.openModal` (Escape, backdrop, Tab trap, stacking, ask-before-close, focus back), `toast` (text, error tone), `initMenus` (outside click, item, blur, Escape closes the menu before the popup); 0.5.0: `confirm`, `initShell`, `initPasswordFields` / `resetPasswordFields`. A classic script: inline it or `<script src>`; see "Plain-HTML behaviour" above. |
3088
+ | `packages/ui/src/menu-plain.js` | 23/10/2026: `gembossUI.initMenuKeys()`, a menu's roles and keys and one menu open at a time for plain HTML (`@gemboss/ui/menu-plain.js`), the same as `menu-keys.ts`. After `kit-plain.js`; runs by itself. See "Plain-HTML behaviour". |
3089
+ | `packages/ui/src/menu.css` | 23/10/2026: the ⋯ menu and its icon button, moved out of `kit-plain.css` (same rules, same order in the core). Imported by `Menu`; see "Menu". |
3090
+ | `packages/ui/src/kit-plain.css` | primitives for surfaces that render plain HTML, not React (0.2.1): key/value list (the menu and the icon button are `menu.css` since 23/10/2026); 0.3.0 adds `ui-link` / `ui-prose`, the media card (`ui-card--media`, `__media`, `__body`, `__foot`) and the popup's `ui-modal__body` / `__foot`. Shipped inside `gemboss-ui.css`; the admin does not import it (its first-load CSS budget has ~0.1 KB headroom).; (0.4.0) report pages: delta, large KPI grid, bar list, column chart, legend, funnel, card grid, section head. |
3091
+ | `packages/ui/src/kit-plain.js` | 0.3.0: the behaviour those surfaces each wrote by hand: `gembossUI.openModal` (Escape, backdrop, Tab trap, stacking, ask-before-close, focus back), `toast` (text, error tone), `initMenus` (outside click, item with focus back on ⋯ first, blur, Escape closes the menu before the popup); 0.5.0: `confirm`, `initShell`, `initPasswordFields` / `resetPasswordFields`. A classic script: inline it or `<script src>`; see "Plain-HTML behaviour" above. |
2824
3092
  | `packages/ui/src/collections.css` | 0.13.0: tables, lists, grids, boards and their states (see "Collections"). A separate entry, NOT inside `gemboss-ui.css`; the admin does not load it. |
2825
3093
  | `packages/ui/src/editor/` | 0.14.0, `@gemboss/ui/editor`: `EditorFrame`, `EditorPaneTabs`, `EditorTopbar`, `EditorBack`, `EditorChatToggle`, `EditorSaveState`, `DeviceToggle`. See "Editor frame". 0.17.0: `PanelTabs`, `PanelHeader`, `PanelAction`, `InspectorGroup`, `Field`, `Seg`, `ColorControl`, `RangeControl`, `EdgeBox`, `ImageControl`, `ChipButton`, `swatchState` (`./editor/swatch` too); 0.20.1 `cssUrl`. See "Settings panel". 0.22.0: `LayerList`, `SortableLayerList`, `LayerTree`, `EditorDrawer`. See "Layers and drawer". |
2826
3094
  | `packages/ui/src/editor-plain.js` | 0.14.0: `gembossUI.initEditorFrame()`, the frame's behaviour for plain HTML; 0.17.0: `gembossUI.initEditorPanel()`, the settings panel's. Load after `kit-plain.js`. |