@frt-platform/report-core 1.3.0 → 1.4.0

package/README.md

@@ -9,7 +9,7 @@ This package is:
 * 🔒 **Safe by design (Zod-based)**
 * 🧱 **The foundation of the FRT incident & reporting platform**
 
-It contains **no React**, **no database code**, and **no styling**.
+It contains **no React**, **no database code**, and **no styling**.  
 You can use it in **Node**, **Next.js**, **backend services**, or custom form engines.
 
 ---
@@ -49,6 +49,7 @@ You can use it in **Node**, **Next.js**, **backend services**, or custom form en
 ### 🔥 Validation Engine
 
 * Build response schema dynamically with conditions
+* DX helper: `buildResponseSchema(template)` (no response needed)
 * Throwing API: `validateReportResponse()`
 * Non-throwing API: `validateReportResponseDetailed()`
 * Rich `ResponseFieldError` objects with:
@@ -63,7 +64,8 @@ You can use it in **Node**, **Next.js**, **backend services**, or custom form en
 
 * Legacy format migration (`fields → sections`)
 * Automatic ID normalization & uniqueness enforcement
-* Safe parsing from JSON or raw objects
+* Stable `"lowercase_with_underscores"`-style IDs
+* Fallback IDs for missing values: `section_1`, `field_1`, etc.
 
 ### 🔍 Schema Diffing
 
@@ -81,7 +83,7 @@ Detect:
 
   * `x-frt-visibleIf`
   * `x-frt-requiredIf`
-  * repeatGroup min/max
+  * `x-frt-minIf` / `x-frt-maxIf` for repeatGroup
   * placeholders
 * Useful for OpenAPI, Postman, or other backend runtimes.
 
@@ -92,6 +94,7 @@ Extend the system at runtime:
 * Add custom types (`richText`, `fileUpload`, etc.)
 * Override validation logic
 * Provide metadata for UI packages
+* Unknown/unregistered field types safely fall back to `z.any()` so they never break the core engine.
 
 ### 🧬 Type Inference
 
@@ -99,7 +102,7 @@ Get a fully typed response type from a template:
 
 ```ts
 type MyResponse = InferResponse<typeof template>;
-```
+````
 
 ### 🧾 Serialization Helpers
 
@@ -127,6 +130,63 @@ npm install @frt-platform/report-core zod
 
 ---
 
+# 🧹 Parsing & Normalization
+
+The core exposes helpers for safely **parsing**, **migrating**, and **normalizing** templates.
+
+```ts
+import {
+  parseReportTemplateSchema,
+  parseReportTemplateSchemaFromString,
+} from "@frt-platform/report-core";
+
+// From a raw JS object (e.g. loaded from DB, file, etc.)
+const template = parseReportTemplateSchema(rawTemplateObject);
+
+// From a JSON string
+const templateFromString = parseReportTemplateSchemaFromString(jsonString);
+```
+
+Under the hood, `parseReportTemplateSchema` does:
+
+1. **Legacy migration**
+
+   * Accepts both the new `{ sections: [...] }` format and legacy flat:
+
+     ```ts
+     {
+       version: 1,
+       fields: [ /* ... */ ]
+     }
+     ```
+
+   * Legacy `fields` are automatically wrapped into a single `section_1`.
+
+2. **Schema validation**
+
+   * Uses a Zod validator for `ReportTemplateSchema` to ensure the template is structurally valid.
+
+3. **Normalization**
+
+   * Section and field IDs are normalized to **lowercase** with spaces → underscores:
+
+     * `"My Field!"` → `"my_field"`
+
+   * Invalid characters are stripped (only `[a-z0-9_-]` are kept).
+
+   * IDs are made **unique per namespace** by appending `-1`, `-2`, … as needed:
+
+     * `my_field`, `my_field-1`, `my_field-2`, …
+
+   * Missing IDs get deterministic fallbacks:
+
+     * Sections: `section_1`, `section_2`, …
+     * Fields: `field_1`, `field_2`, …
+
+This makes templates safe to store, diff, and round-trip in a stable way.
+
+---
+
 # 🚀 Quickstart
 
 ## 1. Define a template
@@ -209,7 +269,8 @@ Produces:
     sectionTitle: "General Info",
     label: "Incident title",
     code: "field.too_small",
-    message: 'Section "General Info" → Field "Incident title": String must contain at least 1 character(s).'
+    message:
+      'Section "General Info" → Field "Incident title": String must contain at least 1 character(s).'
   }
 ]
 ```
@@ -257,6 +318,29 @@ Response shape:
 injured: Array<{ name: string; injury?: string }>;
 ```
 
