@esheet/builder 0.0.3 → 0.0.4-0

package/README.md

@@ -45,7 +45,7 @@ function App() {
 import { EsheetBuilder } from '@esheet/builder';
 
 const initialForm: FormDefinition = {
-  schemaType: 'mieforms-v1.0',
+  id: 'patient-intake',
   title: 'Patient Intake',
   fields: [
     { id: 'name', fieldType: 'text', question: 'Full Name', required: true },

package/dist/index.d.ts

@@ -1,34 +1,118 @@
+import { AddFieldOptions } from '@esheet/core';
 import { BuilderMode } from '@esheet/core';
 import { createUIStore } from '@esheet/core';
 import { default as default_2 } from 'react';
 import { EditTab } from '@esheet/core';
 import { FieldComponentProps } from '@esheet/core';
+import { FieldDefinition } from '@esheet/core';
+import { FieldNode } from '@esheet/core';
+import { FieldResponse } from '@esheet/core';
+import { FieldType } from '@esheet/core';
+import { FieldTypeMeta } from '@esheet/core';
 import { FormDefinition } from '@esheet/core';
 import { FormStore } from '@esheet/core';
 import { FormStoreContext } from '@esheet/fields';
 import { getFieldComponent } from '@esheet/fields';
 import { getRegisteredComponentKeys } from '@esheet/fields';
 import { JSX } from 'react/jsx-runtime';
+import { NormalizedDefinition } from '@esheet/core';
 import { registerCustomFieldTypes } from '@esheet/fields';
-import { resetComponentRegistry } from '@esheet/fields';
 import { UIContext } from '@esheet/fields';
 import { UIState } from '@esheet/core';
 import { UIStore } from '@esheet/core';
 import { useFormStore } from '@esheet/fields';
 import { useUI } from '@esheet/fields';
 
+export declare const BUILDER_SYSTEM_PROMPT: string;
+
+export declare const BUILDER_TOOL_DEFINITIONS: readonly ToolDefinition[];
+
 /**
  * BuilderHeader — top bar with Build/Code/Preview mode toggle and Import/Export actions.
  */
-export declare function BuilderHeader({ form, ui }: BuilderHeaderProps): JSX.Element;
+export declare function BuilderHeader(_props: BuilderHeaderProps): JSX.Element;
 
 export declare interface BuilderHeaderProps {
-    form: FormStore;
-    ui: UIStore;
 }
 
 export { BuilderMode }
 
+/**
+ * Narrow interface exposed to MCP / AI tools via `onBuilderToolsReady`.
+ * Only the operations an external AI agent needs — no raw store internals.
+ */
+export declare 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) => 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: () => FormDefinition;
+    /** Update the form's top-level ID without replacing fields. */
+    setFormId: (id: string) => void;
+}
+
 /**
  * CodeView — Monaco-based JSON/YAML editor for the form definition.
  *
@@ -45,23 +129,84 @@ export { createUIStore }
 
 export { EditTab }
 
-export declare function EsheetBuilder({ definition, onChange, dragEnabled, className, children, }: EsheetBuilderProps): JSX.Element;
+export declare const EsheetBuilder: default_2.ForwardRefExoticComponent<EsheetBuilderProps & default_2.RefAttributes<EsheetBuilderHandle>>;
+
+declare 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 interface EsheetBuilderProps {
-    /** Initial form definition to load. */
-    definition?: FormDefinition;
+    /** 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;
-    /** Whether drag-and-drop reordering is enabled (default: true). Disable for better performance on slow devices. */
+    /**
+     * 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?: default_2.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 declare function executeToolCall(toolName: string, args: ToolArgs, tools: BuilderTools): string | Record<string, unknown>;
+
 export { FieldComponentProps }
 
+export { FieldDefinition }
+
+export declare type FieldResponseMap = Record<string, FieldResponse>;
+
+/** Summary of a single field, suitable for AI context. */
+export declare 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[];
+}
+
 /**
  * FieldWrapper - Extensibility API for custom field components.
  *
@@ -83,7 +228,7 @@ export { FieldComponentProps }
  * </FieldWrapper>
  * ```
  */
