@frt-platform/report-core 1.1.0 → 1.2.1

package/README.md

@@ -1,14 +1,26 @@
-# @frt/report-core
+# `@frt-platform/report-core`
 
-Core engine for building, validating, and migrating **report templates**.
+Core engine for building, validating, and migrating **report templates** – plus validating **report responses** and exporting **JSON Schema**.
 
-This package is framework-agnostic, React-free, and storage-agnostic. It gives you:
+This package is:
 
-- A **typed schema** for report templates (templates → sections → fields)
-- **Zod-based validation** and parsing from unknown / JSON input
-- **Legacy schema migration** (flat `fields` → `sections`, old type names, etc.)
-- **Normalization** helpers to ensure safe IDs & consistent structure
-- **Field defaults** and **ID utilities** you can use to build your own UI
+* **Framework-agnostic** (no React)
+* **Storage-agnostic** (no DB assumptions)
+* **Runtime-safe** (Zod-based validation)
+
+It gives you:
+
+* A **typed schema** for report templates (templates → sections → fields)
+* **Zod-based validation** and parsing from unknown / JSON input
+* **Legacy schema migration** (flat `fields` → `sections`, old type names, etc.)
+* **Normalization** helpers to ensure safe IDs & consistent structure
+* **Field defaults** and **ID utilities** you can use to build your own UI
+* **Response validation** based on templates (`validateReportResponse`)
+* **Conditional logic** for fields (`visibleIf` / `requiredIf`)
+* **Template diffing** (`diffTemplates`) to compare template versions (including ordering)
+* **Type-level response inference** (`InferResponse`) for fully typed responses
+* **Field registry** (`FieldRegistry`) for custom / extensible field types
+* **JSON Schema export** (`exportJSONSchema`) for integration with OpenAPI / external validators
 
 It’s the core that powers a flexible incident/report builder, but it’s generic enough to be reused in any app.
 
@@ -18,14 +30,14 @@ It’s the core that powers a flexible incident/report builder, but it’s gener
 
 ```bash
 # npm
-npm install @frt/report-core zod
+npm install @frt-platform/report-core zod
 
 # yarn
-yarn add @frt/report-core zod
+yarn add @frt-platform/report-core zod
 
 # pnpm
-pnpm add @frt/report-core zod
-````
+pnpm add @frt-platform/report-core zod
+```
 
 `zod` is a peer dependency and is used for schema validation & parsing.
 
@@ -38,11 +50,12 @@ The core model looks like this:
 * A **template** contains multiple **sections**
 * A **section** contains multiple **fields**
 * A **field** has a `type` (short text, long text, number, select, etc.) and optional constraints
+* Fields can have **conditional logic** (`visibleIf`, `requiredIf`)
 
 Supported field types:
 
 ```ts
-import { REPORT_TEMPLATE_FIELD_TYPES } from "@frt/report-core";
+import { REPORT_TEMPLATE_FIELD_TYPES } from "@frt-platform/report-core";
 
 console.log(REPORT_TEMPLATE_FIELD_TYPES);
 // [
@@ -53,9 +66,12 @@ console.log(REPORT_TEMPLATE_FIELD_TYPES);
 //   "checkbox",
 //   "singleSelect",
 //   "multiSelect",
+//   "repeatGroup", // reserved for repeating groups / fieldsets
 // ]
 ```
 
+> `repeatGroup` is reserved for repeating fieldsets (e.g. multiple injured people); the core schema knows about it and provides defaults, and the full runtime semantics can be layered on top in your app/React package.
+
 ---
 
 ## Quick Start
@@ -65,7 +81,7 @@ console.log(REPORT_TEMPLATE_FIELD_TYPES);
 You can define templates statically or load them from DB / API:
 
 ```ts
-import type { ReportTemplateSchema } from "@frt/report-core";
+import type { ReportTemplateSchema } from "@frt-platform/report-core";
 
 const templateJson: ReportTemplateSchema = {
   version: 1,
@@ -81,7 +97,7 @@ const templateJson: ReportTemplateSchema = {
           type: "longText",
           label: "What happened?",
           required: true,
-          minLength: 10
+          minLength: 10,
         },
         {
           id: "status",
@@ -89,30 +105,30 @@ const templateJson: ReportTemplateSchema = {
           label: "Incident status",
           required: true,
           options: ["Pending review", "Resolved", "Escalated"],
-          defaultValue: "Resolved"
-        }
-      ]
-    }
-  ]
+          defaultValue: "Resolved",
+        },
+      ],
+    },
+  ],
 };
 ```
 
