@wix/headless-forms 0.0.10 → 0.0.12

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

@@ -1,4 +1,5 @@
 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 FormServiceConfig } from '../services/form-service.js';
 /**
@@ -303,6 +304,9 @@ export declare const Submitted: React.ForwardRefExoticComponent<SubmittedProps &
 /**
  * Mapping of form field types to their corresponding React components.
  *
+ * ALL field components in this map MUST use Form.Field for proper
+ * grid layout positioning.
+ *
  * Each key represents a field type identifier that matches the field types defined
  * in the form configuration, and each value is a React component that will receive
  * the field's props and render the appropriate UI element.
@@ -401,6 +405,8 @@ export interface FieldMap {
  *
  * @interface FieldsProps
  * @property {FieldMap} fieldMap - A mapping of field types to their corresponding React components
+ * @property {string} rowGapClassname - CSS class name for gap between rows
+ * @property {string} columnGapClassname - CSS class name for gap between columns
  * @example
  * ```tsx
  * const FIELD_MAP = {
@@ -414,11 +420,13 @@ export interface FieldMap {
  *   // ... remaining field components
  * };
  *
- * <Form.Fields fieldMap={FIELD_MAP} />
+ * <Form.Fields fieldMap={FIELD_MAP} rowGapClassname="gap-y-4" columnGapClassname="gap-x-2" />
  * ```
  */
 interface FieldsProps {
     fieldMap: FieldMap;
+    rowGapClassname: string;
+    columnGapClassname: string;
 }
 /**
  * Fields component for rendering a form with custom field renderers.
@@ -428,6 +436,8 @@ interface FieldsProps {
  * @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';
@@ -446,7 +456,11 @@ interface FieldsProps {
  *     <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.Fields
+ *         fieldMap={FIELD_MAP}
+ *         rowGapClassname="gap-y-4"
+ *         columnGapClassname="gap-x-2"
+ *       />
  *     </Form.Root>
  *   );
  * }
@@ -461,12 +475,15 @@ interface FieldsProps {
  * - 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
@@ -534,7 +551,11 @@ interface FieldsProps {
  *     <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.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>
@@ -544,25 +565,221 @@ interface FieldsProps {
  *
  * @example
  * ```tsx
- * // Advanced usage with custom field components
- * const CustomTextField = ({ value, onChange, label, error, ...props }) => (
- *   <div className="form-field">
- *     <label className="text-foreground font-paragraph">{label}</label>
- *     <input
- *       value={value || ''}
- *       onChange={(e) => onChange(e.target.value)}
- *       className="bg-background border-foreground text-foreground"
- *       {...props}
- *     />
- *     {error && <span className="text-destructive">{error}</span>}
- *   </div>
- * );
+ * // 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: CustomTextField,
- *   // ... other field components
+ *   TEXT_INPUT: TextInput,
+ *   // ... all other field components must also use Form.Field
  * };
  * ```
  */
 export declare const Fields: React.ForwardRefExoticComponent<FieldsProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * Props for Field container component
+ */
+export interface FieldProps {
+    /** The unique identifier for this field */
+    id: string;
+    /** Child components (Field.Label, Field.Input, etc.) */
+    children: React.ReactNode;
+    /** Whether to render as a child component */
+    asChild?: boolean;
+    /** CSS classes to apply to the root element */
+    className?: string;
+}
+/**
+ * Field component with sub-components
+ */
+interface FieldComponent extends React.ForwardRefExoticComponent<FieldProps & React.RefAttributes<HTMLDivElement>> {
+    Label: typeof FieldLabel;
+    InputWrapper: typeof FieldInputWrapper;
+    Input: typeof FieldInput;
+    Error: typeof FieldError;
+}
+/**
+ * Props for Field.Label component
+ */
+export interface FieldLabelProps {
+    /** Label content to display */
+    children: React.ReactNode;
+    /** Whether to render as a child component */
+    asChild?: boolean;
+    /** CSS classes to apply to the label element */
+    className?: string;
+}
+/**
+ * Props for Field.InputWrapper component
+ */
+export interface FieldInputWrapperProps {
+    /** Child components (typically Field.Input and Field.Error) */
+    children: React.ReactNode;
+    /** Whether to render as a child component */
+    asChild?: boolean;
+    /** CSS classes to apply to the wrapper element */
+    className?: string;
+}
+/**
+ * Props for Field.Input component
+ */
+export interface FieldInputProps {
+    /** Input element to render */
+    children: React.ReactNode;
+    /** Whether to render as a child component */
+    asChild?: boolean;
+    /** CSS classes to apply to the input element */
+    className?: string;
+    /** Description text to display below the input */
+    description?: React.ReactNode;
+}
+/**
+ * Render props for Field.Error component
+ */
+export interface FieldErrorRenderProps {
+    /** The error type */
+    type: FormError['errorType'];
+    /** The error message */
+    message: string;
+}
+/**
+ * Props for Field.Error component
+ */
+export interface FieldErrorProps {
+    /** Whether to render as a child component */
+    asChild?: boolean;
+    /** CSS classes to apply to the error element */
+    className?: string;
+    /** The error message */
+    errorMessage?: string;
+    /** Child components to render */
+    children?: React.ReactNode;
+}
+/**
+ * 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</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>
+ * ```
+ */
+export declare const FieldLabel: React.ForwardRefExoticComponent<FieldLabelProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * 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 declare const FieldInputWrapper: React.ForwardRefExoticComponent<FieldInputWrapperProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * 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 declare const FieldInput: React.ForwardRefExoticComponent<FieldInputProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * 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 declare const FieldError: React.ForwardRefExoticComponent<FieldErrorProps & React.RefAttributes<HTMLDivElement>>;
+export declare const Field: FieldComponent;
 export {};

