@frt-platform/report-core 1.3.0 → 1.5.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

@@ -7,7 +7,9 @@ declare const Condition: z.ZodType<any>;
 type SimpleCondition = z.infer<typeof Condition>;
 declare const RepeatGroupFieldSchema: z.ZodType<any>;
 declare const ReportTemplateFieldSchema: z.ZodType<any>;
-type ReportTemplateField = z.infer<typeof ReportTemplateFieldSchema>;
+type ReportTemplateField = z.infer<typeof ReportTemplateFieldSchema> & {
+    computed?: string;
+};
 declare const ReportTemplateSectionSchema: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
@@ -68,7 +70,25 @@ declare const ReportTemplateSchemaValidator: z.ZodObject<{
 }>;
 type ReportTemplateSchema = z.infer<typeof ReportTemplateSchemaValidator>;
 
-declare function migrateLegacySchema(raw: unknown): unknown;
+/**
+ * Helper for generating a unique id in a *local* namespace, typically in
+ * UI/builders when adding new sections/fields client-side.
+ *
+ * Note:
+ * - This is deliberately simple and deterministic.
+ * - 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;
+
+/**
+ * Migrate a legacy flat { fields: [...] } structure or partially-upgraded
+ * schema into the current { sections: [...] } shape.
+ *
+ * This is intentionally loose: it accepts `unknown` and only normalizes
+ * what we care about. The full Zod validation happens later.
+ */
+declare function migrateLegacySchema(raw: unknown): ReportTemplateSchema | any;
 
 declare function normalizeReportTemplateSchema(schema: ReportTemplateSchema): ReportTemplateSchema;
 declare function parseReportTemplateSchema(raw: unknown): ReportTemplateSchema;