-### 2. Validate and normalize it
+### 2. Validate and normalize the template
 
 Use the helpers to safely parse and normalize unknown input:
 
 ```ts
 import {
   parseReportTemplateSchema,
-  normalizeReportTemplateSchema
-} from "@frt/report-core";
+  normalizeReportTemplateSchema,
+} from "@frt-platform/report-core";
 
 const raw = /* from DB, file, API, etc. */ templateJson;
 
 // 1) parse + validate (throws on invalid input)
 const parsed = parseReportTemplateSchema(raw);
 
-// 2) optional extra normalization step (IDs, trimming, etc.)
+// 2) optional extra normalization step (IDs, trimming, de-duplication, etc.)
 const normalized = normalizeReportTemplateSchema(parsed);
 
 console.log(normalized.sections[0].fields[0].id);
@@ -122,7 +138,7 @@ console.log(normalized.sections[0].fields[0].id);
 ### 3. Serialize for storage
 
 ```ts
-import { serializeReportTemplateSchema } from "@frt/report-core";
+import { serializeReportTemplateSchema } from "@frt-platform/report-core";
 
 const jsonString = serializeReportTemplateSchema(normalized);
 // ready to store in DB, file, etc.
@@ -135,7 +151,7 @@ const jsonString = serializeReportTemplateSchema(normalized);
 If you have a JSON string (e.g. from a form textarea):
 
 ```ts
-import { parseReportTemplateSchemaFromString } from "@frt/report-core";
+import { parseReportTemplateSchemaFromString } from "@frt-platform/report-core";
 
 try {
   const template = parseReportTemplateSchemaFromString(userInputString);
@@ -147,6 +163,152 @@ try {
 
 ---
 
+## Validating report responses
+
+Once you have a template, you can validate **user-submitted responses** against it.
+
+### Runtime validation
+
+```ts
+import { validateReportResponse } from "@frt-platform/report-core";
+
+const template = /* a valid ReportTemplateSchema */ normalized;
+
+const responseData = {
+  summary: "Student slipped in the hallway, no serious injuries.",
+  status: "Resolved",
+};
+
+// Validate (throws ZodError on failure)
+const safeResponse = validateReportResponse(template, responseData);
+```
+
+`validateReportResponse` respects:
+
+* `required` flags
+* `minLength` / `maxLength` (short/long text)
+* `minValue` / `maxValue` (numbers)
+* `minSelections` / `maxSelections` (multiSelect)
+* `options` (singleSelect + multiSelect)
+* `checkbox` semantics (required checkbox must be `true`)
+* **Conditional logic**:
+
+  * `visibleIf`: if false, the field is treated as invisible and removed from the parsed output
+  * `requiredIf`: if true, the field is treated as required for this specific response
+
+You can still build a raw schema yourself using the conditional builder:
+
+```ts
+import { buildResponseSchemaWithConditions } from "@frt-platform/report-core";
+
+const responseSchema = buildResponseSchemaWithConditions(template, responseData);
+const safeResponse = responseSchema.parse(responseData);
+```
+
+---
+
+## Conditional logic (`visibleIf` / `requiredIf`)
+
+Fields can declare conditions that refer to other field values.
+
+Example:
+
+```json
+{
+  "id": "injury_details",
+  "type": "longText",
+  "label": "Describe the injury",
+  "visibleIf": { "equals": { "injured": true } },
+  "requiredIf": { "equals": { "severity": "High" } }
+}
+```
+
+Supported condition shapes:
+
+* `{"equals": { "fieldId": value } }`
+* `{"any": [cond1, cond2, ...] }`
+* `{"all": [cond1, cond2, ...] }`
+* `{"not": cond }`
+
+At runtime:
+
+* If `visibleIf` is **false** → field is treated as **invisible**, becomes optional, and is stripped from the validated response.
+* If `requiredIf` is **true** → field is treated as **required** for that specific response.
+
+---
+
+## Type-level response inference (`InferResponse`)
+
+If you define templates statically (`as const`), you can get a fully-typed response type from the template:
+
+```ts
+import type { InferResponse } from "@frt-platform/report-core";
+
+const incidentTemplate = {
+  version: 1,
+  sections: [
+    {
+      id: "section-overview",
+      fields: [
+        {
+          id: "summary",
+          type: "longText",
+          label: "What happened?",
+          required: true,
+          minLength: 10,
+        },
+        {
+          id: "status",
+          type: "singleSelect",
+          label: "Status",
+          required: true,
+          options: ["Pending", "Resolved", "Escalated"] as const,
+        },
+        {
+          id: "follow_up_date",
+          type: "date",
+          label: "Follow-up date",
+        },
+        {
+          id: "tags",
+          type: "multiSelect",
+          label: "Tags",
+          options: ["Safety", "Medical", "Security"] as const,
+        },
+        {
+          id: "confirmed",
+          type: "checkbox",
+          label: "I confirm this report is accurate",
+          required: true,
+        },
+      ],
+    },
+  ],
+} as const;
+
+type IncidentResponse = InferResponse<typeof incidentTemplate>;
+```
+
+`IncidentResponse` will be inferred as:
+
+```ts
+type IncidentResponse = {
+  summary: string; // required
+  status: "Pending" | "Resolved" | "Escalated"; // required
+  follow_up_date?: string; // optional
+  tags?: ("Safety" | "Medical" | "Security")[]; // optional
+  confirmed: boolean; // required checkbox
+};
+```
+
+This is extremely useful for:
+
+* API handlers (`(body: IncidentResponse) => { ... }`)
+* DB layers that store `data` blobs
+* Frontend forms with type-safe state
+
+---
+
 ## Using field defaults
 
 The package includes core defaults for each field type (no UI, no icons):
@@ -155,8 +317,8 @@ The package includes core defaults for each field type (no UI, no icons):
 import {
   CORE_FIELD_DEFAULTS,
   DEFAULT_FIELD_LABEL,
-  type ReportTemplateFieldType
-} from "@frt/report-core";
+  type ReportTemplateFieldType,
+} from "@frt-platform/report-core";
 
 function createDefaultField(type: ReportTemplateFieldType) {
   const defaults = CORE_FIELD_DEFAULTS[type] ?? {};
@@ -164,23 +326,70 @@ function createDefaultField(type: ReportTemplateFieldType) {
     id: "your-id-here",
     type,
     label: (defaults.label as string) ?? DEFAULT_FIELD_LABEL,
-    ...defaults
+    ...defaults,
   };
 }
 
 const field = createDefaultField("shortText");
 ```
 
