@esheet/builder 0.0.3 → 0.0.4-1

package/dist/lib/EsheetBuilder.d.ts

@@ -0,0 +1,46 @@
+import React from 'react';
+import { type FormDefinition } from '@esheet/core';
+import { type BuilderTools, type FieldSummary } from './builder-tools.js';
+export { FormStoreContext, UIContext, useFormStore, useUI, } from '@esheet/fields';
+export declare const InstanceIdContext: React.Context<string>;
+/** Hook to access the per-instance ID for unique DOM element IDs. */
+export declare function useInstanceId(): string;
+export type { BuilderTools, FieldSummary };
+export interface EsheetBuilderProps {
+    /** Initial form definition to load. Also accepts SurveyJS, MCP elicitation, or FHIR Questionnaire schemas, which are auto-converted. */
+    definition?: FormDefinition | Record<string, unknown>;
+    /** Callback fired when the form definition changes. */
+    onChange?: (definition: FormDefinition) => void;
+    /**
+     * Called once after the builder mounts, providing a narrow `BuilderTools`
+     * facade for MCP / AI tool integrations. Not intended for general developer use —
+     * everything a developer needs is available through the builder's own UI and props.
+     */
+    onBuilderToolsReady?: (tools: BuilderTools) => void;
+    /** Whether drag-and-drop reordering is enabled (default: true). When false, field reordering is disabled entirely — no fallback UI (e.g. arrow buttons) is shown. */
+    dragEnabled?: boolean;
+    /** Additional CSS class name. */
+    className?: string;
+    /** Optional content rendered below the header (e.g. custom status/debug panels). */
+    children?: React.ReactNode;
+    /**
+     * Enable touch-optimized mode with larger touch targets in preview mode.
+     * - `true`: Always enable touch mode
+     * - `false`: Never enable touch mode (CSS media query still applies)
+     * - `'auto'`: Enable based on viewport width (<980px) via JavaScript
+     * - `undefined`: Rely on CSS media query only (default)
+     */
+    touchMode?: boolean | 'auto';
+    /** Called when touch mode changes (via auto-detection or programmatic toggle). */
+    onTouchModeChange?: (enabled: boolean) => void;
+}
+export interface EsheetBuilderHandle {
+    /** Returns true if touch mode is currently enabled */
+    isTouchModeEnabled: () => boolean;
+    /** Toggle touch mode on/off. Only works when touchMode prop is 'auto' or undefined. */
+    setTouchMode: (enabled: boolean) => void;
+    /** Reset to auto-detection mode (clears manual override). Only works when touchMode='auto'. */
+    resetTouchMode: () => void;
+}
+export declare const EsheetBuilder: React.ForwardRefExoticComponent<EsheetBuilderProps & React.RefAttributes<EsheetBuilderHandle>>;
+//# sourceMappingURL=EsheetBuilder.d.ts.map

package/dist/lib/EsheetBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EsheetBuilder.d.ts","sourceRoot":"","sources":["../../src/lib/EsheetBuilder.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAGL,KAAK,cAAc,EAGpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,oBAAoB,CAAC;AA2B5B,OAAO,EACL,gBAAgB,EAChB,SAAS,EACT,YAAY,EACZ,KAAK,GACN,MAAM,gBAAgB,CAAC;AACxB,eAAO,MAAM,iBAAiB,uBAAkC,CAAC;AAEjE,qEAAqE;AACrE,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAGD,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,CAAC;AAM3C,MAAM,WAAW,kBAAkB;IACjC,wIAAwI;IACxI,UAAU,CAAC,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtD,uDAAuD;IACvD,QAAQ,CAAC,EAAE,CAAC,UAAU,EAAE,cAAc,KAAK,IAAI,CAAC;IAChD;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IACpD,qKAAqK;IACrK,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC7B,kFAAkF;IAClF,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CAChD;AAED,MAAM,WAAW,mBAAmB;IAClC,sDAAsD;IACtD,kBAAkB,EAAE,MAAM,OAAO,CAAC;IAClC,uFAAuF;IACvF,YAAY,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACzC,+FAA+F;IAC/F,cAAc,EAAE,MAAM,IAAI,CAAC;CAC5B;AAMD,eAAO,MAAM,aAAa,gGAuMxB,CAAC"}

