@finsys/core 1.0.0

package/dist/survey-generator.d.ts

@@ -0,0 +1,153 @@
+/**
+ * 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.
+ */
+export type { IQuestion, IPage, ISurvey, IPanel, IElement } from "survey-core";
+export interface Category {
+    id: string;
+    name: string;
+}
+export interface Choice {
+    value: string;
+    text: string;
+}
+export 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
+ */
+export 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
+ */
+export type FieldReference = string | {
+    ref: string;
+    [key: string]: unknown;
+} | {
+    definition: FieldData & {
+        name: string;
+    };
+};
+export 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
+ */
+export interface UnifiedFormConfig {
+    $schema?: string;
+    schemaVersion?: string;
+    displayName?: string;
+    templateIcon?: string;
+    categories: Category[];
+    fields: Record<string, FieldData>;
+    pages?: PageConfig[];
+}
+export interface SurveyElementJSON {
+    type: string;
+    name: string;
+    title?: string;
+    isRequired?: boolean;
+    maxLength?: number;
+    storeDataAsText?: boolean;
+    category?: string;
+    [key: string]: unknown;
+}
+export interface SurveyPageJSON {
+    name: string;
+    title: string;
+    elements: Array<{
+        type: string;
+        name: string;
+        elements: SurveyElementJSON[];
+    }>;
+}
+export 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;
+}
+export interface ResolvedField extends FieldData {
+    name: string;
+}
+/**
+ * Apply dynamic title logic (e.g., bank statements with dynamic month labels,
+ * financial statements with dynamic year labels)
+ */
+export declare function applyDynamicTitles(field: ResolvedField): ResolvedField;
+/**
+ * Generate SurveyJS JSON from unified form config
+ */
+export declare function generateSurveyJson(config: UnifiedFormConfig): SurveyJSON | Record<string, never>;
+/**
+ * Resolve all fields from a page to full field definitions
+ */
+export declare function resolvePageFields(page: PageConfig, fields: Record<string, FieldData>): ResolvedField[];
+/**
+ * Get category name from category ID (supports string or number IDs)
+ */
+export declare function getCategoryName(categoryId: string | undefined, categories: Category[]): string;
+/**
+ * Group fields by their category, maintaining order and creating section breaks
+ */
+export interface FieldGroup {
+    category: string;
+    categoryName: string;
+    fields: ResolvedField[];
+}
+export declare function groupFieldsByCategory(fields: ResolvedField[], categories: Category[]): FieldGroup[];

package/dist/survey-generator.js

