@frt-platform/report-core 1.4.0 → 1.5.0

package/dist/index.d.mts

@@ -7,7 +7,9 @@ declare const Condition: z.ZodType<any>;
 type SimpleCondition = z.infer<typeof Condition>;
 declare const RepeatGroupFieldSchema: z.ZodType<any>;
 declare const ReportTemplateFieldSchema: z.ZodType<any>;
-type ReportTemplateField = z.infer<typeof ReportTemplateFieldSchema>;
+type ReportTemplateField = z.infer<typeof ReportTemplateFieldSchema> & {
+    computed?: string;
+};
 declare const ReportTemplateSectionSchema: z.ZodObject<{
     id: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
@@ -68,7 +70,25 @@ declare const ReportTemplateSchemaValidator: z.ZodObject<{
 }>;
 type ReportTemplateSchema = z.infer<typeof ReportTemplateSchemaValidator>;
 
-declare function migrateLegacySchema(raw: unknown): unknown;
+/**
+ * Helper for generating a unique id in a *local* namespace, typically in
+ * UI/builders when adding new sections/fields client-side.
+ *
+ * Note:
+ * - This is deliberately simple and deterministic.
+ * - Core template normalization uses its own normalizeId/ensureUniqueId logic
+ *   so that persisted IDs stay stable and backwards compatible.
+ */
+declare function createUniqueId(prefix: string, existing: Iterable<string>): string;
+
+/**
+ * Migrate a legacy flat { fields: [...] } structure or partially-upgraded
+ * schema into the current { sections: [...] } shape.
+ *
+ * This is intentionally loose: it accepts `unknown` and only normalizes
+ * what we care about. The full Zod validation happens later.
+ */
+declare function migrateLegacySchema(raw: unknown): ReportTemplateSchema | any;
 
 declare function normalizeReportTemplateSchema(schema: ReportTemplateSchema): ReportTemplateSchema;
 declare function parseReportTemplateSchema(raw: unknown): ReportTemplateSchema;
@@ -99,61 +119,55 @@ interface SerializeOptions {
  */
 declare function serializeReportTemplateSchema(schema: ReportTemplateSchema, options?: SerializeOptions): string;
 
+interface SectionPropertyChange {
+    key: string;
+    before: unknown;
+    after: unknown;
+}
+interface ModifiedSection {
+    sectionId: string;
+    changes: SectionPropertyChange[];
+}
+interface ModifiedField {
+    sectionId: string;
+    fieldId: string;
+    changes: SectionPropertyChange[];
+}
+interface SectionAddRemove {
+    sectionId: string;
+    index: number;
+}
+interface SectionReorder {
+    sectionId: string;
+    from: number;
+    to: number;
+}
+interface FieldAddRemove {
+    sectionId: string;
+    fieldId: string;
+    index: number;
+}
+interface FieldReorder {
+    sectionId: string;
+    fieldId: string;
+    from: number;
+    to: number;
+}
+interface NestedFieldDiff {
+    sectionId: string;
+    groupId: string;
+    diffs: TemplateDiff;
+}
 interface TemplateDiff {
-    addedSections: Array<{
-        sectionId: string;
-        index: number;
-    }>;
-    removedSections: Array<{
-        sectionId: string;
-        index: number;
-    }>;
-    reorderedSections: Array<{
-        sectionId: string;
-        from: number;
-        to: number;
-    }>;
-    modifiedSections: Array<{
-        sectionId: string;
-        changes: Array<{
-            key: string;
-            before: any;
-            after: any;
-        }>;
-    }>;
-    addedFields: Array<{
-        sectionId: string;
-        fieldId: string;
-        index: number;
-    }>;
-    removedFields: Array<{
-        sectionId: string;
-        fieldId: string;
-        index: number;
-    }>;
-    reorderedFields: Array<{
-        sectionId: string;
-        fieldId: string;
-        from: number;
-        to: number;
-    }>;
-    modifiedFields: Array<{
-        sectionId: string;
-        fieldId: string;
-        before: Record<string, any>;
-        after: Record<string, any>;
-        changes: Array<{
-            key: string;
-            before: any;
-            after: any;
-        }>;
-    }>;
-    /** NEW: repeatGroup nested diffs */
-    nestedFieldDiffs: Array<{
-        sectionId: string;
-        groupId: string;
-        diffs: TemplateDiff;
-    }>;
+    addedSections: SectionAddRemove[];
+    removedSections: SectionAddRemove[];
+    reorderedSections: SectionReorder[];
+    modifiedSections: ModifiedSection[];
+    addedFields: FieldAddRemove[];
+    removedFields: FieldAddRemove[];
+    reorderedFields: FieldReorder[];
+    modifiedFields: ModifiedField[];
+    nestedFieldDiffs: NestedFieldDiff[];
 }
 declare function diffTemplates(before: ReportTemplateSchema, after: ReportTemplateSchema): TemplateDiff;
 
@@ -192,85 +206,33 @@ interface JSONSchema {
  */
 declare function exportJSONSchema(template: ReportTemplateSchema): JSONSchema;
 
-declare const DEFAULT_FIELD_LABEL = "Untitled question";
-declare const CORE_FIELD_DEFAULTS: Record<ReportTemplateFieldType, Record<string, unknown>>;
-
 /**
- * Helper for generating a unique id in a *local* namespace, typically in
- * UI/builders when adding new sections/fields client-side.
+ * Evaluate a SimpleCondition against a flat response object.
  *
- * Note: Core template normalization uses its own normalizeId/ensureUniqueId
- * logic so that persisted IDs stay stable and backwards compatible.
- */
-declare function createUniqueId(prefix: string, existing: Iterable<string>): string;
-
-/** -------------------------------------------------------------
- * FieldRegistryEntry
- * --------------------------------------------------------------
- * Represents metadata + behavior for a single field type.
- * -------------------------------------------------------------- */
-interface FieldRegistryEntry {
-    /** Default field-level properties merged when creating new fields */
-    defaults?: Record<string, unknown>;
-    /**
-     * Build a Zod schema for validating the *response value* of this field.
-     * If not provided, the core engine falls back to the built-in handler.
-     */
-    buildResponseSchema?: (field: ReportTemplateField) => ZodTypeAny;
-    /**
-     * Optional UI metadata for @frt/report-react
-     * (icon, color, description, grouping, etc.)
-     */
-    ui?: Record<string, any>;
-}
-/** -------------------------------------------------------------
- * FieldRegistry
- * --------------------------------------------------------------
- * Central store of all field types (built-in + custom).
- * -------------------------------------------------------------- */
-declare class FieldRegistryClass {
-    private registry;
-    /** Register or override a field type. */
-    register(type: string, entry: FieldRegistryEntry): void;
-    /** Get registry entry for a field type. */
-    get(type: string): FieldRegistryEntry | undefined;
-    /** Check if field type is registered. */
-    has(type: string): boolean;
-    /** Return all field types currently registered. */
-    list(): string[];
-}
-/** Singleton instance */
-declare const FieldRegistry: FieldRegistryClass;
-
-/**
- * Evaluate a conditional rule against a submitted response object.
+ * Supported structure:
+ * - { equals: { fieldId: value } }
+ * - { any: [cond, cond, ...] }
+ * - { all: [cond, cond, ...] }
+ * - { not: cond }
  *
- * Supported forms:
- *  { equals: { fieldId: value } }
- *  { any: [cond, cond] }
- *  { all: [cond, cond] }
- *  { not: cond }
+ * Notes:
+ * - We intentionally keep this evaluation shallow and deterministic.
+ * - No special array semantics (e.g. "contains") yet — it's strict equality.
  */
-declare function evaluateCondition(condition: SimpleCondition, response: Record<string, any>): boolean;
+declare function evaluateCondition(condition: SimpleCondition | undefined, response: Record<string, any>): boolean;
 
-declare function buildBaseFieldSchema(field: ReportTemplateField): ZodTypeAny;
-declare function buildResponseSchemaWithConditions(template: ReportTemplateSchema, response: Record<string, any>): z.ZodObject<Record<string, ZodTypeAny>>;
 /**
- * Build a Zod object schema for a template *without* needing a response object.
+ * Build the base Zod schema for a field, WITHOUT:
+ *  - visibleIf
+ *  - requiredIf
+ *  - computed fields
+ *  - repeatGroup logic
  *
- * Notes:
- * - All conditional logic is evaluated against an empty response `{}`.
- * - This means:
- *   - `visibleIf` / `requiredIf` that depend on other fields will typically
- *     evaluate to false.
- *
- * This is mainly useful for:
- * - Static type inference
- * - Generic tooling / OpenAPI style usage
- * - Situations where you just want the overall "shape" of a response.
+ * This is the lowest-level “field → Zod” mapping.
+ * All conditional logic is layered on top in conditionalSchema.ts.
  */
-declare function buildResponseSchema(template: ReportTemplateSchema): z.ZodObject<Record<string, ZodTypeAny>>;
-declare function validateReportResponse(template: ReportTemplateSchema, data: unknown): Record<string, unknown>;
+declare function buildBaseFieldSchema(field: ReportTemplateField): ZodTypeAny;
+
 type FieldErrorCode = "response.invalid_root" | "field.required" | "field.invalid_type" | "field.too_small" | "field.too_big" | "field.invalid_option" | "field.custom";
 interface ResponseFieldError {
     /** field id (template-level id) */
@@ -288,6 +250,27 @@ interface ResponseFieldError {
     /** original Zod issue (for debugging / logging) */
     rawIssue?: ZodIssue;
 }
+/**
+ * Helper to turn a thrown ZodError (e.g. from validateReportResponse)
+ * into the same ResponseFieldError[] shape used by
+ * validateReportResponseDetailed.
+ *
+ * Returns null if the error is not a ZodError.
+ */
+declare function explainValidationError(template: ReportTemplateSchema, error: unknown): ResponseFieldError[] | null;
+
+declare function buildResponseSchemaWithConditions(template: ReportTemplateSchema, response: Record<string, any>): z.ZodObject<Record<string, ZodTypeAny>>;
+/**
+ * Build a Zod object schema for a template *without* needing a response object.
+ *
+ * Notes:
+ * - All conditional logic is evaluated against an empty response `{}`.
+ * - This is mainly useful for:
+ *   - Static type inference
+ *   - Generic tooling / OpenAPI-style usage
+ */
+declare function buildResponseSchema(template: ReportTemplateSchema): z.ZodObject<Record<string, ZodTypeAny>>;
+declare function validateReportResponse(template: ReportTemplateSchema, data: unknown): Record<string, unknown>;
 /**
  * Validates a response against a template, but instead of throwing,
  * returns a structured error object with:
@@ -304,28 +287,66 @@ declare function validateReportResponseDetailed(template: ReportTemplateSchema,
     success: false;
     errors: ResponseFieldError[];
 };
+
 /**
- * Helper to turn a thrown ZodError (e.g. from validateReportResponse)
- * into the same ResponseFieldError[] shape used by
- * validateReportResponseDetailed.
+ * Extracts the union of all field configs from a template type.
  *
- * Returns null if the error is not a ZodError.
+ * Given:
+ * {
+ *   sections: [
+ *     { fields: [F1, F2] },
+ *     { fields: [F3] }
+ *   ]
+ * }
+ *
+ * → TemplateFieldUnion<TTemplate> = F1 | F2 | F3
  */
-declare function explainValidationError(template: ReportTemplateSchema, error: unknown): ResponseFieldError[] | null;
 type TemplateFieldUnion<TTemplate> = TTemplate extends {
     sections: readonly (infer S)[];
 } ? S extends {
     fields: readonly (infer F)[];
 } ? F : never : never;
+/**
+ * Base value type for a field, ignoring `required`.
+ * This is deliberately simple and only keyed off `type` + `options`.
+ */
 type BaseFieldValue<TField extends {
     type: ReportTemplateFieldType;
     required?: boolean;
     options?: readonly string[] | string[];
-}> = TField["type"] extends "shortText" | "longText" ? string : TField["type"] extends "number" ? number : TField["type"] extends "date" ? string : TField["type"] extends "checkbox" ? boolean : TField["type"] extends "singleSelect" ? (TField["options"] extends readonly (infer O)[] ? O : TField["options"] extends (infer O)[] ? O : string) : TField["type"] extends "multiSelect" ? (TField["options"] extends readonly (infer O)[] ? O[] : TField["options"] extends (infer O)[] ? O[] : string[]) : TField["type"] extends "repeatGroup" ? Array<Record<string, unknown>> : unknown;
+}> = TField["type"] extends "shortText" | "longText" ? string : TField["type"] extends "number" ? number : TField["type"] extends "date" ? string : TField["type"] extends "checkbox" ? boolean : TField["type"] extends "singleSelect" ? TField["options"] extends readonly (infer O)[] ? O : TField["options"] extends (infer O)[] ? O : string : TField["type"] extends "multiSelect" ? TField["options"] extends readonly (infer O)[] ? O[] : TField["options"] extends (infer O)[] ? O[] : string[] : TField["type"] extends "repeatGroup" ? Array<Record<string, unknown>> : unknown;
+/**
+ * Wrap base value in optionality depending on `required`.
+ */
 type FieldResponseValue<TField extends {
     type: ReportTemplateFieldType;
     required?: boolean;
 }> = TField["required"] extends true ? BaseFieldValue<TField> : BaseFieldValue<TField> | undefined;
+/**
+ * Infer the response shape from a *const* template definition.
+ *
+ * Example:
+ *
+ *   export const myTemplate = {
+ *     version: 1,
+ *     sections: [
+ *       {
+ *         id: "main",
+ *         fields: [
+ *           { id: "title", type: "shortText", required: true },
+ *           { id: "tags", type: "multiSelect", options: ["A", "B"] },
+ *         ]
+ *       }
+ *     ]
+ *   } as const;
+ *
+ *   type MyResponse = InferResponse<typeof myTemplate>;
+ *
+ *   // {
+ *   //   title: string;
+ *   //   tags?: ("A" | "B")[];
+ *   // }
+ */
 type InferResponse<TTemplate extends {
     sections: readonly {
         fields: readonly {
@@ -339,4 +360,59 @@ type InferResponse<TTemplate extends {
     [F in TemplateFieldUnion<TTemplate> as F["id"]]: FieldResponseValue<F>;
 };
 
-export { CORE_FIELD_DEFAULTS, Condition, DEFAULT_FIELD_LABEL, type FieldErrorCode, FieldRegistry, type FieldRegistryEntry, type InferResponse, type JSONSchema, REPORT_TEMPLATE_FIELD_TYPES, REPORT_TEMPLATE_VERSION, RepeatGroupFieldSchema, type ReportTemplateField, ReportTemplateFieldSchema, type ReportTemplateFieldType, type ReportTemplateSchema, ReportTemplateSchemaValidator, type ReportTemplateSection, ReportTemplateSectionSchema, type ResponseFieldError, type SerializeOptions, type SimpleCondition, type TemplateDiff, buildBaseFieldSchema, buildResponseSchema, buildResponseSchemaWithConditions, createUniqueId, diffTemplates, evaluateCondition, explainValidationError, exportJSONSchema, migrateLegacySchema, normalizeReportTemplateSchema, parseReportTemplateSchema, parseReportTemplateSchemaFromString, serializeReportTemplateSchema, validateReportResponse, validateReportResponseDetailed };
+/** -------------------------------------------------------------
+ * FieldRegistryEntry
+ * --------------------------------------------------------------
+ * Represents metadata + behavior for a single field type.
+ * -------------------------------------------------------------- */
+interface FieldRegistryEntry {
+    /** Default field-level properties merged when creating new fields */
+    defaults?: Record<string, unknown>;
+    /**
+     * Build a Zod schema for validating the *response value* of this field.
+     * If not provided, the core engine falls back to the built-in handler.
+     */
+    buildResponseSchema?: (field: ReportTemplateField) => ZodTypeAny;
+    /**
+     * Optional UI metadata for @frt/report-react
+     * (icon, color, description, grouping, etc.)
+     */
+    ui?: Record<string, any>;
+}
+/** -------------------------------------------------------------
+ * FieldRegistry
+ * --------------------------------------------------------------
+ * Central store of all field types (built-in + custom).
+ * -------------------------------------------------------------- */
+declare class FieldRegistryClass {
+    private registry;
+    /** Register or override a field type. */
+    register(type: string, entry: FieldRegistryEntry): void;
+    /** Get registry entry for a field type. */
+    get(type: string): FieldRegistryEntry | undefined;
+    /** Check if field type is registered. */
+    has(type: string): boolean;
+    /** Return all field types currently registered. */
+    list(): string[];
+}
+/** Singleton instance */
+declare const FieldRegistry: FieldRegistryClass;
+
+/**
+ * Shared default label used for all core field types.
+ */
+declare const DEFAULT_FIELD_LABEL = "Untitled field";
+/**
+ * Shape of the core defaults map.
+ * We keep values loose (Record<string, any>) because different field
+ * types have different shapes, and these are just "seed" objects.
+ */
+type CoreFieldDefaults = Record<ReportTemplateFieldType, Record<string, any>>;
+/**
+ * Default configs for every core field type.
+ * These are *not* full fields (no id), just starter values that
+ * template builders / UIs can merge into new fields.
+ */
+declare const CORE_FIELD_DEFAULTS: CoreFieldDefaults;
+
+export { CORE_FIELD_DEFAULTS, Condition, type CoreFieldDefaults, DEFAULT_FIELD_LABEL, type FieldAddRemove, type FieldErrorCode, FieldRegistry, type FieldRegistryEntry, type FieldReorder, type InferResponse, type JSONSchema, type ModifiedField, type ModifiedSection, type NestedFieldDiff, REPORT_TEMPLATE_FIELD_TYPES, REPORT_TEMPLATE_VERSION, RepeatGroupFieldSchema, type ReportTemplateField, ReportTemplateFieldSchema, type ReportTemplateFieldType, type ReportTemplateSchema, ReportTemplateSchemaValidator, type ReportTemplateSection, ReportTemplateSectionSchema, type ResponseFieldError, type SectionAddRemove, type SectionPropertyChange, type SectionReorder, type SerializeOptions, type SimpleCondition, type TemplateDiff, buildBaseFieldSchema, buildResponseSchema, buildResponseSchemaWithConditions, createUniqueId, diffTemplates, evaluateCondition, explainValidationError, exportJSONSchema, migrateLegacySchema, normalizeReportTemplateSchema, parseReportTemplateSchema, parseReportTemplateSchemaFromString, serializeReportTemplateSchema, validateReportResponse, validateReportResponseDetailed };