Skip to content

The Open Standard for Generative UI

12.6 KB
Raw Blame
// library.extend: derives a library definition from a base plus additions, overrides and removals.
import * as z from "zod/v4/core";
import type {
  AnyAction,
  ComponentGroup,
  DefinedComponent,
  LibraryDefinition,
  LibraryExtension,
} from "./library";
import { isReactiveSchema, markReactive } from "./reactive";
import { copySchemaTags, getUnionOptions, getZodDef, unwrap } from "./signature";

// ─── library.extend ─────────────────────────────────────────────────────────

type Comp<C> = DefinedComponent<any, C>;

const fail = (message: string): never => {
  throw new Error(`[extend] ${message}`);
};

// add ProductCard into "Card", remove Frame -> the base parts with Card, every parent and the groups updated
export function extendDefinition<C>(
  base: LibraryDefinition<C, AnyAction>,
  ext: LibraryExtension<C, AnyAction>,
): LibraryDefinition<C, AnyAction> {
  const changes = applyComponentVerbs(base, ext.components);
  const slots = findContentSlots(changes);
  const placements = placeInSlots(changes, slots);
  return {
    ...base,
    id: undefined, // a derived library does not inherit the base's public id
    components: rebuildComponents(changes, placements),
    componentGroups: withoutRemoved(base.componentGroups, changes.removed),
    functions: [...(base.functions ?? []), ...(ext.functions?.add ?? [])],
    actions: [...(base.actions ?? []), ...(ext.actions?.add ?? [])],
  };
}

interface ComponentChanges<C> {
  /** The library's components after the verbs, in order. */
  byName: Map<string, Comp<C>>;
  /** Every schema that stands for a component, old, new or removed, mapped to its name. */
  nameOf: Map<unknown, string>;
  /** "ProductCard" -> ["Card"] */
  slotRequests: Map<string, string[]>;
  removed: Set<string>;
}

// add [Card], override [Image], remove ["Frame"] -> Stack, Text, Image (new), Card
function applyComponentVerbs<C>(
  base: LibraryDefinition<C, AnyAction>,
  verbs: LibraryExtension<C, AnyAction>["components"] = {},
): ComponentChanges<C> {
  const byName = new Map(base.components.map((c) => [c.name, c]));
  const nameOf = new Map<unknown, string>(base.components.map((c) => [c.props, c.name]));
  const slotRequests = new Map<string, string[]>();
  const touched = new Set<string>(); // added or overridden in this call
  const put = (comp: Comp<C>) => {
    byName.set(comp.name, comp);
    nameOf.set(comp.props, comp.name);
    touched.add(comp.name);
  };

  for (const entry of verbs.add ?? []) {
    const { component, slots } = "slots" in entry ? entry : { component: entry, slots: undefined };
    const name = component.name;
    if (byName.has(name)) fail(`Component "${name}" already exists. Use override.`);
    if (slots?.length === 0) fail(`"slots" for "${name}" is empty. Omit it to only list it.`);
    put(component);
    if (slots) slotRequests.set(name, slots);
  }
  const overridden = new Set<string>();
  for (const comp of verbs.override ?? []) {
    if (!byName.has(comp.name))
      fail(`Cannot override "${comp.name}": not in the library. Use add.`);
    if (overridden.has(comp.name)) fail(`Component "${comp.name}" is overridden twice.`);
    overridden.add(comp.name);
    put(comp);
  }
  const removed = new Set(verbs.remove);
  for (const name of removed) {
    if (touched.has(name))
      fail(`Cannot remove "${name}": it is added or overridden in the same call.`);
    if (!byName.delete(name)) fail(`Cannot remove "${name}": not in the library.`);
    if (name === base.root) fail(`Cannot remove "${name}": it is the library root.`);
  }
  return { byName, nameOf, slotRequests, removed };
}

// A content slot holds a union of components, maybe optional or in an array:
// children: z.array(z.union([Text.ref, Image.ref])) -> that union
function slotUnion(schema: unknown, nameOf: Map<unknown, string>): unknown {
  const inner = unwrap(schema);
  const def = getZodDef(inner);
  if (def?.type === "array") return slotUnion(def.element, nameOf);
  return getUnionOptions(inner)?.some((o) => nameOf.has(o)) ? inner : undefined;
}

