@wix/headless-forms 0.0.22 → 0.0.23

package/cjs/dist/react/Form.d.ts

@@ -1,6 +1,6 @@
 import React from 'react';
 import { type FormError } from '@wix/form-public';
-import { type CheckboxGroupProps, type CheckboxProps, type PhoneInputProps, type DateInputProps, type DatePickerProps, type DateTimeInputProps, type DropdownProps, type FileUploadProps, type MultilineAddressProps, type NumberInputProps, type RadioGroupProps, type RatingInputProps, type RichTextProps, type SignatureProps, type SubmitButtonProps, type TagsProps, type TextAreaProps, type TextInputProps, type TimeInputProps, type ProductListProps, type FixedPaymentProps, type PaymentInputProps, type DonationProps, type AppointmentProps, type ImageChoiceProps } from './types.js';
+import { type CheckboxGroupProps, type CheckboxProps, type PhoneInputProps, type DateInputProps, type DatePickerProps, type DateTimeInputProps, type DropdownProps, type FileUploadProps, type MultilineAddressProps, type NumberInputProps, type RadioGroupProps, type RatingInputProps, type RichTextProps, type SignatureProps, type SubmitButtonProps, type TagsProps, type TextAreaProps, type TextInputProps, type TimeInputProps, type ProductListProps, type FixedPaymentProps, type PaymentInputProps, type DonationProps, type AppointmentProps, type ImageChoiceProps, type LoginBarProps } from './types.js';
 import { type FormServiceConfig } from '../services/form-service.js';
 /**
  * Props for the Form root component following the documented API
@@ -22,7 +22,9 @@ export interface RootProps {
  * @component
  * @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 {FormServiceConfig} props.formServiceConfig - Form service configuration object. Supports two patterns:
+ *   - Pre-loaded form data: `{ form: Form, onSubmit?: Function, addressTemplates?: any[] }`
+ *   - Lazy loading: `{ formId: string, namespace?: string, additionalMetadata?: Record<string, string | string[]>, onSubmit?: Function }`
  * @param {boolean} [props.asChild] - Whether to render as a child component
  * @param {string} [props.className] - CSS classes to apply to the root element
  * @example
@@ -62,6 +64,25 @@ export interface RootProps {
  *     </Form.Root>
  *   );
  * }
+ *
+ * // Pattern 3: With namespace and additional metadata (for bookings, etc.)
+ * function BookingFormPage({ formId }) {
+ *   return (
+ *     <Form.Root
+ *       formServiceConfig={{
+ *         formId,
+ *         namespace: 'wix.bookings.form',
+ *         additionalMetadata: { serviceId: ['service-123'] },
+ *       }}
+ *     >
+ *       <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 Root: React.ForwardRefExoticComponent<RootProps & React.RefAttributes<HTMLDivElement>>;
@@ -399,6 +420,7 @@ export interface FieldMap {
     DONATION: React.ComponentType<DonationProps>;
     APPOINTMENT: React.ComponentType<AppointmentProps>;
     IMAGE_CHOICE: React.ComponentType<ImageChoiceProps>;
+    LOGIN_BAR: React.ComponentType<LoginBarProps>;
 }
 /**
  * Props for the Form Fields component.

package/cjs/dist/react/Form.js

@@ -65,7 +65,9 @@ var TestIds;
  * @component
  * @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 {FormServiceConfig} props.formServiceConfig - Form service configuration object. Supports two patterns:
+ *   - Pre-loaded form data: `{ form: Form, onSubmit?: Function, addressTemplates?: any[] }`
+ *   - Lazy loading: `{ formId: string, namespace?: string, additionalMetadata?: Record<string, string | string[]>, onSubmit?: Function }`
  * @param {boolean} [props.asChild] - Whether to render as a child component
  * @param {string} [props.className] - CSS classes to apply to the root element
  * @example
@@ -105,11 +107,30 @@ var TestIds;
  *     </Form.Root>
  *   );
  * }
+ *
+ * // Pattern 3: With namespace and additional metadata (for bookings, etc.)
+ * function BookingFormPage({ formId }) {
+ *   return (
+ *     <Form.Root
+ *       formServiceConfig={{
+ *         formId,
+ *         namespace: 'wix.bookings.form',
+ *         additionalMetadata: { serviceId: ['service-123'] },
+ *       }}
+ *     >
+ *       <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>
+ *   );
+ * }
  * ```
  */
 exports.Root = react_1.default.forwardRef((props, ref) => {
     const { children, formServiceConfig, asChild, ...otherProps } = props;
-    return ((0, jsx_runtime_1.jsx)(Form_js_1.Root, { formServiceConfig: formServiceConfig, children: (0, jsx_runtime_1.jsx)(RootContent, { asChild: asChild, ref: ref, ...otherProps, children: children }) }));
+    return ((0, jsx_runtime_1.jsx)(Form_js_1.Root, { formServiceConfig: formServiceConfig, formRef: ref, children: (0, jsx_runtime_1.jsx)(RootContent, { asChild: asChild, ref: ref, ...otherProps, children: children }) }));
 });
 /**
  * Internal component to handle the Root content with service access.
@@ -528,16 +549,17 @@ exports.Fields = react_1.default.forwardRef((props, ref) => {
     const [formErrors, setFormErrors] = (0, react_1.useState)([]);
     const currentLocale = essentials_1.i18n.getLocale();
     const currentLanguage = essentials_1.i18n.getLanguage();
+    const formRef = (0, Form_js_1.useFormRef)();
     const handleFormValidate = (0, react_1.useCallback)((errors) => {
         setFormErrors(errors);
     }, []);
     return ((0, jsx_runtime_1.jsx)(Form_js_1.Fields, { children: ({ form, formValues, submitForm, handleForm, addressTemplates }) => {
             if (!form)
                 return null;
-            return ((0, jsx_runtime_1.jsx)("div", { ref: ref, children: (0, jsx_runtime_1.jsx)(form_public_1.FormProvider, { currency: 'USD', locale: currentLanguage, regionalFormat: currentLocale, addressTemplates: addressTemplates, children: (0, jsx_runtime_1.jsx)(form_public_1.UniqueFieldSuffixContextProvider, { parentId: form._id ?? '', children: (0, jsx_runtime_1.jsx)(FieldsWithForm, { form: form, values: formValues, onChange: handleForm, errors: formErrors, onValidate: handleFormValidate, fields: props.fieldMap, submitForm: submitForm, rowGapClassname: props.rowGapClassname, columnGapClassname: props.columnGapClassname }) }) }) }));
+            return ((0, jsx_runtime_1.jsx)("div", { ref: ref, children: (0, jsx_runtime_1.jsx)(form_public_1.FormProvider, { currency: 'USD', locale: currentLanguage, regionalFormat: currentLocale, addressTemplates: addressTemplates, children: (0, jsx_runtime_1.jsx)(form_public_1.UniqueFieldSuffixContextProvider, { parentId: form._id ?? '', children: (0, jsx_runtime_1.jsx)(FieldsWithForm, { form: form, values: formValues, onChange: handleForm, errors: formErrors, onValidate: handleFormValidate, fields: props.fieldMap, submitForm: submitForm, rowGapClassname: props.rowGapClassname, columnGapClassname: props.columnGapClassname, formRef: formRef }) }) }) }));
         } }));
 });
-const FieldsWithForm = ({ form, submitForm, values, onChange, errors, onValidate, fields: fieldMap, rowGapClassname, columnGapClassname, }) => {
+const FieldsWithForm = ({ form, submitForm, values, onChange, errors, onValidate, fields: fieldMap, rowGapClassname, columnGapClassname, formRef, }) => {
     const coreUploadFile = async ({ file, formId, }) => {
         const uploadUrl = await (0, utils_1.getUploadUrl)(formId, file);
         if (uploadUrl === undefined) {
@@ -560,6 +582,7 @@ const FieldsWithForm = ({ form, submitForm, values, onChange, errors, onValidate
         submitForm,
         uploadFile: coreUploadFile,
         fieldMap,
+        forwardedRef: formRef,
     });
     if (!formData)
         return null;

package/cjs/dist/react/core/Form.d.ts

@@ -1,12 +1,19 @@
+import React from 'react';
 import { forms } from '@wix/forms';
 import { FormServiceConfig } from '../../services/form-service.js';
 import { FormValues } from '../types.js';
+/**
+ * Hook to access the form ref from context
+ */
+export declare function useFormRef(): React.Ref<any> | undefined;
 /**
  * Props for Root headless component
  */
 export interface RootProps {
     children: React.ReactNode;
     formServiceConfig: FormServiceConfig;
+    /** Optional ref to access form methods imperatively */
+    formRef?: React.Ref<any>;
 }
 /**
  * Root component that provides the Form service context to its children.
@@ -16,7 +23,9 @@ export interface RootProps {
  * @component
  * @param {RootProps} props - Component props
  * @param {React.ReactNode} props.children - Child components that will have access to form context
- * @param {FormServiceConfig} props.formServiceConfig - Configuration object containing form data
+ * @param {FormServiceConfig} props.formServiceConfig - Configuration object containing form data. Supports two patterns:
+ *   - Pre-loaded form data: `{ form: Form, onSubmit?: Function, addressTemplates?: any[] }`
+ *   - Lazy loading: `{ formId: string, namespace?: string, additionalMetadata?: Record<string, string | string[]>, onSubmit?: Function }`
  * @example
  * ```tsx
  * import { Form } from '@wix/headless-forms/react';
@@ -51,9 +60,30 @@ export interface RootProps {
  *     </Form.Root>
  *   );
  * }
+ *
+ * // Pattern 3: With namespace and additional metadata (for bookings, etc.)
+ * function BookingFormPage({ formId }) {
+ *   return (
+ *     <Form.Root
+ *       formServiceConfig={{
+ *         formId,
+ *         namespace: 'wix.bookings.form',
+ *         additionalMetadata: { serviceId: ['service-123'] },
+ *       }}
+ *     >
+ *       <Form.Loading>
+ *         {({ isLoading }) => isLoading ? <div>Loading form...</div> : null}
+ *       </Form.Loading>
+ *       <Form.LoadingError>
+ *         {({ error, hasError }) => hasError ? <div>{error}</div> : null}
+ *       </Form.LoadingError>
+ *       <Form.Fields fieldMap={FIELD_MAP} />
+ *     </Form.Root>
+ *   );
+ * }
  * ```
  */