+### 📝 repeatGroup behavior & limitations
+
+* **Base constraints**
+
+  * `min` / `max` are always enforced on the row array.
+  * Each row is an object keyed by nested field IDs.
+
+* **Conditional `minIf` / `maxIf`**
+
+  * If `minIf` / `maxIf` are present, they are evaluated against the **current response**.
+  * When the condition is `true`, the conditional value overrides the static `min` / `max` for that validation pass.
+  * When the condition is `false`, the engine falls back to the static `min` / `max` (if any).
+
+* **Conditional logic inside rows**
+
+  * Nested fields in a repeatGroup support the same `visibleIf` / `requiredIf` semantics as top-level fields.
+  * Hidden nested fields are treated as **optional** and are **stripped** from the parsed response, just like hidden top-level fields.
+  * For now, row-level conditions see the **full response object**, not just the row. This matches top-level behavior and keeps the logic model simple.
+
+* **JSON Schema export**
+
+  * repeatGroup constraints and conditions are exported via `x-frt-*` vendor extensions (e.g. `x-frt-minIf`, `x-frt-maxIf`, `x-frt-visibleIf`, `x-frt-requiredIf`), so you can mirror this behavior in other runtimes.
+
 ---
 
 # 🧩 Field Registry (Custom Types)
@@ -281,6 +365,8 @@ Now templates may include fields like:
 { id: "body", type: "richText", label: "Report body" }
 ```
 
+If a template uses a field type that is **not** registered and not one of the built-in core types, the engine safely falls back to `z.any()` so unknown types never crash validation.
+
 ---
 
 # 🧾 JSON Schema Export
@@ -372,7 +458,7 @@ const json = serializeReportTemplateSchema(template, {
 });
 ```
 
-Useful for deterministic output in Git.
+Useful for deterministic output in Git and stable diffs across environments.
 
 ---
 
@@ -386,11 +472,11 @@ Useful for deterministic output in Git.
 * Field Registry
 * Error helpers
 * Serialization features
+* Parsing & normalization helpers
 
 ### Phase 2 — Advanced Field System (IN PROGRESS)
 
-* Repeat group conditional rules (`minIf` / `maxIf`)
-* Conditional logic inside group rows
+* Richer repeatGroup UX
 * Computed fields (design)
 * RichText / FileUpload via registry
 
@@ -411,4 +497,4 @@ Useful for deterministic output in Git.
 
 # 📄 License
 
-MIT — feel free to use, extend, or contribute.
+MIT — feel free to use, extend, or contribute.

package/dist/index.d.mts

@@ -195,6 +195,13 @@ declare function exportJSONSchema(template: ReportTemplateSchema): JSONSchema;
 declare const DEFAULT_FIELD_LABEL = "Untitled question";
 declare const CORE_FIELD_DEFAULTS: Record<ReportTemplateFieldType, Record<string, unknown>>;
 
