@gemboss/ui 0.13.0 → 0.21.0

package/src/collections.tsx

@@ -16,6 +16,7 @@
  * without React writes these classes by hand and gets the same thing.
  */
 import React from "react";
+import { attachBoardMove } from "./board-move";
 
 const cx = (...c: Array<string | false | null | undefined>) => c.filter(Boolean).join(" ");
 
@@ -38,6 +39,11 @@ export type CollectionColumn = {
   label?: string;
   /** Cap the cell at this width with an ellipsis (the whole text belongs in the cell's `title`). */
   truncate?: number | string;
+  /** DataTable (0.16.0): the column is never narrower than this, for cells that wrap (a title + a sub line, a note), so
+   *  a narrow frame scrolls instead of squeezing them to a word a line. Polaris `firstColumnMinWidth`, for any column.
+   *  A row header's column has a floor of its own (9.0625rem, Polaris's first column) that this replaces: `0` removes
+   *  it for a row header that is always short (a date, an id). */
+  minWidth?: number | string;
 };
 
 export type CollectionRow = { id: string; cells: Record<string, React.ReactNode> };
@@ -48,16 +54,23 @@ export function ariaSort(col: CollectionColumn, sort?: CollectionSort | null): R
   return sort && sort.key === col.key ? sort.direction : "none";
 }
 
