@frt-platform/report-core 1.2.0 → 1.3.0

package/README.md

@@ -1,551 +1,414 @@
-# @frt/report-core
+# `@frt-platform/report-core`
 
-Core engine for building, validating, and migrating **report templates** – plus validating **report responses**.
+Core engine for defining, validating, migrating, diffing, and serializing **dynamic report templates**.
 
 This package is:
 
-* **Framework-agnostic** (no React)
-* **Storage-agnostic** (no DB assumptions)
-* **Runtime-safe** (Zod-based validation)
+* 🧠 **Framework-agnostic**
+* 🧩 **UI-agnostic**
+* 🔒 **Safe by design (Zod-based)**
+* 🧱 **The foundation of the FRT incident & reporting platform**
 
-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.
+It contains **no React**, **no database code**, and **no styling**.
+You can use it in **Node**, **Next.js**, **backend services**, or custom form engines.
 
 ---
 
-## Installation
-
-```bash
-# npm
-npm install @frt/report-core zod
+# ✨ Features
 
-# yarn
-yarn add @frt/report-core zod
+### 📄 Template Schema
 
-# pnpm
-pnpm add @frt/report-core zod
-```
+* Sections → fields
+* Field IDs, labels, descriptions, placeholders
+* Built-in field types:
 
-`zod` is a peer dependency and is used for schema validation & parsing.
+  * `shortText`, `longText`
+  * `number`
+  * `date`
+  * `checkbox`
+  * `singleSelect`, `multiSelect`
+  * `repeatGroup` (nested fieldsets)
 
----
+### 🎛 Field Constraints
 
-## Concepts
+* min/max length (`shortText`, `longText`)
+* min/max value (`number`)
+* min/max selections (`multiSelect`)
+* allowed options
+* checkbox required semantics
+* default values
 
-The core model looks like this:
+### 🔀 Conditional Logic
 
-* 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
+* `visibleIf`
+* `requiredIf`
+* Supports:
+  `equals`, `any`, `all`, `not`
+* Fully integrated into validation.
 
-Supported field types:
+### 🔥 Validation Engine
 
-```ts
-import { REPORT_TEMPLATE_FIELD_TYPES } from "@frt/report-core";
-
-console.log(REPORT_TEMPLATE_FIELD_TYPES);
-// [
-//   "shortText",
-//   "longText",
-//   "number",
-//   "date",
-//   "checkbox",
-//   "singleSelect",
-//   "multiSelect",
-// ]
-```
+* Build response schema dynamically with conditions
+* Throwing API: `validateReportResponse()`
+* Non-throwing API: `validateReportResponseDetailed()`
+* Rich `ResponseFieldError` objects with:
 
----
+  * section title
+  * field label
+  * error code
+  * full message
+  * nested repeatGroup row context
 
-## Quick Start
+### 🔄 Template Migration & Normalization
 
-### 1. Define a template in JSON
+* Legacy format migration (`fields → sections`)
+* Automatic ID normalization & uniqueness enforcement
+* Safe parsing from JSON or raw objects
 
-You can define templates statically or load them from DB / API:
+### 🔍 Schema Diffing
 
-```ts
-import type { ReportTemplateSchema } from "@frt/report-core";
+Detect:
 
-const templateJson: ReportTemplateSchema = {
-  version: 1,
-  title: "Incident follow-up",
-  description: "Collect a quick summary after an incident has been resolved.",
-  sections: [
-    {
-      id: "section-overview",
-      title: "Incident overview",
-      fields: [
-        {
-          id: "summary",
-          type: "longText",
-          label: "What happened?",
-          required: true,
-          minLength: 10,
-        },
-        {
-          id: "status",
-          type: "singleSelect",
-          label: "Incident status",
-          required: true,
-          options: ["Pending review", "Resolved", "Escalated"],
-          defaultValue: "Resolved",
-        },
-      ],
-    },
-  ],
-};
-```
+* Added / removed / reordered sections
+* Added / removed / reordered fields
+* Modified fields
+* Nested diffs inside repeat groups
 
-### 2. Validate and normalize the template
+### 📦 JSON Schema Export
 
-Use the helpers to safely parse and normalize unknown input:
+* Export a template as a valid JSON Schema (2020-12 draft)
+* Includes vendor extensions:
 