+/**
+ * Helper for generating a unique id in a *local* namespace, typically in
+ * UI/builders when adding new sections/fields client-side.
+ *
+ * Note: Core template normalization uses its own normalizeId/ensureUniqueId
+ * logic so that persisted IDs stay stable and backwards compatible.
+ */
 declare function createUniqueId(prefix: string, existing: Iterable<string>): string;
 
 /** -------------------------------------------------------------
@@ -248,6 +255,21 @@ declare function evaluateCondition(condition: SimpleCondition, response: Record<
 
 declare function buildBaseFieldSchema(field: ReportTemplateField): ZodTypeAny;
 declare function buildResponseSchemaWithConditions(template: ReportTemplateSchema, response: Record<string, any>): z.ZodObject<Record<string, ZodTypeAny>>;
+/**
+ * Build a Zod object schema for a template *without* needing a response object.
+ *
+ * Notes:
+ * - All conditional logic is evaluated against an empty response `{}`.
+ * - This means:
+ *   - `visibleIf` / `requiredIf` that depend on other fields will typically
+ *     evaluate to false.
+ *
+ * This is mainly useful for:
+ * - Static type inference
+ * - Generic tooling / OpenAPI style usage
+ * - Situations where you just want the overall "shape" of a response.
+ */
+declare function buildResponseSchema(template: ReportTemplateSchema): z.ZodObject<Record<string, ZodTypeAny>>;
 declare function validateReportResponse(template: ReportTemplateSchema, data: unknown): Record<string, unknown>;
 type FieldErrorCode = "response.invalid_root" | "field.required" | "field.invalid_type" | "field.too_small" | "field.too_big" | "field.invalid_option" | "field.custom";
 interface ResponseFieldError {
@@ -317,4 +339,4 @@ type InferResponse<TTemplate extends {
     [F in TemplateFieldUnion<TTemplate> as F["id"]]: FieldResponseValue<F>;
 };
 
-export { CORE_FIELD_DEFAULTS, Condition, DEFAULT_FIELD_LABEL, type FieldErrorCode, FieldRegistry, type FieldRegistryEntry, type InferResponse, type JSONSchema, REPORT_TEMPLATE_FIELD_TYPES, REPORT_TEMPLATE_VERSION, RepeatGroupFieldSchema, type ReportTemplateField, ReportTemplateFieldSchema, type ReportTemplateFieldType, type ReportTemplateSchema, ReportTemplateSchemaValidator, type ReportTemplateSection, ReportTemplateSectionSchema, type ResponseFieldError, type SerializeOptions, type SimpleCondition, type TemplateDiff, buildBaseFieldSchema, buildResponseSchemaWithConditions, createUniqueId, diffTemplates, evaluateCondition, explainValidationError, exportJSONSchema, migrateLegacySchema, normalizeReportTemplateSchema, parseReportTemplateSchema, parseReportTemplateSchemaFromString, serializeReportTemplateSchema, validateReportResponse, validateReportResponseDetailed };
+export { CORE_FIELD_DEFAULTS, Condition, DEFAULT_FIELD_LABEL, type FieldErrorCode, FieldRegistry, type FieldRegistryEntry, type InferResponse, type JSONSchema, REPORT_TEMPLATE_FIELD_TYPES, REPORT_TEMPLATE_VERSION, RepeatGroupFieldSchema, type ReportTemplateField, ReportTemplateFieldSchema, type ReportTemplateFieldType, type ReportTemplateSchema, ReportTemplateSchemaValidator, type ReportTemplateSection, ReportTemplateSectionSchema, type ResponseFieldError, type SerializeOptions, type SimpleCondition, type TemplateDiff, buildBaseFieldSchema, buildResponseSchema, buildResponseSchemaWithConditions, createUniqueId, diffTemplates, evaluateCondition, explainValidationError, exportJSONSchema, migrateLegacySchema, normalizeReportTemplateSchema, parseReportTemplateSchema, parseReportTemplateSchemaFromString, serializeReportTemplateSchema, validateReportResponse, validateReportResponseDetailed };

package/dist/index.d.ts

@@ -195,6 +195,13 @@ declare function exportJSONSchema(template: ReportTemplateSchema): JSONSchema;
 declare const DEFAULT_FIELD_LABEL = "Untitled question";
 declare const CORE_FIELD_DEFAULTS: Record<ReportTemplateFieldType, Record<string, unknown>>;
 
+/**
+ * Helper for generating a unique id in a *local* namespace, typically in
+ * UI/builders when adding new sections/fields client-side.
+ *
+ * Note: Core template normalization uses its own normalizeId/ensureUniqueId
+ * logic so that persisted IDs stay stable and backwards compatible.
+ */
 declare function createUniqueId(prefix: string, existing: Iterable<string>): string;
 
 /** -------------------------------------------------------------
@@ -248,6 +255,21 @@ declare function evaluateCondition(condition: SimpleCondition, response: Record<
 
 declare function buildBaseFieldSchema(field: ReportTemplateField): ZodTypeAny;
 declare function buildResponseSchemaWithConditions(template: ReportTemplateSchema, response: Record<string, any>): z.ZodObject<Record<string, ZodTypeAny>>;
+/**
+ * Build a Zod object schema for a template *without* needing a response object.
+ *
+ * Notes:
+ * - All conditional logic is evaluated against an empty response `{}`.
+ * - This means:
+ *   - `visibleIf` / `requiredIf` that depend on other fields will typically
+ *     evaluate to false.
+ *
+ * This is mainly useful for:
+ * - Static type inference
+ * - Generic tooling / OpenAPI style usage
+ * - Situations where you just want the overall "shape" of a response.
+ */
+declare function buildResponseSchema(template: ReportTemplateSchema): z.ZodObject<Record<string, ZodTypeAny>>;
 declare function validateReportResponse(template: ReportTemplateSchema, data: unknown): Record<string, unknown>;
 type FieldErrorCode = "response.invalid_root" | "field.required" | "field.invalid_type" | "field.too_small" | "field.too_big" | "field.invalid_option" | "field.custom";
 interface ResponseFieldError {
@@ -317,4 +339,4 @@ type InferResponse<TTemplate extends {
     [F in TemplateFieldUnion<TTemplate> as F["id"]]: FieldResponseValue<F>;
 };
 
-export { CORE_FIELD_DEFAULTS, Condition, DEFAULT_FIELD_LABEL, type FieldErrorCode, FieldRegistry, type FieldRegistryEntry, type InferResponse, type JSONSchema, REPORT_TEMPLATE_FIELD_TYPES, REPORT_TEMPLATE_VERSION, RepeatGroupFieldSchema, type ReportTemplateField, ReportTemplateFieldSchema, type ReportTemplateFieldType, type ReportTemplateSchema, ReportTemplateSchemaValidator, type ReportTemplateSection, ReportTemplateSectionSchema, type ResponseFieldError, type SerializeOptions, type SimpleCondition, type TemplateDiff, buildBaseFieldSchema, buildResponseSchemaWithConditions, createUniqueId, diffTemplates, evaluateCondition, explainValidationError, exportJSONSchema, migrateLegacySchema, normalizeReportTemplateSchema, parseReportTemplateSchema, parseReportTemplateSchemaFromString, serializeReportTemplateSchema, validateReportResponse, validateReportResponseDetailed };
+export { CORE_FIELD_DEFAULTS, Condition, DEFAULT_FIELD_LABEL, type FieldErrorCode, FieldRegistry, type FieldRegistryEntry, type InferResponse, type JSONSchema, REPORT_TEMPLATE_FIELD_TYPES, REPORT_TEMPLATE_VERSION, RepeatGroupFieldSchema, type ReportTemplateField, ReportTemplateFieldSchema, type ReportTemplateFieldType, type ReportTemplateSchema, ReportTemplateSchemaValidator, type ReportTemplateSection, ReportTemplateSectionSchema, type ResponseFieldError, type SerializeOptions, type SimpleCondition, type TemplateDiff, buildBaseFieldSchema, buildResponseSchema, buildResponseSchemaWithConditions, createUniqueId, diffTemplates, evaluateCondition, explainValidationError, exportJSONSchema, migrateLegacySchema, normalizeReportTemplateSchema, parseReportTemplateSchema, parseReportTemplateSchemaFromString, serializeReportTemplateSchema, validateReportResponse, validateReportResponseDetailed };

package/dist/index.js

@@ -31,6 +31,7 @@ __export(index_exports, {
   ReportTemplateSchemaValidator: () => ReportTemplateSchemaValidator,
   ReportTemplateSectionSchema: () => ReportTemplateSectionSchema,
   buildBaseFieldSchema: () => buildBaseFieldSchema,
+  buildResponseSchema: () => buildResponseSchema,
   buildResponseSchemaWithConditions: () => buildResponseSchemaWithConditions,
   createUniqueId: () => createUniqueId,
   diffTemplates: () => diffTemplates,
@@ -880,6 +881,41 @@ function buildBaseFieldSchema(field) {
     }
   }
 }
+function buildRepeatGroupSchemaWithConditions(field, response) {
+  const isRequired = Boolean(field.required);
+  const nestedFields = Array.isArray(field.fields) ? field.fields : [];
+  const rowShape = {};
+  for (const nested of nestedFields) {
+    rowShape[nested.id] = buildConditionalFieldSchema(
+      nested,
+      response
+    );
+  }
+  let schema = import_zod2.z.array(import_zod2.z.object(rowShape));
+  const hasStaticMin = typeof field.min === "number";
+  const hasMinIf = Boolean(field.minIf);
+  const minIfCondition = field.minIf;
+  const shouldEnforceMin = hasStaticMin && (!hasMinIf || evaluateCondition(minIfCondition, response));
+  if (shouldEnforceMin) {
+    const minValue = field.min;
+    schema = schema.min(
+      minValue,
+      `Add at least ${minValue} item(s).`
+    );
+  }
+  const hasStaticMax = typeof field.max === "number";
+  const hasMaxIf = Boolean(field.maxIf);
+  const maxIfCondition = field.maxIf;
+  const shouldEnforceMax = hasStaticMax && (!hasMaxIf || evaluateCondition(maxIfCondition, response));
+  if (shouldEnforceMax) {
+    const maxValue = field.max;
+    schema = schema.max(
+      maxValue,
+      `Add at most ${maxValue} item(s).`
+    );
+  }
+  return isRequired ? schema : schema.optional();
+}
 function buildConditionalFieldSchema(field, response) {
   if (field.visibleIf) {
     const visible = evaluateCondition(field.visibleIf, response);
@@ -887,7 +923,12 @@ function buildConditionalFieldSchema(field, response) {
       return import_zod2.z.any().optional();
     }
   }
-  let schema = buildBaseFieldSchema(field);
+  let schema;
+  if (field.type === "repeatGroup") {
+    schema = buildRepeatGroupSchemaWithConditions(field, response);
+  } else {
+    schema = buildBaseFieldSchema(field);
+  }
   if (field.requiredIf) {
     const shouldBeRequired = evaluateCondition(field.requiredIf, response);
     if (shouldBeRequired) {
@@ -907,6 +948,9 @@ function buildResponseSchemaWithConditions(template, response) {
   }
   return import_zod2.z.object(shape);
 }
+function buildResponseSchema(template) {
+  return buildResponseSchemaWithConditions(template, {});
+}
 function validateReportResponse(template, data) {
   if (typeof data !== "object" || data === null) {
     throw new Error("Response must be an object");
@@ -1047,6 +1091,7 @@ function explainValidationError(template, error) {
   ReportTemplateSchemaValidator,
   ReportTemplateSectionSchema,
   buildBaseFieldSchema,
+  buildResponseSchema,
   buildResponseSchemaWithConditions,
   createUniqueId,
   diffTemplates,

package/dist/index.mjs

@@ -834,6 +834,41 @@ function buildBaseFieldSchema(field) {
     }
   }
 }
+function buildRepeatGroupSchemaWithConditions(field, response) {
+  const isRequired = Boolean(field.required);
+  const nestedFields = Array.isArray(field.fields) ? field.fields : [];
+  const rowShape = {};
+  for (const nested of nestedFields) {
+    rowShape[nested.id] = buildConditionalFieldSchema(
+      nested,
+      response
+    );
+  }
+  let schema = z2.array(z2.object(rowShape));
+  const hasStaticMin = typeof field.min === "number";
+  const hasMinIf = Boolean(field.minIf);
+  const minIfCondition = field.minIf;
+  const shouldEnforceMin = hasStaticMin && (!hasMinIf || evaluateCondition(minIfCondition, response));
+  if (shouldEnforceMin) {
+    const minValue = field.min;
+    schema = schema.min(
+      minValue,
+      `Add at least ${minValue} item(s).`
+    );
+  }
+  const hasStaticMax = typeof field.max === "number";
+  const hasMaxIf = Boolean(field.maxIf);
+  const maxIfCondition = field.maxIf;
+  const shouldEnforceMax = hasStaticMax && (!hasMaxIf || evaluateCondition(maxIfCondition, response));
+  if (shouldEnforceMax) {
+    const maxValue = field.max;
+    schema = schema.max(
+      maxValue,
+      `Add at most ${maxValue} item(s).`
+    );
+  }
+  return isRequired ? schema : schema.optional();
+}
 function buildConditionalFieldSchema(field, response) {
   if (field.visibleIf) {
     const visible = evaluateCondition(field.visibleIf, response);
@@ -841,7 +876,12 @@ function buildConditionalFieldSchema(field, response) {
       return z2.any().optional();
     }
   }
-  let schema = buildBaseFieldSchema(field);
+  let schema;
+  if (field.type === "repeatGroup") {
+    schema = buildRepeatGroupSchemaWithConditions(field, response);
+  } else {
+    schema = buildBaseFieldSchema(field);
+  }
   if (field.requiredIf) {
     const shouldBeRequired = evaluateCondition(field.requiredIf, response);
     if (shouldBeRequired) {
@@ -861,6 +901,9 @@ function buildResponseSchemaWithConditions(template, response) {
   }
   return z2.object(shape);
 }
+function buildResponseSchema(template) {
+  return buildResponseSchemaWithConditions(template, {});
+}
 function validateReportResponse(template, data) {
   if (typeof data !== "object" || data === null) {
     throw new Error("Response must be an object");
@@ -1000,6 +1043,7 @@ export {
   ReportTemplateSchemaValidator,
   ReportTemplateSectionSchema,
   buildBaseFieldSchema,
+  buildResponseSchema,
   buildResponseSchemaWithConditions,
   createUniqueId,
   diffTemplates,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frt-platform/report-core",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Core report template engine: schema, validation, normalization, and migration.",
   "author": "Sebastian Mostert",
   "license": "MIT",