-/** The header cell's contents: the label, as a link (`sortHref`) or a button (`onSort`) when the column sorts. */
-export function SortHeader({ col, sort, onSort }: { col: CollectionColumn; sort?: CollectionSort | null; onSort?: (key: string, direction: SortDirection) => void }) {
+/** Extra props for every sort link (0.16.0), passed to `linkAs`: `{ scroll: false }` for a Next `Link` keeps the page
+ *  where it is, since a sort is the same page in another order. Plain data, so a server component can pass it. */
+export type SortLinkProps = Record<string, unknown>;
+
+/** The header cell's contents: the label, as a link (`sortHref`) or a button (`onSort`) when the column sorts. The link
+ *  is `linkAs` (0.16.0; default `<a>`), the same element as the rows' titles: a router link sorts without reloading the page. */
+export function SortHeader({ col, sort, onSort, linkAs: Link = "a", linkProps }: { col: CollectionColumn; sort?: CollectionSort | null; onSort?: (key: string, direction: SortDirection) => void;
+  linkAs?: React.ElementType; linkProps?: SortLinkProps }) {
   const next: SortDirection = sort && sort.key === col.key && sort.direction === "ascending" ? "descending" : "ascending";
-  if (col.sortHref) return <a className="ui-table__sort" href={col.sortHref}>{col.header}</a>;
+  if (col.sortHref) return <Link {...linkProps} className="ui-table__sort" href={col.sortHref}>{col.header}</Link>;
   if (col.sortable && onSort) return <button type="button" className="ui-table__sort" onClick={() => onSort(col.key, next)}>{col.header}</button>;
   return <>{col.header}</>;
 }
 
 const truncStyle = (t: CollectionColumn["truncate"]): React.CSSProperties | undefined =>
   t == null ? undefined : ({ ["--ui-trunc" as string]: typeof t === "number" ? `${t}px` : t } as React.CSSProperties);
+const minStyle = (w: CollectionColumn["minWidth"]): React.CSSProperties | undefined => (w == null ? undefined : { minWidth: w });
 
 export function Truncate({ children, title, width }: { children: React.ReactNode; title?: string; width?: number | string }) {
   return <span className="ui-trunc" title={title} style={truncStyle(width)}>{children}</span>;
@@ -72,6 +85,11 @@ export type DataTableProps = {
   label: string;
   sort?: CollectionSort | null;
   onSort?: (key: string, direction: SortDirection) => void;
+  /** The link element for the sort links (`sortHref`): a Next `Link` from a client module, so a sort does not reload the
+   *  page (0.16.0). Default `<a>`. */
+  linkAs?: React.ElementType;
+  /** Extra props for those links, e.g. `{ scroll: false }` for a Next `Link` (0.16.0). */
+  sortLinkProps?: SortLinkProps;
   /** The first column stays put while the table scrolls sideways (what a data table does below 768). */
   stickyFirstColumn?: boolean;
   /** Rows 32 instead of 36: only for more than 20 rows. */
@@ -87,7 +105,7 @@ export type DataTableProps = {
   className?: string;
 };
 
-export function DataTable({ columns, rows, label, sort, onSort, stickyFirstColumn, density = "default", rowHeaders = true, totals, footer, state = "ready", stateSlot, className }: DataTableProps) {
+export function DataTable({ columns, rows, label, sort, onSort, linkAs, sortLinkProps, stickyFirstColumn, density = "default", rowHeaders = true, totals, footer, state = "ready", stateSlot, className }: DataTableProps) {
   if (state === "loading") return <CollectionSkeleton pattern="table" columns={columns} label={label} />;
   const showRows = state === "ready" || state === "busy";
   return (
@@ -95,7 +113,7 @@ export function DataTable({ columns, rows, label, sort, onSort, stickyFirstColum
       <table className={cx("ui-table", stickyFirstColumn && "ui-table--sticky-first", density === "compact" && "ui-table--compact")}>
         <caption className="ui-sr-only">{label}</caption>
         <thead>
-          <tr>{columns.map((c) => <th key={c.key} scope="col" className={c.numeric ? "is-num" : undefined} aria-sort={ariaSort(c, sort)}><SortHeader col={c} sort={sort} onSort={onSort} /></th>)}</tr>
+          <tr>{columns.map((c) => <th key={c.key} scope="col" className={c.numeric ? "is-num" : undefined} style={minStyle(c.minWidth)} aria-sort={ariaSort(c, sort)}><SortHeader col={c} sort={sort} onSort={onSort} linkAs={linkAs} linkProps={sortLinkProps} /></th>)}</tr>
         </thead>
         {showRows ? (
           <tbody>
@@ -104,7 +122,7 @@ export function DataTable({ columns, rows, label, sort, onSort, stickyFirstColum
                 {columns.map((c, i) => {
                   const body = c.truncate != null ? <span className="ui-trunc" style={truncStyle(c.truncate)}>{r.cells[c.key]}</span> : r.cells[c.key];
                   return i === 0 && rowHeaders
-                    ? <th key={c.key} scope="row" className={c.numeric ? "ui-table__rowhead is-num" : "ui-table__rowhead"}>{body}</th>
+                    ? <th key={c.key} scope="row" className={c.numeric ? "ui-table__rowhead is-num" : "ui-table__rowhead"} style={minStyle(c.minWidth)}>{body}</th>
                     : <td key={c.key} className={c.numeric ? "is-num" : undefined}>{body}</td>;
                 })}
               </tr>
@@ -141,13 +159,17 @@ export type ResourceItemProps = {
   actions?: React.ReactNode;
   selected?: boolean;
   id?: string;
+  /** The selection checkbox, first in the media slot (as Polaris ResourceItem's). `SelectableResourceList` fills it. */
+  check?: React.ReactNode;
 };
 
-export function ResourceItem({ title, href, linkAs: Link = "a", titleText, media, subtitle, meta, badges, aside, actions, selected, id }: ResourceItemProps) {
+export function ResourceItem({ title, href, linkAs: Link = "a", titleText, media, subtitle, meta, badges, aside, actions, selected, id, check }: ResourceItemProps) {
   const shown = (badges || []).slice(0, 3), more = (badges || []).length - shown.length;
   return (
-    <li className={cx("ui-list__item", selected && "is-selected")} id={id} aria-selected={selected ? true : undefined}>
-      {media ? <div className="ui-list__media">{media}</div> : null}
+    // Not aria-selected: a listitem does not take it (jsx-a11y role-supports-aria-props). With a checkbox the box says
+    // it; without one, `selected` marks the item open beside the list (master-detail): aria-current.
+    <li className={cx("ui-list__item", selected && "is-selected")} id={id} aria-current={selected && !check ? "true" : undefined}>
+      {media || check ? <div className="ui-list__media">{check}{media}</div> : null}
       <div className="ui-list__body">
         {href ? <Link className="ui-list__title" href={href} title={titleText}>{title}</Link> : <span className="ui-list__title" title={titleText}>{title}</span>}
         {subtitle ? <p className="ui-list__sub">{subtitle}</p> : null}
@@ -192,23 +214,41 @@ export type CompactItem = {
   icon?: React.ReactNode;
   meta?: React.ReactNode;
   current?: boolean;
+  /** The full label as text, for `title` when the label can be cut (not under `wrap`, where it is all on screen). */
+  labelText?: string;
   /** activity: the line under the label, and the dot's tone. */
   detail?: React.ReactNode;
+  /** activity (0.15.0): the event's own text under the label and the detail (a summary, a note, a post): body size,
+   *  wraps, never cut (`.ui-list__content`). Paragraphs as `<p>`. Not drawn by the one-line variant. */
+  body?: React.ReactNode;
   time?: React.ReactNode;
   dateTime?: string;
   tone?: "success" | "warning" | "critical" | "info";
 };
 
-export function CompactList({ items, label, variant, linkAs: Link = "a", flush, className }: { items: CompactItem[]; label: string; variant?: "activity"; linkAs?: React.ElementType; flush?: boolean; className?: string }) {
+export type CompactListProps = {
+  items: CompactItem[];
+  label: string;
+  variant?: "activity";
+  linkAs?: React.ElementType;
+  flush?: boolean;
+  /** 0.15.0: the label (and an activity's detail) wrap instead of ending in "…" (`ui-list--wrap`). For a list whose
+   *  label carries data a finger must be able to read (a company, a colleague, who wrote it): `title` is mouse-only. */
+  wrap?: boolean;
+  className?: string;
+};
+
+export function CompactList({ items, label, variant, linkAs: Link = "a", flush, wrap, className }: CompactListProps) {
   const activity = variant === "activity";
   return (
-    <ul className={cx("ui-list ui-list--compact", activity && "ui-list--activity", flush && "ui-list--flush", className)} aria-label={label}>
+    <ul className={cx("ui-list ui-list--compact", activity && "ui-list--activity", wrap && "ui-list--wrap", flush && "ui-list--flush", className)} aria-label={label}>
       {items.map((it) => activity ? (
         <li key={it.id} className="ui-list__item">
           <span className={cx("ui-list__dot", it.tone && `ui-list__dot--${it.tone}`)} aria-hidden="true" />
           <div>
-            {it.href ? <Link className="ui-list__label" href={it.href}>{it.label}</Link> : <span className="ui-list__label">{it.label}</span>}
+            {it.href ? <Link className="ui-list__label" href={it.href} title={wrap ? undefined : it.labelText}>{it.label}</Link> : <span className="ui-list__label" title={wrap ? undefined : it.labelText}>{it.label}</span>}
             {it.detail ? <span className="ui-list__detail">{it.detail}</span> : null}
+            {it.body ? <div className="ui-list__content">{it.body}</div> : null}
           </div>
           {it.time ? <time className="ui-list__time" dateTime={it.dateTime}>{it.time}</time> : <span />}
         </li>
@@ -219,7 +259,7 @@ export function CompactList({ items, label, variant, linkAs: Link = "a", flush,
             ...(it.href ? { href: it.href, "aria-current": it.current ? "page" : undefined } : it.onClick ? { type: "button", onClick: it.onClick } : {}),
           }, <>
             {it.icon ? <span className="ui-list__icon" aria-hidden="true">{it.icon}</span> : null}
-            <span className="ui-list__label">{it.label}</span>
+            <span className="ui-list__label" title={wrap ? undefined : it.labelText}>{it.label}</span>
             {it.meta != null ? <span className="ui-list__meta">{it.meta}</span> : null}
           </>)}
         </li>
@@ -247,15 +287,16 @@ export type MediaCardProps = {
   /** The ⋯ menu, in the picture's corner. */
   menu?: React.ReactNode;
   foot?: React.ReactNode;
-  /** 16/10 by default; 4/3 for a theme or a page. */
-  ratio?: "16/10" | "4/3";
+  /** 16/10 by default; 4/3 for a theme or a page; 1/1 (0.18.0) for a square picture: a moodboard, a product shot, a
+   *  social post. These three only (no free ratio: a grid of mixed shapes loses its rows); any other value draws 16/10. */
+  ratio?: "16/10" | "4/3" | "1/1";
   /** Inside CardGrid with a `label`, each card is a list item. */
   listItem?: boolean;
 };
 
 export function MediaCard({ title, href, linkAs: Link = "a", media, meta, badges, menu, foot, ratio = "16/10", listItem }: MediaCardProps) {
   return (
-    <article className="ui-card ui-card--media" data-ratio={ratio === "4/3" ? "4/3" : undefined} role={listItem ? "listitem" : undefined}>
+    <article className="ui-card ui-card--media" data-ratio={ratio === "4/3" || ratio === "1/1" ? ratio : undefined} role={listItem ? "listitem" : undefined}>
       {media == null ? null : href ? <Link className="ui-card__media" href={href} tabIndex={-1} aria-hidden="true">{media}</Link> : <div className="ui-card__media">{media}</div>}
       {menu ? <div className="ui-card__menu">{menu}</div> : null}
       <div className="ui-card__body">
@@ -270,48 +311,134 @@ export function MediaCard({ title, href, linkAs: Link = "a", media, meta, badges
 
 // ── 6 · Board ──────────────────────────────────────────────────────────────────────────────────────────────────────
 
+/** A card with its id (0.18.0): what a move reports and what server paging de-duplicates by. `name` is what the live
+ *  region says ("Moved <name> to Review"); default the card's title text. */
+export type BoardCard = { id: string; card: React.ReactNode; name?: string };
+
 export type BoardColumn = {
   id: string;
   title: React.ReactNode;
   tone?: "success" | "warning" | "critical" | "info";
   /** The cards, already rendered (MediaCard, or a `ui-card ui-card--media` without a picture). */
-  cards: React.ReactNode[];
+  cards?: React.ReactNode[];
+  /** 0.18.0: the cards with their ids, instead of `cards`. Needed for `onMove` and for server paging. */
+  items?: BoardCard[];
   /** The total when the column holds more than it was given (a server that sent the first page). */
   count?: number;
   empty?: React.ReactNode;
+  /** 0.18.0, server paging: the server has more cards for this column than it sent. The column then shows every card
+   *  it was given (the server already cut it: `boardShown(page)` cards, 12 then 24 more a page) and ends in ONE
+   *  "Show N more" that asks the server, instead of the nested `<details>` that need every card in the HTML. Default:
+   *  true when `moreHref` is set; `false` on the last page. */
+  hasMore?: boolean;
+  /** The URL of this page with this column showing one more page (`?col=ideas&page=2`): the position lives in the URL
+   *  like `ui-pager`'s, so it works with no script, Back and a sent link keep it. kit-plain.js fetches it and appends the
+   *  new cards in place (`data-gb-more`); in React it is `linkAs` (a Next `Link` re-renders the server page). */
+  moreHref?: string;
+  /** A request for the next page is under way (`onLoadMore`): the button becomes a spinner + "Loading…". */
+  loading?: boolean;
 };
 
-/** 12 cards a column, then "Show 24 more" (nested `<details>`, no script): the GemFactory rule, now everyone's. */
-export function Board({ columns, label, pageSize = 12, step = 24, moreLabel = (n) => `Show ${n} more`, emptyLabel = "Nothing here", className }:
-  { columns: BoardColumn[]; label: string; pageSize?: number; step?: number; moreLabel?: (n: number) => React.ReactNode; emptyLabel?: React.ReactNode; className?: string }) {
-  const rest = (cards: React.ReactNode[], from: number): React.ReactNode => {
+/** Cards a server-paged column shows at `page` (1-based): 12, then 24 more each page (Chris 05/10/2026). */
+export function boardShown(page: number, pageSize = 12, step = 24): number {
+  // A page read from a query string that is missing or not a number (NaN) is the first page, not an empty column.
+  const p = Number.isFinite(page) ? Math.max(1, Math.floor(page)) : 1;
+  return pageSize + (p - 1) * step;
+}
+
+export type BoardProps = {
+  columns: BoardColumn[];
+  label: string;
+  /** The board's DOM id, and the prefix of the ids inside (column headings, the move help). Set it when a page has two
+   *  boards: kit-plain.js reads a fetched page's column from the board with the same id. */
+  id?: string;
+  pageSize?: number;
+  step?: number;
+  moreLabel?: (n: number) => React.ReactNode;
+  emptyLabel?: React.ReactNode;
+  /** 0.18.0: server paging from a client parent: "Show N more" calls this with the column's id (with `moreHref` too,
+   *  the link keeps its href for a new tab). The parent appends the cards and sets `loading` meanwhile. */
+  onLoadMore?: (columnId: string) => void;
+  /** The element for the "Show more" links (`moreHref`): a Next `Link` keeps the page in the app. Default `<a>`. */
+  linkAs?: React.ElementType;
+  /** Extra props for those links, e.g. `{ scroll: false }` for a Next `Link` (the page stays where it was). */
+  moreLinkProps?: Record<string, unknown>;
+  /** The page is plain HTML driven by kit-plain.js (React only renders it, nothing hydrates: GemFactory): the "Show more"
+   *  links get `data-gb-more`, so kit-plain.js fetches the next page and appends it in place. Never on a board React
+   *  owns: kit-plain.js would put foreign nodes in React's lists. */
+  fetchMore?: boolean;
+  /** 0.18.0: cards move between columns, by dragging or with the keyboard (Space, arrows, Space; board-move.ts). Called
+   *  once per drop with the card's id, the target column's id and its index there (0 = top, counted without the card).
+   *  Only cards given as `items` move. Without it the board is read-only, as before. */
+  onMove?: (cardId: string, toColumn: string, toIndex: number) => void;
+  className?: string;
+};
+
+/** The words a screen reader hears on a movable card (aria-describedby), and the plain-HTML contract's `<p hidden>`. */
+export const BOARD_MOVE_HELP = "Press Space to pick the card up, arrow keys to move it, Space to drop it, Escape to cancel.";
+
+/** 12 cards a column, then "Show 24 more" (nested `<details>`, no script): the GemFactory rule, now everyone's. With
+ *  `hasMore` (0.18.0) the server pages instead; with `onMove` cards move between columns. */
+export function Board({ columns, label, id, pageSize = 12, step = 24, moreLabel = (n) => `Show ${n} more`, emptyLabel = "Nothing here",
+  onLoadMore, linkAs: Link = "a", moreLinkProps, fetchMore, onMove, className }: BoardProps) {
+  const movable = !!onMove;
+  const prefix = id ?? "ui-board";
+  const help = `${prefix}-move-help`;
+  // A callback ref, not an effect: this module stays plain (a server component renders the board; refs do not run
+  // there). attachBoardMove wires the element once and reads the latest onMove at drop time.
+  const ref = movable ? (el: HTMLDivElement | null) => { if (el) attachBoardMove(el, (cardId, to, index) => onMove!(cardId, to, index)); } : undefined;
+  const entries = (col: BoardColumn): BoardCard[] => col.items ?? (col.cards || []).map((card, i) => ({ id: "", card, name: String(i) }));
+  const li = (c: BoardCard, key: React.Key) => c.id
+    ? <li key={c.id} data-id={c.id} data-name={c.name} {...(movable ? { tabIndex: 0, draggable: true, "aria-describedby": help } : {})}>{c.card}</li>
+    : <li key={key}>{c.card}</li>;
+  const rest = (cards: BoardCard[], from: number): React.ReactNode => {
     if (from >= cards.length) return null;
     const n = Math.min(step, cards.length - from);
     return (
       <details className="ui-board__more">
         <summary className="ui-btn ui-btn--sm">{moreLabel(n)}</summary>
-        <ol className="ui-board__list">{cards.slice(from, from + n).map((c, i) => <li key={from + i}>{c}</li>)}</ol>
+        <ol className="ui-board__list">{cards.slice(from, from + n).map((c, i) => li(c, from + i))}</ol>
         {rest(cards, from + n)}
       </details>
     );
   };
+  const next = (col: BoardColumn, shown: number): React.ReactNode => {
+    if (!(col.hasMore ?? col.moreHref != null)) return null;
+    const n = col.count != null ? Math.min(step, Math.max(col.count - shown, 0)) : step;
+    if (col.loading) return <div className="ui-more ui-board__next" aria-busy="true"><span className="ui-spinner" aria-hidden="true" /><span role="status">Loading…</span></div>;
+    const words = n > 0 ? moreLabel(n) : "Show more";
+    const ask = onLoadMore ? (e: React.MouseEvent) => { if (e.metaKey || e.ctrlKey || e.shiftKey || e.button === 1) return; e.preventDefault(); onLoadMore(col.id); } : undefined;
+    return (
+      <div className="ui-more ui-board__next">
+        {col.moreHref
+          ? <Link {...moreLinkProps} className="ui-btn ui-btn--sm" href={col.moreHref} data-gb-more={fetchMore ? "" : undefined} onClick={ask}>{words}</Link>
+          : <button type="button" className="ui-btn ui-btn--sm" onClick={ask} disabled={!onLoadMore}>{words}</button>}
+      </div>
+    );
+  };
   return (
-    <div className={cx("ui-board", className)} role="region" aria-label={label}>
-      {columns.map((col) => (
-        <section key={col.id} className="ui-board__col" aria-labelledby={`ui-board-${col.id}`}>
-          <header className="ui-board__head">
-            <span className={cx("ui-board__dot", col.tone && `ui-board__dot--${col.tone}`)} aria-hidden="true" />
-            <span className="ui-board__name" id={`ui-board-${col.id}`}>{col.title}</span>
-            <span className="ui-board__count">{col.count ?? col.cards.length}</span>
-          </header>
-          {col.cards.length ? (
-            <>
-              <ol className="ui-board__list">{col.cards.slice(0, pageSize).map((c, i) => <li key={i}>{c}</li>)}</ol>
-              {rest(col.cards, pageSize)}
-            </>
-          ) : <p className="ui-board__empty">{col.empty ?? emptyLabel}</p>}
-        </section>
-      ))}
+    <div className={cx("ui-board", className)} id={id} role="region" aria-label={label} ref={ref} data-gb-move={movable ? "" : undefined}>
+      {movable ? <p id={help} hidden>{BOARD_MOVE_HELP}</p> : null}
+      {movable ? <div className="ui-sr-only" aria-live="assertive" data-gb-live="" /> : null}
+      {columns.map((col) => {
+        const cards = entries(col);
+        const server = col.hasMore != null || col.moreHref != null;
+        return (
+          <section key={col.id} className="ui-board__col" data-col={col.id} aria-labelledby={`${prefix}-${col.id}`}>
+            <header className="ui-board__head">
+              <span className={cx("ui-board__dot", col.tone && `ui-board__dot--${col.tone}`)} aria-hidden="true" />
+              <span className="ui-board__name" id={`${prefix}-${col.id}`}>{col.title}</span>
+              <span className="ui-board__count">{col.count ?? cards.length}</span>
+            </header>
+            {cards.length ? (
+              server
+                ? <ol className="ui-board__list">{cards.map((c, i) => li(c, i))}</ol>
+                : <><ol className="ui-board__list">{cards.slice(0, pageSize).map((c, i) => li(c, i))}</ol>{rest(cards, pageSize)}</>
+            ) : <p className="ui-board__empty">{col.empty ?? emptyLabel}</p>}
+            {server ? next(col, cards.length) : null}
+          </section>
+        );
+      })}
     </div>
   );
 }
@@ -356,7 +483,8 @@ export type SkeletonPattern = "table" | "index" | "list" | "compact" | "grid" |
  */
 export function CollectionSkeleton({ pattern, rows = 5, columns = [], media = "thumbnail", label = "Loading", flush, loadingText = "Loading…", check, actions }:
   { pattern: SkeletonPattern; rows?: number; columns?: CollectionColumn[]; media?: "avatar" | "thumbnail" | "none"; label?: string; flush?: boolean; loadingText?: string;
-    /** index: the checkbox and actions columns the real table will have, so no column moves when rows arrive. */ check?: boolean; actions?: boolean }) {
+    /** index: the checkbox and actions columns the real table will have; list (0.16.0): each row's box before its
+     *  media. So nothing moves when rows arrive. */ check?: boolean; actions?: boolean }) {
   const n = Math.max(1, Math.min(10, rows));
   const line = (w?: string) => <span className="ui-skeleton__line" style={w ? { width: w } : undefined} />;
   const status = <span className="ui-sr-only" role="status">{loadingText}</span>;
@@ -379,7 +507,8 @@ export function CollectionSkeleton({ pattern, rows = 5, columns = [], media = "t
         <ul className={cx("ui-list", pattern === "list" ? "ui-skeleton--list" : "ui-list--compact ui-skeleton--compact", flush && "ui-list--flush")} aria-hidden="true">
           {Array.from({ length: n }, (_, i) => pattern === "list" ? (
             <li key={i} className="ui-list__item">
-              {media !== "none" ? <span className={cx("ui-skeleton__block", media === "avatar" && "ui-skeleton__block--round")} /> : null}
+              {check ? <span className="ui-list__media"><span className="ui-list__check" />{media !== "none" ? <span className={cx("ui-skeleton__block", media === "avatar" && "ui-skeleton__block--round")} /> : null}</span>
+                : media !== "none" ? <span className={cx("ui-skeleton__block", media === "avatar" && "ui-skeleton__block--round")} /> : null}
               <span className="ui-list__body">{line()}{line()}</span>
             </li>
           ) : (

package/src/editor/controls.tsx

@@ -0,0 +1,206 @@
+"use client";
+// The settings panel's CONTROLS (0.17.0, step 3 of 5 of the editor kit): segmented, colour, slider, the four-edge px box
+// and the image slot. Each takes a value and gives one back through `onChange`; nothing here knows what is edited, what
+// schema a value came from or where it is saved. Wrap each in `Field` (panel.tsx) for its label and hint.
+//
+// Moved from the admin (apps/admin: FieldRenderer.tsx, element-inspector-controls.tsx) with the markup, the class names
+// and the commit rules they had there, so the admin's editors draw and behave exactly as before:
+//   · text-like boxes keep a DRAFT and commit on blur, Enter blurs (a live preview is not hammered per keystroke);
+//   · the colour swatch commits on every change, the colour's text box on blur / Enter;
+//   · the slider commits on every change (its number);
+//   · the edge box hands each keystroke to the caller (`onChange(side, raw)`) and says when to commit (`onCommit`, on
+//     blur): the caller decides what an empty edge means, and the admin has three answers to that on purpose.
+import { useEffect, useState } from "react";
+import type React from "react";
+import { cssUrl } from "./css-url";
+import { swatchState } from "./swatch";
+import { Segmented } from "../segmented";
+
+const blurOnEnter = (e: React.KeyboardEvent<HTMLInputElement>) => {
+  if (e.key === "Enter") { e.preventDefault(); (e.target as HTMLInputElement).blur(); }
+};
+
+// ── Seg ─────────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+export interface SegOption<T extends string = string> {
+  value: T;
+  /** Default: the value itself. */
+  label?: React.ReactNode;
+}
+
+export interface SegProps<T extends string = string> {
+  options: ReadonlyArray<SegOption<T>>;
+  /** The pressed option. A value that matches none presses none. */
+  value?: string;
+  onChange: (value: T) => void;
+  disabled?: boolean;
+  /** The group's accessible name (`role="group"`): the field's label, said again for a screen reader. */
+  label?: string;
+  /** On the group (the admin narrows two-option rows with a max-width). */
+  style?: React.CSSProperties;
+}
+
+/**
+ * The settings panel's switch: the kit's `Segmented` stretched to its row (`.ui-seg--fill`), the same look as every
+ * other switch in the editors (0.20.0; it was a grey track with a raised white tab of its own). `gemboss-ei-seg` stays on
+ * the group as the hook editor-plain.js finds, and each button carries its `data-value`.
+ */
+export function Seg<T extends string = string>({ options, value, onChange, disabled, label, style }: SegProps<T>) {
+  return (
+    <Segmented<T> fill className="gemboss-ei-seg" style={style} ariaLabel={label ?? ""} value={(value ?? "") as T | ""} onChange={onChange} disabled={disabled}
+      options={options.map((o) => ({ value: o.value, label: o.label ?? o.value }))} />
+  );
+}
+
+// ── ColorControl ────────────────────────────────────────────────────────────────────────────────────────────────────
+
+export interface ColorControlProps {
+  /** The text box's id (the Field's `htmlFor`). */
+  id?: string;
+  value: string;
+  /** A committed value: on every swatch change, and on the text box's blur / Enter. */
+  onChange: (value: string) => void;
+  disabled?: boolean;
+  /** The field's name; the swatch is announced as "<label> swatch". */
+  label: string;
+  placeholder?: string;
+}
+
+/**
+ * `.gemboss-ei-color`: a native swatch beside a text box. The swatch is DISABLED (with a title saying why) for anything
+ * but a 6-digit hex (`swatchState`): `<input type="color">` would show black for `#f00`, `rgba()`, `var()` or a gradient,
+ * and overwrite it with black on the first touch.
+ */
+export function ColorControl({ id, value, onChange, disabled, label, placeholder }: ColorControlProps) {
+  const [draft, setDraft] = useState(value);
+  useEffect(() => { setDraft(value); }, [value]);
+  const { swatch, usable } = swatchState(draft);
+  return (
+    <div className="gemboss-ei-color">
+      <input type="color" className="gemboss-ei-swatch" aria-label={`${label} swatch`} value={swatch}
+        disabled={disabled || !usable}
+        title={usable ? undefined : `${draft} — not a plain 6-digit hex; edit it in the box below`}
+        onChange={(e) => { setDraft(e.target.value); onChange(e.target.value); }} />
+      <input id={id} className="gemboss-field gemboss-ei-inp" placeholder={placeholder ?? "#000000 / var(--…)"} value={draft} disabled={disabled}
+        onChange={(e) => setDraft(e.target.value)} onBlur={() => onChange(draft)} onKeyDown={blurOnEnter} />
+    </div>
+  );
+}
+
+// ── RangeControl ────────────────────────────────────────────────────────────────────────────────────────────────────
+
+export interface RangeControlProps {
+  id?: string;
+  min: number;
+  max: number;
+  /** Default 1. */
+  step?: number;
+  value: number;
+  /** Every change (drag, ←/→, Home/End, PageUp/PageDown), as a number. */
+  onChange: (value: number) => void;
+  disabled?: boolean;
+}
+
+/** `input.gemboss-ei-range` (the native slider in the primary colour). Show its value with `Field`'s `labelValue`. */
+export function RangeControl({ id, min, max, step, value, onChange, disabled }: RangeControlProps) {
+  return (
+    <input id={id} type="range" className="gemboss-ei-range" min={min} max={max} step={step ?? 1}
+      value={value} disabled={disabled} onChange={(e) => onChange(Number(e.target.value))} />
+  );
+}
+
+// ── EdgeBox ─────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+export type EdgeSide = "t" | "r" | "b" | "l";
+const SIDES: readonly EdgeSide[] = ["t", "r", "b", "l"];
+const SIDE_NAME: Record<EdgeSide, string> = { t: "top", r: "right", b: "bottom", l: "left" };
+
+export interface EdgeBoxProps {
+  /** The field's name; each box is announced as "<label> top / right / bottom / left". */
+  label: string;
+  /** What each box shows. A number, the raw text being typed, or empty. */
+  values: Partial<Record<EdgeSide, string | number>>;
+  /** Per side; default "0". The admin shows the inherited desktop value here while editing the phone override. */
+  placeholders?: Partial<Record<EdgeSide, string>>;
+  /** Every keystroke in one box. */
+  onChange: (side: EdgeSide, raw: string) => void;
+  /** A box lost focus (Enter blurs): commit what the boxes hold. */
+  onCommit: () => void;
+  disabled?: boolean;
+  /** `gemboss-field--narrow` on each box (the field family's tight lane). Default true. */
+  narrow?: boolean;
+  /** Ids for the boxes, per side. */
+  ids?: Partial<Record<EdgeSide, string>>;
+}
+
+/** `.gemboss-ei-edgebox`: four px boxes, T · R · B · L, mono and centred. */
+export function EdgeBox({ label, values, placeholders, onChange, onCommit, disabled, narrow = true, ids }: EdgeBoxProps) {
+  const cls = narrow ? "gemboss-field gemboss-field--narrow gemboss-ei-inp" : "gemboss-field gemboss-ei-inp";
+  return (
+    <div className="gemboss-ei-edgebox">
+      {SIDES.map((s) => (
+        <div className="gemboss-ei-edge" key={s}>
+          <input className={cls} inputMode="numeric" placeholder={placeholders?.[s] ?? "0"}
+            aria-label={`${label} ${SIDE_NAME[s]}`} id={ids?.[s]} value={values[s] ?? ""} disabled={disabled}
+            onChange={(e) => onChange(s, e.target.value)} onBlur={onCommit} onKeyDown={blurOnEnter} />
+          <span>{s.toUpperCase()}</span>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+// ── ImageControl ────────────────────────────────────────────────────────────────────────────────────────────────────
+
+/** A dashed pill button (`.gemboss-ei-addchip`): an image slot's Library / Generate / Clear, a panel's "＋ Add". */
+export function ChipButton({ disabled, expanded, onClick, children }: {
+  disabled?: boolean;
+  /** `aria-expanded`, for a chip that opens something under it (the Library grid). */
+  expanded?: boolean;
+  onClick?: React.MouseEventHandler<HTMLButtonElement>;
+  children: React.ReactNode;
+}) {
+  return <button type="button" className="gemboss-ei-addchip" disabled={disabled} aria-expanded={expanded} onClick={onClick}>{children}</button>;
+}
+
+export interface ImageControlProps {
+  /** The URL box's id. */
+  id?: string;
+  /** The committed URL: what the thumbnail shows. */
+  value: string;
+  /** A committed URL: on blur / Enter when the box differs from `value`, and "" from Clear. */
+  onChange: (url: string) => void;
+  disabled?: boolean;
+  placeholder?: string;
+  /**
+   * The URL box's text, when the caller holds it (to put a picked or generated URL in the box at once, before `value`
+   * comes back). Omitted, the control keeps its own draft and resets it whenever `value` changes.
+   */
+  draft?: string;
+  onDraftChange?: (text: string) => void;
+  /** Chips before Clear (`ChipButton`): Library, Generate. */
+  actions?: React.ReactNode;
+  /** Draw Clear while there is a value. Default true. */
+  clearable?: boolean;
+}
+
+/** `.gemboss-ei-img`: a 52px thumbnail (— when empty) beside the URL box and its chips. */
+export function ImageControl({ id, value, onChange, disabled, placeholder, draft, onDraftChange, actions, clearable = true }: ImageControlProps) {
+  const [own, setOwn] = useState(value);
+  useEffect(() => { setOwn(value); }, [value]);
+  const text = draft ?? own;
+  const setText = (next: string) => { if (draft === undefined) setOwn(next); onDraftChange?.(next); };
+  return (
+    <div className="gemboss-ei-img">
+      <div className="gemboss-ei-img-thumb" style={value ? { backgroundImage: cssUrl(value) } : undefined} aria-hidden>{value ? null : "—"}</div>
+      <div className="gemboss-ei-img-ctl">
+        <input id={id} className="gemboss-field gemboss-ei-inp" placeholder={placeholder ?? "Paste image URL…"} value={text} disabled={disabled}
+          onChange={(e) => setText(e.target.value)} onBlur={() => { if (text !== value) onChange(text); }} onKeyDown={blurOnEnter} />
+        <div className="gemboss-ei-img-actions">
+          {actions}
+          {clearable && value ? <ChipButton disabled={disabled} onClick={() => { setText(""); onChange(""); }}>Clear</ChipButton> : null}
+        </div>
+      </div>
+    </div>
+  );
+}

package/src/editor/css-url.ts

@@ -0,0 +1,11 @@
+// A CSS `url("…")` for any image URL (0.20.1). Plain TypeScript, no "use client": a server component may build a
+// background with it (also `@gemboss/ui/editor/css-url`).
+//
+// Unquoted, a URL holding ")" or a space ends the token early, the declaration is dropped, and the thumbnail shows
+// nothing. Quoted, only `"` and `\` need a backslash; a control character (tab, newline, …) is written as a hex escape
+// followed by a space, the one form CSS reads back as that character. (JSON.stringify is NOT this: CSS reads its `\n`
+// as "n" and its `\u0001` as the text "u0001".) editor-plain.js writes the same thing; editor-panel-browser.test.tsx
+// holds the two to one answer.
+export function cssUrl(url: string): string {
+  return `url("${url.replace(/["\\]/g, "\\$&").replace(/[\u0000-\u001f\u007f]/g, (c) => `\\${c.charCodeAt(0).toString(16)} `)}")`;
+}