-```ts
-import {
-  parseReportTemplateSchema,
-  normalizeReportTemplateSchema,
-} from "@frt/report-core";
+  * `x-frt-visibleIf`
+  * `x-frt-requiredIf`
+  * repeatGroup min/max
+  * placeholders
+* Useful for OpenAPI, Postman, or other backend runtimes.
 
-const raw = /* from DB, file, API, etc. */ templateJson;
+### 🏗 Field Registry
 
-// 1) parse + validate (throws on invalid input)
-const parsed = parseReportTemplateSchema(raw);
+Extend the system at runtime:
 
-// 2) optional extra normalization step (IDs, trimming, etc.)
-const normalized = normalizeReportTemplateSchema(parsed);
+* Add custom types (`richText`, `fileUpload`, etc.)
+* Override validation logic
+* Provide metadata for UI packages
 
-console.log(normalized.sections[0].fields[0].id);
-// always a non-empty, safe identifier
-```
+### 🧬 Type Inference
 
-### 3. Serialize for storage
+Get a fully typed response type from a template:
 
 ```ts
-import { serializeReportTemplateSchema } from "@frt/report-core";
-
-const jsonString = serializeReportTemplateSchema(normalized);
-// ready to store in DB, file, etc.
+type MyResponse = InferResponse<typeof template>;
 ```
 
----
+### 🧾 Serialization Helpers
 
-## Parsing from a JSON string
-
-If you have a JSON string (e.g. from a form textarea):
+Deterministic JSON output with sorting options:
 
 ```ts
-import { parseReportTemplateSchemaFromString } from "@frt/report-core";
-
-try {
-  const template = parseReportTemplateSchemaFromString(userInputString);
-  // valid template here
-} catch (err) {
-  // invalid JSON or schema – show error to user
-}
+serializeReportTemplateSchema(template, {
+  pretty: true,
+  sortSectionsById: true,
+  sortFieldsById: true,
+});
 ```
 
----
-
-## 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;
+Perfect for Git diffs and storage.
 
-// 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);
+# 📦 Installation
 
-// Or use the convenience helper:
-const safeResponse2 = validateReportResponse(template, responseData);
+```bash
+npm install @frt-platform/report-core zod
 ```
 
-`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`)
+`zod` is a peer dependency.
 
 ---
 
-## Type-level response inference (`InferResponse`)
+# 🚀 Quickstart
 
-If you define templates statically (`as const`), you can get a fully-typed response type from the template:
+## 1. Define a template
 
 ```ts
-import type { InferResponse } from "@frt/report-core";
+import type { ReportTemplateSchema } from "@frt-platform/report-core";
 
-const incidentTemplate = {
+const template: ReportTemplateSchema = {
   version: 1,
   sections: [
     {
-      id: "section-overview",
+      id: "general",
+      title: "General Info",
       fields: [
         {
-          id: "summary",
-          type: "longText",
-          label: "What happened?",
+          id: "title",
+          type: "shortText",
+          label: "Incident title",
           required: true,
-          minLength: 10,
         },
         {
-          id: "status",
+          id: "severity",
           type: "singleSelect",
-          label: "Status",
+          label: "Severity",
           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,
+          options: ["Low", "Medium", "High"],
         },
         {
-          id: "confirmed",
-          type: "checkbox",
-          label: "I confirm this report is accurate",
-          required: true,
+          id: "details",
+          type: "longText",
+          label: "Details",
+          minLength: 10,
         },
       ],
     },
   ],
-} 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):
-
-```ts
-import {
-  CORE_FIELD_DEFAULTS,
-  DEFAULT_FIELD_LABEL,
-  type ReportTemplateFieldType,
-} from "@frt/report-core";
-
-function createDefaultField(type: ReportTemplateFieldType) {
-  const defaults = CORE_FIELD_DEFAULTS[type] ?? {};
-  return {
-    id: "your-id-here",
-    type,
-    label: (defaults.label as string) ?? DEFAULT_FIELD_LABEL,
-    ...defaults,
-  };
-}
-
-const field = createDefaultField("shortText");
-```
-
-This is especially useful in a form builder UI when the user adds a new field of a given type.
-
 ---
 
-## Generating unique IDs
-
-The core package exposes a generic `createUniqueId` helper:
+## 2. Validate a response (throwing API)
 
 ```ts
-import { createUniqueId } from "@frt/report-core";
+import { validateReportResponse } from "@frt-platform/report-core";
 
-const existingSectionIds = ["section-1", "section-2"];
-const newId = createUniqueId("section", existingSectionIds);
-// "section-3" (or the next available)
+const parsed = validateReportResponse(template, {
+  title: "Broken fire alarm",
+  severity: "High",
+  details: "Triggered after smoke test",
+});
 ```
 
-You can use this for both section and field IDs when building templates dynamically.
+If invalid → throws a ZodError.
 
 ---
 
-## Legacy schema migration
-
-If you had older templates that:
-
-* Used a flat `fields` array instead of `sections`, or
-* Used older field type names (`text`, `textarea`, `dropdown`, `multiselect`, …)
-
-you can pass them through the migration pipeline:
+## 3. Validate without throwing (UI-friendly)
 
 ```ts
