@gemboss/ui 0.61.0 → 0.64.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 (45) hide show
  1. package/CHANGELOG.md +153 -0
  2. package/README.md +163 -2
  3. package/catalog/editor.html +1 -1
  4. package/catalog/index.html +3 -3
  5. package/gemboss-ui.css +3 -3
  6. package/package.json +15 -1
  7. package/parts/components.css +3 -3
  8. package/parts/core.css +1 -1
  9. package/parts/shell.css +1 -1
  10. package/src/app-nav.css +1 -0
  11. package/src/app-nav.tsx +236 -0
  12. package/src/assistant/chat.tsx +67 -4
  13. package/src/assistant/dictation.ts +292 -0
  14. package/src/assistant/index.ts +4 -1
  15. package/src/audiences-table.css +1 -0
  16. package/src/audiences-table.tsx +167 -0
  17. package/src/chat-voice.css +1 -0
  18. package/src/editor/frame-context.ts +9 -0
  19. package/src/editor/index.ts +8 -0
  20. package/src/editor/inspector-frame.tsx +285 -0
  21. package/src/editor/label-side.ts +79 -0
  22. package/src/editor/panel.tsx +23 -6
  23. package/src/editor/repeater.tsx +9 -3
  24. package/src/editor-inspector-frame.css +1 -0
  25. package/src/editor.css +1 -1
  26. package/src/email-editor/editor.tsx +434 -0
  27. package/src/email-editor/index.ts +16 -0
  28. package/src/email-editor/model.ts +357 -0
  29. package/src/email-editor/preview.tsx +208 -0
  30. package/src/email-editor.css +1 -0
  31. package/src/gem-at-work.css +1 -0
  32. package/src/gem-at-work.ts +1165 -0
  33. package/src/index.ts +17 -1
  34. package/src/kit-plain.css +1 -1
  35. package/src/rail-mini.css +1 -0
  36. package/src/report-charts.css +1 -0
  37. package/src/shell.tsx +36 -8
  38. package/src/skill-feedback.css +1 -0
  39. package/src/skill-feedback.tsx +67 -0
  40. package/src/skill-history.css +1 -0
  41. package/src/skill-history.tsx +116 -0
  42. package/src/skill-pages.css +1 -0
  43. package/src/skill-pages.tsx +204 -0
  44. package/src/skill-tabs-group.tsx +45 -0
  45. package/src/skill-view.tsx +7 -1