-export declare function Root({ formServiceConfig, children, }: RootProps): React.ReactNode;
+export declare function Root({ formServiceConfig, formRef, children, }: RootProps): React.ReactNode;
 /**
  * Props for FormLoading headless component
  */
@@ -91,7 +121,7 @@ export interface FormLoadingRenderProps {
  * }
  * ```
  */
-export declare function Loading(props: FormLoadingProps): import("react").ReactNode;
+export declare function Loading(props: FormLoadingProps): React.ReactNode;
 /**
  * Props for FormError headless component
  */
@@ -133,7 +163,7 @@ export interface FormErrorRenderProps {
  * }
  * ```
  */
-export declare function LoadingError(props: FormErrorProps): import("react").ReactNode;
+export declare function LoadingError(props: FormErrorProps): React.ReactNode;
 /**
  * Props for Form Submit Error headless component
  */
@@ -175,7 +205,7 @@ export interface FormSubmitErrorRenderProps {
  * }
  * ```
  */
-export declare function Error(props: FormSubmitErrorProps): import("react").ReactNode;
+export declare function Error(props: FormSubmitErrorProps): React.ReactNode;
 /**
  * Props for Form Submitted headless component
  */
@@ -218,7 +248,7 @@ export interface FormSubmittedRenderProps {
  * }
  * ```
  */