package/cjs/dist/react/Form.js

@@ -33,12 +33,14 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Fields = exports.Submitted = exports.Error = exports.LoadingError = exports.Loading = exports.Root = void 0;
+exports.Field = exports.FieldError = exports.FieldInput = exports.FieldInputWrapper = exports.FieldLabel = exports.Fields = exports.Submitted = exports.Error = exports.LoadingError = exports.Loading = exports.Root = void 0;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = __importStar(require("react"));
 const react_2 = require("@wix/headless-utils/react");
 const form_public_1 = require("@wix/form-public");
 const Form_js_1 = require("./core/Form.js");
+const FieldContext_js_1 = require("./context/FieldContext.js");
+const FieldLayoutContext_js_1 = require("./context/FieldLayoutContext.js");
 var TestIds;
 (function (TestIds) {
     TestIds["formRoot"] = "form-root";
@@ -47,6 +49,11 @@ var TestIds;
     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.
@@ -348,6 +355,8 @@ exports.Submitted = react_1.default.forwardRef((props, ref) => {
  * @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';
@@ -366,7 +375,11 @@ exports.Submitted = react_1.default.forwardRef((props, ref) => {
  *     <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.Fields
+ *         fieldMap={FIELD_MAP}
+ *         rowGapClassname="gap-y-4"
+ *         columnGapClassname="gap-x-2"
+ *       />
  *     </Form.Root>
  *   );
  * }
@@ -381,12 +394,15 @@ exports.Submitted = react_1.default.forwardRef((props, ref) => {
  * - 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
@@ -454,7 +470,11 @@ exports.Submitted = react_1.default.forwardRef((props, ref) => {
  *     <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.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>
@@ -464,23 +484,41 @@ exports.Submitted = react_1.default.forwardRef((props, ref) => {
  *
  * @example
  * ```tsx
- * // Advanced usage with custom field components
- * const CustomTextField = ({ value, onChange, label, error, ...props }) => (
- *   <div className="form-field">
- *     <label className="text-foreground font-paragraph">{label}</label>
- *     <input
- *       value={value || ''}
- *       onChange={(e) => onChange(e.target.value)}
- *       className="bg-background border-foreground text-foreground"
- *       {...props}
- *     />
- *     {error && <span className="text-destructive">{error}</span>}
- *   </div>
- * );
+ * // 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: CustomTextField,
- *   // ... other field components
+ *   TEXT_INPUT: TextInput,
+ *   // ... all other field components must also use Form.Field
  * };
  * ```
  */
@@ -496,6 +534,200 @@ exports.Fields = react_1.default.forwardRef((props, ref) => {
     return ((0, jsx_runtime_1.jsx)(Form_js_1.Fields, { children: ({ form, submitForm }) => {
             if (!form)
                 return null;
-            return ((0, jsx_runtime_1.jsx)("div", { ref: ref, children: (0, jsx_runtime_1.jsx)(form_public_1.Form, { form: form, values: formValues, onChange: handleFormChange, errors: formErrors, onValidate: handleFormValidate, fields: props.fieldMap, submitForm: () => submitForm(formValues) }) }));
+            return ((0, jsx_runtime_1.jsx)("div", { ref: ref, children: (0, jsx_runtime_1.jsx)(form_public_1.FormProvider, { currency: 'USD', locale: 'en', children: (0, jsx_runtime_1.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 = (0, form_public_1.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?
+    (0, jsx_runtime_1.jsx)(FieldLayoutContext_js_1.FieldLayoutProvider, { value: fieldsLayout, children: (0, jsx_runtime_1.jsx)("form", { onSubmit: (e) => e.preventDefault(), children: (0, jsx_runtime_1.jsx)("fieldset", { style: { display: 'flex', flexDirection: 'column' }, className: rowGapClassname, children: fieldElements.map((rowElements, index) => {
+                    return ((0, jsx_runtime_1.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_1.default.forwardRef((props, ref) => {
+    const { id, children, asChild, className, ...otherProps } = props;
+    const layout = (0, FieldLayoutContext_js_1.useFieldLayout)(id);
+    if (!layout) {
+        return null;
+    }
+    return ((0, jsx_runtime_1.jsx)(Form_js_1.Field, { id: id, layout: layout, children: (fieldData) => {
+            const contextValue = {
+                id,
+                layout: fieldData.layout,
+                gridStyles: fieldData.gridStyles,
+            };
+            return ((0, jsx_runtime_1.jsx)(FieldContext_js_1.FieldContext.Provider, { value: contextValue, children: (0, jsx_runtime_1.jsx)(react_2.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</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>
+ * ```
+ */
+exports.FieldLabel = react_1.default.forwardRef((props, ref) => {
+    const { children, asChild, className, ...otherProps } = props;
+    const { gridStyles } = (0, FieldContext_js_1.useFieldContext)();
+    return ((0, jsx_runtime_1.jsx)(react_2.AsChildSlot, { ref: ref, asChild: asChild, className: className, style: gridStyles.label, "data-testid": TestIds.fieldLabel, customElement: children, customElementProps: {}, ...otherProps, children: (0, jsx_runtime_1.jsx)("div", { children: children }) }));
+});
+exports.FieldLabel.displayName = 'Form.Field.Label';
+/**
+ * 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>
+ * ```
+ */
+exports.FieldInputWrapper = react_1.default.forwardRef((props, ref) => {
+    const { children, asChild, className, ...otherProps } = props;
+    const { gridStyles } = (0, FieldContext_js_1.useFieldContext)();
+    return ((0, jsx_runtime_1.jsx)(react_2.AsChildSlot, { ref: ref, asChild: asChild, className: className, style: gridStyles.input, "data-testid": TestIds.fieldInputWrapper, customElement: children, customElementProps: {}, ...otherProps, children: (0, jsx_runtime_1.jsx)("div", { children: children }) }));
+});
+exports.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>
+ * ```
+ */
+exports.FieldInput = react_1.default.forwardRef((props, ref) => {
+    const { children, description, asChild, className, ...otherProps } = props;
+    return ((0, jsx_runtime_1.jsx)(react_2.AsChildSlot, { ref: ref, asChild: asChild, className: className, "data-testid": TestIds.fieldInput, customElement: children, customElementProps: {}, ...otherProps, children: (0, jsx_runtime_1.jsx)("div", { children: children }) }));
+});
+exports.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>
+ * ```
+ */
+exports.FieldError = react_1.default.forwardRef((props, ref) => {
+    const { errorMessage, asChild, className, children, ...otherProps } = props;
+    if (!errorMessage && !children)
+        return null;
+    return ((0, jsx_runtime_1.jsx)(react_2.AsChildSlot, { "data-testid": TestIds.fieldError, ref: ref, asChild: asChild, className: className, ...otherProps, children: children || errorMessage }));
+});
+exports.FieldError.displayName = 'Form.Field.Error';
+exports.Field = FieldRoot;
+exports.Field.Label = exports.FieldLabel;
+exports.Field.InputWrapper = exports.FieldInputWrapper;
+exports.Field.Input = exports.FieldInput;
+exports.Field.Error = exports.FieldError;

package/cjs/dist/react/context/FieldContext.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import { type Layout } from '../core/Form.js';
+export interface FieldContextValue {
+    id: string;
+    layout: Layout;
+    gridStyles: {
+        label: React.CSSProperties;
+        input: React.CSSProperties;
+    };
+}
+export declare const FieldContext: React.Context<FieldContextValue | null>;
+export declare function useFieldContext(): FieldContextValue;