@tooluminati/forms 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jitterbox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/create-form-tools.d.ts

@@ -0,0 +1,6 @@
+import type { WebMcpToolDescriptor } from '@tooluminati/core';
+import type { FormDiagnosticSummary, WebMcpFormToolOptions } from './types';
+export declare function createFormValidationSummaryTool<TValues>(options: WebMcpFormToolOptions<TValues>): WebMcpToolDescriptor<Record<string, never>, FormDiagnosticSummary>;
+export declare function createFormSubmitTool<TValues>(options: WebMcpFormToolOptions<TValues>): WebMcpToolDescriptor;
+export declare function createWebMcpFormTools<TValues>(options: WebMcpFormToolOptions<TValues>): WebMcpToolDescriptor[];
+//# sourceMappingURL=create-form-tools.d.ts.map

package/dist/create-form-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-form-tools.d.ts","sourceRoot":"","sources":["../src/create-form-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAE9D,OAAO,KAAK,EACV,qBAAqB,EAErB,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAqBjB,wBAAgB,+BAA+B,CAAC,OAAO,EACrD,OAAO,EAAE,qBAAqB,CAAC,OAAO,CAAC,GACtC,oBAAoB,CAAC,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,qBAAqB,CAAC,CA+BpE;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAC1C,OAAO,EAAE,qBAAqB,CAAC,OAAO,CAAC,GACtC,oBAAoB,CA0DtB;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAC3C,OAAO,EAAE,qBAAqB,CAAC,OAAO,CAAC,GACtC,oBAAoB,EAAE,CAYxB"}

package/dist/create-form-tools.js

@@ -0,0 +1,96 @@
+import { inferSchemaFromValue } from './infer-schema';
+function formatFormErrors(errors, message) {
+    const lines = errors.map((error) => `${error.path ? `${error.path}: ` : ''}${error.message || error.kind}`);
+    return [message, ...lines].filter(Boolean).join('\n');
+}
+function applyRedactResult(result, redactResult) {
+    if (!redactResult) {
+        return result;
+    }
+    return redactResult(result);
+}
+export function createFormValidationSummaryTool(options) {
+    const schema = options.schema ?? inferSchemaFromValue(options.getValues());
+    return {
+        name: `${options.name}_validation_summary`,
+        description: 'Returns form schema, validation messages, and submitting/validating state without submitting.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            additionalProperties: false,
+        },
+        annotations: { readOnlyHint: true },
+        execute: () => {
+            const summary = {
+                name: options.name,
+                errors: options.getErrors?.() ?? [],
+                schema,
+                ...options.getSummary?.(),
+            };
+            if (options.redactValues) {
+                return {
+                    ...summary,
+                    values: options.redactValues(options.getValues()),
+                };
+            }
+            return summary;
+        },
+    };
+}
+export function createFormSubmitTool(options) {
+    const schema = options.schema ?? inferSchemaFromValue(options.getValues());
+    if (!schema) {
+        throw new Error(`Could not infer WebMCP schema for form "${options.name}". ` +
+            'Provide an explicit schema or use concrete non-null defaults.');
+    }
+    return {
+        name: options.name,
+        description: options.description,
+        inputSchema: schema,
+        annotations: {
+            readOnlyHint: false,
+            ...options.annotations,
+        },
+        validateArgs: options.validateArgs,
+        execute: async (rawArgs) => {
+            const values = options.validateArgs
+                ? options.validateArgs(rawArgs)
+                : rawArgs;
+            await options.setValues(values);
+            const result = await options.submit();
+            if (result.success) {
+                let output = result.message ?? 'Form submitted successfully.';
+                if (result.data !== undefined) {
+                    output = {
+                        message: output,
+                        data: options.redactValues
+                            ? options.redactValues(result.data)
+                            : result.data,
+                    };
+                }
+                return applyRedactResult(output, options.redactResult);
+            }
+            const errors = result.errors ?? options.getErrors?.() ?? [];
+            return applyRedactResult({
+                content: [
+                    {
+                        type: 'text',
+                        text: `Form submission failed:\n${formatFormErrors(errors, result.message)}`,
+                    },
+                ],
+                isError: true,
+            }, options.redactResult);
+        },
+    };
+}
+export function createWebMcpFormTools(options) {
+    const includeValidationSummary = options.includeValidationSummary ?? true;
+    const submitTool = createFormSubmitTool(options);
+    if (includeValidationSummary) {
+        return [
+            submitTool,
+            createFormValidationSummaryTool(options),
+        ];
+    }
+    return [submitTool];
+}

package/dist/create-form-tools.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=create-form-tools.test.d.ts.map

package/dist/create-form-tools.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-form-tools.test.d.ts","sourceRoot":"","sources":["../src/create-form-tools.test.ts"],"names":[],"mappings":""}

package/dist/create-form-tools.test.js

