@esheet/renderer 0.0.4-1 → 0.0.4-2

package/dist/lib/mcp/tool-definitions.js

@@ -1,66 +0,0 @@
-export const RENDERER_TOOL_DEFINITIONS = [
-    {
-        type: 'function',
-        function: {
-            name: 'get_form',
-            description: 'Returns visible fields split into filled vs unfilled. Response: {formId, totalFields, filledCount, unfilledFields (full details), filledFieldIds (just IDs)}. Use unfilledFields to see what needs filling.\n\nFILL LOOP PATTERN:\n1. Call get_form — fill every field in unfilledFields using fill_field.\n2. Call get_form again. If new fields appeared in unfilledFields (revealed by conditional logic), fill those too.\n3. Repeat until unfilledFields is empty.\n\nNever assume you are done after a single pass — conditional logic frequently reveals new fields.',
-            parameters: { type: 'object', properties: {} },
-        },
-    },
-    {
-        type: 'function',
-        function: {
-            name: 'get_form_raw',
-            description: 'Returns ALL fields in the form regardless of visibility, conditional rules, or enabled state. Use this to see the full form schema.',
-            parameters: { type: 'object', properties: {} },
-        },
-    },
-    {
-        type: 'function',
-        function: {
-            name: 'get_responses',
-            description: 'Get the current raw response values for all fields.',
-            parameters: { type: 'object', properties: {} },
-        },
-    },
-    {
-        type: 'function',
-        function: {
-            name: 'get_valid_response',
-            description: 'Run form validation. Returns the full response object if all required fields pass, or null plus field-level errors if validation fails. Call this before submitting.',
-            parameters: { type: 'object', properties: {} },
-        },
-    },
-    {
-        type: 'function',
-        function: {
-            name: 'fill_field',
-            description: 'Set a response value for ONE visible field. Returns { result, filledCount, unfilledFields } where unfilledFields contains ONLY the fields still needing values (with full details including options/valueFormat). You are done when unfilledFields is empty.\n\nField type rules:\n- radio/dropdown/boolean/rating/slider: pass a single string matching one of the options values\n- check/multiselectdropdown: pass an array of strings matching option values\n- ranking: pass an ordered array of option value strings representing the desired rank order\n- multitext: pass an array of strings, one per option slot in order\n- singlematrix: pass an object { "Row Label": "Column Label" } for each row\n- multimatrix: pass an object { "Row Label": ["Col1", "Col2"] } for each row\n- text: use the valueFormat from the field\'s schema (e.g. YYYY-MM-DD for date, YYYY-MM-DDTHH:mm for datetime-local, YYYY-MM for month, HH:mm for time). Wrong formats are rejected with an error.',
-            parameters: {
-                type: 'object',
-                properties: {
-                    fieldId: { type: 'string' },
-                    fieldQuestion: { type: 'string' },
-                    value: {},
-                },
-                required: ['value'],
-            },
-        },
-    },
-    {
-        type: 'function',
-        function: {
-            name: 'clear_responses',
-            description: 'Clear all current form responses.',
-            parameters: { type: 'object', properties: {} },
-        },
-    },
-    {
-        type: 'function',
-        function: {
-            name: 'get_form_tree',
-            description: 'Get the full rendered field tree including visibility, enabled, and required state for each field given current responses.',
-            parameters: { type: 'object', properties: {} },
-        },
-    },
-];

package/dist/lib/mcp/tool-executor.js

