@genesislcap/foundation-forms 14.396.4 → 14.397.1-alpha-87a7828.0

package/dist/esm/utils/csv-parser.js

@@ -0,0 +1,458 @@
+import Papa from 'papaparse';
+/**
+ * Parses a CSV string into headers and rows using PapaParse.
+ * Handles quoted fields, escaped quotes, empty values, and mixed line endings.
+ * @param content - The CSV content as a string
+ * @returns The parsed result with headers, rows, and any errors
+ * @public
+ */
+export function parseCsv(content) {
+    var _a, _b, _c;
+    const errors = [];
+    if (!(content === null || content === void 0 ? void 0 : content.trim())) {
+        errors.push('CSV file is empty');
+        return { headers: [], rows: [], errors };
+    }
+    const result = Papa.parse(content, {
+        header: true,
+        skipEmptyLines: true,
+        dynamicTyping: false, // Keep all values as strings; mapCsvToSchema handles type conversion
+    });
+    const headers = (_a = result.meta.fields) !== null && _a !== void 0 ? _a : [];
+    if (headers.length === 0) {
+        errors.push('CSV file has no headers');
+        return { headers: [], rows: [], errors };
+    }
+    // Add PapaParse errors
+    for (const err of result.errors) {
+        errors.push((_b = err.message) !== null && _b !== void 0 ? _b : `Parse error at row ${(_c = err.row) !== null && _c !== void 0 ? _c : '?'}`);
+    }
+    // Ensure all row values are strings (PapaParse may return undefined for missing cells)
+    const rows = result.data.map((row) => {
+        const stringRow = {};
+        for (const header of headers) {
+            const val = row[header];
+            stringRow[header] = val === undefined || val === null ? '' : String(val);
+        }
+        return stringRow;
+    });
+    return { headers, rows, errors };
+}
+/**
+ * Maps CSV rows to schema fields with case-insensitive matching.
+ * Converts values to appropriate types based on schema definition.
+ * @param csvRows - The parsed CSV rows
+ * @param schema - The JSON schema defining the fields
+ * @returns Mapped rows and list of unmapped columns
+ * @public
+ */
+export function mapCsvToSchema(csvRows, schema) {
+    var _a;
+    if (!(schema === null || schema === void 0 ? void 0 : schema.properties) || csvRows.length === 0) {
+        return { mappedRows: [], unmappedColumns: [] };
+    }
+    const schemaFields = Object.keys(schema.properties);
+    // Create case-insensitive mapping from CSV headers to schema fields
+    const headerMapping = new Map();
+    const unmappedColumns = [];
+    if (csvRows.length > 0) {
+        const csvHeaders = Object.keys((_a = csvRows[0]) !== null && _a !== void 0 ? _a : {});
+        for (const csvHeader of csvHeaders) {
+            const normalizedCsvHeader = csvHeader.toUpperCase();
+            const matchedField = schemaFields.find((field) => field.toUpperCase() === normalizedCsvHeader);
+            if (matchedField) {
+                headerMapping.set(csvHeader, matchedField);
+            }
+            else {
+                unmappedColumns.push(csvHeader);
+            }
+        }
+    }
+    // Map each row
+    const mappedRows = csvRows.map((row) => {
+        var _a;
+        const mappedRow = {};
+        for (const [csvHeader, schemaField] of headerMapping) {
+            const rawValue = row[csvHeader];
+            const fieldSchema = (_a = schema.properties) === null || _a === void 0 ? void 0 : _a[schemaField];
+            mappedRow[schemaField] = convertValue(rawValue, fieldSchema);
+        }
+        return mappedRow;
+    });
+    return { mappedRows, unmappedColumns };
+}
+/**
+ * Converts a string value to the appropriate type based on schema.
+ * @param value - The string value from CSV
+ * @param fieldSchema - The JSON schema for this field
+ * @returns The converted value
+ */
+function convertValue(value, fieldSchema) {
+    if (value === '') {
+        return value;
+    }
+    if (!fieldSchema) {
+        return value;
+    }
+    const fieldType = getFieldType(fieldSchema);
+    switch (fieldType) {
+        case 'integer':
+        case 'number': {
+            const num = parseFloat(value);
+            return isNaN(num) ? value : num;
+        }
+        case 'boolean': {
+            const lowerValue = value.toLowerCase();
+            if (['true', 'yes', '1'].includes(lowerValue)) {
+                return true;
+            }
+            if (['false', 'no', '0'].includes(lowerValue)) {
+                return false;
+            }
+            return value;
+        }
+        default:
+            return value;
+    }
+}
+/**
+ * Gets the type from a JSON schema, handling oneOf/anyOf cases.
+ * @param schema - The JSON schema
+ * @returns The field type
+ */
+function getFieldType(schema) {
+    if (schema.type) {
+        return Array.isArray(schema.type) ? schema.type[0] : schema.type;
+    }
+    // Handle oneOf/anyOf by finding the first non-null type
+    const alternatives = schema.oneOf || schema.anyOf;
+    if (alternatives) {
+        for (const alt of alternatives) {
+            if (typeof alt === 'object' && alt.type && alt.type !== 'null') {
+                return Array.isArray(alt.type) ? alt.type[0] : alt.type;
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Generates a CSV template string with headers and sample data based on JSON schema.
+ * If a UI schema is provided, it will be used to determine which fields to include
+ * and in what order. Hidden fields in the UI schema will be excluded.
+ * @param schema - The JSON schema defining the fields
+ * @param uiSchema - Optional UI schema to determine field order and visibility
+ * @param includeOptionalFields - Whether to include optional fields when no UI schema (default: true)
+ * @param includeBom - Whether to prepend UTF-8 BOM for Excel compatibility (default: true)
+ * @returns The CSV template string with headers and one sample row
+ * @public
+ */
+export function generateCsvTemplate(schema, uiSchema, includeOptionalFields = true, includeBom = true) {
+    if (!(schema === null || schema === void 0 ? void 0 : schema.properties)) {
+        return '';
+    }
+    const requiredFields = new Set(schema.required || []);
+    const headers = [];
+    const sampleValues = [];
+    // Get field order from UI schema if provided
+    const fieldsFromUiSchema = uiSchema ? extractFieldsFromUiSchema(uiSchema) : null;
+    if (fieldsFromUiSchema && fieldsFromUiSchema.length > 0) {
+        // Use UI schema order, filtering out hidden fields
+        for (const { fieldName, isHidden } of fieldsFromUiSchema) {
+            // Skip hidden fields
+            if (isHidden) {
+                continue;
+            }
+            // Check if field exists in JSON schema
+            const fieldSchema = schema.properties[fieldName];
+            if (!fieldSchema) {
+                continue;
+            }
+            headers.push(fieldName);
+            const isRequired = requiredFields.has(fieldName);
+            const sampleValue = generateSampleValue(fieldName, fieldSchema, isRequired);
+            sampleValues.push(escapeCsvValue(sampleValue));
+        }
+    }
+    else {
+        // Fall back to JSON schema order
+        for (const [fieldName, fieldSchema] of Object.entries(schema.properties)) {
+            const isRequired = requiredFields.has(fieldName);
+            // Skip optional fields if not including them
+            if (!includeOptionalFields && !isRequired) {
+                continue;
+            }
+            headers.push(fieldName);
+            const fieldDef = fieldSchema;
+            const sampleValue = generateSampleValue(fieldName, fieldDef, isRequired);
+            sampleValues.push(escapeCsvValue(sampleValue));
+        }
+    }
+    if (headers.length === 0) {
+        return '';
+    }
+    // Build CSV content (escape headers in case they contain commas/quotes)
+    const headerRow = headers.map((h) => escapeCsvValue(h)).join(',');
+    const sampleRow = sampleValues.join(',');
+    const content = `${headerRow}\n${sampleRow}`;
+    return includeBom ? '\uFEFF' + content : content;
+}
+/**
+ * Extracts field names from a UI schema in the order they appear.
+ * @param uiSchema - The UI schema to extract fields from
+ * @returns Array of field info with name and hidden status
+ * @internal
+ */
+export function extractFieldsFromUiSchema(uiSchema) {
+    const fields = [];
+    function processElement(element) {
+        var _a, _b;
+        if (element.type === 'Control' && element.scope) {
+            const fieldName = extractFieldNameFromScope(element.scope);
+            if (fieldName) {
+                const isHidden = ((_a = element.options) === null || _a === void 0 ? void 0 : _a.hidden) === true;
+                fields.push({ fieldName, isHidden });
+            }
+        }
+        if (element.elements) {
+            for (const child of element.elements) {
+                processElement(child);
+            }
+        }
+        if ((_b = element.options) === null || _b === void 0 ? void 0 : _b.childElements) {
+            for (const child of element.options.childElements) {
+                processElement(child);
+            }
+        }
+    }
+    if (uiSchema.elements) {
+        for (const element of uiSchema.elements) {
+            processElement(element);
+        }
+    }
+    const schemaOptions = uiSchema.options;
+    const topLevelChildElements = schemaOptions === null || schemaOptions === void 0 ? void 0 : schemaOptions.childElements;
+    if (topLevelChildElements) {
+        for (const element of topLevelChildElements) {
+            processElement(element);
+        }
+    }
+    return fields;
+}
+/**
+ * Extracts the field name from a JSON schema scope string.
+ * @param scope - The scope string (e.g., "#/properties/FIELD_NAME")
+ * @returns The field name or null if not a valid scope
+ * @internal
+ */
+function extractFieldNameFromScope(scope) {
+    const match = scope.match(/^#\/properties\/(.+)$/);
+    return match ? match[1] : null;
+}
+/**
+ * Generates a sample value for a field based on its schema type.
+ * @param fieldName - The name of the field
+ * @param fieldSchema - The JSON schema for this field
+ * @param isRequired - Whether the field is required
+ * @returns A sample value string
+ */
+function generateSampleValue(fieldName, fieldSchema, isRequired) {
+    const fieldType = getFieldType(fieldSchema);
+    // Check for enum values first
+    if (fieldSchema.enum && fieldSchema.enum.length > 0) {
+        return String(fieldSchema.enum[0]);
+    }
+    // Check for const value
+    if (fieldSchema.const !== undefined) {
+        return String(fieldSchema.const);
+    }
+    // Check for default value
+    if (fieldSchema.default !== undefined) {
+        return String(fieldSchema.default);
+    }
+    // Check for examples
+    if (fieldSchema.examples &&
+        Array.isArray(fieldSchema.examples) &&
+        fieldSchema.examples.length > 0) {
+        return String(fieldSchema.examples[0]);
+    }
+    // Generate sample based on type
+    switch (fieldType) {
+        case 'string':
+            return generateStringSample(fieldName, fieldSchema);
+        case 'integer':
+            return generateIntegerSample(fieldSchema);
+        case 'number':
+            return generateNumberSample(fieldSchema);
+        case 'boolean':
+            return 'true';
+        case 'array':
+            return ''; // Arrays typically need special handling
+        case 'object':
+            return ''; // Objects typically need special handling
+        default:
+            // Default to a simple string sample
+            return isRequired ? `sample_${fieldName.toLowerCase()}` : '';
+    }
+}
+/**
+ * Generates a sample string value based on field name and schema.
+ * Uses format hints first, then heuristic inference from field name.
+ * @param fieldName - The name of the field
+ * @param fieldSchema - The JSON schema for this field
+ * @returns A sample string value
+ */
+function generateStringSample(fieldName, fieldSchema) {
+    const lowerName = fieldName.toLowerCase();
+    // Check for format hints
+    if (fieldSchema.format) {
+        switch (fieldSchema.format) {
+            case 'date':
+                return '2024-01-15';
+            case 'date-time':
+                return '2024-01-15T10:30:00Z';
+            case 'time':
+                return '10:30:00';
+            case 'email':
+                return 'user@example.com';
+            case 'uri':
+            case 'url':
+                return 'https://example.com';
+            case 'uuid':
+                return '550e8400-e29b-41d4-a716-446655440000';
+            case 'hostname':
+                return 'example.com';
+            case 'ipv4':
+                return '192.168.1.1';
+            case 'ipv6':
+                return '2001:0db8:85a3:0000:0000:8a2e:0370:7334';
+        }
+    }
+    // Infer from field name
+    if (lowerName.includes('email')) {
+        return 'user@example.com';
+    }
+    if (lowerName.includes('phone') || lowerName.includes('tel')) {
+        return '+1234567890';
+    }
+    if (lowerName.includes('date') || lowerName.includes('time')) {
+        if (lowerName.includes('time') && !lowerName.includes('date')) {
+            return '10:30:00';
+        }
+        return '2024-01-15';
+    }
+    if (lowerName.includes('url') || lowerName.includes('link') || lowerName.includes('website')) {
+        return 'https://example.com';
+    }
+    if (lowerName.includes('name')) {
+        if (lowerName.includes('first')) {
+            return 'John';
+        }
+        if (lowerName.includes('last')) {
+            return 'Doe';
+        }
+        return 'Sample Name';
+    }
+    if (lowerName.includes('address')) {
+        return '123 Main Street';
+    }
+    if (lowerName.includes('city')) {
+        return 'New York';
+    }
+    if (lowerName.includes('country')) {
+        return 'USA';
+    }
+    if (lowerName.includes('description') ||
+        lowerName.includes('comment') ||
+        lowerName.includes('notes')) {
+        return 'Sample description';
+    }
+    if (lowerName.includes('id') || lowerName.includes('code')) {
+        return 'ABC123';
+    }
+    // Check for minLength/maxLength constraints
+    const minLen = fieldSchema.minLength || 0;
+    const DEFAULT_MAX_LENGTH = 50;
+    const maxLen = fieldSchema.maxLength || DEFAULT_MAX_LENGTH;
+    let sample = `Sample ${fieldName}`;
+    if (sample.length < minLen) {
+        sample = sample.padEnd(minLen, '_');
+    }
+    if (sample.length > maxLen) {
+        sample = sample.substring(0, maxLen);
+    }
+    return sample;
+}
+/**
+ * Generates a sample integer value based on schema constraints.
+ * @param fieldSchema - The JSON schema for this field
+ * @returns A sample integer string
+ */
+function generateIntegerSample(fieldSchema) {
+    var _a, _b;
+    const min = (_a = fieldSchema.minimum) !== null && _a !== void 0 ? _a : 0;
+    const max = (_b = fieldSchema.maximum) !== null && _b !== void 0 ? _b : 100;
+    // Use minimum if specified, otherwise use a value in range
+    if (fieldSchema.minimum !== undefined) {
+        return String(Math.ceil(min));
+    }
+    // Return a sensible default within range
+    const value = Math.min(Math.max(1, min), max);
+    return String(Math.floor(value));
+}
+/**
+ * Generates a sample number value based on schema constraints.
+ * @param fieldSchema - The JSON schema for this field
+ * @returns A sample number string
+ */
+function generateNumberSample(fieldSchema) {
+    var _a, _b;
+    const min = (_a = fieldSchema.minimum) !== null && _a !== void 0 ? _a : 0;
+    const max = (_b = fieldSchema.maximum) !== null && _b !== void 0 ? _b : 100;
+    // Use minimum if specified, otherwise use a value in range
+    if (fieldSchema.minimum !== undefined) {
+        return String(min);
+    }
+    // Return a sensible default within range
+    const DEFAULT_NUMERIC_VALUE = 1.5;
+    const value = Math.min(Math.max(DEFAULT_NUMERIC_VALUE, min), max);
+    return String(value);
+}
+/**
+ * Escapes a value for CSV output.
+ * Values containing commas, quotes, or newlines are wrapped in quotes.
+ * Quotes within values are escaped by doubling them.
+ * @param value - The value to escape
+ * @returns The escaped value
+ */
+function escapeCsvValue(value) {
+    if (!value) {
+        return '';
+    }
+    // Check if escaping is needed
+    const needsEscaping = value.includes(',') || value.includes('"') || value.includes('\n') || value.includes('\r');
+    if (needsEscaping) {
+        // Escape quotes by doubling them and wrap in quotes
+        const escaped = value.replace(/"/g, '""');
+        return `"${escaped}"`;
+    }
+    return value;
+}
+/**
+ * Triggers a download of the CSV template file in the browser.
+ * @param csvContent - The CSV content to download
+ * @param fileName - The name for the downloaded file (default: 'template.csv')
+ * @remarks Browser-only; uses document and URL.createObjectURL. Will throw in Node.js.
+ * @public
+ */
+export function downloadCsvTemplate(csvContent, fileName = 'template.csv') {
+    const blob = new Blob([csvContent], { type: 'text/csv;charset=utf-8;' });
+    const url = URL.createObjectURL(blob);
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = fileName;
+    link.style.display = 'none';
+    document.body.appendChild(link);
+    link.click();
+    document.body.removeChild(link);
+    URL.revokeObjectURL(url);
+}

package/dist/esm/utils/index.js

@@ -1,3 +1,4 @@
+export * from './csv-parser';
 export * from './filters';
 export * from './logger';
 export * from './translation';

package/dist/esm/utils/schema-utils.js

@@ -0,0 +1,120 @@
+/**
+ * Extracts the field name from a JSON schema scope string.
+ * @param scope - The scope string (e.g. "#/properties/FIELD_NAME" or "#/properties/obj/properties/FIELD")
+ * @returns The field name or null if not a valid scope
+ * @internal
+ */
+function extractFieldNameFromScope(scope) {
+    const match = scope.match(/^#\/properties\/(.+)$/);
+    return match ? match[1] : null;
+}
+/**
+ * Recursively extracts Control elements from a UI schema in display order.
+ * Used for grid-style array layouts where labels are shown only in the header row.
+ *
+ * @param uiSchema - The UI schema to extract controls from
+ * @returns Array of control info with uischema, label, and field name
+ * @internal
+ */
+export function extractControlsFromUiSchema(uiSchema) {
+    var _a;
+    const controls = [];
+    function processElement(element) {
+        var _a, _b, _c;
+        if (element.type === 'Control' && element.scope) {
+            const fieldName = extractFieldNameFromScope(element.scope);
+            if (fieldName) {
+                const isHidden = ((_a = element.options) === null || _a === void 0 ? void 0 : _a.hidden) === true;
+                if (!isHidden) {
+                    const label = (_b = element.label) !== null && _b !== void 0 ? _b : fieldName;
+                    controls.push({
+                        uischema: element,
+                        label: String(label),
+                        fieldName,
+                    });
+                }
+            }
+        }
+        if (element.elements) {
+            for (const child of element.elements) {
+                processElement(child);
+            }
+        }
+        if ((_c = element.options) === null || _c === void 0 ? void 0 : _c.childElements) {
+            for (const child of element.options.childElements) {
+                processElement(child);
+            }
+        }
+    }
+    if (uiSchema.elements) {
+        for (const element of uiSchema.elements) {
+            processElement(element);
+        }
+    }
+    if ((_a = uiSchema.options) === null || _a === void 0 ? void 0 : _a.childElements) {
+        for (const element of uiSchema.options.childElements) {
+            processElement(element);
+        }
+    }
+    return controls;
+}
+/**
+ * Creates a deep copy of the UI schema with gridView option set to true on all Control elements.
+ * Used for grid-style array layouts so child controls can adapt their behavior.
+ *
+ * @param uiSchema - The UI schema to modify
+ * @returns A new UI schema with gridView option on all controls
+ * @internal
+ */
+export function withGridView(uiSchema) {
+    const clone = structuredClone(uiSchema);
+    function processElement(element) {
+        var _a;
+        if ((element === null || element === void 0 ? void 0 : element.type) === 'Control') {
+            element.options = Object.assign(Object.assign({}, element.options), { gridView: true });
+        }
+        if (element === null || element === void 0 ? void 0 : element.elements) {
+            element.elements.forEach(processElement);
+        }
+        if ((_a = element === null || element === void 0 ? void 0 : element.options) === null || _a === void 0 ? void 0 : _a.childElements) {
+            element.options.childElements.forEach(processElement);
+        }
+    }
+    processElement(clone);
+    return clone;
+}
+/**
+ * Checks if the provided UI schema is already configured for bulk insert mode.
+ * @param uischema - The UI schema to check
+ * @returns true if the schema has a Control element for #/properties/items
+ * @internal
+ */
+export function isBulkUiSchema(uischema) {
+    var _a;
+    return (_a = uischema === null || uischema === void 0 ? void 0 : uischema.elements) === null || _a === void 0 ? void 0 : _a.some((element) => element.scope === '#/properties/items' && element.type === 'Control');
+}
+/**
+ * Generates a UI schema suitable for bulk insert mode with array control.
+ * @param userProvidedUiSchema - Optional user-provided UI schema to use as childUiSchema
+ * @returns A UI schema configured for bulk insert
+ * @internal
+ */
+export function generateBulkUiSchema(userProvidedUiSchema) {
+    const options = {
+        addLabel: 'Add another',
+        deleteLabel: '',
+    };
+    if (userProvidedUiSchema) {
+        options.childUiSchema = userProvidedUiSchema;
+    }
+    return {
+        type: 'VerticalLayout',
+        elements: [
+            {
+                type: 'Control',
+                scope: '#/properties/items',
+                options,
+            },
+        ],
+    };
+}

package/dist/esm/utils/validation.js

@@ -48,6 +48,8 @@ const describeError = (prop, parentProps) => {
 /**
  * Computes a human-friendly anyOf error message for a given control path.
  * Prefers UI schema custom message, then JSON schema errorMessage.anyOf, then a constructed fallback.
+ *
+ * @public
  */
 export const getAnyOfErrorMessage = (errors, schema, controlPath, uiCustomMsg) => {
     var _a, _b, _c;