@echovisionlab/geul-common 0.2.4 → 0.3.0

package/src/collaboration/form-schema-delta.ts

@@ -0,0 +1,440 @@
+export type FormSchemaPatchScope = "source" | "target";
+
+export type FormSchemaPatchErrorReason =
+  | "invalid_schema"
+  | "schema_identity_changed"
+  | "target_topology_changed"
+  | "schema_identity_collision"
+  | "schema_add_parent_missing";
+
+export class FormSchemaPatchError extends Error {
+  constructor(readonly reason: FormSchemaPatchErrorReason) {
+    super(`form_schema_patch:${reason}`);
+    this.name = "FormSchemaPatchError";
+  }
+}
+
+type NodeKind = "step" | "field" | "option" | "validator";
+
+interface SchemaNode {
+  kind: NodeKind;
+  id: string;
+  parent: string;
+  order: number;
+  properties: Record<string, unknown>;
+  validationProperties?: Record<string, unknown>;
+  childrenPresent?: boolean;
+  validationPresent?: boolean;
+  validatorsPresent?: boolean;
+}
+
+interface FormSchemaIndex {
+  id: string;
+  properties: Record<string, unknown>;
+  nodes: Map<string, SchemaNode>;
+}
+
+const ROOT_PARENT = "form-root";
+const TARGET_LOCALIZED_PROPERTIES: Readonly<
+  Record<NodeKind, ReadonlySet<string>>
+> = {
+  step: new Set(["title", "description"]),
+  field: new Set(["label", "description", "placeholder", "checkboxLabel"]),
+  option: new Set(["label"]),
+  validator: new Set(["message"]),
+};
+
+function fail(): never {
+  throw new FormSchemaPatchError("invalid_schema");
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function object(value: unknown): Record<string, unknown> {
+  return isObject(value) ? value : fail();
+}
+
+function array(value: unknown): unknown[] {
+  return Array.isArray(value) ? value : fail();
+}
+
+function requiredId(value: Record<string, unknown>): string {
+  return typeof value.id === "string" && value.id.length > 0
+    ? value.id
+    : fail();
+}
+
+function nodeKey(kind: NodeKind, id: string): string {
+  return `${kind}\u0000${id}`;
+}
+
+function cloneJson(value: unknown): unknown {
+  const serialized = JSON.stringify(value);
+  if (serialized === undefined) return fail();
+  return JSON.parse(serialized) as unknown;
+}
+
+function stableJson(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableJson).join(",")}]`;
+  }
+  if (isObject(value)) {
+    return `{${Object.keys(value)
+      .filter((key) => value[key] !== undefined)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function copyProperties(
+  value: Record<string, unknown>,
+  excluded: ReadonlySet<string>,
+): Record<string, unknown> {
+  const properties: Record<string, unknown> = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (excluded.has(key) || entry === undefined) continue;
+    properties[key] = cloneJson(entry);
+  }
+  return properties;
+}
+
+function addNode(index: FormSchemaIndex, node: SchemaNode): void {
+  const key = nodeKey(node.kind, node.id);
+  if ([...index.nodes.values()].some((existing) => existing.id === node.id))
+    fail();
+  index.nodes.set(key, node);
+}
+
+function indexFormSchema(value: unknown): FormSchemaIndex {
+  const schema = object(value);
+  const id = requiredId(schema);
+  if (!Array.isArray(schema.steps)) fail();
+  const index: FormSchemaIndex = {
+    id,
+    properties: copyProperties(schema, new Set(["steps"])),
+    nodes: new Map(),
+  };
+
+  array(schema.steps).forEach((rawStep, stepOrder) => {
+    const step = object(rawStep);
+    const stepId = requiredId(step);
+    addNode(index, {
+      kind: "step",
+      id: stepId,
+      parent: ROOT_PARENT,
+      order: stepOrder,
+      properties: copyProperties(step, new Set(["fields"])),
+      ...(Object.hasOwn(step, "fields") && step.fields !== undefined
+        ? { childrenPresent: true }
+        : {}),
+    });
+
+    if (step.fields !== undefined) {
+      array(step.fields).forEach((rawField, fieldOrder) => {
+        const field = object(rawField);
+        const fieldId = requiredId(field);
+        const validation =
+          field.validation === undefined ? undefined : object(field.validation);
+        const validatorsPresent =
+          validation !== undefined && Object.hasOwn(validation, "validators");
+        const validationProperties = validation
+          ? copyProperties(validation, new Set(["validators"]))
+          : undefined;
+        addNode(index, {
+          kind: "field",
+          id: fieldId,
+          parent: nodeKey("step", stepId),
+          order: fieldOrder,
+          properties: copyProperties(field, new Set(["options", "validation"])),
+          ...(validationProperties ? { validationProperties } : {}),
+          ...(Object.hasOwn(field, "options") && field.options !== undefined
+            ? { childrenPresent: true }
+            : {}),
+          ...(validation !== undefined ? { validationPresent: true } : {}),
+          ...(validatorsPresent ? { validatorsPresent: true } : {}),
+        });
+
+        if (field.options !== undefined) {
+          array(field.options).forEach((rawOption, optionOrder) => {
+            const option = object(rawOption);
+            const optionId = requiredId(option);
+            addNode(index, {
+              kind: "option",
+              id: optionId,
+              parent: nodeKey("field", fieldId),
+              order: optionOrder,
+              properties: copyProperties(option, new Set()),
+            });
+          });
+        }
+
+        if (validatorsPresent) {
+          array(validation!.validators).forEach(
+            (rawValidator, validatorOrder) => {
+              const validator = object(rawValidator);
+              const validatorId = requiredId(validator);
+              addNode(index, {
+                kind: "validator",
+                id: validatorId,
+                parent: nodeKey("field", fieldId),
+                order: validatorOrder,
+                properties: copyProperties(validator, new Set()),
+              });
+            },
+          );
+        }
+      });
+    }
+  });
+  return index;
+}
+
+function targetTopology(index: FormSchemaIndex): unknown {
+  const nodes = [...index.nodes.values()].map((node) => {
+    const properties = { ...node.properties };
+    for (const key of TARGET_LOCALIZED_PROPERTIES[node.kind])
+      delete properties[key];
+    return {
+      kind: node.kind,
+      id: node.id,
+      parent: node.parent,
+      order: node.order,
+      properties,
+      validationProperties: node.validationProperties,
+      childrenPresent: node.childrenPresent,
+      validationPresent: node.validationPresent,
+      validatorsPresent: node.validatorsPresent,
+    };
+  });
+  return { id: index.id, properties: index.properties, nodes };
+}
+
+function sameNode(left: SchemaNode, right: SchemaNode): boolean {
+  return (
+    left.parent === right.parent &&
+    left.order === right.order &&
+    stableJson(left.properties) === stableJson(right.properties) &&
+    stableJson(left.validationProperties) ===
+      stableJson(right.validationProperties) &&
+    left.childrenPresent === right.childrenPresent &&
+    left.validationPresent === right.validationPresent &&
+    left.validatorsPresent === right.validatorsPresent
+  );
+}
+
+function orderedChildren(
+  nodes: Map<string, SchemaNode>,
+  parent: string,
+  kind: NodeKind,
+): SchemaNode[] {
+  return [...nodes.values()]
+    .filter((node) => node.parent === parent && node.kind === kind)
+    .sort(
+      (left, right) =>
+        left.order - right.order || left.id.localeCompare(right.id),
+    );
+}
+
+function materialize(index: FormSchemaIndex): Record<string, unknown> {
+  const buildField = (node: SchemaNode): Record<string, unknown> => {
+    const field: Record<string, unknown> = { ...node.properties, id: node.id };
+    if (node.childrenPresent) {
+      field.options = orderedChildren(
+        index.nodes,
+        nodeKey("field", node.id),
+        "option",
+      ).map((option) => ({ ...option.properties, id: option.id }));
+    }
+    if (node.validationPresent) {
+      const validationProperties = { ...node.validationProperties };
+      if (node.validatorsPresent) {
+        validationProperties.validators = orderedChildren(
+          index.nodes,
+          nodeKey("field", node.id),
+          "validator",
+        ).map((validator) => ({ ...validator.properties, id: validator.id }));
+      }
+      field.validation = validationProperties;
+    }
+    return field;
+  };
+  const buildStep = (node: SchemaNode): Record<string, unknown> => {
+    const step: Record<string, unknown> = { ...node.properties, id: node.id };
+    if (node.childrenPresent) {
+      step.fields = orderedChildren(
+        index.nodes,
+        nodeKey("step", node.id),
+        "field",
+      ).map(buildField);
+    }
+    return step;
+  };
+
+  // The index is parent-first and only receives validated additions and moves.
+  const result: Record<string, unknown> = { ...index.properties, id: index.id };
+  result.steps = orderedChildren(index.nodes, ROOT_PARENT, "step").map(
+    buildStep,
+  );
+  return result;
+}
+
+/**
+ * Applies only the stable-ID property and structural changes between previous
+ * and next to the latest server schema. Missing live IDs are never restored
+ * by unchanged stale snapshot data. An explicit source parent deletion
+ * cascades over its current descendants; target edits are restricted to
+ * catalogued localized properties and cannot change topology.
+ */
+export function applyFormSchemaPatch(
+  currentSchema: unknown,
+  previousSchema: unknown,
+  nextSchema: unknown,
+  scope: FormSchemaPatchScope,
+): unknown {
+  const current = indexFormSchema(currentSchema);
+  const previous = indexFormSchema(previousSchema);
+  const next = indexFormSchema(nextSchema);
+  if (current.id !== previous.id || previous.id !== next.id) {
+    throw new FormSchemaPatchError("schema_identity_changed");
+  }
+  if (
+    scope === "target" &&
+    stableJson(targetTopology(previous)) !== stableJson(targetTopology(next))
+  ) {
+    throw new FormSchemaPatchError("target_topology_changed");
+  }
+
+  const result: FormSchemaIndex = {
+    id: current.id,
+    properties: { ...current.properties },
+    nodes: new Map(
+      [...current.nodes].map(([key, node]) => [key, structuredClone(node)]),
+    ),
+  };
+
+  for (const key of new Set([
+    ...Object.keys(previous.properties),
+    ...Object.keys(next.properties),
+  ])) {
+    if (key === "id") continue;
+    const beforeHas = Object.hasOwn(previous.properties, key);
+    const afterHas = Object.hasOwn(next.properties, key);
+    if (
+      beforeHas === afterHas &&
+      stableJson(previous.properties[key]) === stableJson(next.properties[key])
+    ) {
+      continue;
+    }
+    if (afterHas)
+      result.properties[key] = structuredClone(next.properties[key]);
+    else delete result.properties[key];
+  }
+
+  const added = new Set<string>();
+  for (const [key, node] of next.nodes) {
+    if (previous.nodes.has(key)) continue;
+    if (result.nodes.has(key)) {
+      const live = result.nodes.get(key)!;
+      if (!sameNode(live, node)) {
+        throw new FormSchemaPatchError("schema_identity_collision");
+      }
+      continue;
+    }
+    if (node.parent !== ROOT_PARENT && !result.nodes.has(node.parent)) {
+      throw new FormSchemaPatchError("schema_add_parent_missing");
+    }
+    result.nodes.set(key, structuredClone(node));
+    added.add(key);
+  }
+
+  for (const [key, after] of next.nodes) {
+    const before = previous.nodes.get(key);
+    if (!before || added.has(key)) continue;
+    const live = result.nodes.get(key);
+    if (!live) continue;
+
+    for (const property of new Set([
+      ...Object.keys(before.properties),
+      ...Object.keys(after.properties),
+    ])) {
+      const beforeHas = Object.hasOwn(before.properties, property);
+      const afterHas = Object.hasOwn(after.properties, property);
+      if (
+        beforeHas === afterHas &&
+        stableJson(before.properties[property]) ===
+          stableJson(after.properties[property])
+      ) {
+        continue;
+      }
+      if (afterHas)
+        live.properties[property] = structuredClone(after.properties[property]);
+      else delete live.properties[property];
+    }
+
+    const beforeValidation = before.validationProperties ?? {};
+    const afterValidation = after.validationProperties ?? {};
+    for (const property of new Set([
+      ...Object.keys(beforeValidation),
+      ...Object.keys(afterValidation),
+    ])) {
+      const beforeHas = Object.hasOwn(beforeValidation, property);
+      const afterHas = Object.hasOwn(afterValidation, property);
+      if (
+        beforeHas === afterHas &&
+        stableJson(beforeValidation[property]) ===
+          stableJson(afterValidation[property])
+      ) {
+        continue;
+      }
+      const updated = { ...(live.validationProperties ?? {}) };
+      if (afterHas)
+        updated[property] = structuredClone(afterValidation[property]);
+      else delete updated[property];
+      live.validationProperties = updated;
+    }
+
+    if (
+      before.parent !== after.parent &&
+      (after.parent === ROOT_PARENT || result.nodes.has(after.parent))
+    ) {
+      live.parent = after.parent;
+      live.order = after.order;
+    } else if (
+      before.parent === after.parent &&
+      before.order !== after.order &&
+      live.parent === before.parent
+    ) {
+      live.order = after.order;
+    }
+    if (before.childrenPresent !== after.childrenPresent) {
+      live.childrenPresent = after.childrenPresent;
+    }
+    if (before.validationPresent !== after.validationPresent) {
+      live.validationPresent = after.validationPresent;
+    }
+    if (before.validatorsPresent !== after.validatorsPresent) {
+      live.validatorsPresent = after.validatorsPresent;
+    }
+  }
+
+  const deleted = new Set(
+    [...previous.nodes.keys()].filter((key) => !next.nodes.has(key)),
+  );
+  let addedDescendant = true;
+  while (addedDescendant) {
+    addedDescendant = false;
+    for (const [key, node] of result.nodes) {
+      if (deleted.has(node.parent) && !deleted.has(key)) {
+        deleted.add(key);
+        addedDescendant = true;
+      }
+    }
+  }
+  for (const key of deleted) result.nodes.delete(key);
+
+  return materialize(result);
+}

package/src/collaboration/menu.ts

@@ -42,6 +42,11 @@ export interface MenuCanonicalSnapshot {
   requestedLabels: Record<string, string>;
 }
 
+export interface MenuCanonicalSourceSnapshot {
+  name: string;
+  items: readonly MenuCollaborationItem[];
+}
+
 export function hydrateMenuCanonicalRoom(input: MenuCanonicalRoomInput): Y.Doc {
   const document = new Y.Doc();
   document.transact(() => {
@@ -50,7 +55,7 @@ export function hydrateMenuCanonicalRoom(input: MenuCanonicalRoomInput): Y.Doc {
     context.set("locale", input.locale);
     context.set("localeExists", input.localeExists);
     document.getMap<string>(MENU_ROOT_MAP_NAME).set("name", input.name);
-    replaceMenuStructure(document, input.items);
+    replaceMenuStructure(document, [], input.items);
     const sourceLabels = document.getMap<string>(MENU_SOURCE_LABELS_MAP_NAME);
     const requestedLabels = menuLocaleLabelsMap(document);
     for (const [id, label] of Object.entries(input.sourceLabels))
@@ -125,27 +130,64 @@ export function replaceMenuCanonicalSource(
   document: Y.Doc,
   name: string,
   items: readonly MenuCollaborationItem[],
+  previous: MenuCanonicalSourceSnapshot,
 ): void {
-  document.getMap<string>(MENU_ROOT_MAP_NAME).set("name", name);
-  replaceMenuStructure(document, items);
+  assertMenuCanonicalSourceSnapshot(previous);
+  const root = document.getMap<string>(MENU_ROOT_MAP_NAME);
+  if (previous.name !== name) root.set("name", name);
+  const deletedItemIds = replaceMenuStructure(document, previous.items, items);
   const labels = menuLocaleLabelsMap(document);
+  const sourceLabels = document.getMap<string>(MENU_SOURCE_LABELS_MAP_NAME);
   const locale = document
     .getMap<string | boolean>(MENU_CONTEXT_MAP_NAME)
     .get("locale");
   if (typeof locale !== "string") {
     throw new Error("Menu collaboration locale is required");
   }
-  const ids = new Set(flattenMenuItems(items).map(({ item }) => item.id));
-  for (const id of [...labels.keys()]) if (!ids.has(id)) labels.delete(id);
-  for (const { item } of flattenMenuItems(items)) {
-    if (!menuItemOwnsLocaleLabel(item, locale)) {
-      labels.delete(item.id);
-    } else if (item.label !== undefined) {
-      labels.set(item.id, item.label);
+  const previousById = new Map(
+    flattenMenuItems(previous.items).map((entry) => [
+      entry.item.id,
+      entry.item,
+    ]),
+  );
+  const nextById = new Map(
+    flattenMenuItems(items).map((entry) => [entry.item.id, entry.item]),
+  );
+  for (const id of deletedItemIds) {
+    labels.delete(id);
+    sourceLabels.delete(id);
+  }
+  for (const [id, item] of nextById) {
+    const before = previousById.get(id);
+    const previouslyOwned = before
+      ? menuItemOwnsLocaleLabel(before, locale)
+      : false;
+    const currentlyOwned = menuItemOwnsLocaleLabel(item, locale);
+    if (!currentlyOwned) {
+      if (previouslyOwned) labels.delete(id);
+    } else if (!before || !previouslyOwned || before.label !== item.label) {
+      if (item.label !== undefined) labels.set(id, item.label);
     }
   }
 }
 
+function assertMenuCanonicalSourceSnapshot(
+  value: unknown,
+): asserts value is MenuCanonicalSourceSnapshot {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    !("name" in value) ||
+    typeof value.name !== "string" ||
+    !("items" in value) ||
+    !Array.isArray(value.items)
+  ) {
+    throw new Error(
+      "Menu source replacement requires an observed previous snapshot",
+    );
+  }
+}
+
 export function setMenuLocaleLabel(
   document: Y.Doc,
   itemId: string,
@@ -180,29 +222,77 @@ export function extractMenuCanonicalSnapshot(
 
 function replaceMenuStructure(
   document: Y.Doc,
+  previousItems: readonly MenuCollaborationItem[],
   nextItems: readonly MenuCollaborationItem[],
-): void {
+): Set<string> {
+  const previous = flattenMenuItems(previousItems);
   const flattened = flattenMenuItems(nextItems);
+  const previousById = new Map(previous.map((entry) => [entry.item.id, entry]));
   const nextIDs = new Set(flattened.map(({ item }) => item.id));
   if (nextIDs.size !== flattened.length || nextIDs.has(MENU_ROOT_PARENT)) {
     throw new Error("Invalid Menu collaboration item identity");
   }
+  const previousIDs = new Set(previous.map(({ item }) => item.id));
+  if (
+    previousIDs.size !== previous.length ||
+    previousIDs.has(MENU_ROOT_PARENT)
+  ) {
+    throw new Error("Invalid Menu collaboration item identity");
+  }
   const items = document.getMap<string>(MENU_ITEMS_MAP_NAME);
   const parents = document.getMap<string>(MENU_PARENTS_MAP_NAME);
   const orders = document.getMap<number>(MENU_ORDERS_MAP_NAME);
-  for (const id of [...items.keys()]) {
-    if (!nextIDs.has(id)) {
-      items.delete(id);
-      parents.delete(id);
-      orders.delete(id);
+  const childrenByParent = new Map<string, string[]>();
+  for (const id of items.keys()) {
+    const parent = parents.get(id) ?? MENU_ROOT_PARENT;
+    const children = childrenByParent.get(parent) ?? [];
+    children.push(id);
+    childrenByParent.set(parent, children);
+  }
+
+  const deletedIDs = new Set([...previousIDs].filter((id) => !nextIDs.has(id)));
+  const pendingDeletedIDs = [...deletedIDs];
+  for (let index = 0; index < pendingDeletedIDs.length; index += 1) {
+    const deletedParent = pendingDeletedIDs[index]!;
+    for (const childId of childrenByParent.get(deletedParent) ?? []) {
+      if (nextIDs.has(childId) || deletedIDs.has(childId)) continue;
+      deletedIDs.add(childId);
+      pendingDeletedIDs.push(childId);
     }
   }
+  for (const id of deletedIDs) {
+    items.delete(id);
+    parents.delete(id);
+    orders.delete(id);
+  }
   for (const { item, parent, order } of flattened) {
+    const before = previousById.get(item.id);
     const stored = menuItemStructure(item);
-    items.set(item.id, JSON.stringify(stored));
-    parents.set(item.id, parent);
-    orders.set(item.id, order);
+    if (
+      !before ||
+      stableMenuJson(menuItemStructure(before.item)) !== stableMenuJson(stored)
+    ) {
+      items.set(item.id, JSON.stringify(stored));
+    }
+    if (!before || before.parent !== parent) parents.set(item.id, parent);
+    if (!before || before.order !== order) orders.set(item.id, order);
+  }
+  return deletedIDs;
+}
+
+function stableMenuJson(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map(stableMenuJson).join(",")}]`;
+  }
+  if (typeof value === "object" && value !== null) {
+    const record = value as Record<string, unknown>;
+    return `{${Object.keys(record)
+      .filter((key) => record[key] !== undefined)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${stableMenuJson(record[key])}`)
+      .join(",")}}`;
   }
+  return JSON.stringify(value);
 }
 
 function flattenMenuItems(items: readonly MenuCollaborationItem[]): Array<{

package/src/index.ts

@@ -4,6 +4,7 @@ export * from "./collaboration/block-room-codec.ts";
 export * from "./collaboration/document-layout.ts";
 export * from "./collaboration/document.ts";
 export * from "./collaboration/form.ts";
+export * from "./collaboration/form-schema-delta.ts";
 export * from "./collaboration/label.ts";
 export * from "./collaboration/map-theme.ts";
 export * from "./collaboration/metadata-ai.ts";