@wix/headless-forms 0.0.0

package/dist/react/Form.js

@@ -0,0 +1,740 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import React, { useState, useCallback } from 'react';
+import { AsChildSlot } from '@wix/headless-utils/react';
+import { useForm, FormProvider, } from '@wix/form-public';
+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 { FieldContext, useFieldContext, } from './context/FieldContext.js';
+import { FieldLayoutProvider, useFieldLayout, } from './context/FieldLayoutContext.js';
+var TestIds;
+(function (TestIds) {
+    TestIds["formRoot"] = "form-root";
+    TestIds["form"] = "form";
+    TestIds["formLoading"] = "form-loading";
+    TestIds["formLoadingError"] = "form-loading-error";
+    TestIds["formError"] = "form-error";
+    TestIds["formSubmitted"] = "form-submitted";
+    TestIds["fieldRoot"] = "field-root";
+    TestIds["fieldLabel"] = "field-label";
+    TestIds["fieldInputWrapper"] = "field-input-wrapper";
+    TestIds["fieldInput"] = "field-input";
+    TestIds["fieldError"] = "field-error";
+})(TestIds || (TestIds = {}));
+/**
+ * Root component that provides all necessary service contexts for a complete form experience.
+ * This component sets up the Form service and provides context to child components.
+ * Must be used as the top-level component for all form functionality.
+ *
+ * @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 {boolean} [props.asChild] - Whether to render as a child component
+ * @param {string} [props.className] - CSS classes to apply to the root element
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ * import { loadFormServiceConfig } from '@wix/headless-forms/services';
+ *
+ * const FIELD_MAP = {
+ *   TEXT_INPUT: TextInput,
+ *   TEXT_AREA: TextArea,
+ *   CHECKBOX: Checkbox,
+ *   // ... other field components
+ * };
+ *
+ * // Pattern 1: Pre-loaded form data (SSR/SSG)
+ * function FormPage({ 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 DynamicFormPage({ 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 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 }) }));
+});
+/**
+ * Internal component to handle the Root content with service access.
+ * This component wraps the children with the necessary div container and applies styling.
+ *
+ * @internal
+ * @param {RootContentProps} props - Component props
+ * @param {React.ReactNode} props.children - Child components to render
+ * @param {string} [props.className] - CSS classes to apply to the container
+ * @param {boolean} [props.asChild] - Whether to render as a child component
+ * @returns {JSX.Element} The wrapped content
+ */
+const RootContent = React.forwardRef((props, ref) => {
+    const { asChild, children, className, ...otherProps } = props;
+    return (_jsx(AsChildSlot, { ref: ref, asChild: asChild, className: className, "data-testid": TestIds.formRoot, customElement: children, customElementProps: {}, ...otherProps, children: _jsx("div", { children: children }) }));
+});
+/**
+ * Component that renders content during loading state.
+ * Only displays its children when the form is currently loading.
+ *
+ * @component
+ * @param {LoadingProps} props - The component props
+ * @param {boolean} [props.asChild] - Whether to render as a child component
+ * @param {React.ReactNode} [props.children] - Content to display during loading state
+ * @param {string} [props.className] - CSS classes to apply to the default element
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * // Default usage with className
+ * function FormLoading() {
+ *   return (
+ *     <Form.Loading className="flex justify-center p-4" />
+ *   );
+ * }
+ *
+ * // Custom content
+ * function CustomFormLoading() {
+ *   return (
+ *     <Form.Loading>
+ *       <div className="flex justify-center items-center p-4">
+ *         <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-primary"></div>
+ *         <span className="ml-2 text-foreground font-paragraph">Loading form...</span>
+ *       </div>
+ *     </Form.Loading>
+ *   );
+ * }
+ *
+ * // With asChild for custom components
+ * function CustomFormLoadingAsChild() {
+ *   return (
+ *     <Form.Loading asChild>
+ *       <div className="custom-loading-container">
+ *         <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-primary"></div>
+ *         <span className="ml-2 text-foreground font-paragraph">Loading form...</span>
+ *       </div>
+ *     </Form.Loading>
+ *   );
+ * }
+ * ```
+ */
+export const Loading = React.forwardRef((props, ref) => {
+    const { asChild, children, className, ...otherProps } = props;
+    return (_jsx(CoreLoading, { children: ({ isLoading }) => {
+            if (!isLoading)
+                return null;
+            return (_jsx(AsChildSlot, { "data-testid": TestIds.formLoading, ref: ref, asChild: asChild, className: className, customElement: children, content: "Loading form...", ...otherProps, children: _jsx("div", { children: "Loading form..." }) }));
+        } }));
+});
+/**
+ * Component that renders content when there's an error loading the form.
+ * Only displays its children when an error has occurred.
+ *
+ * @component
+ * @param {LoadingErrorProps} props - The component props
+ * @param {boolean} [props.asChild] - Whether to render as a child component
+ * @param {React.ReactNode} [props.children] - Content to display during error state
+ * @param {string} [props.className] - CSS classes to apply to the default element
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * // Default usage with className
+ * function FormLoadingError() {
+ *   return (
+ *     <Form.LoadingError className="text-destructive px-4 py-3 rounded mb-4" />
+ *   );
+ * }
+ *
+ * // Custom content
+ * function CustomLoadingError() {
+ *   return (
+ *     <Form.LoadingError>
+ *       <div className="bg-destructive/10 border border-destructive text-destructive px-4 py-3 rounded mb-4">
+ *         <h3 className="font-heading text-lg">Error loading form</h3>
+ *         <p className="font-paragraph">Something went wrong. Please try again.</p>
+ *       </div>
+ *     </Form.LoadingError>
+ *   );
+ * }
+ *
+ * // With asChild for custom components
+ * function CustomLoadingErrorAsChild() {
+ *   return (
+ *     <Form.LoadingError asChild>
+ *       {React.forwardRef<HTMLDivElement, { error: string | null; hasError: boolean }>(
+ *         ({ error }, ref) => (
+ *           <div ref={ref} className="custom-error-container">
+ *             <h3 className="font-heading">Error Loading Form</h3>
+ *             <p className="font-paragraph">{error}</p>
+ *           </div>
+ *         )
+ *       )}
+ *     </Form.LoadingError>
+ *   );
+ * }
+ * ```
+ */
+export const LoadingError = React.forwardRef((props, ref) => {
+    const { asChild, children, className, ...otherProps } = props;
+    return (_jsx(CoreLoadingError, { children: ({ error, hasError }) => {
+            if (!hasError)
+                return null;
+            const errorData = { error, hasError };
+            return (_jsx(AsChildSlot, { ref: ref, asChild: asChild, className: className, "data-testid": TestIds.formLoadingError, customElement: children, customElementProps: errorData, content: error, ...otherProps, children: _jsx("div", { children: error }) }));
+        } }));
+});
+/**
+ * Component that renders content when there's an error during form submission.
+ * Only displays its children when a submission error has occurred.
+ *
+ * @component
+ * @param {ErrorProps} props - The component props
+ * @param {boolean} [props.asChild] - Whether to render as a child component
+ * @param {React.ReactNode} [props.children] - Content to display during submit error state
+ * @param {string} [props.className] - CSS classes to apply to the default element
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * // Default usage with className
+ * function FormError() {
+ *   return <Form.Error className="text-destructive p-4 rounded-lg mb-4" />;
+ * }
+ *
+ * // Custom content
+ * function CustomFormError() {
+ *   return (
+ *     <Form.Error>
+ *       <div className="bg-destructive/10 border border-destructive text-destructive p-4 rounded-lg mb-4">
+ *         <h3 className="font-heading text-lg">Submission Failed</h3>
+ *         <p className="font-paragraph">Please check your input and try again.</p>
+ *       </div>
+ *     </Form.Error>
+ *   );
+ * }
+ *
+ * // With asChild for custom components
+ * function CustomFormErrorAsChild() {
+ *   return (
+ *     <Form.Error asChild>
+ *       {React.forwardRef<HTMLDivElement, { error: string | null; hasError: boolean }>(
+ *         ({ error }, ref) => (
+ *           <div ref={ref} className="custom-error-container">
+ *             <h3 className="font-heading">Submission Failed</h3>
+ *             <p className="font-paragraph">{error}</p>
+ *           </div>
+ *         )
+ *       )}
+ *     </Form.Error>
+ *   );
+ * }
+ * ```
+ */
+export const Error = React.forwardRef((props, ref) => {
+    const { asChild, children, className, ...otherProps } = props;
+    return (_jsx(CoreError, { children: ({ error, hasError }) => {
+            if (!hasError)
+                return null;
+            const errorData = { error, hasError };
+            return (_jsx(AsChildSlot, { ref: ref, asChild: asChild, className: className, "data-testid": TestIds.formError, customElement: children, customElementProps: errorData, content: error, ...otherProps, children: _jsx("div", { className: "text-destructive text-sm sm:text-base", children: error }) }));
+        } }));
+});
+/**
+ * Component that renders content after successful form submission.
+ * Only displays its children when the form has been successfully submitted.
+ *
+ * @component
+ * @param {SubmittedProps} props - The component props
+ * @param {boolean} [props.asChild] - Whether to render as a child component
+ * @param {React.ReactNode} [props.children] - Content to display after successful submission
+ * @param {string} [props.className] - CSS classes to apply to the default element
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * // Default usage with className
+ * function FormSubmitted() {
+ *   return <Form.Submitted className="text-green-500 p-4 rounded-lg mb-4" />;
+ * }
+ *
+ * // Custom content
+ * function CustomFormSubmitted() {
+ *   return (
+ *     <Form.Submitted>
+ *       <div className="bg-green-50 border border-green-200 text-green-800 p-6 rounded-lg mb-4">
+ *         <h2 className="font-heading text-xl mb-2">Thank You!</h2>
+ *         <p className="font-paragraph">Your form has been submitted successfully.</p>
+ *       </div>
+ *     </Form.Submitted>
+ *   );
+ * }
+ *
+ * // With asChild for custom components
+ * function CustomFormSubmittedAsChild() {
+ *   return (
+ *     <Form.Submitted asChild>
+ *       {React.forwardRef<HTMLDivElement, { isSubmitted: boolean; message: string }>(
+ *         ({ message }, ref) => (
+ *           <div ref={ref} className="custom-success-container">
+ *             <h2 className="font-heading">Thank You!</h2>
+ *             <p className="font-paragraph">{message}</p>
+ *           </div>
+ *         )
+ *       )}
+ *     </Form.Submitted>
+ *   );
+ * }
+ * ```
+ */
+export const Submitted = React.forwardRef((props, ref) => {
+    const { asChild, children, className, ...otherProps } = props;
+    return (_jsx(CoreSubmitted, { children: ({ isSubmitted, message }) => {
+            if (!isSubmitted)
+                return null;
+            const submittedData = { isSubmitted, message };
+            return (_jsx(AsChildSlot, { ref: ref, asChild: asChild, className: className, "data-testid": TestIds.formSubmitted, customElement: children, customElementProps: submittedData, content: message, ...otherProps, children: _jsx("div", { className: "text-green-500 text-sm sm:text-base", children: message }) }));
+        } }));
+});
+/**
+ * Fields component for rendering a form with custom field renderers.
+ * This component handles the rendering of form fields based on the provided fieldMap.
+ * Must be used within Form.Root to access form context.
+ *
+ * @component
+ * @param {FieldsProps} props - Component props
+ * @param {FieldMap} props.fieldMap - A mapping of field types to their corresponding React components
+ * @param {string} props.rowGapClassname - CSS class name for gap between rows
+ * @param {string} props.columnGapClassname - CSS class name for gap between columns
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ * import { TextInput, TextArea, Checkbox } from './field-components';
+ *
+ * const FIELD_MAP = {
+ *   TEXT_INPUT: TextInput,
+ *   TEXT_AREA: TextArea,
+ *   CHECKBOX: Checkbox,
+ *   NUMBER_INPUT: NumberInput,
+ *   // ... remaining field components
+ * };
+ *
+ * function ContactForm({ 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}
+ *         rowGapClassname="gap-y-4"
+ *         columnGapClassname="gap-x-2"
+ *       />
+ *     </Form.Root>
+ *   );
+ * }
+ * ```
+ */
+/**
+ * Fields component for rendering a form with custom field renderers.
+ * It maps each field type from the form configuration to its corresponding React component
+ * and renders them in the order and layout defined by the form structure.
+ *
+ * The component automatically handles:
+ * - Field validation and error display
+ * - Form state management
+ * - Field value updates
+ * - Grid layout with configurable row and column gaps
+ *
+ * Must be used within Form.Root to access form context.
+ *
+ * @component
+ * @param {FieldsProps} props - The component props
+ * @param {FieldMap} props.fieldMap - A mapping of field types to their corresponding React components. Each key represents a field type (e.g., 'TEXT_INPUT', 'CHECKBOX') and the value is the React component that should render that field type.
+ * @param {string} props.rowGapClassname - CSS class name for gap between form rows
+ * @param {string} props.columnGapClassname - CSS class name for gap between form columns
+ *
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ * import { loadFormServiceConfig } from '@wix/headless-forms/services';
+ * import {
+ *   TextInput,
+ *   TextArea,
+ *   PhoneInput,
+ *   MultilineAddress,
+ *   DateInput,
+ *   DatePicker,
+ *   DateTimeInput,
+ *   FileUpload,
+ *   NumberInput,
+ *   Checkbox,
+ *   Signature,
+ *   RatingInput,
+ *   RadioGroup,
+ *   CheckboxGroup,
+ *   Dropdown,
+ *   Tags,
+ *   TimeInput,
+ *   RichText,
+ *   SubmitButton,
+ *   ProductList,
+ *   FixedPayment,
+ *   PaymentInput,
+ *   Donation,
+ *   Appointment,
+ *   ImageChoice
+ * } from './components';
+ *
+ * // Define your field mapping - this tells the Fields component which React component to use for each field type
+ * const FIELD_MAP = {
+ *   TEXT_INPUT: TextInput,
+ *   TEXT_AREA: TextArea,
+ *   PHONE_INPUT: PhoneInput,
+ *   MULTILINE_ADDRESS: MultilineAddress,
+ *   DATE_INPUT: DateInput,
+ *   DATE_PICKER: DatePicker,
+ *   DATE_TIME_INPUT: DateTimeInput,
+ *   FILE_UPLOAD: FileUpload,
+ *   NUMBER_INPUT: NumberInput,
+ *   CHECKBOX: Checkbox,
+ *   SIGNATURE: Signature,
+ *   RATING_INPUT: RatingInput,
+ *   RADIO_GROUP: RadioGroup,
+ *   CHECKBOX_GROUP: CheckboxGroup,
+ *   DROPDOWN: Dropdown,
+ *   TAGS: Tags,
+ *   TIME_INPUT: TimeInput,
+ *   TEXT: RichText,
+ *   SUBMIT_BUTTON: SubmitButton,
+ *   PRODUCT_LIST: ProductList,
+ *   FIXED_PAYMENT: FixedPayment,
+ *   PAYMENT_INPUT: PaymentInput,
+ *   DONATION: Donation,
+ *   APPOINTMENT: Appointment,
+ *   IMAGE_CHOICE: ImageChoice,
+ * };
+ *
+ * function ContactForm({ 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}
+ *         rowGapClassname="gap-y-4"
+ *         columnGapClassname="gap-x-2"
+ *       />
+ *       <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>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Creating custom field components - ALL field components MUST use Form.Field
+ * // This example shows the REQUIRED structure for a TEXT_INPUT component
+ * import { Form, type TextInputProps } from '@wix/headless-forms/react';
+ *
+ * const TextInput = (props: TextInputProps) => {
+ *   const { id, value, onChange, label, error, required, ...inputProps } = props;
+ *
+ *   // Form.Field provides automatic grid layout positioning
+ *   return (
+ *     <Form.Field id={id}>
+ *       <Form.Field.Label>
+ *         <label className="text-foreground font-paragraph">
+ *           {label}
+ *           {required && <span className="text-destructive ml-1">*</span>}
+ *         </label>
+ *       </Form.Field.Label>
+ *       <Form.Field.Input
+ *         description={error && <span className="text-destructive text-sm">{error}</span>}
+ *       >
+ *         <input
+ *           type="text"
+ *           value={value || ''}
+ *           onChange={(e) => onChange(e.target.value)}
+ *           className="bg-background border-foreground text-foreground"
+ *           aria-invalid={!!error}
+ *           {...inputProps}
+ *         />
+ *       </Form.Field.Input>
+ *     </Form.Field>
+ *   );
+ * };
+ *
+ * const FIELD_MAP = {
+ *   TEXT_INPUT: TextInput,
+ *   // ... all other field components must also use Form.Field
+ * };
+ * ```
+ */
+export const Fields = React.forwardRef((props, ref) => {
+    const [formValues, setFormValues] = useState({});
+    const [formErrors, setFormErrors] = useState([]);
+    const handleFormChange = useCallback((values) => {
+        setFormValues(values);
+    }, []);
+    const handleFormValidate = useCallback((errors) => {
+        setFormErrors(errors);
+    }, []);
+    return (_jsx(CoreFields, { children: ({ form, submitForm }) => {
+            if (!form)
+                return null;
+            return (_jsx("div", { ref: ref, children: _jsx(FormProvider, { currency: 'USD', locale: 'en', children: _jsx(FieldsWithForm, { form: form, values: formValues, onChange: handleFormChange, errors: formErrors, onValidate: handleFormValidate, fields: props.fieldMap, submitForm: () => submitForm(formValues), rowGapClassname: props.rowGapClassname, columnGapClassname: props.columnGapClassname }) }) }));
+        } }));
+});
+const FieldsWithForm = ({ form, submitForm, values, onChange, errors, onValidate, fields: fieldMap, rowGapClassname, columnGapClassname, }) => {
+    const formData = useForm({
+        form,
+        values,
+        errors,
+        onChange,
+        onValidate,
+        submitForm,
+        fieldMap,
+    });
+    if (!formData)
+        return null;
+    const { columnCount, fieldElements, fieldsLayout } = formData;
+    return (
+    // TODO: use readOnly, isDisabled
+    // TODO: step title a11y support
+    // TODO: mobile support?
+    _jsx(FieldLayoutProvider, { value: fieldsLayout, children: _jsx("form", { onSubmit: (e) => e.preventDefault(), children: _jsx("fieldset", { style: { display: 'flex', flexDirection: 'column' }, className: rowGapClassname, children: fieldElements.map((rowElements, index) => {
+                    return (_jsx("div", { style: {
+                            display: 'grid',
+                            width: '100%',
+                            gridTemplateColumns: `repeat(${columnCount}, 1fr)`,
+                            gridAutoRows: 'minmax(min-content, max-content)',
+                        }, className: columnGapClassname, children: rowElements }, index));
+                }) }) }) }));
+};
+/**
+ * Container component for a form field with grid layout support.
+ * Provides context to Field.Label, Field.InputWrapper, Field.Input, and Field.Error child components.
+ * Based on the default-field-layout functionality.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * function FormFields() {
+ *   return (
+ *     <Form.Field id="username">
+ *       <Form.Field.Label>
+ *         <label className="text-foreground font-paragraph">Username</label>
+ *       </Form.Field.Label>
+ *       <Form.Field.InputWrapper>
+ *         <Form.Field.Input description={<span className="text-secondary-foreground">Required</span>}>
+ *           <input className="bg-background border-foreground text-foreground" />
+ *         </Form.Field.Input>
+ *         <Form.Field.Error>
+ *           <span className="text-destructive text-sm font-paragraph">Username is required</span>
+ *         </Form.Field.Error>
+ *       </Form.Field.InputWrapper>
+ *     </Form.Field>
+ *   );
+ * }
+ * ```
+ */
+const FieldRoot = React.forwardRef((props, ref) => {
+    const { id, children, asChild, className, ...otherProps } = props;
+    const layout = useFieldLayout(id);
+    if (!layout) {
+        return null;
+    }
+    return (_jsx(CoreField, { id: id, layout: layout, children: (fieldData) => {
+            const contextValue = {
+                id,
+                layout: fieldData.layout,
+                gridStyles: fieldData.gridStyles,
+            };
+            return (_jsx(FieldContext.Provider, { value: contextValue, children: _jsx(AsChildSlot, { ref: ref, asChild: asChild, className: className, "data-testid": TestIds.fieldRoot, customElement: children, customElementProps: {}, ...otherProps, children: children }) }));
+        } }));
+});
+FieldRoot.displayName = 'Form.Field';
+/**
+ * Label component for a form field with automatic grid positioning.
+ * Must be used within a Form.Field component.
+ * Renders in the label row of the field's grid layout.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * <Form.Field id="email">
+ *   <Form.Field.Label>
+ *     <label className="text-foreground font-paragraph">
+ *       Email Address
+ *       <Form.Field.Label.Required required={true} />
+ *     </label>
+ *   </Form.Field.Label>
+ *   <Form.Field.InputWrapper>
+ *     <Form.Field.Input>
+ *       <input type="email" className="bg-background border-foreground text-foreground" />
+ *     </Form.Field.Input>
+ *   </Form.Field.InputWrapper>
+ * </Form.Field>
+ * ```
+ */
+const FieldLabelRoot = React.forwardRef((props, ref) => {
+    const { children, asChild, className, ...otherProps } = props;
+    const { gridStyles } = useFieldContext();
+    return (_jsx(AsChildSlot, { ref: ref, asChild: asChild, className: className, style: gridStyles.label, "data-testid": TestIds.fieldLabel, customElement: children, customElementProps: {}, ...otherProps, children: _jsx("div", { children: children }) }));
+});
+FieldLabelRoot.displayName = 'Form.Field.Label';
+/**
+ * Required indicator component for form field labels.
+ * Must be used within a Form.Field.Label component.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * // Basic usage with required prop
+ * <Form.Field.Label>
+ *   <label className="text-foreground font-paragraph">
+ *     Email Address
+ *     <Form.Field.Label.Required  />
+ *   </label>
+ * </Form.Field.Label>
+ *
+ * // Custom styling
+ * <Form.Field.Label>
+ *   <label className="text-foreground font-paragraph">
+ *     Username
+ *     <Form.Field.Label.Required required={true} className="text-destructive ml-2" />
+ *   </label>
+ * </Form.Field.Label>
+ */
+export const FieldLabelRequired = React.forwardRef((props, ref) => {
+    const { required = false, children, asChild, className, ...otherProps } = props;
+    const requiredIndicator = 'asterisk';
+    // @ts-expect-error
+    if (!required || requiredIndicator === 'none')
+        return null;
+    return (_jsx(AsChildSlot, { ref: ref, asChild: asChild, className: className, customElement: children, ...otherProps, children: _jsx("span", { children: requiredIndicator === 'asterisk'
+                ? '*'
+                : requiredIndicator === 'text'
+                    ? '(Required)'
+                    : null }) }));
+});
+FieldLabelRequired.displayName = 'Form.Field.Label.Required';
+export const FieldLabel = FieldLabelRoot;
+FieldLabel.Required = FieldLabelRequired;
+/**
+ * InputWrapper component that wraps input and error elements with grid positioning.
+ * Must be used within a Form.Field component.
+ * This wrapper applies the grid positioning styles to contain both the input and error.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * <Form.Field id="email">
+ *   <Form.Field.Label>
+ *     <label className="text-foreground font-paragraph">Email Address</label>
+ *   </Form.Field.Label>
+ *   <Form.Field.InputWrapper>
+ *     <Form.Field.Input>
+ *       <input type="email" className="bg-background border-foreground text-foreground" />
+ *     </Form.Field.Input>
+ *     <Form.Field.Error>
+ *       <span className="text-destructive text-sm font-paragraph">Please enter a valid email</span>
+ *     </Form.Field.Error>
+ *   </Form.Field.InputWrapper>
+ * </Form.Field>
+ * ```
+ */
+export const FieldInputWrapper = React.forwardRef((props, ref) => {
+    const { children, asChild, className, ...otherProps } = props;
+    const { gridStyles } = useFieldContext();
+    return (_jsx(AsChildSlot, { ref: ref, asChild: asChild, className: className, style: gridStyles.input, "data-testid": TestIds.fieldInputWrapper, customElement: children, customElementProps: {}, ...otherProps, children: _jsx("div", { children: children }) }));
+});
+FieldInputWrapper.displayName = 'Form.Field.InputWrapper';
+/**
+ * Input component for a form field.
+ * Must be used within a Form.Field.InputWrapper component.
+ * Renders the actual input element without grid positioning.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * <Form.Field id="password">
+ *   <Form.Field.Label>
+ *     <label className="text-foreground font-paragraph">Password</label>
+ *   </Form.Field.Label>
+ *   <Form.Field.InputWrapper>
+ *     <Form.Field.Input description={<span className="text-secondary-foreground">Min 8 characters</span>}>
+ *       <input type="password" className="bg-background border-foreground text-foreground" />
+ *     </Form.Field.Input>
+ *   </Form.Field.InputWrapper>
+ * </Form.Field>
+ * ```
+ */
+export const FieldInput = React.forwardRef((props, ref) => {
+    const { children, description, asChild, className, ...otherProps } = props;
+    return (_jsx(AsChildSlot, { ref: ref, asChild: asChild, className: className, "data-testid": TestIds.fieldInput, customElement: children, customElementProps: {}, ...otherProps, children: _jsx("div", { children: children }) }));
+});
+FieldInput.displayName = 'Form.Field.Input';
+/**
+ * Error component for displaying field-level validation errors.
+ * Must be used within a Form.Field.InputWrapper component.
+ * Only renders when there is an error for the current field.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * <Form.Field id="email">
+ *   <Form.Field.Label>
+ *     <label className="text-foreground font-paragraph">Email Address</label>
+ *   </Form.Field.Label>
+ *   <Form.Field.InputWrapper>
+ *     <Form.Field.Input>
+ *       <input type="email" className="bg-background border-foreground text-foreground" />
+ *     </Form.Field.Input>
+ *     <Form.Field.Error path="email">
+ *       <span className="text-destructive text-sm font-paragraph">Please enter a valid email address</span>
+ *     </Form.Field.Error>
+ *   </Form.Field.InputWrapper>
+ * </Form.Field>
+ * ```
+ */
+export const FieldError = React.forwardRef((props, ref) => {
+    const { errorMessage, asChild, className, children, ...otherProps } = props;
+    if (!errorMessage && !children)
+        return null;
+    return (_jsx(AsChildSlot, { "data-testid": TestIds.fieldError, ref: ref, asChild: asChild, className: className, ...otherProps, children: children || errorMessage }));
+});
+FieldError.displayName = 'Form.Field.Error';
+export const Field = FieldRoot;
+Field.Label = FieldLabel;
+Field.InputWrapper = FieldInputWrapper;
+Field.Input = FieldInput;
+Field.Error = FieldError;