+`CORE_FIELD_DEFAULTS` includes basic defaults for:
+
+* `shortText`, `longText`, `number`, `date`, `checkbox`, `singleSelect`, `multiSelect`
+* `repeatGroup` (with an empty `fields` array; your builder populates nested fields)
+
 This is especially useful in a form builder UI when the user adds a new field of a given type.
 
 ---
 
+## Field Registry (`FieldRegistry`)
+
+You can register **custom field types** or override core types at runtime:
+
+```ts
+import { FieldRegistry } from "@frt-platform/report-core";
+import { z } from "zod";
+
+// Simple example: a "richText" field that behaves like a string
+FieldRegistry.register("richText", {
+  defaults: {
+    label: "Details",
+    placeholder: "Write here...",
+  },
+  buildResponseSchema: (field) => {
+    let schema = z.string();
+
+    if (typeof field.minLength === "number") {
+      schema = schema.min(field.minLength);
+    }
+    if (typeof field.maxLength === "number") {
+      schema = schema.max(field.maxLength);
+    }
+
+    return field.required ? schema : schema.optional();
+  },
+});
+```
+
+At validation time, `validateReportResponse` and `buildBaseFieldSchema` will:
+
+1. Check the registry for a custom handler.
+2. Use the built-in fallback if none is registered.
+
+Use this for:
+
+* App-specific field types (e.g. `fileUpload`, `signature`, `mapLocation`)
+* Tenant-specific extensions in a multi-tenant platform
+* Gradually introducing new field behaviors without changing the core package
+
+---
+
 ## Generating unique IDs
 
 The core package exposes a generic `createUniqueId` helper:
 
 ```ts
-import { createUniqueId } from "@frt/report-core";
+import { createUniqueId } from "@frt-platform/report-core";
 
 const existingSectionIds = ["section-1", "section-2"];
 const newId = createUniqueId("section", existingSectionIds);
@@ -203,16 +412,16 @@ you can pass them through the migration pipeline:
 ```ts
 import {
   migrateLegacySchema,
-  parseReportTemplateSchema
-} from "@frt/report-core";
+  parseReportTemplateSchema,
+} from "@frt-platform/report-core";
 
 const legacy = {
   title: "Old template",
   description: "Using flat fields",
   fields: [
     { id: "summary", type: "textarea", label: "Summary" },
-    { id: "status", type: "dropdown", label: "Status", options: ["Open", "Closed"] }
-  ]
+    { id: "status", type: "dropdown", label: "Status", options: ["Open", "Closed"] },
+  ],
 };
 
 const migrated = migrateLegacySchema(legacy);