-import {
-  migrateLegacySchema,
-  parseReportTemplateSchema,
-} from "@frt/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"] },
-  ],
-};
+import { validateReportResponseDetailed } from "@frt-platform/report-core";
 
-const migrated = migrateLegacySchema(legacy);
-const parsed = parseReportTemplateSchema(migrated);
+const result = validateReportResponseDetailed(template, {
+  title: "",
+  severity: "High",
+});
 
-console.log(parsed.sections.length); // 1
-console.log(parsed.sections[0].fields[0].type); // "longText"
+if (!result.success) {
+  console.log(result.errors);
+}
 ```
 
-You don’t normally need to call `migrateLegacySchema` yourself – `parseReportTemplateSchema` already does:
+Produces:
 
 ```ts
-// internally:
-const migrated = migrateLegacySchema(raw);
-const parsed = ReportTemplateSchemaValidator.parse(migrated);
+[
+  {
+    fieldId: "title",
+    sectionId: "general",
+    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).'
+  }
+]
 ```
 
 ---
 
-## 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:
+# 🔀 Conditional Logic Example
 
 ```ts
-import { diffTemplates } from "@frt/report-core";
+{
+  id: "follow_up_notes",
+  type: "longText",
+  label: "Follow-up notes",
+  visibleIf: { equals: { follow_up_required: true } },
+  requiredIf: { equals: { follow_up_required: true } },
+}
+```
 
-const beforeTemplate = /* old template */;
-const afterTemplate = /* updated template */;
+Behavior:
 
-const diff = diffTemplates(beforeTemplate, afterTemplate);
+* If `follow_up_required = false` → field is **hidden** and **ignored**
+* If `true` → field becomes **required**
 
-console.log(diff.addedSections);
-console.log(diff.removedSections);
-console.log(diff.fieldChanges);
-```
+---
 
-`diff.fieldChanges` contains entries like:
+# 🔁 Repeat Group Example
 
 ```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 },
-  ],
+  id: "injured",
+  type: "repeatGroup",
+  label: "Injured people",
+  min: 1,
+  max: 5,
+  fields: [
+    { id: "name", type: "shortText", label: "Name", required: true },
+    { id: "injury", type: "longText", label: "Injury description" }
+  ]
 }
 ```
 
-Use this for:
+Response shape:
 
-* “Changes” tabs in your UI
-* Migration & compatibility warnings
-* Audit trails
+```ts
+injured: Array<{ name: string; injury?: string }>;
+```
 
 ---
 
-## API Overview
-
-### Types
+# 🧩 Field Registry (Custom Types)
 
 ```ts
-import type {
-  ReportTemplateSchema,
-  ReportTemplateSection,
-  ReportTemplateField,
-  ReportTemplateFieldType,
-  InferResponse,
-} from "@frt/report-core";
+import { FieldRegistry } from "@frt-platform/report-core";
+import { z } from "zod";
+
+FieldRegistry.register("richText", {
+  defaults: { label: "Details" },
+  buildResponseSchema(field) {
+    let schema = z.string();
+    if (field.minLength) schema = schema.min(field.minLength);
+    return field.required ? schema : schema.optional();
+  },
+});
 ```
 
-* `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
+Now templates may include fields like:
 
 ```ts
-import {
-  REPORT_TEMPLATE_VERSION,
-  REPORT_TEMPLATE_FIELD_TYPES,
-  DEFAULT_FIELD_LABEL,
-  CORE_FIELD_DEFAULTS,
-} from "@frt/report-core";
+{ id: "body", type: "richText", label: "Report body" }
 ```
 
-* `REPORT_TEMPLATE_VERSION: number`
-* `REPORT_TEMPLATE_FIELD_TYPES: readonly ReportTemplateFieldType[]`
-* `DEFAULT_FIELD_LABEL: string`
-* `CORE_FIELD_DEFAULTS: Record<ReportTemplateFieldType, Record<string, unknown>>`
+---
 
-### Validation & parsing
+# 🧾 JSON Schema Export
 
 ```ts
-import {
-  ReportTemplateFieldSchema,
-  ReportTemplateSectionSchema,
-  ReportTemplateSchemaValidator,
-  parseReportTemplateSchema,
-  parseReportTemplateSchemaFromString,
-  normalizeReportTemplateSchema,
-  serializeReportTemplateSchema,
-} from "@frt/report-core";
+import { exportJSONSchema } from "@frt-platform/report-core";
+
+const jsonSchema = exportJSONSchema(template);
 ```
 
-Use the Zod schemas directly if you want:
+Produces JSON Schema with:
 
-```ts
-import { ReportTemplateSchemaValidator } from "@frt/report-core";
+* field types
+* enums
+* min/max constraints
+* default values
+* conditional logic preserved as custom `x-frt-*` properties
 
