@wix/headless-forms 0.0.0

package/dist/services/form-service.d.ts

@@ -0,0 +1,114 @@
+import { forms } from '@wix/forms';
+import { type ReadOnlySignal } from '@wix/services-definitions/core-services/signals';
+import { FormValues } from '../react/types.js';
+/**
+ * Response type for form submission operations.
+ * Represents the different states a form submission can be in.
+ */
+export type SubmitResponse = {
+    type: 'success';
+    message?: string;
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'idle';
+} | {
+    type: 'loading';
+};
+/**
+ * API interface for the Form service, providing reactive form data management.
+ * This service handles loading and managing form data, loading state, errors, and submissions.
+ * It supports both pre-loaded form data and lazy loading with form IDs.
+ *
+ * @interface FormServiceAPI
+ */
+export interface FormServiceAPI {
+    /** Reactive signal containing the current form data */
+    formSignal: ReadOnlySignal<forms.Form | null>;
+    /** Reactive signal indicating if a form is currently being loaded */
+    isLoadingSignal: ReadOnlySignal<boolean>;
+    /** Reactive signal containing any error message, or null if no error */
+    errorSignal: ReadOnlySignal<string | null>;
+    /** Reactive signal containing submission response state */
+    submitResponseSignal: ReadOnlySignal<SubmitResponse>;
+    /** Function to submit form with current values */
+    submitForm: (formValues: FormValues) => Promise<void>;
+}
+/**
+ * Service definition for the Form service.
+ * This defines the contract that the FormService must implement.
+ *
+ * @constant
+ */
+export declare const FormServiceDefinition: string & {
+    __api: FormServiceAPI;
+    __config: {};
+    isServiceDefinition?: boolean;
+} & FormServiceAPI;
+type OnSubmit = (formId: string, formValues: FormValues) => Promise<SubmitResponse>;
+/**
+ * Configuration type for the Form service.
+ * Supports two distinct patterns for providing form data:
+ * - Pre-loaded form data (SSR/SSG scenarios)
+ * - Lazy loading with form ID (client-side routing)
+ *
+ * Optionally accepts a custom submission handler to override default behavior.
+ *
+ * @type {FormServiceConfig}
+ */
+export type FormServiceConfig = {
+    formId: string;
+    onSubmit?: OnSubmit;
+} | {
+    form: forms.Form;
+    onSubmit?: OnSubmit;
+};
+/**
+ * Implementation of the Form service that manages reactive form data and submissions.
+ * This service provides signals for form data, loading state, error handling, and submission state.
+ * It supports both pre-loaded form data and lazy loading with form IDs.
+ * Consumers can provide a custom submission handler via config.
+ *
+ * @example
+ * ```tsx
+ * // Pre-loaded form data (SSR/SSG)
+ * const formService = FormService.withConfig({ form: formData });
+ *
+ * // Lazy loading with form ID (client-side)
+ * const formService = FormService.withConfig({ formId: 'form-123' });
+ *
+ * // With custom submission handler
+ * const formService = FormService.withConfig({
+ *   formId: 'form-123',
+ *   onSubmit: async (formId, formValues) => {
+ *     // Custom submission logic
+ *     await fetch('/api/submit', { method: 'POST', body: JSON.stringify({ formId, ...formValues }) });
+ *     return { type: 'success', message: 'Form submitted!' };
+ *   }
+ * });
+ * ```
+ */
+export declare const FormService: import("@wix/services-definitions").ServiceFactory<string & {
+    __api: FormServiceAPI;
+    __config: {};
+    isServiceDefinition?: boolean;
+} & FormServiceAPI, FormServiceConfig>;
+/**
+ * Loads form service configuration from the Wix Forms API for SSR initialization.
+ * This function is designed to be used during Server-Side Rendering (SSR) to preload
+ * a specific form by ID that will be used to configure the FormService.
+ *
+ * @param {string} formId - The unique identifier of the form to load
+ * @returns {Promise<FormServiceConfig>} Configuration object with pre-loaded form data
+ * @throws {Error} When the form cannot be loaded
+ *
+ * @example
+ * ```tsx
+ * // In your SSR/SSG setup
+ * const formConfig = await loadFormServiceConfig('form-123');
+ * const formService = FormService.withConfig(formConfig);
+ * ```
+ */
+export declare function loadFormServiceConfig(formId: string): Promise<FormServiceConfig>;
+export {};

