@frt-platform/report-core 1.2.0 → 1.2.1

package/README.md

@@ -1,6 +1,6 @@
-# @frt/report-core
+# `@frt-platform/report-core`
 
-Core engine for building, validating, and migrating **report templates** – plus validating **report responses**.
+Core engine for building, validating, and migrating **report templates** – plus validating **report responses** and exporting **JSON Schema**.
 
 This package is:
 
@@ -15,9 +15,12 @@ It gives you:
 * **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
+* **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.
 
@@ -27,13 +30,13 @@ 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.
@@ -47,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);
 // [
@@ -62,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
@@ -74,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,
@@ -114,14 +121,14 @@ Use the helpers to safely parse and normalize unknown input:
 import {
   parseReportTemplateSchema,
   normalizeReportTemplateSchema,
-} from "@frt/report-core";
+} 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);
@@ -131,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.
@@ -144,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);
@@ -160,33 +167,23 @@ try {
 
 Once you have a template, you can validate **user-submitted responses** against it.
 
-### Runtime schema for responses
+### Runtime validation
 
 ```ts
-import {
-  buildResponseSchema,
-  validateReportResponse,
-} from "@frt/report-core";
+import { validateReportResponse } from "@frt-platform/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);
+const safeResponse = validateReportResponse(template, responseData);
 ```
 
-`buildResponseSchema` respects:
+`validateReportResponse` respects:
 
 * `required` flags
 * `minLength` / `maxLength` (short/long text)
@@ -194,6 +191,49 @@ const safeResponse2 = validateReportResponse(template, responseData);
 * `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.
 
 ---
 
@@ -202,7 +242,7 @@ const safeResponse2 = validateReportResponse(template, responseData);
 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";
+import type { InferResponse } from "@frt-platform/report-core";
 
 const incidentTemplate = {
   version: 1,
@@ -278,7 +318,7 @@ import {
   CORE_FIELD_DEFAULTS,
   DEFAULT_FIELD_LABEL,
   type ReportTemplateFieldType,
-} from "@frt/report-core";
+} from "@frt-platform/report-core";
 
 function createDefaultField(type: ReportTemplateFieldType) {
   const defaults = CORE_FIELD_DEFAULTS[type] ?? {};
@@ -293,16 +333,63 @@ function createDefaultField(type: ReportTemplateFieldType) {
 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);
@@ -326,7 +413,7 @@ you can pass them through the migration pipeline:
 import {
   migrateLegacySchema,
   parseReportTemplateSchema,
-} from "@frt/report-core";
+} from "@frt-platform/report-core";
 
 const legacy = {
   title: "Old template",
@@ -356,10 +443,10 @@ 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:
+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/report-core";
+import { diffTemplates } from "@frt-platform/report-core";
 
 const beforeTemplate = /* old template */;
 const afterTemplate = /* updated template */;
@@ -368,14 +455,19 @@ const diff = diffTemplates(beforeTemplate, afterTemplate);
 
 console.log(diff.addedSections);
 console.log(diff.removedSections);
-console.log(diff.fieldChanges);
+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.fieldChanges` contains entries like:
+`diff.modifiedFields` contains entries like:
 
 ```ts
 {
-  type: "modified",
   sectionId: "section-overview",
   fieldId: "summary",
   before: { label: "What happened?", required: false, ... },
@@ -392,6 +484,42 @@ 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`.
 
 ---
 
@@ -406,7 +534,7 @@ import type {
   ReportTemplateField,
   ReportTemplateFieldType,
   InferResponse,
-} from "@frt/report-core";
+} from "@frt-platform/report-core";
 ```
 
 * `ReportTemplateFieldType` – union of all field type strings
@@ -423,7 +551,7 @@ import {
   REPORT_TEMPLATE_FIELD_TYPES,
   DEFAULT_FIELD_LABEL,
   CORE_FIELD_DEFAULTS,
-} from "@frt/report-core";
+} from "@frt-platform/report-core";
 ```
 
 * `REPORT_TEMPLATE_VERSION: number`
@@ -442,13 +570,13 @@ import {
   parseReportTemplateSchemaFromString,
   normalizeReportTemplateSchema,
   serializeReportTemplateSchema,
-} from "@frt/report-core";
+} 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) {
@@ -459,7 +587,7 @@ 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.
@@ -468,16 +596,28 @@ Takes `unknown` legacy input and returns a shape better suited for current schem
 
 ```ts
 import {
-  buildResponseSchema,
   validateReportResponse,
+  buildResponseSchemaWithConditions,
   type InferResponse,
-} from "@frt/report-core";
+} from "@frt-platform/report-core";
 ```
 
 ### Template diffing
 
 ```ts
-import { diffTemplates } from "@frt/report-core";
+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";
 ```
 
 ---
@@ -497,6 +637,7 @@ This package is intentionally minimal. You can layer it into:
   * 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:
 
@@ -518,13 +659,14 @@ Typical pattern in a full stack app:
 
    * Load templates from DB
    * Use them to render dynamic forms
-   * Use `buildResponseSchema` to validate and normalize responses
+   * 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:
 
@@ -536,16 +678,18 @@ Things you might add on top (in a separate package, e.g. `@frt/report-react`):
   * File uploads
   * Signature pads
   * Matrix / grid fields
-* Conditional logic:
+  * Fully-featured `repeatGroup` UI & runtime
+* Richer conditional logic:
 
   * `visibleIf`
   * `requiredIf`
+  * multi-step branching
 * Multi-language labels & descriptions
 
-The core stays simple: **schema + validation + migration + response validation + diffing**.
+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.

package/package.json

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