@@ -0,0 +1,45 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createFormSubmitTool, createFormValidationSummaryTool, createWebMcpFormTools, } from './create-form-tools';
+describe('create-form-tools', () => {
+    const baseOptions = {
+        name: 'submit_ticket',
+        description: 'Submit a support ticket.',
+        getValues: () => ({ subject: 'Help', priority: 'low' }),
+        setValues: vi.fn(async () => undefined),
+        submit: vi.fn(async () => ({ success: true })),
+    };
+    it('creates submit and validation summary tools by default', () => {
+        const tools = createWebMcpFormTools(baseOptions);
+        expect(tools.map((tool) => tool.name)).toEqual([
+            'submit_ticket',
+            'submit_ticket_validation_summary',
+        ]);
+    });
+    it('omits validation summary when disabled', () => {
+        const tools = createWebMcpFormTools({
+            ...baseOptions,
+            includeValidationSummary: false,
+        });
+        expect(tools).toHaveLength(1);
+        expect(tools[0]?.name).toBe('submit_ticket');
+    });
+    it('returns validation summary without submitting', async () => {
+        const tool = createFormValidationSummaryTool({
+            ...baseOptions,
+            getErrors: () => [{ kind: 'required', path: 'subject', message: 'Required' }],
+        });
+        const summary = await tool.execute({}, {});
+        expect(summary.errors).toHaveLength(1);
+        expect(summary.schema).toBeDefined();
+    });
+    it('submits through the submit tool execute handler', async () => {
+        const submit = vi.fn(async () => ({ success: true, message: 'ok' }));
+        const tool = createFormSubmitTool({
+            ...baseOptions,
+            submit,
+        });
+        const result = await tool.execute({ subject: 'Help', priority: 'low' }, {});
+        expect(submit).toHaveBeenCalledOnce();
+        expect(result).toBe('ok');
+    });
+});

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+import type { FormError } from './types';
+/** @experimental */
+export declare class FormValidationError extends Error {
+    readonly errors: FormError[];
+    constructor(message: string, errors: FormError[]);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,oBAAoB;AACpB,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC;gBAEjB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE;CAKjD"}

package/dist/errors.js

@@ -0,0 +1,9 @@
+/** @experimental */
+export class FormValidationError extends Error {
+    errors;
+    constructor(message, errors) {
+        super(message);
+        this.name = 'FormValidationError';
+        this.errors = errors;
+    }
+}

package/dist/form-tool-definition.d.ts

@@ -0,0 +1,11 @@
+import type { JsonSchema } from '@tooluminati/core';
+/** @internal Declarative-compat metadata; not shipped as a browser polyfill. */
+export interface FormToolDefinition<TValues = Record<string, unknown>> {
+    name: string;
+    description: string;
+    schema?: JsonSchema;
+    getValues: () => TValues;
+    setValues: (values: TValues) => void | Promise<void>;
+    submit: () => unknown | Promise<unknown>;
+}
+//# sourceMappingURL=form-tool-definition.d.ts.map

package/dist/form-tool-definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"form-tool-definition.d.ts","sourceRoot":"","sources":["../src/form-tool-definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,gFAAgF;AAChF,MAAM,WAAW,kBAAkB,CAAC,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,SAAS,EAAE,MAAM,OAAO,CAAC;IACzB,SAAS,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,MAAM,EAAE,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1C"}

package/dist/form-tool-definition.js

@@ -0,0 +1 @@
+export {};

package/dist/formik.d.ts

@@ -0,0 +1,16 @@
+import type { WebMcpFormToolOptions } from './types';
+export interface FormikLike<TValues> {
+    values: TValues;
+    errors?: unknown;
+    touched?: unknown;
+    isSubmitting?: boolean;
+    isValidating?: boolean;
+    setValues(values: TValues): void | Promise<void>;
+    validateForm(): Promise<unknown>;
+    submitForm(): Promise<void>;
+}
+export interface FormikWebMcpOptions<TValues> extends Pick<WebMcpFormToolOptions<TValues>, 'name' | 'description' | 'schema' | 'validateArgs' | 'annotations'> {
+    formik: FormikLike<TValues>;
+}
+export declare function useFormikWebMcpTool<TValues>({ formik, ...options }: FormikWebMcpOptions<TValues>): void;
+//# sourceMappingURL=formik.d.ts.map

package/dist/formik.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formik.d.ts","sourceRoot":"","sources":["../src/formik.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAa,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAEhE,MAAM,WAAW,UAAU,CAAC,OAAO;IACjC,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,YAAY,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IACjC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAmB,CAAC,OAAO,CAC1C,SAAQ,IAAI,CACV,qBAAqB,CAAC,OAAO,CAAC,EAC9B,MAAM,GAAG,aAAa,GAAG,QAAQ,GAAG,cAAc,GAAG,aAAa,CACnE;IACD,MAAM,EAAE,UAAU,CAAC,OAAO,CAAC,CAAC;CAC7B;AAkBD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,EAC3C,MAAM,EACN,GAAG,OAAO,EACX,EAAE,mBAAmB,CAAC,OAAO,CAAC,GAAG,IAAI,CAqBrC"}

package/dist/formik.js

@@ -0,0 +1,35 @@
+import { useWebMcpFormTool } from './useWebMcpFormTool';
+function flattenErrors(errors, prefix = '') {
+    if (!errors || typeof errors !== 'object') {
+        return [];
+    }
+    return Object.entries(errors).flatMap(([key, value]) => {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (typeof value === 'string') {
+            return [{ path, message: value }];
+        }
+        return flattenErrors(value, path);
+    });
+}
+export function useFormikWebMcpTool({ formik, ...options }) {
+    useWebMcpFormTool({
+        ...options,
+        getValues: () => formik.values,
+        setValues: (values) => formik.setValues(values),
+        getErrors: () => flattenErrors(formik.errors),
+        getSummary: () => ({
+            submitting: formik.isSubmitting,
+            validating: formik.isValidating,
+            touched: Boolean(formik.touched),
+        }),
+        submit: async () => {
+            const errors = await formik.validateForm();
+            const flattened = flattenErrors(errors);
+            if (flattened.length > 0) {
+                return { success: false, errors: flattened };
+            }
+            await formik.submitForm();
+            return { success: true };
+        },
+    });
+}