@gemboss/ui 0.60.0 → 0.63.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,141 @@ Versions up to 0.9.0 are described in the README, each in the section that intro
4
4
 
5
5
  ## Unreleased
6
6
 
7
+ ## 0.63.0 (08/11/2026)
8
+
9
+ **Skills pages, as content-radar drew them** (found switching content-radar to these parts, its before and after rendered side
10
+ by side): the QA judge chip is purple (`#f1ebfd` / `#5b2fc0`: the tokens it named are the ink and a grey); a tab group's
11
+ current page keeps its underline; a section's action link ("Source file") is 24px on a finger; only a Markdown table the
12
+ surface did not wrap scrolls itself (`.ui-skilldoc__md > table`), so a wrapped one keeps its full width.
13
+
14
+ - `useKeyedRows` (07/11/2026): a stored list is compared with our writes in one key order (`spelled`), so a write the store answers in its own spelling (Postgres JSONB orders an object's keys by length) is that write coming back. Read as a change from elsewhere, it dropped the newer write still on its way: of two quick Adds in the page editor's elements fold, one was lost.
15
+
16
+ **Skills pages** (07/11/2026, Chris: the Skills pages of GemBoss admin and content-radar draw from one kit). Content-radar's Skills
17
+ pages, taken into the kit so GemBoss admin and content-radar draw the same parts. Links go through `renderLink: SkillLinkRender`
18
+ (next/link, a PendingLink or a plain `<a>`), so the parts need no router and render on the server.
19
+ - `skill-pages.css` (new entry): `SkillsTabs` (Skills · Rules · Building blocks; a tab may be a group with a menu), the Rules book
20
+ (`SkillRuleSummary` counts, `SkillRuleSection`, `SkillGuardGroups` a card per group, `SkillCheckTable` with `wide: "rule" | "check"`,
21
+ `SkillRuleChip`, `SkillRuleLevel`) and Building blocks (`SkillLayerList`, `SkillDocJump`, `SkillDoc`, `SkillDocHistory`). On a coarse
22
+ pointer or a narrow screen its controls are 44px and its list links 24px. A section's link in a `.ui-tabs` row may be
23
+ `aria-current="true"` (drawn as current, rule in this entry: gemboss-ui.css is frozen).
24
+ - `skill-feedback.css` (new entry): `SkillFeedbackList` (rows of badges, who, aside, a quote, a body, fine print, actions),
25
+ `SkillFeedbackBar`, `SkillFeedbackHead`.
26
+ - `skill-history.css` (new entry, 05/11/2026): `SkillVersionList`, `SkillDiff`, `SkillChangeCard`, a skill pack's History.
27
+ - `SkillRuleHoldChip` (skill-view.tsx): the chip saying how a rule is held, one owner for `SkillRuleList` and the Rules book.
28
+
29
+ - `report-charts.css` (06/11/2026, Chris's OK): `ui-barlist`, `ui-chart` and `ui-legend` move out of `kit-plain.css` to their own entry just before it in the core, the same rules in the same order, so an admin page can import them. Plain-HTML surfaces load what they did.
30
+
31
+ **Gem at work** (05/11/2026, ADR 0013): `createGemAtWork`, what Gem is doing drawn on the page it is doing it to: Gem's crew (Gem
32
+ and six experts, each an arrow and a name), a ring naming the block, the box dragged at its real size, the words written into the
33
+ block itself, sections a build adds stacked as soft cards in the page's column (the page makes room for them, so its footer moves
34
+ down), and `reveal(ids?)` building the saved sections in, two or three of the crew at once each dragging a block's box out, a
35
+ picture coming up through its tint. The calm clock draws each step long enough to be seen and words at reading pace, trailing Gem
36
+ but never leading it (`clock: "live"` for each activity as it arrives; `idle()` resolves once it has caught up). `catchUp(activities)` draws a turn's
37
+ past at once with nothing moving, for a frame that joins mid-turn (the person switched between Page and Canvas). It reads only the
38
+ activity contract v1 (`GemActivity`, exported here as the contract's one body), finds blocks by `data-gem-el-id` /
39
+ `data-gem-section-id`, steps down a ladder it reports through `onFallback`, and puts back every word and style it touched. Only
40
+ transform, opacity and clip-path move. New entry `gem-at-work.css`; browser test `gem-at-work-browser.test.ts` (in `test:ui-browser`).
41
+
42
+ **One settings frame** (one settings frame slice 1, 06/11/2026; Chris found three frames around one set of settings controls). The
43
+ element panel's frame is the standard, taken out of the admin's ElementNodePanel into the kit as it was (same classes' rules, same
44
+ markup, its own part):
45
+
46
+ Added
47
+ - `InspectorFrame` (`@gemboss/ui/editor`, `editor/inspector-frame.tsx`): `div.gemboss-ei-frame[data-settings-frame]` (display: contents)
48
+ › the host's head › `InspectorSearch` › the index of clusters (`nav.gemboss-ei-index[data-settings-index]`, Look · Layout · Visibility ·
49
+ Code, one press to each, the one the panel stands in marked as it scrolls) › an aside › the lead › each cluster's name
50
+ (`InspectorClusterBreak`, `[data-panel-cluster]`) and its groups. A search's results take the place of the index, the lead and the clusters.
51
+ - `InspectorFrameGroup`: a group in one of three states, one element for the three (a chip pressed keeps its place and the focus):
52
+ `open` (its name), `add` (its name and a +, a pill when marked `chip` in an `InspectorChips` run), `added` (its rows, a −, small actions).
53
+ - `INSPECTOR_CLUSTERS`, `InspectorSearch`, `InspectorClusterBreak`.
54
+ - `InspectorFrame` `searching`: a search shown in place (the index and the clusters' names hidden, the lead kept, nothing drawn again), and
55
+ `InspectorFramePart`: a part that is not a group (a section's words), in its place, `hidden` while a search does not find it.
56
+
57
+ Changed
58
+ - `InspectorGroup` `collapsible={false}` inside an `InspectorFrame` is the frame's open group (`.gemboss-ei-grp` › `.gemboss-ei-openhead`),
59
+ decided by InspectorGroup itself (`editor/frame-context.ts`); outside a frame it is the form's static group as before.
60
+ - Its own part `editor-inspector-frame.css` (0.9 KB gzip, ceiling 1,351 B): only a surface that draws the frame loads it.
61
+
62
+ **Where a label goes is its control's, in one table** (Chris 04/11 and 05/11/2026: label left, control right for every one-value
63
+ setting, as GemPages; only a long text, a list, a spacing box, media, a gradient's editor or a drawing under its label). Measured before:
64
+ 98 hand-built labelled rows in 30 admin files, each deciding its side; every label on the wrong side was in one of them
65
+ (`_local/gemboss/label-beside-audit-2026-11-05.md`).
66
+
67
+ Added
68
+ - `LABEL_SIDE`, `labelSide(control)`, `isFieldControlKind`, `FieldControlKind`, `LabelSide` (`@gemboss/ui/editor`, `editor/label-side.ts`, no
69
+ React): the one table. A one-line text box, a link and a date are beside their label now, as a list is; a line of code (`code`) is
70
+ above. `screens` and `font-pick` are above until those controls are reworked (three device glyphs; the font as a list).
71
+ - `Field` `control`: the control the field holds; its label goes on that control's side. `row` is deprecated (kept for a surface pinned
72
+ to an older kit; ignored when `control` is given).
73
+
74
+ Changed
75
+ - **Layout change for any surface that sets `row` (or a `--row` class) outside an inspector group:** the row CSS is no longer scoped
76
+ to `.gemboss-ei-grp` / `.gemboss-ei-group`. A `.gemboss-ei-fld--row` is laid out as a row (label 2 parts, control 3) wherever it is,
77
+ at the same specificity as the scoped rules. Before, outside a group it drew its label above (the admin's page settings drawer: Store
78
+ header, Store footer, Font loading asked for a row and stacked).
79
+ - A row's notes (`.gemboss-ei-hint` children: its help, a limit or a count, what a link opens) run across the field under the row
80
+ instead of the control column, outside a group and inside one alike (a group's help shows there once its ? is pressed).
81
+
82
+ Removed
83
+ - `.gemboss-ei-addrow`: nothing has drawn it since gemboss #5042 (searched gemboss, gemfactory, gemcare, gempress, gemlabs,
84
+ gemcommunity on 05/11/2026). Removing it keeps `editor.css` under its weight ceiling with the rules above (8,733 → 8,719 B gzip,
85
+ ceiling 8,730).
86
+ - `.gemboss-ei-range` has no side margins: a full-width slider in a row ran 2px past its field.
87
+
88
+ ## 0.62.0 (05/11/2026)
89
+
90
+ **A section that opens as an app of its own: the rail folds to its icons, and the section brings its own grey nav** (Chris 05/11/2026:
91
+ "vào plugin co sidebar menu lại thành dạng thanh icon … để toàn bộ không gian cho plugin", "mọi plugin nên tổ chức như cách bạn tổ chức cho
92
+ gempersonalizer … visual ko đánh nhau với thanh icon"; canvas https://claude.ai/artifact/Hsou4RYohWWXpzv1jHbtYZ, direction A). Not
93
+ published: the admin reads the workspace package; publishing for other surfaces is Chris's call.
94
+
95
+ Added
96
+ - `railMode` on `AppShell` and `Shell` (`"full"` | `"mini"`, type `RailMode`): `mini` puts `data-rail="mini"` on the shell and, from
97
+ 761px, folds the rail to 56px of icons (32px rows under a mouse, 44 under a finger, as the page editor's closed rail), `main` and the
98
+ holding cover start at 56, and so does Gem full screen or pinned below 1100. A `RailItem` with a label in words takes it as `title`
99
+ and `aria-label` (not the `aria-label` when a count follows it, so the count stays in its name); the label stays in the markup, out
100
+ of sight, shown beside the rail on keyboard focus. `RailCount` is a dot, its count in its `aria-label`. Sub rows and headings go;
101
+ the phone's drawer is the full rail. `full`, the default, adds nothing to the markup. Its own entry, `@gemboss/ui/rail-mini.css`,
102
+ brought by `AppNav`.
103
+ - `AppNav` (`identity`: icon, name, status, `tone`; `groups[{ heading?, items[{ label, href, current?, count?, badge?, badgeLabel? }] }]`;
104
+ `foot`; `onSwitch` / `switchMenu` / `switchLabel` / `switchHeading`; `linkAs`; `onItemClick`), `AppNavLink` (a foot row), `AppNavPublish`
105
+ ("N changes not live" + Publish, or "Live on your store"), `AppNavSwitchRow` (a row of the switcher's menu: dot, name, note) and `AppNavFrame` (the nav beside the
106
+ page's 900 column; the shell's main gives up its gutter for it). Words only, 216 wide on a new token, `--gemboss-appnav-bg`
107
+ (#f6f6f7, declared in the entry: gemboss-ui.css is frozen); at 768px and below the header and one row of chips. Its own entry,
108
+ `@gemboss/ui/app-nav.css` (1.7 KB gzip).
109
+
110
+ ## 0.61.0 (05/11/2026)
111
+
112
+ **The skills UI without content-radar's overrides** (04/11/2026: the four kit gaps content-radar's move to 0.59.0 found, gemlabs
113
+ #1586; each was a one-line override there).
114
+
115
+ Fixed
116
+ - A Flow canvas inside `SkillView` / `SkillViewBody` sticks its zoom bar and detail panel under the tab row. The 56px `--skf-sticky`
117
+ on `.ui-skillview` never reached the canvas, because `.skf` sets its own 12px; the value is now set on `.ui-skillview
118
+ .skf:not(.skf--full)`, from the row's height less the scroller's top padding (24px in the popup, 40px on touch and phones,
119
+ content-radar's measured values). A full-screen canvas keeps its 0.
120
+ - A `SkillViewBody` in a padded scroller of a surface's own (a writer pane, a `Dialog` body, an `EditorFrame` preview) can stick
121
+ its tab row to the scroller's very top and run it over the side padding, as the popup's does: set `--ui-skillview-pad-top` and
122
+ `--ui-skillview-pad-x` (the scroller's padding) on the body or the scroller. The popup sets them itself (16px, 32px; 16px sides on
123
+ a phone). Unset, nothing changes.
124
+ - `SkillCard size="lg"` no longer cuts its `line` at two lines (Chris 31/10/2026: text a writer reads is read whole).
125
+ - `SkillGroup`'s `id` names the `<section>` too, so `#<id>` jumps to the group; the heading keeps `<id>-h`.
126
+
127
+ **What a polish round on the GemX screens needed from the kit** (04/11/2026, GemX boards ubl-PL-2, ubl-PZ-4, ubl-AB-6p, ubm-AB-6p).
128
+
129
+ Added
130
+ - `Sheet` `subtitleBeside`: the subtitle on the title line, at its end, before the actions (`ui-sheet--beside`, in `sheet.css`): an
131
+ idea's "Ideas · Ready-made". It still describes the popup, never names it.
132
+ - `VersionBlank`: the blank card a version pair draws, on its own, for a picture that turns out to have none once asked (the admin's
133
+ page poster that cannot be drawn), so the place holds the kit's card, never an empty box.
134
+ - `MomentPicture` (`mark`: `bar-top` | `bar-bottom` | `popup` | `section` | `section-off` | `drawer`, `label`): what has no version B (a
135
+ moment during the visit) in a pair's place, one blank card with what it does marked where it happens. In `versions.css`.
136
+ - `Icon` `funnel`.
137
+
138
+ Changed
139
+ - `Menu` `select` off (`disabled`): shows its choice with no hover, no pointer and a quiet chevron (`menu-select.css`): a field a
140
+ screen shows and does not change there (Who sees what's Everyone else).
141
+
7
142
  ## 0.60.0 (04/11/2026)
8
143
 
9
144
  **A progress bar a screen places anywhere** (04/11/2026, GemX on the UI book, board ubl-PL-1b: a rule's days on Plan's Testing card).
package/README.md CHANGED
@@ -72,9 +72,12 @@ its CSS out of the build with it (`sideEffects`). gzip of the minified file, as
72
72
  | 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 |
73
73
  | 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 |
74
74
  | editor-chips | `@gemboss/ui/editor-chips.css` | `packages/ui/src/editor-chips.css` | `InspectorChips`: a run of inspector groups where one holding nothing is a chip | 0.4 KB | `InspectorChips` imports it |
75
+ | editor-inspector-frame | `@gemboss/ui/editor-inspector-frame.css` | `packages/ui/src/editor-inspector-frame.css` | `InspectorFrame`, `InspectorFrameGroup`: the settings frame every settings surface draws (search, the index of clusters, a cluster's name, a group open, a + line, added with a −) | 0.9 KB | `InspectorFrame` imports it |
75
76
  | 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 |
76
77
  | narration | `@gemboss/ui/narration.css` | `packages/ui/src/narration.css` | the narration timeline's own: a step that selects its section, its Undo from here, the plan card pinned at the top of a turn | 0.6 KB | admin `NarrationTimeline` imports it |
77
78
  | editor-rail | `@gemboss/ui/editor-rail.css` | `packages/ui/src/editor-rail.css` | the page editor's 56px rail: the editor frame 56px in, the shell's rail beside it as icons, opened to 240px over the editor (unreleased) | 0.9 KB | admin `EditorRailToggle` imports it |
79
+ | rail-mini | `@gemboss/ui/rail-mini.css` | `packages/ui/src/rail-mini.css` | the rail folded to 56px of icons (`railMode="mini"`, 0.62.0): rows as icons with their names out of sight, counts as dots, main at 56 | 0.6 KB | `AppNav` imports it; a surface that folds the rail without one links it |
80
+ | app-nav | `@gemboss/ui/app-nav.css` | `packages/ui/src/app-nav.css` | `AppNav`, `AppNavFrame`: a section's own grey nav beside the folded rail, and its chips on a phone (0.62.0) | 1.7 KB | `AppNav` imports it (with rail-mini.css) |
78
81
  | reactions | `@gemboss/ui/reactions.css` | `packages/ui/src/reactions.css` | the emoji reactions and their picker | 0.8 KB | `Reactions` / `ReactionPicker` import it |
79
82
  | assistant-engine | `@gemboss/ui/assistant-engine.css` | `packages/ui/src/assistant-engine.css` | the engine picker (chip + Settings › AI & engines) and the bridge notice | 1.9 KB | `EnginePicker` / `EngineSettings` / `BridgeNotice` import it |
80
83
  | 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 |
@@ -102,6 +105,9 @@ its CSS out of the build with it (`sideEffects`). gzip of the minified file, as
102
105
  | skill-view | `@gemboss/ui/skill-view.css` | `packages/ui/src/skill-view.css` | `SkillView`, `SkillViewBody`, `SkillViewSection`, `SkillRuleList`: one skill in a ReaderDialog (or alone), tabs as slots (03/11/2026, unreleased) | 1.4 KB | `SkillView` imports it (with reader-dialog.css) |
103
106
  | skill-card | `@gemboss/ui/skill-card.css` | `packages/ui/src/skill-card.css` | `SkillGroup`, `SkillCard`: the cards a skill's popup opens from (04/11/2026, unreleased) | 1.3 KB | `SkillCard` / `SkillGroup` import it |
104
107
  | skill-stats | `@gemboss/ui/skill-stats.css` | `packages/ui/src/skill-stats.css` | `SkillStats`: one skill's usage, runs, engines, outcomes, versions (03/11/2026, unreleased) | 1.0 KB | `SkillStats` imports it (and minichart.css through ShareBar) |
108
+ | skill-history | `@gemboss/ui/skill-history.css` | `packages/ui/src/skill-history.css` | `SkillVersionList`, `SkillDiff`, `SkillChangeCard`: a skill pack's History, versions with Compare, a proposal's changes (05/11/2026, unreleased) | 0.6 KB | `SkillVersionList` / `SkillDiff` / `SkillChangeCard` import it |
109
+ | skill-pages | `@gemboss/ui/skill-pages.css` | `packages/ui/src/skill-pages.css` | `SkillsTabs`, the Rules book (`SkillRuleSummary`, `SkillRuleSection`, `SkillGuardGroups`, `SkillCheckTable`, `SkillRuleChip`, `SkillRuleLevel`), Building blocks (`SkillLayerList`, `SkillDocJump`, `SkillDoc`, `SkillDocHistory`): content-radar's Skills pages (07/11/2026, unreleased) | 1.7 KB | the components in `skill-pages.tsx` import it |
110
+ | skill-feedback | `@gemboss/ui/skill-feedback.css` | `packages/ui/src/skill-feedback.css` | `SkillFeedbackList`, `SkillFeedbackBar`, `SkillFeedbackHead`: runs and feedback on a skill, content-radar's Feedback tab (07/11/2026, unreleased) | 0.4 KB | `SkillFeedbackList` imports it |
105
111
  | skill-flow | `@gemboss/ui/skill-flow.css` | `packages/ui/src/skill-flow.css` | `SkillFlow`: a skill's flow canvas, its OWN lazy entry `@gemboss/ui/skill-flow` (React Flow + dagre, optional peers) (03/11/2026, unreleased) | 3.4 KB | the canvas imports it, with `@xyflow/react/dist/style.css` |
106
112
  | members | `@gemboss/ui/members.css` | `packages/ui/src/members.css` | `MembersPage`: the members list of every service (chips with counts, the table with a role select per scope and the inline confirm, the drawer, Invite and the CSV check, the phone cards); the `gb-members-*` classes a plain-HTML page writes (04/11/2026, unreleased) | 2.0 KB | `MembersPage` imports it (with list-page.css, sheet.css, portal.css through the kit parts it draws); a plain-HTML page links it (README "Members") |
107
113
  | gems | `@gemboss/ui/gems.css` | `packages/ui/src/gems.css` | The four gems: `--gemboss-gem-emerald` / `-ruby` / `-amber` (sapphire is the iris accent) and the rail count in ruby. Colour with a job: ruby = look here, emerald = it is working, amber = connect and wait; never a button fill (unreleased) | 0.1 KB | the surface links it beside its core (the bundle is frozen) |
@@ -197,6 +203,53 @@ One component for a page that lists one kind of thing (the admin's Rules first;
197
203
  Colours are Polaris' where Polaris is loaded (`--p-color-text`, `--p-color-text-secondary`, `--p-color-bg-fill-tertiary`),
198
204
  the kit's tokens elsewhere.
199
205
 
206
+ ## AppNav and the mini rail (0.62.0): a section that opens as an app of its own
207
+
208
+ Chris, 05/11/2026: entering a plugin folds the main menu to icons so the plugin gets the space, and every plugin is laid out the
209
+ same way, its visuals never clashing with the icon rail (canvas https://claude.ai/artifact/Hsou4RYohWWXpzv1jHbtYZ, direction A).
210
+ Three planes: the rail is icons on white, the section's nav is words on light grey, the page is white.
211
+
212
+ ```tsx
213
+ <AppShell railMode="mini" rail={…} railBottom={…}>
214
+ <AppNavFrame nav={(
215
+ <AppNav identity={{ icon: <Icon/>, name: "GemReview", status: "On · 2 places", tone: "on" }}
216
+ switchLabel="Switch plugin" switchHeading="Your plugins"
217
+ switchMenu={<>{others.map((o) => <AppNavSwitchRow key={o.id} href={o.href} name={o.name} tone={o.on ? "on" : "off"} note={o.on ? null : "Off"} current={o.id === id} />)}<hr /><AppNavSwitchRow href="/app/plugins" icon={<GridIcon />} name="All plugins" /></>}
218
+ groups={[
219
+ { items: [{ label: "Home", href: "?tab=home", current: true }, { label: "Reviews", href: "?tab=reviews", badge: 4, badgeLabel: "4 need you" }] },
220
+ { heading: "Library", items: [{ label: "Widgets", href: "?tab=widgets", count: 3 }] },
221
+ { heading: "Numbers", items: [{ label: "Insights", href: "?tab=insights" }] },
222
+ ]}
223
+ foot={<><AppNavLink href="?tab=settings">Settings</AppNavLink><AppNavPublish changes={2} onPublish={publish} busy={publishing} /></>}
224
+ linkAs={Link} onItemClick={(item, e) => { e.preventDefault(); openTab(item.href); }} />
225
+ )}>
226
+ {page}
227
+ </AppNavFrame>
228
+ </AppShell>
229
+ ```
230
+
231
+ - `railMode` (`AppShell`, `Shell`): `mini` puts `data-rail="mini"` on the shell, and from 761px the rail is 56px of icons (the page
232
+ editor's closed rail, the same numbers: 32px rows under a mouse, 44 under a finger), `main` starts at 56, the holding cover and Gem
233
+ full screen or pinned start there too. A `RailItem` whose label is words takes it as its `title` and its `aria-label` (not the
234
+ `aria-label` when a `RailCount` follows it: the hidden label and the count name it); the label stays in the markup, out of sight,
235
+ and shows beside the rail on keyboard focus. A `RailCount` is a dot whose `aria-label` is the count. Sub rows and headings go. On
236
+ a phone nothing changes: the drawer opens the full rail. `full`, the default, adds nothing to the markup. The rules are
237
+ `rail-mini.css`, which `AppNav` brings; a surface that folds the rail without an AppNav imports `@gemboss/ui/rail-mini.css`.
238
+ - `AppNav`: `identity` (`icon` on a 32px iris tile, `name`, `status` with a dot in `tone`: `on` · `off` · `wait`), `groups`
239
+ (`heading?`, `items: { label, href, current?, count?, badge?, badgeLabel? }`), `foot`. With `onSwitch` or `switchMenu` the header is
240
+ a button with a chevron; `switchMenu` opens under it, 280 wide over the page, `switchHeading` over its rows (Escape, a press outside
241
+ or a row followed closes it). `AppNavSwitchRow`: a dot in `tone`, an `icon`, the `name`, a `note` at the end; `current` is shaded. Words only in the rows:
242
+ 216 wide on `--gemboss-appnav-bg` (#f6f6f7, its own token in this entry), rows 32 tall, 0 12 inside, 8 round, 13/500; the current
243
+ row (`aria-current="page"`) white, 600, on a hairline ring; headings 11/600 caps; a badge an iris pill, a count muted at the end.
244
+ `linkAs` renders the links (a router's), `onItemClick` hears a row pressed first (a surface that changes the page itself).
245
+ - `AppNavLink` is a foot row (Settings), `AppNavPublish` the foot's Publish: "N changes not live" and the button (`pending` when the
246
+ changes cannot be counted, `busy` while it runs), else `live` with a tick ("Live on your store"; null draws nothing).
247
+ - `AppNavFrame` lays the nav beside the page: the nav sticks under the topbar, full height; the page is the kit's 900 column; the
248
+ shell's `main` gives up its gutter while it holds one.
249
+ - At 768px and below the same data is the header and one row of chips, the current one filled near-black; headings and counts go,
250
+ the foot's rows join the chips.
251
+ - Any section draws it (a plugin, the admin's Reach): nothing in it knows what the section is.
252
+
200
253
  ## Page width (0.8.1)
201
254
 
202
255
  Chris, 04/10/2026: the rail on the left, and on the right a content column with the same max width on every
@@ -812,7 +865,7 @@ import "@gemboss/ui/editor.css"; // only on the screens that show an editor
812
865
  | Preview | `.gemboss-pv` › `.gemboss-pv-stage` › `.gemboss-pv-frame` (`.desktop` / `.tablet` / `.mobile`, `.gemboss-pv-fit` for scale-to-fit) › `iframe.gemboss-pv-iframe`; `.gemboss-pv-spin`; empty state `.gemboss-pv-empty` (`-art`, `-title`, `-sub`, `-cta`). Device toggle `.gemboss-pv-devices › button.gemboss-pv-device` |
813
866
  | Left column | tab row `div.gemboss-ec-tabs[role=tablist] › button[role=tab][aria-selected]` (add `.gemboss-ec-tab` for the 44px pointer floors); Configure pane `.gemboss-ec-dock-body` |
814
867
  | Inspector | `.gemboss-ei` (`--docked` inside the Configure pane) › `.gemboss-ei-head` (`-title`, `-x`, `-savedot`), `.gemboss-ei-tabs › .gemboss-ei-tab`, `.gemboss-ei-body`, `.gemboss-ei-foot`. Groups `.gemboss-ei-group › .gemboss-ei-grouphead` (collapsible) and `.gemboss-ei-gh` / `.gemboss-ei-grp`. Field `.gemboss-ei-fld › label + control + .gemboss-ei-hint` |
815
- | Controls | text / select `.gemboss-field.gemboss-ei-inp` (+ `.gemboss-ei-mono`), a number with its unit inside `UnitField` (`label.gemboss-field.gemboss-field--group` › `.gemboss-field__bare` + `.gemboss-field__suffix`, 0.40.0; `.gemboss-ei-suffix` is gone), segmented `.gemboss-ei-seg`, colour `.gemboss-ei-color` / `.gemboss-ei-swatches › .gemboss-ei-sw` / `.gemboss-ei-swatch`, range `.gemboss-ei-range` + `.gemboss-ei-rangeval`, spacing box `.gemboss-ei-edgebox › .gemboss-ei-edge`, image `.gemboss-ei-img` (`-thumb`, `-ctl`, `-actions`, `-info`, `-name`, `-meta`, `-drop`, `-grid`, `-cell`), repeater `.gemboss-ei-rep-item` (`-head`, `-acts`, `-add`), blocks `.gemboss-ei-block` (`-head`, `-x`), add `.gemboss-ei-addrow` (its buttons are the kit's `.ui-btn` via `ChipButton`, 0.40.0; `.gemboss-ei-addchip` is gone), element tree `.gemboss-ei-tree › .gemboss-ei-tnode` (`-tname`, `-tacts`, `-tadd`), notes `.gemboss-ei-note`, `.gemboss-ei-oos` (`-h`), `.gemboss-ei-empty`, drag `.gemboss-ei-drag` / `.gemboss-ei-dragmask` |
868
+ | Controls | text / select `.gemboss-field.gemboss-ei-inp` (+ `.gemboss-ei-mono`), a number with its unit inside `UnitField` (`label.gemboss-field.gemboss-field--group` › `.gemboss-field__bare` + `.gemboss-field__suffix`, 0.40.0; `.gemboss-ei-suffix` is gone), segmented `.gemboss-ei-seg`, colour `.gemboss-ei-color` / `.gemboss-ei-swatches › .gemboss-ei-sw` / `.gemboss-ei-swatch`, range `.gemboss-ei-range` + `.gemboss-ei-rangeval`, spacing box `.gemboss-ei-edgebox › .gemboss-ei-edge`, image `.gemboss-ei-img` (`-thumb`, `-ctl`, `-actions`, `-info`, `-name`, `-meta`, `-drop`, `-grid`, `-cell`), repeater `.gemboss-ei-rep-item` (`-head`, `-acts`, `-add`), blocks `.gemboss-ei-block` (`-head`, `-x`), element tree `.gemboss-ei-tree › .gemboss-ei-tnode` (`-tname`, `-tacts`, `-tadd`), notes `.gemboss-ei-note`, `.gemboss-ei-oos` (`-h`), `.gemboss-ei-empty`, drag `.gemboss-ei-drag` / `.gemboss-ei-dragmask` |
816
869
  | Layers | `.gemboss-layers` › `.gemboss-layer-head` + `.gemboss-layers-list` › `.gemboss-layer` (`.is-sel`) › `.gemboss-layer-main` (`.gemboss-layer-type`) + `.gemboss-layer-acts` (`.gemboss-layer-del`) |
817
870
  | Settings drawer | `.gemboss-settings` › `.gemboss-picker-head` + `.gemboss-settings-body` › the kit's `Field`s (`.gemboss-ei-fld`), `.gemboss-settings-grouphead`, `-gen`, `-note`, `-error`; `.gemboss-settings-foot` (`-save`, `-cancel`); backdrop `.gemboss-picker-backdrop`, empty `.gemboss-picker-empty` |
818
871
  | Page / section editor bar | `.gemboss-pageedit` (`-top`, `-title`, `-kind`, `-status`, `-standing`, `-scope`, `-modes`, `-notice`, `-chip`, `-pv`; the left cluster's gap is `--gemboss-tb-gap`, 12px, for a child that hands it back; above 1000px the bar's tracks are `auto fit-content(100%) auto`, so its free space sits beside the centre), `.gemboss-sec-type`, section insert `.gemboss-sec-insert-*`, draft preview `.gemboss-page-draft-stage` / `-status`, `.gemboss-page-section-content`, global styles bundle `.gemboss-bundle-look` |
@@ -943,7 +996,10 @@ import { ColorControl, EdgeBox, Field, ImageControl, InspectorGroup, PanelAction
943
996
  | `PanelHeader`, `PanelAction` | `header.gemboss-ei-head` › `.gemboss-ei-title` (+ `small` subtitle) · `.gemboss-ei-act` buttons · `.gemboss-ei-x` ✕ | ✕ only with `onClose` (a docked panel has none); `onDragStart` adds `.gemboss-ei-drag` and takes the mouse-down of a floating panel. |
944
997
  | `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 (`.gemboss-ei-grp>.gemboss-ei-gh[data-open="closed"]~*`, a class heavier than any field's own `display`; the body stays mounted; an inline `display` on the body's first element would still 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`. |
945
998
  | `InspectorChips` | `.gemboss-ei-chips` › groups in their own order; a group marked `data-chip` (an `InspectorGroup`'s `attrs`, or a `.gemboss-ei-grp` line of the caller's) is its first child alone as a pill (28px, 44 under a finger, 8px apart, no chevron); the others take the whole width | Its own part, `editor-chips.css` (31/10/2026, Control UI C32 slice 3: the element panel's empty shared groups). The caller marks and unmarks a group; it stays the same element under the same parent, so a chip that opens keeps the focus. editor.css weighs a folded group's padding as the group's own (`:where(:has(…))`, (0,1,0)), so a chip's rule needs no extra weight. |
946
- | `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`. `aside`: a control on the label line, at its right, beside the label and not in it (a spacing field's shape). |
999
+ | `InspectorFrame` | `div.gemboss-ei-frame[data-settings-frame]` (display: contents) › head · `InspectorSearch` (`.gemboss-ei-find`) · `nav.gemboss-ei-index` (`data-jump` per cluster, `aria-current` on the one in view) · aside · lead · per cluster `div.gemboss-ei-cluster[data-panel-cluster]` › `.gemboss-ei-cluster-name` and its groups | The settings frame (06/11/2026, the element panel's, for every settings surface): its own part, `editor-inspector-frame.css`. A cluster with no content is neither drawn nor indexed; `results` (a search's) replace the index, the lead and the clusters. The index moves the panel's own scroller, not the page. |
1000
+ | `InspectorFramePart` | `div.gemboss-ei-part[data-frame-part]` (display: contents), `hidden` while a search does not find it | A part of the panel that is not one of its groups (a section's words, its options), in its place in its cluster: a search shown in place (`InspectorFrame` `searching`) never draws it again from nothing. A static `InspectorGroup` inside the frame is drawn as the frame's open group (InspectorGroup decides it). |
1001
+ | `InspectorFrameGroup` | `state="open"`: `.gemboss-ei-grp[data-open-group]` › `.gemboss-ei-openhead`. `"add"`: `.gemboss-ei-grp.gemboss-ei-addline[data-add-group]` › `button.gemboss-ei-addhead` (name, `.gemboss-ei-addplus` +). `"added"`: `.gemboss-ei-grp[data-added-group]` › `.gemboss-ei-addedhead` (name, `.gemboss-ei-headacts` › acts, `button.gemboss-ei-addsign[data-remove-group]` −) and the rows | One element in the three states, so a group added stays where it was with the focus in it. `chip` in an `InspectorChips` run draws the + line as a pill. What + and − write is the caller's. |
1002
+ | `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. `control` (05/11/2026, unreleased): the control it holds, by the one table `LABEL_SIDE` (`labelSide`, `isFieldControlKind`): `select`, `chips`, `toggle`, `color`, `value`, `number`, `range`, `pick`, `text`, `link`, `date` put the label beside it (`.gemboss-ei-fld--row`, a row wherever it is, not only in a group); `textarea`, `list`, `edges`, `image`, `tiles`, `gradient`, `drawing`, `code` keep it above, and so do `screens` and `font-pick` until those controls are reworked. A row's notes (`.gemboss-ei-hint`, its help included) run across the field under it. `row` is deprecated (a side by hand). `className` (the admin's `togrow`), `style`. `aside`: a control on the label line, at its right, beside the label and not in it (a spacing field's shape). |
947
1003
  | `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. |
948
1004
  | `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`). |
949
1005
  | `RangeControl` | `input[type=range].gemboss-ei-range` | Every change, as a number (drag, arrows, Home / End). Show the value with `Field`'s `labelValue`. |
@@ -1351,6 +1407,7 @@ does: keep it idempotent. A route that draws the sheet (Next's intercepting rout
1351
1407
  | | |
1352
1408
  | --- | --- |
1353
1409
  | Markup | `<dialog class="ui-modal ui-sheet">` with the popup's own `ui-modal__head` (title, `__subtitle`, `__actions`, ✕), `__body`, `__foot` |
1410
+ | Subtitle beside | `subtitleBeside`: the subtitle on the title line, at its end, before the actions (`ui-sheet--beside`; Plan's idea, "Ideas · Ready-made"); it still describes the popup, never names it |
1354
1411
  | Behaviour | It is `Dialog` with `ui-sheet` on it (one render tree, one hook, `useModalDialog`): Escape, ✕ and a click on the backdrop close it (a press that STARTED on the backdrop: a selection dragged out of the panel does not), `onClose` hears each once, the page behind is inert and holds still (`html:has(dialog.ui-modal:modal) { overflow: hidden }` in kit-plain.css, one rule for every modal kit popup), the panel itself takes focus on open (not the head's first link), focus goes back to the row. The subtitle describes the popup (`aria-describedby`); the name is the title alone |
1355
1412
  | Size | the full height; 560 wide, `wide` 760, from 768px up; the whole screen below that; head, ✕ and buttons at the popup's density (README "Popup density") |
1356
1413
  | Motion | slides in from the right (200 ms); none under `prefers-reduced-motion` |
@@ -1922,7 +1979,8 @@ import { AppShell, BrandLockup, AccountMenu, AccountMenuItem, Icon, RailItem } f
1922
1979
  opens from a field as wide as its column (the choice, cut with "…", and a chevron; 32px, 44 under a finger or below 768), named
1923
1980
  "When: About to leave"; its rows are the parts above, the chosen one `checked`. CSS in its own entry, `menu-select.css`, which
1924
1981
  `Menu` imports; `menu-select.test.tsx` holds the markup. For a choice whose rows say more than an `<option>` can; a plain choice
1925
- stays a select.
1982
+ stays a select. Off (`disabled`), it shows its choice with no hover and a quiet chevron: a field the screen shows and does not change
1983
+ there (Who sees what's Everyone else, version A).
1926
1984
 
1927
1985
  ## Topbar search (0.6.3)
1928
1986
 
@@ -2805,6 +2863,54 @@ import { KindArt } from "@gemboss/ui";
2805
2863
  - Decorative (`aria-hidden`): the card's name says what it is. `title` makes it an image with that name, where the picture is the
2806
2864
  only thing that says it. Server-renderable, no inline style. Its own entry, `kind-art.css` (0.6 KB gzip).
2807
2865
 
2866
+ ## Gem at work (05/11/2026, unreleased; ADR 0013): `createGemAtWork`
2867
+
2868
+ What Gem is doing, drawn on the page it is doing it to, while a turn runs. Gem's crew (Gem leading, then a copy, a layout, an image
2869
+ and a CRO expert, QA and smart styling, each an arrow with its name; kept on Chris's word, 05/11: "giữ lại làm cho sinh động và dễ
2870
+ hiểu") goes to the block being changed; a ring names it; the expert for that kind of work drags the box out from its corner at its
2871
+ real size; the words arrive IN the block itself; what changed lights up once at the end. It reads ONE thing, the activity contract
2872
+ v1, never the agent's stream: the admin's reader (`apps/admin/src/lib/gem-activity.ts`) turns the stream into activities, so a
2873
+ renamed tool changes a line in its map.
2874
+
2875
+ ```ts
2876
+ import { createGemAtWork } from "@gemboss/ui";
2877
+
2878
+ const gem = createGemAtWork({ onFallback: (level) => count(level), onStatus: (text) => setStatus(text) });
2879
+ reader.read(event).forEach((activity) => gem.push(activity)); // every stream event, as it arrives
2880
+ gem.reveal(["s-hero", "s-faq"]); // saved sections arrived: built in after what is still being drawn (no ids: every section)
2881
+ await gem.idle(); // the calm clock has drawn everything that arrived
2882
+ gem.catchUp(turnSoFar); // a frame that joins mid-turn (Page ⇄ Canvas): the turn so far, drawn at once, nothing moving
2883
+ gem.skip(); // the person pressed Skip: the page as it is, at once
2884
+ gem.destroy(); // the layer leaves the page
2885
+ ```
2886
+
2887
+ - **The calm clock** (Chris 05/11: "các bước cũng ko cần phải quá nhanh… để mắt người nhìn kịp"): activities are drawn in order,
2888
+ each held long enough to be seen (a thought 1.2 s, a finished line 0.7 s, a check 1.8 s), words typed at 28 characters a second.
2889
+ It may trail Gem, never lead it: it only ever draws what has arrived, and more than 12 s behind it hurries in proportion.
2890
+ `clock: "live"` draws each activity the moment it arrives.
2891
+ - **The grammar.** `think`/`plan`: the crew arrives, Gem's tag says the step. `focus`: the layout expert goes to the block and a ring
2892
+ names it. `draft`: the box dragged out at its real size (W × H), two guides across its section, the words written into the
2893
+ block's own text node (a caret where the next word goes). A section this turn adds (`created`) that the page does not have yet is a
2894
+ soft card in the page's content column, its words in the page's own font, each next one stacked below; the page makes room for
2895
+ them (one empty block after its last section), so its footer moves down instead of being drawn over. `apply`: a tick. `check`: QA
2896
+ sweeps a scan line down the screen. `fail`: Gem and the ring turn red for 2.4 s, the words go back. `land`: what changed lights up
2897
+ for 1.6 s; the crew leaves. At most four are on the page at once: Gem, the one at work, and two trades beside it walking slowly along the block's edges, off its words; the others are gone until their trade comes up. The walk stops with the turn.
2898
+ - **`reveal(ids?)`**: saved sections, each through **one order, overview to detail**: structure (frames that paint something), pictures, headlines, words, buttons, then QA's sweep; within a step blocks go top to bottom and left to right; Gem's tag names the step. A section taller than the screen goes a screenful at a time, each through the whole order, so the page only moves down. An expert goes to a block's corner, holds the mouse down and drags its box out; words wipe in behind a caret, a picture's box fills with tint and the picture comes up through it. Nothing is outlined ahead of the boxes (Chris 05/11: a box dragged over a box already there makes no sense).
2899
+ - **Targets by stable ids only**: `[data-gem-el-id]`, then `[data-gem-section-id]`, the first match that has a box (a custom-liquid
2900
+ section is a `display: contents` wrapper around an inner section with the same id; `find` replaces the lookup). **The ladder**: an
2901
+ element it cannot find is drawn on its section, a section it cannot find at page level, and an error anywhere skips to the page
2902
+ as it is; `onFallback(level, activity)` reports each step down.
2903
+ - **One layer, no hooks in the page.** Words written into a block are its own text node's value only, put back by `skip()`,
2904
+ `destroy()` and a refusal (left for the saved page when a turn lands a change); the one block put in the page is the room for
2905
+ sections on their way, taken out with them; `reveal()` puts every style it touched back as it was. Under a bar that sticks to the
2906
+ top of the screen the layer is cut at the bar's edge, so what is drawn scrolls under it as the page does. The page is followed
2907
+ down as Gem works, unless the person moved it themselves in the last 4 s; a page drawn at its full height (the Studio's Canvas
2908
+ pans it) cannot scroll, so `onLook(top, height)` tells its host where to move the board.
2909
+ - **Light.** Only transform, opacity and clip-path move, nothing loops, the stylesheet animates nothing. `mode`: `full`, `subtle`
2910
+ (rings, words and the light, no crew or dragged box) or `off`; `crew` sets how many of the seven draw. With prefers-reduced-motion
2911
+ nothing travels or animates. A store theme's resets (`svg { max-width: 100% }`) do not shrink the crew's arrows.
2912
+ - Plain DOM, no React: the same file runs in the preview frame (gemsite copies it byte for byte). Its own entry, `gem-at-work.css`.
2913
+
2808
2914
  ## Report pages (0.4.0)
2809
2915
 
2810
2916
  Plain CSS in `kit-plain.css` for a numbers page written by hand (first user: gemnews `/admin`, 03/10/2026; that page moved to GemCommunity the same day, so gemnews no longer takes the package). The
@@ -2814,6 +2920,7 @@ surface computes every number and ratio; the kit only draws. Markup for each is
2814
2920
  top, big value, a foot line for the comparison.
2815
2921
  - `ui-delta` (`--good` / `--bad`): change vs a previous period. Good or bad is the surface's call (reads up is good,
2816
2922
  bounce up is bad); the arrow is direction, written in the markup. No tone = neutral or "no previous period".
2923
+ - A page without the core (the admin) imports `@gemboss/ui/report-charts.css` for `ui-barlist`, `ui-chart` and `ui-legend`.
2817
2924
  - `ui-barlist`: horizontal bars. `--v` (0..1) is the length, `--c` the colour; label and value on one line, the bar
2818
2925
  full width below it, so no fixed label column gets squeezed at 320px. `__share`, `__note`.
2819
2926
  - `ui-chart`: stacked columns over time plus an optional hollow-dot series. `--v` per segment and dot, `data-max`
@@ -2990,6 +3097,10 @@ draw their pictures and figures from here, so one change moves both. Their own e
2990
3097
 
2991
3098
  - `VersionPair`: `a` and `b` are the surface's own pictures (null draws a blank card), held to 3:4 with their letters (`tags`, default
2992
3099
  A and B) on the corner. `lit: "a" | "b"` lights one letter: the version that leads a test, the one an audience is shown.
3100
+ - `VersionBlank`: that blank card on its own, for a picture that turns out to have none once asked (a page poster that cannot be drawn:
3101
+ the admin's `PagePosterThumb unavailable`), so the place holds the kit's card, never an empty box.
3102
+ - `MomentPicture`: what has no version B (a moment during the visit) in the same place: one blank card, what it does marked where it
3103
+ happens (`mark`: `bar-top`, `bar-bottom`, `popup`, `section`, `section-off`, `drawer`), named by `label` ("Shows a bar at the bottom").
2993
3104
  - `Figure`: the value, and under it its cap in the caption's size. `strong` for the figure a column is about, `tone` for what kind of
2994
3105
  number it is (`pos` a gain, `accent` a version's letter, `muted` a dash or a word), `capTone: "pos"` for a lift under a leader.
2995
3106
  - `mediaColumn`: IndexTable puts each row's `media` in a column of its own before the title, and leaves it out when it folds.
@@ -8,7 +8,7 @@
8
8
  .cat-code summary{padding:10px 16px;font-size:13px;cursor:pointer;color:var(--gemboss-text-muted);border-top:1px solid var(--gemboss-divider);min-height:24px}
9
9
  .cat-code pre,.cat-api{margin:0;padding:12px 16px;overflow:auto;background:#0f1012;color:#e8e8e6;font-size:12px;line-height:1.5;border-radius:0}
10
10
  .cat-api{border-radius:12px;margin:0 0 16px}</style></head><body><div class="cat">
11
- <h1>@gemboss/ui 0.60.0 · Editor</h1>
11
+ <h1>@gemboss/ui 0.63.0 · Editor</h1>
12
12
  <p>Khung của mọi editor: <code>EditorFrame</code> (cột trái · khe kéo · preview · cột phải dock trên mép phải preview) và <code>EditorTopbar</code> (← · tiêu đề · cụm giữa · cụm phải · dòng trạng thái). Là đúng khung của theme / page / section editor trong admin. Gói chỉ vẽ KHUNG; chat, Configure, canvas, page picker, menu, Publish là của editor, đi vào bằng slot. Trang HTML thuần nạp <code>editor.css</code> + <code>editor-plain.js</code> rồi gọi <code>gembossUI.initEditorFrame()</code>: kéo khe (chuột, chạm, phím mũi tên / Home / End), đổi thiết bị, mở ⋯ và Publish ▾, ẩn cột trái, Chat | Preview trên điện thoại. <a href="index.html">← Catalog</a></p>
13
13
  <h2>React</h2><pre class="cat-api"><code>import &quot;@gemboss/ui/editor.css&quot;;
14
14
  import { EditorFrame, EditorTopbar, EditorBack, EditorChatToggle, EditorPaneTabs, EditorSaveState, DeviceToggle } from &quot;@gemboss/ui/editor&quot;;