@gemboss/ui 0.66.0 → 0.68.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.
@@ -12,7 +12,8 @@
12
12
  // `base()` (the kit's own control for that kind, for an app that draws a kit kind its way only sometimes). A kind no one draws is a visible
13
13
  // "no control" line, never a text box that seems to work. A choice's `glyph` is drawn as the app's picture by that name (`glyphs`).
14
14
  import "../editor.css"; // its own stylesheet travels with it: a surface that never renders a form never loads it
15
- import { createContext, useContext, useState, type ChangeEvent, type CSSProperties, type FocusEventHandler, type KeyboardEvent, type ReactNode } from "react";
15
+ import "../editor-grow.css"; // the line that grows with its text (GrowLine), its own entry
16
+ import { createContext, useContext, useState, type ChangeEvent, type FocusEventHandler, type KeyboardEvent, type ReactNode } from "react";
16
17
  import { ColorChoicesContext } from "./color-choices";
17
18
  import { ChipButton, ColorControl, ImageControl, RangeControl, Seg, UnitField } from "./controls";
18
19
  import {
@@ -21,7 +22,9 @@ import {
21
22
  } from "./field-spec";
22
23
  import { labelSide, type FieldControlKind } from "./label-side";
23
24
  import { useOnNewValue } from "./new-value";
25
+ import { useGrowToText } from "./grow-to-text";
24
26
  import { Field, InspectorGroup } from "./panel";
27
+ import { ItemsField } from "./items-field";
25
28
 
26
29
  // ── An app's kinds ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────
27
30
 
@@ -81,7 +84,7 @@ export function controlOf(field: AnyFieldSpec, value?: unknown, rules?: FieldKin
81
84
  case "color": return "color";
82
85
  case "range": return "range";
83
86
  case "number": return "number";
84
- case "text": return "text";
87
+ case "text": return f.code ? "code" : "text";
85
88
  case "textarea": return "textarea";
86
89
  case "image": return "image";
87
90
  case "repeater": return "list";
@@ -125,6 +128,12 @@ export type FieldControlProps = {
125
128
  onDraft?: (v: unknown) => void;
126
129
  /** A host's refusal before a numeric control normalizes its raw draft on blur; no wrapper is added. */
127
130
  onBlurCapture?: FocusEventHandler<HTMLDivElement>;
131
+ /** A line in sight under the control, across the field (not behind the ?, which is the setting's help): what a switch does, why a
132
+ * list has nothing to offer. The control is described by it (its id `<control id>-note`). Honoured by select and toggle. */
133
+ note?: ReactNode;
134
+ /** The id of a `<datalist>` the host draws once for many boxes (a menu's addresses: its store pages and collections), offered as the
135
+ * box is typed in. Honoured by text. */
136
+ listId?: string;
128
137
  /** The app's kinds (FieldKindsProvider by default). */
129
138
  kinds?: FieldKinds;
130
139
  /** The app's glyphs (FieldKindsProvider by default). */
@@ -155,9 +164,13 @@ export function FieldControl(props: FieldControlProps) {
155
164
  }
156
165
 
157
166
  function kitControl(p: Drawn): ReactNode {
158
- const { value, onChange, disabled, onPickImage, onDraft, onBlurCapture, inputId, mark, labelMark, describedBy, shopId, colorDrafts = false, labelHidden = false, invalid = false, kinds, glyphs, id, lbl, named, ariaLabel } = p;
167
+ const { value, onChange, disabled, onPickImage, onDraft, onBlurCapture, inputId, mark, labelMark, shopId, listId, note, colorDrafts = false, labelHidden = false, invalid = false, kinds, glyphs, id, lbl, named, ariaLabel } = p;
159
168
  if (!isKitFieldKind(p.field.kind)) return <UnknownKind field={p.field} named={named} />;
160
169
  const field = p.field as FieldSpec;
170
+ // A note under a select or a switch: in the field (a row's note spans it, editor.css), and what the control is described by.
171
+ const noteId = note != null && (field.kind === "select" || field.kind === "toggle") ? `${id}-note` : undefined;
172
+ const describedBy = [p.describedBy, noteId].filter(Boolean).join(" ") || undefined;
173
+ const noteLine = noteId ? <p className="gemboss-ei-hint" id={noteId}>{note}</p> : null;
161
174
  switch (field.kind) {
162
175
  case "toggle": {
163
176
  const on = value === true || value === "true";
@@ -165,8 +178,9 @@ function kitControl(p: Drawn): ReactNode {
165
178
  // The seam's `info` for a checkbox is `hint`. It fills the control column like every segmented row (control standard §13b: one
166
179
  // width rule).
167
180
  <Field label={named} className="togrow" hint={field.hint} control="toggle" mark={labelMark}>
168
- <Seg<"on" | "off"> label={lbl} value={on ? "on" : "off"} disabled={disabled} onChange={(v) => onChange(v === "on")}
181
+ <Seg<"on" | "off"> label={lbl} value={on ? "on" : "off"} disabled={disabled} describedBy={describedBy} onChange={(v) => onChange(v === "on")}
169
182
  options={[{ value: "on", label: field.onLabel ?? "On" }, { value: "off", label: field.offLabel ?? "Off" }]} />
183
+ {noteLine}
170
184
  </Field>
171
185
  );
172
186
  }
@@ -183,8 +197,12 @@ function kitControl(p: Drawn): ReactNode {
183
197
  {/* Nothing stored: said, not the first option shown as if chosen. Picking an option then writes it. A clearable list keeps it
184
198
  as a choice. */}
185
199
  {(cur === "" || field.clearable) && !field.options.some((o) => o.value === "") ? <option value="" disabled={!field.clearable}>Not set</option> : null}
186
- {field.options.map((o) => <option key={o.value} value={o.value}>{o.label ?? labelize(o.value)}</option>)}
200
+ {optionRuns(field.options).map((run) => {
201
+ const opts = run.options.map((o) => <option key={o.value} value={o.value} disabled={o.disabled || undefined}>{o.label ?? labelize(o.value)}</option>);
202
+ return run.group === undefined ? opts : <optgroup key={`${run.group}-${run.options[0]!.value}`} label={run.group}>{opts}</optgroup>;
203
+ })}
187
204
  </select>
205
+ {noteLine}
188
206
  </Field>
189
207
  );
190
208
  }
@@ -209,7 +227,7 @@ function kitControl(p: Drawn): ReactNode {
209
227
  return (
210
228
  // Here the chips fit the row's control column (3/5 of the field, chipsFitBeside): more, or longer labels, are a list.
211
229
  <Field label={named} hint={field.hint} control="chips" mark={labelMark}>
212
- <Seg label={lbl} value={shown} disabled={disabled} onChange={(v) => { if (v !== shown) onChange(v); else if (field.clearable) onChange(""); }}
230
+ <Seg label={lbl} value={shown} disabled={disabled} describedBy={describedBy} onChange={(v) => { if (v !== shown) onChange(v); else if (field.clearable) onChange(""); }}
213
231
  options={field.options.map((o, i) => (o.glyph
214
232
  ? { value: o.value, label: pictures[i] ?? o.label ?? labelize(o.value), name: o.label ?? labelize(o.value) }
215
233
  : { value: o.value, label: o.label ?? labelize(o.value), ...(o.name ? { name: o.name } : {}) }))} />
@@ -226,17 +244,31 @@ function kitControl(p: Drawn): ReactNode {
226
244
  case "range":
227
245
  return <RangeField id={id} label={lbl} field={field} value={value} disabled={disabled} onCommit={onChange} onBlurCapture={onBlurCapture} labelMark={labelMark} />;
228
246
  case "repeater":
229
- return <RepeaterField label={lbl} field={field} value={Array.isArray(value) ? (value as Array<Record<string, unknown>>) : []} disabled={disabled} onChange={onChange} />;
247
+ // The kit's Items control (items-field.tsx): one write of the whole list per change, each row's other keys kept.
248
+ return <ItemsField label={lbl} field={field} value={value} disabled={disabled} onChange={(next) => onChange(next)} idPrefix={id}
249
+ shopId={shopId} onPickImage={onPickImage} kinds={kinds} glyphs={glyphs} />;
230
250
  case "textarea":
231
251
  case "number":
232
252
  case "text":
233
- return <TextField id={id} label={named} field={field} value={value} disabled={disabled} onCommit={onChange} onDraft={onDraft} onBlurCapture={onBlurCapture} describedBy={describedBy} labelMark={labelMark} ariaLabel={ariaLabel} invalid={invalid} />;
253
+ return <TextField id={id} label={named} field={field} value={value} disabled={disabled} onCommit={onChange} onDraft={onDraft} onBlurCapture={onBlurCapture} describedBy={describedBy} labelMark={labelMark} ariaLabel={ariaLabel} invalid={invalid} listId={field.kind === "text" ? listId : undefined} />;
234
254
  default:
235
255
  // A kit kind with no drawing here yet: said in sight, as any kind no one draws.
236
256
  return <UnknownKind field={p.field} named={named} />;
237
257
  }
238
258
  }
239
259
 
260
+ /** A list's choices in runs, each run's `group` its heading (`<optgroup>`) or none: a group named again after another one is a second
261
+ * heading, so the choices keep the order the host gave. */
262
+ function optionRuns<O extends { group?: string }>(options: readonly O[]): Array<{ group?: string; options: O[] }> {
263
+ const runs: Array<{ group?: string; options: O[] }> = [];
264
+ for (const o of options) {
265
+ const last = runs.at(-1);
266
+ if (last && last.group === o.group) last.options.push(o);
267
+ else runs.push({ group: o.group, options: [o] });
268
+ }
269
+ return runs;
270
+ }
271
+
240
272
  /** A kind no one draws here (an app's kind not registered in this form): said in sight, so a setting never goes missing in silence. */
241
273
  function UnknownKind({ field, named }: { field: AnyFieldSpec; named: ReactNode }) {
242
274
  return (
@@ -246,51 +278,16 @@ function UnknownKind({ field, named }: { field: AnyFieldSpec; named: ReactNode }
246
278
  );
247
279
  }
248
280
 
249
- function RepeaterField({ label, field, value, disabled, onChange }: {
250
- label: string;
251
- field: Extract<FieldSpec, { kind: "repeater" }>;
252
- value: Array<Record<string, unknown>>;
253
- disabled?: boolean;
254
- onChange: (v: unknown) => void;
255
- }) {
256
- const update = (i: number, key: string, v: string) => onChange(value.map((r, ri) => (ri === i ? { ...r, [key]: v } : r)));
257
- const add = () => onChange([...value, Object.fromEntries(field.item.map((f) => [f.key, ""]))]);
258
- const remove = (i: number) => onChange(value.filter((_, ri) => ri !== i));
259
- const rowStyle: CSSProperties = { display: "flex", gap: 6, alignItems: "flex-start", marginBottom: 6 };
260
- const fieldsStyle: CSSProperties = { display: "grid", gap: 4, flex: 1 };
261
- return (
262
- <Field label={label} hint={field.hint} control="list">
263
- {value.map((row, i) => (
264
- <div style={rowStyle} key={i}>
265
- <div style={fieldsStyle}>
266
- {field.item.map((it) => (
267
- it.long
268
- ? <textarea key={it.key} className="gemboss-field gemboss-ei-inp" rows={2} placeholder={it.label ?? labelize(it.key)} disabled={disabled}
269
- value={String(row[it.key] ?? "")} onChange={(e) => update(i, it.key, e.target.value)} />
270
- : <input key={it.key} className="gemboss-field gemboss-ei-inp" placeholder={it.label ?? labelize(it.key)} disabled={disabled}
271
- value={String(row[it.key] ?? "")} onChange={(e) => update(i, it.key, e.target.value)} />
272
- ))}
273
- </div>
274
- <button type="button" className="gemboss-control gemboss-control--icon gemboss-ei-inp"
275
- disabled={disabled} aria-label="Remove row" onClick={() => remove(i)}>×</button>
276
- </div>
277
- ))}
278
- <button type="button" className="gemboss-control gemboss-ei-inp" disabled={disabled} onClick={add}>+ {field.addLabel ?? "Add"}</button>
279
- </Field>
280
- );
281
- }
282
-
283
281
  /** Text / number / textarea: draft locally, commit on blur or Enter (never per keystroke, so a live preview isn't hammered while typing).
284
- * Numbers persist as numbers, else "" (reverts to default). */
285
- function TextField({ id, label, field, value, disabled, onCommit, onDraft, onBlurCapture, describedBy, labelMark, ariaLabel, invalid = false }: {
282
+ * Numbers persist as numbers, else "" (reverts to default). A number box steps with ↑ / ↓ as the browser's own number box does (by its
283
+ * `step`, 1 by default, held to its bounds; an empty box starts at its floor, else 0), each step a draft like a key typed. */
284
+ function TextField({ id, label, field, value, disabled, onCommit, onDraft, onBlurCapture, describedBy, labelMark, ariaLabel, invalid = false, listId }: {
286
285
  id: string; label: ReactNode; field: Extract<FieldSpec, { kind: "text" | "number" | "textarea" }>; ariaLabel?: string; invalid?: boolean;
287
286
  value: unknown; disabled?: boolean; onCommit: (v: unknown) => void; onDraft?: (v: unknown) => void;
288
- onBlurCapture?: FocusEventHandler<HTMLDivElement>; describedBy?: string; labelMark?: ReactNode;
287
+ onBlurCapture?: FocusEventHandler<HTMLDivElement>; describedBy?: string; labelMark?: ReactNode; listId?: string;
289
288
  }) {
290
289
  const norm = (v: unknown) => (v === undefined || v === null ? "" : String(v));
291
290
  const [draft, setDraft] = useState(norm(value));
292
- // A value from outside (Take latest, an Undo, the chat's write) replaces the draft while this renders, not in an effect a render later.
293
- useOnNewValue(() => setDraft(norm(value)), [value]);
294
291
  const isNum = field.kind === "number";
295
292
  // Bounds a setting declares (a 10..90 % scroll depth) are shown AND held: a value outside them is clamped on commit, so what the panel
296
293
  // keeps is what the storefront uses.
@@ -298,8 +295,16 @@ function TextField({ id, label, field, value, disabled, onCommit, onDraft, onBlu
298
295
  const hi = isNum ? field.max : undefined;
299
296
  // An unset bound is no bound: with `hi ?? n` the typed value was its own ceiling, so under a floor alone (min 1) a 0 stayed 0.
300
297
  const clamp = (n: number) => Math.min(hi ?? Infinity, Math.max(lo ?? -Infinity, n));
298
+ // A number as typed, a comma read as its point (the decimal keypad of a comma locale has no "."): "31,25" is 31.25, not a box left empty.
299
+ const read = (d: string) => Number(d.replace(",", "."));
300
+ // What a draft commits: the text, or a number as it reads, held to the bounds ("" for none).
301
+ const committed = (d: string) => (!isNum ? d : d.trim() !== "" && Number.isFinite(read(d)) ? String(clamp(read(d))) : "");
302
+ // A value from outside (Take latest, an Undo, the chat's write) replaces the draft while this renders, not in an effect a render later;
303
+ // but not the draft's own echo (a host that shows each draft at once hands it back): a "0" typed in a box held to 1 stays "0" while it is
304
+ // typed, and turns 1 when the box is left (review 09/11/2026: the box jumped to "1" under the seller's fingers).
305
+ useOnNewValue(() => { if (norm(value) !== committed(draft)) setDraft(norm(value)); }, [value]);
301
306
  const commit = () => {
302
- const next = isNum ? (draft !== "" && Number.isFinite(Number(draft)) ? clamp(Number(draft)) : "") : draft;
307
+ const next = isNum ? (draft !== "" && Number.isFinite(read(draft)) ? clamp(read(draft)) : "") : draft;
303
308
  // A clamped number can equal the stored value, so the host correctly skips that write.
304
309
  // Normalize the local draft too: without a new prop value, its effect cannot replace an invalid draft.
305
310
  if (isNum) setDraft(norm(next));
@@ -310,7 +315,16 @@ function TextField({ id, label, field, value, disabled, onCommit, onDraft, onBlu
310
315
  setDraft(raw);
311
316
  if (!onDraft) return;
312
317
  if (!isNum) { onDraft(raw); return; }
313
- if (raw.trim() !== "" && Number.isFinite(Number(raw))) onDraft(clamp(Number(raw)));
318
+ if (raw.trim() !== "" && Number.isFinite(read(raw))) onDraft(clamp(read(raw)));
319
+ };
320
+ // ↑ / ↓ on a number: the next step from what the box holds (a box holding no number keeps the keys for its caret).
321
+ const stepped = (dir: 1 | -1): string | null => {
322
+ const step = field.kind === "number" && field.step && field.step > 0 ? field.step : 1;
323
+ if (draft.trim() === "") return String(clamp(lo ?? 0));
324
+ const n = read(draft);
325
+ if (!Number.isFinite(n)) return null;
326
+ const places = (String(step).split(".")[1] ?? "").length;
327
+ return String(clamp(Number((n + dir * step).toFixed(places))));
314
328
  };
315
329
  // A lone bound says itself too: the commit raises a 0 to a floor of 1, and that needs its reason on screen as much as a pair does.
316
330
  const boundUnit = isNum && field.suffix ? ` ${field.suffix}` : "";
@@ -322,7 +336,12 @@ function TextField({ id, label, field, value, disabled, onCommit, onDraft, onBlu
322
336
  // The limits stay in sight under the box (not behind the ?): the commit clamps to them, and a 200 that turns into 90 needs its reason on
323
337
  // screen. The setting's own help is behind the ?.
324
338
  <Field label={label} htmlFor={id} hint={"hint" in field ? field.hint : undefined} control={controlOf(field)} onBlurCapture={onBlurCapture} mark={labelMark}>
325
- {field.kind === "textarea" ? (
339
+ {(field.kind === "text" && field.code) || (field.kind === "textarea" && field.grow) ? (
340
+ // A line of code (text `code`) and a sentence a shopper reads (textarea `grow`) are ONE box (follow-up #46): a line that wraps and
341
+ // grows with its text, read whole; the code one in a monospace face, not spell-checked.
342
+ <GrowLine id={id} code={!!field.code} value={draft} placeholder={field.placeholder} maxLength={maxLength} disabled={disabled} describedBy={describedBy}
343
+ ariaLabel={ariaLabel} invalid={invalid} onChange={typed} onCommit={commit} />
344
+ ) : field.kind === "textarea" ? (
326
345
  <textarea id={id} className={`gemboss-field gemboss-ei-inp${field.code ? " gemboss-mono" : ""}`} rows={field.rows ?? 2} placeholder={field.placeholder}
327
346
  value={draft} disabled={disabled} maxLength={maxLength} spellCheck={field.code ? false : undefined}
328
347
  aria-describedby={describedBy} aria-label={ariaLabel} onChange={(e) => typed(e.target.value)} onBlur={commit} />
@@ -332,10 +351,21 @@ function TextField({ id, label, field, value, disabled, onCommit, onDraft, onBlu
332
351
  const on = {
333
352
  onChange: (e: ChangeEvent<HTMLInputElement>) => typed(e.target.value), onBlur: commit, "aria-describedby": describedBy, "aria-label": ariaLabel,
334
353
  "aria-invalid": invalid || undefined,
335
- // Enter commits by leaving the box; a search commits as it is typed and keeps the focus.
336
- onKeyDown: (e: KeyboardEvent<HTMLInputElement>) => { if (e.key === "Enter" && !(field.kind === "text" && field.inputType === "search")) { e.preventDefault(); (e.target as HTMLInputElement).blur(); } },
354
+ onKeyDown: (e: KeyboardEvent<HTMLInputElement>) => {
355
+ // Enter commits by leaving the box; a search commits as it is typed and keeps the focus.
356
+ if (e.key === "Enter" && !(field.kind === "text" && field.inputType === "search")) { e.preventDefault(); (e.target as HTMLInputElement).blur(); return; }
357
+ if (isNum && (e.key === "ArrowUp" || e.key === "ArrowDown") && !e.metaKey && !e.ctrlKey && !e.altKey) {
358
+ const next = stepped(e.key === "ArrowUp" ? 1 : -1);
359
+ if (next !== null) { e.preventDefault(); typed(next); }
360
+ }
361
+ },
362
+ ...(listId ? { list: listId } : {}),
363
+ // An ID typed as written: none of the help a word gets. `on` is spread after the url/search/date `autoComplete` below, so its "off" holds.
364
+ ...(field.kind === "text" && field.verbatim ? { spellCheck: false, autoCapitalize: "off", autoCorrect: "off", autoComplete: "off" } : {}),
337
365
  };
338
- const inputMode = isNum ? ("numeric" as const) : undefined;
366
+ // A phone's keypad: a number's digits by default, a box's `inputMode` where it says (`decimal`: digits and a point, so a width of
367
+ // 12.5 in can be typed on an iPhone, whose digits keypad has no point).
368
+ const inputMode = field.kind === "number" ? field.inputMode ?? ("numeric" as const) : field.kind === "text" ? field.inputMode : undefined;
339
369
  const placeholder = field.kind === "text" || field.kind === "number" ? field.placeholder : undefined;
340
370
  // The unit INSIDE its box (UnitField, Polaris TextField's `suffix`): beside it, the box ended short of every other control's right
341
371
  // edge (control standard §13b).
@@ -346,11 +376,39 @@ function TextField({ id, label, field, value, disabled, onCommit, onDraft, onBlu
346
376
  : <input id={id} className="gemboss-field gemboss-ei-inp" type={field.kind === "text" ? field.inputType : undefined} inputMode={inputMode} placeholder={placeholder} value={draft} maxLength={maxLength} disabled={disabled}
347
377
  autoComplete={field.kind === "text" && (field.inputType === "url" || field.inputType === "search" || field.inputType === "date") ? "off" : undefined} {...on} />;
348
378
  })()}
349
- {bounds || count ? <p className="gemboss-ei-hint">{bounds || count}</p> : null}
379
+ {/* A number's bounds are a sentence, across the field like every note; a count is the box's own, under it at its end (editor.css
380
+ `.gemboss-ei-count`). */}
381
+ {bounds ? <p className="gemboss-ei-hint">{bounds}</p> : count ? <p className="gemboss-ei-hint gemboss-ei-count">{count}</p> : null}
350
382
  </Field>
351
383
  );
352
384
  }
353
385
 
386
+ /**
387
+ * THE kit's one box that grows with its text (follow-up #46, 10/11/2026): one line of text in a textarea that wraps and grows with it,
388
+ * across the field under its label, so it is read whole (§9.1). Two FieldSpecs draw it:
389
+ * - text `code`: a line of code or a CSS value that runs long (a condition's expression, a font stack, a border, a shadow), monospace,
390
+ * not spell-checked, no capitals or corrections on a phone. Global styles' Mono font was a 174px one-line box beside its label at 330,
391
+ * 172px of its stack out of sight (#7080); the element panel's "Show when" box (#7088) is this one;
392
+ * - textarea `grow`: a sentence a shopper reads (a plugin's `message`: the cart drawer's "You're {amount} away from free shipping",
393
+ * which was cut in a one-line box, #7085).
394
+ * One line still: Enter commits (it leaves the box, as a text box's Enter does; not the Enter that ends an input method's composition)
395
+ * and a line break typed or pasted becomes a space, the caret kept. Its height: grow-to-text.ts (`field-sizing: content` in
396
+ * editor-grow.css, set by hand where a browser lacks it, again when its width changes).
397
+ */
398
+ function GrowLine({ id, code, value, placeholder, maxLength, disabled, describedBy, ariaLabel, invalid, onChange, onCommit }: {
399
+ id: string; code: boolean; value: string; placeholder?: string; maxLength?: number; disabled?: boolean; describedBy?: string; ariaLabel?: string;
400
+ invalid?: boolean; onChange: (v: string) => void; onCommit: () => void;
401
+ }) {
402
+ const grow = useGrowToText(value, true);
403
+ return (
404
+ <textarea ref={grow.ref} id={id} className={`gemboss-field gemboss-ei-inp gemboss-ei-grow${code ? " gemboss-ei-mono gemboss-ei-code-line" : ""}`} rows={1}
405
+ placeholder={placeholder} value={value} maxLength={maxLength} disabled={disabled} spellCheck={code ? false : undefined}
406
+ autoCapitalize={code ? "off" : undefined} autoCorrect={code ? "off" : undefined} aria-describedby={describedBy} aria-label={ariaLabel}
407
+ aria-invalid={invalid || undefined} onBlur={onCommit} onChange={(e) => onChange(grow.line(e.target.value, e.target.selectionStart))}
408
+ onKeyDown={(e) => { if (e.key === "Enter" && !e.nativeEvent.isComposing && e.keyCode !== 229) { e.preventDefault(); e.currentTarget.blur(); } }} />
409
+ );
410
+ }
411
+
354
412
  function RangeField({ id, label, field, value, disabled, onCommit, onBlurCapture, labelMark }: {
355
413
  id: string; label: string; field: Extract<FieldSpec, { kind: "range" }>;
356
414
  value: unknown; disabled?: boolean; onCommit: (v: unknown) => void;
@@ -410,6 +468,8 @@ export type FieldRowsProps = {
410
468
  onDraft?: (id: string, value: unknown) => void;
411
469
  /** The controls' ids, `<idPrefix><field id>`, for a host whose form is mounted more than once. Else `fr-<field id>`. */
412
470
  idPrefix?: string;
471
+ /** The shop an app's kinds read (a link picker searching its products), for every field of the run. */
472
+ shopId?: string;
413
473
  /** The app's kinds and glyphs (FieldKindsProvider by default). */
414
474
  kinds?: FieldKinds;
415
475
  glyphs?: FieldGlyphs;
@@ -418,7 +478,7 @@ export type FieldRowsProps = {
418
478
  /** One group's fields, each its control, with the label on one side for the run (firstSideFirst). What a schema form draws inside a group,
419
479
  * whichever frame holds the group (FieldRenderer's static groups, FieldFrame's settings frame). A kind over several stored settings
420
480
  * (`spread`) reads them and writes back only the ones it changed, and is locked when any of them is. */
421
- export function FieldRows({ fields, values, onChange, disabled, off, offWhy, onPickImage, onDraft, idPrefix, kinds: kindsProp, glyphs: glyphsProp }: FieldRowsProps & { fields: readonly AnyFieldSpec[] }) {
481
+ export function FieldRows({ fields, values, onChange, disabled, off, offWhy, onPickImage, onDraft, idPrefix, shopId, kinds: kindsProp, glyphs: glyphsProp }: FieldRowsProps & { fields: readonly AnyFieldSpec[] }) {
422
482
  const { kinds, glyphs } = useFieldKinds(kindsProp, glyphsProp);
423
483
  const inputId = (f: AnyFieldSpec) => (idPrefix ? `${idPrefix}${f.id}` : undefined);
424
484
  const spreadOf = (f: AnyFieldSpec) => kindIn(kinds, f.kind)?.spread;
@@ -430,11 +490,11 @@ export function FieldRows({ fields, values, onChange, disabled, off, offWhy, onP
430
490
  // Several settings, one control: only the settings a change touched are written. Locked when any of them is.
431
491
  const locked = !!off && [f.id, ...spread.ids(f)].some((id) => off.has(id));
432
492
  return <FieldControl key={f.id} field={f} inputId={inputId(f)} disabled={disabled || locked} describedBy={locked ? offWhy : undefined}
433
- value={knobValue(f, values, kinds)} kinds={kinds} glyphs={glyphs}
493
+ value={knobValue(f, values, kinds)} kinds={kinds} glyphs={glyphs} shopId={shopId}
434
494
  onChange={(v) => { for (const [id, next] of spread.write(f, v, values)) onChange(id, next); }} />;
435
495
  }
436
496
  return <FieldControl key={f.id} field={f} inputId={inputId(f)} value={values[f.id]} disabled={disabled || off?.has(f.id)}
437
- describedBy={off?.has(f.id) ? offWhy : undefined} kinds={kinds} glyphs={glyphs}
497
+ describedBy={off?.has(f.id) ? offWhy : undefined} kinds={kinds} glyphs={glyphs} shopId={shopId}
438
498
  onChange={(v) => onChange(f.id, v)} onPickImage={onPickImage} onDraft={onDraft ? (v) => onDraft(f.id, v) : undefined} />;
439
499
  })}
440
500
  </>
@@ -21,8 +21,12 @@ export function labelize(s: string): string {
21
21
 
22
22
  /** One choice of a select or of chips. `glyph`: drawn as that picture (an app's `glyphs`), its `label` its name (aria and tooltip).
23
23
  * `name`: what a short label stands for, announced and in its tooltip (a shadow's "S" is "Subtle"). `G`: the glyph names an app
24
- * draws, so a typo is a type error there. */
25
- export type SelectOption<G extends string = string> = { value: string; label?: string; glyph?: G; name?: string };
24
+ * draws, so a typo is a type error there. `group`: the heading a list draws it under (`<optgroup>`), one heading for each run of
25
+ * choices that name the same group (an element's styles: This shop · Shared library); chips draw no heading. `disabled`: in a list,
26
+ * shown and not pickable. */
27
+ export type SelectOption<G extends string = string> = { value: string; label?: string; glyph?: G; name?: string; group?: string;
28
+ /** Shown but not pickable (a list's own words for a value that is gone: "Removed from the library"; a group with nothing to offer). */
29
+ disabled?: boolean };
26
30
 
27
31
  /** One field of a kind the kit draws. `id` keys into the flat `values` object the host owns. */
28
32
  export type FieldSpec<G extends string = string> =
@@ -32,10 +36,26 @@ export type FieldSpec<G extends string = string> =
32
36
  /** The box's own type where it says what it holds: a link (`url`: the phone's link keyboard), a search (`search`: the browser's clear
33
37
  * button where it draws one, and Enter keeps the focus in it), an email, a day (`date`: the browser's own date picker, its value
34
38
  * YYYY-MM-DD). Default a plain text box. A box with a `prefix` stays text. */
35
- inputType?: "url" | "search" | "email" | "date" }
36
- // `code`: a stylesheet or a script, in a monospace face, not spell-checked.
37
- | { kind: "textarea"; id: string; label?: string; rows?: number; placeholder?: string; hint?: string; maxLength?: number; code?: boolean }
38
- | { kind: "number"; id: string; label?: string; min?: number; max?: number; step?: number; suffix?: string; hint?: string; placeholder?: string }
39
+ inputType?: "url" | "search" | "email" | "date";
40
+ /** The phone's keyboard for a value kept as typed text: `decimal` a number with its point (a cost typed as "12.50"), `numeric`
41
+ * digits only. Default the text keyboard. A `number` field takes the same, default `numeric` (it keeps a number). */
42
+ inputMode?: "decimal" | "numeric";
43
+ /** An ID or a code, typed as it is written elsewhere (a partner's store ID): no spell check, no capital or correction on a phone, none
44
+ * of the browser's remembered entries. Not `code`: it keeps the text face and its label beside it. */
45
+ verbatim?: boolean;
46
+ /** A line of code or a CSS value that runs long (a condition's expression, a font stack, a border, a shadow): the `code` control, its
47
+ * label above, the value across the field in a monospace line that wraps and grows with it, not spell-checked, so it is read whole
48
+ * (§9.1). Still one line of text: Enter commits, a line break typed or pasted becomes a space. Not with `prefix` or `inputType`,
49
+ * which a line of code has no use for: with `code` they are not drawn. One `code`: #7088's one-line monospace box is this one. */
50
+ code?: boolean }
51
+ // `code`: a stylesheet or a script, in a monospace face, not spell-checked. `grow`: a sentence or two (a message a shopper reads, a
52
+ // template with {tokens}): one line tall to start, as tall as its text after, so it is read whole (§9.1); `rows` does not apply. Still
53
+ // one line of text: Enter commits, a line break typed or pasted becomes a space.
54
+ | { kind: "textarea"; id: string; label?: string; rows?: number; placeholder?: string; hint?: string; maxLength?: number; code?: boolean; grow?: boolean }
55
+ // `inputMode`: the phone's keypad, as a text box's: default `numeric` (digits alone, which on an iPhone has no point), `decimal` for a
56
+ // number with a fraction (a width of 12.5 in, a box at 31.25 %). Any number box reads a comma typed for its point as one ("31,25" is
57
+ // 31.25: the decimal keypad of a comma locale, vi or de, has no ".").
58
+ | { kind: "number"; id: string; label?: string; min?: number; max?: number; step?: number; suffix?: string; hint?: string; placeholder?: string; inputMode?: "decimal" | "numeric" }
39
59
  | { kind: "range"; id: string; label?: string; min: number; max: number; step?: number; suffix?: string }
40
60
  // `numeric`: the setting holds a number (a text's own Weight): the option picked is written as one. `clearable`: "Not set" stays a
41
61
  // choice once a value is stored, and picking it clears the setting ("" deletes it).
@@ -45,9 +65,25 @@ export type FieldSpec<G extends string = string> =
45
65
  | { kind: "toggle"; id: string; label?: string; onLabel?: string; offLabel?: string; hint?: string }
46
66
  | { kind: "color"; id: string; label?: string; hint?: string; placeholder?: string }
47
67
  | { kind: "image"; id: string; label?: string }
48
- // A list of object rows (e.g. pricing tiers, review cards). Each row edits `item` sub-fields; the control's value is the whole array.
49
- // Rows can be added and removed inline.
50
- | { kind: "repeater"; id: string; label?: string; item: Array<{ key: string; label?: string; long?: boolean }>; addLabel?: string; hint?: string };
68
+ // A LIST OF ROWS (pricing tiers, review cards, a section's benefits), drawn by the kit's Items control (items-field.tsx): each row one line
69
+ // (its picture or its words, a ⋯), dragged or moved with Alt+↑ / ↓, opened to edit its fields in place. The value is the whole list, and
70
+ // each change writes it whole. A row's fields are `fields` (any kind a form draws: a text, a picture, an app's link), else the older
71
+ // `item` keys (a text box each). Kept as stored: a row's other keys, a picture's alt text, a string row (items.ts).
72
+ | { kind: "repeater"; id: string; label?: string; item: Array<{ key: string; label?: string; long?: boolean }>; addLabel?: string; hint?: string;
73
+ /** A row's fields; `from`: older keys a value is stored under (read from the first that holds one, written back there). */
74
+ fields?: Array<RowFieldSpec>;
75
+ /** What one row is ("benefit"): "+ Add benefit", a nameless row "Benefit 3". */
76
+ noun?: string;
77
+ /** The fewest and the most rows the list holds: Remove off at the least, Add and Duplicate off at the most, each saying why. */
78
+ min?: number; max?: number;
79
+ /** The row "+ Add" puts in, so it shows at once (the section's starter words). Default: every field empty, as the list always added. */
80
+ starter?: Record<string, unknown>;
81
+ /** The field that names a row in the list, and the one that is its picture. Default: the first words, the first picture. */
82
+ title?: string; thumb?: string };
83
+
84
+ /** One field of a list's row: any kind a form draws (a kit kind with its own settings, or an app's), and `from`, older keys the value is
85
+ * stored under. Typed loosely on purpose: a row's field may be any FieldSpec, and FieldSpec holds the list (a type cannot hold itself). */
86
+ export type RowFieldSpec = AppFieldSpec & { from?: readonly string[] } & Record<string, unknown>;
51
87
 
52
88
  /** The kinds the kit draws, in FieldSpec's order (a gate reads every one). */
53
89
  export const KIT_FIELD_KINDS = ["text", "textarea", "number", "range", "select", "segmented", "toggle", "color", "image", "repeater"] as const;
@@ -0,0 +1,51 @@
1
+ // A LINE OF TEXT AS TALL AS ITS TEXT (09/11/2026): a sentence a shopper reads (a plugin's `message`, FieldSpec textarea `grow`), drawn in
2
+ // a textarea so it wraps, read whole. Where the browser sizes a textarea to its text itself (`field-sizing: content`, the CSS of the box
3
+ // that asks for it), its height is left to it; where it does not (Safari, Firefox in 2026), the box's height is set to its text's on each
4
+ // value, and again when its width changes (the text re-wraps). Still one line of text: a line break typed or pasted becomes a space, the
5
+ // caret staying where it was. No React rendering here: a hook for the control that draws the box.
6
+ import { useEffect, useLayoutEffect, useRef } from "react";
7
+
8
+ const useIsoLayoutEffect = typeof window === "undefined" ? useEffect : useLayoutEffect;
9
+
10
+ /** Whether the browser sizes the box to its text itself (`field-sizing: content`). */
11
+ export const sizesItself = (): boolean => typeof CSS !== "undefined" && Boolean(CSS.supports?.("field-sizing", "content"));
12
+
13
+ /** The box's height set to its text's (its scroll height and borders). */
14
+ export function growToText(el: HTMLTextAreaElement): void {
15
+ el.style.height = "auto";
16
+ el.style.height = `${el.scrollHeight + el.offsetHeight - el.clientHeight}px`;
17
+ }
18
+
19
+ /** One line of text: a line break (and the spaces around it) becomes one space ("1px\nsolid" is "1px solid", not "1pxsolid"). */
20
+ export const oneLine = (v: string): string => v.replace(/\s*[\r\n]+\s*/g, " ");
21
+
22
+ /**
23
+ * A textarea that grows with its text and holds one line of it (`on`): its `ref`, and `line(raw, caret)` for its change, which says the
24
+ * value without line breaks and keeps the caret where it was (React writing the new value puts it last). Where the browser does not size
25
+ * the box, its height is set on each `value` and when its width changes, watching the box that is drawn now (a box drawn anew is watched
26
+ * anew, not the one it replaced).
27
+ */
28
+ export function useGrowToText(value: string, on: boolean) {
29
+ const ref = useRef<HTMLTextAreaElement>(null);
30
+ const caret = useRef<number | null>(null);
31
+ const watching = useRef<{ el: HTMLTextAreaElement; watch: ResizeObserver } | null>(null);
32
+ useIsoLayoutEffect(() => {
33
+ const el = ref.current;
34
+ if (el && caret.current !== null) { el.setSelectionRange(caret.current, caret.current); caret.current = null; }
35
+ if (!on || !el || sizesItself()) return;
36
+ growToText(el);
37
+ if (typeof ResizeObserver === "undefined" || watching.current?.el === el) return;
38
+ watching.current?.watch.disconnect();
39
+ let width = el.clientWidth;
40
+ const watch = new ResizeObserver(() => { if (el.clientWidth !== width) { width = el.clientWidth; growToText(el); } });
41
+ watch.observe(el);
42
+ watching.current = { el, watch };
43
+ }, [value, on]);
44
+ useEffect(() => () => { watching.current?.watch.disconnect(); watching.current = null; }, []);
45
+ const line = (raw: string, at: number | null): string => {
46
+ if (!on || !/[\r\n]/.test(raw)) return raw;
47
+ caret.current = oneLine(raw.slice(0, at ?? raw.length)).length;
48
+ return oneLine(raw);
49
+ };
50
+ return { ref, line };
51
+ }
@@ -54,9 +54,16 @@ export {
54
54
  } from "./layers";
55
55
  export { SortableLayerList, type SortableLayerListProps, useRowDrag, dropIndex } from "./sortable";
56
56
  // 16/10/2026: a setting that is a list, as rows (drag, duplicate, fold); its own CSS part, editor-repeater.css.
57
- export { RepeaterList, useKeyedRows, type RepeaterListProps, type KeyedRows } from "./repeater";
57
+ export { RepeaterList, useKeyedRows, type RepeaterListProps, type KeyedRows, type KeyedChange } from "./repeater";
58
+ // 09/11/2026: the Items control every list setting draws (a schema's `repeater`, a section's rows), and how a row is read and written as stored.
59
+ export { ItemsField, type ItemsFieldProps } from "./items-field";
60
+ export { IMAGE_URL_KEYS, itemLimits, rowFieldEditable, rowFields, rowThumb, rowTitle, rowValues, starterRow, storedRows, withRowValue, type ItemsSpec, type RowField } from "./items";
58
61
  // 16/10/2026: a closed choice of shapes (an image's ratio, a layout) as picture tiles; its own CSS part, editor-tiles.css.
59
62
  export { ChoiceTiles, tileShapeStyle, type ChoiceTile, type ChoiceTilesProps } from "./tiles";
63
+ // 09/11/2026: on / off in place where a field's On / Off does not fit (a part's switch on a canvas tag); its own CSS part, editor-switch.css.
64
+ export { Switch, type SwitchProps } from "./switch";
65
+ // One choice of a few, each a card with its words and a picture (Global styles' form set and style pack): real radios in one group.
66
+ export { ChoiceCards, type ChoiceCard, type ChoiceCardsProps } from "./choice-cards";
60
67
  // 31/10/2026: a run of groups where one holding nothing is a chip (Control UI C32 slice 3); its own CSS part, editor-chips.css.
61
68
  export { InspectorChips, type InspectorChipsProps } from "./chips";
62
69
  // 06/11/2026: the settings FRAME every settings surface draws (one settings frame slice 1): search, the index of clusters, a cluster's
@@ -73,7 +80,7 @@ export {
73
80
  kindIn, KIT_FIELD_KINDS, knobClearWrites, knobCleared, knobHolds, knobValue, labelize, labelWidthPx, NARROWEST_COLUMN_PX, ROW_CONTROL_COLUMN_PX, segmentable,
74
81
  OWN_FRAME_PLACES, settingMatches, STYLE_FRAME_PLACES, unplacedStyleFields,
75
82
  type AnyFieldSpec, type AppFieldSpec, type FieldGroup, type FieldKindRules, type FieldKindRuleSet, type FieldSchema, type FieldSpec, type FieldSpread,
76
- type FieldWrite, type FrameCluster, type FrameGroup, type FramePlace, type FramePlaces, type FrameWay, type KitFieldKind, type SelectOption,
83
+ type FieldWrite, type RowFieldSpec, type FrameCluster, type FrameGroup, type FramePlace, type FramePlaces, type FrameWay, type KitFieldKind, type SelectOption,
77
84
  } from "./field-spec";
78
85
  export {
79
86
  controlOf, FieldControl, FieldKindsProvider, FieldRenderer, FieldRows, labelBeside,
@@ -89,6 +96,8 @@ export { Popover, type PopoverProps } from "./popover";
89
96
  export { ColorPicker, type ColorPickerProps } from "./color-picker";
90
97
  // 24/10/2026: the body of every "choose one" popup (search, rows, states); its own CSS part, editor-picker.css.
91
98
  export { PickerList, type PickerItem, type PickerListProps, type PickerTone } from "./picker";
99
+ // 09/11/2026 (one control set): the pickers' own search box for a host's combobox (the page editor's insert menu).
100
+ export { PickSearch, type PickerSearch } from "./picker";
92
101
  // 24/10/2026: the same search and states for things chosen by their picture (the shop's images, an icon library); its own CSS part.
93
102
  export { PickerGrid, type PickerTile, type PickerGridProps } from "./picker-grid";
94
103
  export { LayerTree, type LayerTreeProps, type LayerTreeRow } from "./tree";