@wix/headless-forms 0.0.2 → 0.0.4

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

@@ -1,5 +1,9 @@
 import { forms } from '@wix/forms';
-import { type Signal } from '@wix/services-definitions/core-services/signals';
+import { type ReadOnlySignal } from '@wix/services-definitions/core-services/signals';
+/**
+ * Response type for form submission operations.
+ * Represents the different states a form submission can be in.
+ */
 export type SubmitResponse = {
     type: 'success';
     message?: string;
@@ -9,181 +13,78 @@ export type SubmitResponse = {
 } | {
     type: 'idle';
 };
+/**
+ * API interface for the Form service, providing reactive form data management.
+ * This service handles loading and managing form data, loading state, and errors.
+ * It supports both pre-loaded form data and lazy loading with form IDs.
+ *
+ * @interface FormServiceAPI
+ */
 export interface FormServiceAPI {
-    form: Signal<forms.Form | null>;
-    isLoading: Signal<boolean>;
-    error: Signal<string | null>;
-    submitResponse: Signal<SubmitResponse>;
+    /** 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>;
 }
+/**
+ * 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;
 /**
- * Configuration object for initializing the Form service.
- *
- * The Form service supports two distinct patterns for providing form data:
- *
- * **Pattern 1: Pre-loaded Form Data (SSR/SSG)**
- * - Use when you have form data available at service initialization
- * - Recommended for server-side rendering and static site generation
- * - Provides immediate form availability with no loading states
- * - Better performance and SEO as form data is available immediately
+ * 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)
  *
- * **Pattern 2: Lazy Loading with Form ID (Client-side)**
- * - Use when you only have a form ID and need to load form data asynchronously
- * - Ideal for client-side routing and dynamic form loading
- * - Service will automatically fetch form data using the provided formId
- * - Provides loading states and error handling during form fetch
- *
- * @interface FormServiceConfig
- * @property {forms.Form} [form] - Pre-loaded form data. When provided, the service uses this data immediately without any network requests. Recommended for SSR/SSG scenarios.
- * @property {string} [formId] - Form ID for lazy loading. When provided (and no form data), the service will fetch form data asynchronously from the Wix Forms API. Ideal for client-side routing.
- *
- * @example
- * ```tsx
- * // Pattern 1: Pre-loaded form data (SSR/SSG)
- * // Server-side: Load form data first
- * const formServiceConfigResult = await loadFormServiceConfig('form-123');
- * if (formServiceConfigResult.type === 'success') {
- *   // Use pre-loaded form data
- *   <Form.Root formServiceConfig={formServiceConfigResult.config} />
- * }
- *
- * // Or with direct form data
- * const config1: FormServiceConfig = { form: myForm };
- * <Form.Root formServiceConfig={config1} />
- * ```
- *
- * @example
- * ```tsx
- * // Pattern 2: Lazy loading with form ID (Client-side)
- * // Simple formId-based loading - service handles the rest
- * const config2: FormServiceConfig = { formId: 'form-123' };
- * <Form.Root formServiceConfig={config2} />
- *
- * // With loading and error handling
- * <Form.Root formServiceConfig={{ formId: 'form-123' }}>
- *   <Form.Loading>
- *     {({ isLoading }) => isLoading ? <div>Loading form...</div> : null}
- *   </Form.Loading>
- *   <Form.LoadingError>
- *     {({ error, hasError }) => hasError ? <div>Error: {error}</div> : null}
- *   </Form.LoadingError>
- *   <Form.Fields fieldMap={FIELD_MAP} />
- * </Form.Root>
- * ```
- *
- * @example
- * ```tsx
- * // Pattern 3: Both provided (form takes precedence)
- * // The pre-loaded form data will be used, formId is ignored
- * const config3: FormServiceConfig = {
- *   form: myForm,
- *   formId: 'form-123' // This will be ignored
- * };
- * <Form.Root formServiceConfig={config3} />
- * ```
- *
- * @throws {Error} Throws an error if neither form nor formId is provided
+ * @type {FormServiceConfig}
  */
-export interface FormServiceConfig {
-    form?: forms.Form;
-    formId?: string;
-}
+export type FormServiceConfig = {
+    formId: string;
+} | {
+    form: forms.Form;
+};
 /**
- * Form service implementation that supports both pre-loaded form data and lazy loading.
- *
- * This service provides reactive state management for form data, loading states, errors, and submission responses.
- * It automatically handles form loading when only a formId is provided, making it suitable for both SSR and client-side scenarios.
- *
- * ## Service Behavior
- *
- * **Configuration Resolution:**
- * - If `form` is provided: Uses pre-loaded form data immediately (SSR/SSG pattern)
- * - If only `formId` is provided: Loads form data asynchronously from Wix Forms API
- * - If both are provided: Uses pre-loaded `form` data and ignores `formId`
- * - If neither is provided: Throws an error during service initialization
- *
- * **Loading States:**
- * - `isLoading`: `true` when loading form data via `formId`, `false` otherwise
- * - `form`: `null` initially when using `formId`, populated after successful load
- * - `error`: `null` initially, populated if form loading fails
- * - `submitResponse`: `{ type: 'idle' }` initially, updated during form submission
- *
- * **Error Handling:**
- * - Network errors during form loading are caught and stored in the `error` signal
- * - "Form not found" errors are handled when the formId doesn't exist
- * - All errors are logged to console for debugging
+ * Implementation of the Form service that manages reactive form data.
+ * This service provides signals for form data, loading state, and error handling.
+ * It supports both pre-loaded form data and lazy loading with form IDs.
  *
  * @example
  * ```tsx
- * // Service automatically handles loading states
- * const service = useService(FormServiceDefinition);
+ * // Pre-loaded form data (SSR/SSG)
+ * const formService = FormService.withConfig({ form: formData });
  *
- * // Check loading state
- * const isLoading = service.isLoading.get();
- *
- * // Access form data (null during loading)
- * const form = service.form.get();
- *
- * // Check for errors
- * const error = service.error.get();
+ * // Lazy loading with form ID (client-side)
+ * const formService = FormService.withConfig({ formId: 'form-123' });
  * ```
- *
  */
 export declare const FormService: import("@wix/services-definitions").ServiceFactory<string & {
     __api: FormServiceAPI;
     __config: {};
     isServiceDefinition?: boolean;
 } & FormServiceAPI, FormServiceConfig>;
-export type FormServiceConfigResult = {
-    type: 'success';
-    config: FormServiceConfig;
-} | {
-    type: 'notFound';
-};
 /**
- * Loads form service configuration by form ID.
- *
- * This function fetches form data from the Wix Forms API and returns a configuration
- * object that can be used to initialize the Form service. This is the recommended approach
- * for server-side rendering (SSR) and static site generation (SSG) scenarios.
- *
- * @param {string} id - The unique identifier of the form to load
- * @returns {Promise<FormServiceConfigResult>} A promise that resolves to either:
- *   - `{ type: 'success', config: FormServiceConfig }` if the form is found and loaded successfully
- *   - `{ type: 'notFound' }` if the form doesn't exist or an error occurs during loading
- *
- * @example
- * ```tsx
- * import { loadFormServiceConfig } from '@wix/headless-forms/services';
- *
- * // Server-side loading (Astro/SSR) - pre-loads form data
- * const formServiceConfigResult = await loadFormServiceConfig('form-id');
+ * 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.
  *
- * if (formServiceConfigResult.type === 'notFound') {
- *   return Astro.redirect('/404');
- * }
- *
- * // Use pre-loaded form data
- * const formServiceConfig = formServiceConfigResult.config;
- * <Form.Root formServiceConfig={formServiceConfig} />
- * ```
+ * @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
- * // Alternative: Client-side loading with formId
- * // No need to pre-load, service handles loading automatically
- * <Form.Root formServiceConfig={{ formId: 'form-id' }}>
- *   <Form.Loading>
- *     {({ isLoading }) => isLoading ? <div>Loading...</div> : null}
- *   </Form.Loading>
- *   <Form.Fields fieldMap={FIELD_MAP} />
- * </Form.Root>
+ * // In your SSR/SSG setup
+ * const formConfig = await loadFormServiceConfig('form-123');
+ * const formService = FormService.withConfig(formConfig);
  * ```
- *
- * @throws {Error} Logs errors to console but returns 'notFound' result instead of throwing
  */
-export declare function loadFormServiceConfig(id: string): Promise<FormServiceConfigResult>;
+export declare function loadFormServiceConfig(formId: string): Promise<FormServiceConfig>;

package/cjs/dist/services/form-service.js

@@ -5,137 +5,92 @@ exports.loadFormServiceConfig = loadFormServiceConfig;
 const forms_1 = require("@wix/forms");
 const services_definitions_1 = require("@wix/services-definitions");
 const signals_1 = require("@wix/services-definitions/core-services/signals");
-exports.FormServiceDefinition = (0, services_definitions_1.defineService)('formService');
 /**
- * Form service implementation that supports both pre-loaded form data and lazy loading.
- *
- * This service provides reactive state management for form data, loading states, errors, and submission responses.
- * It automatically handles form loading when only a formId is provided, making it suitable for both SSR and client-side scenarios.
- *
- * ## Service Behavior
- *
- * **Configuration Resolution:**
- * - If `form` is provided: Uses pre-loaded form data immediately (SSR/SSG pattern)
- * - If only `formId` is provided: Loads form data asynchronously from Wix Forms API
- * - If both are provided: Uses pre-loaded `form` data and ignores `formId`
- * - If neither is provided: Throws an error during service initialization
+ * Service definition for the Form service.
+ * This defines the contract that the FormService must implement.
  *
- * **Loading States:**
- * - `isLoading`: `true` when loading form data via `formId`, `false` otherwise
- * - `form`: `null` initially when using `formId`, populated after successful load
- * - `error`: `null` initially, populated if form loading fails
- * - `submitResponse`: `{ type: 'idle' }` initially, updated during form submission
- *
- * **Error Handling:**
- * - Network errors during form loading are caught and stored in the `error` signal
- * - "Form not found" errors are handled when the formId doesn't exist
- * - All errors are logged to console for debugging
+ * @constant
+ */
+exports.FormServiceDefinition = (0, services_definitions_1.defineService)('formService');
+/**
+ * Implementation of the Form service that manages reactive form data.
+ * This service provides signals for form data, loading state, and error handling.
+ * It supports both pre-loaded form data and lazy loading with form IDs.
  *
  * @example
  * ```tsx
- * // Service automatically handles loading states
- * const service = useService(FormServiceDefinition);
+ * // Pre-loaded form data (SSR/SSG)
+ * const formService = FormService.withConfig({ form: formData });
  *
- * // Check loading state
- * const isLoading = service.isLoading.get();
- *
- * // Access form data (null during loading)
- * const form = service.form.get();
- *
- * // Check for errors
- * const error = service.error.get();
+ * // Lazy loading with form ID (client-side)
+ * const formService = FormService.withConfig({ formId: 'form-123' });
  * ```
- *
  */
 exports.FormService = services_definitions_1.implementService.withConfig()(exports.FormServiceDefinition, ({ getService, config }) => {
     const signalsService = getService(signals_1.SignalsServiceDefinition);
-    const { form: initialForm, formId } = config;
-    // Validation: ensure either form or formId is provided
-    if (!initialForm && !formId) {
-        throw new Error('FormServiceConfig must provide either "form" or "formId"');
+    const isLoadingSignal = signalsService.signal(false);
+    const errorSignal = signalsService.signal(null);
+    const hasSchema = 'form' in config;
+    const formSignal = signalsService.signal(hasSchema ? config.form : null);
+    if (!hasSchema) {
+        loadForm(config.formId);
     }
-    const form = signalsService.signal(initialForm || null);
-    const isLoading = signalsService.signal(!!formId && !initialForm);
-    const error = signalsService.signal(null);
-    const submitResponse = signalsService.signal({ type: 'idle' });
-    // Client-side form loading for formId case
-    if (formId && !initialForm) {
-        // Load form asynchronously
-        forms_1.forms
-            .getForm(formId)
-            .then((loadedForm) => {
-            if (loadedForm) {
-                form.set(loadedForm);
-                isLoading.set(false);
+    async function loadForm(id) {
+        isLoadingSignal.set(true);
+        errorSignal.set(null);
+        try {
+            const result = await fetchForm(id);
+            if (result) {
+                formSignal.set(result);
             }
             else {
-                error.set('Form not found');
-                isLoading.set(false);
+                errorSignal.set('Form not found');
             }
-        })
-            .catch((err) => {
-            console.error('Failed to load form:', err);
-            error.set('Failed to load form');
-            isLoading.set(false);
-        });
+        }
+        catch (err) {
+            errorSignal.set('Failed to load form');
+            throw err;
+        }
+        finally {
+            isLoadingSignal.set(false);
+        }
     }
-    return { form, isLoading, error, submitResponse };
+    return {
+        formSignal: formSignal,
+        isLoadingSignal: isLoadingSignal,
+        errorSignal: errorSignal,
+    };
 });
+async function fetchForm(id) {
+    try {
+        const result = await forms_1.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 by form ID.
- *
- * This function fetches form data from the Wix Forms API and returns a configuration
- * object that can be used to initialize the Form service. This is the recommended approach
- * for server-side rendering (SSR) and static site generation (SSG) scenarios.
- *
- * @param {string} id - The unique identifier of the form to load
- * @returns {Promise<FormServiceConfigResult>} A promise that resolves to either:
- *   - `{ type: 'success', config: FormServiceConfig }` if the form is found and loaded successfully
- *   - `{ type: 'notFound' }` if the form doesn't exist or an error occurs during loading
- *
- * @example
- * ```tsx
- * import { loadFormServiceConfig } from '@wix/headless-forms/services';
+ * 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.
  *
- * // Server-side loading (Astro/SSR) - pre-loads form data
- * const formServiceConfigResult = await loadFormServiceConfig('form-id');
- *
- * if (formServiceConfigResult.type === 'notFound') {
- *   return Astro.redirect('/404');
- * }
- *
- * // Use pre-loaded form data
- * const formServiceConfig = formServiceConfigResult.config;
- * <Form.Root formServiceConfig={formServiceConfig} />
- * ```
+ * @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
- * // Alternative: Client-side loading with formId
- * // No need to pre-load, service handles loading automatically
- * <Form.Root formServiceConfig={{ formId: 'form-id' }}>
- *   <Form.Loading>
- *     {({ isLoading }) => isLoading ? <div>Loading...</div> : null}
- *   </Form.Loading>
- *   <Form.Fields fieldMap={FIELD_MAP} />
- * </Form.Root>
+ * // In your SSR/SSG setup
+ * const formConfig = await loadFormServiceConfig('form-123');
+ * const formService = FormService.withConfig(formConfig);
  * ```
- *
- * @throws {Error} Logs errors to console but returns 'notFound' result instead of throwing
  */
-async function loadFormServiceConfig(id) {
-    try {
-        const form = await forms_1.forms.getForm(id);
-        if (!form) {
-            return { type: 'notFound' };
-        }
-        return {
-            type: 'success',
-            config: { form },
-        };
-    }
-    catch (error) {
-        console.error('Failed to load form:', error);
-    }
-    return { type: 'notFound' };
+async function loadFormServiceConfig(formId) {
+    const form = await fetchForm(formId);
+    return { form };
 }

package/dist/react/Form.d.ts

@@ -22,6 +22,7 @@ export interface RootProps {
  * @param {RootProps} props - The component props
  * @param {React.ReactNode} props.children - Child components that will have access to form context
  * @param {FormServiceConfig} props.formServiceConfig - Form service configuration object
+ * @param {boolean} [props.asChild] - Whether to render as a child component
  * @param {string} [props.className] - CSS classes to apply to the root element
  * @example
  * ```tsx
@@ -368,7 +369,7 @@ export declare const Submitted: React.ForwardRefExoticComponent<SubmittedProps &
  * };
  * ```
  */
-interface FieldMap {
+export interface FieldMap {
     TEXT_INPUT: React.ComponentType<TextInputProps>;
     TEXT_AREA: React.ComponentType<TextAreaProps>;
     PHONE_INPUT: React.ComponentType<PhoneInputProps>;
@@ -416,7 +417,7 @@ interface FieldMap {
  * <Form.Fields fieldMap={FIELD_MAP} />
  * ```
  */
-export interface FieldsProps {
+interface FieldsProps {
     fieldMap: FieldMap;
 }
 /**
@@ -564,69 +565,4 @@ export interface FieldsProps {
  * ```
  */
 export declare const Fields: React.ForwardRefExoticComponent<FieldsProps & React.RefAttributes<HTMLDivElement>>;
-/**
- * Main Form namespace containing all form components following the compound component pattern.
- * Provides a headless, flexible way to render and manage forms with custom field components.
- *
- * @namespace Form
- * @property {typeof Root} Root - Form root component that provides service context to all child components
- * @property {typeof Loading} Loading - Form loading state component that displays content during form loading
- * @property {typeof LoadingError} LoadingError - Form loading error state component for handling form loading errors
- * @property {typeof Error} Error - Form submit error state component for handling form submission errors
- * @property {typeof Submitted} Submitted - Form submitted state component for displaying success messages
- * @property {typeof Fields} Fields - Form fields component for rendering form fields with custom field renderers
- * @example
- * ```tsx
- * import { Form } from '@wix/headless-forms/react';
- * import { loadFormServiceConfig } from '@wix/headless-forms/services';
- * import { TextInput, TextArea, Checkbox } from './field-components';
- *
- * const FIELD_MAP = {
- *   TEXT_INPUT: TextInput,
- *   TEXT_AREA: TextArea,
- *   CHECKBOX: Checkbox,
- *   // ... other field components
- * };
- *
- * // Pattern 1: Pre-loaded form data (SSR/SSG)
- * function MyForm({ formServiceConfig }) {
- *   return (
- *     <Form.Root formServiceConfig={formServiceConfig}>
- *       <Form.Loading className="flex justify-center p-4" />
- *       <Form.LoadingError className="text-destructive px-4 py-3 rounded mb-4" />
- *       <Form.Fields fieldMap={FIELD_MAP} />
- *       <Form.Error className="text-destructive p-4 rounded-lg mb-4" />
- *       <Form.Submitted className="text-green-500 p-4 rounded-lg mb-4" />
- *     </Form.Root>
- *   );
- * }
- *
- * // Pattern 2: Lazy loading with formId (Client-side)
- * function DynamicForm({ formId }) {
- *   return (
- *     <Form.Root formServiceConfig={{ formId }}>
- *       <Form.Loading className="flex justify-center p-4" />
- *       <Form.LoadingError className="text-destructive px-4 py-3 rounded mb-4" />
- *       <Form.Fields fieldMap={FIELD_MAP} />
- *       <Form.Error className="text-destructive p-4 rounded-lg mb-4" />
- *       <Form.Submitted className="text-green-500 p-4 rounded-lg mb-4" />
- *     </Form.Root>
- *   );
- * }
- * ```
- */
-export declare const Form: {
-    /** Form root component that provides service context */
-    readonly Root: React.ForwardRefExoticComponent<RootProps & React.RefAttributes<HTMLDivElement>>;
-    /** Form loading state component */
-    readonly Loading: React.ForwardRefExoticComponent<LoadingProps & React.RefAttributes<HTMLElement>>;
-    /** Form loading error state component */
-    readonly LoadingError: React.ForwardRefExoticComponent<LoadingErrorProps & React.RefAttributes<HTMLElement>>;
-    /** Form error state component */
-    readonly Error: React.ForwardRefExoticComponent<ErrorProps & React.RefAttributes<HTMLElement>>;
-    /** Form submitted state component */
-    readonly Submitted: React.ForwardRefExoticComponent<SubmittedProps & React.RefAttributes<HTMLElement>>;
-    /** Form fields component for rendering form fields */
-    readonly Fields: React.ForwardRefExoticComponent<FieldsProps & React.RefAttributes<HTMLDivElement>>;
-};
 export {};