@@ -0,0 +1,285 @@
1
+ "use client";
2
+ // THE SETTINGS FRAME (06/11/2026, one settings frame slice 1). Chris found three frames around one set of controls: the element panel's
3
+ // (search, an index of four clusters, group titles, groups that hold nothing as + lines and chips), the theme editor's folding groups,
4
+ // and a library section's Style as a flat list under uppercase heads. The element panel's is the standard (about 96% of the setting rows
5
+ // drawn); this is it, taken out of the admin's ElementNodePanel so every settings surface draws the same frame:
6
+ //
7
+ // div.gemboss-ei-frame[data-settings-frame] (display: contents: no box of its own, the panel's rows stay its host's children in layout)
8
+ // › head (the host's own row) › InspectorSearch › nav.gemboss-ei-index (Look · Layout · Visibility · Code, one press to each)
9
+ // › aside (a popover anchored in the panel) › lead (what governs everything under it)
10
+ // › per cluster: div.gemboss-ei-cluster[data-panel-cluster] (its name) › its groups
11
+ // A search's results take the place of the index, the lead and the clusters.
12
+ //
13
+ // The groups are the caller's, drawn with InspectorFrameGroup: open (always shown, no fold), add (a group holding nothing: its name and a
14
+ // +; marked `chip` inside InspectorChips it is a pill) or added (its rows under its name and a − that clears them). What a + or a − writes is the caller's: the frame decides how a panel looks and moves, never what it stores.
15
+ // Its own part, editor-inspector-frame.css: only a surface that draws the frame loads it.
16
+ import "../editor.css"; // a group's note (.gemboss-ei-gh-note) and the group itself are editor.css's
17
+ import "../editor-inspector-frame.css";
18
+ import { Fragment, useEffect, useLayoutEffect, useRef, useState } from "react";
19
+ import type React from "react";
20
+ import { Icon } from "../icons";
21
+ import { StaticGroupInFrame, type FramedStaticGroup } from "./frame-context";
22
+
23
+ /** The clusters by name (element review C34): Layout, not Spacing, as it holds Spacing and Sticky (a SPACING label over a group named
24
+ * Spacing read twice). */
25
+ export const INSPECTOR_CLUSTERS: Readonly<Record<string, string>> = { look: "Look", place: "Layout", when: "Visibility", code: "Code" };
26
+
27
+ // ── InspectorSearch ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
28
+
29
+ export interface InspectorSearchProps {
30
+ value: string;
31
+ onChange: (value: string) => void;
32
+ /** Default "Find a setting"; a panel whose host has a chat says "Find a setting, or ask chat". */
33
+ placeholder?: string;
34
+ /** The box's `name` (one per kind of panel, so a browser's autofill keeps them apart). */
35
+ name?: string;
36
+ /** Enter, where the host does something with it (the element panel asks its chat when no setting matches). */
37
+ onSubmit?: () => void;
38
+ }
39
+
40
+ /** The search box over a panel: Escape empties it, Enter is the host's (`onSubmit`). */
41
+ export function InspectorSearch({ value, onChange, placeholder = "Find a setting", name = "setting-search", onSubmit }: InspectorSearchProps) {
42
+ return (
43
+ <div className="gemboss-ei-find">
44
+ <label className="gemboss-field gemboss-field--group">
45
+ <Icon name="search" size={16} />
46
+ <input className="gemboss-field__bare" type="search" name={name} autoComplete="off" value={value} placeholder={placeholder} aria-label="Find a setting"
47
+ onChange={(e) => onChange(e.target.value)}
48
+ onKeyDown={(e) => {
49
+ if (e.key === "Escape" && value) { e.preventDefault(); onChange(""); }
50
+ if (e.key === "Enter" && onSubmit) { e.preventDefault(); onSubmit(); }
51
+ }} />
52
+ </label>
53
+ </div>
54
+ );
55
+ }
56
+
57
+ // ── InspectorClusterBreak ───────────────────────────────────────────────────────────────────────────────────────────────────────────────
58
+
59
+ /** Where a cluster starts (Control UI C32, labelled since element review C34): room, not a line, and the cluster's name at its foot, so
60
+ * the panel reads as three levels (cluster, group, field). A heading for a screen reader too. `first`: at the top, with no room above. */
61
+ export function InspectorClusterBreak({ cluster, label, first = false, hidden = false }: { cluster: string; label?: React.ReactNode; first?: boolean; hidden?: boolean }) {
62
+ return (
63
+ <div className={first ? "gemboss-ei-cluster gemboss-ei-cluster--first" : "gemboss-ei-cluster"} data-panel-cluster={cluster} hidden={hidden || undefined}>
64
+ <span className="gemboss-ei-cluster-name" role="heading" aria-level={3}>{label ?? INSPECTOR_CLUSTERS[cluster] ?? cluster}</span>
65
+ </div>
66
+ );
67
+ }
68
+
69
+ // ── InspectorFrame ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
70
+
71
+ export interface InspectorFrameCluster {
72
+ /** `look` · `place` · `when` · `code` (INSPECTOR_CLUSTERS names them), or a host's own with a `label`. */
73
+ id: string;
74
+ label?: React.ReactNode;
75
+ /** Its groups. */
76
+ content: React.ReactNode;
77
+ /** Whether it is drawn (its break, its groups, its index entry). Default: it has content. */
78
+ on?: boolean;
79
+ }
80
+
81
+ export interface InspectorFrameProps {
82
+ /** The host's own row, on top (a path back, the screen edited). */
83
+ head?: React.ReactNode;
84
+ /** An InspectorSearch, or nothing where there is nothing to find. */
85
+ search?: React.ReactNode;
86
+ /** After the index: a popover the panel anchors (it is drawn in the top layer, its place in the tree is its focus order). */
87
+ aside?: React.ReactNode;
88
+ /** Above the first cluster: what governs everything under it (the screen edited and its sentence, a condition hiding the element, a
89
+ * write held or not saved). Drawn while searching too. */
90
+ lead?: React.ReactNode;
91
+ /** In order. The first one drawn has no room above its break. */
92
+ clusters: ReadonlyArray<InspectorFrameCluster>;
93
+ /** A search's results: drawn in place of the index, the lead and the clusters (the element panel's, whose found rows are drawn anew). */
94
+ results?: React.ReactNode;
95
+ /**
96
+ * A search shown IN PLACE: the index and the clusters' names hidden, everything else as it is drawn, the caller hiding what the words
97
+ * do not find (InspectorFramePart, a group not drawn). Nothing is drawn again from nothing, so a part that read something (a section's
98
+ * words) keeps it and its controls (FieldFrame).
99
+ */
100
+ searching?: boolean;
101
+ /** `data-*` on the index (what a page finds it by). */
102
+ indexAttrs?: Record<`data-${string}`, string>;
103
+ }
104
+
105
+ /** The nearest box up the tree that scrolls and has more than it shows: the one the index moves. */
106
+ function scrollerOf(el: HTMLElement): HTMLElement | null {
107
+ for (let p = el.parentElement; p; p = p.parentElement) {
108
+ const y = getComputedStyle(p).overflowY;
109
+ if ((y === "auto" || y === "scroll") && p.scrollHeight > p.clientHeight) return p;
110
+ }
111
+ return null;
112
+ }
113
+ // A layout effect in the browser; on a server render (a gate's static markup) nothing to measure, and no warning.
114
+ const useBrowserLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
115
+ const reducedMotion = () => typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
116
+ const hasContent = (n: React.ReactNode): boolean => (Array.isArray(n) ? n.some(hasContent) : n !== null && n !== undefined && n !== false && n !== "");
117
+ /** What a jump focuses in a cluster: its first group's head or control. */
118
+ const FOCUSABLE = ".gemboss-ei-gh, button, input, select, textarea";
119
+
120
+ /** A form's static group inside the frame (InspectorGroup `collapsible={false}` asks for it): the frame's open group, its title the
121
+ * frame's group title. One look for every group in the frame, decided where the group is drawn. */
122
+ const FramedStatic: FramedStaticGroup = ({ title, hint, attrs, children }) => (
123
+ <div className="gemboss-ei-grp" role="group" aria-label={typeof title === "string" ? title : undefined} {...attrs}>
124
+ {title ? <div className="gemboss-ei-openhead" data-ei-head=""><span>{title}</span></div> : null}
125
+ {children}
126
+ {hint ? <p className="gemboss-ei-hint">{hint}</p> : null}
127
+ </div>
128
+ );
129
+
130
+ export function InspectorFrame({ head, search, aside, lead, clusters, results, searching = false, indexAttrs }: InspectorFrameProps) {
131
+ // The index under the box; its parent holds the clusters it jumps to (this panel's, not another one on the screen).
132
+ const [indexEl, setIndexEl] = useState<HTMLElement | null>(null);
133
+ // The cluster the panel stands in (element review C34, Chris 31/10: "bấm … không biết nó nhảy đi đâu"), kept as the panel scrolls: the
134
+ // last cluster whose name is above the top third of the panel's view. Not "the last one at the end": the clusters after Look are short,
135
+ // so the end shows two or three of them and the one being read is the one near the top.
136
+ const first = clusters[0]?.id ?? "look";
137
+ const [here, setHere] = useState(first);
138
+ // A jump from the index is where the panel stands until the seller scrolls by hand: while its smooth scroll runs, and while the panel
139
+ // rests where it took it (a jump to Layout near the end rests with Visibility and Code in view too).
140
+ const jumped = useRef<{ cluster: string; top: number; at: number } | null>(null);
141
+ // Read again when a jump's smooth scroll has had its time (nothing else would: the panel may rest there).
142
+ const readHere = useRef<() => void>(() => {});
143
+ // The box that scrolls the panel: found again after each drawing (it may start to scroll only once the panel's content is read), and
144
+ // the listeners attached only when it is another box.
145
+ const [box, setBox] = useState<HTMLElement | null>(null);
146
+ useBrowserLayoutEffect(() => {
147
+ const b = indexEl && !searching ? scrollerOf(indexEl) : null;
148
+ if (b !== box) setBox(b);
149
+ });
150
+ const firstRef = useRef(first);
151
+ firstRef.current = first;
152
+ useEffect(() => {
153
+ if (!box || !indexEl) return undefined;
154
+ let frame = 0;
155
+ const read = () => {
156
+ frame = 0;
157
+ const j = jumped.current;
158
+ if (j && (performance.now() - j.at < 1000 || Math.abs(box.scrollTop - j.top) < 4)) { setHere(j.cluster); return; }
159
+ jumped.current = null;
160
+ const line = box.getBoundingClientRect().top + box.clientHeight / 3;
161
+ const labels = [...(indexEl.parentElement?.querySelectorAll<HTMLElement>(":scope > [data-panel-cluster]") ?? [])];
162
+ const passed = labels.filter((l) => l.getBoundingClientRect().top <= line);
163
+ setHere(passed.at(-1)?.getAttribute("data-panel-cluster") ?? firstRef.current);
164
+ };
165
+ readHere.current = read;
166
+ const onScroll = () => { if (!frame) frame = requestAnimationFrame(read); };
167
+ // The seller's own hand (wheel, touch, a key, a press on the scrollbar) lets a jump go at once.
168
+ const byHand = () => { jumped.current = null; };
169
+ box.addEventListener("scroll", onScroll, { passive: true });
170
+ for (const t of ["wheel", "touchstart", "keydown", "pointerdown"] as const) box.addEventListener(t, byHand, { passive: true });
171
+ return () => {
172
+ box.removeEventListener("scroll", onScroll);
173
+ for (const t of ["wheel", "touchstart", "keydown", "pointerdown"] as const) box.removeEventListener(t, byHand);
174
+ if (frame) cancelAnimationFrame(frame);
175
+ };
176
+ }, [box, indexEl]);
177
+ if (results) return <div className="gemboss-ei-frame" data-settings-frame=""><StaticGroupInFrame.Provider value={FramedStatic}>{head}{search}{aside}{results}</StaticGroupInFrame.Provider></div>;
178
+ const shown = clusters.filter((c) => c.on ?? hasContent(c.content));
179
+ // One press away, as far down as it stands: the cluster's name at the top of the panel, the focus on its first control, the cluster's
180
+ // own first (a section's words, who it is for), and never past its end.
181
+ const jumpTo = (cluster: string) => {
182
+ const panel = indexEl?.parentElement;
183
+ const label = panel?.querySelector(`:scope > [data-panel-cluster="${cluster}"]`);
184
+ if (!(label instanceof HTMLElement)) return;
185
+ // The panel's own scroller moves, not the page around it: scrollIntoView moves every scrolling box up the tree.
186
+ const scroller = scrollerOf(label);
187
+ const top = scroller ? Math.min(scroller.scrollTop + label.getBoundingClientRect().top - scroller.getBoundingClientRect().top, scroller.scrollHeight - scroller.clientHeight) : 0;
188
+ jumped.current = { cluster, top, at: performance.now() };
189
+ scroller?.scrollTo({ top, behavior: reducedMotion() ? "auto" : "smooth" });
190
+ setHere(cluster);
191
+ setTimeout(() => readHere.current(), 1050);
192
+ for (let n = label.nextElementSibling; n && !n.hasAttribute("data-panel-cluster"); n = n.nextElementSibling) {
193
+ if ((n as HTMLElement).hidden) continue;
194
+ const to = n.matches(FOCUSABLE) ? n : n.querySelector<HTMLElement>(FOCUSABLE);
195
+ if (to instanceof HTMLElement) { to.focus({ preventScroll: true }); break; }
196
+ }
197
+ };
198
+ const index = shown.length > 1 ? (
199
+ <nav ref={setIndexEl} className="gemboss-ei-index" aria-label="Jump to" data-settings-index="" hidden={searching || undefined} {...indexAttrs}>
200
+ {/* The dot between two links is drawn, not said, and is not part of either target. */}
201
+ {shown.map((c, n) => <Fragment key={c.id}>{n ? <span className="gemboss-ei-index-dot" aria-hidden="true">·</span> : null}
202
+ <button type="button" className="gemboss-ei-index-link" onClick={() => jumpTo(c.id)} data-jump={c.id}
203
+ aria-current={here === c.id ? "location" : undefined}>{c.label ?? INSPECTOR_CLUSTERS[c.id] ?? c.id}</button></Fragment>)}
204
+ </nav>
205
+ ) : null;
206
+ return (
207
+ <div className="gemboss-ei-frame" data-settings-frame="" data-searching={searching ? "" : undefined}>
208
+ <StaticGroupInFrame.Provider value={FramedStatic}>
209
+ {head}{search}{index}{aside}{lead}
210
+ {shown.map((c) => <Fragment key={c.id}><InspectorClusterBreak cluster={c.id} label={c.label} first={c === shown[0]} hidden={searching} />{c.content}</Fragment>)}
211
+ </StaticGroupInFrame.Provider>
212
+ </div>
213
+ );
214
+ }
215
+
216
+ /** A part of the panel that is not one of its groups (a section's words, its own options, who it is for): in its place in its cluster,
217
+ * `hidden` while a search does not find it, never drawn again from nothing (what it read and its controls are kept). display: contents. */
218
+ export function InspectorFramePart({ partKey, hidden = false, partRef, children }: {
219
+ partKey: string; hidden?: boolean; partRef?: React.Ref<HTMLDivElement>; children?: React.ReactNode;
220
+ }) {
221
+ return <div className="gemboss-ei-part" data-frame-part={partKey} hidden={hidden || undefined} ref={partRef}>{children}</div>;
222
+ }
223
+
224
+ // ── InspectorFrameGroup ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────
225
+
226
+ export interface InspectorFrameGroupProps {
227
+ groupKey: string;
228
+ /**
229
+ * `open`: always shown (the type and the space round it, an element's own groups): its name and note, no fold, no target's height.
230
+ * `add`: it holds nothing: its name and a +, the whole line the target (Figma's empty section); `chip` inside InspectorChips, a pill.
231
+ * `added`: it holds a value, or + showed it: its rows under its name and a − in the place the + was.
232
+ * ONE component for the three, so a group that changes state stays the same element in the same place: pressed, a chip draws whole
233
+ * where it was and the focus stays in it (Control UI C33); a remount dropped the focus to the page.
234
+ */
235
+ state: "open" | "add" | "added";
236
+ title: string;
237
+ note?: React.ReactNode;
238
+ /** Its accessible name where it is not the title (open and added groups are named groups). */
239
+ label?: string;
240
+ /** `add`: what + does, and its accessible name (default "Add <title>"). */
241
+ onAdd?: (e: React.MouseEvent<HTMLButtonElement>) => void;
242
+ addLabel?: string;
243
+ chip?: boolean;
244
+ /** `added`: the −. Absent where it would write nothing (a value held on another screen keeps the group added). */
245
+ remove?: { label: string; onRemove: (e: React.MouseEvent<HTMLButtonElement>) => void } | null;
246
+ /** `added`: small actions before the − (Play, Preview). */
247
+ acts?: React.ReactNode;
248
+ /** + and − wait while a write runs. */
249
+ disabled?: boolean;
250
+ children?: React.ReactNode;
251
+ }
252
+
253
+ export function InspectorFrameGroup({ groupKey, state, title, note, label, onAdd, addLabel, chip = false, remove, acts, disabled, children }: InspectorFrameGroupProps) {
254
+ const noteNode = note ? <small className="gemboss-ei-gh-note"> · {note}</small> : null;
255
+ if (state === "add") return (
256
+ <div className="gemboss-ei-grp gemboss-ei-addline" data-add-group={groupKey} data-chip={chip ? "" : undefined}>
257
+ <button type="button" className="gemboss-ei-addhead" disabled={disabled} onClick={onAdd} aria-label={addLabel ?? `Add ${title.toLowerCase()}`}>
258
+ <span>{title}</span><span className="gemboss-ei-addplus" aria-hidden="true">+</span>
259
+ </button>
260
+ </div>
261
+ );
262
+ if (state === "open") return (
263
+ <div className="gemboss-ei-grp" data-open-group={groupKey} role="group" aria-label={label ?? title}>
264
+ <div className="gemboss-ei-openhead" data-ei-head=""><span>{title}{noteNode}</span></div>
265
+ {children}
266
+ </div>
267
+ );
268
+ return (
269
+ <div className="gemboss-ei-grp" data-added-group={groupKey} role="group" aria-label={label ?? title}>
270
+ <div className="gemboss-ei-addedhead" data-ei-head="">
271
+ <span>{title}{noteNode}</span>
272
+ {acts || remove ? (
273
+ <span className="gemboss-ei-headacts">
274
+ {acts}
275
+ {remove ? (
276
+ <button type="button" className="gemboss-ei-addsign" disabled={disabled} onClick={remove.onRemove} aria-label={remove.label}
277
+ data-remove-group={groupKey}>−</button>
278
+ ) : null}
279
+ </span>
280
+ ) : null}
281
+ </div>
282
+ {children}
283
+ </div>
284
+ );
285
+ }
@@ -0,0 +1,79 @@
1
+ // WHERE A SETTING'S LABEL GOES IS DECIDED BY ITS CONTROL, IN THIS ONE TABLE (Chris 04/11/2026: "đi theo hướng side bên, gọn
2
+ // hơn"; 05/11/2026, as GemPages draws it: label left, control right for every single-value setting). A control that holds one value
3
+ // on one line has its label BESIDE it (`Field` adds `.gemboss-ei-fld--row`: label two parts, control three, editor.css). Only a
4
+ // control that needs the panel's width keeps its label ABOVE it, the control under it across the field.
5
+ //
6
+ // Measured before it was one table (05/11/2026, _local/gemboss/label-beside-audit-2026-11-05.md): 98 hand-built labelled rows in
7
+ // 30 admin files, 4 reading the admin's `labelBeside`, 29 setting `row` by hand, 64 setting nothing; every label on the wrong side
8
+ // was in one of the hand-decided ones. Now `Field` reads it (`control`), and so does every host that orders a list of settings by
9
+ // side, so the drawing and the order cannot disagree. Changing a control's side is one line here. The admin's gate
10
+ // `every-label-follows-its-control` renders every settings surface and fails on a label that is not on its control's side.
11
+ //
12
+ // No React here: a script or a non-React surface reads the same table.
13
+
14
+ /** Where a label sits: beside its control (one row), or above it (the control under it, across the field). */
15
+ export type LabelSide = "beside" | "above";
16
+
17
+ /** Every control a labelled setting is drawn with, by where its label goes. */
18
+ export const LABEL_SIDE = {
19
+ // ONE ROW: the label left, the control right.
20
+ /** A list of choices (a native select, or chips too wide for the row drawn as one). */
21
+ select: "beside",
22
+ /** A row of chips that fits the control column (glyphs, or up to three short words). */
23
+ chips: "beside",
24
+ /** On / Off. */
25
+ toggle: "beside",
26
+ /** One colour: its swatch and its value. */
27
+ color: "beside",
28
+ /** A number with named values (chips, a box, a slider: ValueControl). */
29
+ value: "beside",
30
+ /** A number box. */
31
+ number: "beside",
32
+ /** A slider and its value. */
33
+ range: "beside",
34
+ /** One button that opens a picker (a ratio, an icon, a font). */
35
+ pick: "beside",
36
+ /** A one-line text box (a CSS class, a condition's expression, a heading's words in a list). Chris 05/11/2026: beside, as GemPages. */
37
+ text: "beside",
38
+ /** Where a click goes: a box and its Choose. */
39
+ link: "beside",
40
+ /** A date and time. */
41
+ date: "beside",
42
+ // THE PANEL'S WIDTH: the label above, the control under it.
43
+ /** A text of several lines (a description, custom CSS). */
44
+ textarea: "above",
45
+ /** A list of items, each a row of its own. */
46
+ list: "above",
47
+ /** Four sides (padding, margin). */
48
+ edges: "above",
49
+ /** A picture or a video, and its actions. */
50
+ image: "above",
51
+ /** Choices drawn as pictures (a layout, an icon set). */
52
+ tiles: "above",
53
+ /** A gradient's editor (Solid / Gradient and its stops). */
54
+ gradient: "above",
55
+ /** A shape drawn on a picture (a print area). */
56
+ drawing: "above",
57
+ /** A line of code (a condition's expression): it reads whole across the field, not cut in the control column. */
58
+ code: "above",
59
+ // ABOVE FOR NOW: the decision is here, not in the host, so what is drawn and the table agree until the control is reworked.
60
+ /** Which screens show it (Desktop · Tablet · Mobile): three chips in words, too wide for the row. Three device glyphs beside the
61
+ * label move it to `chips` (slice 2 of the label-side work, decision E). */
62
+ screens: "above",
63
+ /** A font's one button (an "Aa" in the font, its name, CSS): a name needs the width (FontPickerField). It follows `pick` in a later
64
+ * slice (decision C); the element panel's Font is a list (`select`), beside. */
65
+ "font-pick": "above",
66
+ } as const satisfies Record<string, LabelSide>;
67
+
68
+ /** The controls the table knows (`Field`'s `control`). */
69
+ export type FieldControlKind = keyof typeof LABEL_SIDE;
70
+
71
+ /** Where the label of a setting drawn with this control goes. */
72
+ export function labelSide(control: FieldControlKind): LabelSide {
73
+ return LABEL_SIDE[control];
74
+ }
75
+
76
+ /** Whether a value is one of the table's controls (a script reading a control's name from markup). */
77
+ export function isFieldControlKind(value: unknown): value is FieldControlKind {
78
+ return typeof value === "string" && Object.prototype.hasOwnProperty.call(LABEL_SIDE, value);
79
+ }
@@ -5,8 +5,10 @@
5
5
  // InspectorGroup's own open/closed when the caller does not hold it. Controls (Seg, Color, Range, EdgeBox, Image) are