package/dist/services/form-service.js

@@ -0,0 +1,148 @@
+import { forms, submissions } from '@wix/forms';
+import { defineService, implementService } from '@wix/services-definitions';
+import { SignalsServiceDefinition, } from '@wix/services-definitions/core-services/signals';
+/**
+ * Service definition for the Form service.
+ * This defines the contract that the FormService must implement.
+ *
+ * @constant
+ */
+export const FormServiceDefinition = defineService('formService');
+/**
+ * Implementation of the Form service that manages reactive form data and submissions.
+ * This service provides signals for form data, loading state, error handling, and submission state.
+ * It supports both pre-loaded form data and lazy loading with form IDs.
+ * Consumers can provide a custom submission handler via config.
+ *
+ * @example
+ * ```tsx
+ * // Pre-loaded form data (SSR/SSG)
+ * const formService = FormService.withConfig({ form: formData });
+ *
+ * // Lazy loading with form ID (client-side)
+ * const formService = FormService.withConfig({ formId: 'form-123' });
+ *
+ * // With custom submission handler
+ * const formService = FormService.withConfig({
+ *   formId: 'form-123',
+ *   onSubmit: async (formId, formValues) => {
+ *     // Custom submission logic
+ *     await fetch('/api/submit', { method: 'POST', body: JSON.stringify({ formId, ...formValues }) });
+ *     return { type: 'success', message: 'Form submitted!' };
+ *   }
+ * });
+ * ```
+ */
+export const FormService = implementService.withConfig()(FormServiceDefinition, ({ getService, config }) => {
+    const signalsService = getService(SignalsServiceDefinition);
+    const isLoadingSignal = signalsService.signal(false);
+    const errorSignal = signalsService.signal(null);
+    const submitResponseSignal = signalsService.signal({
+        type: 'idle',
+    });
+    const hasSchema = 'form' in config;
+    const formSignal = signalsService.signal(hasSchema ? config.form : null);
+    if (!hasSchema) {
+        loadForm(config.formId);
+    }
+    async function loadForm(id) {
+        isLoadingSignal.set(true);
+        errorSignal.set(null);
+        try {
+            const result = await fetchForm(id);
+            if (result) {
+                formSignal.set(result);
+            }
+            else {
+                errorSignal.set('Form not found');
+            }
+        }
+        catch (err) {
+            errorSignal.set('Failed to load form');
+            throw err;
+        }
+        finally {
+            isLoadingSignal.set(false);
+        }
+    }
+    async function defaultSubmitHandler(formId, formValues) {
+        try {
+            await submissions.createSubmission({
+                formId,
+                submissions: formValues,
+            });
+            // TODO: add message
+            return { type: 'success' };
+        }
+        catch (error) {
+            console.error('Form submission failed:', error);
+            return { type: 'error', message: 'Failed to submit form' };
+        }
+    }
+    /**
+     * Submits the form with the provided values.
+     * Uses custom handler if provided in config, otherwise uses default submission.
+     */
+    async function submitForm(formValues) {
+        const form = formSignal.get();
+        if (!form) {
+            console.error('Cannot submit: form not loaded');
+            return;
+        }
+        // @ts-expect-error
+        const formId = form._id ? form._id : form.id;
+        submitResponseSignal.set({ type: 'loading' });
+        try {
+            const handler = config.onSubmit || defaultSubmitHandler;
+            const response = await handler(formId, formValues);
+            submitResponseSignal.set(response);
+        }
+        catch (error) {
+            console.error('Unexpected error during submission:', error);
+            submitResponseSignal.set({
+                type: 'error',
+                message: 'Unexpected error during submission',
+            });
+        }
+    }
+    return {
+        formSignal: formSignal,
+        isLoadingSignal: isLoadingSignal,
+        errorSignal: errorSignal,
+        submitResponseSignal: submitResponseSignal,
+        submitForm: submitForm,
+    };
+});
+async function fetchForm(id) {
+    try {
+        const result = await forms.getForm(id);
+        if (!result) {
+            throw new Error(`Form ${id} not found`);
+        }
+        return result;
+    }
+    catch (err) {
+        console.error('Failed to load form:', id, err);
+        throw err;
+    }
+}
+/**
+ * Loads form service configuration from the Wix Forms API for SSR initialization.
+ * This function is designed to be used during Server-Side Rendering (SSR) to preload
+ * a specific form by ID that will be used to configure the FormService.
+ *
+ * @param {string} formId - The unique identifier of the form to load
+ * @returns {Promise<FormServiceConfig>} Configuration object with pre-loaded form data
+ * @throws {Error} When the form cannot be loaded
+ *
+ * @example
+ * ```tsx
+ * // In your SSR/SSG setup
+ * const formConfig = await loadFormServiceConfig('form-123');
+ * const formService = FormService.withConfig(formConfig);
+ * ```
+ */
+export async function loadFormServiceConfig(formId) {
+    const form = await fetchForm(formId);
+    return { form };
+}

