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

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 };
+}