@esheet/adapters 0.0.3

package/dist/lib/surveyjs-converter.js

@@ -0,0 +1,698 @@
+/**
+ * Convert SurveyJS schema to eSheet FormDefinition.
+ *
+ * SurveyJS is well-known with lots of training data, so AI models
+ * generate better SurveyJS output. We leverage this by having AI
+ * generate SurveyJS, then converting to eSheet format.
+ */
+// ---------------------------------------------------------------------------
+// Type Mapping
+// ---------------------------------------------------------------------------
+const TYPE_MAP = {
+    text: 'text',
+    comment: 'longtext',
+    radiogroup: 'radio',
+    checkbox: 'check',
+    dropdown: 'dropdown',
+    tagbox: 'multiselectdropdown',
+    boolean: 'boolean',
+    rating: 'rating',
+    ranking: 'ranking',
+    matrix: 'singlematrix',
+    matrixdropdown: 'multimatrix',
+    matrixdynamic: 'multimatrix',
+    signaturepad: 'signature',
+    image: 'image',
+    html: 'html',
+    expression: 'html',
+    imagepicker: 'radio',
+    file: 'text',
+    panel: 'section',
+    paneldynamic: 'section',
+    multipletext: 'multitext',
+};
+const INPUT_TYPE_MAP = {
+    // Direct matches
+    text: 'string',
+    string: 'string',
+    number: 'number',
+    email: 'email',
+    tel: 'tel',
+    date: 'date',
+    'datetime-local': 'datetime-local',
+    month: 'month',
+    time: 'time',
+    url: 'url',
+    // SurveyJS aliases
+    color: 'string',
+    password: 'string',
+    range: 'number',
+    week: 'date',
+    datetime: 'datetime-local',
+    datetimelocal: 'datetime-local',
+};
+function mapInputType(surveyInputType) {
+    if (typeof surveyInputType !== 'string')
+        return 'string';
+    const normalized = surveyInputType.toLowerCase().replace(/[_\s]/g, '');
+    return INPUT_TYPE_MAP[normalized] ?? 'string';
+}
+// ---------------------------------------------------------------------------
+// Converters
+// ---------------------------------------------------------------------------
+function toKebabCase(str) {
+    if (typeof str !== 'string')
+        return '';
+    return str
+        .replace(/([a-z])([A-Z])/g, '$1-$2')
+        .replace(/[\s_]+/g, '-')
+        .toLowerCase();
+}
+function convertChoice(choice, index) {
+    if (typeof choice === 'string') {
+        return { id: toKebabCase(choice) || `opt-${index}`, value: choice };
+    }
+    return {
+        id: toKebabCase(choice.value) || `opt-${index}`,
+        value: choice.value,
+        text: choice.text,
+        score: choice.score,
+    };
+}
+function convertMatrixRow(item, index) {
+    if (typeof item === 'string') {
+        return { id: toKebabCase(item) || `item-${index}`, value: item };
+    }
+    return {
+        id: toKebabCase(item.value) || `item-${index}`,
+        value: item.text ?? item.value,
+    };
+}
+function convertMatrixColumn(item, index) {
+    if (typeof item === 'string') {
+        return { id: toKebabCase(item) || `item-${index}`, value: item };
+    }
+    return {
+        id: toKebabCase(item.value) || `item-${index}`,
+        value: item.text ?? item.value,
+        score: item.score,
+    };
+}
+/**
+ * Parse SurveyJS visibleIf expression into eSheet rules.
+ *
+ * Simple expressions like `{gender} = 'female'` become field conditions.
+ * Complex expressions with arithmetic or multiple fields become expression conditions.
+ */
+function parseVisibleIf(expr, effect) {
+    if (typeof expr !== 'string')
+        return null;
+    const trimmed = expr.trim();
+    if (!trimmed)
+        return null;
+    // Count field references - if more than one, it's a complex expression
+    const fieldRefs = trimmed.match(/\{[^}]+\}/g) ?? [];
+    // Check for arithmetic operators between field refs
+    const hasArithmetic = /\{[^}]+\}\s*[+\-*/]\s*\{/.test(trimmed);
+    // Simple pattern: {fieldName} op 'value' (single field, no arithmetic)
+    if (fieldRefs.length === 1 && !hasArithmetic) {
+        // Note: >= and <= must come before > and < in the alternation (regex is first-match)
+        const simpleMatch = trimmed.match(/^\{([^}]+)\}\s*(==|!=|<>|>=|<=|=|>|<|empty|notempty)\s*'?([^']*)'?$/i);
+        if (simpleMatch) {
+            const [, targetId, op, rawExpected] = simpleMatch;
+            const expected = rawExpected.trim();
+            const operatorMap = {
+                '==': 'equals',
+                '!=': 'notEquals',
+                '<>': 'notEquals',
+                '>=': 'greaterThanOrEqual',
+                '<=': 'lessThanOrEqual',
+                '=': 'equals',
+                '>': 'greaterThan',
+                '<': 'lessThan',
+                empty: 'empty',
+                notempty: 'notEmpty',
+            };
+            const operator = operatorMap[op.toLowerCase()] ?? 'equals';
+            // Normalize expected value for boolean comparisons
+            // SurveyJS uses true/false, eSheet uses yes/no option IDs
+            let normalizedExpected = expected;
+            if (operator === 'empty' || operator === 'notEmpty') {
+                normalizedExpected = '';
+            }
+            else if (expected.toLowerCase() === 'true') {
+                normalizedExpected = 'yes';
+            }
+            else if (expected.toLowerCase() === 'false') {
+                normalizedExpected = 'no';
+            }
+            const condition = {
+                conditionType: 'field',
+                targetId: toKebabCase(targetId),
+                operator,
+                expected: normalizedExpected,
+            };
+            return {
+                effect,
+                logic: 'AND',
+                conditions: [condition],
+            };
+        }
+    }
+    // Complex expression: use expression condition type
+    // Convert SurveyJS field syntax {fieldName} to eSheet syntax
+    const eSheetExpr = trimmed.replace(/\{([^}]+)\}/g, (_, fieldName) => `{${toKebabCase(fieldName)}}`);
+    return {
+        effect,
+        logic: 'AND',
+        conditions: [
+            {
+                conditionType: 'expression',
+                expression: eSheetExpr,
+            },
+        ],
+    };
+}
+function convertElement(element, ancestorIds = new Set()) {
+    const fieldType = TYPE_MAP[element.type] ?? 'text';
+    const id = toKebabCase(element.name);
+    // Preserve original SurveyJS metadata for lossless round-trip export.
+    const _sourceData = {
+        surveyType: element.type,
+        surveyName: element.name,
+        ...(element.visibleIf ? { visibleIf: element.visibleIf } : {}),
+        ...(element.enableIf ? { enableIf: element.enableIf } : {}),
+        ...(element.requiredIf ? { requiredIf: element.requiredIf } : {}),
+        ...(element.placeholder !== undefined
+            ? { placeholder: element.placeholder }
+            : {}),
+        ...(element.defaultValue !== undefined
+            ? { defaultValue: element.defaultValue }
+            : {}),
+        ...(element.defaultValueExpression !== undefined
+            ? { defaultValueExpression: element.defaultValueExpression }
+            : {}),
+        ...(element.min !== undefined ? { min: element.min } : {}),
+        ...(element.max !== undefined ? { max: element.max } : {}),
+        ...(element.step !== undefined ? { step: element.step } : {}),
+        ...(element.rateMin !== undefined ? { rateMin: element.rateMin } : {}),
+        ...(element.rateMax !== undefined ? { rateMax: element.rateMax } : {}),
+        ...(element.rateStep !== undefined ? { rateStep: element.rateStep } : {}),
+        ...(element.minRateDescription !== undefined
+            ? { minRateDescription: element.minRateDescription }
+            : {}),
+        ...(element.maxRateDescription !== undefined
+            ? { maxRateDescription: element.maxRateDescription }
+            : {}),
+        ...(element.showOtherItem !== undefined
+            ? { showOtherItem: element.showOtherItem }
+            : {}),
+        ...(element.otherText !== undefined
+            ? { otherText: element.otherText }
+            : {}),
+        ...(element.showNoneItem !== undefined
+            ? { showNoneItem: element.showNoneItem }
+            : {}),
+        ...(element.noneText !== undefined ? { noneText: element.noneText } : {}),
+        ...(element.showSelectAllItem !== undefined
+            ? { showSelectAllItem: element.showSelectAllItem }
+            : {}),
+        ...(element.selectAllText !== undefined
+            ? { selectAllText: element.selectAllText }
+            : {}),
+        ...(element.storeOthersAsComment !== undefined
+            ? { storeOthersAsComment: element.storeOthersAsComment }
+            : {}),
+        ...(element.colCount !== undefined ? { colCount: element.colCount } : {}),
+        ...(element.allowMultiple !== undefined
+            ? { allowMultiple: element.allowMultiple }
+            : {}),
+        ...(element.acceptedTypes !== undefined
+            ? { acceptedTypes: element.acceptedTypes }
+            : {}),
+    };
+    // Build rules from visibleIf/enableIf/requiredIf
+    const rules = [];
+    if (element.visibleIf) {
+        const rule = parseVisibleIf(element.visibleIf, 'visible');
+        if (rule)
+            rules.push(rule);
+    }
+    if (element.enableIf) {
+        const rule = parseVisibleIf(element.enableIf, 'enable');
+        if (rule)
+            rules.push(rule);
+    }
+    if (element.requiredIf) {
+        const rule = parseVisibleIf(element.requiredIf, 'required');
+        if (rule)
+            rules.push(rule);
+    }
+    // Base field
+    const base = {
+        id,
+        question: element.title ?? element.name,
+        required: element.isRequired ?? false,
+        rules,
+        _sourceData,
+    };
+    // Type-specific properties
+    switch (fieldType) {
+        case 'text':
+            return {
+                ...base,
+                fieldType: 'text',
+                inputType: mapInputType(element.inputType),
+            };
+        case 'longtext':
+            return {
+                ...base,
+                fieldType: 'longtext',
+                inputType: 'string',
+            };
+        case 'radio':
+        case 'dropdown':
+        case 'check':
+        case 'multiselectdropdown':
+            return {
+                ...base,
+                fieldType,
+                options: (element.choices ?? []).map(convertChoice),
+            };
+        case 'boolean':
+            return {
+                ...base,
+                fieldType: 'boolean',
+                options: [
+                    { id: 'yes', value: 'Yes' },
+                    { id: 'no', value: 'No' },
+                ],
+            };
+        case 'rating': {
+            let options;
+            if (element.choices && element.choices.length > 0) {
+                options = element.choices.map(convertChoice);
+            }
+            else {
+                // Generate from rateMin/rateMax/rateStep
+                const min = typeof element.rateMin === 'number' ? element.rateMin : 1;
+                const max = typeof element.rateMax === 'number' ? element.rateMax : 5;
+                const step = typeof element.rateStep === 'number' && element.rateStep > 0
+                    ? element.rateStep
+                    : 1;
+                options = [];
+                for (let n = min; n <= max; n += step) {
+                    options.push({ id: String(n), value: String(n) });
+                }
+            }
+            return { ...base, fieldType: 'rating', options };
+        }
+        case 'ranking':
+            return {
+                ...base,
+                fieldType: 'ranking',
+                options: (element.choices ?? []).map(convertChoice),
+            };
+        case 'singlematrix':
+        case 'multimatrix': {
+            const rows = (element.rows ?? []).map(convertMatrixRow);
+            const columns = (element.columns ?? []).map(convertMatrixColumn);
+            // Check if any column has an explicit score
+            const hasScores = columns.some((col) => col.score !== undefined);
+            return {
+                ...base,
+                fieldType,
+                rows,
+                columns,
+                // Enable scored mode if any column has scores
+                ...(hasScores ? { scored: true } : {}),
+            };
+        }
+        case 'signature':
+            return {
+                ...base,
+                fieldType: 'signature',
+            };
+        case 'image':
+            return {
+                ...base,
+                fieldType: 'image',
+                imageUri: element.imageLink ?? '',
+                altText: element.altText,
+            };
+        case 'html':
+            return {
+                ...base,
+                fieldType: 'html',
+                // 'expression' type: render the expression string as HTML placeholder
+                htmlContent: element.type === 'expression'
+                    ? element.expression ?? ''
+                    : element.html ?? '',
+            };
+        case 'multitext':
+            return {
+                ...base,
+                fieldType: 'multitext',
+                options: (element.items ?? []).map((item, idx) => ({
+                    id: toKebabCase(item.name) || `item-${idx}`,
+                    value: item.name,
+                    text: item.title ?? item.name,
+                })),
+            };
+        case 'section': {
+            // Guard against circular nesting (AI can generate panels referencing ancestor IDs)
+            if (ancestorIds.has(id)) {
+                return { ...base, fieldType: 'text', inputType: 'string' };
+            }
+            const childAncestors = new Set(ancestorIds).add(id);
+            return {
+                ...base,
+                fieldType: 'section',
+                title: element.title ?? element.name,
+                fields: (element.elements ?? []).map((el) => convertElement(el, childAncestors)),
+            };
+        }
+        default:
+            return {
+                ...base,
+                fieldType: 'text',
+                inputType: 'string',
+            };
+    }
+}
+/**
+ * Convert a SurveyJS schema to eSheet FormDefinition.
+ */
+export function convertSurveyJSToESheet(survey) {
+    const fields = [];
+    // Collect survey-level metadata for round-trip fidelity
+    const surveyMeta = {};
+    if (survey.locale !== undefined)
+        surveyMeta.locale = survey.locale;
+    if (survey.logo !== undefined)
+        surveyMeta.logo = survey.logo;
+    if (survey.logoPosition !== undefined)
+        surveyMeta.logoPosition = survey.logoPosition;
+    if (survey.showProgressBar !== undefined)
+        surveyMeta.showProgressBar = survey.showProgressBar;
+    if (survey.progressBarType !== undefined)
+        surveyMeta.progressBarType = survey.progressBarType;
+    if (survey.completedHtml !== undefined)
+        surveyMeta.completedHtml = survey.completedHtml;
+    if (survey.showQuestionNumbers !== undefined)
+        surveyMeta.showQuestionNumbers = survey.showQuestionNumbers;
+    if (survey.questionTitleLocation !== undefined)
+        surveyMeta.questionTitleLocation = survey.questionTitleLocation;
+    if (survey.calculatedValues !== undefined)
+        surveyMeta.calculatedValues = survey.calculatedValues;
+    if (survey.triggers !== undefined)
+        surveyMeta.triggers = survey.triggers;
+    const hasSurveyMeta = Object.keys(surveyMeta).length > 0;
+    // Handle pages (convert each page to a section)
+    if (survey.pages && survey.pages.length > 0) {
+        for (const page of survey.pages) {
+            if (!page.elements || page.elements.length === 0)
+                continue;
+            // If only one page, flatten elements directly
+            if (survey.pages.length === 1) {
+                fields.push(...page.elements.map((el) => convertElement(el)));
+            }
+            else {
+                // Multiple pages become sections
+                const sectionId = toKebabCase(page.name ?? page.title ?? 'page');
+                const sectionAncestors = new Set([sectionId]);
+                fields.push({
+                    id: sectionId,
+                    fieldType: 'section',
+                    question: '',
+                    required: false,
+                    rules: [],
+                    title: page.title ?? page.name ?? 'Section',
+                    fields: page.elements.map((el) => convertElement(el, sectionAncestors)),
+                });
+            }
+        }
+    }
+    // Handle top-level elements (no pages)
+    if (survey.elements) {
+        fields.push(...survey.elements.map((el) => convertElement(el)));
+    }
+    return {
+        id: toKebabCase(survey.title ?? 'form'),
+        title: survey.title ?? 'Untitled Form',
+        description: survey.description,
+        fields,
+        ...(hasSurveyMeta ? { _sourceData: { surveyMeta } } : {}),
+    };
+}
+/**
+ * System prompt for generating SurveyJS format.
+ * AI models have better training data for SurveyJS.
+ */
+export const SURVEYJS_SYSTEM_PROMPT = `You are an expert form designer. Output ONLY a valid SurveyJS JSON schema — no markdown, no explanation, no code blocks, raw JSON only. STRUCTURE: {"title":"...","pages":[{"name":"page1","title":"...","elements":[...]}]} FIELD TYPES — always pick most specific: short text→text (add inputType:"email"/"tel"/"date"/"number"/"url"), long text→comment, single choice→radiogroup (NOT text), multiple choice→checkbox (NOT text), long list single→dropdown, long list multi→tagbox, yes/no→boolean (NOT radiogroup), 1-N scale→rating (set rateMin/rateMax/minRateDescription/maxRateDescription), ordered preference→ranking, grid single answer→matrix (rows=items columns=scale labels), grid multi answer→matrixdropdown, signature→signaturepad (NEVER use text), file upload→file, image pick→imagepicker, multiple short inputs→multipletext. RULES: use pages only to group related fields — never use panel type; every page must have a title; add "isRequired":true on important fields; use "visibleIf" for follow-up questions: "{field} = 'value'"; choices format: [{"value":"id","text":"Label"}]. For scored surveys: use numeric strings as column values ("0","1","2","3"), add calculatedValues at top level. OUTPUT: raw JSON only, no prose.`;
+// ---------------------------------------------------------------------------
+// Export: FormDefinition → SurveyJS schema
+// ---------------------------------------------------------------------------
+const FIELD_TYPE_TO_SURVEY = {
+    text: 'text',
+    longtext: 'comment',
+    radio: 'radiogroup',
+    check: 'checkbox',
+    dropdown: 'dropdown',
+    multiselectdropdown: 'tagbox',
+    boolean: 'boolean',
+    rating: 'rating',
+    ranking: 'ranking',
+    singlematrix: 'matrix',
+    multimatrix: 'matrixdropdown',
+    signature: 'signaturepad',
+    image: 'image',
+    html: 'html',
+    multitext: 'multipletext',
+    section: 'panel',
+};
+const ESHEET_INPUT_TO_SURVEY = {
+    string: 'text',
+    number: 'number',
+    email: 'email',
+    tel: 'tel',
+    date: 'date',
+    'datetime-local': 'datetime-local',
+    month: 'month',
+    time: 'time',
+    url: 'url',
+};
+const OPERATOR_TO_SURVEY = {
+    equals: '=',
+    notEquals: '<>',
+    greaterThan: '>',
+    lessThan: '<',
+    greaterThanOrEqual: '>=',
+    lessThanOrEqual: '<=',
+    empty: 'empty',
+    notEmpty: 'notempty',
+};
+function conditionToSurveyExpr(condition) {
+    if (condition.conditionType === 'expression') {
+        return condition.expression ?? '';
+    }
+    const op = OPERATOR_TO_SURVEY[condition.operator ?? 'equals'] ?? '=';
+    if (op === 'empty' || op === 'notempty') {
+        return `{${condition.targetId}} ${op}`;
+    }
+    return `{${condition.targetId}} ${op} '${condition.expected}'`;
+}
+function ruleToSurveyExpr(rule) {
+    const sep = rule.logic === 'OR' ? ' or ' : ' and ';
+    return rule.conditions.map(conditionToSurveyExpr).join(sep);
+}
+function fieldToSurveyElement(field) {
+    const meta = field._sourceData;
+    // Restore original SurveyJS name if available; otherwise convert id back
+    const name = meta?.surveyName ?? field.id;
+    // Restore original SurveyJS type if available; otherwise use reverse map
+    const type = meta?.surveyType ?? FIELD_TYPE_TO_SURVEY[field.fieldType] ?? 'text';
+    const el = { type, name };
+    if (field.question !== undefined)
+        el.title = field.question;
+    if (field.required)
+        el.isRequired = true;
+    // Restore conditional expressions verbatim from _sourceData for lossless round-trip.
+    // Fall back to re-constructing from parsed rules.
+    const visibleRule = field.rules?.find((r) => r.effect === 'visible');
+    const enableRule = field.rules?.find((r) => r.effect === 'enable');
+    const requiredRule = field.rules?.find((r) => r.effect === 'required');
+    if (meta?.visibleIf)
+        el.visibleIf = meta.visibleIf;
+    else if (visibleRule)
+        el.visibleIf = ruleToSurveyExpr(visibleRule);
+    if (meta?.enableIf)
+        el.enableIf = meta.enableIf;
+    else if (enableRule)
+        el.enableIf = ruleToSurveyExpr(enableRule);
+    if (meta?.requiredIf)
+        el.requiredIf = meta.requiredIf;
+    else if (requiredRule)
+        el.requiredIf = ruleToSurveyExpr(requiredRule);
+    // Restore extra element props from _sourceData for round-trip fidelity
+    if (meta?.placeholder !== undefined)
+        el.placeholder = meta.placeholder;
+    if (meta?.defaultValue !== undefined)
+        el.defaultValue = meta.defaultValue;
+    if (meta?.defaultValueExpression !== undefined)
+        el.defaultValueExpression = meta.defaultValueExpression;
+    if (meta?.min !== undefined)
+        el.min = meta.min;
+    if (meta?.max !== undefined)
+        el.max = meta.max;
+    if (meta?.step !== undefined)
+        el.step = meta.step;
+    if (meta?.rateMin !== undefined)
+        el.rateMin = meta.rateMin;
+    if (meta?.rateMax !== undefined)
+        el.rateMax = meta.rateMax;
+    if (meta?.rateStep !== undefined)
+        el.rateStep = meta.rateStep;
+    if (meta?.minRateDescription !== undefined)
+        el.minRateDescription = meta.minRateDescription;
+    if (meta?.maxRateDescription !== undefined)
+        el.maxRateDescription = meta.maxRateDescription;
+    if (meta?.showOtherItem !== undefined)
+        el.showOtherItem = meta.showOtherItem;
+    if (meta?.otherText !== undefined)
+        el.otherText = meta.otherText;
+    if (meta?.showNoneItem !== undefined)
+        el.showNoneItem = meta.showNoneItem;
+    if (meta?.noneText !== undefined)
+        el.noneText = meta.noneText;
+    if (meta?.showSelectAllItem !== undefined)
+        el.showSelectAllItem = meta.showSelectAllItem;
+    if (meta?.selectAllText !== undefined)
+        el.selectAllText = meta.selectAllText;
+    if (meta?.storeOthersAsComment !== undefined)
+        el.storeOthersAsComment = meta.storeOthersAsComment;
+    if (meta?.colCount !== undefined)
+        el.colCount = meta.colCount;
+    if (meta?.allowMultiple !== undefined)
+        el.allowMultiple = meta.allowMultiple;
+    if (meta?.acceptedTypes !== undefined)
+        el.acceptedTypes = meta.acceptedTypes;
+    // Type-specific properties
+    switch (field.fieldType) {
+        case 'text':
+        case 'longtext': {
+            const inputType = field.inputType;
+            if (inputType && inputType !== 'string') {
+                el.inputType = ESHEET_INPUT_TO_SURVEY[inputType] ?? inputType;
+            }
+            break;
+        }
+        case 'radio':
+        case 'check':
+        case 'dropdown':
+        case 'multiselectdropdown':
+        case 'ranking':
+        case 'rating':
+            el.choices = (field.options ?? []).map((o) => o.text !== undefined
+                ? {
+                    value: o.value,
+                    text: o.text,
+                    ...(o.score !== undefined ? { score: o.score } : {}),
+                }
+                : o.value);
+            break;
+        case 'singlematrix':
+        case 'multimatrix':
+            el.rows = (field.rows ?? []).map((r) => ({ value: r.id, text: r.value }));
+            el.columns = (field.columns ?? []).map((c) => ({
+                value: c.id,
+                text: c.value,
+                ...(c.score !== undefined ? { score: c.score } : {}),
+            }));
+            break;
+        case 'image':
+            if (field.imageUri)
+                el.imageLink = field.imageUri;
+            if (field.altText)
+                el.altText = field.altText;
+            break;
+        case 'html':
+            // expression type: restore expression property instead of html
+            if (type === 'expression') {
+                el.expression = field.htmlContent ?? '';
+            }
+            else {
+                el.html = field.htmlContent ?? '';
+            }
+            break;
+        case 'multitext':
+            el.items = (field.options ?? []).map((o) => ({
+                name: o.value,
+                title: o.text ?? o.value,
+            }));
+            break;
+        case 'section':
+            el.elements = (field.fields ?? []).map(fieldToSurveyElement);
+            break;
+    }
+    return el;
+}
+/**
+ * Convert an eSheet FormDefinition back to a SurveyJS schema.
+ *
+ * Preserves original SurveyJS element names, types, and conditional expressions
+ * stored in `_sourceData` during import, enabling a lossless round-trip.
+ * Fields without `_sourceData` are reverse-mapped from eSheet types.
+ *
+ * Section fields become pages; non-section fields are placed in a single page.
+ */
+export function exportToSurveyJS(form) {
+    // Restore survey-level metadata preserved during import
+    const surveyMeta = form._sourceData
+        ?.surveyMeta ?? {};
+    const hasSections = form.fields.some((f) => f.fieldType === 'section');
+    if (hasSections) {
+        // Each top-level section becomes a page; non-section fields go into a leading page.
+        const pages = [];
+        const topLevelFields = form.fields.filter((f) => f.fieldType !== 'section');
+        if (topLevelFields.length > 0) {
+            pages.push({
+                name: 'page1',
+                elements: topLevelFields.map(fieldToSurveyElement),
+            });
+        }
+        for (const field of form.fields) {
+            if (field.fieldType !== 'section')
+                continue;
+            const meta = field._sourceData;
+            pages.push({
+                name: meta?.surveyName ?? field.id,
+                title: field.title ?? field.question,
+                elements: (field.fields ?? []).map(fieldToSurveyElement),
+            });
+        }
+        return {
+            title: form.title,
+            ...(form.description ? { description: form.description } : {}),
+            ...surveyMeta,
+            pages,
+        };
+    }
+    // No sections — single page
+    return {
+        title: form.title,
+        ...(form.description ? { description: form.description } : {}),
+        ...surveyMeta,
+        pages: [{ name: 'page1', elements: form.fields.map(fieldToSurveyElement) }],
+    };
+}
+/**
+ * Convert a SurveyJS schema to eSheet FormDefinition.
+ * Primary named export matching the importFromMcp / exportToMcp naming convention.
+ */
+export const importFromSurveyJS = convertSurveyJSToESheet;
+/**
+ * Convert a SurveyJS schema to eSheet FormDefinition.
+ * Alias for importFromSurveyJS / convertSurveyJSToESheet.
+ */
+export const convertSurveyJS = convertSurveyJSToESheet;