@@ -232,6 +441,88 @@ const parsed = ReportTemplateSchemaValidator.parse(migrated);
 
 ---
 
+## Diffing templates
+
+When you version templates (e.g. editing in a UI), you might want to see what changed between versions. The core exposes a diff utility:
+
+```ts
+import { diffTemplates } from "@frt-platform/report-core";
+
+const beforeTemplate = /* old template */;
+const afterTemplate = /* updated template */;
+
+const diff = diffTemplates(beforeTemplate, afterTemplate);
+
+console.log(diff.addedSections);
+console.log(diff.removedSections);
+console.log(diff.reorderedSections);
+console.log(diff.modifiedSections);
+
+console.log(diff.addedFields);
+console.log(diff.removedFields);
+console.log(diff.reorderedFields);
+console.log(diff.modifiedFields);
+```
+
+`diff.modifiedFields` contains entries like:
+
+```ts
+{
+  sectionId: "section-overview",
+  fieldId: "summary",
+  before: { label: "What happened?", required: false, ... },
+  after: { label: "What happened exactly?", required: true, ... },
+  changes: [
+    { key: "label", before: "What happened?", after: "What happened exactly?" },
+    { key: "required", before: false, after: true },
+  ],
+}
+```
+
+Use this for:
+
+* “Changes” tabs in your UI
+* Migration & compatibility warnings
+* Audit trails
+* Showing ordered changes (section/field reorder is explicitly tracked)
+
+---
+
+## JSON Schema export
+
+You can export a template as a **JSON Schema** object for use with OpenAPI, Swagger, Postman, or other runtimes that don’t speak TypeScript/Zod.
+
+```ts
+import { exportJSONSchema } from "@frt-platform/report-core";
+
+const jsonSchema = exportJSONSchema(template);
+```
+
+Shape (simplified):
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "summary": { "type": "string", "minLength": 10 },
+    "status": { "type": "string", "enum": ["Pending", "Resolved", "Escalated"] }
+  },
+  "required": ["summary", "status"],
+  "additionalProperties": false,
+  "x-frt-templateTitle": "Incident follow-up",
+  "x-frt-version": 1
+}
+```
+
+Key points:
+
+* String/number/boolean/array mapping matches the runtime validation semantics.
+* `required` only includes **unconditionally required** fields (no `visibleIf` / `requiredIf`), but we expose conditional logic as vendor extensions.
+* Extra metadata is available under `x-frt-*` keys, e.g. `x-frt-placeholder`, `x-frt-dataClassification`, `x-frt-visibleIf`, `x-frt-requiredIf`.
+
+---
+
 ## API Overview
 
 ### Types
@@ -241,14 +532,16 @@ import type {
   ReportTemplateSchema,
   ReportTemplateSection,
   ReportTemplateField,
-  ReportTemplateFieldType
-} from "@frt/report-core";
+  ReportTemplateFieldType,
+  InferResponse,
+} from "@frt-platform/report-core";
 ```
 
 * `ReportTemplateFieldType` – union of all field type strings
 * `ReportTemplateField` – one question/field in a section
 * `ReportTemplateSection` – a logical grouping of fields
 * `ReportTemplateSchema` – full template
+* `InferResponse<TTemplate>` – builds a typed response object from a static template
 
 ### Constants
 
