@frt-platform/report-core 1.2.0 → 1.3.0

package/dist/index.mjs

@@ -1,4 +1,4 @@
-// src/schema.ts
+// src/template/schema.ts
 import { z } from "zod";
 var REPORT_TEMPLATE_VERSION = 1;
 var REPORT_TEMPLATE_FIELD_TYPES = [
@@ -123,59 +123,7 @@ var ReportTemplateSchemaValidator = z.object({
   sections: z.array(ReportTemplateSectionSchema).max(25, "Templates can include at most 25 sections.").default([])
 });
 
-// src/fields.ts
-var DEFAULT_FIELD_LABEL = "Untitled question";
-var CORE_FIELD_DEFAULTS = {
-  shortText: {
-    label: DEFAULT_FIELD_LABEL,
-    placeholder: "Short answer text"
-  },
-  longText: {
-    label: DEFAULT_FIELD_LABEL,
-    placeholder: "Long answer text"
-  },
-  number: {
-    label: DEFAULT_FIELD_LABEL,
-    placeholder: "123"
-  },
-  date: {
-    label: DEFAULT_FIELD_LABEL
-  },
-  checkbox: {
-    label: DEFAULT_FIELD_LABEL,
-    placeholder: "Check to confirm"
-  },
-  singleSelect: {
-    label: DEFAULT_FIELD_LABEL,
-    options: ["Option 1", "Option 2", "Option 3"]
-  },
-  multiSelect: {
-    label: DEFAULT_FIELD_LABEL,
-    options: ["Option 1", "Option 2", "Option 3"],
-    allowOther: false
-  },
-  repeatGroup: {
-    // Minimal safe defaults – your builder UI is expected
-    // to configure nested fields + min/max as needed.
-    label: DEFAULT_FIELD_LABEL,
-    fields: []
-    // nested fields go here in the UI layer
-  }
-};
-
-// src/ids.ts
-function createUniqueId(prefix, existing) {
-  const used = new Set(existing);
-  let attempt = used.size + 1;
-  let candidate = `${prefix}-${attempt}`;
-  while (used.has(candidate)) {
-    attempt++;
-    candidate = `${prefix}-${attempt}`;
-  }
-  return candidate;
-}
-
-// src/migrate.ts
+// src/template/migrate.ts
 var LEGACY_FIELD_TYPE_MAP = {
   shorttext: "shortText",
   text: "shortText",
@@ -202,12 +150,14 @@ function migrateLegacySchema(raw) {
   if (obj.fields) {
     obj.sections = [
       {
-        id: "section-1",
+        id: "section_1",
+        // ⬅ underscore to match normalizer/tests
         title: obj.title,
         description: obj.description,
         fields: obj.fields.map((f, i) => ({
           ...f,
-          id: f.id || `field-${i + 1}`,
+          id: f.id || `field_${i + 1}`,
+          // ⬅ underscore here too
           type: LEGACY_FIELD_TYPE_MAP[f.type?.toLowerCase()] ?? f.type
         }))
       }
@@ -218,10 +168,12 @@ function migrateLegacySchema(raw) {
   if (Array.isArray(obj.sections)) {
     obj.sections = obj.sections.map((sec, i) => ({
       ...sec,
-      id: sec.id || `section-${i + 1}`,
+      id: sec.id || `section_${i + 1}`,
+      // ⬅ underscore
       fields: (sec.fields || []).map((f, idx) => ({
         ...f,
-        id: f.id || `field-${idx + 1}`,
+        id: f.id || `field_${idx + 1}`,
+        // ⬅ underscore
         type: LEGACY_FIELD_TYPE_MAP[f.type?.toLowerCase()] ?? f.type
       }))
     }));
@@ -229,7 +181,7 @@ function migrateLegacySchema(raw) {
   return obj;
 }
 
-// src/normalize.ts
+// src/template/normalize.ts
 function normalizeId(raw, fallback) {
   if (!raw || typeof raw !== "string") return fallback;
   const cleaned = raw.trim().toLowerCase().replace(/\s+/g, "_").replace(/[^a-z0-9_-]/g, "");
@@ -302,349 +254,96 @@ function parseReportTemplateSchema(raw) {
 function parseReportTemplateSchemaFromString(raw) {
   return parseReportTemplateSchema(JSON.parse(raw));
 }
-function serializeReportTemplateSchema(schema) {
-  return JSON.stringify(schema, null, 2);
-}
-
-// src/responses.ts
-import { z as z2 } from "zod";
-
-// src/fieldRegistry.ts
-var FieldRegistryClass = class {
-  constructor() {
-    this.registry = /* @__PURE__ */ new Map();
-  }
-  /** Register or override a field type. */
-  register(type, entry) {
-    this.registry.set(type, entry);
-  }
-  /** Get registry entry for a field type. */
-  get(type) {
-    return this.registry.get(type);
-  }
-  /** Check if field type is registered. */
-  has(type) {
-    return this.registry.has(type);
-  }
-  /** Return all field types currently registered. */
-  list() {
-    return [...this.registry.keys()];
-  }
-};
-var FieldRegistry = new FieldRegistryClass();
-var CORE_TYPES = [
-  "shortText",
-  "longText",
-  "number",
-  "date",
-  "checkbox",
-  "singleSelect",
-  "multiSelect"
-];
-for (const type of CORE_TYPES) {
-  FieldRegistry.register(type, {
-    defaults: CORE_FIELD_DEFAULTS[type]
-    // Core types rely on existing validation logic.
-    // buildResponseSchema is optional — fallback handles it.
-  });
-}
-
-// src/conditions.ts
-function evaluateCondition(condition, response) {
-  if ("equals" in condition) {
-    return Object.entries(condition.equals).every(([key, val]) => {
-      return response[key] === val;
+function serializeReportTemplateSchema(schema, options = {}) {
+  const {
+    pretty = true,
+    sortSectionsById = false,
+    sortFieldsById = false
+  } = options;
+  let toSerialize = schema;
+  if (sortSectionsById || sortFieldsById) {
+    const sortedSections = [...schema.sections].map((section) => {
+      const clonedSection = { ...section };
+      if (sortFieldsById) {
+        const fields = section.fields ?? [];
+        clonedSection.fields = [...fields].sort(
+          (a, b) => a.id.localeCompare(b.id)
+        );
+      }
+      return clonedSection;
     });
+    if (sortSectionsById) {
+      toSerialize = {
+        ...schema,
+        sections: sortedSections.sort(
+          (a, b) => a.id.localeCompare(b.id)
+        )
+      };
+    } else {
+      toSerialize = {
+        ...schema,
+        sections: sortedSections
+      };
+    }
   }
-  if ("any" in condition) {
-    return condition.any.some(
-      (sub) => evaluateCondition(sub, response)
-    );
-  }
-  if ("all" in condition) {
-    return condition.all.every(
-      (sub) => evaluateCondition(sub, response)
-    );
-  }
-  if ("not" in condition) {
-    const sub = condition.not;
-    return !evaluateCondition(sub, response);
-  }
-  return false;
+  return JSON.stringify(toSerialize, null, pretty ? 2 : 0);
 }
 
-// src/responses.ts
-function buildBaseFieldSchema(field) {
-  const isRequired = Boolean(field.required);
-  const registry = FieldRegistry.get(field.type);
-  if (registry?.buildResponseSchema) {
-    return registry.buildResponseSchema(field);
-  }
-  switch (field.type) {
-    case "shortText":
-    case "longText": {
-      let schema = z2.string();
-      if (typeof field.minLength === "number") {
-        schema = schema.min(field.minLength);
-      }
-      if (typeof field.maxLength === "number") {
-        schema = schema.max(field.maxLength);
-      }
-      return isRequired ? schema : schema.optional();
-    }
-    case "number": {
-      let schema = z2.number();
-      if (typeof field.minValue === "number") {
-        schema = schema.min(field.minValue);
-      }
-      if (typeof field.maxValue === "number") {
-        schema = schema.max(field.maxValue);
-      }
-      return isRequired ? schema : schema.optional();
-    }
-    case "date": {
-      let schema = z2.string();
-      return isRequired ? schema : schema.optional();
-    }
-    case "checkbox": {
-      if (isRequired) return z2.literal(true);
-      return z2.boolean().optional();
-    }
-    case "singleSelect": {
-      let schema = z2.string();
-      if (Array.isArray(field.options) && field.options.length > 0) {
-        const allowed = new Set(field.options);
-        schema = schema.refine(
-          (value) => allowed.has(value),
-          "Value must be one of the defined options."
-        );
-      }
-      return isRequired ? schema : schema.optional();
-    }
-    case "multiSelect": {
-      let schema = z2.array(z2.string());
-      if (Array.isArray(field.options) && field.options.length > 0 && !field.allowOther) {
-        const allowed = new Set(field.options);
-        schema = schema.refine(
-          (values) => values.every((value) => allowed.has(value)),
-          "All values must be among the defined options."
-        );
-      }
-      if (typeof field.minSelections === "number") {
-        schema = schema.min(
-          field.minSelections,
-          `Select at least ${field.minSelections} option(s).`
-        );
-      } else if (isRequired) {
-        schema = schema.min(
-          1,
-          "Select at least one option."
-        );
-      }
-      if (typeof field.maxSelections === "number") {
-        schema = schema.max(
-          field.maxSelections,
-          `Select at most ${field.maxSelections} option(s).`
-        );
-      }
-      return isRequired ? schema : schema.optional();
-    }
-    default: {
-      return z2.any();
+// src/template/diff.ts
+function indexById(items) {
+  const map = {};
+  items.forEach((item, i) => map[item.id] = i);
+  return map;
+}
+function diffObjectProperties(before, after, ignoreKeys = []) {
+  const changes = [];
+  const keys = /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)]);
+  for (const key of keys) {
+    if (ignoreKeys.includes(key)) continue;
+    const b = before[key];
+    const a = after[key];
+    const changed = Array.isArray(b) && Array.isArray(a) ? JSON.stringify(b) !== JSON.stringify(a) : b !== a;
+    if (changed) {
+      changes.push({ key, before: b, after: a });
     }
   }
+  return changes;
 }
-function buildConditionalFieldSchema(field, response) {
-  if (field.visibleIf) {
-    const visible = evaluateCondition(field.visibleIf, response);
-    if (!visible) {
-      return z2.any().optional();
+function diffRepeatGroupFields(beforeFields, afterFields, sectionId, groupId) {
+  const empty = {
+    addedSections: [],
+    removedSections: [],
+    reorderedSections: [],
+    modifiedSections: [],
+    addedFields: [],
+    removedFields: [],
+    reorderedFields: [],
+    modifiedFields: [],
+    nestedFieldDiffs: []
+  };
+  const beforeIndex = indexById(beforeFields);
+  const afterIndex = indexById(afterFields);
+  for (const f of afterFields) {
+    if (!(f.id in beforeIndex)) {
+      empty.addedFields.push({ sectionId, fieldId: f.id, index: afterIndex[f.id] });
     }
   }
-  let schema = buildBaseFieldSchema(field);
-  if (field.requiredIf) {
-    const shouldBeRequired = evaluateCondition(field.requiredIf, response);
-    if (shouldBeRequired) {
-      if (schema instanceof z2.ZodOptional) {
-        schema = schema.unwrap();
-      }
-    }
-  }
-  return schema;
-}
-function buildResponseSchemaWithConditions(template, response) {
-  const shape = {};
-  for (const section of template.sections) {
-    for (const field of section.fields) {
-      shape[field.id] = buildConditionalFieldSchema(field, response);
-    }
-  }
-  return z2.object(shape);
-}
-function validateReportResponse(template, data) {
-  if (typeof data !== "object" || data === null) {
-    throw new Error("Response must be an object");
-  }
-  const response = data;
-  const schema = buildResponseSchemaWithConditions(template, response);
-  const parsed = schema.parse(response);
-  for (const section of template.sections) {
-    for (const field of section.fields) {
-      if (field.visibleIf) {
-        const visible = evaluateCondition(field.visibleIf, response);
-        if (!visible) {
-          delete parsed[field.id];
-        }
-      }
-    }
-  }
-  return parsed;
-}
-function mapZodIssueToFieldErrorCode(issue) {
-  switch (issue.code) {
-    case z2.ZodIssueCode.invalid_type:
-      return "field.invalid_type";
-    case z2.ZodIssueCode.too_small:
-      return "field.too_small";
-    case z2.ZodIssueCode.too_big:
-      return "field.too_big";
-    case z2.ZodIssueCode.invalid_enum_value:
-    case z2.ZodIssueCode.invalid_literal:
-      return "field.invalid_option";
-    case z2.ZodIssueCode.custom:
-      return "field.custom";
-    default:
-      return "field.custom";
-  }
-}
-function buildFieldMetadataLookup(template) {
-  const map = /* @__PURE__ */ new Map();
-  for (const section of template.sections) {
-    for (const field of section.fields) {
-      map.set(field.id, {
-        sectionId: section.id,
-        sectionTitle: section.title,
-        label: field.label
-      });
-    }
-  }
-  return map;
-}
-function validateReportResponseDetailed(template, data) {
-  if (typeof data !== "object" || data === null) {
-    return {
-      success: false,
-      errors: [
-        {
-          fieldId: "",
-          code: "response.invalid_root",
-          message: "Response must be an object."
-        }
-      ]
-    };
-  }
-  const response = data;
-  const schema = buildResponseSchemaWithConditions(template, response);
-  const fieldMeta = buildFieldMetadataLookup(template);
-  const result = schema.safeParse(response);
-  if (result.success) {
-    const parsed = { ...result.data };
-    for (const section of template.sections) {
-      for (const field of section.fields) {
-        if (field.visibleIf) {
-          const visible = evaluateCondition(field.visibleIf, response);
-          if (!visible) {
-            delete parsed[field.id];
-          }
-        }
-      }
-    }
-    return { success: true, value: parsed };
-  }
-  const errors = [];
-  for (const issue of result.error.issues) {
-    const path = issue.path ?? [];
-    const fieldId = typeof path[0] === "string" ? path[0] : "";
-    const meta = fieldId ? fieldMeta.get(fieldId) : void 0;
-    const code = mapZodIssueToFieldErrorCode(issue);
-    const sectionLabel = meta?.sectionTitle ?? meta?.sectionId;
-    const fieldLabel = meta?.label ?? fieldId;
-    let message;
-    if (meta && sectionLabel && fieldLabel) {
-      message = `Section "${sectionLabel}" \u2192 Field "${fieldLabel}": ${issue.message}`;
-    } else if (fieldLabel) {
-      message = `Field "${fieldLabel}": ${issue.message}`;
-    } else {
-      message = issue.message;
-    }
-    errors.push({
-      fieldId,
-      sectionId: meta?.sectionId,
-      sectionTitle: meta?.sectionTitle,
-      label: meta?.label,
-      code,
-      message,
-      rawIssue: issue
-    });
-  }
-  return { success: false, errors };
-}
-
-// src/diff.ts
-function indexById(items) {
-  const map = {};
-  items.forEach((item, i) => map[item.id] = i);
-  return map;
-}
-function diffObjectProperties(before, after, ignoreKeys = []) {
-  const changes = [];
-  const keys = /* @__PURE__ */ new Set([...Object.keys(before), ...Object.keys(after)]);
-  for (const key of keys) {
-    if (ignoreKeys.includes(key)) continue;
-    const b = before[key];
-    const a = after[key];
-    const changed = Array.isArray(b) && Array.isArray(a) ? JSON.stringify(b) !== JSON.stringify(a) : b !== a;
-    if (changed) {
-      changes.push({ key, before: b, after: a });
-    }
-  }
-  return changes;
-}
-function diffRepeatGroupFields(beforeFields, afterFields, sectionId, groupId) {
-  const empty = {
-    addedSections: [],
-    removedSections: [],
-    reorderedSections: [],
-    modifiedSections: [],
-    addedFields: [],
-    removedFields: [],
-    reorderedFields: [],
-    modifiedFields: [],
-    nestedFieldDiffs: []
-  };
-  const beforeIndex = indexById(beforeFields);
-  const afterIndex = indexById(afterFields);
-  for (const f of afterFields) {
-    if (!(f.id in beforeIndex)) {
-      empty.addedFields.push({ sectionId, fieldId: f.id, index: afterIndex[f.id] });
-    }
-  }
-  for (const f of beforeFields) {
-    if (!(f.id in afterIndex)) {
-      empty.removedFields.push({ sectionId, fieldId: f.id, index: beforeIndex[f.id] });
-    }
-  }
-  for (const f of afterFields) {
-    if (f.id in beforeIndex) {
-      const from = beforeIndex[f.id];
-      const to = afterIndex[f.id];
-      if (from !== to) {
-        empty.reorderedFields.push({
-          sectionId,
-          fieldId: f.id,
-          from,
-          to
-        });
+  for (const f of beforeFields) {
+    if (!(f.id in afterIndex)) {
+      empty.removedFields.push({ sectionId, fieldId: f.id, index: beforeIndex[f.id] });
+    }
+  }
+  for (const f of afterFields) {
+    if (f.id in beforeIndex) {
+      const from = beforeIndex[f.id];
+      const to = afterIndex[f.id];
+      if (from !== to) {
+        empty.reorderedFields.push({
+          sectionId,
+          fieldId: f.id,
+          from,
+          to
+        });
       }
     }
   }
@@ -757,7 +456,7 @@ function diffTemplates(before, after) {
   return diff;
 }
 
-// src/jsonSchema.ts
+// src/template/jsonSchema.ts
 function mapFieldTypeToJSONSchemaCore(field) {
   const common = {
     title: field.label,
@@ -809,9 +508,6 @@ function mapFieldTypeToJSONSchemaCore(field) {
         ...common,
         type: "boolean"
       };
-      if (field.required && !field.requiredIf) {
-        schema.const = true;
-      }
       return schema;
     }
     case "singleSelect": {
@@ -819,7 +515,8 @@ function mapFieldTypeToJSONSchemaCore(field) {
         ...common,
         type: "string"
       };
-      if (Array.isArray(field.options) && field.options.length > 0) {
+      const hasOptions = Array.isArray(field.options) && field.options.length > 0;
+      if (hasOptions && !field.allowOther) {
         schema.enum = field.options;
       }
       return schema;
@@ -847,6 +544,38 @@ function mapFieldTypeToJSONSchemaCore(field) {
       }
       return schema;
     }
+    case "repeatGroup": {
+      const nestedFields = Array.isArray(field.fields) ? field.fields : [];
+      const rowProperties = {};
+      const rowRequired = [];
+      for (const nested of nestedFields) {
+        rowProperties[nested.id] = mapFieldTypeToJSONSchemaCore(
+          nested
+        );
+        if (nested.required === true && !nested.requiredIf && !nested.visibleIf) {
+          rowRequired.push(nested.id);
+        }
+      }
+      const rowSchema = {
+        type: "object",
+        properties: rowProperties,
+        additionalProperties: false
+      };
+      if (rowRequired.length > 0) {
+        rowSchema.required = rowRequired;
+      }
+      const schema = {
+        ...common,
+        type: "array",
+        items: rowSchema,
+        // expose min/max + conditional minIf/maxIf as extensions
+        "x-frt-min": field.min,
+        "x-frt-max": field.max,
+        "x-frt-minIf": field.minIf,
+        "x-frt-maxIf": field.maxIf
+      };
+      return schema;
+    }
     default: {
       return {
         ...common
@@ -879,6 +608,386 @@ function exportJSONSchema(template) {
   }
   return schema;
 }
+
+// src/fields/defaults.ts
+var DEFAULT_FIELD_LABEL = "Untitled question";
+var CORE_FIELD_DEFAULTS = {
+  shortText: {
+    label: DEFAULT_FIELD_LABEL,
+    placeholder: "Short answer text"
+  },
+  longText: {
+    label: DEFAULT_FIELD_LABEL,
+    placeholder: "Long answer text"
+  },
+  number: {
+    label: DEFAULT_FIELD_LABEL,
+    placeholder: "123"
+  },
+  date: {
+    label: DEFAULT_FIELD_LABEL
+  },
+  checkbox: {
+    label: DEFAULT_FIELD_LABEL,
+    placeholder: "Check to confirm"
+  },
+  singleSelect: {
+    label: DEFAULT_FIELD_LABEL,
+    options: ["Option 1", "Option 2", "Option 3"]
+  },
+  multiSelect: {
+    label: DEFAULT_FIELD_LABEL,
+    options: ["Option 1", "Option 2", "Option 3"],
+    allowOther: false
+  },
+  repeatGroup: {
+    // Minimal safe defaults – your builder UI is expected
+    // to configure nested fields + min/max as needed.
+    label: DEFAULT_FIELD_LABEL,
+    fields: []
+    // nested fields go here in the UI layer
+  }
+};
+
+// src/fields/ids.ts
+function createUniqueId(prefix, existing) {
+  const used = new Set(existing);
+  let attempt = used.size + 1;
+  let candidate = `${prefix}-${attempt}`;
+  while (used.has(candidate)) {
+    attempt++;
+    candidate = `${prefix}-${attempt}`;
+  }
+  return candidate;
+}
+
+// src/fields/registry.ts
+var FieldRegistryClass = class {
+  constructor() {
+    this.registry = /* @__PURE__ */ new Map();
+  }
+  /** Register or override a field type. */
+  register(type, entry) {
+    this.registry.set(type, entry);
+  }
+  /** Get registry entry for a field type. */
+  get(type) {
+    return this.registry.get(type);
+  }
+  /** Check if field type is registered. */
+  has(type) {
+    return this.registry.has(type);
+  }
+  /** Return all field types currently registered. */
+  list() {
+    return [...this.registry.keys()];
+  }
+};
+var FieldRegistry = new FieldRegistryClass();
+var CORE_TYPES = [
+  "shortText",
+  "longText",
+  "number",
+  "date",
+  "checkbox",
+  "singleSelect",
+  "multiSelect",
+  "repeatGroup"
+];
+for (const type of CORE_TYPES) {
+  FieldRegistry.register(type, {
+    defaults: CORE_FIELD_DEFAULTS[type]
+    // Core types rely on existing validation logic.
+    // buildResponseSchema is optional — fallback handles it.
+  });
+}
+
+// src/validation/conditions.ts
+function evaluateCondition(condition, response) {
+  if ("equals" in condition) {
+    return Object.entries(condition.equals).every(([key, val]) => {
+      return response[key] === val;
+    });
+  }
+  if ("any" in condition) {
+    return condition.any.some(
+      (sub) => evaluateCondition(sub, response)
+    );
+  }
+  if ("all" in condition) {
+    return condition.all.every(
+      (sub) => evaluateCondition(sub, response)
+    );
+  }
+  if ("not" in condition) {
+    const sub = condition.not;
+    return !evaluateCondition(sub, response);
+  }
+  return false;
+}
+
+// src/validation/responses.ts
+import {
+  z as z2,
+  ZodError
+} from "zod";
+function buildBaseFieldSchema(field) {
+  const isRequired = Boolean(field.required);
+  const registry = FieldRegistry.get(field.type);
+  if (registry?.buildResponseSchema) {
+    return registry.buildResponseSchema(field);
+  }
+  switch (field.type) {
+    case "shortText":
+    case "longText": {
+      let schema = z2.string();
+      if (typeof field.minLength === "number") {
+        schema = schema.min(field.minLength);
+      }
+      if (typeof field.maxLength === "number") {
+        schema = schema.max(field.maxLength);
+      }
+      return isRequired ? schema : schema.optional();
+    }
+    case "number": {
+      let schema = z2.number();
+      if (typeof field.minValue === "number") {
+        schema = schema.min(field.minValue);
+      }
+      if (typeof field.maxValue === "number") {
+        schema = schema.max(field.maxValue);
+      }
+      return isRequired ? schema : schema.optional();
+    }
+    case "date": {
+      let schema = z2.string();
+      return isRequired ? schema : schema.optional();
+    }
+    case "checkbox": {
+      if (isRequired) return z2.literal(true);
+      return z2.boolean().optional();
+    }
+    case "singleSelect": {
+      let schema = z2.string();
+      if (Array.isArray(field.options) && field.options.length > 0) {
+        const allowed = new Set(field.options);
+        schema = schema.refine(
+          (value) => allowed.has(value),
+          "Value must be one of the defined options."
+        );
+      }
+      return isRequired ? schema : schema.optional();
+    }
+    case "multiSelect": {
+      let schema = z2.array(z2.string());
+      if (Array.isArray(field.options) && field.options.length > 0 && !field.allowOther) {
+        const allowed = new Set(field.options);
+        schema = schema.refine(
+          (values) => values.every((value) => allowed.has(value)),
+          "All values must be among the defined options."
+        );
+      }
+      if (typeof field.minSelections === "number") {
+        schema = schema.min(
+          field.minSelections,
+          `Select at least ${field.minSelections} option(s).`
+        );
+      } else if (isRequired) {
+        schema = schema.min(
+          1,
+          "Select at least one option."
+        );
+      }
+      if (typeof field.maxSelections === "number") {
+        schema = schema.max(
+          field.maxSelections,
+          `Select at most ${field.maxSelections} option(s).`
+        );
+      }
+      return isRequired ? schema : schema.optional();
+    }
+    case "repeatGroup": {
+      const nestedFields = Array.isArray(field.fields) ? field.fields : [];
+      const rowShape = {};
+      for (const nested of nestedFields) {
+        rowShape[nested.id] = buildBaseFieldSchema(
+          nested
+        );
+      }
+      let schema = z2.array(z2.object(rowShape));
+      if (typeof field.min === "number") {
+        schema = schema.min(
+          field.min,
+          `Add at least ${field.min} item(s).`
+        );
+      }
+      if (typeof field.max === "number") {
+        schema = schema.max(
+          field.max,
+          `Add at most ${field.max} item(s).`
+        );
+      }
+      return isRequired ? schema : schema.optional();
+    }
+    default: {
+      return z2.any();
+    }
+  }
+}
+function buildConditionalFieldSchema(field, response) {
+  if (field.visibleIf) {
+    const visible = evaluateCondition(field.visibleIf, response);
+    if (!visible) {
+      return z2.any().optional();
+    }
+  }
+  let schema = buildBaseFieldSchema(field);
+  if (field.requiredIf) {
+    const shouldBeRequired = evaluateCondition(field.requiredIf, response);
+    if (shouldBeRequired) {
+      if (schema instanceof z2.ZodOptional) {
+        schema = schema.unwrap();
+      }
+    }
+  }
+  return schema;
+}
+function buildResponseSchemaWithConditions(template, response) {
+  const shape = {};
+  for (const section of template.sections) {
+    for (const field of section.fields) {
+      shape[field.id] = buildConditionalFieldSchema(field, response);
+    }
+  }
+  return z2.object(shape);
+}
+function validateReportResponse(template, data) {
+  if (typeof data !== "object" || data === null) {
+    throw new Error("Response must be an object");
+  }
+  const response = data;
+  const schema = buildResponseSchemaWithConditions(template, response);
+  const parsed = schema.parse(response);
+  for (const section of template.sections) {
+    for (const field of section.fields) {
+      if (field.visibleIf) {
+        const visible = evaluateCondition(field.visibleIf, response);
+        if (!visible) {
+          delete parsed[field.id];
+        }
+      }
+    }
+  }
+  return parsed;
+}
+function mapZodIssueToFieldErrorCode(issue) {
+  switch (issue.code) {
+    case z2.ZodIssueCode.invalid_type:
+      return "field.invalid_type";
+    case z2.ZodIssueCode.too_small:
+      return "field.too_small";
+    case z2.ZodIssueCode.too_big:
+      return "field.too_big";
+    case z2.ZodIssueCode.invalid_enum_value:
+    case z2.ZodIssueCode.invalid_literal:
+      return "field.invalid_option";
+    case z2.ZodIssueCode.custom:
+      return "field.custom";
+    default:
+      return "field.custom";
+  }
+}
+function buildFieldMetadataLookup(template) {
+  const map = /* @__PURE__ */ new Map();
+  for (const section of template.sections) {
+    for (const field of section.fields) {
+      map.set(field.id, {
+        sectionId: section.id,
+        sectionTitle: section.title,
+        label: field.label
+      });
+    }
+  }
+  return map;
+}
+function mapZodIssuesToResponseErrors(template, issues) {
+  const fieldMeta = buildFieldMetadataLookup(template);
+  const errors = [];
+  for (const issue of issues) {
+    const path = issue.path ?? [];
+    const topLevelFieldId = path.find(
+      (p) => typeof p === "string"
+    );
+    const rowIndex = path.find(
+      (p) => typeof p === "number"
+    );
+    const nestedFieldId = path.length >= 3 && typeof path[path.length - 1] === "string" ? path[path.length - 1] : void 0;
+    const fieldId = topLevelFieldId ?? "";
+    const meta = fieldId ? fieldMeta.get(fieldId) : void 0;
+    const code = mapZodIssueToFieldErrorCode(issue);
+    const sectionLabel = meta?.sectionTitle ?? meta?.sectionId;
+    const fieldLabel = meta?.label ?? fieldId;
+    let message;
+    if (rowIndex != null && nestedFieldId && meta && sectionLabel) {
+      message = `Section "${sectionLabel}" \u2192 "${meta.label}" (row ${rowIndex + 1}, field "${nestedFieldId}"): ${issue.message}`;
+    } else if (meta && sectionLabel && fieldLabel) {
+      message = `Section "${sectionLabel}" \u2192 Field "${fieldLabel}": ${issue.message}`;
+    } else if (fieldLabel) {
+      message = `Field "${fieldLabel}": ${issue.message}`;
+    } else {
+      message = issue.message;
+    }
+    errors.push({
+      fieldId,
+      sectionId: meta?.sectionId,
+      sectionTitle: meta?.sectionTitle,
+      label: meta?.label,
+      code,
+      message,
+      rawIssue: issue
+    });
+  }
+  return errors;
+}
+function validateReportResponseDetailed(template, data) {
+  if (typeof data !== "object" || data === null) {
+    return {
+      success: false,
+      errors: [
+        {
+          fieldId: "",
+          code: "response.invalid_root",
+          message: "Response must be an object."
+        }
+      ]
+    };
+  }
+  const response = data;
+  const schema = buildResponseSchemaWithConditions(template, response);
+  const result = schema.safeParse(response);
+  if (result.success) {
+    const parsed = { ...result.data };
+    for (const section of template.sections) {
+      for (const field of section.fields) {
+        if (field.visibleIf) {
+          const visible = evaluateCondition(field.visibleIf, response);
+          if (!visible) {
+            delete parsed[field.id];
+          }
+        }
+      }
+    }
+    return { success: true, value: parsed };
+  }
+  const errors = mapZodIssuesToResponseErrors(template, result.error.issues);
+  return { success: false, errors };
+}
+function explainValidationError(template, error) {
+  if (error instanceof ZodError) {
+    return mapZodIssuesToResponseErrors(template, error.issues);
+  }
+  return null;
+}
 export {
   CORE_FIELD_DEFAULTS,
   Condition,
@@ -895,6 +1004,7 @@ export {
   createUniqueId,
   diffTemplates,
   evaluateCondition,
+  explainValidationError,
   exportJSONSchema,
   migrateLegacySchema,
   normalizeReportTemplateSchema,