@gogitcms/design-system 0.16.0-next.10 → 0.16.0-next.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gogitcms/design-system",
-  "version": "0.16.0-next.10",
+  "version": "0.16.0-next.11",
   "main": "src/index.ts",
   "types": "src/index.ts",
   "// exports": "The root entry is the react-native source the SPAs, desktop app and mobile app consume. ./web is the plain-DOM build for server-rendered surfaces (the Astro docs site) that don't run react-native-web, and ./css ships the tokens as custom properties. The trailing wildcard keeps deep paths resolvable — plugin bundling and the Vite aliases reach into src/ directly.",

package/src/__tests__/ContentBrowser.references.test.tsx

@@ -0,0 +1,179 @@
+import React from "react";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+import { ThemeProvider } from "../ThemeProvider";
+import { ContentBrowser, type CmsEntry, type CmsNavSection, type EntryField } from "../components/ContentBrowser";
+import type { ReferenceApi, ReferenceDef, ReferenceTarget } from "../references";
+
+// Force the desktop layout (jsdom reports width 0 → mobile otherwise).
+jest.mock("../ThemeProvider", () => {
+  const actual = jest.requireActual("../ThemeProvider");
+  return { ...actual, useResponsive: () => ({ width: 1300, height: 900, isDesktop: true, isMobile: false }) };
+});
+
+const ada: ReferenceTarget = { id: "au1", collection: "authors", path: "content/authors/ada.md", key: "content/authors/ada.md", label: "Ada Lovelace" };
+const bob: ReferenceTarget = { id: "au2", collection: "authors", path: "content/authors/bob.md", key: "content/authors/bob.md", label: "Bob" };
+const byKey: Record<string, ReferenceTarget> = { [ada.key]: ada, [bob.key]: bob };
+
+function makeApi(over: Partial<ReferenceApi> = {}): ReferenceApi {
+  return {
+    search: jest.fn(async ({ query }) => [ada, bob].filter((t) => !query || t.label.toLowerCase().includes(query.toLowerCase()))),
+    resolve: jest.fn(async (_collections: string[], _key: string, keys: string[]) =>
+      keys.map((k) => ({ key: k, target: byKey[k] ?? null, ambiguous: false, candidates: [] })),
+    ),
+    referrers: jest.fn(async () => [{ id: "d2", collection: "articles", path: "content/articles/other.md", label: "Other", fieldPath: "related.0" }]),
+    ...over,
+  };
+}
+
+// The editor keeps unsaved edits per document id in localStorage, and every
+// test here renders document "a": clear it so one test's pick never seeds the
+// next test's field.
+beforeEach(() => {
+  window.localStorage.clear();
+});
+
+const sections: CmsNavSection[] = [
+  { title: "Content", items: [{ key: "articles", label: "Articles", icon: "newspaper" }] },
+];
+
+const authorDef: ReferenceDef = { collections: ["authors"], key: "_path", keyName: "ref", embed: [], onDelete: "restrict" };
+const embedDef: ReferenceDef = {
+  collections: ["authors"], key: "_path", keyName: "ref", onDelete: "restrict",
+  embed: [{ name: "name", source: "name" }, { name: "url", source: "/authors/{{slug}}/" }],
+};
+
+// `null` renders without a references seam; the default is a working one.
+// (A default parameter also fires for an explicit `undefined`, so the no-seam
+// case has to be spelled `null`.)
+function renderWith(fields: EntryField[], api: ReferenceApi | null = makeApi()) {
+  const onSave = jest.fn();
+  const entry: CmsEntry = { id: "a", path: "content/articles/a.md", title: "Alpha", body: "", fields };
+  render(
+    <ThemeProvider>
+      <ContentBrowser
+        workspace={{ name: "acme/site", initials: "AC", branch: "main", changed: 0 }}
+        sections={sections}
+        activeNavKey="articles"
+        onSelectNav={() => {}}
+        entries={[entry]}
+        userInitials="ED"
+        references={api ?? undefined}
+        onSaveEntry={onSave}
+      />
+    </ThemeProvider>,
+  );
+  return onSave;
+}
+
+test("a string reference resolves its key to the target's label", async () => {
+  const api = makeApi();
+  renderWith([{ name: "author", label: "Author", type: "string", component: "reference", reference: authorDef, value: ada.key }], api);
+  expect(await screen.findByText("Ada Lovelace")).toBeInTheDocument();
+  expect(screen.getByTestId("reference-key")).toHaveTextContent(ada.key);
+  expect(api.resolve).toHaveBeenCalledWith(["authors"], "_path", [ada.key]);
+});
+
+test("a key naming nothing shows the missing state and keeps the key", async () => {
+  renderWith([{ name: "author", label: "Author", type: "string", component: "reference", reference: authorDef, value: "content/authors/gone.md" }]);
+  expect(await screen.findByTestId("reference-missing")).toBeInTheDocument();
+  expect(screen.getByTestId("reference-key")).toHaveTextContent("content/authors/gone.md");
+});
+
+test("picking a document from the picker writes its key", async () => {
+  const api = makeApi();
+  renderWith([{ name: "author", label: "Author", type: "string", component: "reference", reference: authorDef, value: "" }], api);
+  expect(screen.getByText("No document selected")).toBeInTheDocument();
+
+  fireEvent.click(screen.getByTestId("reference-choose"));
+  fireEvent.click(await screen.findByTestId(`reference-row-${bob.id}`));
+
+  // The control now holds Bob's key and resolves it.
+  expect(await screen.findByText("Bob")).toBeInTheDocument();
+  expect(screen.getByTestId("reference-key")).toHaveTextContent(bob.key);
+  expect(api.search).toHaveBeenCalledWith(expect.objectContaining({ collections: ["authors"], key: "_path" }));
+});
+
+test("an object reference shows its embedded copies read-only and picks by key child", async () => {
+  renderWith([
+    {
+      name: "author", label: "Author", type: "object", component: "reference", reference: embedDef,
+      fields: [
+        { name: "ref", type: "string", value: undefined },
+        { name: "name", label: "Name", type: "string", value: undefined },
+        { name: "url", label: "URL", type: "string", value: undefined },
+      ],
+      value: { ref: ada.key, name: "Ada Lovelace", url: "/authors/ada/" },
+    },
+  ]);
+  expect(await screen.findByTestId("reference-target")).toHaveTextContent("Ada Lovelace");
+  const copies = screen.getByTestId("reference-copies");
+  expect(copies).toHaveTextContent("/authors/ada/");
+  expect(copies).toHaveTextContent("Copied from Ada Lovelace");
+  // No input is offered for a copy: the server owns them.
+  expect(screen.queryByDisplayValue("/authors/ada/")).not.toBeInTheDocument();
+
+  fireEvent.click(screen.getByTestId("reference-choose"));
+  fireEvent.click(await screen.findByTestId(`reference-row-${bob.id}`));
+  expect(screen.getByTestId("reference-key")).toHaveTextContent(bob.key);
+  // The old copies stay until the server replaces them on save; once the new
+  // key resolves the caption names the new target.
+  await waitFor(() => expect(screen.getByTestId("reference-copies")).toHaveTextContent("Copied from Bob"));
+  expect(screen.getByTestId("reference-copies")).toHaveTextContent("/authors/ada/");
+});
+
+test("an array of references renders a picker per item", async () => {
+  renderWith([
+    { name: "related", label: "Related", type: "array", of: "string", component: "list", reference: authorDef, value: [ada.key, bob.key] },
+  ]);
+  expect(await screen.findAllByTestId("reference-choose")).toHaveLength(2);
+  expect(await screen.findByText("Bob")).toBeInTheDocument();
+});
+
+test("the Details modal shows the document's metadata and its references both ways", async () => {
+  renderWith([
+    { name: "title", label: "Title", type: "string", value: "Alpha" },
+    { name: "author", label: "Author", type: "string", component: "reference", reference: authorDef, value: ada.key },
+    { name: "editor", label: "Editor", type: "string", component: "reference", reference: authorDef, value: "content/authors/gone.md" },
+  ]);
+  // Nothing about references sits in the document body itself.
+  await screen.findByText("Ada Lovelace");
+  expect(screen.queryByText("Referenced by")).not.toBeInTheDocument();
+
+  fireEvent.click(screen.getByTestId("detail-menu"));
+  fireEvent.click(screen.getByTestId("detail-details"));
+  const modal = await screen.findByTestId("document-details");
+  expect(modal).toHaveTextContent("content/articles/a.md");
+  expect(modal).toHaveTextContent("Articles");
+
+  const refs = await screen.findByTestId("details-references");
+  await waitFor(() => expect(refs).toHaveTextContent("Ada Lovelace"));
+  expect(refs).toHaveTextContent("author");
+  expect(refs).toHaveTextContent("content/authors/gone.md — missing");
+
+  const referrers = await screen.findByTestId("details-referrers");
+  await waitFor(() => expect(referrers).toHaveTextContent("Other"));
+  expect(referrers).toHaveTextContent("related.0");
+
+  fireEvent.click(screen.getByTestId("details-close"));
+  expect(screen.queryByTestId("document-details")).not.toBeInTheDocument();
+});
+
+test("without a references seam the field renders read-only", async () => {
+  renderWith([{ name: "author", label: "Author", type: "string", component: "reference", reference: authorDef, value: ada.key }], null);
+  // Nothing resolves and the picker cannot open: the key shows raw.
+  expect(await screen.findByTestId("reference-key")).toHaveTextContent(ada.key);
+  fireEvent.click(screen.getByTestId("reference-choose"));
+  await new Promise((r) => setTimeout(r, 50));
+  expect(screen.queryByText("Choose a document")).not.toBeInTheDocument();
+  expect(screen.queryByTestId("reference-target")).not.toBeInTheDocument();
+  expect(screen.queryByTestId("reference-missing")).not.toBeInTheDocument();
+
+  // Details still opens — it is a read — with the metadata and the raw key,
+  // but claims nothing about what the key resolves to.
+  fireEvent.click(screen.getByTestId("detail-menu"));
+  fireEvent.click(screen.getByTestId("detail-details"));
+  const modal = await screen.findByTestId("document-details");
+  expect(modal).toHaveTextContent("content/articles/a.md");
+  expect(screen.getByTestId("details-references")).toHaveTextContent(ada.key);
+  expect(screen.queryByTestId("details-referrers")).not.toBeInTheDocument();
+});