@@ -99,61 +119,55 @@ interface SerializeOptions {
  */
 declare function serializeReportTemplateSchema(schema: ReportTemplateSchema, options?: SerializeOptions): string;
 
+interface SectionPropertyChange {
+    key: string;
+    before: unknown;
+    after: unknown;
+}
+interface ModifiedSection {
+    sectionId: string;
+    changes: SectionPropertyChange[];
+}
+interface ModifiedField {
+    sectionId: string;
+    fieldId: string;
+    changes: SectionPropertyChange[];
+}
+interface SectionAddRemove {
+    sectionId: string;
+    index: number;
+}
+interface SectionReorder {
+    sectionId: string;
+    from: number;
+    to: number;
+}
+interface FieldAddRemove {
+    sectionId: string;
+    fieldId: string;
+    index: number;
+}
+interface FieldReorder {
+    sectionId: string;
+    fieldId: string;
+    from: number;
+    to: number;
+}
+interface NestedFieldDiff {
+    sectionId: string;
+    groupId: string;
+    diffs: TemplateDiff;
+}
 interface TemplateDiff {
-    addedSections: Array<{
-        sectionId: string;
-        index: number;
-    }>;
-    removedSections: Array<{
-        sectionId: string;
-        index: number;
-    }>;
-    reorderedSections: Array<{
-        sectionId: string;
-        from: number;
-        to: number;
-    }>;
-    modifiedSections: Array<{
-        sectionId: string;
-        changes: Array<{
-            key: string;
-            before: any;
-            after: any;
-        }>;
-    }>;
-    addedFields: Array<{
-        sectionId: string;
-        fieldId: string;
-        index: number;
-    }>;
-    removedFields: Array<{
-        sectionId: string;
-        fieldId: string;
-        index: number;
-    }>;
-    reorderedFields: Array<{
-        sectionId: string;
-        fieldId: string;
-        from: number;
-        to: number;
-    }>;
-    modifiedFields: Array<{
-        sectionId: string;
-        fieldId: string;
-        before: Record<string, any>;
-        after: Record<string, any>;
-        changes: Array<{
-            key: string;
-            before: any;
-            after: any;
-        }>;
-    }>;
-    /** NEW: repeatGroup nested diffs */
-    nestedFieldDiffs: Array<{
-        sectionId: string;
-        groupId: string;
-        diffs: TemplateDiff;
-    }>;
+    addedSections: SectionAddRemove[];
+    removedSections: SectionAddRemove[];
+    reorderedSections: SectionReorder[];
+    modifiedSections: ModifiedSection[];
+    addedFields: FieldAddRemove[];
+    removedFields: FieldAddRemove[];
+    reorderedFields: FieldReorder[];
+    modifiedFields: ModifiedField[];
+    nestedFieldDiffs: NestedFieldDiff[];
 }
 declare function diffTemplates(before: ReportTemplateSchema, after: ReportTemplateSchema): TemplateDiff;
 
@@ -192,63 +206,33 @@ interface JSONSchema {
  */
 declare function exportJSONSchema(template: ReportTemplateSchema): JSONSchema;
 
-declare const DEFAULT_FIELD_LABEL = "Untitled question";
-declare const CORE_FIELD_DEFAULTS: Record<ReportTemplateFieldType, Record<string, unknown>>;
-
-declare function createUniqueId(prefix: string, existing: Iterable<string>): string;
-
-/** -------------------------------------------------------------
- * FieldRegistryEntry
- * --------------------------------------------------------------
- * Represents metadata + behavior for a single field type.
- * -------------------------------------------------------------- */
-interface FieldRegistryEntry {
-    /** Default field-level properties merged when creating new fields */
-    defaults?: Record<string, unknown>;
-    /**
-     * Build a Zod schema for validating the *response value* of this field.
-     * If not provided, the core engine falls back to the built-in handler.
-     */
-    buildResponseSchema?: (field: ReportTemplateField) => ZodTypeAny;
-    /**
-     * Optional UI metadata for @frt/report-react
-     * (icon, color, description, grouping, etc.)
-     */
-    ui?: Record<string, any>;
-}
-/** -------------------------------------------------------------
- * FieldRegistry
- * --------------------------------------------------------------
- * Central store of all field types (built-in + custom).
- * -------------------------------------------------------------- */
-declare class FieldRegistryClass {
-    private registry;
-    /** Register or override a field type. */
-    register(type: string, entry: FieldRegistryEntry): void;
-    /** Get registry entry for a field type. */
-    get(type: string): FieldRegistryEntry | undefined;
-    /** Check if field type is registered. */
-    has(type: string): boolean;
-    /** Return all field types currently registered. */
-    list(): string[];
-}
-/** Singleton instance */
-declare const FieldRegistry: FieldRegistryClass;
-
 /**
- * Evaluate a conditional rule against a submitted response object.
+ * Evaluate a SimpleCondition against a flat response object.
  *
- * Supported forms:
- *  { equals: { fieldId: value } }
- *  { any: [cond, cond] }
- *  { all: [cond, cond] }
- *  { not: cond }
+ * Supported structure:
+ * - { equals: { fieldId: value } }
+ * - { any: [cond, cond, ...] }
+ * - { all: [cond, cond, ...] }
+ * - { not: cond }
+ *
+ * Notes:
+ * - We intentionally keep this evaluation shallow and deterministic.
+ * - No special array semantics (e.g. "contains") yet — it's strict equality.
  */
-declare function evaluateCondition(condition: SimpleCondition, response: Record<string, any>): boolean;
+declare function evaluateCondition(condition: SimpleCondition | undefined, response: Record<string, any>): boolean;
 
+/**
+ * Build the base Zod schema for a field, WITHOUT:
+ *  - visibleIf
+ *  - requiredIf
+ *  - computed fields
+ *  - repeatGroup logic
+ *
+ * This is the lowest-level “field → Zod” mapping.
+ * All conditional logic is layered on top in conditionalSchema.ts.
+ */
 declare function buildBaseFieldSchema(field: ReportTemplateField): ZodTypeAny;
-declare function buildResponseSchemaWithConditions(template: ReportTemplateSchema, response: Record<string, any>): 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 {
     /** field id (template-level id) */
@@ -266,6 +250,27 @@ interface ResponseFieldError {
     /** original Zod issue (for debugging / logging) */
     rawIssue?: ZodIssue;
 }
+/**
+ * Helper to turn a thrown ZodError (e.g. from validateReportResponse)
+ * into the same ResponseFieldError[] shape used by
+ * validateReportResponseDetailed.
+ *
+ * Returns null if the error is not a ZodError.
+ */
+declare function explainValidationError(template: ReportTemplateSchema, error: unknown): ResponseFieldError[] | null;
+
+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 is mainly useful for:
+ *   - Static type inference
+ *   - Generic tooling / OpenAPI-style usage
+ */
+declare function buildResponseSchema(template: ReportTemplateSchema): z.ZodObject<Record<string, ZodTypeAny>>;
+declare function validateReportResponse(template: ReportTemplateSchema, data: unknown): Record<string, unknown>;
 /**
  * Validates a response against a template, but instead of throwing,
  * returns a structured error object with:
@@ -282,28 +287,66 @@ declare function validateReportResponseDetailed(template: ReportTemplateSchema,
     success: false;
     errors: ResponseFieldError[];
 };
+
 /**
- * Helper to turn a thrown ZodError (e.g. from validateReportResponse)
- * into the same ResponseFieldError[] shape used by
- * validateReportResponseDetailed.
+ * Extracts the union of all field configs from a template type.
  *
- * Returns null if the error is not a ZodError.
+ * Given:
+ * {
+ *   sections: [
+ *     { fields: [F1, F2] },
+ *     { fields: [F3] }
+ *   ]
+ * }
+ *
+ * → TemplateFieldUnion<TTemplate> = F1 | F2 | F3
  */
-declare function explainValidationError(template: ReportTemplateSchema, error: unknown): ResponseFieldError[] | null;
 type TemplateFieldUnion<TTemplate> = TTemplate extends {
     sections: readonly (infer S)[];
 } ? S extends {
     fields: readonly (infer F)[];
 } ? F : never : never;
+/**
+ * Base value type for a field, ignoring `required`.
+ * This is deliberately simple and only keyed off `type` + `options`.
+ */
 type BaseFieldValue<TField extends {
     type: ReportTemplateFieldType;
     required?: boolean;
     options?: readonly string[] | string[];
-}> = TField["type"] extends "shortText" | "longText" ? string : TField["type"] extends "number" ? number : TField["type"] extends "date" ? string : TField["type"] extends "checkbox" ? boolean : TField["type"] extends "singleSelect" ? (TField["options"] extends readonly (infer O)[] ? O : TField["options"] extends (infer O)[] ? O : string) : TField["type"] extends "multiSelect" ? (TField["options"] extends readonly (infer O)[] ? O[] : TField["options"] extends (infer O)[] ? O[] : string[]) : TField["type"] extends "repeatGroup" ? Array<Record<string, unknown>> : unknown;
+}> = TField["type"] extends "shortText" | "longText" ? string : TField["type"] extends "number" ? number : TField["type"] extends "date" ? string : TField["type"] extends "checkbox" ? boolean : TField["type"] extends "singleSelect" ? TField["options"] extends readonly (infer O)[] ? O : TField["options"] extends (infer O)[] ? O : string : TField["type"] extends "multiSelect" ? TField["options"] extends readonly (infer O)[] ? O[] : TField["options"] extends (infer O)[] ? O[] : string[] : TField["type"] extends "repeatGroup" ? Array<Record<string, unknown>> : unknown;
+/**
+ * Wrap base value in optionality depending on `required`.
+ */
 type FieldResponseValue<TField extends {
     type: ReportTemplateFieldType;
     required?: boolean;
 }> = TField["required"] extends true ? BaseFieldValue<TField> : BaseFieldValue<TField> | undefined;
+/**
+ * Infer the response shape from a *const* template definition.
+ *
+ * Example:
+ *
+ *   export const myTemplate = {
+ *     version: 1,
+ *     sections: [
+ *       {
+ *         id: "main",
+ *         fields: [
+ *           { id: "title", type: "shortText", required: true },
+ *           { id: "tags", type: "multiSelect", options: ["A", "B"] },
+ *         ]
+ *       }
+ *     ]
+ *   } as const;
+ *
+ *   type MyResponse = InferResponse<typeof myTemplate>;
+ *
+ *   // {
+ *   //   title: string;
+ *   //   tags?: ("A" | "B")[];
+ *   // }
+ */
 type InferResponse<TTemplate extends {
     sections: readonly {
         fields: readonly {
@@ -317,4 +360,59 @@ 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 };
+/** -------------------------------------------------------------
+ * FieldRegistryEntry
+ * --------------------------------------------------------------
+ * Represents metadata + behavior for a single field type.
+ * -------------------------------------------------------------- */
+interface FieldRegistryEntry {
+    /** Default field-level properties merged when creating new fields */
+    defaults?: Record<string, unknown>;
+    /**
+     * Build a Zod schema for validating the *response value* of this field.
+     * If not provided, the core engine falls back to the built-in handler.
+     */
+    buildResponseSchema?: (field: ReportTemplateField) => ZodTypeAny;
+    /**
+     * Optional UI metadata for @frt/report-react
+     * (icon, color, description, grouping, etc.)
+     */
+    ui?: Record<string, any>;
+}
+/** -------------------------------------------------------------
+ * FieldRegistry
+ * --------------------------------------------------------------
+ * Central store of all field types (built-in + custom).
+ * -------------------------------------------------------------- */
+declare class FieldRegistryClass {
+    private registry;
+    /** Register or override a field type. */
+    register(type: string, entry: FieldRegistryEntry): void;
+    /** Get registry entry for a field type. */
+    get(type: string): FieldRegistryEntry | undefined;
+    /** Check if field type is registered. */
+    has(type: string): boolean;
+    /** Return all field types currently registered. */
+    list(): string[];
+}
+/** Singleton instance */
+declare const FieldRegistry: FieldRegistryClass;
+
+/**
+ * Shared default label used for all core field types.
+ */
+declare const DEFAULT_FIELD_LABEL = "Untitled field";
+/**
+ * Shape of the core defaults map.
+ * We keep values loose (Record<string, any>) because different field
+ * types have different shapes, and these are just "seed" objects.
+ */
+type CoreFieldDefaults = Record<ReportTemplateFieldType, Record<string, any>>;
+/**
+ * Default configs for every core field type.
+ * These are *not* full fields (no id), just starter values that
+ * template builders / UIs can merge into new fields.
+ */
+declare const CORE_FIELD_DEFAULTS: CoreFieldDefaults;
+
+export { CORE_FIELD_DEFAULTS, Condition, type CoreFieldDefaults, DEFAULT_FIELD_LABEL, type FieldAddRemove, type FieldErrorCode, FieldRegistry, type FieldRegistryEntry, type FieldReorder, type InferResponse, type JSONSchema, type ModifiedField, type ModifiedSection, type NestedFieldDiff, REPORT_TEMPLATE_FIELD_TYPES, REPORT_TEMPLATE_VERSION, RepeatGroupFieldSchema, type ReportTemplateField, ReportTemplateFieldSchema, type ReportTemplateFieldType, type ReportTemplateSchema, ReportTemplateSchemaValidator, type ReportTemplateSection, ReportTemplateSectionSchema, type ResponseFieldError, type SectionAddRemove, type SectionPropertyChange, type SectionReorder, type SerializeOptions, type SimpleCondition, type TemplateDiff, buildBaseFieldSchema, buildResponseSchema, buildResponseSchemaWithConditions, createUniqueId, diffTemplates, evaluateCondition, explainValidationError, exportJSONSchema, migrateLegacySchema, normalizeReportTemplateSchema, parseReportTemplateSchema, parseReportTemplateSchemaFromString, serializeReportTemplateSchema, validateReportResponse, validateReportResponseDetailed };