package/dist/services/index.d.ts

@@ -0,0 +1 @@
+export * from './form-service.js';

package/dist/services/index.js

@@ -0,0 +1 @@
+export * from './form-service.js';

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@wix/headless-forms",
+  "version": "0.0.0",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "npm run build:esm && npm run build:cjs",
+    "build:esm": "tsc -p tsconfig.json",
+    "build:cjs": "tsc -p tsconfig.cjs.json",
+    "build:watch": "tsc -p tsconfig.json --watch",
+    "test": "vitest",
+    "lint:fix": "prettier --write \"src/**/*.{ts,tsx,js,jsx,json,md}\"",
+    "lint:check": "prettier --check \"src/**/*.{ts,tsx,js,jsx,json,md}\""
+  },
+  "files": [
+    "dist",
+    "cjs",
+    "react",
+    "services"
+  ],
+  "exports": {
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js",
+      "require": "./cjs/dist/react/index.js"
+    },
+    "./services": {
+      "types": "./dist/services/index.d.ts",
+      "import": "./dist/services/index.js",
+      "require": "./cjs/dist/services/index.js"
+    }
+  },
+  "devDependencies": {
+    "@testing-library/dom": "^10.4.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/react": "^16.3.0",
+    "@types/node": "^20.9.0",
+    "@vitest/ui": "^3.1.4",
+    "jsdom": "^26.1.0",
+    "prettier": "^3.4.2",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.4"
+  },
+  "dependencies": {
+    "@wix/form-public": "^0.55.0",
+    "@wix/forms": "^1.0.331",
+    "@wix/headless-utils": "0.0.0",
+    "@wix/services-definitions": "^0.1.4",
+    "@wix/services-manager-react": "^0.1.26"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "wix": {
+    "artifact": {
+      "artifactId": "headless-forms",
+      "groupId": "com.wixpress.headless-components"
+    }
+  },
+  "falconPackageHash": "dcd3156d41c136d87ea0aa02ff35682cef2a377130471163d8530f6d"
+}

package/react/package.json

@@ -0,0 +1,4 @@
+{
+  "main": "../cjs/dist/react/index.js",
+  "types": "../dist/react/index.d.ts"
+}

package/services/package.json

@@ -0,0 +1,4 @@
+{
+  "main": "../cjs/dist/services/index.js",
+  "types": "../dist/services/index.d.ts"
+}