-export declare function Submitted(props: FormSubmittedProps): import("react").ReactNode;
+export declare function Submitted(props: FormSubmittedProps): React.ReactNode;
 /**
  * Render props for Fields component
  */
@@ -269,7 +299,7 @@ export interface FieldsProps {
  * }
  * ```
  */
-export declare function Fields(props: FieldsProps): import("react").ReactNode;
+export declare function Fields(props: FieldsProps): React.ReactNode;
 /**
  * Form view interface containing field definitions
  */
@@ -342,4 +372,4 @@ export interface FieldProps {
  * }
  * ```
  */
-export declare function Field(props: FieldProps): import("react").ReactNode;
+export declare function Field(props: FieldProps): React.ReactNode;

package/cjs/dist/react/core/Form.js

@@ -1,5 +1,9 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.useFormRef = useFormRef;
 exports.Root = Root;
 exports.Loading = Loading;
 exports.LoadingError = LoadingError;
@@ -8,11 +12,22 @@ exports.Submitted = Submitted;
 exports.Fields = Fields;
 exports.Field = Field;
 const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = __importDefault(require("react"));
 const services_manager_react_1 = require("@wix/services-manager-react");
 const services_manager_1 = require("@wix/services-manager");
 const form_service_js_1 = require("../../services/form-service.js");
 const utils_js_1 = require("../utils.js");
 const DEFAULT_SUCCESS_MESSAGE = 'Your form has been submitted successfully.';
+/**
+ * Context for passing form ref from Root to Fields
+ */
+const FormRefContext = react_1.default.createContext(undefined);
+/**
+ * Hook to access the form ref from context
+ */
+function useFormRef() {
+    return react_1.default.useContext(FormRefContext);
+}
 /**
  * Root component that provides the Form service context to its children.
  * This component sets up the necessary services for rendering and managing form data.
@@ -21,7 +36,9 @@ const DEFAULT_SUCCESS_MESSAGE = 'Your form has been submitted successfully.';
  * @component
  * @param {RootProps} props - Component props
  * @param {React.ReactNode} props.children - Child components that will have access to form context
- * @param {FormServiceConfig} props.formServiceConfig - Configuration object containing form data
+ * @param {FormServiceConfig} props.formServiceConfig - Configuration object containing form data. Supports two patterns:
+ *   - Pre-loaded form data: `{ form: Form, onSubmit?: Function, addressTemplates?: any[] }`
+ *   - Lazy loading: `{ formId: string, namespace?: string, additionalMetadata?: Record<string, string | string[]>, onSubmit?: Function }`
  * @example
  * ```tsx
  * import { Form } from '@wix/headless-forms/react';
@@ -56,10 +73,31 @@ const DEFAULT_SUCCESS_MESSAGE = 'Your form has been submitted successfully.';
  *     </Form.Root>
  *   );
  * }
+ *
+ * // Pattern 3: With namespace and additional metadata (for bookings, etc.)
+ * function BookingFormPage({ formId }) {
+ *   return (
+ *     <Form.Root
+ *       formServiceConfig={{
+ *         formId,
+ *         namespace: 'wix.bookings.form',
+ *         additionalMetadata: { serviceId: ['service-123'] },
+ *       }}
+ *     >
+ *       <Form.Loading>
+ *         {({ isLoading }) => isLoading ? <div>Loading form...</div> : null}
+ *       </Form.Loading>
+ *       <Form.LoadingError>
+ *         {({ error, hasError }) => hasError ? <div>{error}</div> : null}
+ *       </Form.LoadingError>
+ *       <Form.Fields fieldMap={FIELD_MAP} />
+ *     </Form.Root>
+ *   );
+ * }
  * ```
  */