@@ -1,55 +0,0 @@
-export function executeToolCall(toolName, args, tools) {
-    switch (toolName) {
-        case 'get_form':
-            return getFormOptimized(tools);
-        case 'get_form_raw':
-            return tools.getFormRaw();
-        case 'get_responses':
-            return tools.getResponses();
-        case 'get_valid_response':
-            return tools.getValidResponse();
-        case 'fill_field':
-            return fillField(args, tools);
-        case 'clear_responses':
-            tools.clearResponses();
-            return 'Responses cleared';
-        case 'get_form_tree':
-            return { fields: tools.getFormTree() };
-        default:
-            return `Unknown tool: ${toolName}`;
-    }
-}
-/** Optimized get_form: returns full details only for unfilled fields to reduce token usage. */
-function getFormOptimized(tools) {
-    const form = tools.getForm();
-    const filledFields = form.fields.filter((f) => f.hasValue);
-    const unfilledFields = form.fields.filter((f) => !f.hasValue);
-    return {
-        formId: form.formId,
-        totalFields: form.fieldCount,
-        filledCount: filledFields.length,
-        // Only unfilled fields need full details (options, questions, etc.)
-        unfilledFields,
-        // Filled fields: just IDs for reference
-        filledFieldIds: filledFields.map((f) => f.id),
-    };
-}
-function fillField(args, tools) {
-    const fieldId = tools.resolveFieldId(args['fieldId'], args['fieldQuestion']);
-    if (!fieldId)
-        return 'Error: field not found — provide fieldId or fieldQuestion';
-    const result = tools.fillField(fieldId, args['value']);
-    if (typeof result === 'string')
-        return result; // format validation error
-    if (!result)
-        return `Error: field "${fieldId}" is not currently visible — call get_form to see the current visible fields`;
-    const form = tools.getForm();
-    // Return only unfilled fields with full details (token optimization)
-    const filledFields = form.fields.filter((f) => f.hasValue);
-    const unfilledFields = form.fields.filter((f) => !f.hasValue);
-    return {
-        result: `Field "${fieldId}" updated`,
-        filledCount: filledFields.length,
-        unfilledFields,
-    };
-}

package/dist/lib/mcp/useRendererToolBridge.js

