@esheet/renderer 0.0.3 → 0.0.4-0

package/README.md

@@ -39,7 +39,7 @@ import { EsheetRenderer } from '@esheet/renderer';
 import type { FormDefinition } from '@esheet/core';
 
 const myForm: FormDefinition = {
-  schemaType: 'mieforms-v1.0',
+  id: 'patient-intake',
   title: 'Patient Intake',
   fields: [
     {
@@ -105,7 +105,7 @@ function App() {
 
 ```tsx
 const yamlSchema = `
-schemaType: mieforms-v1.0
+id: simple-form
 title: Simple Form
 fields:
   - id: q1
@@ -164,7 +164,7 @@ EsheetRenderer is a thin wrapper that:
 
 ```tsx
 const conditionalForm: FormDefinition = {
-  schemaType: 'mieforms-v1.0',
+  id: 'conditional-form',
   title: 'Conditional Form',
   fields: [
     {

package/dist/index.d.ts

@@ -1,7 +1,12 @@
 import { default as default_2 } from 'react';
+import { FhirQuestionnaireResponse } from '@esheet/adapters';
+import { FieldDefinition } from '@esheet/core';
+import { FormDefinition } from '@esheet/core';
 import { FormResponse } from '@esheet/core';
+import { FormResponseEnvelope } from '@esheet/core';
 import { FormStore } from '@esheet/core';
 import { JSX } from 'react/jsx-runtime';
+import { ResponseExportOptions } from '@esheet/adapters';
 import { UIStore } from '@esheet/core';
 import { ValidationError } from '@esheet/core';
 
@@ -30,6 +35,30 @@ export declare const EsheetRenderer: default_2.ForwardRefExoticComponent<EsheetR
 export declare interface EsheetRendererHandle {
     /** Get current form responses */
     getRawResponse: () => FormResponse;
+    /**
+     * Get form responses in the specified format.
+     *
+     * @param options - Format and export options
+     * @returns Native FormResponse or FHIR QuestionnaireResponse
+     *
+     * @example
+     * ```ts
+     * // Native format (default)
+     * const native = ref.current.getResponse();
+     *
+     * // FHIR QuestionnaireResponse
+     * const fhir = ref.current.getResponse({
+     *   format: 'fhir',
+     *   fhir: {
+     *     questionnaireUrl: 'http://example.org/Questionnaire/my-form',
+     *     status: 'completed',
+     *   }
+     * });
+     * ```
+     */
+    getResponse: <T extends ResponseFormat = 'native'>(options?: GetResponseOptions & {
+        format?: T;
+    }) => GetResponseResult<T>;
     /** Get form store instance */
     getFormStore: () => FormStore;
     /** Get UI store instance */
@@ -39,6 +68,12 @@ export declare interface EsheetRendererHandle {
         response: FormResponse | null;
         errors: ValidationError[];
     };
+    /** Returns true if touch mode is currently enabled */
+    isTouchModeEnabled: () => boolean;
+    /** Toggle touch mode on/off. Only works when touchMode prop is 'auto' or undefined. Overrides auto-detection. */
+    setTouchMode: (enabled: boolean) => void;
+    /** Reset to auto-detection mode (clears manual override). Only works when touchMode='auto'. */
+    resetTouchMode: () => void;
 }
 
 export declare interface EsheetRendererProps {
@@ -55,8 +90,28 @@ export declare interface EsheetRendererProps {
     strict?: boolean;
     /** Called after the form definition has been parsed and loaded into the store. */
     onReady?: () => void;
+    /**
+     * Called once after the renderer mounts, providing a narrow `RendererTools`
+     * facade for MCP / AI tool integrations.
+     */
+    onRendererToolsReady?: (tools: RendererTools) => void;
+    /**
+     * Enable touch-optimized mode with larger touch targets.
+     * - `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).
+     * Useful for syncing external UI with the renderer's touch state.
+     */
+    onTouchModeChange?: (enabled: boolean) => void;
 }
 
+export declare function executeToolCall(toolName: string, args: ToolArgs, tools: RendererTools): string | Record<string, unknown>;
+
 /**
  * FieldNode - Renders a single field or section with recursive children
  *
@@ -73,6 +128,28 @@ declare interface FieldNodeProps {
     depth?: number;
 }
 
+export { FormDefinition }
+
+export { FormResponseEnvelope }
+
+/** Options for getResponse() */
+export declare interface GetResponseOptions {
+    /** Output format: 'native' (default) or 'fhir' (FHIR QuestionnaireResponse) */
+    format?: ResponseFormat;
+    /** FHIR export options (required when format is 'fhir') */
+    fhir?: Omit<ResponseExportOptions, 'questionnaireUrl'> & {
+        /** Canonical URL of the questionnaire. Falls back to form._sourceData metadata if available. */
+        questionnaireUrl?: string;
+    };
+}
+
+/** Return type for getResponse() — varies by format */
+export declare type GetResponseResult<T extends ResponseFormat = 'native'> = T extends 'fhir' ? FhirQuestionnaireResponse : FormResponse;
+
+export declare const RENDERER_SYSTEM_PROMPT: string;
+
+export declare const RENDERER_TOOL_DEFINITIONS: readonly ToolDefinition[];
+
 /**
  * RendererBody - Iterates over visible root fields and renders them
  *
@@ -87,16 +164,128 @@ declare interface RendererBodyProps {
     ui: UIStore;
 }
 
+/** Summary of a single field, suitable for AI context. */
+declare interface RendererFieldSummary {
+    id: string;
+    fieldType: string;
+    /** For text fields: the HTML input type (e.g. 'date', 'datetime-local', 'month', 'time', 'email', 'number'). Use the correct format when filling this field. */
+    inputType?: string;
+    /** Required value format for structured input types. Use this exact format when calling fill_field. */
+    valueFormat?: string;
+    question: string | undefined;
+    required: boolean;
+    /** True if this field already has a response value. False means it is still empty and needs to be filled. */
+    hasValue: boolean;
+    /** Available option values for selection fields (radio, check, dropdown, etc.). Only present when the field has options. */
+    options?: string[];
+    /** Available row labels for matrix fields. Only present for singlematrix / multimatrix. */
+    rows?: string[];
+    /** Available column labels for matrix fields. Only present for singlematrix / multimatrix. */
+    columns?: string[];
+}
+
+/**
+ * Narrow interface exposed to MCP / AI tools via `onRendererToolsReady`.
+ * Read-oriented: inspect responses, fill responses, and query the render tree.
+ */
+export declare interface RendererTools {
+    /** Currently visible, fillable fields with their available options. */
+    getForm: () => {
+        formId: string;
+        fieldCount: number;
+        fields: RendererFieldSummary[];
+    };
+    /** All fields in the form regardless of visibility, rules, or enabled state. */
+    getFormRaw: () => {
+        formId: string;
+        fieldCount: number;
+        fields: RendererFieldSummary[];
+    };
+    /** Get current raw responses keyed by field ID. */
+    getResponses: () => Record<string, unknown>;
+    /** Get validated responses — returns null if validation fails. */
+    getValidResponse: () => {
+        response: Record<string, unknown> | null;
+        errors: ValidationError[];
+    };
+    /** Set a response value for one visible field. Returns true on success, false if field not found/visible, or an error string if the value format is invalid. */
+    fillField: (fieldId: string, value: unknown) => boolean | string;
+    /** Clear all responses. */
+    clearResponses: () => void;
+    /** Full render tree with visibility/enabled/required per field. */
+    getFormTree: () => RenderFieldNode[];
+    /** Find a field ID by exact ID or partial question match. */
+    resolveFieldId: (fieldId?: string, fieldQuestion?: string) => string | undefined;
+}
+
+declare interface RenderFieldNode {
+    /** Field identifier. */
+    id: string;
+    /** Field definition without nested children. */
+    definition: Omit<FieldDefinition, 'fields'>;
+    /** Computed visible state. */
+    visible: boolean;
+    /** Computed enabled state. */
+    enabled: boolean;
+    /** Computed required state. */
+    required: boolean;
+    /** Renderable child nodes (sections only). */
+    children: RenderFieldNode[];
+}
+
+/** Response format options for getResponse() */
+export declare type ResponseFormat = 'native' | 'fhir';
+
+declare type ToolArgs = Record<string, unknown>;
+
+export declare interface ToolDefinition {
+    type: string;
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+
 /**
  * Initialize renderer with form definition.
  *
  * Auto-detects and converts the following input formats:
  * - eSheet FormDefinition (object or JSON/YAML string)
+ * - FHIR R4 Questionnaire resource
  * - MCP elicitation/create envelope
  * - SurveyJS schema (has top-level `pages` or `elements` array)
  */
 export declare function useRendererInit(form: FormStore, ui: UIStore, formData: unknown, initialResponses?: FormResponse, onValidationError?: (errors: string[]) => void, strict?: boolean, onReady?: () => void): void;
 
+/**
+ * Listens for AI tool-call events on a target element and dispatches them to
+ * the renderer's MCP tool executor. Returns the `onRendererToolsReady` callback
+ * to pass to `<EsheetRenderer>`.
+ *
+ * @example – default (listens on document)
+ * const onRendererToolsReady = useRendererMcpToolHandler({ eventName: 'ozwell-tool-call' });
+ * <EsheetRenderer onRendererToolsReady={onRendererToolsReady} ... />
+ *
+ * @example – scoped to a container element
+ * const ref = React.useRef<HTMLDivElement>(null);
+ * const onRendererToolsReady = useRendererMcpToolHandler({ target: ref.current ?? undefined, eventName: 'ozwell-tool-call' });
+ * <div ref={ref}><EsheetRenderer onRendererToolsReady={onRendererToolsReady} ... /></div>
+ */
+export declare function useRendererMcpToolHandler(options: UseRendererMcpToolHandlerOptions): (tools: RendererTools) => void;
+
+export declare interface UseRendererMcpToolHandlerOptions {
+    /**
+     * 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;
+}
+
 export { ValidationError }
 
 export { }