@frt-platform/report-core 1.1.0 → 1.2.0

package/README.md

@@ -1,14 +1,23 @@
 # @frt/report-core
 
-Core engine for building, validating, and migrating **report templates**.
+Core engine for building, validating, and migrating **report templates** – plus validating **report responses**.
 
-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 (`buildResponseSchema`, `validateReportResponse`)
+* **Template diffing** (`diffTemplates`) to compare template versions
+* **Type-level response inference** (`InferResponse`) for fully typed responses
 
 It’s the core that powers a flexible incident/report builder, but it’s generic enough to be reused in any app.
 
@@ -25,7 +34,7 @@ yarn add @frt/report-core zod
 
 # pnpm
 pnpm add @frt/report-core zod
-````
+```
 
 `zod` is a peer dependency and is used for schema validation & parsing.
 
@@ -81,7 +90,7 @@ const templateJson: ReportTemplateSchema = {
           type: "longText",
           label: "What happened?",
           required: true,
-          minLength: 10
+          minLength: 10,
         },
         {
           id: "status",
@@ -89,22 +98,22 @@ 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
+  normalizeReportTemplateSchema,
 } from "@frt/report-core";
 
 const raw = /* from DB, file, API, etc. */ templateJson;
@@ -147,6 +156,119 @@ try {
 
 ---
 
+## Validating report responses
+
+Once you have a template, you can validate **user-submitted responses** against it.
+
+### Runtime schema for responses
+
+```ts
+import {
+  buildResponseSchema,
+  validateReportResponse,
+} from "@frt/report-core";
+
+const template = /* a valid ReportTemplateSchema */ normalized;
+
+// Build a Zod schema for responses
+const responseSchema = buildResponseSchema(template);
+
+// Example response object
+const responseData = {
+  summary: "Student slipped in the hallway, no serious injuries.",
+  status: "Resolved",
+};
+
+// Validate (throws ZodError on failure)
+const safeResponse = responseSchema.parse(responseData);
+
+// Or use the convenience helper:
+const safeResponse2 = validateReportResponse(template, responseData);
+```
+
+`buildResponseSchema` respects:
+
+* `required` flags
+* `minLength` / `maxLength` (short/long text)
+* `minValue` / `maxValue` (numbers)
+* `minSelections` / `maxSelections` (multiSelect)
+* `options` (singleSelect + multiSelect)
+* `checkbox` semantics (required checkbox must be `true`)
+
+---
+
+## 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/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,7 +277,7 @@ The package includes core defaults for each field type (no UI, no icons):
 import {
   CORE_FIELD_DEFAULTS,
   DEFAULT_FIELD_LABEL,
-  type ReportTemplateFieldType
+  type ReportTemplateFieldType,
 } from "@frt/report-core";
 
 function createDefaultField(type: ReportTemplateFieldType) {
@@ -164,7 +286,7 @@ function createDefaultField(type: ReportTemplateFieldType) {
     id: "your-id-here",
     type,
     label: (defaults.label as string) ?? DEFAULT_FIELD_LABEL,
-    ...defaults
+    ...defaults,
   };
 }
 
@@ -203,7 +325,7 @@ you can pass them through the migration pipeline:
 ```ts
 import {
   migrateLegacySchema,
-  parseReportTemplateSchema
+  parseReportTemplateSchema,
 } from "@frt/report-core";
 
 const legacy = {
@@ -211,8 +333,8 @@ const legacy = {
   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 +354,47 @@ 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 simple diff utility:
+
+```ts
+import { diffTemplates } from "@frt/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.fieldChanges);
+```
+
+`diff.fieldChanges` contains entries like:
+
+```ts
+{
+  type: "modified",
+  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
+
+---
+
 ## API Overview
 
 ### Types
@@ -241,7 +404,8 @@ import type {
   ReportTemplateSchema,
   ReportTemplateSection,
   ReportTemplateField,
-  ReportTemplateFieldType
+  ReportTemplateFieldType,
+  InferResponse,
 } from "@frt/report-core";
 ```
 
@@ -249,6 +413,7 @@ import type {
 * `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,7 +422,7 @@ import {
   REPORT_TEMPLATE_VERSION,
   REPORT_TEMPLATE_FIELD_TYPES,
   DEFAULT_FIELD_LABEL,
-  CORE_FIELD_DEFAULTS
+  CORE_FIELD_DEFAULTS,
 } from "@frt/report-core";
 ```
 
@@ -276,7 +441,7 @@ import {
   parseReportTemplateSchema,
   parseReportTemplateSchemaFromString,
   normalizeReportTemplateSchema,
-  serializeReportTemplateSchema
+  serializeReportTemplateSchema,
 } from "@frt/report-core";
 ```
 
@@ -299,10 +464,20 @@ import { migrateLegacySchema } from "@frt/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 {
+  buildResponseSchema,
+  validateReportResponse,
+  type InferResponse,
+} from "@frt/report-core";
+```
+
+### Template diffing
+
+```ts
+import { diffTemplates } from "@frt/report-core";
 ```
 
 ---
@@ -321,23 +496,29 @@ 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
 
 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 `buildResponseSchema` to validate and normalize responses
 
 ---
 
@@ -349,15 +530,19 @@ Things you might add on top (in a separate package, e.g. `@frt/report-react`):
 
   * 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
+* Conditional logic:
+
+  * `visibleIf`
+  * `requiredIf`
 * Multi-language labels & descriptions
 
-The core stays simple: schema + validation + migration.
+The core stays simple: **schema + validation + migration + response validation + diffing**.
 
 ---