-const result = ReportTemplateSchemaValidator.safeParse(raw);
-if (!result.success) {
-  // handle validation errors
-}
-```
+---
 
-### Migration
+# 🔍 Diff Templates
 
 ```ts
-import { migrateLegacySchema } from "@frt/report-core";
-```
+import { diffTemplates } from "@frt-platform/report-core";
 
-Takes `unknown` legacy input and returns a shape better suited for current schema validation.
+const diff = diffTemplates(oldTemplate, newTemplate);
+```
 
-### Response validation
+Detects:
 
-```ts
-import {
-  buildResponseSchema,
-  validateReportResponse,
-  type InferResponse,
-} from "@frt/report-core";
-```
+* added/removed/reordered sections
+* added/removed/reordered fields
+* modified fields
+* nested diffs for repeat groups
 
-### Template diffing
+Perfect for:
 
-```ts
-import { diffTemplates } from "@frt/report-core";
-```
+* Version history
+* Audit logs
+* Template editing UI
 
 ---
 
-## Integration Ideas
-
-This package is intentionally minimal. You can layer it into:
+# 🧬 Type Inference
 
-* **Next.js / React** apps for:
+Given a template:
 
-  * Template builders
-  * Dynamic report forms
-  * Admin panels for managing report templates
-* **Node/Edge backends** for:
+```ts
+export const myTemplate = {
+  version: 1,
+  sections: [
+    {
+      id: "s",
+      fields: [
+        { id: "title", type: "shortText", required: true },
+        { id: "tags", type: "multiSelect", options: ["A", "B"] },
+      ]
+    }
+  ]
+} as const;
+```
 
-  * Validating templates on save
-  * Migrating old template shapes
-  * Ensuring consistent data before persisting to a DB
-  * Validating report responses before saving them
+Infer response type:
 
-Typical pattern in a full stack app:
+```ts
+type MyResponse = InferResponse<typeof myTemplate>;
+```
 
-1. **Frontend**
+Produces:
 
-   * Build a visual editor for templates
-   * Send template JSON to server
+```ts
+type MyResponse = {
+  title: string;
+  tags?: ("A" | "B")[];
+};
+```
 
-2. **Backend**
+---
 
-   * `parseReportTemplateSchema` to validate templates
-   * Store `ReportTemplateSchema` JSON in your DB (e.g. Mongo via Prisma)
-   * On response submission:
+# 🧾 Serialization
 
-     * Load template from DB
-     * `validateReportResponse(template, data)` before insert
+```ts
+import { serializeReportTemplateSchema } from "@frt-platform/report-core";
 
-3. **Runtime**
+const json = serializeReportTemplateSchema(template, {
+  pretty: true,
+  sortSectionsById: true,
+  sortFieldsById: true,
+});
+```
 
-   * Load templates from DB
-   * Use them to render dynamic forms
-   * Use `buildResponseSchema` to validate and normalize responses
+Useful for deterministic output in Git.
 
 ---
 
-## Roadmap / Extensions (ideas)
+# 🧱 Roadmap
+
+### Phase 1 — Core Maturation (✔️ COMPLETE)
+
+* Validation
+* Conditional logic
+* Diffing
+* Field Registry
+* Error helpers
+* Serialization features
 
-Things you might add on top (in a separate package, e.g. `@frt/report-react`):
+### Phase 2 — Advanced Field System (IN PROGRESS)
 
-* React components for:
+* Repeat group conditional rules (`minIf` / `maxIf`)
+* Conditional logic inside group rows
+* Computed fields (design)
+* RichText / FileUpload via registry
 
-  * Template builder UI
-  * Field editors/renderers (short text, selects, etc.)
-  * Auto-generated `<ReportForm />` that consumes a template
-* More advanced field types:
+### Phase 3 — Reactions & Analytics (Planned)
 
-  * File uploads
-  * Signature pads
-  * Matrix / grid fields
-* Conditional logic:
+* Scoring rules
+* Auto-tagging
+* Suggested outcomes
 
-  * `visibleIf`
-  * `requiredIf`
-* Multi-language labels & descriptions
+### Phase 4 — React UI Package (Planned)
 
-The core stays simple: **schema + validation + migration + response validation + diffing**.
+* Form renderer
+* Template builder
+* Field palette
+* Full ShadCN integration
 
 ---
 
-## License
+# 📄 License
 
-MIT – use it in your projects, commercial or not. Contributions welcome.
+MIT — feel free to use, extend, or contribute.