@frt-platform/report-core 1.0.0

package/README.md

@@ -0,0 +1,367 @@
+# @frt/report-core
+
+Core engine for building, validating, and migrating **report templates**.
+
+This package is framework-agnostic, React-free, and storage-agnostic. 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
+
+It’s the core that powers a flexible incident/report builder, but it’s generic enough to be reused in any app.
+
+---
+
+## Installation
+
+```bash
+# npm
+npm install @frt/report-core zod
+
+# yarn
+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.
+
+---
+
+## Concepts
+
+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
+
+Supported field types:
+
+```ts
+import { REPORT_TEMPLATE_FIELD_TYPES } from "@frt/report-core";
+
+console.log(REPORT_TEMPLATE_FIELD_TYPES);
+// [
+//   "shortText",
+//   "longText",
+//   "number",
+//   "date",
+//   "checkbox",
+//   "singleSelect",
+//   "multiSelect",
+//   "starRating"
+// ]
+```
+
+---
+
+## Quick Start
+
+### 1. Define a template in JSON
+
+You can define templates statically or load them from DB / API:
+
+```ts
+import type { ReportTemplateSchema } from "@frt/report-core";
+
+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"
+        }
+      ]
+    }
+  ]
+};
+```
+
+### 2. Validate and normalize it
+
+Use the helpers to safely parse and normalize unknown input:
+
+```ts
+import {
+  parseReportTemplateSchema,
+  normalizeReportTemplateSchema
+} from "@frt/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.)
+const normalized = normalizeReportTemplateSchema(parsed);
+
+console.log(normalized.sections[0].fields[0].id);
+// always a non-empty, safe identifier
+```
+
+### 3. Serialize for storage
+
+```ts
+import { serializeReportTemplateSchema } from "@frt/report-core";
+
+const jsonString = serializeReportTemplateSchema(normalized);
+// ready to store in DB, file, etc.
+```
+
+---
+
+## Parsing from a JSON string
+
+If you have a JSON string (e.g. from a form textarea):
+
+```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
+}
+```
+
+---
+
+## 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:
+
+```ts
+import { createUniqueId } from "@frt/report-core";
+
+const existingSectionIds = ["section-1", "section-2"];
+const newId = createUniqueId("section", existingSectionIds);
+// "section-3" (or the next available)
+```
+
+You can use this for both section and field IDs when building templates dynamically.
+
+---
+
+## 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:
+
+```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"] }
+  ]
+};
+
+const migrated = migrateLegacySchema(legacy);
+const parsed = parseReportTemplateSchema(migrated);
+
+console.log(parsed.sections.length); // 1
+console.log(parsed.sections[0].fields[0].type); // "longText"
+```
+
+You don’t normally need to call `migrateLegacySchema` yourself – `parseReportTemplateSchema` already does:
+
+```ts
+// internally:
+const migrated = migrateLegacySchema(raw);
+const parsed = ReportTemplateSchemaValidator.parse(migrated);
+```
+
+---
+
+## API Overview
+
+### Types
+
+```ts
+import type {
+  ReportTemplateSchema,
+  ReportTemplateSection,
+  ReportTemplateField,
+  ReportTemplateFieldType
+} from "@frt/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
+
+### Constants
+
+```ts
+import {
+  REPORT_TEMPLATE_VERSION,
+  REPORT_TEMPLATE_FIELD_TYPES,
+  DEFAULT_FIELD_LABEL,
+  CORE_FIELD_DEFAULTS
+} from "@frt/report-core";
+```
+
+* `REPORT_TEMPLATE_VERSION: number`
+* `REPORT_TEMPLATE_FIELD_TYPES: readonly ReportTemplateFieldType[]`
+* `DEFAULT_FIELD_LABEL: string`
+* `CORE_FIELD_DEFAULTS: Record<ReportTemplateFieldType, Record<string, unknown>>`
+
+### Validation & parsing
+
+```ts
+import {
+  ReportTemplateFieldSchema,
+  ReportTemplateSectionSchema,
+  ReportTemplateSchemaValidator,
+  parseReportTemplateSchema,
+  parseReportTemplateSchemaFromString,
+  normalizeReportTemplateSchema,
+  serializeReportTemplateSchema
+} from "@frt/report-core";
+```
+
+Use the Zod schemas directly if you want:
+
+```ts
+import { ReportTemplateSchemaValidator } from "@frt/report-core";
+
+const result = ReportTemplateSchemaValidator.safeParse(raw);
+if (!result.success) {
+  // handle validation errors
+}
+```
+
+### Migration
+
+```ts
+import { migrateLegacySchema } from "@frt/report-core";
+```
+
+Takes `unknown` legacy input and returns a shape better suited for current schema validation.
+
+### Utilities
+
+```ts
+import { createUniqueId } from "@frt/report-core";
+```
+
+---
+
+## Integration Ideas
+
+This package is intentionally minimal. You can layer it into:
+
+* **Next.js / React** apps for:
+
+  * Template builders
+  * Dynamic report forms
+  * Admin panels for managing report templates
+* **Node/Edge backends** for:
+
+  * Validating templates on save
+  * Migrating old template shapes
+  * Ensuring consistent data before persisting to a DB
+
+Typical pattern in a full stack app:
+
+1. **Frontend**:
+
+   * Build a visual editor for templates
+   * Send template JSON to server
+
+2. **Backend**:
+
+   * `parseReportTemplateSchema` to validate
+   * Store `ReportTemplateSchema` JSON in your DB (e.g. Mongo via Prisma)
+
+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).
+
+---
+
+## Roadmap / Extensions (ideas)
+
+Things you might add on top (in a separate package, e.g. `@frt/report-react`):
+
+* React components for:
+
+  * Template builder UI
+  * Field editors/renderers (short text, selects, star rating, etc.)
+* Response schemas built from templates
+* More advanced field types:
+
+  * File uploads
+  * Signature pads
+  * Matrix / grid fields
+* Multi-language labels & descriptions
+
+The core stays simple: schema + validation + migration.
+
+---
+
+## License
+
+MIT – use it in your projects, commercial or not. Contributions welcome.