@@ -0,0 +1,185 @@
+/**
+ * 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.
+ */
+import { getPastMonthLabel, getPastYearLabel } from "./utils.js";
+/**
+ * Normalize a field to ensure backward compatibility
+ * - Sets both `required` and `isRequired` to the same value
+ */
+function normalizeField(field) {
+    // Spec: Fields are required by default unless explicitly false
+    const isRequired = field.isRequired !== false && field.required !== false;
+    return {
+        ...field,
+        required: isRequired,
+        isRequired: isRequired
+    };
+}
+/**
+ * Resolve a field reference to a full field definition
+ */
+function resolveFieldReference(ref, fields) {
+    if (typeof ref === "string") {
+        // Simple string reference
+        const fieldDef = fields[ref];
+        if (!fieldDef) {
+            console.warn(`Field "${ref}" not found in fields definition`);
+            return null;
+        }
+        return normalizeField({ name: ref, ...fieldDef });
+    }
+    if ("definition" in ref) {
+        // Inline definition
+        return normalizeField(ref.definition);
+    }
+    if ("ref" in ref) {
+        // Reference with overrides
+        const fieldDef = fields[ref.ref];
+        if (!fieldDef) {
+            console.warn(`Field "${ref.ref}" not found in fields definition`);
+            return null;
+        }
+        const { ref: fieldName, ...overrides } = ref;
+        return normalizeField({ name: fieldName, ...fieldDef, ...overrides });
+    }
+    return null;
+}
+/**
+ * Apply dynamic title logic (e.g., bank statements with dynamic month labels,
+ * financial statements with dynamic year labels)
+ */
+export function applyDynamicTitles(field) {
+    const bankStatementMatch = field.name.match(/^bank_statement_t(\d+)$/);
+    if (bankStatementMatch) {
+        const monthsAgo = parseInt(bankStatementMatch[1], 10);
+        return {
+            ...field,
+            displayName: `Bank Statement (${getPastMonthLabel(monthsAgo)})`
+        };
+    }
+    if (field.name === "financials") {
+        return {
+            ...field,
+            displayName: `Audited Financial Statement (${getPastYearLabel(1)})`
+        };
+    }
+    return field;
+}
+/**
+ * Generate SurveyJS JSON from unified form config
+ */
+export function generateSurveyJson(config) {
+    if (!config.pages || config.pages.length === 0)
+        return {};
+    const firstPage = config.pages.find(p => p.id !== "success-message");
+    if (!firstPage)
+        return {};
+    const categories = config.categories || [];
+    const categoryMap = categories.reduce((acc, cat) => {
+        acc[cat.id] = cat.name;
+        return acc;
+    }, {});
+    // Process all fields from the first page
+    const processedFields = firstPage.fields
+        .map(ref => resolveFieldReference(ref, config.fields))
+        .filter((f) => f !== null)
+        .map(f => applyDynamicTitles(f))
+        .map(f => mapFieldToSurveyJS(f));
+    // Group by Category
+    const grouped = processedFields.reduce((acc, field) => {
+        const catName = categoryMap[field.category] || "Default";
+        if (!acc[catName])
+            acc[catName] = [];
+        acc[catName].push(field);
+        return acc;
+    }, {});
+    // Build Pages (One Page per Category for Wizard effect)
+    const pages = Object.entries(grouped).map(([categoryName, elements]) => ({
+        name: categoryName.toLowerCase().replace(/\s+/g, "-"),
+        title: firstPage.showCategoryHeadings === false ? "" : categoryName,
+        elements: [
+            {
+                type: "panel",
+                name: `${categoryName.toLowerCase().replace(/\s+/g, "-")}-panel`,
+                elements: elements,
+            },
+        ],
+    }));
+    return {
+        title: config.displayName || "Flexible Financing Program",
+        logoPosition: "right",
+        pages,
+        showQuestionNumbers: "off",
+        questionErrorLocation: "bottom",
+        completedHtml: "<h3>Thank you for completing the form</h3>",
+        showTOC: firstPage.showTOC ?? true,
+        completeText: "Submit",
+        showPreviewBeforeComplete: "showAllQuestions",
+        showProgressBar: firstPage.showProgressBar === false ? "off" : "top",
+        widthMode: "responsive",
+        width: "100%",
+    };
+}
+/**
+ * Map a field definition to SurveyJS element format
+ */
+function mapFieldToSurveyJS(field) {
+    const element = {
+        type: field.type,
+        name: field.name,
+        ...(field.displayName && { title: field.displayName }),
+        isRequired: field.isRequired ?? field.required ?? false,
+        ...(field.maxLength && { maxLength: Number(field.maxLength) }),
+    };
+    if (field.type === "file") {
+        element.storeDataAsText = false;
+    }
+    // Copy other properties
+    const excludeKeys = ["displayName", "required", "category"];
+    Object.keys(field).forEach((key) => {
+        if (!(key in element) && !excludeKeys.includes(key) && field[key] !== undefined) {
+            element[key] = field[key];
+        }
+    });
+    // Store category for grouping
+    element.category = field.category ?? "";
+    return element;
+}
+/**
+ * Resolve all fields from a page to full field definitions
+ */
+export function resolvePageFields(page, fields) {
+    return page.fields
+        .map(ref => resolveFieldReference(ref, fields))
+        .filter((f) => f !== null)
+        .map(f => applyDynamicTitles(f));
+}
+/**
+ * Get category name from category ID (supports string or number IDs)
+ */
+export function getCategoryName(categoryId, categories) {
+    if (categoryId === undefined)
+        return "Other";
+    const cat = categories.find(c => c.id === categoryId);
+    return cat?.name || "Other";
+}
+export function groupFieldsByCategory(fields, categories) {
+    const groups = [];
+    let currentGroup = null;
+    for (const field of fields) {
+        const category = field.category ?? "";
+        if (!currentGroup || currentGroup.category !== category) {
+            currentGroup = {
+                category,
+                categoryName: getCategoryName(category, categories),
+                fields: []
+            };
+            groups.push(currentGroup);
+        }
+        currentGroup.fields.push(field);
+    }
+    return groups;
+}