-export declare function FieldWrapper({ fieldId, form, ui, dragHandleRef, isSelectedOverride, onSelectOverride, selectedVariant: _selectedVariant, forceExpandVersion, forceCollapseVersion, children, }: FieldWrapperProps): JSX.Element | null;
+export declare function FieldWrapper({ fieldId, form, ui, dragHandleRef, isSelectedOverride, onSelectOverride, selectedVariant, forceExpandVersion, forceCollapseVersion, children, }: FieldWrapperProps): JSX.Element | null;
 
 export declare interface FieldWrapperProps {
     /** The field ID */
@@ -115,6 +260,52 @@ export declare interface FieldWrapperProps {
  */
 export declare type FieldWrapperRenderProps = FieldComponentProps;
 
+export declare interface FormApi {
+    field: FieldNode | undefined;
+    response: FieldResponse | undefined;
+    isVisible: boolean;
+    isEnabled: boolean;
+    isRequired: boolean;
+    normalized: NormalizedDefinition;
+    responses: FieldResponseMap;
+    instanceId: string;
+    form: {
+        addField: (type: FieldType, opts?: AddFieldOptions) => string | null;
+        loadDefinition: FormStore['getState'] extends () => infer S ? S extends {
+            loadDefinition: infer F;
+        } ? F : never : never;
+        setFormId: (id: string) => void;
+        hydrateDefinition: () => ReturnType<ReturnType<FormStore['getState']>['hydrateDefinition']>;
+        hydrateResponse: () => ReturnType<ReturnType<FormStore['getState']>['hydrateResponse']>;
+        resetResponses: () => void;
+    };
+    field_: {
+        update: (patch: Partial<Omit<FieldDefinition, 'fields'>>) => boolean;
+        remove: () => boolean;
+        move: (toIndex: number, toParentId?: string | null) => boolean;
+        setResponse: (resp: FieldResponse) => void;
+        clearResponse: () => void;
+    };
+    option: {
+        add: (value?: string) => string | null;
+        update: (optId: string, value: string) => boolean;
+        remove: (optId: string) => boolean;
+    };
+    row: {
+        add: (value?: string) => string | null;
+        update: (rowId: string, value: string) => boolean;
+        remove: (rowId: string) => boolean;
+    };
+    column: {
+        add: (value?: string) => string | null;
+        update: (colId: string, value: string) => boolean;
+        remove: (colId: string) => boolean;
+    };
+    _form: FormStore;
+}
+
+export { FormDefinition }
+
 export { FormStoreContext }
 
 export { getFieldComponent }
@@ -125,7 +316,31 @@ export declare const InstanceIdContext: default_2.Context<string>;
 
 export { registerCustomFieldTypes }
 
-export { resetComponentRegistry }
+declare type ToolArgs = Record<string, unknown>;
+
+export declare interface ToolDefinition {
+    type: string;
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+
+export declare interface UiApi {
+    mode: BuilderMode;
+    selectedFieldId: string | null;
+    selectedFieldChildId: string | null;
+    editTab: EditTab;
+    codeEditorHasError: boolean;
+    selectField: (id: string | null) => void;
+    selectFieldChild: (parentId: string, childId: string | null) => void;
+    setMode: (m: BuilderMode) => void;
+    setEditTab: (tab: EditTab) => void;
+    setEditModalOpen: (open: boolean) => void;
+    clearDragState: () => void;
+    _ui: UIStore;
+}
 
 export { UIContext }
 
@@ -133,6 +348,47 @@ export { UIState }
 
 export { UIStore }
 
+/**
+ * Listens for AI tool-call events on a target element and dispatches them to
+ * the builder's MCP tool executor. Returns the `onBuilderToolsReady` callback
+ * to pass to `<EsheetBuilder>`.
+ *
+ * @example – default (listens on document)
+ * const onBuilderToolsReady = useBuilderMcpToolHandler();
+ * <EsheetBuilder onBuilderToolsReady={onBuilderToolsReady} />
+ *
+ * @example – scoped to a container element
+ * const ref = React.useRef<HTMLDivElement>(null);
+ * const onBuilderToolsReady = useBuilderMcpToolHandler({ target: ref.current ?? undefined });
+ * <div ref={ref}><EsheetBuilder onBuilderToolsReady={onBuilderToolsReady} /></div>
+ *
+ * @example – custom event name
+ * const onBuilderToolsReady = useBuilderMcpToolHandler({ eventName: 'my-ai-tool-call' });
+ */
+export declare function useBuilderMcpToolHandler(options: UseBuilderMcpToolHandlerOptions): (tools: BuilderTools) => void;
+
+export declare interface UseBuilderMcpToolHandlerOptions {
+    /**
+     * The DOM element to listen on for tool-call events.
+     * Pass `document` to listen globally, or a specific element to scope it.
+     */
+    target?: EventTarget;
+    /**
+     * The event name to listen for, e.g. `'ozwell-tool-call'`.
+     */
+    eventName: string;
+}
+
+/**
+ * useFormApi — reactive field state + form store actions.
+ *
+ * Touches only the FormStore. For UI state (mode, selection, tabs) use
+ * useUiApi(). For the computed visible root IDs use useVisibleRootIds().
+ *
+ * @param fieldId - The field to bind to. Pass undefined for form-level ops only.
+ */
+export declare function useFormApi(fieldId?: string): FormApi;
+
 export { useFormStore }
 
 /** Hook to access the per-instance ID for unique DOM element IDs. */
@@ -140,4 +396,22 @@ export declare function useInstanceId(): string;
 
 export { useUI }
 
+/**
+ * useUiApi — lightweight hook for components that only need UI state/actions.
+ *
+ * Useful when you don't need field-scoped state. Requires UIContext provider.
+ */
+export declare function useUiApi(): UiApi;
+
+/**
+ * useVisibleRootIds — returns the root field IDs to render.
+ *
+ * In build/code mode: all root IDs.
+ * In preview mode: only IDs whose visibility rules evaluate to true.
+ *
+ * Requires both FormStoreContext and UIContext providers.
+ * Uses a stable-ref cache so the array reference only changes when content does.
+ */
+export declare function useVisibleRootIds(): readonly string[];
+
 export { }