-function Root({ formServiceConfig, children, }) {
-    return ((0, jsx_runtime_1.jsx)(services_manager_react_1.WixServices, { servicesMap: (0, services_manager_1.createServicesMap)().addService(form_service_js_1.FormServiceDefinition, form_service_js_1.FormService, formServiceConfig), children: children }));
+function Root({ formServiceConfig, formRef, children, }) {
+    return ((0, jsx_runtime_1.jsx)(services_manager_react_1.WixServices, { servicesMap: (0, services_manager_1.createServicesMap)().addService(form_service_js_1.FormServiceDefinition, form_service_js_1.FormService, formServiceConfig), children: (0, jsx_runtime_1.jsx)(FormRefContext.Provider, { value: formRef, children: children }) }));
 }
 /**
  * Headless component for form loading state access

package/cjs/dist/react/types.d.ts

@@ -1,5 +1,5 @@
-import { type CheckboxGroupProps, type CheckboxProps, type PhoneInputProps, type DateInputProps, type DatePickerProps, type DateTimeInputProps, type DropdownProps, type FileUploadProps, type MultilineAddressProps, type NumberInputProps, type RadioGroupProps, type RatingInputProps, type RichTextProps, type SignatureProps, type SubmitButtonProps, type TagsProps, type TextAreaProps, type TextInputProps, type TimeInputProps, type ProductListProps, type FixedPaymentProps, type PaymentInputProps, type DonationProps, type AppointmentProps, type ImageChoiceProps } from '@wix/form-public';
-export type { CheckboxGroupProps, CheckboxProps, PhoneInputProps, DateInputProps, DatePickerProps, DateTimeInputProps, DropdownProps, FileUploadProps, MultilineAddressProps, NumberInputProps, RadioGroupProps, RatingInputProps, RichTextProps, SignatureProps, SubmitButtonProps, TagsProps, TextAreaProps, TextInputProps, TimeInputProps, ProductListProps, FixedPaymentProps, PaymentInputProps, DonationProps, AppointmentProps, ImageChoiceProps, };
+import { type CheckboxGroupProps, type CheckboxProps, type PhoneInputProps, type DateInputProps, type DatePickerProps, type DateTimeInputProps, type DropdownProps, type FileUploadProps, type MultilineAddressProps, type NumberInputProps, type RadioGroupProps, type RatingInputProps, type RichTextProps, type SignatureProps, type SubmitButtonProps, type TagsProps, type TextAreaProps, type TextInputProps, type TimeInputProps, type ProductListProps, type FixedPaymentProps, type PaymentInputProps, type DonationProps, type AppointmentProps, type ImageChoiceProps, type UseFormProps, type LoginBarProps } from '@wix/form-public';
+export type { CheckboxGroupProps, CheckboxProps, PhoneInputProps, DateInputProps, DatePickerProps, DateTimeInputProps, DropdownProps, FileUploadProps, MultilineAddressProps, NumberInputProps, RadioGroupProps, RatingInputProps, RichTextProps, SignatureProps, SubmitButtonProps, TagsProps, TextAreaProps, TextInputProps, TimeInputProps, ProductListProps, FixedPaymentProps, PaymentInputProps, DonationProps, AppointmentProps, ImageChoiceProps, UseFormProps, LoginBarProps, };
 export type FormValues = Record<string, any>;
 export interface UploadFileParams {
     file: File;

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

@@ -5,8 +5,8 @@ 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");
-const essentials_1 = require("@wix/essentials");
 const address_forms_js_1 = require("./utils/address-forms.js");
+const auto_sdk_forms_forms_1 = require("@wix/auto_sdk_forms_forms");
 /**
  * Service definition for the Form service.
  * This defines the contract that the FormService must implement.
@@ -151,41 +151,18 @@ exports.FormService = services_definitions_1.implementService.withConfig()(expor
         handleForm,
     };
 });
-function buildFormFetchQueryParams({ id, namespace, additionalMetadata, }) {
-    const params = new URLSearchParams();
-    params.append('formId', id);
-    if (namespace) {
-        params.append('namespace', namespace);
-    }
-    if (additionalMetadata) {
-        Object.entries(additionalMetadata).forEach(([key, value]) => {
-            if (Array.isArray(value)) {
-                value.forEach((v) => params.append(key, v));
-            }
-            else {
-                params.append(key, value);
-            }
-        });
-    }
-    return params;
-}
-async function fetchForm({ id, namespace, additionalMetadata, }) {
+async function fetchForm({ id, namespace = 'wix.form_app.form', additionalMetadata, }) {
     try {
-        const params = buildFormFetchQueryParams({
-            id,
-            namespace,
+        const response = await forms_1.forms.listForms(namespace, {
             additionalMetadata,
+            formIds: [id],
+            fieldsets: [auto_sdk_forms_forms_1.Fieldset.NESTED_FORMS],
         });
-        const url = `https://www.wixapis.com/form-schema-service/v4/forms/${id}?${params.toString()}`;
-        const response = await essentials_1.httpClient.fetchWithAuth(url);
-        if (!response.ok) {
-            throw new Error(`Failed to fetch form: ${response.status} ${response.statusText}`);
-        }
-        const data = await response.json();
-        if (data && data.form) {
-            return data.form;
+        const form = response.forms?.[0];
+        if (!form) {
+            throw new Error('Form not found');
         }
-        throw new Error('Invalid response format from Forms API');
+        return form;
     }
     catch (err) {
         console.error('Failed to load form:', id, err);

package/dist/react/Form.d.ts

@@ -1,6 +1,6 @@
 import React from 'react';
 import { type FormError } from '@wix/form-public';
-import { type CheckboxGroupProps, type CheckboxProps, type PhoneInputProps, type DateInputProps, type DatePickerProps, type DateTimeInputProps, type DropdownProps, type FileUploadProps, type MultilineAddressProps, type NumberInputProps, type RadioGroupProps, type RatingInputProps, type RichTextProps, type SignatureProps, type SubmitButtonProps, type TagsProps, type TextAreaProps, type TextInputProps, type TimeInputProps, type ProductListProps, type FixedPaymentProps, type PaymentInputProps, type DonationProps, type AppointmentProps, type ImageChoiceProps } from './types.js';
+import { type CheckboxGroupProps, type CheckboxProps, type PhoneInputProps, type DateInputProps, type DatePickerProps, type DateTimeInputProps, type DropdownProps, type FileUploadProps, type MultilineAddressProps, type NumberInputProps, type RadioGroupProps, type RatingInputProps, type RichTextProps, type SignatureProps, type SubmitButtonProps, type TagsProps, type TextAreaProps, type TextInputProps, type TimeInputProps, type ProductListProps, type FixedPaymentProps, type PaymentInputProps, type DonationProps, type AppointmentProps, type ImageChoiceProps, type LoginBarProps } from './types.js';
 import { type FormServiceConfig } from '../services/form-service.js';
 /**
  * Props for the Form root component following the documented API
@@ -22,7 +22,9 @@ export interface RootProps {
  * @component
  * @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 {FormServiceConfig} props.formServiceConfig - Form service configuration object. Supports two patterns:
+ *   - Pre-loaded form data: `{ form: Form, onSubmit?: Function, addressTemplates?: any[] }`
+ *   - Lazy loading: `{ formId: string, namespace?: string, additionalMetadata?: Record<string, string | string[]>, onSubmit?: Function }`
  * @param {boolean} [props.asChild] - Whether to render as a child component
  * @param {string} [props.className] - CSS classes to apply to the root element
  * @example
@@ -62,6 +64,25 @@ export interface RootProps {
  *     </Form.Root>
  *   );
  * }
+ *
+ * // Pattern 3: With namespace and additional metadata (for bookings, etc.)
+ * function BookingFormPage({ formId }) {
+ *   return (
+ *     <Form.Root
+ *       formServiceConfig={{
+ *         formId,
+ *         namespace: 'wix.bookings.form',
+ *         additionalMetadata: { serviceId: ['service-123'] },
+ *       }}
+ *     >
+ *       <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 Root: React.ForwardRefExoticComponent<RootProps & React.RefAttributes<HTMLDivElement>>;
@@ -399,6 +420,7 @@ export interface FieldMap {
     DONATION: React.ComponentType<DonationProps>;
     APPOINTMENT: React.ComponentType<AppointmentProps>;
     IMAGE_CHOICE: React.ComponentType<ImageChoiceProps>;
+    LOGIN_BAR: React.ComponentType<LoginBarProps>;
 }
 /**
  * Props for the Form Fields component.

package/dist/react/Form.js

@@ -3,7 +3,7 @@ import React, { useState, useCallback } from 'react';
 import { AsChildSlot } from '@wix/headless-utils/react';
 import { useForm, FormProvider, UniqueFieldSuffixContextProvider, } from '@wix/form-public';
 import { i18n } from '@wix/essentials';
-import { Root as CoreRoot, Loading as CoreLoading, LoadingError as CoreLoadingError, Error as CoreError, Submitted as CoreSubmitted, Fields as CoreFields, Field as CoreField, } from './core/Form.js';
+import { Root as CoreRoot, Loading as CoreLoading, LoadingError as CoreLoadingError, Error as CoreError, Submitted as CoreSubmitted, Fields as CoreFields, Field as CoreField, useFormRef, } from './core/Form.js';
 import { FieldContext, useFieldContext, } from './context/FieldContext.js';
 import { FieldLayoutProvider, useFieldLayout, } from './context/FieldLayoutContext.js';
 import { getUploadUrl, uploadFile } from '../services/utils';
@@ -29,7 +29,9 @@ var TestIds;
  * @component
  * @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 {FormServiceConfig} props.formServiceConfig - Form service configuration object. Supports two patterns:
+ *   - Pre-loaded form data: `{ form: Form, onSubmit?: Function, addressTemplates?: any[] }`
+ *   - Lazy loading: `{ formId: string, namespace?: string, additionalMetadata?: Record<string, string | string[]>, onSubmit?: Function }`
  * @param {boolean} [props.asChild] - Whether to render as a child component
  * @param {string} [props.className] - CSS classes to apply to the root element
  * @example
@@ -69,11 +71,30 @@ var TestIds;
  *     </Form.Root>
  *   );
  * }
+ *
+ * // Pattern 3: With namespace and additional metadata (for bookings, etc.)
+ * function BookingFormPage({ formId }) {
+ *   return (
+ *     <Form.Root
+ *       formServiceConfig={{
+ *         formId,
+ *         namespace: 'wix.bookings.form',
+ *         additionalMetadata: { serviceId: ['service-123'] },
+ *       }}
+ *     >
+ *       <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 const Root = React.forwardRef((props, ref) => {
     const { children, formServiceConfig, asChild, ...otherProps } = props;
-    return (_jsx(CoreRoot, { formServiceConfig: formServiceConfig, children: _jsx(RootContent, { asChild: asChild, ref: ref, ...otherProps, children: children }) }));
+    return (_jsx(CoreRoot, { formServiceConfig: formServiceConfig, formRef: ref, children: _jsx(RootContent, { asChild: asChild, ref: ref, ...otherProps, children: children }) }));
 });
 /**
  * Internal component to handle the Root content with service access.
@@ -492,16 +513,17 @@ export const Fields = React.forwardRef((props, ref) => {
     const [formErrors, setFormErrors] = useState([]);
     const currentLocale = i18n.getLocale();
     const currentLanguage = i18n.getLanguage();
+    const formRef = useFormRef();
     const handleFormValidate = useCallback((errors) => {
         setFormErrors(errors);
     }, []);
     return (_jsx(CoreFields, { children: ({ form, formValues, submitForm, handleForm, addressTemplates }) => {
             if (!form)
                 return null;
-            return (_jsx("div", { ref: ref, children: _jsx(FormProvider, { currency: 'USD', locale: currentLanguage, regionalFormat: currentLocale, addressTemplates: addressTemplates, children: _jsx(UniqueFieldSuffixContextProvider, { parentId: form._id ?? '', children: _jsx(FieldsWithForm, { form: form, values: formValues, onChange: handleForm, errors: formErrors, onValidate: handleFormValidate, fields: props.fieldMap, submitForm: submitForm, rowGapClassname: props.rowGapClassname, columnGapClassname: props.columnGapClassname }) }) }) }));
+            return (_jsx("div", { ref: ref, children: _jsx(FormProvider, { currency: 'USD', locale: currentLanguage, regionalFormat: currentLocale, addressTemplates: addressTemplates, children: _jsx(UniqueFieldSuffixContextProvider, { parentId: form._id ?? '', children: _jsx(FieldsWithForm, { form: form, values: formValues, onChange: handleForm, errors: formErrors, onValidate: handleFormValidate, fields: props.fieldMap, submitForm: submitForm, rowGapClassname: props.rowGapClassname, columnGapClassname: props.columnGapClassname, formRef: formRef }) }) }) }));
         } }));
 });
-const FieldsWithForm = ({ form, submitForm, values, onChange, errors, onValidate, fields: fieldMap, rowGapClassname, columnGapClassname, }) => {
+const FieldsWithForm = ({ form, submitForm, values, onChange, errors, onValidate, fields: fieldMap, rowGapClassname, columnGapClassname, formRef, }) => {
     const coreUploadFile = async ({ file, formId, }) => {
         const uploadUrl = await getUploadUrl(formId, file);
         if (uploadUrl === undefined) {
@@ -524,6 +546,7 @@ const FieldsWithForm = ({ form, submitForm, values, onChange, errors, onValidate
         submitForm,
         uploadFile: coreUploadFile,
         fieldMap,
+        forwardedRef: formRef,
     });
     if (!formData)
         return null;

package/dist/react/core/Form.d.ts

@@ -1,12 +1,19 @@
+import React from 'react';
 import { forms } from '@wix/forms';
 import { FormServiceConfig } from '../../services/form-service.js';
 import { FormValues } from '../types.js';
+/**
+ * Hook to access the form ref from context
+ */
+export declare function useFormRef(): React.Ref<any> | undefined;
 /**
  * Props for Root headless component
  */
 export interface RootProps {
     children: React.ReactNode;
     formServiceConfig: FormServiceConfig;
+    /** Optional ref to access form methods imperatively */
+    formRef?: React.Ref<any>;
 }
 /**
  * Root component that provides the Form service context to its children.
@@ -16,7 +23,9 @@ export interface RootProps {
  * @component
  * @param {RootProps} props - Component props
  * @param {React.ReactNode} props.children - Child components that will have access to form context
- * @param {FormServiceConfig} props.formServiceConfig - Configuration object containing form data
+ * @param {FormServiceConfig} props.formServiceConfig - Configuration object containing form data. Supports two patterns:
+ *   - Pre-loaded form data: `{ form: Form, onSubmit?: Function, addressTemplates?: any[] }`
+ *   - Lazy loading: `{ formId: string, namespace?: string, additionalMetadata?: Record<string, string | string[]>, onSubmit?: Function }`
  * @example
  * ```tsx
  * import { Form } from '@wix/headless-forms/react';
@@ -51,9 +60,30 @@ export interface RootProps {
  *     </Form.Root>
  *   );
  * }
+ *
+ * // Pattern 3: With namespace and additional metadata (for bookings, etc.)
+ * function BookingFormPage({ formId }) {
+ *   return (
+ *     <Form.Root
+ *       formServiceConfig={{
+ *         formId,
+ *         namespace: 'wix.bookings.form',
+ *         additionalMetadata: { serviceId: ['service-123'] },
+ *       }}
+ *     >
+ *       <Form.Loading>
+ *         {({ isLoading }) => isLoading ? <div>Loading form...</div> : null}
+ *       </Form.Loading>
+ *       <Form.LoadingError>
+ *         {({ error, hasError }) => hasError ? <div>{error}</div> : null}
+ *       </Form.LoadingError>
+ *       <Form.Fields fieldMap={FIELD_MAP} />
+ *     </Form.Root>
+ *   );
+ * }
  * ```
  */
-export declare function Root({ formServiceConfig, children, }: RootProps): React.ReactNode;
+export declare function Root({ formServiceConfig, formRef, children, }: RootProps): React.ReactNode;
 /**
  * Props for FormLoading headless component
  */
@@ -91,7 +121,7 @@ export interface FormLoadingRenderProps {
  * }
  * ```
  */
-export declare function Loading(props: FormLoadingProps): import("react").ReactNode;
+export declare function Loading(props: FormLoadingProps): React.ReactNode;
 /**
  * Props for FormError headless component
  */
@@ -133,7 +163,7 @@ export interface FormErrorRenderProps {
  * }
  * ```
  */
-export declare function LoadingError(props: FormErrorProps): import("react").ReactNode;
+export declare function LoadingError(props: FormErrorProps): React.ReactNode;
 /**
  * Props for Form Submit Error headless component
  */
@@ -175,7 +205,7 @@ export interface FormSubmitErrorRenderProps {
  * }
  * ```
  */
-export declare function Error(props: FormSubmitErrorProps): import("react").ReactNode;
+export declare function Error(props: FormSubmitErrorProps): React.ReactNode;
 /**
  * Props for Form Submitted headless component
  */
@@ -218,7 +248,7 @@ export interface FormSubmittedRenderProps {
  * }
  * ```
  */
-export declare function Submitted(props: FormSubmittedProps): import("react").ReactNode;
+export declare function Submitted(props: FormSubmittedProps): React.ReactNode;
 /**
  * Render props for Fields component
  */
@@ -269,7 +299,7 @@ export interface FieldsProps {
  * }
  * ```
  */
-export declare function Fields(props: FieldsProps): import("react").ReactNode;
+export declare function Fields(props: FieldsProps): React.ReactNode;
 /**
  * Form view interface containing field definitions
  */
@@ -342,4 +372,4 @@ export interface FieldProps {
  * }
  * ```
  */
-export declare function Field(props: FieldProps): import("react").ReactNode;
+export declare function Field(props: FieldProps): React.ReactNode;

package/dist/react/core/Form.js

@@ -1,9 +1,20 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import React from 'react';
 import { useService, WixServices } from '@wix/services-manager-react';
 import { createServicesMap } from '@wix/services-manager';
 import { FormServiceDefinition, FormService, } from '../../services/form-service.js';
 import { calculateGridStyles } from '../utils.js';
 const DEFAULT_SUCCESS_MESSAGE = 'Your form has been submitted successfully.';
+/**
+ * Context for passing form ref from Root to Fields
+ */
+const FormRefContext = React.createContext(undefined);
+/**
+ * Hook to access the form ref from context
+ */
+export function useFormRef() {
+    return React.useContext(FormRefContext);
+}
 /**
  * Root component that provides the Form service context to its children.
  * This component sets up the necessary services for rendering and managing form data.
@@ -12,7 +23,9 @@ const DEFAULT_SUCCESS_MESSAGE = 'Your form has been submitted successfully.';
  * @component
  * @param {RootProps} props - Component props
  * @param {React.ReactNode} props.children - Child components that will have access to form context
- * @param {FormServiceConfig} props.formServiceConfig - Configuration object containing form data
+ * @param {FormServiceConfig} props.formServiceConfig - Configuration object containing form data. Supports two patterns:
+ *   - Pre-loaded form data: `{ form: Form, onSubmit?: Function, addressTemplates?: any[] }`
+ *   - Lazy loading: `{ formId: string, namespace?: string, additionalMetadata?: Record<string, string | string[]>, onSubmit?: Function }`
  * @example
  * ```tsx
  * import { Form } from '@wix/headless-forms/react';
@@ -47,10 +60,31 @@ const DEFAULT_SUCCESS_MESSAGE = 'Your form has been submitted successfully.';
  *     </Form.Root>
  *   );
  * }
+ *
+ * // Pattern 3: With namespace and additional metadata (for bookings, etc.)
+ * function BookingFormPage({ formId }) {
+ *   return (
+ *     <Form.Root
+ *       formServiceConfig={{
+ *         formId,
+ *         namespace: 'wix.bookings.form',
+ *         additionalMetadata: { serviceId: ['service-123'] },
+ *       }}
+ *     >
+ *       <Form.Loading>
+ *         {({ isLoading }) => isLoading ? <div>Loading form...</div> : null}
+ *       </Form.Loading>
+ *       <Form.LoadingError>
+ *         {({ error, hasError }) => hasError ? <div>{error}</div> : null}
+ *       </Form.LoadingError>
+ *       <Form.Fields fieldMap={FIELD_MAP} />
+ *     </Form.Root>
+ *   );
+ * }
  * ```
  */
-export function Root({ formServiceConfig, children, }) {
-    return (_jsx(WixServices, { servicesMap: createServicesMap().addService(FormServiceDefinition, FormService, formServiceConfig), children: children }));
+export function Root({ formServiceConfig, formRef, children, }) {
+    return (_jsx(WixServices, { servicesMap: createServicesMap().addService(FormServiceDefinition, FormService, formServiceConfig), children: _jsx(FormRefContext.Provider, { value: formRef, children: children }) }));
 }
 /**
  * Headless component for form loading state access

package/dist/react/types.d.ts

@@ -1,5 +1,5 @@
-import { type CheckboxGroupProps, type CheckboxProps, type PhoneInputProps, type DateInputProps, type DatePickerProps, type DateTimeInputProps, type DropdownProps, type FileUploadProps, type MultilineAddressProps, type NumberInputProps, type RadioGroupProps, type RatingInputProps, type RichTextProps, type SignatureProps, type SubmitButtonProps, type TagsProps, type TextAreaProps, type TextInputProps, type TimeInputProps, type ProductListProps, type FixedPaymentProps, type PaymentInputProps, type DonationProps, type AppointmentProps, type ImageChoiceProps } from '@wix/form-public';
-export type { CheckboxGroupProps, CheckboxProps, PhoneInputProps, DateInputProps, DatePickerProps, DateTimeInputProps, DropdownProps, FileUploadProps, MultilineAddressProps, NumberInputProps, RadioGroupProps, RatingInputProps, RichTextProps, SignatureProps, SubmitButtonProps, TagsProps, TextAreaProps, TextInputProps, TimeInputProps, ProductListProps, FixedPaymentProps, PaymentInputProps, DonationProps, AppointmentProps, ImageChoiceProps, };
+import { type CheckboxGroupProps, type CheckboxProps, type PhoneInputProps, type DateInputProps, type DatePickerProps, type DateTimeInputProps, type DropdownProps, type FileUploadProps, type MultilineAddressProps, type NumberInputProps, type RadioGroupProps, type RatingInputProps, type RichTextProps, type SignatureProps, type SubmitButtonProps, type TagsProps, type TextAreaProps, type TextInputProps, type TimeInputProps, type ProductListProps, type FixedPaymentProps, type PaymentInputProps, type DonationProps, type AppointmentProps, type ImageChoiceProps, type UseFormProps, type LoginBarProps } from '@wix/form-public';
+export type { CheckboxGroupProps, CheckboxProps, PhoneInputProps, DateInputProps, DatePickerProps, DateTimeInputProps, DropdownProps, FileUploadProps, MultilineAddressProps, NumberInputProps, RadioGroupProps, RatingInputProps, RichTextProps, SignatureProps, SubmitButtonProps, TagsProps, TextAreaProps, TextInputProps, TimeInputProps, ProductListProps, FixedPaymentProps, PaymentInputProps, DonationProps, AppointmentProps, ImageChoiceProps, UseFormProps, LoginBarProps, };
 export type FormValues = Record<string, any>;
 export interface UploadFileParams {
     file: File;

package/dist/services/form-service.js

@@ -1,8 +1,8 @@
-import { submissions } from '@wix/forms';
+import { forms, submissions } from '@wix/forms';
 import { defineService, implementService } from '@wix/services-definitions';
 import { SignalsServiceDefinition, } from '@wix/services-definitions/core-services/signals';
-import { httpClient } from '@wix/essentials';
 import { fetchAddressForms, hasMultilineAddressField, } from './utils/address-forms.js';
+import { Fieldset } from '@wix/auto_sdk_forms_forms';
 /**
  * Service definition for the Form service.
  * This defines the contract that the FormService must implement.
@@ -147,41 +147,18 @@ export const FormService = implementService.withConfig()(FormServiceDefinition,
         handleForm,
     };
 });
-function buildFormFetchQueryParams({ id, namespace, additionalMetadata, }) {
-    const params = new URLSearchParams();
-    params.append('formId', id);
-    if (namespace) {
-        params.append('namespace', namespace);
-    }
-    if (additionalMetadata) {
-        Object.entries(additionalMetadata).forEach(([key, value]) => {
-            if (Array.isArray(value)) {
-                value.forEach((v) => params.append(key, v));
-            }
-            else {
-                params.append(key, value);
-            }
-        });
-    }
-    return params;
-}
-async function fetchForm({ id, namespace, additionalMetadata, }) {
+async function fetchForm({ id, namespace = 'wix.form_app.form', additionalMetadata, }) {
     try {
-        const params = buildFormFetchQueryParams({
-            id,
-            namespace,
+        const response = await forms.listForms(namespace, {
             additionalMetadata,
+            formIds: [id],
+            fieldsets: [Fieldset.NESTED_FORMS],
         });
-        const url = `https://www.wixapis.com/form-schema-service/v4/forms/${id}?${params.toString()}`;
-        const response = await httpClient.fetchWithAuth(url);
-        if (!response.ok) {
-            throw new Error(`Failed to fetch form: ${response.status} ${response.statusText}`);
-        }
-        const data = await response.json();
-        if (data && data.form) {
-            return data.form;
+        const form = response.forms?.[0];
+        if (!form) {
+            throw new Error('Form not found');
         }
-        throw new Error('Invalid response format from Forms API');
+        return form;
     }
     catch (err) {
         console.error('Failed to load form:', id, err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/headless-forms",
-  "version": "0.0.22",
+  "version": "0.0.23",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -42,7 +42,7 @@
     "vitest": "^3.1.4"
   },
   "dependencies": {
-    "@wix/form-public": "^0.103.0",
+    "@wix/form-public": "^0.104.0",
     "@wix/forms": "^1.0.373",
     "@wix/headless-utils": "0.0.8",
     "@wix/services-definitions": "^0.1.4",
@@ -59,5 +59,5 @@
       "groupId": "com.wixpress.headless-components"
     }
   },
-  "falconPackageHash": "eac62dbea375dc890ae3bd0b5a84df1aece684a51aef9d27cc731690"
+  "falconPackageHash": "6d90b5a274c89f69fb6007bfac926468be779780b40000231b716ec3"
 }