6
6
  // controls.tsx: their own module, because only a screen that edits values draws them.
7
7
  import "../editor.css"; // its own stylesheet travels with it (0.23.0): a surface that never renders it never loads it
8
- import { useId, useState } from "react";
8
+ import { useContext, useId, useState } from "react";
9
9
  import type React from "react";
10
+ import { labelSide, type FieldControlKind } from "./label-side";
11
+ import { StaticGroupInFrame } from "./frame-context";
10
12
 
11
13
  // ── PanelTabs ───────────────────────────────────────────────────────────────────────────────────────────────────────
12
14
 
@@ -125,7 +127,8 @@ export interface InspectorGroupProps {
125
127
  /**
126
128
  * Default true: the inspector's group, `.gemboss-ei-grp` with a header BUTTON (▾ / ▸, `aria-expanded`); closed, CSS
127
129
  * hides everything after the header (`.gemboss-ei-grp>.gemboss-ei-gh[data-open="closed"]~*`), so the body stays mounted.
128
- * `false`: the schema form's static group, `section.gemboss-ei-group` with an `h4.gemboss-ei-grouphead` (no toggle).
130
+ * `false`: the schema form's static group, `section.gemboss-ei-group` with an `h4.gemboss-ei-grouphead` (no toggle); inside a settings
131
+ * frame (InspectorFrame) the frame's open group, `.gemboss-ei-grp` with its `.gemboss-ei-openhead`.
129
132
  */
130
133
  collapsible?: boolean;
131
134
  /** A muted line after the body (`p.gemboss-ei-hint`). */
@@ -141,7 +144,11 @@ export interface InspectorGroupProps {
141
144
 
142
145
  export function InspectorGroup({ title, note, open, defaultOpen = true, onOpenChange, collapsible = true, hint, attrs, children }: InspectorGroupProps) {
143
146
  const [own, setOwn] = useState(defaultOpen);
147
+ // Inside a settings frame (InspectorFrame), a static group is the frame's open group: one look for every group in the frame, decided
148
+ // here rather than restyled from outside (one settings frame, 06/11/2026).
149
+ const Framed = useContext(StaticGroupInFrame);
144
150
  const hintNode = hint ? <p className="gemboss-ei-hint">{hint}</p> : null;
151
+ if (!collapsible && Framed) return <Framed title={title} hint={hint} attrs={attrs}>{children}</Framed>;
145
152
  if (!collapsible) {
146
153
  return (
147
154
  <section className="gemboss-ei-group" {...attrs}>
@@ -177,8 +184,13 @@ export interface FieldProps {
177
184
  /** The setting's help (`p.gemboss-ei-hint.gemboss-ei-help-text`). In a plugin's form a line under the control; inside an
178
185
  * inspector group (`InspectorGroup`) a ? beside the label opens and closes it (0.39.0). */
179
186
  hint?: React.ReactNode;
180
- /** A one-value setting (a number, a select, a colour, chips): inside an inspector group the label goes LEFT and the control
181
- * right, one row (0.39.0). Outside a group nothing changes. */
187
+ /** The control this field holds (`LABEL_SIDE`, label-side.ts): its label goes on that control's side. A one-value control (a
188
+ * select, chips, a toggle, a colour, a number, a one-line text box, a link, a date, a picker's button) has its label LEFT and
189
+ * the control right, one row; a control that needs the field's width (a long text, a list, four sides, a picture, tiles, a
190
+ * gradient, a drawing, a line of code) has it above. Anywhere: in an inspector group, a drawer or a card (05/11/2026, unreleased). */
191
+ control?: FieldControlKind;
192
+ /** @deprecated Say the `control` instead: the table decides its side, so a host never decides it by hand. Kept for surfaces
193
+ * pinned to an older kit; ignored when `control` is given. */
182
194
  row?: boolean;
183
195
  /** A control that belongs to the label line, at its right (a spacing field's mode switch, Control UI C02). Beside the label, not
184
196
  * in it: a label may hold no other control. */
@@ -203,11 +215,16 @@ export interface FieldProps {
203
215
  * There a `row` is label left, control right (GemPages: 52px a setting), the label is quiet (bodyMd, secondary) and the help
204
216
  * is behind a ? (GemPages, PageFly). Outside a group, a plugin's settings form, a help line under a wide field is the
205
217
  * Polaris form and stays.
218
+ *
219
+ * WHICH SIDE THE LABEL IS ON is the control's (`control`, the one table in label-side.ts: Chris 05/11/2026), never the host's:
220
+ * beside it in a group, a drawer or a card alike (05/11/2026, unreleased: the row was laid out only inside a group, so the page settings drawer's
221
+ * three lists stacked under labels that asked to sit beside them).
206
222
  */
207
- export function Field({ label, htmlFor, labelValue, hint, row = false, aside, mark, className, style, onBlurCapture, children }: FieldProps) {
223
+ export function Field({ label, htmlFor, labelValue, hint, control, row = false, aside, mark, className, style, onBlurCapture, children }: FieldProps) {
208
224
  const helpId = useId();
209
225
  const [helpOpen, setHelpOpen] = useState(false);
210
- const cls = ["gemboss-ei-fld", row && label != null ? "gemboss-ei-fld--row" : "", className].filter(Boolean).join(" ");
226
+ const beside = control ? labelSide(control) === "beside" : row;
227
+ const cls = ["gemboss-ei-fld", beside && label != null ? "gemboss-ei-fld--row" : "", className].filter(Boolean).join(" ");
211
228
  const labelNode = label != null ? (
212
229
  <label htmlFor={htmlFor}>{label}{labelValue != null ? <span className="gemboss-ei-rangeval">{labelValue}</span> : null}</label>
213
230
  ) : null;
@@ -65,18 +65,24 @@ export interface KeyedRows<T> {
65
65
  * (its answer decides). Without an answer what was written stays shown until the stored list says otherwise.
66
66
  * · the stored list is read by CONTENT: a caller that hands a new array each render (`rows ?? []`) does not reset what is
67
67
  * shown (review of #4506: a row added to an unset list vanished).
68
- * · a stored list equal to one of our writes is that write coming back: what is shown (maybe newer) stays; any other is a
68
+ * · a stored list equal to one of our writes (in any key order: `spelled`) is that write coming back: what is shown (maybe newer)
69
+ * stays; any other is a
69
70
  * change from elsewhere (an undo, the chat) and replaces it, the keys kept by position.
70
71
  * · `commit` is told where each row came from (`how.from[i]`: the place row i had in the list before this change, -1 for a new
71
72
  * one; a duplicate names its original) and how many rows there were (`how.was`), so a host that keeps something per row (a
72
73
  * tab's column of elements, Control UI C41) moves it with the row instead of guessing from the rows' words.
73
74
  */
74
75
  export type KeyedChange = { from: number[]; was: number };
76
+ /** A list's text with each object's keys in one order. The store may answer a row in its own spelling (Postgres JSONB orders an
77
+ * object's keys by length), and that is still our write coming back: read as a change from elsewhere, it dropped the newer
78
+ * write still on its way, so of two quick Adds one was lost (the page editor's elements fold, 07/11/2026). */
79
+ const spelled = (value: unknown): string => JSON.stringify(value, (_key, v: unknown) => v && typeof v === "object" && !Array.isArray(v)
80
+ ? Object.fromEntries(Object.keys(v).sort().map((k) => [k, (v as Record<string, unknown>)[k]])) : v);
75
81
  export function useKeyedRows<T>(value: readonly T[], commit: (next: T[], how: KeyedChange) => false | void | PromiseLike<unknown>): KeyedRows<T> {
76
82
  const [state, setState] = useState(() => ({ rows: value.slice(), keys: value.map(() => freshKey()) }));
77
83
  const latest = useRef(state);
78
84
  latest.current = state;
79
- const seen = JSON.stringify(value);
85
+ const seen = spelled(value);
80
86
  // The stored list, its text, and the keys it is shown with: what a refused write goes back to.
81
87
  const stored = useRef<{ rows: readonly T[]; json: string; keys: string[] }>({ rows: value, json: seen, keys: state.keys });
82
88
  // Our writes on their way, oldest first.
@@ -108,7 +114,7 @@ export function useKeyedRows<T>(value: readonly T[], commit: (next: T[], how: Ke
108
114
  const write = (rows: T[], keys: string[], from: number[]) => {
109
115
  const before = latest.current, previousWrite = writes.current;
110
116
  const n = ++writeSequence.current; writes.current = n;
111
- pending.current.push({ n, json: JSON.stringify(rows), keys });
117
+ pending.current.push({ n, json: spelled(rows), keys });
112
118
  latest.current = { rows, keys };
113
119
  setState(latest.current);
114
120
  const answer = commit(rows, { from, was: before.rows.length });
@@ -0,0 +1 @@
1
+ .gemboss-ei-frame{display:contents}.gemboss-ei-find{margin-bottom:8px}.gemboss-ei-index{display:flex;flex-wrap:wrap;align-items:center;gap:0 4px;margin:-4px 0 8px}.gemboss-ei-index-link{min-height:24px;padding:0 4px;border:0;border-radius:4px;background:none;font:inherit;font-size:11px;line-height:16px;color:var(--gemboss-text-muted);cursor:pointer}.gemboss-ei-index-link:hover{color:var(--gemboss-text);background:var(--gemboss-hover)}.gemboss-ei-index-link:focus-visible{outline:2px solid var(--ui-focus,#5661f5);outline-offset:2px}.gemboss-ei-index-link[aria-current]{color:var(--gemboss-text);font-weight:600}.gemboss-ei-index-dot{font-size:11px;line-height:16px;color:var(--gemboss-text-muted)}.gemboss-ei-cluster{display:flex;align-items:flex-end;height:calc(var(--gemboss-ei-gap-group,16px)*2 + 1px + 16px);margin:0}.gemboss-ei-cluster--first{height:auto;margin:0 0 -8px}.gemboss-ei-cluster-name{font-size:11px;line-height:16px;font-weight:600;letter-spacing:.06em;text-transform:uppercase;color:var(--gemboss-text-muted)}.gemboss-ei-part{display:contents}.gemboss-ei-part>.gemboss-ei-grp:last-child{border-bottom:1px solid var(--gemboss-divider-soft)}.gemboss-ei-part:last-child>.gemboss-ei-grp:last-child{border-bottom:none}.gemboss-ei-part[hidden],.gemboss-ei-index[hidden],.gemboss-ei-cluster[hidden]{display:none}.gemboss-ei-addhead{display:flex;align-items:center;justify-content:space-between;width:100%;min-height:28px;padding:0;border:0;background:none;font:inherit;font-size:13px;line-height:20px;color:var(--gemboss-text-muted);cursor:pointer;text-align:left}.gemboss-ei-addhead:hover{color:var(--gemboss-text)}.gemboss-ei-addhead:focus-visible{outline:2px solid var(--ui-focus,#5661f5);outline-offset:2px;border-radius:4px}.gemboss-ei-addhead:disabled{cursor:default}.gemboss-ei-addplus{display:grid;place-items:center;width:24px;height:24px;border-radius:8px;font-size:16px;line-height:1}.gemboss-ei-addline[data-chip] .gemboss-ei-addplus{width:auto;height:auto;font-size:13px;color:var(--gemboss-text-muted);background:none}.gemboss-ei-addline:not([data-chip]) .gemboss-ei-addhead{width:calc(100% + 16px);margin-inline:-8px;padding-inline:8px;border-radius:8px}.gemboss-ei-addline:not([data-chip]) .gemboss-ei-addhead:hover:not(:disabled){background:var(--gemboss-hover)}.gemboss-ei-addline:not([data-chip]) .gemboss-ei-addhead:active:not(:disabled),.gemboss-ei-addline[data-chip] .gemboss-ei-addhead:active:not(:disabled){background:var(--gemboss-active-bg)}.gemboss-ei-grp.gemboss-ei-addline:not([data-chip]){padding:4px 0}.gemboss-ei-addedhead{display:flex;align-items:center;justify-content:space-between;gap:6px;min-height:28px;font-size:13px;line-height:20px;font-weight:650;color:var(--gemboss-text)}.gemboss-ei-openhead{font-size:13px;line-height:20px;font-weight:650;color:var(--gemboss-text)}.gemboss-ei-headacts{display:flex;align-items:center;gap:4px}.gemboss-ei-addsign{display:grid;place-items:center;flex:none;width:24px;height:24px;padding:0;border:0;border-radius:8px;background:none;font:inherit;font-size:16px;font-weight:400;line-height:1;color:var(--gemboss-text-muted);cursor:pointer}.gemboss-ei-addsign:hover{background:var(--gemboss-hover);color:var(--gemboss-text)}.gemboss-ei-addsign:focus-visible{outline:2px solid var(--ui-focus,#5661f5);outline-offset:2px}.gemboss-ei-addsign:active:not(:disabled){background:var(--gemboss-active-bg)}.gemboss-ei-addsign:disabled{cursor:default;opacity:.5}@media (pointer: coarse),(max-width:47.9975em){.gemboss-ei-index-link{min-width:44px;min-height:44px}.gemboss-ei-addhead,.gemboss-ei-addedhead{min-height:44px}.gemboss-ei-addsign{width:44px;height:44px}.gemboss-ei-grp.gemboss-ei-addline:not([data-chip]){padding:2px 0}}