package/dist/survey-generator.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/survey-generator.test.js

@@ -0,0 +1,317 @@
+import { describe, it, expect } from 'vitest';
+import { generateSurveyJson, resolvePageFields, getCategoryName, groupFieldsByCategory, applyDynamicTitles } from './survey-generator.js';
+// ---- Shared fixtures ----
+const categories = [
+    { id: 'personal', name: 'Personal Info' },
+    { id: 'financial', name: 'Financial Details' }
+];
+const baseConfig = {
+    displayName: 'Test Loan Application',
+    categories,
+    fields: {
+        fullName: {
+            type: 'text',
+            displayName: 'Full Name',
+            category: 'personal',
+            required: true
+        },
+        email: {
+            type: 'text',
+            inputType: 'email',
+            displayName: 'Email Address',
+            category: 'personal',
+            required: true
+        },
+        loanAmount: {
+            type: 'number',
+            displayName: 'Loan Amount',
+            category: 'financial',
+            min: 1000,
+            max: 500000,
+            required: true
+        },
+        termsAccepted: {
+            type: 'boolean',
+            displayName: 'Accept Terms',
+            category: 'personal',
+            required: false
+        }
+    },
+    pages: [
+        {
+            id: 'page1',
+            title: 'Application',
+            showTOC: true,
+            showProgressBar: true,
+            showCategoryHeadings: true,
+            fields: ['fullName', 'email', 'loanAmount', 'termsAccepted']
+        }
+    ]
+};
+// ---- generateSurveyJson ----
+describe('generateSurveyJson', () => {
+    it('should return empty object if config has no pages', () => {
+        const result = generateSurveyJson({ ...baseConfig, pages: [] });
+        expect(result).toEqual({});
+    });
+    it('should return empty object if config.pages is undefined', () => {
+        const { pages, ...noPagesConfig } = baseConfig;
+        const result = generateSurveyJson(noPagesConfig);
+        expect(result).toEqual({});
+    });
+    it('should return empty object if only page is "success-message"', () => {
+        const result = generateSurveyJson({
+            ...baseConfig,
+            pages: [{ id: 'success-message', title: 'Done', fields: [] }]
+        });
+        expect(result).toEqual({});
+    });
+    it('should generate valid SurveyJS JSON from a config', () => {
+        const result = generateSurveyJson(baseConfig);
+        expect(result).toHaveProperty('title', 'Test Loan Application');
+        expect(result).toHaveProperty('pages');
+        expect(Array.isArray(result.pages)).toBe(true);
+    });
+    it('should use displayName as title or fall back to default', () => {
+        const noNameConfig = { ...baseConfig, displayName: undefined };
+        const result = generateSurveyJson(noNameConfig);
+        expect(result.title).toBe('Flexible Financing Program');
+    });
+    it('should group fields by category into separate pages', () => {
+        const result = generateSurveyJson(baseConfig);
+        expect(result.pages.length).toBe(2); // personal + financial
+        expect(result.pages[0].title).toBe('Personal Info');
+        expect(result.pages[1].title).toBe('Financial Details');
+    });
+    it('should hide category headings when showCategoryHeadings is false', () => {
+        const config = {
+            ...baseConfig,
+            pages: [{
+                    id: 'page1',
+                    title: 'Test',
+                    showCategoryHeadings: false,
+                    fields: ['fullName']
+                }]
+        };
+        const result = generateSurveyJson(config);
+        expect(result.pages[0].title).toBe('');
+    });
+    it('should set showTOC from page config', () => {
+        const result = generateSurveyJson(baseConfig);
+        expect(result.showTOC).toBe(true);
+    });
+    it('should set showProgressBar to "off" when disabled', () => {
+        const config = {
+            ...baseConfig,
+            pages: [{ id: 'page1', title: 'Test', showProgressBar: false, fields: ['fullName'] }]
+        };
+        const result = generateSurveyJson(config);
+        expect(result.showProgressBar).toBe('off');
+    });
+    it('should set storeDataAsText=false for file fields', () => {
+        const config = {
+            ...baseConfig,
+            fields: {
+                ...baseConfig.fields,
+                upload: { type: 'file', displayName: 'Upload', category: 'personal' }
+            },
+            pages: [{ id: 'page1', title: 'Test', fields: ['upload'] }]
+        };
+        const result = generateSurveyJson(config);
+        const fileElement = result.pages[0].elements[0].elements.find((e) => e.name === 'upload');
+        expect(fileElement.storeDataAsText).toBe(false);
+    });
+    it('should set isRequired based on field config', () => {
+        const result = generateSurveyJson(baseConfig);
+        const personalElements = result.pages[0].elements[0].elements;
+        const fullNameEl = personalElements.find((e) => e.name === 'fullName');
+        const termsEl = personalElements.find((e) => e.name === 'termsAccepted');
+        expect(fullNameEl.isRequired).toBe(true);
+        expect(termsEl.isRequired).toBe(false);
+    });
+    it('should apply maxLength when specified', () => {
+        const config = {
+            ...baseConfig,
+            fields: {
+                name: { type: 'text', displayName: 'Name', category: 'personal', maxLength: 50 }
+            },
+            pages: [{ id: 'page1', title: 'Test', fields: ['name'] }]
+        };
+        const result = generateSurveyJson(config);
+        const el = result.pages[0].elements[0].elements[0];
+        expect(el.maxLength).toBe(50);
+    });
+});
+// ---- resolvePageFields ----
+describe('resolvePageFields', () => {
+    it('should resolve simple string field references', () => {
+        const page = { id: 'p1', title: 'Test', fields: ['fullName', 'email'] };
+        const resolved = resolvePageFields(page, baseConfig.fields);
+        expect(resolved).toHaveLength(2);
+        expect(resolved[0].name).toBe('fullName');
+        expect(resolved[1].name).toBe('email');
+    });
+    it('should resolve ref-with-overrides', () => {
+        const page = {
+            id: 'p1',
+            title: 'Test',
+            fields: [
+                { ref: 'fullName', displayName: 'Your Name', required: false }
+            ]
+        };
+        const resolved = resolvePageFields(page, baseConfig.fields);
+        expect(resolved).toHaveLength(1);
+        expect(resolved[0].displayName).toBe('Your Name');
+        expect(resolved[0].required).toBe(false);
+        expect(resolved[0].isRequired).toBe(false);
+    });
+    it('should resolve inline definitions', () => {
+        const page = {
+            id: 'p1',
+            title: 'Test',
+            fields: [
+                { definition: { name: 'customField', type: 'text', displayName: 'Custom' } }
+            ]
+        };
+        const resolved = resolvePageFields(page, baseConfig.fields);
+        expect(resolved).toHaveLength(1);
+        expect(resolved[0].name).toBe('customField');
+        expect(resolved[0].type).toBe('text');
+    });
+    it('should filter out unresolvable references', () => {
+        const page = {
+            id: 'p1',
+            title: 'Test',
+            fields: ['fullName', 'nonExistent', 'email']
+        };
+        const resolved = resolvePageFields(page, baseConfig.fields);
+        expect(resolved).toHaveLength(2);
+        expect(resolved.map(f => f.name)).toEqual(['fullName', 'email']);
+    });
+    it('should normalize required/isRequired on resolved fields', () => {
+        const page = { id: 'p1', title: 'Test', fields: ['fullName'] };
+        const resolved = resolvePageFields(page, baseConfig.fields);
+        // fullName has required: true, normalizeField should set both
+        expect(resolved[0].required).toBe(true);
+        expect(resolved[0].isRequired).toBe(true);
+    });
+    it('should apply dynamic titles for bank_statement fields', () => {
+        const fields = {
+            bank_statement_t1: { type: 'file', displayName: 'Bank Statement', category: 'financial' }
+        };
+        const page = { id: 'p1', title: 'Test', fields: ['bank_statement_t1'] };
+        const resolved = resolvePageFields(page, fields);
+        expect(resolved[0].displayName).toContain('Bank Statement (');
+    });
+    it('should apply dynamic titles for financials field', () => {
+        const fields = {
+            financials: { type: 'file', displayName: 'Financial Statement', category: 'financial' }
+        };
+        const page = { id: 'p1', title: 'Test', fields: ['financials'] };
+        const resolved = resolvePageFields(page, fields);
+        expect(resolved[0].displayName).toContain('Audited Financial Statement (');
+    });
+});
+// ---- getCategoryName ----
+describe('getCategoryName', () => {
+    it('should return category name when ID matches', () => {
+        expect(getCategoryName('personal', categories)).toBe('Personal Info');
+        expect(getCategoryName('financial', categories)).toBe('Financial Details');
+    });
+    it('should return "Other" for undefined categoryId', () => {
+        expect(getCategoryName(undefined, categories)).toBe('Other');
+    });
+    it('should return "Other" for unrecognized categoryId', () => {
+        expect(getCategoryName('nonexistent', categories)).toBe('Other');
+    });
+    it('should return "Other" for empty categories array', () => {
+        expect(getCategoryName('personal', [])).toBe('Other');
+    });
+});
+// ---- groupFieldsByCategory ----
+describe('groupFieldsByCategory', () => {
+    const makeField = (name, category) => ({
+        name,
+        type: 'text',
+        category,
+        required: true,
+        isRequired: true
+    });
+    it('should group fields by category in order', () => {
+        const fields = [
+            makeField('a', 'personal'),
+            makeField('b', 'personal'),
+            makeField('c', 'financial'),
+            makeField('d', 'financial')
+        ];
+        const groups = groupFieldsByCategory(fields, categories);
+        expect(groups).toHaveLength(2);
+        expect(groups[0].category).toBe('personal');
+        expect(groups[0].categoryName).toBe('Personal Info');
+        expect(groups[0].fields).toHaveLength(2);
+        expect(groups[1].category).toBe('financial');
+        expect(groups[1].fields).toHaveLength(2);
+    });
+    it('should create separate groups for interleaved categories', () => {
+        const fields = [
+            makeField('a', 'personal'),
+            makeField('b', 'financial'),
+            makeField('c', 'personal')
+        ];
+        const groups = groupFieldsByCategory(fields, categories);
+        // Categories alternate, so 3 groups: personal, financial, personal
+        expect(groups).toHaveLength(3);
+        expect(groups[0].category).toBe('personal');
+        expect(groups[1].category).toBe('financial');
+        expect(groups[2].category).toBe('personal');
+    });
+    it('should return empty array for empty fields', () => {
+        const groups = groupFieldsByCategory([], categories);
+        expect(groups).toEqual([]);
+    });
+    it('should use "Other" for fields with no matching category', () => {
+        const fields = [makeField('a', 'unknown')];
+        const groups = groupFieldsByCategory(fields, categories);
+        expect(groups[0].categoryName).toBe('Other');
+    });
+    it('should handle fields with undefined category', () => {
+        const field = makeField('a', '');
+        field.category = undefined;
+        const groups = groupFieldsByCategory([field], categories);
+        expect(groups[0].category).toBe('');
+        expect(groups[0].categoryName).toBe('Other');
+    });
+});
+// ---- applyDynamicTitles ----
+describe('applyDynamicTitles', () => {
+    const makeField = (name, displayName) => ({
+        name,
+        type: 'file',
+        displayName,
+        required: true,
+        isRequired: true
+    });
+    it('should transform bank_statement_t1 with month label', () => {
+        const result = applyDynamicTitles(makeField('bank_statement_t1', 'Bank Statement'));
+        expect(result.displayName).toMatch(/^Bank Statement \(\w+\)$/);
+    });
+    it('should transform bank_statement_t3 with 3-month-ago label', () => {
+        const result = applyDynamicTitles(makeField('bank_statement_t3'));
+        expect(result.displayName).toMatch(/^Bank Statement \(\w+\)$/);
+    });
+    it('should transform financials field with year label', () => {
+        const result = applyDynamicTitles(makeField('financials', 'Financial Statement'));
+        const expectedYear = (new Date().getFullYear() - 1).toString();
+        expect(result.displayName).toBe(`Audited Financial Statement (${expectedYear})`);
+    });
+    it('should not modify regular fields', () => {
+        const field = makeField('fullName', 'Full Name');
+        const result = applyDynamicTitles(field);
+        expect(result.displayName).toBe('Full Name');
+    });
+    it('should not modify fields with similar but non-matching names', () => {
+        const field = makeField('bank_statement', 'Statement');
+        const result = applyDynamicTitles(field);
+        expect(result.displayName).toBe('Statement');
+    });
+});

package/dist/utils.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Utility functions for @finsys/core
+ */
+export declare function getPastMonthLabel(monthsAgo: number): string;
+export 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.
+ */
+export declare function evaluateExpression(expression: string, data: any): boolean;