@esheet/builder 0.0.4-0 → 0.0.4-1

package/dist/index.d.ts

@@ -1,417 +1,16 @@
-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 { 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(_props: BuilderHeaderProps): JSX.Element;
-
-export declare interface BuilderHeaderProps {
-}
-
-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.
- *
- * Serialize on mount, live-validate on edit, auto-save on unmount.
- */
-export declare function CodeView({ form, ui }: CodeViewProps): JSX.Element;
-
-export declare interface CodeViewProps {
-    form: FormStore;
-    ui: UIStore;
-}
-
-export { createUIStore }
-
-export { EditTab }
-
-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. 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?: 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.
- *
- * Wraps a field with collapsible header, selection highlighting, edit/delete buttons, and drag handles.
- * Exposes field data and tools to the render function, allowing users to create
- * custom field types while getting all the built-in editor functionality.
- *
- * @example
- * ```tsx
- * <FieldWrapper fieldId={id} form={form} ui={ui}>
- *   {({ field, onUpdate, onRemove }) => (
- *     <div>
- *       <input
- *         value={field.question}
- *         onChange={(e) => onUpdate({ question: e.target.value })}
- *       />
- *     </div>
- *   )}
- * </FieldWrapper>
- * ```
- */
-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 */
-    fieldId: string;
-    /** The form store */
-    form: FormStore;
-    /** The UI store */
-    ui: UIStore;
-    /** Ref attached to the drag-handle element. */
-    dragHandleRef?: default_2.RefObject<HTMLDivElement | null>;
-    /** Optional override for selection state (used by nested section child interaction). */
-    isSelectedOverride?: boolean;
-    /** Optional override for click selection behavior. */
-    onSelectOverride?: (e: default_2.MouseEvent) => void;
-    /** Optional selected styling variant. */
-    selectedVariant?: 'default' | 'nested';
-    /** Optional signal used to force expand a field wrapper (used for section drop UX). */
-    forceExpandVersion?: number;
-    /** Optional signal used to force collapse a field wrapper. */
-    forceCollapseVersion?: number;
-    /** Render function that receives field data and tools */
-    children: (props: FieldWrapperRenderProps) => default_2.ReactNode;
-}
-
-/**
- * Props exposed to the render function for custom field components.
- * Identical to `FieldComponentProps` from core — kept as a named alias for
- * backward-compatibility with existing builder consumers.
- */
-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 }
-
-export { getRegisteredComponentKeys }
-
-export declare const InstanceIdContext: default_2.Context<string>;
-
-export { registerCustomFieldTypes }
-
-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 }
-
-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. */
-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 { }
+import './index.output.css';
+export { createUIStore, type UIState, type UIStore, type BuilderMode, type EditTab, type FieldComponentProps, } from '@esheet/core';
+export { EsheetBuilder, FormStoreContext, UIContext, InstanceIdContext, useFormStore, useUI, useInstanceId, type EsheetBuilderProps, type BuilderTools, type FieldSummary, } from './lib/EsheetBuilder.js';
+export { FieldWrapper, type FieldWrapperProps, type FieldWrapperRenderProps, } from './lib/components/FieldWrapper.js';
+export { registerCustomFieldTypes, getFieldComponent, getRegisteredComponentKeys, } from '@esheet/fields';
+export { BuilderHeader, type BuilderHeaderProps, } from './lib/components/BuilderHeader.js';
+export { CodeView, type CodeViewProps } from './lib/components/CodeView.js';
+export { useFormApi } from './lib/hooks/useFormApi.js';
+export type { FormApi, FieldResponseMap } from './lib/hooks/useFormApi.js';
+export { useUiApi } from './lib/hooks/useUiApi.js';
+export type { UiApi } from './lib/hooks/useUiApi.js';
+export { useVisibleRootIds } from './lib/hooks/useVisibleRootIds.js';
+export { executeToolCall, BUILDER_TOOL_DEFINITIONS, BUILDER_SYSTEM_PROMPT, useBuilderMcpToolHandler, } from './lib/mcp/index.js';
+export type { ToolDefinition, UseBuilderMcpToolHandlerOptions, } from './lib/mcp/index.js';
+export type { FormDefinition, FieldDefinition } from '@esheet/core';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,oBAAoB,CAAC;AAG5B,OAAO,EACL,aAAa,EACb,KAAK,OAAO,EACZ,KAAK,OAAO,EACZ,KAAK,WAAW,EAChB,KAAK,OAAO,EACZ,KAAK,mBAAmB,GACzB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,KAAK,EACL,aAAa,EACb,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,YAAY,GAClB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,GAC7B,MAAM,kCAAkC,CAAC;AAE1C,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,0BAA0B,GAC3B,MAAM,gBAAgB,CAAC;AAExB,OAAO,EACL,aAAa,EACb,KAAK,kBAAkB,GACxB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAE5E,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,YAAY,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC3E,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,YAAY,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,kCAAkC,CAAC;AAErE,OAAO,EACL,eAAe,EACf,wBAAwB,EACxB,qBAAqB,EACrB,wBAAwB,GACzB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,cAAc,EACd,+BAA+B,GAChC,MAAM,oBAAoB,CAAC;AAG5B,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}