package/src/components/ContentBrowser.tsx

@@ -32,6 +32,9 @@ import {
 } from "./CollabField";
 import { clamp, reorder, slotAtX } from "./reorder";
 import { MediaField, MediaProvider, DocumentPathProvider, useFieldMedia } from "./MediaField";
+import { ReferenceField, ReferenceProvider } from "./ReferenceField";
+import { DocumentDetails } from "./DocumentDetails";
+import type { ReferenceApi, ReferenceDef } from "../references";
 import { MediaBrowser } from "./MediaBrowser";
 import { FormsBrowser } from "./FormsBrowser";
 import { FORMS_NAV_KEY, formsNavKey, isFormsNavKey, parseFormsNavKey, type FormsApi } from "../forms";
@@ -76,6 +79,12 @@ export type EntryField = {
   // field these describe its *items*, making each one a media picker.
   media?: string;
   storeAs?: string;
+  // For a document picker (`component: "reference"`, or an array whose items
+  // are references): what the field points at and stores. An object-shaped
+  // reference's `fields` are the derived children — the key child and the
+  // embedded copies — which the server recomputes on every save and the
+  // editor shows read-only (docs/references.md).
+  reference?: ReferenceDef;
   value: unknown;
   // Item type for an array field (string | number | boolean | object).
   of?: string;
@@ -360,6 +369,11 @@ export type ContentBrowserProps = {
   // store gets.
   media?: MediaApi;
 
+  // References data seam, the same split (docs/references.md §6): the DS owns
+  // the document picker and the "Referenced by" list, the host owns fetching.
+  // Omitted → reference fields render read-only.
+  references?: ReferenceApi;
+
   // Forms data seam, the same split (docs/forms.md §10.2). Omitted → the Forms
   // surface never renders, which is what a config declaring no forms looks like.
   forms?: FormsApi;
@@ -878,6 +892,28 @@ function FieldControlInner(props: FieldControlProps) {
 
   const comp = resolveComponent(field);
 
+  // ---- references ----------------------------------------------------------
+  // Like media, one component for two field types: a string stores the key, an
+  // object stores the key plus the server-computed copies. Checked before the
+  // type branches for the same reason media is.
+  if (comp === "reference" && field.reference) {
+    return (
+      <View style={{ gap: t.space(2) }}>
+        {labelNode}
+        <ReferenceField
+          value={value}
+          onChange={onChange}
+          shape={field.type === "object" ? "object" : "string"}
+          def={field.reference}
+          embedFields={field.fields}
+          readOnly={readOnly}
+          error={!!error}
+        />
+        {errorNode}
+      </View>
+    );
+  }
+
   // ---- media ------------------------------------------------------------
   // Checked before the type-specific branches because `media` is the one
   // component valid for two different field types: a string field stores a path,
@@ -1681,6 +1717,9 @@ function ListControl({
     fields: field.fields,
     value: null,
     ...(field.media ? { component: "media", media: field.media, storeAs: field.storeAs } : {}),
+    // An array that declares a reference makes each item a document picker, the
+    // same way an array naming a media set makes each item a media picker.
+    ...(field.reference ? { component: "reference", reference: field.reference } : {}),
   };
 
   // The list's own path, from the FieldControl wrapping this control; an item
@@ -2503,14 +2542,18 @@ function PromptDialog({
   );
 }
 
-// DetailMenu is the "..." menu in the detail header: Rename / Move to folder /
-// Delete, each shown only when its handler is provided. Delete has an inline
-// confirm step; Rename/Move open a PromptDialog owned by EntryDetail.
+// DetailMenu is the "..." menu in the detail header: Details / Rename / Move to
+// folder / Delete, each shown only when its handler is provided. Details is a
+// read (metadata and references, see DocumentDetails) and so is offered on
+// read-only documents too; Delete has an inline confirm step; Rename/Move open
+// a PromptDialog owned by EntryDetail.
 function DetailMenu({
+  onDetails,
   onRename,
   onMove,
   onDelete,
 }: {
+  onDetails?: () => void;
   onRename?: () => void;
   onMove?: () => void;
   onDelete?: () => void;
@@ -2541,6 +2584,12 @@ function DetailMenu({
             borderRadius: t.radius.md, paddingVertical: t.space(1),
           }}
         >
+          {onDetails ? (
+            <Pressable testID="detail-details" onPress={() => { close(); onDetails(); }} style={rowStyle}>
+              <Icon name="fileText" size={15} color={t.color.textSecondary} />
+              <Text variant="sm">Details</Text>
+            </Pressable>
+          ) : null}
           {onRename ? (
             <Pressable testID="detail-rename" onPress={() => { close(); onRename(); }} style={rowStyle}>
               <Icon name="file" size={15} color={t.color.textSecondary} />
@@ -2684,6 +2733,7 @@ function EntryDetail({
   onDeleteEntry,
   onRename,
   onMove,
+  collection,
   collectionPath,
   folderOptions,
   history,
@@ -2708,6 +2758,8 @@ function EntryDetail({
   onDeleteEntry?: (entry: CmsEntry) => Promise<void> | void;
   onRename?: (entry: CmsEntry, filename: string) => Promise<void> | void;
   onMove?: (entry: CmsEntry, folder: string) => Promise<void> | void;
+  // The collection the document belongs to, shown in its Details.
+  collection?: string;
   collectionPath?: string;
   // Existing folders (relative to the glob base) offered by the move autocomplete.
   folderOptions?: string[];
@@ -2735,6 +2787,19 @@ function EntryDetail({
   const canRename = !readOnly && !!onRename;
   const canMove = !readOnly && !!onMove && glob.hierarchical;
   const [prompt, setPrompt] = useState<"rename" | "move" | null>(null);
+  // The Details modal: metadata and references, opened from the menu.
+  const [showDetails, setShowDetails] = useState(false);
+  // A header action that failed — a delete refused because other documents
+  // reference this one — reported inline, where the Delete was pressed.
+  const [actionError, setActionError] = useState<string | null>(null);
+  const deleteEntry = onDeleteEntry
+    ? () => {
+        setActionError(null);
+        Promise.resolve(onDeleteEntry(entry)).catch((e: unknown) => {
+          setActionError(e instanceof Error ? e.message : "Couldn’t delete the document.");
+        });
+      }
+    : undefined;
   // Per-field "your value was replaced" counters, bumped by a restore. Only the
   // host-supplied body editor reads them (see FieldSlotArgs.resetNonce); every
   // built-in control is controlled and needs no telling.
@@ -3191,13 +3256,12 @@ function EntryDetail({
             testID="document-history-toggle"
           />
         ) : null}
-        {canRename || canMove || (canDelete && onDeleteEntry) ? (
-          <DetailMenu
-            onRename={canRename ? () => setPrompt("rename") : undefined}
-            onMove={canMove ? () => setPrompt("move") : undefined}
-            onDelete={canDelete && onDeleteEntry ? () => onDeleteEntry(entry) : undefined}
-          />
-        ) : null}
+        <DetailMenu
+          onDetails={() => setShowDetails(true)}
+          onRename={canRename ? () => setPrompt("rename") : undefined}
+          onMove={canMove ? () => setPrompt("move") : undefined}
+          onDelete={canDelete && deleteEntry ? deleteEntry : undefined}
+        />
         {onCollapse ? (
           <IconButton name="panelLeft" size="sm" label="Collapse column" onPress={onCollapse} testID="column-collapse" />
         ) : null}
@@ -3247,6 +3311,7 @@ function EntryDetail({
           contentContainerStyle={{ padding: t.space(5), gap: t.space(4) }}
         >
           {saveHandler && error ? <FormAlert message={error} onDismiss={clearError} /> : null}
+          {actionError ? <FormAlert message={actionError} onDismiss={() => setActionError(null)} /> : null}
           {groupPath.length > 0 ? (
             <Pressable
               testID="group-back"
@@ -3286,6 +3351,7 @@ function EntryDetail({
         <DocumentPathProvider path={entry.path}>
         <View key={entry.id} style={{ padding: t.space(5), gap: t.space(4), flex: 1 }}>
           {saveHandler && error ? <FormAlert message={error} onDismiss={clearError} /> : null}
+          {actionError ? <FormAlert message={actionError} onDismiss={() => setActionError(null)} /> : null}
           <View style={{ gap: t.space(2) }}>
             <Text variant="label" color="tertiary">Title</Text>
             <Text variant="h2">{entry.title}</Text>
@@ -3300,6 +3366,9 @@ function EntryDetail({
         </DocumentPathProvider>
       )}
 
+      {showDetails ? (
+        <DocumentDetails entry={entry} collection={collection} onClose={() => setShowDetails(false)} />
+      ) : null}
       {prompt === "rename" && onRename ? (
         <PromptDialog
           title="Rename file"
@@ -3402,6 +3471,8 @@ type ColumnModel = {
   canDelete?: boolean;
   canRename: boolean;
   canMove: boolean;
+  // The tab's collection key, for the document's Details.
+  collection?: string;
   collectionPath?: string;
   /** Set for a custom column (see OpenTab.content); `entry` is then unused. */
   content?: React.ReactNode;
@@ -4085,6 +4156,7 @@ function DesktopBrowser(props: ContentBrowserProps) {
         canDelete: tab.canDelete,
         canRename: !!tab.canRename,
         canMove: !!tab.canMove,
+        collection: tab.collection,
         collectionPath: tab.collectionPath,
         content: tab.content,
         title: tab.title,
@@ -4276,6 +4348,9 @@ function DesktopBrowser(props: ContentBrowserProps) {
           onDeleteEntry={onDeleteEntry}
           onRename={col.canRename ? onRename : undefined}
           onMove={col.canMove ? onMove : undefined}
+          // A host-managed tab names its collection; a column the browser opened
+          // itself (uncontrolled selection) belongs to the active one.
+          collection={navLabelFor(props.sections, col.collection || props.activeNavKey) ?? (col.collection || props.activeNavKey)}
           collectionPath={col.collectionPath}
           folderOptions={moveFolders}
           active={!showCreate && col.active}
@@ -5153,6 +5228,7 @@ function MobileBrowser(props: ContentBrowserProps) {
           onDeleteEntry={onDeleteEntry}
           onRename={onRename}
           onMove={onMove}
+          collection={navLabelFor(props.sections, props.activeNavKey) ?? props.activeNavKey}
           collectionPath={collectionPath}
           folderOptions={moveFolders}
         />
@@ -5404,7 +5480,9 @@ export function ContentBrowser(props: ContentBrowserProps) {
   // object store) renders media fields read-only.
   return (
     <MediaProvider api={props.media}>
-      {isDesktop ? <DesktopBrowser {...withSections} /> : <MobileBrowser {...withSections} />}
+      <ReferenceProvider api={props.references}>
+        {isDesktop ? <DesktopBrowser {...withSections} /> : <MobileBrowser {...withSections} />}
+      </ReferenceProvider>
     </MediaProvider>
   );
 }

package/src/fieldComponents.ts

@@ -7,12 +7,12 @@
 // valid for both string (ISO-8601 text) and number (epoch).
 
 export const componentsByType: Record<string, string[]> = {
-  string: ["input", "textarea", "body", "slug", "email", "url", "date", "datetime", "select", "media"],
+  string: ["input", "textarea", "body", "slug", "email", "url", "date", "datetime", "select", "media", "reference"],
   boolean: ["checkbox", "switch"],
   integer: ["number", "stepper", "telephone", "date", "datetime", "select"],
   float: ["number", "stepper", "telephone", "date", "datetime", "select"],
   array: ["list", "mixedList"],
-  object: ["inlineGroup", "group", "media"],
+  object: ["inlineGroup", "group", "media", "reference"],
 };
 
 export const defaultComponentByType: Record<string, string> = {

package/src/index.ts

@@ -172,6 +172,21 @@ export type {
   MediaFacets,
 } from "./media";
 
+// References: the document picker, "referenced by", and the host data seam
+export { ReferenceField, ReferencePicker, ReferenceProvider, useReferenceApi } from "./components/ReferenceField";
+export type { ReferenceFieldProps, ReferencePickerProps } from "./components/ReferenceField";
+export { DocumentDetails, collectSites } from "./components/DocumentDetails";
+export type { DocumentDetailsProps, DetailsField } from "./components/DocumentDetails";
+export { DEFAULT_REFERENCE_KEY_NAME, referenceKey, referenceValue } from "./references";
+export type {
+  ReferenceApi,
+  ReferenceDef,
+  ReferenceEmbed,
+  ReferenceTarget,
+  ReferenceResolution,
+  Referrer,
+} from "./references";
+
 // Field components registry (mirror of the Go schema's component set)
 export {
   componentsByType,

package/src/references.ts

@@ -0,0 +1,97 @@
+// The document picker's declaration and its host data seam.
+//
+// This is the TypeScript mirror of packages/importer/schema/references.go — the
+// Go file is the source of truth validated on config import; keep the two in
+// sync. A reference field points at documents of other collections (or its
+// own). A string field stores the target's key; an object field stores the key
+// under `keyName` plus embedded copies the SERVER computes on every save — the
+// editor shows those copies read-only and never writes them
+// (docs/references.md).
+
+// ReferenceDef is a field's `reference:` block as the API delivers it.
+export interface ReferenceDef {
+  // The collections the field may point at.
+  collections: string[];
+  // Which rendered form of the target the field stores: "_path" (the target's
+  // project-relative path) or the name of a field on the target.
+  key: string;
+  // For the object shape, the child that holds the key ("ref" unless renamed).
+  keyName: string;
+  // The embedded copies, in the order the derived children appear.
+  embed: ReferenceEmbed[];
+  // What deleting a referenced document does: restrict | unset.
+  onDelete: string;
+}
+
+export interface ReferenceEmbed {
+  name: string;
+  source: string;
+}
+
+// ReferenceTarget is one document a reference can point at, keyed as the field
+// stores it. `path` is repository-relative, like a document's.
+export interface ReferenceTarget {
+  id: string;
+  collection: string;
+  path: string;
+  key: string;
+  label: string;
+}
+
+// ReferenceResolution is the answer to "what does this stored key name?".
+// `target` null with `ambiguous` false is a dangling reference; `ambiguous`
+// means a field key several documents share, and `candidates` holds them.
+export interface ReferenceResolution {
+  key: string;
+  target?: ReferenceTarget | null;
+  ambiguous: boolean;
+  candidates: ReferenceTarget[];
+}
+
+// Referrer is one document that points at another, and the field it does so
+// from.
+export interface Referrer {
+  id: string;
+  collection: string;
+  path: string;
+  label: string;
+  fieldPath: string;
+}
+
+// ReferenceApi is the data seam between the design system and its host, the
+// same split as MediaApi: the DS owns the picker and the display, the host owns
+// fetching. Omitting it from ContentBrowser renders reference fields read-only.
+export interface ReferenceApi {
+  // Documents the field may point at — the picker's list. `collections` and
+  // `key` are the field's ReferenceDef; `query` matches labels.
+  search: (params: { collections: string[]; key: string; query?: string; limit?: number }) => Promise<ReferenceTarget[]>;
+  // Resolve stored keys to their documents, batched per document.
+  resolve: (collections: string[], key: string, keys: string[]) => Promise<ReferenceResolution[]>;
+  // Documents that point at one — "Referenced by". Omit to hide the section.
+  referrers?: (documentId: string) => Promise<Referrer[]>;
+}
+
+// The key child an object reference stores by default. Mirrors the Go
+// DefaultKeyName.
+export const DEFAULT_REFERENCE_KEY_NAME = "ref";
+
+// referenceKey reads the stored key out of a reference field's value, for
+// either shape. Empty when the field is unset.
+export function referenceKey(value: unknown, shape: "string" | "object", def: ReferenceDef): string {
+  if (shape === "object") {
+    if (typeof value !== "object" || value === null) return "";
+    const key = (value as Record<string, unknown>)[def.keyName || DEFAULT_REFERENCE_KEY_NAME];
+    return typeof key === "string" ? key.trim() : "";
+  }
+  return typeof value === "string" ? value.trim() : "";
+}
+
+// referenceValue builds the value the field writes when a target is picked:
+// the key alone in a string field; in an object field the key under keyName,
+// with any copies the value already carried kept until the server replaces
+// them on save — writing nothing else is what keeps the copies the server's.
+export function referenceValue(target: ReferenceTarget, shape: "string" | "object", def: ReferenceDef, previous: unknown): unknown {
+  if (shape === "string") return target.key;
+  const prev = typeof previous === "object" && previous !== null ? (previous as Record<string, unknown>) : {};
+  return { ...prev, [def.keyName || DEFAULT_REFERENCE_KEY_NAME]: target.key };
+}