// Stack(children: (Text | Image)[]) -> ["Stack.children"]
function findContentSlots<C>({ byName, nameOf }: ComponentChanges<C>): string[] {
  const slots: string[] = [];
  for (const comp of byName.values()) {
    for (const [prop, schema] of Object.entries(comp.props.shape)) {
      if (slotUnion(schema, nameOf)) slots.push(`${comp.name}.${prop}`);
    }
  }
  return slots;
}

// ProductCard asks for ["Card"] -> "Card.children" -> ["ProductCard"]
function placeInSlots<C>(changes: ComponentChanges<C>, slots: string[]): Map<string, string[]> {
  const placements = new Map<string, string[]>();
  for (const [name, requested] of changes.slotRequests) {
    for (const slot of requested) {
      const path = resolveSlot(slot, name, slots, changes.byName);
      const placed = placements.get(path) ?? [];
      // slots: ["Stack.children", "Stack"] name one path; Card joins it once
      if (!placed.includes(name)) placements.set(path, [...placed, name]);
    }
  }
  return placements;
}

// "Stack.children" stays; "Stack" -> "Stack.children" when Stack has exactly one content slot
function resolveSlot(slot: string, name: string, slots: string[], byName: Map<string, unknown>) {
  if (slots.includes(slot)) return slot;
  const parent = slot.split(".")[0]!;
  const candidates = slots.filter((s) => s.startsWith(`${parent}.`));
  if (!slot.includes(".") && candidates.length === 1) return candidates[0]!;
  const what = `Slot "${slot}" for "${name}"`;
  if (!byName.has(parent)) fail(`${what}: "${parent}" is not in the library.`);
  if (!candidates.length)
    fail(
      `${what}: "${parent}" has no content slot (a prop that is a union of components, or an optional or array of one).`,
    );
  return fail(`${what} must be one content slot. Candidates: ${candidates.join(", ")}.`);
}

/** The prop being rebuilt, its content-slot union if any, and the schemas slotted into it. */
type Slot = { path: string; union: unknown; added: unknown[] };

// Zod parents hold their children's schema objects, not their names, so every parent of an
// overridden, removed or slotted-in component is cloned to point at the final schemas.
// Schemas with nothing to change keep their identity. Built in two passes so cycles work:
// every clone exists (with an empty shape) before any shape is filled, so Card(body: Stack)
// slotted into Stack.children points at the new Stack, and the new Stack at the new Card.
function rebuildComponents<C>(
  changes: ComponentChanges<C>,
  placements: Map<string, string[]>,
): Comp<C>[] {
  const { byName, nameOf, removed } = changes;
  const final = new Map<string, Comp<C>>(byName);
  const shapes = new Map<string, Record<string, unknown>>();
  for (const name of findRebuilt(changes, placements)) {
    const comp = byName.get(name)!;
    const shape: Record<string, unknown> = {};
    const props = cloneSchema(comp.props, {
      get shape() {
        return shape; // filled below, read by zod only after
      },
    }) as z.$ZodObject;
    final.set(name, { ...comp, props, ref: props as unknown as Comp<C>["ref"] });
    shapes.set(name, shape);
  }
  const finalProps = (name: string) => final.get(name)!.props;

  const onlyType = (name: string | undefined, slot: Slot): never =>
    fail(`Cannot remove "${name}": it is the only type allowed in ${slot.path}.`);

  // z.array(z.union([Text, Frame])) with Frame removed -> z.array(z.union([Text]))
  const rebind = (schema: unknown, slot: Slot, memo: Map<unknown, unknown>): unknown => {
    const name = nameOf.get(schema);
    if (name !== undefined) {
      if (removed.has(name)) onlyType(name, slot);
      return finalProps(name);
    }
    const def = getZodDef(schema);
    if (!def || def.type === "lazy") return schema;
    if (memo.has(schema)) return memo.get(schema);
    memo.set(schema, schema); // cycle guard
    const walk = (child: unknown) => rebind(child, slot, memo);

    const patch: Record<string, unknown> = {};
    const options = getUnionOptions(schema);
    const holdsComponents = options?.some((o) => nameOf.has(o));
    for (const [key, value] of Object.entries(def)) {
      if (key === "checks" || (holdsComponents && key === "options")) continue;
      const next = rebindField(key, value, walk);
      if (!sameField(next, value)) patch[key] = next;
    }
    if (holdsComponents) {
      // Text | Image | Frame, Frame removed and Card slotted in -> Text | Image | Card
      const kept = options!.filter((o) => !removed.has(nameOf.get(o) ?? "")).map(walk);
      const added = schema === slot.union ? slot.added.filter((a) => !kept.includes(a)) : [];
      if (!kept.length && !added.length) onlyType(nameOf.get(options![0]), slot);
      const next = [...kept, ...added];
      if (!sameField(next, options)) patch.options = next;
    }
    const out = Object.keys(patch).length ? cloneSchema(schema, patch) : schema;
    memo.set(schema, out);
    return out;
  };

  for (const [name, shape] of shapes) {
    for (const [prop, schema] of Object.entries(byName.get(name)!.props.shape)) {
      const path = `${name}.${prop}`;
      const added = (placements.get(path) ?? []).map(finalProps);
      shape[prop] = rebind(schema, { path, union: slotUnion(schema, nameOf), added }, new Map());
    }
  }
  return [...final.values()];
}