package/dist/lib/EsheetBuilder.js

@@ -0,0 +1,111 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from 'react';
+import { useSyncExternalStore } from 'react';
+import { createFormStore, createUIStore, } from '@esheet/core';
+import { createBuilderTools, } from './builder-tools.js';
+import { FormStoreContext, UIContext, useTouchMode } from '@esheet/fields';
+import { convertSurveyJS, isSurveyJSSchema, importFromMcp, isMcpElicitationRequest, importFromFhir, isFhirQuestionnaire, } from '@esheet/adapters';
+import { Canvas } from './components/Canvas.js';
+import { ToolPanel } from './components/ToolPanel.js';
+import { EditPanel } from './components/edit-panel/EditPanel.js';
+import { BuilderHeader } from './components/BuilderHeader.js';
+import { CodeView } from './components/CodeView.js';
+import { PlusIcon } from './icons.js';
+import { ensureDefaultFieldComponentsRegistered } from './register-defaults.js';
+import { MobileBottomDrawer } from './components/MobileBottomDrawer.js';
+import { Switch } from '@mieweb/ui';
+// ---------------------------------------------------------------------------
+// Contexts
+// ---------------------------------------------------------------------------
+export { FormStoreContext, UIContext, useFormStore, useUI, } from '@esheet/fields';
+export const InstanceIdContext = React.createContext('');
+/** Hook to access the per-instance ID for unique DOM element IDs. */
+export function useInstanceId() {
+    return React.useContext(InstanceIdContext);
+}
+// ---------------------------------------------------------------------------
+// Component
+// ---------------------------------------------------------------------------
+export const EsheetBuilder = React.forwardRef(function EsheetBuilder({ definition, onChange, onBuilderToolsReady, dragEnabled = true, className = '', children, touchMode: touchModeProp, onTouchModeChange, }, ref) {
+    ensureDefaultFieldComponentsRegistered();
+    const formRef = React.useRef(null);
+    const uiRef = React.useRef(null);
+    if (!formRef.current) {
+        let resolved;
+        if (isFhirQuestionnaire(definition)) {
+            resolved = importFromFhir(definition);
+        }
+        else if (isSurveyJSSchema(definition)) {
+            resolved = convertSurveyJS(definition);
+        }
+        else if (isMcpElicitationRequest(definition)) {
+            const mcpReq = definition;
+            if (mcpReq.params.mode !== 'url') {
+                resolved = importFromMcp(mcpReq.params.requestedSchema, { mcpId: mcpReq.id, mcpMessage: mcpReq.params.message });
+            }
+        }
+        else {
+            resolved = definition;
+        }
+        formRef.current = createFormStore(resolved);
+    }
+    if (!uiRef.current) {
+        uiRef.current = createUIStore();
+    }
+    const form = formRef.current;
+    const ui = uiRef.current;
+    // Stable per-instance ID for unique DOM element IDs
+    const instanceId = React.useId();
+    // Subscribe to mode for conditional rendering
+    const mode = useSyncExternalStore((cb) => ui.subscribe(cb), () => ui.getState().mode, () => ui.getState().mode);
+    const selectedFieldId = useSyncExternalStore((cb) => ui.subscribe(cb), () => ui.getState().selectedFieldId, () => ui.getState().selectedFieldId);
+    const editModalOpen = useSyncExternalStore((cb) => ui.subscribe(cb), () => ui.getState().editModalOpen, () => ui.getState().editModalOpen);
+    const [toolsModalOpen, setToolsModalOpen] = React.useState(false);
+    // Touch mode state using shared hook
+    const { isTouchEnabled, isManualOverride, setTouchMode, resetTouchMode } = useTouchMode({ mode: touchModeProp, onChange: onTouchModeChange });
+    // Expose ref API for touch mode
+    React.useImperativeHandle(ref, () => ({
+        isTouchModeEnabled: () => isTouchEnabled,
+        setTouchMode,
+        resetTouchMode,
+    }), [isTouchEnabled, setTouchMode, resetTouchMode]);
+    React.useEffect(() => {
+        if (mode !== 'build') {
+            setToolsModalOpen(false);
+            ui.getState().setEditModalOpen(false);
+        }
+    }, [mode, ui]);
+    React.useEffect(() => {
+        if (!selectedFieldId && editModalOpen) {
+            ui.getState().setEditModalOpen(false);
+        }
+    }, [selectedFieldId, editModalOpen, ui]);
+    // Subscribe to form changes and forward to onChange.
+    React.useEffect(() => {
+        if (!onChange)
+            return;
+        return form.subscribe(() => {
+            onChange(form.getState().hydrateDefinition());
+        });
+    }, [form, onChange]);
+    // Expose a narrow BuilderTools facade to MCP / AI tool callers once on mount.
+    React.useEffect(() => {
+        if (onBuilderToolsReady)
+            onBuilderToolsReady(createBuilderTools(form));
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [form]);
+    // Apply disabled class when user explicitly disabled touch mode (prevents CSS media query)
+    const applyTouchDisabledClass = isManualOverride && !isTouchEnabled;
+    // Build root class string
+    const rootClasses = [
+        'ms-builder-root',
+        isTouchEnabled && 'esheet-touch-active',
+        applyTouchDisabledClass && 'touch-mode-disabled',
+        'ms:flex ms:h-full ms:flex-1 ms:min-h-0 ms:max-h-full ms:w-full ms:min-w-0 ms:max-w-[1440px] ms:mx-auto ms:flex-col ms:gap-2',
+        'ms:overflow-x-hidden ms:bg-msbackground ms:text-mstext',
+        className,
+    ]
+        .filter(Boolean)
+        .join(' ');
+    return (_jsx(FormStoreContext.Provider, { value: form, children: _jsx(UIContext.Provider, { value: ui, children: _jsx(InstanceIdContext.Provider, { value: instanceId, children: _jsxs("div", { className: rootClasses, children: [_jsx("div", { className: "ms:sticky ms:top-0 ms:z-40 ms:bg-msbackground", children: _jsx(BuilderHeader, {}) }), children, mode === 'build' && (_jsxs("div", { className: "builder-layout ms:grid ms:min-w-0 ms:grid-cols-1 ms:lg:grid-cols-[18rem_minmax(0,1fr)_340px] ms:gap-3", children: [_jsx("aside", { className: "panel-tools-wrap panel-tools ms:hidden ms:lg:flex ms:self-start ms:min-h-0 ms:max-h-[calc(100dvh-12.5rem)] ms:overflow-y-auto ms:flex-col ms:rounded-lg ms:border ms:border-msborder ms:bg-mssurface", children: _jsx(ToolPanel, {}) }), _jsxs("main", { className: "panel-canvas ms:min-w-0 ms:self-start ms:max-h-[calc(100dvh-12.5rem)] ms:overflow-hidden ms:flex ms:flex-col ms:rounded-lg ms:border ms:border-msborder ms:bg-mssurface", children: [_jsx(Canvas, { form: form, ui: ui, dragEnabled: dragEnabled }), _jsx("div", { className: "ms:lg:hidden ms:sticky ms:bottom-0 ms:z-20 ms:pt-2 ms:pb-3 ms:flex ms:justify-center ms:pointer-events-none", children: _jsxs("button", { type: "button", onClick: () => setToolsModalOpen(true), className: "ms:pointer-events-auto ms:inline-flex ms:items-center ms:gap-1.5 ms:px-3.5 ms:py-2 ms:rounded-full ms:bg-mssurface/95 ms:backdrop-blur-sm ms:text-mstext ms:text-sm ms:font-semibold ms:border ms:border-msprimary/35 ms:shadow-lg ms:shadow-msprimary/10 ms:outline-none ms:focus:outline-none ms:hover:bg-mssurface ms:hover:border-msprimary/50 ms:hover:shadow-xl ms:hover:shadow-msprimary/15 ms:transition-all", "aria-label": "Open add field tools", children: [_jsx(PlusIcon, { className: "ms:w-3.5 ms:h-3.5 ms:text-msprimary" }), _jsx("span", { children: "Add field" })] }) })] }), _jsx("aside", { className: "panel-editor-wrap panel-editor ms:hidden ms:lg:flex ms:self-start ms:min-h-0 ms:max-h-[calc(100dvh-12.5rem)] ms:overflow-y-auto ms:flex-col ms:rounded-lg ms:border ms:border-msborder ms:bg-mssurface", children: _jsx(EditPanel, {}) }), _jsx(MobileBottomDrawer, { title: "Add Field", open: toolsModalOpen, onClose: () => setToolsModalOpen(false), children: _jsx(ToolPanel, {}) }), _jsx(MobileBottomDrawer, { title: "Edit Field", open: editModalOpen && !!selectedFieldId, onClose: () => ui.getState().setEditModalOpen(false), children: _jsx(EditPanel, {}) })] })), mode === 'code' && (_jsx("div", { className: "code-layout ms:flex ms:h-[calc(100dvh-12.5rem)] ms:min-h-0 ms:min-w-0 ms:overflow-hidden ms:rounded-lg ms:border ms:border-msborder ms:bg-mssurface", children: _jsx(CodeView, { form: form, ui: ui }) })), mode === 'preview' && (_jsxs("div", { className: "preview-layout ms:flex-1 ms:min-h-0 ms:min-w-0 ms:w-full ms:max-w-2xl ms:mx-auto ms:p-4 ms:max-h-[calc(100dvh-12.5rem)] ms:overflow-y-auto", children: [_jsx("div", { className: "ms:flex ms:items-center ms:justify-end ms:mb-3", children: _jsx(Switch, { size: "sm", checked: isTouchEnabled, onCheckedChange: setTouchMode, label: "Touch Mode" }) }), _jsx(Canvas, { form: form, ui: ui, dragEnabled: false })] }))] }) }) }) }));
+});

package/dist/lib/builder-tools.d.ts

@@ -0,0 +1,107 @@
+import type { AddFieldOptions, FieldType, FieldTypeMeta, FormStore } from '@esheet/core';
+/** Summary of a single field, suitable for AI context. */
+export interface FieldSummary {
+    id: string;
+    fieldType: string;
+    question: string | undefined;
+    required: boolean;
+    options: {
+        id: string;
+        value: string;
+    }[];
+    rows: {
+        id: string;
+        value: string;
+    }[];
+    columns: {
+        id: string;
+        value: string;
+    }[];
+    /** Which tool family to use: 'add_option' for option-based fields, 'add_row / add_column' for matrix fields. */
+    editWith: string;
+    /** True if this field has conditional logic rules attached. Use get_field to inspect them. */
+    hasRules: boolean;
+    /** Required value format for structured input types (date, datetime-local, month, time). Use this exact format when calling fill_field. */
+    valueFormat?: string;
+    /** True if this field already has a response value. False means it is still empty and needs to be filled. */
+    hasValue: boolean;
+    /** Section child fields (only present when fieldType === 'section'). */
+    children?: FieldSummary[];
+}
+/**
+ * Narrow interface exposed to MCP / AI tools via `onBuilderToolsReady`.
+ * Only the operations an external AI agent needs — no raw store internals.
+ */
+export interface BuilderTools {
+    /** Add a new field. Returns the generated ID, or null for unknown type. */
+    addField: (fieldType: FieldType, opts?: AddFieldOptions) => string | null;
+    /** Patch a field's properties. Returns false if the field was not found. */
+    updateField: (fieldId: string, patch: Record<string, unknown>) => boolean;
+    /** Remove a field. Returns false if not found. */
+    removeField: (fieldId: string) => boolean;
+    /** Find a field ID by exact ID or partial question match. */
+    resolveFieldId: (fieldId?: string, fieldQuestion?: string) => string | undefined;
+    /** Replace the entire form with a new definition. */
+    resetForm: (definition: {
+        id?: string;
+        fields: Record<string, unknown>[];
+    }) => void;
+    /** Generate a form from a list of plain question descriptors. */
+    generateForm: (questions: {
+        question: string;
+        fieldType?: string;
+        required?: boolean;
+        inputType?: string;
+        options?: string[];
+    }[]) => string;
+    /** Snapshot of the current form suitable for AI context. */
+    getFormSummary: () => {
+        formId: string;
+        fieldCount: number;
+        fields: FieldSummary[];
+    };
+    /** Set a response value for a field (for testing in preview mode). Returns true on success, false if field not found, or an error string if the value format is invalid. */
+    fillField: (fieldId: string, value: unknown) => boolean | string;
+    /** Clear all responses. */
+    clearResponses: () => void;
+    /** Get current responses keyed by field ID. */
+    getResponses: () => Record<string, unknown>;
+    /** Granular option mutations (radio, check, dropdown, etc.). */
+    option: {
+        add: (fieldId: string, value?: string) => string | null;
+        update: (fieldId: string, optionId: string, value: string) => boolean;
+        remove: (fieldId: string, optionId: string) => boolean;
+    };
+    /** Granular row mutations (matrix fields). */
+    row: {
+        add: (fieldId: string, value?: string) => string | null;
+        update: (fieldId: string, rowId: string, value: string) => boolean;
+        remove: (fieldId: string, rowId: string) => boolean;
+    };
+    /** Granular column mutations (matrix fields). */
+    column: {
+        add: (fieldId: string, value?: string) => string | null;
+        update: (fieldId: string, columnId: string, value: string) => boolean;
+        remove: (fieldId: string, columnId: string) => boolean;
+    };
+    /** Move a field to a new index. */
+    moveField: (fieldId: string, toIndex: number, toParentId?: string | null) => boolean;
+    /** Get a single field node by ID. */
+    getField: (fieldId: string) => import('@esheet/core').FieldNode | undefined;
+    /** List all registered field type keys and their labels. */
+    getFieldTypes: () => {
+        key: string;
+        label: string;
+        category: string;
+        hasOptions: boolean;
+        hasMatrix: boolean;
+    }[];
+    /** Get full spec for a single field type (properties, capabilities, defaults). */
+    getFieldSpec: (fieldType: string) => FieldTypeMeta | undefined;
+    /** Export the full form definition tree (inverse of loadDefinition). */
+    getDefinition: () => import('@esheet/core').FormDefinition;
+    /** Update the form's top-level ID without replacing fields. */
+    setFormId: (id: string) => void;
+}
+export declare function createBuilderTools(form: FormStore): BuilderTools;
+//# sourceMappingURL=builder-tools.d.ts.map

package/dist/lib/builder-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder-tools.d.ts","sourceRoot":"","sources":["../../src/lib/builder-tools.ts"],"names":[],"mappings":"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"}

package/dist/lib/builder-tools.js

@@ -0,0 +1,321 @@
+// ---------------------------------------------------------------------------
+// BuilderTools — narrow facade for MCP / AI tool callers only.
+// Normal developers interact with the builder entirely through its props/UI.
+// ---------------------------------------------------------------------------
+import { getFieldTypeMeta, getRegisteredFieldTypes, hydrateDefinition, } from '@esheet/core';
+export function createBuilderTools(form) {
+    function resolveFieldId(fieldId, fieldQuestion) {
+        if (fieldId)
+            return fieldId;
+        if (fieldQuestion) {
+            const q = fieldQuestion.toLowerCase();
+            const { normalized } = form.getState();
+            for (const id of Object.keys(normalized.byId)) {
+                const question = normalized.byId[id].definition.question;
+                if (question?.toLowerCase().includes(q))
+                    return id;
+            }
+        }
+        return undefined;
+    }
+    return {
+        resetForm: (definition) => form.getState().loadDefinition(definition),
+        generateForm: (questions) => {
+            const fields = questions.map((q, i) => ({
+                id: `f${i + 1}`,
+                fieldType: q.fieldType ?? 'text',
+                question: q.question,
+                ...(q.required !== undefined && { required: q.required }),
+                ...(q.inputType && { inputType: q.inputType }),
+                ...(q.options && {
+                    options: q.options.map((v, j) => ({ id: `o${j + 1}`, value: v })),
+                }),
+            }));
+            form.getState().loadDefinition({
+                id: form.getState().formId,
+                fields: [],
+            });
+            form.getState().loadDefinition({
+                id: form.getState().formId,
+                fields,
+            });
+            const summary = fields
+                .map((f, i) => `${i + 1}. ${f.question} (${f.fieldType})`)
+                .join(', ');
+            return `Form generated with ${fields.length} field(s): ${summary}`;
+        },
+        addField: (fieldType, opts) => form.getState().addField(fieldType, opts),
+        updateField: (fieldId, patch) => form.getState().updateField(fieldId, patch),
+        removeField: (fieldId) => form.getState().removeField(fieldId),
+        resolveFieldId,
+        fillField: (fieldId, value) => {
+            const { normalized } = form.getState();
+            const node = normalized.byId[fieldId];
+            if (!node)
+                return false;
+            const def = node.definition;
+            function normalizeTextValue(v, inputType) {
+                if (!v)
+                    return v;
+                switch (inputType) {
+                    case 'date':
+                        if (/^\d{4}-\d{2}-\d{2}$/.test(v))
+                            return v;
+                        if (/^\d{4}-\d{2}$/.test(v))
+                            return `${v}-01`;
+                        if (/^\d{4}$/.test(v))
+                            return `${v}-01-01`;
+                        return null;
+                    case 'month':
+                        if (/^\d{4}-\d{2}$/.test(v))
+                            return v;
+                        if (/^\d{4}-\d{2}-\d{2}$/.test(v))
+                            return v.slice(0, 7);
+                        return null;
+                    case 'datetime-local': {
+                        const n = v.replace(' ', 'T');
+                        if (/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/.test(n))
+                            return n;
+                        if (/^\d{4}-\d{2}-\d{2}$/.test(n))
+                            return `${n}T00:00`;
+                        return null;
+                    }
+                    case 'time': {
+                        if (/^\d{2}:\d{2}$/.test(v))
+                            return v;
+                        const m = v.match(/^(\d{1,2}):(\d{2})\s*(AM|PM)$/i);
+                        if (m) {
+                            let h = parseInt(m[1], 10);
+                            if (m[3].toUpperCase() === 'AM' && h === 12)
+                                h = 0;
+                            if (m[3].toUpperCase() === 'PM' && h !== 12)
+                                h += 12;
+                            return `${String(h).padStart(2, '0')}:${m[2]}`;
+                        }
+                        return null;
+                    }
+                    default:
+                        return v;
+                }
+            }
+            let response;
+            if (def.fieldType === 'singlematrix' &&
+                value !== null &&
+                typeof value === 'object') {
+                const rows = def.rows ?? [];
+                const columns = def.columns ?? [];
+                const existing = (form.getState().responses[fieldId]?.selected ??
+                    {});
+                const selected = {
+                    ...existing,
+                };
+                const entries = Array.isArray(value)
+                    ? value.map((v, i) => [rows[i]?.value ?? String(i), v])
+                    : Object.entries(value);
+                for (const [rowKey, colVal] of entries) {
+                    const row = rows.find((r) => r.value.toLowerCase() === rowKey.toLowerCase() || r.id === rowKey);
+                    if (!row)
+                        continue;
+                    const colStr = String(colVal);
+                    const col = columns.find((c) => c.value.toLowerCase() === colStr.toLowerCase() ||
+                        c.id === colStr) ?? columns[parseInt(colStr, 10)];
+                    if (col)
+                        selected[row.id] = { id: col.id, value: col.value };
+                }
+                response = { selected };
+            }
+            else if (def.fieldType === 'multimatrix' &&
+                value !== null &&
+                typeof value === 'object') {
+                const rows = def.rows ?? [];
+                const columns = def.columns ?? [];
+                const existing = (form.getState().responses[fieldId]?.selected ??
+                    {});
+                const selected = {
+                    ...existing,
+                };
+                const entries = Array.isArray(value)
+                    ? value.map((v, i) => [rows[i]?.value ?? String(i), v])
+                    : Object.entries(value);
+                for (const [rowKey, colVals] of entries) {
+                    const row = rows.find((r) => r.value.toLowerCase() === rowKey.toLowerCase() || r.id === rowKey);
+                    if (!row)
+                        continue;
+                    const colValArr = Array.isArray(colVals)
+                        ? colVals
+                        : [colVals];
+                    const matched = colValArr
+                        .map((v) => {
+                        const s = String(v);
+                        return columns.find((c) => c.value.toLowerCase() === s.toLowerCase() || c.id === s);
+                    })
+                        .filter((c) => c != null);
+                    if (matched.length > 0)
+                        selected[row.id] = matched;
+                }
+                response = { selected };
+            }
+            else if (['radio', 'dropdown', 'boolean', 'rating', 'slider'].includes(def.fieldType)) {
+                const opts = def.options ?? [];
+                const match = opts.find((o) => o.value.toLowerCase() === String(value).toLowerCase() ||
+                    o.id === value);
+                const numVal = Number(value);
+                const numMatch = !match && !isNaN(numVal)
+                    ? opts[numVal - 1] ?? opts[numVal]
+                    : undefined;
+                const resolved = match ?? numMatch;
+                response = resolved
+                    ? { selected: { id: resolved.id, value: resolved.value } }
+                    : { selected: undefined };
+            }
+            else if (def.fieldType === 'check' ||
+                def.fieldType === 'multiselectdropdown') {
+                const opts = def.options ?? [];
+                const vals = Array.isArray(value) ? value : [value];
+                const matches = opts.filter((o) => vals.some((v) => o.value.toLowerCase() === String(v).toLowerCase() || o.id === v));
+                response = {
+                    selected: matches.map((o) => ({ id: o.id, value: o.value })),
+                };
+            }
+            else if (def.fieldType === 'ranking') {
+                const opts = def.options ?? [];
+                const vals = Array.isArray(value) ? value : [value];
+                const ordered = vals
+                    .map((v) => opts.find((o) => o.value.toLowerCase() === String(v).toLowerCase() || o.id === v))
+                    .filter((o) => o != null);
+                const mentioned = new Set(ordered.map((o) => o.id));
+                const remaining = opts.filter((o) => !mentioned.has(o.id));
+                response = { selected: [...ordered, ...remaining] };
+            }
+            else if (def.fieldType === 'multitext') {
+                const opts = def.options ?? [];
+                const vals = Array.isArray(value)
+                    ? value
+                    : typeof value === 'object' && value !== null
+                        ? Object.values(value)
+                        : [value];
+                const multitextAnswers = {};
+                opts.forEach((opt, i) => {
+                    if (vals[i] != null)
+                        multitextAnswers[opt.id] = String(vals[i]);
+                });
+                response = { multitextAnswers };
+            }
+            else {
+                if (value == null) {
+                    response = { answer: undefined };
+                }
+                else {
+                    const normalized = normalizeTextValue(String(value), def.inputType);
+                    if (normalized === null) {
+                        const fmt = {
+                            date: 'YYYY-MM-DD',
+                            'datetime-local': 'YYYY-MM-DDTHH:mm',
+                            month: 'YYYY-MM',
+                            time: 'HH:mm',
+                        };
+                        const expected = fmt[def.inputType ?? ''];
+                        return expected
+                            ? `Error: invalid value for inputType "${def.inputType}" — expected format ${expected}`
+                            : `Error: invalid value for field`;
+                    }
+                    response = { answer: normalized };
+                }
+            }
+            form
+                .getState()
+                .setResponse(fieldId, { ...response, _ai: true });
+            return true;
+        },
+        clearResponses: () => form.getState().resetResponses(),
+        getResponses: () => form.getState().responses,
+        option: {
+            add: (fieldId, value) => form.getState().addOption(fieldId, value),
+            update: (fieldId, optionId, value) => form.getState().updateOption(fieldId, optionId, value),
+            remove: (fieldId, optionId) => form.getState().removeOption(fieldId, optionId),
+        },
+        row: {
+            add: (fieldId, value) => form.getState().addRow(fieldId, value),
+            update: (fieldId, rowId, value) => form.getState().updateRow(fieldId, rowId, value),
+            remove: (fieldId, rowId) => form.getState().removeRow(fieldId, rowId),
+        },
+        column: {
+            add: (fieldId, value) => form.getState().addColumn(fieldId, value),
+            update: (fieldId, columnId, value) => form.getState().updateColumn(fieldId, columnId, value),
+            remove: (fieldId, columnId) => form.getState().removeColumn(fieldId, columnId),
+        },
+        moveField: (fieldId, toIndex, toParentId) => form.getState().moveField(fieldId, toIndex, toParentId),
+        getField: (fieldId) => form.getState().getField(fieldId),
+        getFieldTypes: () => getRegisteredFieldTypes().map((key) => {
+            const meta = getFieldTypeMeta(key);
+            return {
+                key,
+                label: meta.label,
+                category: meta.category,
+                hasOptions: meta.hasOptions,
+                hasMatrix: meta.hasMatrix,
+            };
+        }),
+        getFieldSpec: (fieldType) => getFieldTypeMeta(fieldType),
+        getDefinition: () => {
+            const { normalized, formId } = form.getState();
+            return {
+                id: formId,
+                fields: hydrateDefinition(normalized),
+            };
+        },
+        setFormId: (id) => form.getState().setFormId(id),
+        getFormSummary: () => {
+            const { normalized, formId } = form.getState();
+            const INPUT_TYPE_FORMAT = {
+                date: 'YYYY-MM-DD',
+                'datetime-local': 'YYYY-MM-DDTHH:mm',
+                month: 'YYYY-MM',
+                time: 'HH:mm',
+            };
+            function summarizeField(id) {
+                const node = normalized.byId[id];
+                const def = node.definition;
+                const isMatrix = def.fieldType === 'singlematrix' || def.fieldType === 'multimatrix';
+                const isSection = def.fieldType === 'section';
+                const base = {
+                    id,
+                    fieldType: def.fieldType,
+                    question: isSection
+                        ? def.title
+                        : def.question,
+                    required: def.required ?? false,
+                    options: def.options ?? [],
+                    rows: def.rows ?? [],
+                    columns: def.columns ?? [],
+                    editWith: isMatrix
+                        ? 'add_row / add_column (NOT add_option)'
+                        : 'add_option',
+                    hasRules: (def.rules?.length ?? 0) > 0,
+                    hasValue: (() => {
+                        const r = form.getState().responses[id];
+                        return (r != null &&
+                            Object.values(r).some((v) => v != null &&
+                                v !== '' &&
+                                !(Array.isArray(v) && v.length === 0) &&
+                                !(typeof v === 'object' &&
+                                    !Array.isArray(v) &&
+                                    Object.keys(v).length === 0)));
+                    })(),
+                    ...(def.inputType && INPUT_TYPE_FORMAT[def.inputType]
+                        ? { valueFormat: INPUT_TYPE_FORMAT[def.inputType] }
+                        : {}),
+                };
+                if (isSection && node.childIds.length > 0) {
+                    return { ...base, children: node.childIds.map(summarizeField) };
+                }
+                return base;
+            }
+            return {
+                formId,
+                fieldCount: Object.keys(normalized.byId).length,
+                fields: normalized.rootIds.map(summarizeField),
+            };
+        },
+    };
+}

package/dist/lib/components/BuilderHeader.d.ts

@@ -0,0 +1,7 @@
+export interface BuilderHeaderProps {
+}
+/**
+ * BuilderHeader — top bar with Build/Code/Preview mode toggle and Import/Export actions.
+ */
+export declare function BuilderHeader(_props: BuilderHeaderProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=BuilderHeader.d.ts.map

package/dist/lib/components/BuilderHeader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BuilderHeader.d.ts","sourceRoot":"","sources":["../../../src/lib/components/BuilderHeader.tsx"],"names":[],"mappings":"AAuCA,MAAM,WAAW,kBAAkB;CAAG;AAmLtC;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,kBAAkB,2CAgnBvD"}