@open-mercato/core 0.8.1-develop.7296.1.2111d779db → 0.8.1-develop.7441.1.b42958b98c

package/dist/modules/forms/backend/forms/[id]/studio/schema-helpers.js

@@ -0,0 +1,1693 @@
+import {
+  OM_FIELD_KEYWORDS,
+  OM_FIELD_VALIDATORS,
+  OM_ROOT_KEYWORDS,
+  OM_ROOT_VALIDATORS,
+  validateOmCrossKeyword
+} from "../../../../schema/jsonschema-extensions.js";
+const UNGROUPED_SECTION_KEY = "__ungrouped__";
+class SchemaHelperError extends Error {
+  constructor(message, code, path = []) {
+    super(message);
+    this.name = "SchemaHelperError";
+    this.code = code;
+    this.path = path;
+  }
+}
+const FIELD_TYPE_TO_JSON_TYPE = {
+  text: "string",
+  textarea: "string",
+  number: "number",
+  integer: "integer",
+  boolean: "boolean",
+  yes_no: "boolean",
+  yes_no_buttons: "boolean",
+  date: "string",
+  datetime: "string",
+  select_one: "string",
+  select_many: "array",
+  scale: "integer",
+  info_block: "string",
+  // Tier-2 — Phase B (`.ai/specs/2026-05-14-forms-tier-2-question-palette.md`).
+  email: "string",
+  phone: "string",
+  website: "string",
+  // Tier-2 — Phase C: address is a composite object with required sub-fields.
+  address: "object",
+  // Tier-2 — Phase D: NPS + opinion_scale are integers (range constraints
+  // live in `x-om-min/x-om-max` for opinion_scale; nps has fixed 0..10).
+  nps: "integer",
+  opinion_scale: "integer",
+  // Tier-2 — Phase E: ranking persists as an array of option-value strings in
+  // user-chosen order.
+  ranking: "array",
+  // Tier-2 — Phase F: matrix persists as a Record<rowKey, string | string[]>.
+  matrix: "object",
+  // W4 — file persists as an array of attachment-reference objects.
+  file: "array",
+  // W6 — group (repeatable) persists as an array of objects (one per entry).
+  group: "array"
+};
+const FIELD_TYPE_NODE_INITIALIZER = {
+  select_one: (node) => {
+    node["x-om-options"] = [];
+    return node;
+  },
+  select_many: (node) => {
+    node.items = { type: "string" };
+    node["x-om-options"] = [];
+    return node;
+  },
+  address: (node) => {
+    node.properties = {
+      street1: { type: "string" },
+      street2: { type: "string" },
+      city: { type: "string" },
+      region: { type: "string" },
+      postalCode: { type: "string" },
+      country: { type: "string" }
+    };
+    node.required = ["street1", "city", "country"];
+    node.additionalProperties = false;
+    return node;
+  },
+  // Tier-2 Phase E — ranking persists as `string[]` (an ordered list of option
+  // values). The JSON Schema `items` constraint pins each entry's type so AJV
+  // rejects non-string entries; the `x-om-options` map seeds the empty array
+  // so authors immediately see the option editor.
+  ranking: (node) => {
+    node.items = { type: "string" };
+    node["x-om-options"] = [];
+    return node;
+  },
+  // Tier-2 Phase F — matrix seeds empty rows / columns + locks unknown sub-keys.
+  matrix: (node) => {
+    node.additionalProperties = false;
+    node["x-om-matrix-rows"] = [];
+    node["x-om-matrix-columns"] = [];
+    return node;
+  },
+  // W4 — file persists an array of attachment-reference objects; `items`
+  // pins each entry to an object so AJV rejects scalars in the array.
+  file: (node) => {
+    node.items = { type: "object" };
+    node["x-om-accept"] = [];
+    node["x-om-multiple"] = false;
+    return node;
+  },
+  // W2 — signature persists an object value (mode + image/typedName +
+  // affirmed + signedAt + clauseSha256). Seed an empty consent clause map so
+  // the author immediately sees the clause editor.
+  signature: (node) => {
+    node.additionalProperties = false;
+    node["x-om-consent-clause"] = {};
+    return node;
+  },
+  // W6 — group (repeatable) persists as an array of objects. Seed `items`
+  // with a JSON-Schema object fragment carrying one starter sub-field so the
+  // author immediately sees the sub-field editor. Native `items.properties` /
+  // `required` / `additionalProperties:false` let AJV enforce the sub-field
+  // shape server-side (the submission service validates via `compiled.ajv`).
+  group: (node) => {
+    node.items = {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        field_1: {
+          type: "string",
+          "x-om-type": "text",
+          "x-om-label": { en: "New sub-field" }
+        }
+      },
+      required: []
+    };
+    return node;
+  }
+};
+const FIELD_KEY_PATTERN = /^field_(\d+)$/;
+function deepClone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function nextFieldKey(properties) {
+  let maxSuffix = 0;
+  for (const key of Object.keys(properties)) {
+    const match = FIELD_KEY_PATTERN.exec(key);
+    if (!match) continue;
+    const value = Number.parseInt(match[1], 10);
+    if (Number.isFinite(value) && value > maxSuffix) maxSuffix = value;
+  }
+  return `field_${maxSuffix + 1}`;
+}
+function nextSectionKey(sections) {
+  let maxSuffix = 0;
+  const pattern = /^section_(\d+)$/;
+  for (const section of sections ?? []) {
+    const match = pattern.exec(section.key);
+    if (!match) continue;
+    const value = Number.parseInt(match[1], 10);
+    if (Number.isFinite(value) && value > maxSuffix) maxSuffix = value;
+  }
+  return `section_${maxSuffix + 1}`;
+}
+function validateSchemaExtensions(schema) {
+  for (const [keyword, validator] of Object.entries(OM_ROOT_VALIDATORS)) {
+    const rootKeyword = keyword;
+    const value = schema[rootKeyword];
+    if (value === void 0) continue;
+    const violation = validator(value);
+    if (violation) throw new SchemaHelperError(violation, "invalid_root", [rootKeyword]);
+  }
+  for (const [fieldKey, fieldNode] of Object.entries(schema.properties)) {
+    if (!fieldNode || typeof fieldNode !== "object") {
+      throw new SchemaHelperError("Field nodes must be objects.", "invalid_field", [fieldKey]);
+    }
+    for (const [keyword, validator] of Object.entries(OM_FIELD_VALIDATORS)) {
+      const fieldKeyword = keyword;
+      const value = fieldNode[fieldKeyword];
+      if (value === void 0) continue;
+      const violation = validator(value);
+      if (violation) {
+        throw new SchemaHelperError(violation, "invalid_field", [fieldKey, fieldKeyword]);
+      }
+    }
+  }
+  const crossKeywordViolation = validateOmCrossKeyword(schema);
+  if (crossKeywordViolation) {
+    throw new SchemaHelperError(crossKeywordViolation, "invalid_cross_keyword", []);
+  }
+}
+function rebuildPropertiesByOrder(schema, orderedKeys) {
+  const next = deepClone(schema);
+  const sourceProperties = next.properties;
+  const seen = /* @__PURE__ */ new Set();
+  const rebuilt = {};
+  for (const key of orderedKeys) {
+    if (seen.has(key)) continue;
+    seen.add(key);
+    const node = sourceProperties[key];
+    if (!node) continue;
+    rebuilt[key] = node;
+  }
+  for (const [key, node] of Object.entries(sourceProperties)) {
+    if (seen.has(key)) continue;
+    rebuilt[key] = node;
+  }
+  next.properties = rebuilt;
+  return next;
+}
+function findSectionOwning(schema, fieldKey) {
+  const sections = schema[OM_ROOT_KEYWORDS.sections] ?? [];
+  for (const section of sections) {
+    if (section.fieldKeys.includes(fieldKey)) return section;
+  }
+  return null;
+}
+function indexOfFieldInSection(schema, sectionKey, fieldKey) {
+  const sections = schema[OM_ROOT_KEYWORDS.sections] ?? [];
+  const section = sections.find((entry) => entry.key === sectionKey);
+  if (!section) return -1;
+  return section.fieldKeys.indexOf(fieldKey);
+}
+function linearizeFields(schema) {
+  const linear = [];
+  const sections = schema[OM_ROOT_KEYWORDS.sections] ?? [];
+  const claimed = /* @__PURE__ */ new Set();
+  for (const section of sections) {
+    for (const fieldKey of section.fieldKeys) {
+      if (claimed.has(fieldKey)) continue;
+      claimed.add(fieldKey);
+      linear.push({ key: fieldKey, sectionKey: section.key });
+    }
+  }
+  for (const fieldKey of Object.keys(schema.properties)) {
+    if (claimed.has(fieldKey)) continue;
+    linear.push({ key: fieldKey, sectionKey: null });
+  }
+  return linear;
+}
+function addFieldFromPalette(input) {
+  const { schema, typeKey, target } = input;
+  if (!typeKey) {
+    throw new SchemaHelperError("typeKey is required.", "invalid_input", ["typeKey"]);
+  }
+  const next = deepClone(schema);
+  const sections = next[OM_ROOT_KEYWORDS.sections] ?? [];
+  const section = sections.find((entry) => entry.key === target.sectionKey);
+  if (!section) {
+    throw new SchemaHelperError(
+      `Section "${target.sectionKey}" not found.`,
+      "unknown_section",
+      [target.sectionKey]
+    );
+  }
+  const newKey = nextFieldKey(next.properties);
+  const jsonType = FIELD_TYPE_TO_JSON_TYPE[typeKey] ?? "string";
+  const defaultActorRole = next[OM_ROOT_KEYWORDS.defaultActorRole] ?? "admin";
+  const fieldNode = {
+    type: jsonType,
+    "x-om-type": typeKey,
+    "x-om-label": { en: "New field" },
+    "x-om-editable-by": dedupePreservingOrder([defaultActorRole, "admin"])
+  };
+  const initializer = FIELD_TYPE_NODE_INITIALIZER[typeKey];
+  if (initializer) initializer(fieldNode);
+  next.properties[newKey] = fieldNode;
+  next.required = next.required ?? [];
+  const insertionIndex = typeof target.index === "number" && target.index >= 0 && target.index <= section.fieldKeys.length ? target.index : section.fieldKeys.length;
+  section.fieldKeys = [
+    ...section.fieldKeys.slice(0, insertionIndex),
+    newKey,
+    ...section.fieldKeys.slice(insertionIndex)
+  ];
+  const orderedKeys = collectCanonicalOrder(next);
+  const result = rebuildPropertiesByOrder(next, orderedKeys);
+  validateSchemaExtensions(result);
+  return { schema: result, fieldKey: newKey };
+}
+function moveField(input) {
+  const { schema, fieldKey, target } = input;
+  if (!schema.properties[fieldKey]) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  const next = deepClone(schema);
+  const sections = next[OM_ROOT_KEYWORDS.sections] ?? [];
+  const targetSection = sections.find((entry) => entry.key === target.sectionKey);
+  if (!targetSection) {
+    throw new SchemaHelperError(
+      `Section "${target.sectionKey}" not found.`,
+      "unknown_section",
+      [target.sectionKey]
+    );
+  }
+  for (const section of sections) {
+    section.fieldKeys = section.fieldKeys.filter((entry) => entry !== fieldKey);
+  }
+  const insertionIndex = typeof target.index === "number" && target.index >= 0 && target.index <= targetSection.fieldKeys.length ? target.index : targetSection.fieldKeys.length;
+  targetSection.fieldKeys = [
+    ...targetSection.fieldKeys.slice(0, insertionIndex),
+    fieldKey,
+    ...targetSection.fieldKeys.slice(insertionIndex)
+  ];
+  const orderedKeys = collectCanonicalOrder(next);
+  const result = rebuildPropertiesByOrder(next, orderedKeys);
+  validateSchemaExtensions(result);
+  return result;
+}
+function deleteField(input) {
+  const { schema, fieldKey } = input;
+  if (!schema.properties[fieldKey]) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  const next = deepClone(schema);
+  delete next.properties[fieldKey];
+  next.required = (next.required ?? []).filter((entry) => entry !== fieldKey);
+  const sections = next[OM_ROOT_KEYWORDS.sections] ?? [];
+  for (const section of sections) {
+    section.fieldKeys = section.fieldKeys.filter((entry) => entry !== fieldKey);
+  }
+  const orderedKeys = collectCanonicalOrder(next);
+  const result = rebuildPropertiesByOrder(next, orderedKeys);
+  validateSchemaExtensions(result);
+  return result;
+}
+function addLayoutFromPalette(input) {
+  const { schema, kind } = input;
+  if (kind !== "page" && kind !== "section" && kind !== "ending") {
+    throw new SchemaHelperError(
+      `Unknown layout kind "${String(kind)}" \u2014 expected "page", "section", or "ending".`,
+      "invalid_layout_kind",
+      ["kind"]
+    );
+  }
+  const next = deepClone(schema);
+  const sections = next[OM_ROOT_KEYWORDS.sections] ?? [];
+  const newKey = nextSectionKey(sections);
+  const newSection = {
+    key: newKey,
+    kind,
+    title: {
+      en: kind === "page" ? "New page" : kind === "ending" ? "New ending" : "New section"
+    },
+    fieldKeys: []
+  };
+  const desiredIndex = input.target?.index;
+  const insertionIndex = typeof desiredIndex === "number" && desiredIndex >= 0 && desiredIndex <= sections.length ? desiredIndex : sections.length;
+  const inserted = [
+    ...sections.slice(0, insertionIndex),
+    newSection,
+    ...sections.slice(insertionIndex)
+  ];
+  next[OM_ROOT_KEYWORDS.sections] = inserted;
+  validateSchemaExtensions(next);
+  return { schema: next, sectionKey: newKey };
+}
+function moveSection(input) {
+  const { schema, sectionKey, beforeKey } = input;
+  const next = deepClone(schema);
+  const sections = next[OM_ROOT_KEYWORDS.sections] ?? [];
+  const sourceIndex = sections.findIndex((entry) => entry.key === sectionKey);
+  if (sourceIndex < 0) {
+    throw new SchemaHelperError(
+      `Section "${sectionKey}" not found.`,
+      "unknown_section",
+      [sectionKey]
+    );
+  }
+  const [moved] = sections.splice(sourceIndex, 1);
+  let targetIndex = sections.length;
+  if (beforeKey !== null) {
+    const candidate = sections.findIndex((entry) => entry.key === beforeKey);
+    if (candidate >= 0) targetIndex = candidate;
+  }
+  sections.splice(targetIndex, 0, moved);
+  next[OM_ROOT_KEYWORDS.sections] = sections;
+  validateSchemaExtensions(next);
+  return next;
+}
+function deleteSection(input) {
+  const { schema, sectionKey } = input;
+  const next = deepClone(schema);
+  const sections = next[OM_ROOT_KEYWORDS.sections] ?? [];
+  const target = sections.find((entry) => entry.key === sectionKey);
+  if (!target) {
+    throw new SchemaHelperError(
+      `Section "${sectionKey}" not found.`,
+      "unknown_section",
+      [sectionKey]
+    );
+  }
+  const fieldsToRemove = new Set(target.fieldKeys);
+  next[OM_ROOT_KEYWORDS.sections] = sections.filter((entry) => entry.key !== sectionKey);
+  for (const fieldKey of fieldsToRemove) {
+    delete next.properties[fieldKey];
+  }
+  next.required = (next.required ?? []).filter((entry) => !fieldsToRemove.has(entry));
+  validateSchemaExtensions(next);
+  return next;
+}
+function setSectionColumns(input) {
+  const { schema, sectionKey, columns } = input;
+  const next = deepClone(schema);
+  const sections = next[OM_ROOT_KEYWORDS.sections] ?? [];
+  const section = sections.find((entry) => entry.key === sectionKey);
+  if (!section) {
+    throw new SchemaHelperError(
+      `Section "${sectionKey}" not found.`,
+      "unknown_section",
+      [sectionKey]
+    );
+  }
+  if (columns === 1) {
+    delete section.columns;
+  } else {
+    section.columns = columns;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setSectionTitle(input) {
+  const { schema, sectionKey, locale, title } = input;
+  if (!locale) {
+    throw new SchemaHelperError("locale is required.", "invalid_input", ["locale"]);
+  }
+  const next = deepClone(schema);
+  const sections = next[OM_ROOT_KEYWORDS.sections] ?? [];
+  const section = sections.find((entry) => entry.key === sectionKey);
+  if (!section) {
+    throw new SchemaHelperError(
+      `Section "${sectionKey}" not found.`,
+      "unknown_section",
+      [sectionKey]
+    );
+  }
+  const titleMap = section.title ? { ...section.title } : {};
+  if (title.length === 0) {
+    delete titleMap[locale];
+  } else {
+    titleMap[locale] = title;
+  }
+  section.title = titleMap;
+  validateSchemaExtensions(next);
+  return next;
+}
+function setSectionKind(input) {
+  const { schema, sectionKey, kind } = input;
+  const next = deepClone(schema);
+  const sections = next[OM_ROOT_KEYWORDS.sections] ?? [];
+  const section = sections.find((entry) => entry.key === sectionKey);
+  if (!section) {
+    throw new SchemaHelperError(
+      `Section "${sectionKey}" not found.`,
+      "unknown_section",
+      [sectionKey]
+    );
+  }
+  if (kind === "section") {
+    delete section.kind;
+  } else {
+    section.kind = kind;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setSectionGap(input) {
+  const { schema, sectionKey, gap } = input;
+  const next = deepClone(schema);
+  const sections = next[OM_ROOT_KEYWORDS.sections] ?? [];
+  const section = sections.find((entry) => entry.key === sectionKey);
+  if (!section) {
+    throw new SchemaHelperError(
+      `Section "${sectionKey}" not found.`,
+      "unknown_section",
+      [sectionKey]
+    );
+  }
+  if (gap === "md") {
+    delete section.gap;
+  } else {
+    section.gap = gap;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setSectionDivider(input) {
+  const { schema, sectionKey, divider } = input;
+  const next = deepClone(schema);
+  const sections = next[OM_ROOT_KEYWORDS.sections] ?? [];
+  const section = sections.find((entry) => entry.key === sectionKey);
+  if (!section) {
+    throw new SchemaHelperError(
+      `Section "${sectionKey}" not found.`,
+      "unknown_section",
+      [sectionKey]
+    );
+  }
+  if (divider === false) {
+    delete section.divider;
+  } else {
+    section.divider = true;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setSectionHideTitle(input) {
+  const { schema, sectionKey, hideTitle } = input;
+  const next = deepClone(schema);
+  const sections = next[OM_ROOT_KEYWORDS.sections] ?? [];
+  const section = sections.find((entry) => entry.key === sectionKey);
+  if (!section) {
+    throw new SchemaHelperError(
+      `Section "${sectionKey}" not found.`,
+      "unknown_section",
+      [sectionKey]
+    );
+  }
+  if (hideTitle === false) {
+    delete section.hideTitle;
+  } else {
+    section.hideTitle = true;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setFieldGridSpan(input) {
+  const { schema, fieldKey, span } = input;
+  const next = deepClone(schema);
+  const node = next.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  if (span === 1) {
+    delete node["x-om-grid-span"];
+  } else {
+    node["x-om-grid-span"] = span;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setFieldAlign(input) {
+  const { schema, fieldKey, align } = input;
+  const next = deepClone(schema);
+  const node = next.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  if (align === "start") {
+    delete node[OM_FIELD_KEYWORDS.align];
+  } else {
+    node[OM_FIELD_KEYWORDS.align] = align;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setJumps(input) {
+  const { schema, rules } = input;
+  const next = deepClone(schema);
+  if (!rules || rules.length === 0) {
+    delete next[OM_ROOT_KEYWORDS.jumps];
+  } else {
+    ;
+    next[OM_ROOT_KEYWORDS.jumps] = rules.map((rule) => {
+      const result = {
+        from: rule.from,
+        rules: rule.rules
+      };
+      if (rule.otherwise) result.otherwise = rule.otherwise;
+      return result;
+    });
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setVariables(input) {
+  const { schema, entries } = input;
+  const next = deepClone(schema);
+  if (!entries || entries.length === 0) {
+    delete next[OM_ROOT_KEYWORDS.variables];
+  } else {
+    const cleaned = entries.map((entry) => {
+      const result = {
+        name: entry.name,
+        type: entry.type,
+        formula: entry.formula
+      };
+      if (entry.default !== void 0) result.default = entry.default;
+      return result;
+    });
+    next[OM_ROOT_KEYWORDS.variables] = cleaned;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setHiddenFields(input) {
+  const { schema, entries } = input;
+  const next = deepClone(schema);
+  if (!entries || entries.length === 0) {
+    delete next[OM_ROOT_KEYWORDS.hiddenFields];
+  } else {
+    const cleaned = entries.map((entry) => {
+      const result = { name: entry.name };
+      if (entry.defaultValue !== void 0 && entry.defaultValue.length > 0) {
+        result.defaultValue = entry.defaultValue;
+      }
+      return result;
+    });
+    next[OM_ROOT_KEYWORDS.hiddenFields] = cleaned;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setRedirectUrl(input) {
+  const { schema, sectionKey, url } = input;
+  const next = deepClone(schema);
+  const sections = next[OM_ROOT_KEYWORDS.sections] ?? [];
+  const section = sections.find((entry) => entry.key === sectionKey);
+  if (!section) {
+    throw new SchemaHelperError(
+      `Section "${sectionKey}" not found.`,
+      "unknown_section",
+      [sectionKey]
+    );
+  }
+  if (section.kind !== "ending") {
+    throw new SchemaHelperError(
+      `Section "${sectionKey}" is not an ending \u2014 redirect URL is only valid on ending sections.`,
+      "invalid_redirect_target",
+      [sectionKey]
+    );
+  }
+  const trimmed = typeof url === "string" ? url.trim() : "";
+  if (!trimmed) {
+    delete section["x-om-redirect-url"];
+  } else {
+    ;
+    section["x-om-redirect-url"] = trimmed;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setFieldVisibilityIf(input) {
+  const { schema, fieldKey, predicate } = input;
+  const next = deepClone(schema);
+  const node = next.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  if (predicate === null || predicate === void 0) {
+    delete node[OM_FIELD_KEYWORDS.visibilityIf];
+  } else {
+    node[OM_FIELD_KEYWORDS.visibilityIf] = predicate;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setSectionVisibilityIf(input) {
+  const { schema, sectionKey, predicate } = input;
+  const next = deepClone(schema);
+  const sections = next[OM_ROOT_KEYWORDS.sections] ?? [];
+  const section = sections.find((entry) => entry.key === sectionKey);
+  if (!section) {
+    throw new SchemaHelperError(
+      `Section "${sectionKey}" not found.`,
+      "unknown_section",
+      [sectionKey]
+    );
+  }
+  if (predicate === null || predicate === void 0) {
+    delete section["x-om-visibility-if"];
+  } else {
+    ;
+    section["x-om-visibility-if"] = predicate;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setFieldPattern(input) {
+  const { schema, fieldKey, pattern } = input;
+  const next = deepClone(schema);
+  const node = next.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  if (pattern === null || pattern.length === 0) {
+    delete node[OM_FIELD_KEYWORDS.pattern];
+  } else {
+    node[OM_FIELD_KEYWORDS.pattern] = pattern;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setFieldLengthRange(input) {
+  const { schema, fieldKey, min, max } = input;
+  const next = deepClone(schema);
+  const node = next.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  if (min !== void 0) {
+    if (min === null) delete node[OM_FIELD_KEYWORDS.minLength];
+    else node[OM_FIELD_KEYWORDS.minLength] = min;
+  }
+  if (max !== void 0) {
+    if (max === null) delete node[OM_FIELD_KEYWORDS.maxLength];
+    else node[OM_FIELD_KEYWORDS.maxLength] = max;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setFieldNumberRange(input) {
+  const { schema, fieldKey, min, max } = input;
+  const next = deepClone(schema);
+  const node = next.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  if (min !== void 0) {
+    if (min === null) delete node[OM_FIELD_KEYWORDS.min];
+    else node[OM_FIELD_KEYWORDS.min] = min;
+  }
+  if (max !== void 0) {
+    if (max === null) delete node[OM_FIELD_KEYWORDS.max];
+    else node[OM_FIELD_KEYWORDS.max] = max;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setFieldValidationMessages(input) {
+  const { schema, fieldKey, locale, rule, message } = input;
+  if (!locale) {
+    throw new SchemaHelperError("locale is required.", "invalid_input", ["locale"]);
+  }
+  if (!rule) {
+    throw new SchemaHelperError("rule is required.", "invalid_input", ["rule"]);
+  }
+  const next = deepClone(schema);
+  const node = next.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  const existing = node[OM_FIELD_KEYWORDS.validationMessages];
+  const current = existing && typeof existing === "object" && !Array.isArray(existing) ? { ...existing } : {};
+  const inner = current[locale] ? { ...current[locale] } : {};
+  const trimmed = typeof message === "string" ? message : "";
+  if (!trimmed) {
+    delete inner[rule];
+  } else {
+    inner[rule] = trimmed;
+  }
+  if (Object.keys(inner).length === 0) {
+    delete current[locale];
+  } else {
+    current[locale] = inner;
+  }
+  if (Object.keys(current).length === 0) {
+    delete node[OM_FIELD_KEYWORDS.validationMessages];
+  } else {
+    node[OM_FIELD_KEYWORDS.validationMessages] = current;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setFieldOpinionIcon(input) {
+  const { schema, fieldKey, icon } = input;
+  const next = deepClone(schema);
+  const node = next.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  if (icon === null || icon === "dot") {
+    delete node[OM_FIELD_KEYWORDS.opinionIcon];
+  } else {
+    node[OM_FIELD_KEYWORDS.opinionIcon] = icon;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setFieldNpsAnchors(input) {
+  const { schema, fieldKey, locale, anchor, label } = input;
+  if (!locale) {
+    throw new SchemaHelperError("locale is required.", "invalid_input", ["locale"]);
+  }
+  const next = deepClone(schema);
+  const node = next.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  const existing = node[OM_FIELD_KEYWORDS.npsAnchors];
+  const current = existing && typeof existing === "object" && !Array.isArray(existing) ? {
+    low: existing.low && typeof existing.low === "object" ? { ...existing.low } : void 0,
+    high: existing.high && typeof existing.high === "object" ? { ...existing.high } : void 0
+  } : {};
+  const target = current[anchor] ? { ...current[anchor] } : {};
+  const trimmed = typeof label === "string" ? label : "";
+  if (!trimmed) {
+    delete target[locale];
+  } else {
+    target[locale] = trimmed;
+  }
+  if (Object.keys(target).length === 0) {
+    delete current[anchor];
+  } else {
+    current[anchor] = target;
+  }
+  const hasLow = current.low && Object.keys(current.low).length > 0;
+  const hasHigh = current.high && Object.keys(current.high).length > 0;
+  if (!hasLow && !hasHigh) {
+    delete node[OM_FIELD_KEYWORDS.npsAnchors];
+  } else {
+    node[OM_FIELD_KEYWORDS.npsAnchors] = {
+      low: current.low ?? {},
+      high: current.high ?? {}
+    };
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setFieldRankingExhaustive(input) {
+  const { schema, fieldKey, value } = input;
+  const next = deepClone(schema);
+  const node = next.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  if (value === false) {
+    delete node[OM_FIELD_KEYWORDS.rankingExhaustive];
+  } else {
+    node[OM_FIELD_KEYWORDS.rankingExhaustive] = true;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+const MATRIX_ROW_KEY_PATTERN_HELPER = /^row_(\d+)$/;
+function nextMatrixRowKey(rows) {
+  let maxSuffix = 0;
+  for (const row of rows ?? []) {
+    const key = row.key;
+    if (typeof key !== "string") continue;
+    const match = MATRIX_ROW_KEY_PATTERN_HELPER.exec(key);
+    if (!match) continue;
+    const value = Number.parseInt(match[1], 10);
+    if (Number.isFinite(value) && value > maxSuffix) maxSuffix = value;
+  }
+  return `row_${maxSuffix + 1}`;
+}
+function readMatrixRowsArray(node) {
+  const raw = node[OM_FIELD_KEYWORDS.matrixRows];
+  if (!Array.isArray(raw)) return [];
+  return raw.map((entry) => {
+    const candidate = entry;
+    const row = {
+      key: typeof candidate.key === "string" ? candidate.key : "",
+      label: candidate.label && typeof candidate.label === "object" && !Array.isArray(candidate.label) ? { ...candidate.label } : {}
+    };
+    if (typeof candidate.multiple === "boolean") row.multiple = candidate.multiple;
+    if (typeof candidate.required === "boolean") row.required = candidate.required;
+    return row;
+  });
+}
+function readMatrixColumnsArray(node) {
+  const raw = node[OM_FIELD_KEYWORDS.matrixColumns];
+  if (!Array.isArray(raw)) return [];
+  return raw.map((entry) => {
+    const candidate = entry;
+    return {
+      value: typeof candidate.value === "string" ? candidate.value : "",
+      label: candidate.label && typeof candidate.label === "object" && !Array.isArray(candidate.label) ? { ...candidate.label } : {}
+    };
+  });
+}
+function canonicalMatrixRow(row) {
+  const result = {
+    key: row.key,
+    label: row.label
+  };
+  if (row.multiple === true) result.multiple = true;
+  if (row.required === true) result.required = true;
+  return result;
+}
+function canonicalMatrixColumn(column) {
+  return {
+    value: column.value,
+    label: column.label
+  };
+}
+function setMatrixRows(input) {
+  const { schema, fieldKey, rows } = input;
+  const next = deepClone(schema);
+  const node = next.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  if (!rows || rows.length === 0) {
+    delete node[OM_FIELD_KEYWORDS.matrixRows];
+  } else {
+    node[OM_FIELD_KEYWORDS.matrixRows] = rows.map(canonicalMatrixRow);
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setMatrixColumns(input) {
+  const { schema, fieldKey, columns } = input;
+  const next = deepClone(schema);
+  const node = next.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  if (!columns || columns.length === 0) {
+    delete node[OM_FIELD_KEYWORDS.matrixColumns];
+  } else {
+    node[OM_FIELD_KEYWORDS.matrixColumns] = columns.map(canonicalMatrixColumn);
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function addMatrixRow(input) {
+  const { schema, fieldKey, row } = input;
+  const node = schema.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  const existing = readMatrixRowsArray(node);
+  const requestedKey = row?.key && row.key.length > 0 ? row.key : nextMatrixRowKey(existing);
+  const newRow = {
+    key: requestedKey,
+    label: row?.label ?? { en: "New row" }
+  };
+  if (row?.multiple === true) newRow.multiple = true;
+  if (row?.required === true) newRow.required = true;
+  return setMatrixRows({ schema, fieldKey, rows: [...existing, newRow] });
+}
+function removeMatrixRow(input) {
+  const { schema, fieldKey, rowKey } = input;
+  const node = schema.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  const existing = readMatrixRowsArray(node);
+  return setMatrixRows({
+    schema,
+    fieldKey,
+    rows: existing.filter((entry) => entry.key !== rowKey)
+  });
+}
+function moveMatrixRow(input) {
+  const { schema, fieldKey, fromIndex, toIndex } = input;
+  const node = schema.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  const rows = readMatrixRowsArray(node);
+  if (rows.length === 0) return schema;
+  const sourceIndex = Math.max(0, Math.min(fromIndex, rows.length - 1));
+  const destIndex = Math.max(0, Math.min(toIndex, rows.length - 1));
+  if (sourceIndex === destIndex) return schema;
+  const [moved] = rows.splice(sourceIndex, 1);
+  rows.splice(destIndex, 0, moved);
+  return setMatrixRows({ schema, fieldKey, rows });
+}
+function addMatrixColumn(input) {
+  const { schema, fieldKey, column } = input;
+  const node = schema.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  const existing = readMatrixColumnsArray(node);
+  let value = column?.value && column.value.length > 0 ? column.value : "";
+  if (!value) {
+    const pattern = /^col_(\d+)$/;
+    let maxSuffix = 0;
+    for (const entry of existing) {
+      const match = pattern.exec(entry.value);
+      if (!match) continue;
+      const parsed = Number.parseInt(match[1], 10);
+      if (Number.isFinite(parsed) && parsed > maxSuffix) maxSuffix = parsed;
+    }
+    value = `col_${maxSuffix + 1}`;
+  }
+  const newColumn = {
+    value,
+    label: column?.label ?? { en: "New column" }
+  };
+  return setMatrixColumns({ schema, fieldKey, columns: [...existing, newColumn] });
+}
+function removeMatrixColumn(input) {
+  const { schema, fieldKey, value } = input;
+  const node = schema.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  const existing = readMatrixColumnsArray(node);
+  return setMatrixColumns({
+    schema,
+    fieldKey,
+    columns: existing.filter((entry) => entry.value !== value)
+  });
+}
+function moveMatrixColumn(input) {
+  const { schema, fieldKey, fromIndex, toIndex } = input;
+  const node = schema.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  const columns = readMatrixColumnsArray(node);
+  if (columns.length === 0) return schema;
+  const sourceIndex = Math.max(0, Math.min(fromIndex, columns.length - 1));
+  const destIndex = Math.max(0, Math.min(toIndex, columns.length - 1));
+  if (sourceIndex === destIndex) return schema;
+  const [moved] = columns.splice(sourceIndex, 1);
+  columns.splice(destIndex, 0, moved);
+  return setMatrixColumns({ schema, fieldKey, columns });
+}
+const GROUP_SUB_FIELD_KEY_PATTERN = /^field_(\d+)$/;
+function buildGroupItemsNode(properties, required) {
+  return { type: "object", additionalProperties: false, properties, required };
+}
+function buildGroupSubFieldNode(typeKey, label) {
+  const jsonType = FIELD_TYPE_TO_JSON_TYPE[typeKey] ?? "string";
+  const subNode = {
+    type: jsonType,
+    "x-om-type": typeKey,
+    "x-om-label": label
+  };
+  const subInitializer = FIELD_TYPE_NODE_INITIALIZER[typeKey];
+  if (subInitializer) subInitializer(subNode);
+  return subNode;
+}
+function groupNodeAddSubField(node, label) {
+  const { properties, required } = readGroupItemsNode(node);
+  const key = nextGroupSubFieldKey(properties);
+  const subNode = buildGroupSubFieldNode("text", label);
+  const updated = { ...node };
+  updated.items = buildGroupItemsNode({ ...properties, [key]: subNode }, required);
+  return updated;
+}
+function groupNodeRemoveSubField(node, subFieldKey) {
+  const { properties, required } = readGroupItemsNode(node);
+  const nextProperties = {};
+  for (const [key, subNode] of Object.entries(properties)) {
+    if (key === subFieldKey) continue;
+    nextProperties[key] = subNode;
+  }
+  const updated = { ...node };
+  updated.items = buildGroupItemsNode(nextProperties, required.filter((entry) => entry !== subFieldKey));
+  return updated;
+}
+function groupNodeUpdateSubField(node, subFieldKey, patch) {
+  const { properties, required } = readGroupItemsNode(node);
+  const existing = properties[subFieldKey];
+  if (!existing) return node;
+  let nextSubNode = { ...existing };
+  if (patch.label !== void 0) {
+    nextSubNode["x-om-label"] = patch.label;
+  }
+  if (patch.type !== void 0 && patch.type.length > 0 && patch.type !== existing["x-om-type"]) {
+    nextSubNode = buildGroupSubFieldNode(patch.type, nextSubNode["x-om-label"] ?? { en: "New sub-field" });
+  }
+  let nextRequired = required;
+  if (patch.required !== void 0) {
+    nextRequired = patch.required ? Array.from(/* @__PURE__ */ new Set([...required, subFieldKey])) : required.filter((entry) => entry !== subFieldKey);
+  }
+  const updated = { ...node };
+  updated.items = buildGroupItemsNode({ ...properties, [subFieldKey]: nextSubNode }, nextRequired);
+  return updated;
+}
+function readGroupItemsNode(node) {
+  const items = node.items;
+  const itemsNode = items && typeof items === "object" && !Array.isArray(items) ? items : {};
+  const properties = itemsNode.properties && typeof itemsNode.properties === "object" && !Array.isArray(itemsNode.properties) ? itemsNode.properties : {};
+  const required = Array.isArray(itemsNode.required) ? itemsNode.required.filter((entry) => typeof entry === "string") : [];
+  return { properties, required };
+}
+function nextGroupSubFieldKey(properties) {
+  let maxSuffix = 0;
+  for (const key of Object.keys(properties)) {
+    const match = GROUP_SUB_FIELD_KEY_PATTERN.exec(key);
+    if (!match) continue;
+    const value = Number.parseInt(match[1], 10);
+    if (Number.isFinite(value) && value > maxSuffix) maxSuffix = value;
+  }
+  return `field_${maxSuffix + 1}`;
+}
+function setGroupItemRange(input) {
+  const { schema, fieldKey, min, max } = input;
+  const next = deepClone(schema);
+  const node = next.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(`Field "${fieldKey}" not found.`, "unknown_field", [fieldKey]);
+  }
+  if (min !== void 0) {
+    if (min === null) delete node[OM_FIELD_KEYWORDS.minItems];
+    else node[OM_FIELD_KEYWORDS.minItems] = min;
+  }
+  if (max !== void 0) {
+    if (max === null) delete node[OM_FIELD_KEYWORDS.maxItems];
+    else node[OM_FIELD_KEYWORDS.maxItems] = max;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function addGroupSubField(input) {
+  const { schema, fieldKey, subField } = input;
+  const next = deepClone(schema);
+  const node = next.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(`Field "${fieldKey}" not found.`, "unknown_field", [fieldKey]);
+  }
+  const { properties, required } = readGroupItemsNode(node);
+  const typeKey = subField?.type && subField.type.length > 0 ? subField.type : "text";
+  const jsonType = FIELD_TYPE_TO_JSON_TYPE[typeKey] ?? "string";
+  const key = subField?.key && subField.key.length > 0 ? subField.key : nextGroupSubFieldKey(properties);
+  const subNode = {
+    type: jsonType,
+    "x-om-type": typeKey,
+    "x-om-label": subField?.label ?? { en: "New sub-field" }
+  };
+  const subInitializer = FIELD_TYPE_NODE_INITIALIZER[typeKey];
+  if (subInitializer) subInitializer(subNode);
+  const nextProperties = { ...properties, [key]: subNode };
+  const nextRequired = subField?.required === true ? [...required, key] : required;
+  node.items = {
+    type: "object",
+    additionalProperties: false,
+    properties: nextProperties,
+    required: nextRequired
+  };
+  validateSchemaExtensions(next);
+  return next;
+}
+function removeGroupSubField(input) {
+  const { schema, fieldKey, subFieldKey } = input;
+  const next = deepClone(schema);
+  const node = next.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(`Field "${fieldKey}" not found.`, "unknown_field", [fieldKey]);
+  }
+  const { properties, required } = readGroupItemsNode(node);
+  if (!properties[subFieldKey]) {
+    throw new SchemaHelperError(
+      `Sub-field "${subFieldKey}" not found in group "${fieldKey}".`,
+      "unknown_sub_field",
+      [fieldKey, subFieldKey]
+    );
+  }
+  const nextProperties = {};
+  for (const [key, subNode] of Object.entries(properties)) {
+    if (key === subFieldKey) continue;
+    nextProperties[key] = subNode;
+  }
+  node.items = {
+    type: "object",
+    additionalProperties: false,
+    properties: nextProperties,
+    required: required.filter((entry) => entry !== subFieldKey)
+  };
+  validateSchemaExtensions(next);
+  return next;
+}
+function updateGroupSubField(input) {
+  const { schema, fieldKey, subFieldKey, patch } = input;
+  const next = deepClone(schema);
+  const node = next.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(`Field "${fieldKey}" not found.`, "unknown_field", [fieldKey]);
+  }
+  const { properties, required } = readGroupItemsNode(node);
+  const subNode = properties[subFieldKey];
+  if (!subNode) {
+    throw new SchemaHelperError(
+      `Sub-field "${subFieldKey}" not found in group "${fieldKey}".`,
+      "unknown_sub_field",
+      [fieldKey, subFieldKey]
+    );
+  }
+  let nextSubNode = { ...subNode };
+  if (patch.label !== void 0) {
+    nextSubNode["x-om-label"] = patch.label;
+  }
+  if (patch.type !== void 0 && patch.type.length > 0 && patch.type !== subNode["x-om-type"]) {
+    const jsonType = FIELD_TYPE_TO_JSON_TYPE[patch.type] ?? "string";
+    nextSubNode = {
+      type: jsonType,
+      "x-om-type": patch.type,
+      "x-om-label": nextSubNode["x-om-label"] ?? { en: "New sub-field" }
+    };
+    const subInitializer = FIELD_TYPE_NODE_INITIALIZER[patch.type];
+    if (subInitializer) subInitializer(nextSubNode);
+  }
+  const nextProperties = { ...properties, [subFieldKey]: nextSubNode };
+  let nextRequired = required;
+  if (patch.required !== void 0) {
+    nextRequired = patch.required ? Array.from(/* @__PURE__ */ new Set([...required, subFieldKey])) : required.filter((entry) => entry !== subFieldKey);
+  }
+  node.items = {
+    type: "object",
+    additionalProperties: false,
+    properties: nextProperties,
+    required: nextRequired
+  };
+  validateSchemaExtensions(next);
+  return next;
+}
+function setFieldHideMobile(input) {
+  const { schema, fieldKey, value } = input;
+  const next = deepClone(schema);
+  const node = next.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  if (value === false) {
+    delete node[OM_FIELD_KEYWORDS.hideMobile];
+  } else {
+    node[OM_FIELD_KEYWORDS.hideMobile] = true;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+const SWAP_FAMILIES = {
+  text: /* @__PURE__ */ new Set(["text", "textarea"]),
+  textarea: /* @__PURE__ */ new Set(["text", "textarea"]),
+  number: /* @__PURE__ */ new Set(["number", "integer"]),
+  integer: /* @__PURE__ */ new Set(["number", "integer"]),
+  boolean: /* @__PURE__ */ new Set(["boolean", "yes_no", "yes_no_buttons"]),
+  yes_no: /* @__PURE__ */ new Set(["boolean", "yes_no", "yes_no_buttons"]),
+  yes_no_buttons: /* @__PURE__ */ new Set(["boolean", "yes_no", "yes_no_buttons"]),
+  select_one: /* @__PURE__ */ new Set(["select_one", "select_many"]),
+  select_many: /* @__PURE__ */ new Set(["select_one", "select_many"])
+};
+const FIELD_TYPE_TO_DEFAULT_UI = {
+  text: { widget: "text" },
+  textarea: { widget: "textarea", rows: 4 },
+  number: { widget: "number" },
+  integer: { widget: "integer" },
+  boolean: { widget: "checkbox" },
+  yes_no: { widget: "yes_no" },
+  yes_no_buttons: { widget: "yes_no_buttons" },
+  date: { widget: "date" },
+  datetime: { widget: "datetime" },
+  select_one: { widget: "select" },
+  select_many: { widget: "multiselect" },
+  scale: { widget: "scale" },
+  info_block: { widget: "info" },
+  // Tier-2 — Phase B.
+  email: { widget: "email" },
+  phone: { widget: "phone" },
+  website: { widget: "website" },
+  // Tier-2 — Phase C.
+  address: { widget: "address" },
+  // Tier-2 — Phase D.
+  nps: { widget: "nps" },
+  opinion_scale: { widget: "opinion_scale" },
+  // Tier-2 — Phase E.
+  ranking: { widget: "ranking" },
+  // Tier-2 — Phase F.
+  matrix: { widget: "matrix" }
+};
+function isCompatibleFieldSwap(from, to) {
+  if (from === to) return true;
+  const family = SWAP_FAMILIES[from];
+  if (!family) return false;
+  return family.has(to);
+}
+function swapFieldType(input) {
+  const { schema, fieldKey, targetType } = input;
+  const node = schema.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  const fromType = String(node["x-om-type"] ?? "");
+  if (!isCompatibleFieldSwap(fromType, targetType)) {
+    throw new SchemaHelperError(
+      `Cross-family swap "${fromType}" \u2192 "${targetType}" is not supported. Delete the field and recreate it.`,
+      "incompatible_swap",
+      [fieldKey, OM_FIELD_KEYWORDS.type]
+    );
+  }
+  const next = deepClone(schema);
+  const target = next.properties[fieldKey];
+  target["x-om-type"] = targetType;
+  target.type = FIELD_TYPE_TO_JSON_TYPE[targetType] ?? target.type ?? "string";
+  const targetUi = FIELD_TYPE_TO_DEFAULT_UI[targetType];
+  if (targetUi && typeof targetUi.widget === "string") {
+    target[OM_FIELD_KEYWORDS.widget] = targetUi.widget;
+  } else {
+    delete target[OM_FIELD_KEYWORDS.widget];
+  }
+  const leavingSelectFamily = (fromType === "select_one" || fromType === "select_many") && targetType !== "select_one" && targetType !== "select_many";
+  if (leavingSelectFamily) {
+    delete target[OM_FIELD_KEYWORDS.options];
+  }
+  const leavingNumberFamily = (fromType === "number" || fromType === "integer") && targetType !== "number" && targetType !== "integer";
+  if (leavingNumberFamily) {
+    delete target[OM_FIELD_KEYWORDS.min];
+    delete target[OM_FIELD_KEYWORDS.max];
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setFormStyle(input) {
+  const { schema, style } = input;
+  const next = deepClone(schema);
+  if (style === "default") {
+    delete next[OM_ROOT_KEYWORDS.formStyle];
+  } else {
+    ;
+    next[OM_ROOT_KEYWORDS.formStyle] = style;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setFormLabelPosition(input) {
+  const { schema, position } = input;
+  const next = deepClone(schema);
+  if (position === "top") {
+    delete next[OM_ROOT_KEYWORDS.formLabelPosition];
+  } else {
+    ;
+    next[OM_ROOT_KEYWORDS.formLabelPosition] = position;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setPageMode(input) {
+  const { schema, mode } = input;
+  const next = deepClone(schema);
+  if (mode === "stacked") {
+    delete next[OM_ROOT_KEYWORDS.pageMode];
+  } else {
+    ;
+    next[OM_ROOT_KEYWORDS.pageMode] = mode;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setShowProgress(input) {
+  const { schema, value } = input;
+  const next = deepClone(schema);
+  if (value === false) {
+    delete next[OM_ROOT_KEYWORDS.showProgress];
+  } else {
+    ;
+    next[OM_ROOT_KEYWORDS.showProgress] = true;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function isEmptyTheme(theme) {
+  if (!theme) return true;
+  return Object.keys(theme).length === 0;
+}
+function setFormTheme(schema, theme) {
+  const next = deepClone(schema);
+  if (isEmptyTheme(theme)) {
+    delete next[OM_ROOT_KEYWORDS.theme];
+  } else {
+    ;
+    next[OM_ROOT_KEYWORDS.theme] = theme;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setFormThemeField(schema, key, value) {
+  const current = schema[OM_ROOT_KEYWORDS.theme];
+  const nextTheme = { ...current ?? {} };
+  if (value === void 0) {
+    delete nextTheme[key];
+  } else {
+    nextTheme[key] = value;
+  }
+  return setFormTheme(schema, nextTheme);
+}
+function setSectionStyle(schema, sectionKey, style) {
+  const next = deepClone(schema);
+  const sections = next[OM_ROOT_KEYWORDS.sections] ?? [];
+  const section = sections.find((entry) => entry.key === sectionKey);
+  if (!section) {
+    throw new SchemaHelperError(
+      `Section "${sectionKey}" not found.`,
+      "unknown_section",
+      [sectionKey]
+    );
+  }
+  if (!style || Object.keys(style).length === 0) {
+    delete section.style;
+  } else {
+    section.style = style;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function setFieldStyle(schema, fieldKey, style) {
+  const next = deepClone(schema);
+  const node = next.properties[fieldKey];
+  if (!node) {
+    throw new SchemaHelperError(
+      `Field "${fieldKey}" not found.`,
+      "unknown_field",
+      [fieldKey]
+    );
+  }
+  if (!style || Object.keys(style).length === 0) {
+    delete node[OM_FIELD_KEYWORDS.style];
+  } else {
+    node[OM_FIELD_KEYWORDS.style] = style;
+  }
+  validateSchemaExtensions(next);
+  return next;
+}
+function dedupePreservingOrder(values) {
+  const seen = /* @__PURE__ */ new Set();
+  const ordered = [];
+  for (const value of values) {
+    if (seen.has(value)) continue;
+    seen.add(value);
+    ordered.push(value);
+  }
+  return ordered;
+}
+function addRoleToSchema(schema, role) {
+  const next = deepClone(schema);
+  const roles = dedupePreservingOrder([
+    "admin",
+    ...next[OM_ROOT_KEYWORDS.roles] ?? [],
+    role
+  ]);
+  next[OM_ROOT_KEYWORDS.roles] = roles;
+  return next;
+}
+function renameRoleInSchema(schema, oldRole, newRole) {
+  const next = deepClone(schema);
+  if (oldRole === "admin" || newRole === "admin" || oldRole === newRole) return next;
+  const roles = dedupePreservingOrder(
+    (next[OM_ROOT_KEYWORDS.roles] ?? []).map(
+      (entry) => entry === oldRole ? newRole : entry
+    )
+  );
+  next[OM_ROOT_KEYWORDS.roles] = roles;
+  if (next[OM_ROOT_KEYWORDS.defaultActorRole] === oldRole) {
+    next[OM_ROOT_KEYWORDS.defaultActorRole] = newRole;
+  }
+  for (const field of Object.values(next.properties)) {
+    for (const keyword of [OM_FIELD_KEYWORDS.editableBy, OM_FIELD_KEYWORDS.visibleTo]) {
+      const list = field[keyword];
+      if (!Array.isArray(list)) continue;
+      field[keyword] = dedupePreservingOrder(
+        list.map((entry) => entry === oldRole ? newRole : entry)
+      );
+    }
+  }
+  return next;
+}
+function removeRoleFromSchema(schema, role) {
+  const next = deepClone(schema);
+  if (role === "admin") return next;
+  next[OM_ROOT_KEYWORDS.roles] = (next[OM_ROOT_KEYWORDS.roles] ?? []).filter((entry) => entry !== role);
+  if (next[OM_ROOT_KEYWORDS.defaultActorRole] === role) {
+    next[OM_ROOT_KEYWORDS.defaultActorRole] = "admin";
+  }
+  for (const field of Object.values(next.properties)) {
+    const editableBy = field[OM_FIELD_KEYWORDS.editableBy];
+    if (Array.isArray(editableBy)) {
+      const filtered = editableBy.filter((entry) => entry !== role);
+      field[OM_FIELD_KEYWORDS.editableBy] = filtered.length > 0 ? filtered : ["admin"];
+    }
+    const visibleTo = field[OM_FIELD_KEYWORDS.visibleTo];
+    if (Array.isArray(visibleTo)) {
+      field[OM_FIELD_KEYWORDS.visibleTo] = visibleTo.filter(
+        (entry) => entry !== role
+      );
+    }
+  }
+  return next;
+}
+const GUEST_ROLE = "guest";
+function isGuestSubmissionEnabled(schema) {
+  const roles = schema[OM_ROOT_KEYWORDS.roles] ?? [];
+  return roles.includes(GUEST_ROLE) && schema[OM_ROOT_KEYWORDS.defaultActorRole] === GUEST_ROLE;
+}
+function enableGuestSubmissions(schema) {
+  const next = addRoleToSchema(schema, GUEST_ROLE);
+  next[OM_ROOT_KEYWORDS.defaultActorRole] = GUEST_ROLE;
+  for (const field of Object.values(next.properties)) {
+    const editableBy = field[OM_FIELD_KEYWORDS.editableBy] ?? [];
+    field[OM_FIELD_KEYWORDS.editableBy] = dedupePreservingOrder([
+      ...editableBy,
+      GUEST_ROLE,
+      "admin"
+    ]);
+  }
+  return next;
+}
+function disableGuestSubmissions(schema) {
+  return removeRoleFromSchema(schema, GUEST_ROLE);
+}
+function computeOrphanFieldKeys(schema) {
+  const sections = schema[OM_ROOT_KEYWORDS.sections] ?? [];
+  const claimed = /* @__PURE__ */ new Set();
+  for (const section of sections) {
+    for (const fieldKey of section.fieldKeys) claimed.add(fieldKey);
+  }
+  const orphans = [];
+  for (const fieldKey of Object.keys(schema.properties)) {
+    if (!claimed.has(fieldKey)) orphans.push(fieldKey);
+  }
+  return orphans;
+}
+function adoptUngroupedAsSection(input) {
+  const orphans = computeOrphanFieldKeys(input.schema);
+  if (orphans.length === 0) {
+    throw new SchemaHelperError(
+      "No ungrouped fields to adopt.",
+      "no_orphans",
+      []
+    );
+  }
+  const next = deepClone(input.schema);
+  const sections = next[OM_ROOT_KEYWORDS.sections] ?? [];
+  const newKey = nextSectionKey(sections);
+  const newSection = {
+    key: newKey,
+    kind: "section",
+    title: { en: "Untitled" },
+    fieldKeys: [...orphans]
+  };
+  next[OM_ROOT_KEYWORDS.sections] = [newSection, ...sections];
+  validateSchemaExtensions(next);
+  return { schema: next, sectionKey: newKey };
+}
+function collectCanonicalOrder(schema) {
+  const ordered = [];
+  const sections = schema[OM_ROOT_KEYWORDS.sections] ?? [];
+  for (const section of sections) {
+    for (const fieldKey of section.fieldKeys) {
+      if (!ordered.includes(fieldKey)) ordered.push(fieldKey);
+    }
+  }
+  for (const fieldKey of Object.keys(schema.properties)) {
+    if (!ordered.includes(fieldKey)) ordered.push(fieldKey);
+  }
+  return ordered;
+}
+export {
+  GUEST_ROLE,
+  SWAP_FAMILIES,
+  SchemaHelperError,
+  UNGROUPED_SECTION_KEY,
+  addFieldFromPalette,
+  addGroupSubField,
+  addLayoutFromPalette,
+  addMatrixColumn,
+  addMatrixRow,
+  addRoleToSchema,
+  adoptUngroupedAsSection,
+  buildGroupSubFieldNode,
+  computeOrphanFieldKeys,
+  deepClone,
+  deleteField,
+  deleteSection,
+  disableGuestSubmissions,
+  enableGuestSubmissions,
+  findSectionOwning,
+  groupNodeAddSubField,
+  groupNodeRemoveSubField,
+  groupNodeUpdateSubField,
+  indexOfFieldInSection,
+  isCompatibleFieldSwap,
+  isGuestSubmissionEnabled,
+  linearizeFields,
+  moveField,
+  moveMatrixColumn,
+  moveMatrixRow,
+  moveSection,
+  nextFieldKey,
+  nextSectionKey,
+  removeGroupSubField,
+  removeMatrixColumn,
+  removeMatrixRow,
+  removeRoleFromSchema,
+  renameRoleInSchema,
+  setFieldAlign,
+  setFieldGridSpan,
+  setFieldHideMobile,
+  setFieldLengthRange,
+  setFieldNpsAnchors,
+  setFieldNumberRange,
+  setFieldOpinionIcon,
+  setFieldPattern,
+  setFieldRankingExhaustive,
+  setFieldStyle,
+  setFieldValidationMessages,
+  setFieldVisibilityIf,
+  setFormLabelPosition,
+  setFormStyle,
+  setFormTheme,
+  setFormThemeField,
+  setGroupItemRange,
+  setHiddenFields,
+  setJumps,
+  setMatrixColumns,
+  setMatrixRows,
+  setPageMode,
+  setRedirectUrl,
+  setSectionColumns,
+  setSectionDivider,
+  setSectionGap,
+  setSectionHideTitle,
+  setSectionKind,
+  setSectionStyle,
+  setSectionTitle,
+  setSectionVisibilityIf,
+  setShowProgress,
+  setVariables,
+  swapFieldType,
+  updateGroupSubField,
+  validateSchemaExtensions
+};
+//# sourceMappingURL=schema-helpers.js.map