@pramen/cms-editor 0.0.59 → 0.0.61

package/src/buzola.gen.ts

@@ -6,40 +6,73 @@ import { buildRouteTree } from '@buzola/router';
 import type { RouteConfig } from '@buzola/router';
 
 import Route0 from './routes/_layout';
-const Route1 = () => import('./routes/collection-item').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
-const Route2 = () => import('./routes/collection').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
-const Route3 = () => import('./routes/home').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
-const Route4 = () => import('./routes/media').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
-const Route5 = () => import('./routes/page').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
-const Route6 = () => import('./routes/settings').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
-const Route7 = () => import('./routes/type').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
-const Route8 = () => import('./routes/users').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
-const Route9 = () => import('./routes/_404').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
+const Route1 = () => import('./routes/admin-page').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
+const Route2 = () => import('./routes/block-type').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
+const Route3 = () => import('./routes/collection-item').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
+const Route4 = () => import('./routes/collection').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
+const Route5 = () => import('./routes/content-type').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
+const Route6 = () => import('./routes/home').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
+const Route7 = () => import('./routes/media').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
+const Route8 = () => import('./routes/menu').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
+const Route9 = () => import('./routes/menus').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
+const Route10 = () => import('./routes/page').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
+const Route11 = () => import('./routes/redirects').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
+const Route12 = () => import('./routes/schema').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
+const Route13 = () => import('./routes/settings').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
+const Route14 = () => import('./routes/taxonomies').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
+const Route15 = () => import('./routes/taxonomy').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
+const Route16 = () => import('./routes/type').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
+const Route17 = () => import('./routes/users').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
+const Route18 = () => import('./routes/widget-area').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
+const Route19 = () => import('./routes/widgets').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
+const Route20 = () => import('./routes/_404').then(m => ({ default: m.default.component })) as Promise<{ default: ComponentType }>;
 
 // Module augmentation for type-safe page-centric routing
 declare module '@buzola/router' {
   interface BuzolaPageMap {
+    'admin-page': { slug: string };
+    'block-type': { slug: string };
     'collection-item': { slug: string; id: string };
     'collection': { slug: string };
+    'content-type': { slug: string };
     'home': {};
     'media': {};
+    'menu': { name: string };
+    'menus': {};
     'page': { pageId: string; tab?: string };
+    'redirects': {};
+    'schema': {};
     'settings': {};
+    'taxonomies': {};
+    'taxonomy': { slug: string };
     'type': { slug: string };
     'users': {};
+    'widget-area': { name: string };
+    'widgets': {};
   }
 }
 
 // Page registry — page ID → route pattern
 export const pageRegistry: Record<string, string> = {
+  'admin-page': '/apps/:slug',
+  'block-type': '/schema/blocks/:slug',
   'collection-item': '/collections/:slug/:id',
   'collection': '/collections/:slug',
+  'content-type': '/schema/content/:slug',
   'home': '/',
   'media': '/media',
+  'menu': '/menus/:name',
+  'menus': '/menus',
   'page': '/pages/:pageId',
+  'redirects': '/redirects',
+  'schema': '/schema',
   'settings': '/settings',
+  'taxonomies': '/taxonomies',
+  'taxonomy': '/taxonomies/:slug',
   'type': '/types/:slug',
   'users': '/users',
+  'widget-area': '/widgets/:name',
+  'widgets': '/widgets',
 };
 
 const routeConfigs: RouteConfig[] = [
@@ -49,55 +82,116 @@ const routeConfigs: RouteConfig[] = [
     isLayout: true,
     children: [
       {
-        path: '/collection-item',
-        matchPath: '/collections/:slug/:id',
+        path: '/admin-page',
+        matchPath: '/apps/:slug',
         component: lazy(Route1),
         preload: Route1,
       },
       {
-        path: '/collection',
-        matchPath: '/collections/:slug',
+        path: '/block-type',
+        matchPath: '/schema/blocks/:slug',
         component: lazy(Route2),
         preload: Route2,
       },
       {
-        path: '/home',
-        matchPath: '/',
+        path: '/collection-item',
+        matchPath: '/collections/:slug/:id',
         component: lazy(Route3),
         preload: Route3,
       },
       {
-        path: '/media',
+        path: '/collection',
+        matchPath: '/collections/:slug',
         component: lazy(Route4),
         preload: Route4,
       },
       {
-        path: '/page',
-        matchPath: '/pages/:pageId',
+        path: '/content-type',
+        matchPath: '/schema/content/:slug',
         component: lazy(Route5),
         preload: Route5,
       },
       {
-        path: '/settings',
+        path: '/home',
+        matchPath: '/',
         component: lazy(Route6),
         preload: Route6,
       },
       {
-        path: '/type',
-        matchPath: '/types/:slug',
+        path: '/media',
         component: lazy(Route7),
         preload: Route7,
       },
       {
-        path: '/users',
+        path: '/menu',
+        matchPath: '/menus/:name',
         component: lazy(Route8),
         preload: Route8,
       },
       {
-        path: '/:__notFound+',
+        path: '/menus',
         component: lazy(Route9),
         preload: Route9,
       },
+      {
+        path: '/page',
+        matchPath: '/pages/:pageId',
+        component: lazy(Route10),
+        preload: Route10,
+      },
+      {
+        path: '/redirects',
+        component: lazy(Route11),
+        preload: Route11,
+      },
+      {
+        path: '/schema',
+        component: lazy(Route12),
+        preload: Route12,
+      },
+      {
+        path: '/settings',
+        component: lazy(Route13),
+        preload: Route13,
+      },
+      {
+        path: '/taxonomies',
+        component: lazy(Route14),
+        preload: Route14,
+      },
+      {
+        path: '/taxonomy',
+        matchPath: '/taxonomies/:slug',
+        component: lazy(Route15),
+        preload: Route15,
+      },
+      {
+        path: '/type',
+        matchPath: '/types/:slug',
+        component: lazy(Route16),
+        preload: Route16,
+      },
+      {
+        path: '/users',
+        component: lazy(Route17),
+        preload: Route17,
+      },
+      {
+        path: '/widget-area',
+        matchPath: '/widgets/:name',
+        component: lazy(Route18),
+        preload: Route18,
+      },
+      {
+        path: '/widgets',
+        component: lazy(Route19),
+        preload: Route19,
+      },
+      {
+        path: '/:__notFound+',
+        component: lazy(Route20),
+        preload: Route20,
+      },
     ],
   },
 ];

