@finsys/core 1.1.0 → 1.2.0

package/dist/index.d.cts

@@ -0,0 +1,375 @@
+import { z } from 'zod';
+import { ErrorObject } from 'ajv';
+export { IElement, IPage, IPanel, IQuestion, ISurvey } from 'survey-core';
+
+/**
+ * Survey Generator - Converts unified form configurations into SurveyJS-compatible JSON
+ *
+ * This module converts a unified form-config.json into SurveyJS-compatible JSON,
+ * resolving field references, applying dynamic titles, and grouping by category.
+ */
+
+interface Category {
+    id: string;
+    name: string;
+}
+interface Choice {
+    value: string;
+    text: string;
+}
+interface Validator {
+    type: "regex" | "email" | "numeric" | "text" | "expression" | "answercount" | "custom";
+    text?: string;
+    regex?: string;
+    minValue?: number;
+    maxValue?: number;
+    minLength?: number;
+    maxLength?: number;
+    minCount?: number;
+    maxCount?: number;
+    expression?: string;
+    validator?: string;
+}
+/**
+ * FieldData - Field definition in the unified form config
+ */
+interface FieldData {
+    name?: string;
+    displayName?: string;
+    type: string;
+    inputType?: "text" | "number" | "tel" | "date" | "email" | "password" | "url";
+    category?: string;
+    maxLength?: number | string;
+    min?: number | string;
+    max?: number | string;
+    step?: number;
+    html?: string;
+    choices?: Choice[];
+    validators?: Validator[];
+    visible?: boolean;
+    visibleIf?: string;
+    required?: boolean;
+    isRequired?: boolean;
+    placeholder?: string;
+    defaultValue?: string | number | boolean | string[];
+    readOnly?: boolean;
+    startWithNewLine?: boolean;
+    enableIf?: string;
+    titleLocation?: "default" | "top" | "bottom" | "left" | "hidden";
+    ihs_column_names?: string[];
+    requiredForEvaluation?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * FieldReference - How fields are referenced in pages
+ */
+type FieldReference = string | {
+    ref: string;
+    [key: string]: unknown;
+} | {
+    definition: FieldData & {
+        name: string;
+    };
+};
+interface PageConfig {
+    id: string;
+    title?: string;
+    description?: string;
+    showTOC?: boolean;
+    showProgressBar?: boolean;
+    showCategoryHeadings?: boolean;
+    layout?: "default" | "grid" | "vertical";
+    fields: FieldReference[];
+}
+/**
+ * UnifiedFormConfig - The main configuration type for the unified form format
+ */
+interface UnifiedFormConfig {
+    $schema?: string;
+    schemaVersion?: string;
+    displayName?: string;
+    templateIcon?: string;
+    categories: Category[];
+    fields: Record<string, FieldData>;
+    pages?: PageConfig[];
+}
+interface SurveyElementJSON {
+    type: string;
+    name: string;
+    title?: string;
+    isRequired?: boolean;
+    maxLength?: number;
+    storeDataAsText?: boolean;
+    category?: string;
+    [key: string]: unknown;
+}
+interface SurveyPageJSON {
+    name: string;
+    title: string;
+    elements: Array<{
+        type: string;
+        name: string;
+        elements: SurveyElementJSON[];
+    }>;
+}
+interface SurveyJSON {
+    title: string;
+    logoPosition?: string;
+    pages: SurveyPageJSON[];
+    showQuestionNumbers?: string;
+    questionErrorLocation?: string;
+    completedHtml?: string;
+    showTOC?: boolean;
+    completeText?: string;
+    showPreviewBeforeComplete?: string;
+    showProgressBar?: string;
+    widthMode?: string;
+    width?: string;
+}
+interface ResolvedField extends FieldData {
+    name: string;
+}
+/**
+ * Apply dynamic title logic (e.g., bank statements with dynamic month labels,
+ * financial statements with dynamic year labels)
+ */
+declare function applyDynamicTitles(field: ResolvedField): ResolvedField;
+/**
+ * Generate SurveyJS JSON from unified form config
+ */
+declare function generateSurveyJson(config: UnifiedFormConfig): SurveyJSON | Record<string, never>;
+/**
+ * Resolve all fields from a page to full field definitions
+ */
+declare function resolvePageFields(page: PageConfig, fields: Record<string, FieldData>): ResolvedField[];
+/**
+ * Get category name from category ID (supports string or number IDs)
+ */
+declare function getCategoryName(categoryId: string | undefined, categories: Category[]): string;
+/**
+ * Group fields by their category, maintaining order and creating section breaks
+ */
+interface FieldGroup {
+    category: string;
+    categoryName: string;
+    fields: ResolvedField[];
+}
+declare function groupFieldsByCategory(fields: ResolvedField[], categories: Category[]): FieldGroup[];
+
+/**
+ * Utility functions for @finsys/core
+ */
+declare function getPastMonthLabel(monthsAgo: number): string;
+declare function getPastYearLabel(yearsAgo: number): string;
+/**
+ * Evaluate a SurveyJS-style expression against a data object.
+ * e.g. "{totalFinancing} > 50000"
+ *
+ * NOTE: This is a simplified evaluator that replaces {key} with data[key] access.
+ * It does not support complex SurveyJS functions like age() or complicated nested paths unless handled by JS.
+ */
+declare function evaluateExpression(expression: string, data: any): boolean;
+
+interface RHFStep {
+    id: number;
+    title: string;
+    description?: string;
+    fields: ResolvedField[];
+    showCategoryHeadings: boolean;
+    layout?: "default" | "grid" | "vertical";
+}
+interface RHFSchemaOutput {
+    zodSchema: z.ZodTypeAny;
+    baseSchema: z.ZodObject<any>;
+    defaultValues: Record<string, any>;
+    fields: ResolvedField[];
+    groupedFields: FieldGroup[];
+    steps: RHFStep[];
+    displayName: string;
+    categories: Category[];
+    templateIcon?: string;
+}
+declare function generateRHFSchema(config: UnifiedFormConfig): RHFSchemaOutput;
+/**
+ * Get Zod schema for a specific step
+ */
+declare function getStepSchema(step: RHFStep, fullSchema: any): z.ZodTypeAny;
+/**
+ * Extract default values for a specific step
+ */
+declare function getStepDefaultValues(step: RHFStep, allDefaults: Record<string, any>): Record<string, any>;
+
+interface ValidationResult {
+    valid: boolean;
+    errors?: ErrorObject[];
+    message?: string;
+}
+/**
+ * Validates a unified form-config.json object against its schema
+ */
+declare function validateFormConfig(data: unknown): ValidationResult;
+/** @deprecated Use validateFormConfig instead */
+declare function validateFormSpec(data: unknown): ValidationResult;
+/** @deprecated Use validateFormConfig instead */
+declare function validatePagesConfig(data: unknown): ValidationResult;
+
+declare class FormFieldCategory {
+    private _id;
+    private _name;
+    constructor(id: string | number, name: string);
+    get id(): string;
+    get name(): string;
+    set name(value: string);
+    toJSON(): {
+        id: string;
+        name: string;
+    };
+}
+
+declare enum FieldType {
+    FILE = "file",
+    TEXT = "text",
+    DROPDOWN = "dropdown",
+    BOOLEAN = "boolean",
+    CHECKBOX = "checkbox",
+    RADIOGROUP = "radiogroup",
+    SLIDER = "slider",
+    HTML = "html",
+    TAGBOX = "tagbox",
+    NUMBER = "number",
+    EMAIL = "email",
+    COMMENT = "comment",
+    RANGE = "range",
+    UNKNOWN = "unknown"
+}
+interface FormFieldType {
+    name: string;
+    displayName: string;
+}
+interface FormFieldInputType {
+    name: string;
+    displayName: string;
+}
+interface FormFieldTypeDefinitions {
+    version: number;
+    types: FormFieldType[];
+    input_types: FormFieldInputType[];
+}
+interface DropdownOption {
+    id: number;
+    name: string;
+    displayName: string;
+    choices: Choice[];
+}
+interface EditorValidator {
+    id: number;
+    displayName: string;
+    class: string;
+    description: string;
+    isRequired: boolean;
+    validators: Validator[];
+}
+declare abstract class FormField {
+    fieldObject: FieldData;
+    constructor(name: string, displayName: string, type: string, category: string);
+    static fromObject(fieldObject: FieldData): FormField;
+    abstract getFieldNames(): string[];
+    protected cleanObject(obj: any): any;
+    toJSON(): any;
+    get displayName(): string;
+    set displayName(newDisplayName: string);
+    get name(): string;
+    get type(): FieldType;
+    get inputType(): string;
+    get categoryId(): string;
+    set categoryId(categoryId: string);
+    get defaultValue(): any;
+    set defaultValue(value: any);
+    get placeholder(): string | undefined;
+    get validators(): Validator[] | undefined;
+    get choices(): Choice[];
+    set choices(choices: Choice[]);
+    get visible(): boolean;
+    get visibleIf(): string | undefined;
+    get isRequired(): boolean;
+    get startWithNewLine(): boolean;
+    get requiredForEvaluation(): boolean;
+    get maxLength(): number | undefined;
+    get min(): number | undefined;
+    get max(): number | undefined;
+}
+declare class BasicFormField extends FormField {
+    constructor(name: string, displayName: string, type: string, category: string);
+    getFieldNames(): string[];
+}
+declare class FileFormField extends FormField {
+    constructor(name: string, displayName: string, type: string, category: string, ihs_column_names: string[]);
+    getFieldNames(): string[];
+}
+
+declare class FormSpec {
+    private _categories;
+    private _fields;
+    private _displayName;
+    private _templateIcon?;
+    private _schemaVersion;
+    private _pages;
+    constructor(displayName: string, categories: FormFieldCategory[], fields: FormField[], pages?: PageConfig[], templateIcon?: string, schemaVersion?: string);
+    static readonly MIN_PARSER_SCHEMA_VERSION = "v1.0.0";
+    static readonly MAX_PARSER_SCHEMA_VERSION = "v2.0.0";
+    get fieldNames(): string[];
+    get schemaVersion(): string;
+    get requiresUpgrade(): boolean;
+    upgradeToV2(): void;
+    get displayName(): string;
+    set displayName(newDisplayName: string);
+    get templateIcon(): string | undefined;
+    set templateIcon(value: string | undefined);
+    get categories(): FormFieldCategory[];
+    set categories(categories: FormFieldCategory[]);
+    get fields(): FormField[];
+    set fields(fields: FormField[]);
+    get pages(): PageConfig[];
+    set pages(value: PageConfig[]);
+    addField(field: FormField): void;
+    updateField(field: FormField): void;
+    removeField(fieldName: string): void;
+    getFieldsByCategory(categoryName: string): FormField[];
+    validate(): {
+        valid: boolean;
+        errors?: any[];
+    };
+    private cleanObject;
+    toJSON(): object;
+    static fromJSON(jsonString: string): FormSpec;
+}
+
+interface FormValidatorDefinitions {
+    options: EditorValidator[];
+    version: number;
+}
+declare class FormFieldValidator implements EditorValidator {
+    id: number;
+    displayName: string;
+    class: string;
+    description: string;
+    isRequired: boolean;
+    validators: Validator[];
+    constructor(validatorData: EditorValidator);
+    validate(value: any): boolean;
+    private validateNumeric;
+    private validateText;
+}
+
+declare const BASE_FIELD_SPECS: {
+    schemaVersion: string;
+    categories: Category[];
+    fields: FieldData[];
+};
+declare const FIELD_TYPE_DEFINITIONS: FormFieldTypeDefinitions;
+declare const DEFAULT_VALIDATOR_DEFINITIONS: FormValidatorDefinitions;
+declare function getBaseFieldSpecs(): FieldData[];
+declare function getBaseCategories(): Category[];
+declare function getBaseFieldNames(): string[];
+
+export { BASE_FIELD_SPECS, BasicFormField, type Category, type Choice, DEFAULT_VALIDATOR_DEFINITIONS, type DropdownOption, type EditorValidator, FIELD_TYPE_DEFINITIONS, type FieldData, type FieldGroup, type FieldReference, FieldType, FileFormField, FormField, FormFieldCategory, type FormFieldInputType, type FormFieldType, type FormFieldTypeDefinitions, FormFieldValidator, FormSpec, type FormValidatorDefinitions, type PageConfig, type RHFSchemaOutput, type RHFStep, type ResolvedField, type SurveyElementJSON, type SurveyJSON, type SurveyPageJSON, type UnifiedFormConfig, type Validator, applyDynamicTitles, evaluateExpression, generateRHFSchema, generateSurveyJson, getBaseCategories, getBaseFieldNames, getBaseFieldSpecs, getCategoryName, getPastMonthLabel, getPastYearLabel, getStepDefaultValues, getStepSchema, groupFieldsByCategory, resolvePageFields, validateFormConfig, validateFormSpec, validatePagesConfig };