@wix/headless-forms 0.0.11 → 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';
 /**
@@ -621,7 +622,9 @@ export interface FieldProps {
  */
 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
@@ -634,6 +637,17 @@ export interface FieldLabelProps {
     /** 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
  */
@@ -647,6 +661,28 @@ export interface FieldInputProps {
     /** 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.
@@ -661,17 +697,45 @@ export interface FieldInputProps {
  *   <Form.Field.Label>
  *     <label className="text-foreground font-paragraph">Email Address</label>
  *   </Form.Field.Label>
- *   <Form.Field.Input>
- *     <input type="email" className="bg-background border-foreground" />
- *   </Form.Field.Input>
+ *   <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>>;
 /**
- * Input component for a form field with automatic grid positioning.
+ * InputWrapper component that wraps input and error elements with grid positioning.
  * Must be used within a Form.Field component.
- * Renders in the input row of the field's grid layout with optional description.
+ * 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
@@ -682,12 +746,40 @@ export declare const FieldLabel: React.ForwardRefExoticComponent<FieldLabelProps
  *   <Form.Field.Label>
  *     <label className="text-foreground font-paragraph">Password</label>
  *   </Form.Field.Label>
- *   <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.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.Field = exports.FieldInput = exports.FieldLabel = 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";
@@ -49,7 +51,9 @@ var TestIds;
     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.
@@ -530,28 +534,27 @@ 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.FormProvider, { 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 }) }) }));
+            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,
-        onChange,
         errors,
+        onChange,
         onValidate,
         submitForm,
         fieldMap,
     });
     if (!formData)
         return null;
-    console.log('formData', formData);
     const { columnCount, fieldElements, fieldsLayout } = formData;
     return (
     // TODO: use readOnly, isDisabled
     // TODO: step title a11y support
     // TODO: mobile support?
-    (0, jsx_runtime_1.jsx)(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) => {
+    (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%',
@@ -560,45 +563,9 @@ const FieldsWithForm = ({ form, submitForm, values, onChange, errors, onValidate
                         }, className: columnGapClassname, children: rowElements }, index));
                 }) }) }) }));
 };
-/**
- * Context for sharing field layout data across the form
- * @internal
- */
-const FieldLayoutContext = react_1.default.createContext(null);
-/**
- * Provider component that makes field layout data available to child components
- * @internal
- */
-const FieldLayoutProvider = ({ value, children, }) => {
-    return ((0, jsx_runtime_1.jsx)(FieldLayoutContext.Provider, { value: value, children: children }));
-};
-/**
- * Hook to access layout configuration for a specific field
- * @internal
- * @param {string} fieldId - The unique identifier of the field
- * @returns {Layout | null} The layout configuration for the field, or null if not found
- */
-function useFieldLayout(fieldId) {
-    const layoutMap = react_1.default.useContext(FieldLayoutContext);
-    if (!layoutMap) {
-        return null;
-    }
-    return layoutMap[fieldId] || null;
-}
-const FieldContext = react_1.default.createContext(null);
-/**
- * Hook to access field context
- */
-function useFieldContext() {
-    const context = react_1.default.useContext(FieldContext);
-    if (!context) {
-        throw new globalThis.Error('Field components must be used within a Form.Field component');
-    }
-    return context;
-}
 /**
  * Container component for a form field with grid layout support.
- * Provides context to Field.Label and Field.Input child components.
+ * Provides context to Field.Label, Field.InputWrapper, Field.Input, and Field.Error child components.
  * Based on the default-field-layout functionality.
  *
  * @component
@@ -612,9 +579,14 @@ function useFieldContext() {
  *       <Form.Field.Label>
  *         <label className="text-foreground font-paragraph">Username</label>
  *       </Form.Field.Label>
- *       <Form.Field.Input description={<span className="text-secondary-foreground">Required</span>}>
- *         <input className="bg-background border-foreground text-foreground" />
- *       </Form.Field.Input>
+ *       <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>
  *   );
  * }
@@ -622,7 +594,7 @@ function useFieldContext() {
  */
 const FieldRoot = react_1.default.forwardRef((props, ref) => {
     const { id, children, asChild, className, ...otherProps } = props;
-    const layout = useFieldLayout(id);
+    const layout = (0, FieldLayoutContext_js_1.useFieldLayout)(id);
     if (!layout) {
         return null;
     }
@@ -632,7 +604,7 @@ const FieldRoot = react_1.default.forwardRef((props, ref) => {
                 layout: fieldData.layout,
                 gridStyles: fieldData.gridStyles,
             };
-            return ((0, jsx_runtime_1.jsx)(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 }) }));
+            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';
@@ -650,22 +622,55 @@ FieldRoot.displayName = 'Form.Field';
  *   <Form.Field.Label>
  *     <label className="text-foreground font-paragraph">Email Address</label>
  *   </Form.Field.Label>
- *   <Form.Field.Input>
- *     <input type="email" className="bg-background border-foreground" />
- *   </Form.Field.Input>
+ *   <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 } = useFieldContext();
+    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';
 /**
- * Input component for a form field with automatic grid positioning.
+ * InputWrapper component that wraps input and error elements with grid positioning.
  * Must be used within a Form.Field component.
- * Renders in the input row of the field's grid layout with optional description.
+ * 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
@@ -676,18 +681,53 @@ exports.FieldLabel.displayName = 'Form.Field.Label';
  *   <Form.Field.Label>
  *     <label className="text-foreground font-paragraph">Password</label>
  *   </Form.Field.Label>
- *   <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.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;
-    const { gridStyles } = useFieldContext();
-    return ((0, jsx_runtime_1.jsx)(react_2.AsChildSlot, { ref: ref, asChild: asChild, className: className, style: gridStyles.input, "data-testid": TestIds.fieldInput, customElement: children, customElementProps: {}, ...otherProps, children: (0, jsx_runtime_1.jsx)("div", { children: children }) }));
+    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;

package/cjs/dist/react/context/FieldContext.js

@@ -0,0 +1,16 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FieldContext = void 0;
+exports.useFieldContext = useFieldContext;
+const react_1 = __importDefault(require("react"));
+exports.FieldContext = react_1.default.createContext(null);
+function useFieldContext() {
+    const context = react_1.default.useContext(exports.FieldContext);
+    if (!context) {
+        throw new Error('Field components must be used within a Form.Field component');
+    }
+    return context;
+}

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

@@ -0,0 +1,12 @@
+import React from 'react';
+import { type Layout } from '../core/Form.js';
+export interface FieldLayoutMap {
+    [fieldId: string]: Layout;
+}
+export declare const FieldLayoutContext: React.Context<FieldLayoutMap | null>;
+export interface FieldLayoutProviderProps {
+    value: FieldLayoutMap;
+    children: React.ReactNode;
+}
+export declare const FieldLayoutProvider: React.FC<FieldLayoutProviderProps>;
+export declare function useFieldLayout(fieldId: string): Layout | null;

package/cjs/dist/react/context/FieldLayoutContext.js

@@ -0,0 +1,21 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FieldLayoutProvider = exports.FieldLayoutContext = void 0;
+exports.useFieldLayout = useFieldLayout;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = __importDefault(require("react"));
+exports.FieldLayoutContext = react_1.default.createContext(null);
+const FieldLayoutProvider = ({ value, children, }) => {
+    return ((0, jsx_runtime_1.jsx)(exports.FieldLayoutContext.Provider, { value: value, children: children }));
+};
+exports.FieldLayoutProvider = FieldLayoutProvider;
+function useFieldLayout(fieldId) {
+    const layoutMap = react_1.default.useContext(exports.FieldLayoutContext);
+    if (!layoutMap) {
+        return null;
+    }
+    return layoutMap[fieldId] || null;
+}

package/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';
 /**
@@ -621,7 +622,9 @@ export interface FieldProps {
  */
 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
@@ -634,6 +637,17 @@ export interface FieldLabelProps {
     /** 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
  */
@@ -647,6 +661,28 @@ export interface FieldInputProps {
     /** 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.
@@ -661,17 +697,45 @@ export interface FieldInputProps {
  *   <Form.Field.Label>
  *     <label className="text-foreground font-paragraph">Email Address</label>
  *   </Form.Field.Label>
- *   <Form.Field.Input>
- *     <input type="email" className="bg-background border-foreground" />
- *   </Form.Field.Input>
+ *   <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>>;
 /**
- * Input component for a form field with automatic grid positioning.
+ * InputWrapper component that wraps input and error elements with grid positioning.
  * Must be used within a Form.Field component.
- * Renders in the input row of the field's grid layout with optional description.
+ * 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
@@ -682,12 +746,40 @@ export declare const FieldLabel: React.ForwardRefExoticComponent<FieldLabelProps
  *   <Form.Field.Label>
  *     <label className="text-foreground font-paragraph">Password</label>
  *   </Form.Field.Label>
- *   <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.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/dist/react/Form.js

@@ -3,6 +3,8 @@ 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";
@@ -13,7 +15,9 @@ var TestIds;
     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.
@@ -494,22 +498,21 @@ export const Fields = React.forwardRef((props, ref) => {
     return (_jsx(CoreFields, { children: ({ form, submitForm }) => {
             if (!form)
                 return null;
-            return (_jsx("div", { ref: ref, children: _jsx(FormProvider, { 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 }) }) }));
+            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,
-        onChange,
         errors,
+        onChange,
         onValidate,
         submitForm,
         fieldMap,
     });
     if (!formData)
         return null;
-    console.log('formData', formData);
     const { columnCount, fieldElements, fieldsLayout } = formData;
     return (
     // TODO: use readOnly, isDisabled
@@ -524,45 +527,9 @@ const FieldsWithForm = ({ form, submitForm, values, onChange, errors, onValidate
                         }, className: columnGapClassname, children: rowElements }, index));
                 }) }) }) }));
 };
-/**
- * Context for sharing field layout data across the form
- * @internal
- */
-const FieldLayoutContext = React.createContext(null);
-/**
- * Provider component that makes field layout data available to child components
- * @internal
- */
-const FieldLayoutProvider = ({ value, children, }) => {
-    return (_jsx(FieldLayoutContext.Provider, { value: value, children: children }));
-};
-/**
- * Hook to access layout configuration for a specific field
- * @internal
- * @param {string} fieldId - The unique identifier of the field
- * @returns {Layout | null} The layout configuration for the field, or null if not found
- */
-function useFieldLayout(fieldId) {
-    const layoutMap = React.useContext(FieldLayoutContext);
-    if (!layoutMap) {
-        return null;
-    }
-    return layoutMap[fieldId] || null;
-}
-const FieldContext = React.createContext(null);
-/**
- * Hook to access field context
- */
-function useFieldContext() {
-    const context = React.useContext(FieldContext);
-    if (!context) {
-        throw new globalThis.Error('Field components must be used within a Form.Field component');
-    }
-    return context;
-}
 /**
  * Container component for a form field with grid layout support.
- * Provides context to Field.Label and Field.Input child components.
+ * Provides context to Field.Label, Field.InputWrapper, Field.Input, and Field.Error child components.
  * Based on the default-field-layout functionality.
  *
  * @component
@@ -576,9 +543,14 @@ function useFieldContext() {
  *       <Form.Field.Label>
  *         <label className="text-foreground font-paragraph">Username</label>
  *       </Form.Field.Label>
- *       <Form.Field.Input description={<span className="text-secondary-foreground">Required</span>}>
- *         <input className="bg-background border-foreground text-foreground" />
- *       </Form.Field.Input>
+ *       <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>
  *   );
  * }
@@ -614,9 +586,11 @@ FieldRoot.displayName = 'Form.Field';
  *   <Form.Field.Label>
  *     <label className="text-foreground font-paragraph">Email Address</label>
  *   </Form.Field.Label>
- *   <Form.Field.Input>
- *     <input type="email" className="bg-background border-foreground" />
- *   </Form.Field.Input>
+ *   <Form.Field.InputWrapper>
+ *     <Form.Field.Input>
+ *       <input type="email" className="bg-background border-foreground text-foreground" />
+ *     </Form.Field.Input>
+ *   </Form.Field.InputWrapper>
  * </Form.Field>
  * ```
  */
@@ -627,9 +601,40 @@ export const FieldLabel = React.forwardRef((props, ref) => {
 });
 FieldLabel.displayName = 'Form.Field.Label';
 /**
- * Input component for a form field with automatic grid positioning.
+ * InputWrapper component that wraps input and error elements with grid positioning.
  * Must be used within a Form.Field component.
- * Renders in the input row of the field's grid layout with optional description.
+ * 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
@@ -640,18 +645,53 @@ FieldLabel.displayName = 'Form.Field.Label';
  *   <Form.Field.Label>
  *     <label className="text-foreground font-paragraph">Password</label>
  *   </Form.Field.Label>
- *   <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.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;
-    const { gridStyles } = useFieldContext();
-    return (_jsx(AsChildSlot, { ref: ref, asChild: asChild, className: className, style: gridStyles.input, "data-testid": TestIds.fieldInput, customElement: children, customElementProps: {}, ...otherProps, children: _jsx("div", { children: children }) }));
+    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;

package/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;

package/dist/react/context/FieldContext.js

@@ -0,0 +1,9 @@
+import React from 'react';
+export const FieldContext = React.createContext(null);
+export function useFieldContext() {
+    const context = React.useContext(FieldContext);
+    if (!context) {
+        throw new Error('Field components must be used within a Form.Field component');
+    }
+    return context;
+}

package/dist/react/context/FieldLayoutContext.d.ts

@@ -0,0 +1,12 @@
+import React from 'react';
+import { type Layout } from '../core/Form.js';
+export interface FieldLayoutMap {
+    [fieldId: string]: Layout;
+}
+export declare const FieldLayoutContext: React.Context<FieldLayoutMap | null>;
+export interface FieldLayoutProviderProps {
+    value: FieldLayoutMap;
+    children: React.ReactNode;
+}
+export declare const FieldLayoutProvider: React.FC<FieldLayoutProviderProps>;
+export declare function useFieldLayout(fieldId: string): Layout | null;

package/dist/react/context/FieldLayoutContext.js

@@ -0,0 +1,13 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import React from 'react';
+export const FieldLayoutContext = React.createContext(null);
+export const FieldLayoutProvider = ({ value, children, }) => {
+    return (_jsx(FieldLayoutContext.Provider, { value: value, children: children }));
+};
+export function useFieldLayout(fieldId) {
+    const layoutMap = React.useContext(FieldLayoutContext);
+    if (!layoutMap) {
+        return null;
+    }
+    return layoutMap[fieldId] || null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/headless-forms",
-  "version": "0.0.11",
+  "version": "0.0.12",
   "type": "module",
   "scripts": {
     "build": "npm run build:esm && npm run build:cjs",
@@ -41,7 +41,7 @@
     "vitest": "^3.1.4"
   },
   "dependencies": {
-    "@wix/form-public": "^0.40.0",
+    "@wix/form-public": "^0.53.0",
     "@wix/forms": "^1.0.331",
     "@wix/headless-utils": "0.0.4",
     "@wix/services-definitions": "^0.1.4",