@esheet/builder 0.0.4-0 → 0.0.4-1

package/dist/index.js

@@ -4133,116 +4133,6 @@ var Cd = Kt(
 );
 da.displayName = "Slider";
 var Ed = Kt(
-  [
-    "w-full px-3 py-2",
-    "border border-input rounded-lg",
-    "bg-background text-foreground",
-    "placeholder:text-muted-foreground",
-    "transition-colors duration-200",
-    "focus:outline-none focus:ring-2 focus:ring-ring focus:border-transparent",
-    "disabled:cursor-not-allowed disabled:opacity-50"
-  ],
-  {
-    variants: {
-      size: {
-        sm: "h-8 text-sm",
-        md: "h-10 text-base",
-        lg: "h-12 text-lg"
-      },
-      hasError: {
-        true: "border-destructive focus:ring-destructive",
-        false: ""
-      }
-    },
-    defaultVariants: {
-      size: "md",
-      hasError: !1
-    }
-  }
-), vo = B.forwardRef(
-  ({
-    className: e,
-    size: t,
-    hasError: r,
-    error: n,
-    helperText: s,
-    label: i,
-    hideLabel: o,
-    required: l,
-    disabled: a,
-    id: d,
-    "aria-describedby": c,
-    ...u
-  }, f) => {
-    const p = B.useId(), h = d || p, b = `${h}-error`, v = `${h}-helper`, w = [
-      n ? b : null,
-      s && !n ? v : null,
-      c
-    ].filter(Boolean).join(" ");
-    return /* @__PURE__ */ g(
-      "div",
-      {
-        "data-slot": "input-wrapper",
-        className: ue("flex flex-col gap-1.5", a && "opacity-50"),
-        children: [
-          i && /* @__PURE__ */ g(
-            "label",
-            {
-              "data-slot": "input-label",
-              htmlFor: h,
-              className: ue(
-                "text-foreground text-sm font-medium",
-                o && "sr-only"
-              ),
-              children: [
-                i,
-                l && /* @__PURE__ */ m("span", { className: "text-destructive ml-1", "aria-hidden": "true", children: "*" })
-              ]
-            }
-          ),
-          /* @__PURE__ */ m(
-            "input",
-            {
-              "data-slot": "input",
-              id: h,
-              ref: f,
-              className: ue(
-                Ed({ size: t, hasError: r || !!n }),
-                e
-              ),
-              "aria-invalid": r || !!n,
-              "aria-describedby": w || void 0,
-              required: l,
-              disabled: a,
-              ...u
-            }
-          ),
-          n && /* @__PURE__ */ m(
-            "p",
-            {
-              id: b,
-              "data-slot": "input-error",
-              className: "text-destructive-700 dark:text-destructive-400 text-sm",
-              role: "alert",
-              children: n
-            }
-          ),
-          s && !n && /* @__PURE__ */ m(
-            "p",
-            {
-              id: v,
-              "data-slot": "input-helper",
-              className: "text-muted-foreground text-sm",
-              children: s
-            }
-          )
-        ]
-      }
-    );
-  }
-);
-vo.displayName = "Input";
-var Td = Kt(
   [
     "shrink-0 appearance-none",
     "border-2 border-input rounded",
@@ -4300,19 +4190,19 @@ var Td = Kt(
               disabled: a,
               "aria-describedby": [n ? h : null, i ? b : null].filter(Boolean).join(" ") || void 0,
               "aria-invalid": !!i,
-              className: ue("peer", Td({ size: t }), e),
+              className: ue("peer", Ed({ size: t }), e),
               ...d
             }
           ),
           /* @__PURE__ */ m(
-            Id,
+            Td,
             {
               size: t,
               className: "pointer-events-none absolute text-white opacity-0 transition-opacity peer-checked:opacity-100"
             }
           ),
           /* @__PURE__ */ m(
-            _d,
+            Id,
             {
               size: t,
               className: "pointer-events-none absolute text-white opacity-0 transition-opacity peer-indeterminate:opacity-100"
@@ -4373,7 +4263,7 @@ var Td = Kt(
   }
 );
 Yn.displayName = "Checkbox";
-function Id({ size: e, className: t }) {
+function Td({ size: e, className: t }) {
   const r = {
     sm: 10,
     md: 12,
@@ -4397,7 +4287,7 @@ function Id({ size: e, className: t }) {
     }
   );
 }
-function _d({ size: e, className: t }) {
+function Id({ size: e, className: t }) {
   const r = {
     sm: 10,
     md: 12,
@@ -4421,6 +4311,116 @@ function _d({ size: e, className: t }) {
     }
   );
 }
+var _d = Kt(
+  [
+    "w-full px-3 py-2",
+    "border border-input rounded-lg",
+    "bg-background text-foreground",
+    "placeholder:text-muted-foreground",
+    "transition-colors duration-200",
+    "focus:outline-none focus:ring-2 focus:ring-ring focus:border-transparent",
+    "disabled:cursor-not-allowed disabled:opacity-50"
+  ],
+  {
+    variants: {
+      size: {
+        sm: "h-8 text-sm",
+        md: "h-10 text-base",
+        lg: "h-12 text-lg"
+      },
+      hasError: {
+        true: "border-destructive focus:ring-destructive",
+        false: ""
+      }
+    },
+    defaultVariants: {
+      size: "md",
+      hasError: !1
+    }
+  }
+), vo = B.forwardRef(
+  ({
+    className: e,
+    size: t,
+    hasError: r,
+    error: n,
+    helperText: s,
+    label: i,
+    hideLabel: o,
+    required: l,
+    disabled: a,
+    id: d,
+    "aria-describedby": c,
+    ...u
+  }, f) => {
+    const p = B.useId(), h = d || p, b = `${h}-error`, v = `${h}-helper`, w = [
+      n ? b : null,
+      s && !n ? v : null,
+      c
+    ].filter(Boolean).join(" ");
+    return /* @__PURE__ */ g(
+      "div",
+      {
+        "data-slot": "input-wrapper",
+        className: ue("flex flex-col gap-1.5", a && "opacity-50"),
+        children: [
+          i && /* @__PURE__ */ g(
+            "label",
+            {
+              "data-slot": "input-label",
+              htmlFor: h,
+              className: ue(
+                "text-foreground text-sm font-medium",
+                o && "sr-only"
+              ),
+              children: [
+                i,
+                l && /* @__PURE__ */ m("span", { className: "text-destructive ml-1", "aria-hidden": "true", children: "*" })
+              ]
+            }
+          ),
+          /* @__PURE__ */ m(
+            "input",
+            {
+              "data-slot": "input",
+              id: h,
+              ref: f,
+              className: ue(
+                _d({ size: t, hasError: r || !!n }),
+                e
+              ),
+              "aria-invalid": r || !!n,
+              "aria-describedby": w || void 0,
+              required: l,
+              disabled: a,
+              ...u
+            }
+          ),
+          n && /* @__PURE__ */ m(
+            "p",
+            {
+              id: b,
+              "data-slot": "input-error",
+              className: "text-destructive-700 dark:text-destructive-400 text-sm",
+              role: "alert",
+              children: n
+            }
+          ),
+          s && !n && /* @__PURE__ */ m(
+            "p",
+            {
+              id: v,
+              "data-slot": "input-helper",
+              className: "text-muted-foreground text-sm",
+              children: s
+            }
+          )
+        ]
+      }
+    );
+  }
+);
+vo.displayName = "Input";
 function Ad(e) {
   if (!e) return e;
   if (e.startsWith("+")) {

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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"}