package/src/chrome.ts

@@ -0,0 +1,16 @@
+// The layout primitives every screen shares.
+//
+// A LEAF module on purpose. These were copied into four files, and the obvious fix — put
+// them in `components.tsx`, which already has them — is not available: `components.tsx`
+// imports from `furniture.tsx` (for `flattenTerms`, used by the page editor's Terms panel),
+// so `furniture.tsx` importing back would be a cycle. Constants and class strings have no
+// dependencies of their own, so they belong below both.
+//
+// Class strings rather than components, because that is what the call sites want: most
+// apply them to an element they are already styling for their own reasons.
+
+/** The page gutter every full-width screen uses. */
+export const WRAP = "mx-auto max-w-[1200px] px-7 pb-8 pt-2";
+
+/** One row in a list — a card-surfaced strip with the standard inset. */
+export const ROW = "flex items-center gap-3 rounded-[14px] border border-transparent bg-surface-card px-[18px] py-3.5";

package/src/components.tsx

@@ -6,19 +6,26 @@ import { Button, Heading, Input, ModalDialog, ModalOverlay, ModalSurface, Textar
 import { useCallback, useEffect, useMemo, useRef, useState, type ReactNode } from "react";
 import { Api, ApiError } from "./api";
 import { CONTROL, FieldForm, formatWhen, fromLocalInput, slugify, toLocalInput } from "./fields";
+import { ROW, WRAP } from "./chrome";
 import type { Config } from "./api";
 import { useApp, type Me } from "./app-context";
 import { isRichTextDoc, richTextToPlainText } from "./rich-text";
-import type { AssembledPage, AuditEntry, BlockType, CmsCapabilities, CollectionMeta, ContentType, FieldDefinition, FieldValue, FieldValues, Media, Page, RegionDefinition, RenderedBlock } from "./types";
+import { flattenTerms } from "./furniture";
+import type { AssembledPage, AuditEntry, BlockType, CmsCapabilities, CollectionMeta, ContentType, FieldDefinition, FieldValue, FieldValues, Media, Page, RegionDefinition, RenderedBlock, Taxonomy, Term } from "./types";
 
-export type InspectorTab = "settings" | "seo" | "workflow" | "i18n" | "audit";
-export const INSPECTOR_TABS: InspectorTab[] = ["settings", "seo", "workflow", "i18n", "audit"];
+export type InspectorTab = "settings" | "seo" | "workflow" | "i18n" | "terms" | "audit";
+export const INSPECTOR_TABS: InspectorTab[] = ["settings", "seo", "workflow", "i18n", "terms", "audit"];
 
 /** The tabs a deployment actually shows. ONE definition, used by the tab bar, the panel
  * switch and the route's deep-link fallback — three places that previously each re-derived
- * "is i18n visible?" and could disagree. */
-export function visibleTabs(multilingual: boolean): InspectorTab[] {
-  return multilingual ? INSPECTOR_TABS : INSPECTOR_TABS.filter((t) => t !== "i18n");
+ * "is i18n visible?" and could disagree.
+ *
+ * `terms` follows `siteFurniture` for the same reason `i18n` follows `multilingual`: on a
+ * server without the taxonomy handlers the panel could only ever render an error. With them
+ * and no vocabularies defined it renders its own empty state, which is the honest answer
+ * and points at the screen that fixes it. */
+export function visibleTabs(multilingual: boolean, siteFurniture = false): InspectorTab[] {
+  return INSPECTOR_TABS.filter((t) => (t === "i18n" ? multilingual : t === "terms" ? siteFurniture : true));
 }
 
 /** Collections-only deployments hide the block/page builder entirely. Read in one place so
@@ -48,8 +55,6 @@ export function splitsByType(contentTypes: ContentType[] | null, cms: CmsCapabil
 
 // --- presentational primitives (podoba tokens; replaces styles.ts classes) ---
 
-const ROW = "flex items-center gap-3 rounded-[14px] border border-transparent bg-surface-card px-[18px] py-3.5";
-const WRAP = "mx-auto max-w-[1200px] px-7 pb-8 pt-2";
 
 function Hero({ lead, em, children }: { lead: string; em: string; children?: ReactNode }) {
   return (
@@ -666,7 +671,7 @@ export function CollectionEditor({ api, def, id, onSaved, onDeleted, onBack, onE
 // --- page editor -------------------------------------------------------------
 
 export function PageEditor({ api, page, blockTypes, tab, onTab, onBack, onChange, registerGuard }: { api: Api; page: Page; blockTypes: BlockType[]; tab: InspectorTab; onTab: (t: InspectorTab) => void; onBack: () => void; onChange: (p: Page) => void; registerGuard: (fn: (() => boolean) | null) => void }) {
-  const { cms: { multilingual } } = useApp();
+  const { cms: { multilingual, siteFurniture, canEdit } } = useApp();
   const [ct, setCt] = useState<ContentType | null>(null);
   const [assembled, setAssembled] = useState<AssembledPage | null>(null);
   const [err, setErr] = useState("");
@@ -905,7 +910,7 @@ export function PageEditor({ api, page, blockTypes, tab, onTab, onBack, onChange
 
       <div className="overflow-auto rounded-panel border border-border bg-surface-card p-5">
         <div className="mb-3 flex gap-1">
-          {visibleTabs(multilingual).map((t) => (
+          {visibleTabs(multilingual, siteFurniture).map((t) => (
             <Button key={t} variant="ghost" size="sm" className={tab === t ? "bg-surface-muted text-fg" : "text-fg-muted"} onPress={() => onTab(t)}>{t}</Button>
           ))}
         </div>
@@ -913,6 +918,7 @@ export function PageEditor({ api, page, blockTypes, tab, onTab, onBack, onChange
         {tab === "seo" ? <SeoPanel api={api} page={page} onError={setErr} /> : null}
         {tab === "workflow" ? <Workflow api={api} page={page} onChanged={(p) => { onChange(p); }} onError={setErr} /> : null}
         {tab === "i18n" && multilingual ? <I18n api={api} page={page} onError={setErr} /> : null}
+        {tab === "terms" ? <PageTerms api={api} pageId={page.id} canEdit={canEdit} onError={setErr} /> : null}
         {tab === "audit" ? <AuditLog api={api} pageId={page.id} onError={setErr} /> : null}
       </div>
     </div>
@@ -1401,6 +1407,92 @@ function I18n({ api, page, onError }: { api: Api; page: Page; onError: (s: strin
   );
 }
 
+/** The page's taxonomy terms.
+ *
+ * Assignment has to live in the page editor: `cms_page_terms` links a term to a PAGE, so
+ * the vocabulary screen can define terms but has no way to attach one — a taxonomy with no
+ * assignment surface is a list of words.
+ *
+ * `setPageTerms` replaces the whole selection rather than adding and removing one at a
+ * time, so the panel holds the selection and saves it as a unit. Two calls each patching
+ * one end of it race into a state neither asked for.
+ */
+function PageTerms({ api, pageId, canEdit, onError }: { api: Api; pageId: string; canEdit: boolean; onError: (s: string) => void }) {
+  const [taxa, setTaxa] = useState<Taxonomy[] | null>(null);
+  const [terms, setTerms] = useState<Record<string, Term[]>>({});
+  const [selected, setSelected] = useState<Set<string>>(() => new Set());
+  const [busy, setBusy] = useState(false);
+  const [ok, setOk] = useState(false);
+
+  useEffect(() => {
+    let live = true;
+    (async () => {
+      try {
+        const list = await api.listTaxonomies();
+        if (!live) return;
+        setTaxa(list);
+        // In parallel, and alongside the page's own assignments. Awaiting one vocabulary at
+        // a time made the panel's open cost N+1 serial round trips for data that has no
+        // ordering dependency between the calls.
+        const [trees, assigned] = await Promise.all([
+          Promise.all(list.map(async (t) => [t.slug, flattenTerms(await api.getTermTree(t.slug)).map((f) => f.term)] as const)),
+          api.listPageTerms(pageId),
+        ]);
+        if (!live) return;
+        setTerms(Object.fromEntries(trees));
+        setSelected(new Set(assigned.map((t) => t.id)));
+      } catch (e) {
+        if (live) onError(errMsg(e));
+      }
+    })();
+    return () => { live = false; };
+  }, [api, pageId, onError]);
+
+  const toggle = (id: string) => {
+    setSelected((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) next.delete(id); else next.add(id);
+      return next;
+    });
+  };
+
+  const save = async () => {
+    setBusy(true);
+    try {
+      await api.setPageTerms(pageId, [...selected]);
+      setOk(true);
+      setTimeout(() => setOk(false), 1200);
+    } catch (e) { onError(errMsg(e)); } finally { setBusy(false); }
+  };
+
+  if (taxa === null) return <p className="text-fg-subtle">Loading…</p>;
+  if (taxa.length === 0) return <p className="text-fg-subtle">No vocabularies defined yet.</p>;
+
+  return (
+    <div className="flex flex-col gap-4">
+      {ok ? <Banner ok>saved</Banner> : null}
+      {taxa.map((t) => (
+        <div key={t.id}>
+          <Section>{t.label}</Section>
+          <div className="flex flex-col gap-1">
+            {(terms[t.slug] ?? []).length === 0 ? <span className="text-caption text-fg-subtle">No terms yet.</span> : null}
+            {(terms[t.slug] ?? []).map((term) => (
+              <label key={term.id} className="flex items-center gap-2">
+                {/* `setPageTerms` is editor-gated, so a reviewer got live checkboxes and a
+                    Save button that 403s — the one new write surface that did not take
+                    `canEdit`. */}
+                <input type="checkbox" disabled={!canEdit} checked={selected.has(term.id)} onChange={() => toggle(term.id)} />
+                <span className="text-sm text-fg">{term.label}</span>
+              </label>
+            ))}
+          </div>
+        </div>
+      ))}
+      {canEdit ? <Button size="sm" className="self-start" onPress={save} isDisabled={busy}>{busy ? "Saving…" : "Save terms"}</Button> : null}
+    </div>
+  );
+}
+
 function AuditLog({ api, pageId, onError }: { api: Api; pageId: string; onError: (s: string) => void }) {
   const [rows, setRows] = useState<AuditEntry[]>([]);
   useEffect(() => {

package/src/fields.tsx

@@ -8,10 +8,10 @@ import Highlight from "@tiptap/extension-highlight";
 import TaskItem from "@tiptap/extension-task-item";
 import TaskList from "@tiptap/extension-task-list";
 import StarterKit from "@tiptap/starter-kit";
-import { useEffect, useRef, useState, type DragEvent, type ReactNode } from "react";
+import { useCallback, useEffect, useRef, useState, type DragEvent, type ReactNode } from "react";
 import type { Api } from "./api";
 import { isRichTextDoc, richTextToPlainText } from "./rich-text";
-import type { FieldDefinition, FieldValue, FieldValues, Media, RichTextDoc } from "./types";
+import type { FieldDefinition, FieldValue, FieldValues, Media, ReferenceOption, ReferenceResult, RichTextDoc } from "./types";
 
 // Tokenized bare control (podoba's filled-field skin) for the native inputs that
 // don't map cleanly onto a podoba primitive (number/date/select/file).
@@ -260,6 +260,16 @@ function FieldInput({ def, value, onChange, api, hideLabelAs, siblings }: { def:
           <MediaField value={value as string | null} onChange={onChange} api={api} />
         </FieldShell>
       );
+    case "reference":
+      // Deliberately NOT FieldShell: the control is a row of <button>s, and a <label>
+      // wrapper would forward a click on the label text to the first one (opening the
+      // picker). Same reason `publish` and `boolean` opt out.
+      return (
+        <div className="flex w-full flex-col gap-2">
+          {label === undefined ? null : <span className="text-sm font-medium text-fg">{label}</span>}
+          <ReferenceField def={def} value={value} onChange={onChange} api={api} ariaLabel={hideLabelAs} />
+        </div>
+      );
     case "group":
       return (
         <FieldShell label={label}>
@@ -742,3 +752,248 @@ export function MediaPicker({ api, onClose, onPick }: { api: Api; onClose: () =>
     </ModalOverlay>
   );
 }
+
+// --- reference ------------------------------------------------------------------------
+//
+// A pointer to a record that is not this row. `select` + `optionsFrom` already does the
+// easy half — fetch `{ value, label }[]` once, render a `<select>` — and stays the right
+// answer for twenty campaigns. It has no answer for a thousand records: no search, no
+// paging, and no way to render the label of a stored value that is not in the one page it
+// fetched, so an existing row shows a uuid.
+//
+// So this control asks the server two different questions, and the second is the one that
+// makes it work on an existing row:
+//
+//   { search, limit, offset } -> browse / search  (the picker)
+//   { ids: [...] }            -> resolve labels   (what the closed control renders)
+//
+// The stored value stays an opaque id, so the same field points at a pramen row or at a
+// record in a system we do not own.
+
+const REFERENCE_PAGE_SIZE = 20;
+
+/** Tolerate a handler that answers with a bare array — the `optionsFrom` shape — so a
+ * `select`'s existing options handler can be pointed at a `reference` without a rewrite. */
+function asReferenceResult(raw: unknown): ReferenceResult {
+  if (Array.isArray(raw)) return { items: raw as ReferenceOption[] };
+  const r = raw as ReferenceResult | null;
+  return { items: Array.isArray(r?.items) ? r.items : [], hasMore: r?.hasMore };
+}
+
+/** Resolve labels for ids that are already stored.
+ *
+ * Only ever asks for ids it does not already have a label for, and keeps what it has
+ * across renders: a repeater of twenty references would otherwise re-resolve every one of
+ * them on every keystroke in a sibling field. */
+function useReferenceLabels(api: Api, from: string | undefined, ids: readonly string[]): Map<string, ReferenceOption> {
+  const [known, setKnown] = useState<Map<string, ReferenceOption>>(() => new Map());
+  // The ids, as a stable primitive — an array literal is a new identity every render.
+  //
+  // JSON, not `join(" ")`: an id here is OPAQUE, which is the whole premise of the field, so
+  // it may contain a space. Splitting on one turned a single external id into two ids that
+  // resolve to nothing, and the control showed "Loading..." forever.
+  const key = JSON.stringify(ids);
+  useEffect(() => {
+    if (!from) return;
+    const wanted = JSON.parse(key) as string[];
+    const missing = wanted.filter((id) => !known.has(id));
+    if (missing.length === 0) return;
+    let alive = true;
+    api
+      .call<ReferenceResult>(from, { ids: missing })
+      .then((r) => {
+        if (!alive) return;
+        const items = asReferenceResult(r).items;
+        setKnown((prev) => {
+          const next = new Map(prev);
+          for (const it of items) next.set(it.value, it);
+          // An id the handler did not answer for is recorded as UNRESOLVED rather than left
+          // missing — otherwise this effect asks for it again on every render, forever, for
+          // a record that has been deleted.
+          for (const id of missing) if (!next.has(id)) next.set(id, { value: id, label: "" });
+          return next;
+        });
+      })
+      .catch(() => {
+        if (!alive) return;
+        setKnown((prev) => {
+          const next = new Map(prev);
+          for (const id of missing) if (!next.has(id)) next.set(id, { value: id, label: "" });
+          return next;
+        });
+      });
+    return () => { alive = false; };
+  }, [api, from, key, known]);
+  return known;
+}
+
+/** What a stored id renders as while it is being resolved, and after it could not be. */
+function referenceLabel(id: string, known: Map<string, ReferenceOption>): { label: string; muted: boolean } {
+  const hit = known.get(id);
+  if (!hit) return { label: "Loading...", muted: true };
+  // An empty label is the recorded "no such record" — show the raw id, because that is the
+  // only thing left that identifies what the row points at.
+  return hit.label ? { label: hit.label, muted: false } : { label: id, muted: true };
+}
+
+function ReferenceField({ def, value, onChange, api, ariaLabel }: { def: FieldDefinition; value: FieldValue; onChange: (v: FieldValue) => void; api: Api; ariaLabel?: string }) {
+  const multiple = def.multiple === true;
+  // `unknown[]` before filtering: `FieldValue` is a union that INCLUDES array members, so
+  // `Array.isArray` narrows to a union of array types and the type-guard overload of
+  // `.filter` no longer resolves. The guard below is the real narrowing either way.
+  const ids: string[] = multiple
+    ? (Array.isArray(value) ? (value as unknown[]).filter((v): v is string => typeof v === "string") : [])
+    : typeof value === "string" && value !== "" ? [value] : [];
+  const known = useReferenceLabels(api, def.referenceFrom, ids);
+  const [picking, setPicking] = useState(false);
+
+  const pick = (opt: ReferenceOption) => {
+    if (multiple) {
+      if (!ids.includes(opt.value)) onChange([...ids, opt.value]);
+    } else {
+      onChange(opt.value);
+      setPicking(false);
+    }
+  };
+  const remove = (id: string) => onChange(multiple ? ids.filter((v) => v !== id) : null);
+
+  // Nothing to pick FROM. Said out loud rather than rendered as an empty control that
+  // silently does nothing when clicked — this is a schema mistake, and the person seeing it
+  // is the one who can fix it.
+  if (!def.referenceFrom) {
+    return <span className="text-sm text-danger">This reference field declares no `referenceFrom` handler.</span>;
+  }
+
+  return (
+    <div className="flex flex-col gap-2">
+      {ids.length === 0 ? (
+        <span className="text-sm text-fg-muted">Nothing selected.</span>
+      ) : (
+        <div className="flex flex-col gap-1">
+          {ids.map((id) => {
+            const { label, muted } = referenceLabel(id, known);
+            const hint = known.get(id)?.hint;
+            return (
+              <div key={id} className="flex items-center gap-2 rounded-[14px] bg-surface-card px-4 py-2.5">
+                <span className={`min-w-0 flex-1 truncate text-sm ${muted ? "text-fg-subtle" : "text-fg"}`}>{label}</span>
+                {hint ? <span className="shrink-0 text-caption text-fg-subtle">{hint}</span> : null}
+                <Button variant="ghost" size="sm" className="text-danger" onPress={() => remove(id)}>remove</Button>
+              </div>
+            );
+          })}
+        </div>
+      )}
+      <Button variant="secondary" size="sm" className="self-start" aria-label={ariaLabel} onPress={() => setPicking(true)}>
+        {multiple ? "+ Add" : ids.length > 0 ? "Change" : "Choose"}
+      </Button>
+      {picking ? (
+        <ReferencePicker
+          api={api}
+          from={def.referenceFrom}
+          title={def.label ?? def.name}
+          selected={ids}
+          multiple={multiple}
+          onPick={pick}
+          onClose={() => setPicking(false)}
+        />
+      ) : null}
+    </div>
+  );
+}
+
+function ReferencePicker({ api, from, title, selected, multiple, onPick, onClose }: {
+  api: Api;
+  from: string;
+  title: string;
+  selected: readonly string[];
+  multiple: boolean;
+  onPick: (opt: ReferenceOption) => void;
+  onClose: () => void;
+}) {
+  const [search, setSearch] = useState("");
+  const [items, setItems] = useState<ReferenceOption[]>([]);
+  const [hasMore, setHasMore] = useState(false);
+  const [loading, setLoading] = useState(true);
+  const [err, setErr] = useState("");
+  // Debounced: the fetch keys on `term`, so typing does not fire a request per character.
+  const [term, setTerm] = useState("");
+
+  useEffect(() => {
+    const id = setTimeout(() => setTerm(search.trim()), 250);
+    return () => clearTimeout(id);
+  }, [search]);
+
+  const load = useCallback(
+    (offset: number) => {
+      setLoading(true);
+      setErr("");
+      return api
+        .call<ReferenceResult>(from, { search: term || undefined, limit: REFERENCE_PAGE_SIZE, offset })
+        .then((raw) => {
+          const r = asReferenceResult(raw);
+          setItems((prev) => (offset === 0 ? r.items : [...prev, ...r.items]));
+          // A handler that omits `hasMore` is taken at its word only when it returned a
+          // SHORT page; a full one is assumed to have more — the same rule the page and
+          // collection lists use.
+          setHasMore(r.hasMore ?? r.items.length === REFERENCE_PAGE_SIZE);
+        })
+        .catch((e: unknown) => setErr(String((e as Error)?.message ?? e)))
+        .finally(() => setLoading(false));
+    },
+    [api, from, term],
+  );
+
+  useEffect(() => { void load(0); }, [load]);
+
+  return (
+    <ModalOverlay isOpen isDismissable onOpenChange={(open) => !open && onClose()}>
+      <ModalSurface className="w-full max-w-[560px] px-9 py-8">
+        <ModalDialog className="max-h-[86vh] overflow-auto outline-none">
+          <Heading level="1" className="mb-5 font-normal">
+            Choose <span className="text-fg-subtle">{title.toLowerCase()}</span>
+          </Heading>
+          <input
+            className={`${CONTROL} mb-3`}
+            type="search"
+            autoFocus
+            placeholder="Search"
+            aria-label="Search"
+            value={search}
+            onChange={(e) => setSearch(e.target.value)}
+          />
+          {err ? <div className="mb-2 rounded-lg border border-danger bg-surface-card px-3.5 py-2.5 text-small text-danger">{err}</div> : null}
+          <div className="flex flex-col gap-1">
+            {items.map((opt) => {
+              const already = selected.includes(opt.value);
+              return (
+                <button
+                  key={opt.value}
+                  type="button"
+                  disabled={already}
+                  onClick={() => onPick(opt)}
+                  className="flex items-center gap-3 rounded-lg px-3 py-2 text-left transition-colors hover:bg-surface-muted disabled:opacity-40"
+                >
+                  <span className="min-w-0 flex-1">
+                    <span className="block truncate text-sm text-fg">{opt.label}</span>
+                    {opt.hint ? <span className="block truncate text-caption text-fg-subtle">{opt.hint}</span> : null}
+                  </span>
+                  {already ? <span className="shrink-0 text-caption text-fg-subtle">selected</span> : null}
+                </button>
+              );
+            })}
+            {!loading && items.length === 0 ? <p className="px-3 py-2 text-sm text-fg-subtle">Nothing matches.</p> : null}
+            {loading ? <p className="px-3 py-2 text-sm text-fg-subtle">Loading...</p> : null}
+          </div>
+          {hasMore && !loading ? (
+            <div className="mt-3 text-center">
+              <Button variant="secondary" size="sm" onPress={() => void load(items.length)}>Load more</Button>
+            </div>
+          ) : null}
+          <div className="mt-3 text-right">
+            <Button variant="ghost" onPress={onClose}>{multiple ? "done" : "close"}</Button>
+          </div>
+        </ModalDialog>
+      </ModalSurface>
+    </ModalOverlay>
+  );
+}