@@ -257,8 +550,8 @@ import {
   REPORT_TEMPLATE_VERSION,
   REPORT_TEMPLATE_FIELD_TYPES,
   DEFAULT_FIELD_LABEL,
-  CORE_FIELD_DEFAULTS
-} from "@frt/report-core";
+  CORE_FIELD_DEFAULTS,
+} from "@frt-platform/report-core";
 ```
 
 * `REPORT_TEMPLATE_VERSION: number`
@@ -276,14 +569,14 @@ import {
   parseReportTemplateSchema,
   parseReportTemplateSchemaFromString,
   normalizeReportTemplateSchema,
-  serializeReportTemplateSchema
-} from "@frt/report-core";
+  serializeReportTemplateSchema,
+} from "@frt-platform/report-core";
 ```
 
 Use the Zod schemas directly if you want:
 
 ```ts
-import { ReportTemplateSchemaValidator } from "@frt/report-core";
+import { ReportTemplateSchemaValidator } from "@frt-platform/report-core";
 
 const result = ReportTemplateSchemaValidator.safeParse(raw);
 if (!result.success) {
@@ -294,15 +587,37 @@ if (!result.success) {
 ### Migration
 
 ```ts
-import { migrateLegacySchema } from "@frt/report-core";
+import { migrateLegacySchema } from "@frt-platform/report-core";
 ```
 
 Takes `unknown` legacy input and returns a shape better suited for current schema validation.
 
-### Utilities
+### Response validation
 
 ```ts
-import { createUniqueId } from "@frt/report-core";
+import {
+  validateReportResponse,
+  buildResponseSchemaWithConditions,
+  type InferResponse,
+} from "@frt-platform/report-core";
+```
+
+### Template diffing
+
+```ts
+import { diffTemplates } from "@frt-platform/report-core";
+```
+
+### JSON Schema export
+
+```ts
+import { exportJSONSchema } from "@frt-platform/report-core";
+```
+
+### Field registry
+
+```ts
+import { FieldRegistry } from "@frt-platform/report-core";
 ```
 
 ---
@@ -321,46 +636,60 @@ This package is intentionally minimal. You can layer it into:
   * Validating templates on save
   * Migrating old template shapes
   * Ensuring consistent data before persisting to a DB
+  * Validating report responses before saving them
+  * Serving JSON Schema to other services
 
 Typical pattern in a full stack app:
 
-1. **Frontend**:
+1. **Frontend**
 
    * Build a visual editor for templates
    * Send template JSON to server
 
-2. **Backend**:
+2. **Backend**
 
-   * `parseReportTemplateSchema` to validate
+   * `parseReportTemplateSchema` to validate templates
    * Store `ReportTemplateSchema` JSON in your DB (e.g. Mongo via Prisma)
+   * On response submission:
 
-3. **Runtime**:
+     * Load template from DB
+     * `validateReportResponse(template, data)` before insert
+
+3. **Runtime**
 
    * Load templates from DB
-   * Use them to render dynamic forms and validate responses (you can build a separate response schema per field, if you want).
+   * Use them to render dynamic forms
+   * Use `validateReportResponse` / `buildResponseSchemaWithConditions` to validate and normalize responses
+   * Use `exportJSONSchema` for interoperability with other stacks
 
 ---
 
 ## Roadmap / Extensions (ideas)
 
-Things you might add on top (in a separate package, e.g. `@frt/report-react`):
+Things you might add on top (in a separate package, e.g. `@frt-platform/report-react`):
 
 * React components for:
 
   * Template builder UI
   * Field editors/renderers (short text, selects, etc.)
-* Response schemas built from templates
+  * Auto-generated `<ReportForm />` that consumes a template
 * More advanced field types:
 
   * File uploads
   * Signature pads
   * Matrix / grid fields
+  * Fully-featured `repeatGroup` UI & runtime
+* Richer conditional logic:
+
+  * `visibleIf`
+  * `requiredIf`
+  * multi-step branching
 * Multi-language labels & descriptions
 
-The core stays simple: schema + validation + migration.
+The core stays simple: **schema + validation + conditional logic + migration + diffing + registry + JSON Schema export**.
 
 ---
 
 ## License
 
-MIT – use it in your projects, commercial or not. Contributions welcome.
+MIT – use it in your projects, commercial or not. Contributions welcome.