// Stack gets a slotted-in Card, Frame nests a removed or overridden Image, or a component nests
// one of those (repeated until nothing changes, so cycles settle) -> those names
function findRebuilt<C>(
  { byName, nameOf, removed }: ComponentChanges<C>,
  placements: Map<string, string[]>,
): Set<string> {
  const nested = new Map<string, Set<unknown>>();
  for (const [name, comp] of byName) {
    const found = new Set<unknown>();
    for (const schema of Object.values(comp.props.shape)) nestedComponents(schema, nameOf, found);
    nested.set(name, found);
  }
  const stale = (s: unknown) => {
    const name = nameOf.get(s)!;
    return removed.has(name) || byName.get(name)!.props !== s;
  };
  const slotted = new Set([...placements.keys()].map((path) => path.split(".")[0]!));
  const rebuilt = new Set([...byName.keys()].filter((n) => slotted.has(n)));
  for (const [name, found] of nested) if ([...found].some(stale)) rebuilt.add(name);
  for (let grew = true; grew;) {
    grew = false;
    for (const [name, found] of nested) {
      if (rebuilt.has(name) || ![...found].some((s) => rebuilt.has(nameOf.get(s)!))) continue;
      rebuilt.add(name);
      grew = true;
    }
  }
  return rebuilt;
}

// Card(body: Stack, tags?: (Text | Image)[]) -> Stack, Text, Image; stops at each component
function nestedComponents(
  schema: unknown,
  nameOf: Map<unknown, string>,
  found: Set<unknown>,
  seen = new Set<unknown>(),
): void {
  if (nameOf.has(schema)) return void found.add(schema);
  const def = getZodDef(schema);
  if (!def || def.type === "lazy" || seen.has(schema)) return;
  seen.add(schema);
  for (const [key, value] of Object.entries(def)) {
    if (key === "checks") continue;
    rebindField(key, value, (child) => nestedComponents(child, nameOf, found, seen));
  }
}

// A def field holds a schema, an array of schemas, a shape of schemas, or plain data
function rebindField(key: string, value: unknown, walk: (s: unknown) => unknown): unknown {
  if (getZodDef(value)) return walk(value);
  if (Array.isArray(value)) return value.map(walk);
  if (key !== "shape") return value;
  const shape: Record<string, unknown> = {};
  for (const [prop, child] of Object.entries(value as object)) shape[prop] = walk(child);
  return shape;
}

// Arrays and shapes are rebuilt on every walk, so compare their entries, not their identity
function sameField(next: unknown, old: any): boolean {
  if (next === old) return true;
  if (getZodDef(next)) return false;
  const entries = Object.entries(next as object);
  return entries.length === Object.keys(old).length && entries.every(([i, c]) => c === old[i]);
}

// Copy a schema with a patched def, keeping its prompt tags and metadata.
function cloneSchema(s: unknown, patch: Record<string, unknown>): unknown {
  const schema = s as z.$ZodType;
  const copy = z.clone(schema, z.util.mergeDefs(schema._zod.def, patch) as any);
  copySchemaTags(schema, copy);
  if (isReactiveSchema(schema)) markReactive(copy);
  const meta = z.globalRegistry.get(schema);
  if (meta) z.globalRegistry.add(copy, meta);
  return copy;
}

// Media: ["Image", "Frame"] with Frame removed -> Media: ["Image"]; a group left empty is dropped
function withoutRemoved(groups: ComponentGroup[] | undefined, removed: Set<string>) {
  return groups
    ?.map((g) => ({ ...g, components: g.components.filter((n) => !removed.has(n)) }))
    .filter((g) => g.components.length);
}