@@ -1,53 +0,0 @@
-import React from 'react';
-import { executeToolCall } from './tool-executor.js';
-/**
- * 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 function useRendererMcpToolHandler(options) {
-    const { target, eventName } = options;
-    const toolsRef = React.useRef(null);
-    const onRendererToolsReady = React.useCallback((tools) => {
-        toolsRef.current = tools;
-    }, []);
-    React.useEffect(() => {
-        const el = target ?? document;
-        function onToolCall(e) {
-            const { name: rawName, arguments: args, respond, } = e.detail;
-            // Strip 'postMessage:' prefix if present (added by Ozwell widget internally)
-            const name = rawName.replace(/^postMessage:/, '');
-            if (!toolsRef.current) {
-                respond({ success: false, message: 'Renderer not ready' });
-                return;
-            }
-            const toResponse = (r) => typeof r === 'string' ? { result: r } : r;
-            try {
-                const result = executeToolCall(name, args, toolsRef.current);
-                if (result instanceof Promise) {
-                    result
-                        .then((r) => respond(toResponse(r)))
-                        .catch((err) => respond({ error: String(err) }));
-                }
-                else {
-                    respond(toResponse(result));
-                }
-            }
-            catch (err) {
-                respond({ error: String(err) });
-            }
-        }
-        el.addEventListener(eventName, onToolCall);
-        return () => el.removeEventListener(eventName, onToolCall);
-    }, [target, eventName]);
-    return onRendererToolsReady;
-}

package/dist/lib/register-defaults.js

@@ -1,36 +0,0 @@
-// ---------------------------------------------------------------------------
-// Built-in field component registration for the renderer
-// ---------------------------------------------------------------------------
-// Called from EsheetRenderer runtime path so consumers get built-in defaults
-// without relying on package entry side-effect imports.
-// ---------------------------------------------------------------------------
-import { registerFieldComponents } from '@esheet/fields';
-import { TextField, LongTextField, MultiTextField, RadioField, CheckField, BooleanField, DropdownField, MultiSelectDropdownField, RatingField, RankingField, SliderField, SingleMatrixField, MultiMatrixField, SectionField, SignatureField, DiagramField, ImageField, HtmlField, DisplayField, } from '@esheet/fields';
-let defaultsRegistered = false;
-export function ensureDefaultFieldComponentsRegistered() {
-    if (defaultsRegistered) {
-        return;
-    }
-    registerFieldComponents({
-        text: TextField,
-        longtext: LongTextField,
-        multitext: MultiTextField,
-        radio: RadioField,
-        check: CheckField,
-        boolean: BooleanField,
-        dropdown: DropdownField,
-        multiselectdropdown: MultiSelectDropdownField,
-        rating: RatingField,
-        ranking: RankingField,
-        slider: SliderField,
-        singlematrix: SingleMatrixField,
-        multimatrix: MultiMatrixField,
-        section: SectionField,
-        signature: SignatureField,
-        diagram: DiagramField,
-        image: ImageField,
-        html: HtmlField,
-        display: DisplayField,
-    });
-    defaultsRegistered = true;
-}

package/dist/lib/renderer-tools.js

@@ -1,305 +0,0 @@
-// ---------------------------------------------------------------------------
-// RendererTools — narrow facade for MCP / AI tool callers only.
-// ---------------------------------------------------------------------------
-import { validateForm, } from '@esheet/core';
-import { renderer } from './renderer.js';
-const NON_INPUT = new Set(['section', 'html', 'display', 'image', 'diagram']);
-/** Flatten the render tree into only visible, fillable leaf nodes. */
-function flattenVisible(nodes) {
-    const result = [];
-    for (const node of nodes) {
-        if (!node.visible)
-            continue;
-        if (node.children.length > 0) {
-            result.push(...flattenVisible(node.children));
-        }
-        else if (!NON_INPUT.has(node.definition.fieldType)) {
-            result.push(node);
-        }
-    }
-    return result;
-}
-export function createRendererTools(formStore) {
-    function resolveFieldId(fieldId, fieldQuestion) {
-        if (fieldId)
-            return fieldId;
-        if (fieldQuestion) {
-            const q = fieldQuestion.toLowerCase();
-            const { normalized } = formStore.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;
-    }
-    function getCurrentRenderTree() {
-        const { formId, responses } = formStore.getState();
-        const definition = formStore.getState().hydrateDefinition();
-        if (!definition)
-            return [];
-        return renderer({ ...definition, id: formId }, responses);
-    }
-    const INPUT_TYPE_FORMAT = {
-        date: 'YYYY-MM-DD',
-        'datetime-local': 'YYYY-MM-DDTHH:mm',
-        month: 'YYYY-MM',
-        time: 'HH:mm',
-    };
-    function toFieldSummary(id, def, required) {
-        const response = formStore.getState().responses[id];
-        const hasValue = response != null &&
-            Object.values(response).some((v) => v != null &&
-                v !== '' &&
-                !(Array.isArray(v) && v.length === 0) &&
-                !(typeof v === 'object' &&
-                    !Array.isArray(v) &&
-                    Object.keys(v).length === 0));
-        const summary = {
-            id,
-            fieldType: def.fieldType,
-            question: def.question,
-            required: required ?? def.required ?? false,
-            hasValue,
-        };
-        if (def.inputType)
-            summary.inputType = def.inputType;
-        if (def.inputType && INPUT_TYPE_FORMAT[def.inputType])
-            summary.valueFormat = INPUT_TYPE_FORMAT[def.inputType];
-        if (def.options && def.options.length > 0)
-            summary.options = def.options.map((o) => o.value);
-        if (def.rows && def.rows.length > 0)
-            summary.rows = def.rows.map((r) => r.value);
-        if (def.columns && def.columns.length > 0)
-            summary.columns = def.columns.map((c) => c.value);
-        return summary;
-    }
-    /**
-     * Normalize and validate a text value for a given inputType.
-     * Returns the normalized string on success, or null if the value cannot
-     * be coerced into a valid format (caller should reject the fill).
-     */
-    function normalizeTextValue(value, inputType) {
-        if (!value)
-            return value;
-        switch (inputType) {
-            case 'date': {
-                if (/^\d{4}-\d{2}-\d{2}$/.test(value))
-                    return value;
-                if (/^\d{4}-\d{2}$/.test(value))
-                    return `${value}-01`;
-                if (/^\d{4}$/.test(value))
-                    return `${value}-01-01`;
-                return null; // not a recognisable date
-            }
-            case 'month': {
-                if (/^\d{4}-\d{2}$/.test(value))
-                    return value;
-                if (/^\d{4}-\d{2}-\d{2}$/.test(value))
-                    return value.slice(0, 7);
-                return null;
-            }
-            case 'datetime-local': {
-                const n = value.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(value))
-                    return value;
-                const match = value.match(/^(\d{1,2}):(\d{2})\s*(AM|PM)$/i);
-                if (match) {
-                    let h = parseInt(match[1], 10);
-                    const m = match[2];
-                    const period = match[3].toUpperCase();
-                    if (period === 'AM' && h === 12)
-                        h = 0;
-                    if (period === 'PM' && h !== 12)
-                        h += 12;
-                    return `${String(h).padStart(2, '0')}:${m}`;
-                }
-                return null;
-            }
-            default:
-                return value;
-        }
-    }
-    function applyFieldValue(fieldId, value, checkVisibility) {
-        const { normalized } = formStore.getState();
-        const node = normalized.byId[fieldId];
-        if (!node)
-            return false;
-        if (checkVisibility) {
-            const visibleIds = new Set(flattenVisible(getCurrentRenderTree()).map((n) => n.id));
-            if (!visibleIds.has(fieldId))
-                return false;
-        }
-        const def = node.definition;
-        let response;
-        if (def.fieldType === 'singlematrix' &&
-            value !== null &&
-            typeof value === 'object') {
-            const rows = def.rows ?? [];
-            const columns = def.columns ?? [];
-            const existing = (formStore.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') {
-            // multimatrix: { selected: Record<rowId, SelectedOption[]> }
-            const rows = def.rows ?? [];
-            const columns = def.columns ?? [];
-            const existing = (formStore.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);
-            // For slider/rating, also try matching by numeric index or option value as number
-            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') {
-            // ranking: { selected: SelectedOption[] } in the user-specified order
-            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);
-            // append any options not mentioned by the user at the end
-            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') {
-            // multitext: { multitextAnswers: Record<optionId, string> }
-            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} (e.g. ${new Date()
-                            .toISOString()
-                            .slice(0, expected.length)
-                            .replace('T', 'T')
-                            .replace(/[^\dT:-]/g, '0')})`
-                        : `Error: invalid value for field`;
-                }
-                response = { answer: normalized };
-            }
-        }
-        formStore.getState().setResponse(fieldId, response);
-        return true;
-    }
-    return {
-        getForm: () => {
-            const { formId } = formStore.getState();
-            const visibleNodes = flattenVisible(getCurrentRenderTree());
-            const fields = visibleNodes.map((node) => toFieldSummary(node.id, node.definition, node.required));
-            return { formId, fieldCount: fields.length, fields };
-        },
-        getFormRaw: () => {
-            const { normalized, formId } = formStore.getState();
-            const fields = Object.keys(normalized.byId)
-                .filter((id) => !NON_INPUT.has(normalized.byId[id].definition.fieldType))
-                .map((id) => toFieldSummary(id, normalized.byId[id].definition));
-            return { formId, fieldCount: fields.length, fields };
-        },
-        getResponses: () => formStore.getState().responses,
-        getValidResponse: () => {
-            const state = formStore.getState();
-            const errors = validateForm(state.normalized, state.responses);
-            return {
-                response: errors.length === 0
-                    ? state.responses
-                    : null,
-                errors,
-            };
-        },
-        fillField: (fieldId, value) => applyFieldValue(fieldId, value, true),
-        clearResponses: () => formStore.getState().resetResponses(),
-        getFormTree: () => getCurrentRenderTree(),
-        resolveFieldId,
-    };
-}

package/dist/lib/renderer.js

@@ -1,33 +0,0 @@
-import { normalizeDefinition, resolveEffect, } from '@esheet/core';
-/**
- * Build a render tree from form definition + responses.
- *
- * Sections are represented as nodes with nested `children`.
- */
-export function renderer(definition, responses = {}, options = {}) {
-    const normalized = normalizeDefinition(definition.fields);
-    const includeHidden = options.includeHidden === true;
-    function build(ids) {
-        const result = [];
-        for (const id of ids) {
-            const node = normalized.byId[id];
-            if (!node)
-                continue;
-            const visible = resolveEffect('visible', node.definition, normalized, responses);
-            if (!visible && !includeHidden)
-                continue;
-            result.push({
-                id,
-                definition: node.definition,
-                visible,
-                enabled: resolveEffect('enable', node.definition, normalized, responses),
-                required: resolveEffect('required', node.definition, normalized, responses),
-                children: build(node.childIds),
-            });
-        }
-        return result;
-    }
-    return build(normalized.rootIds);
-}
-/** Alias for readability in consumers that prefer explicit naming. */
-export const buildRenderTree = renderer;