@wix/headless-forms 0.0.10 → 0.0.12

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/cjs/dist/react/core/Form.d.ts

@@ -135,14 +135,14 @@ export interface FormErrorRenderProps {
  */
 export declare function LoadingError(props: FormErrorProps): import("react").ReactNode;
 /**
- * Props for Form Error headless component
+ * Props for Form Submit Error headless component
  */
 export interface FormSubmitErrorProps {
     /** Render prop function that receives submit error state data */
     children: (props: FormSubmitErrorRenderProps) => React.ReactNode;
 }
 /**
- * Render props for Form Error component
+ * Render props for Form Submit Error component
  */
 export interface FormSubmitErrorRenderProps {
     /** Submit error message */
@@ -222,14 +222,17 @@ export declare function Submitted(props: FormSubmittedProps): import("react").Re
 /**
  * Render props for Fields component
  */
-interface FieldsRenderProps {
+export interface FieldsRenderProps {
+    /** The form data, or null if not loaded */
     form: forms.Form | null;
+    /** Function to submit the form with values */
     submitForm: (formValues: FormValues) => Promise<void>;
 }
 /**
  * Props for Fields headless component
  */
-interface FieldsProps {
+export interface FieldsProps {
+    /** Render prop function that receives form data and submit handler */
     children: (props: FieldsRenderProps) => React.ReactNode;
 }
 /**
@@ -264,4 +267,76 @@ interface FieldsProps {
  * ```
  */
 export declare function Fields(props: FieldsProps): import("react").ReactNode;
-export {};
+/**
+ * Form view interface containing field definitions
+ */
+export interface FormView {
+    fields: FieldDefinition[];
+}
+/**
+ * Field layout configuration
+ */
+export interface Layout {
+    column: number;
+    row: number;
+    height: number;
+    width: number;
+}
+/**
+ * Field definition including layout information
+ */
+export interface FieldDefinition {
+    id: string;
+    layout: Layout;
+}
+/**
+ * Render props for Field component
+ */
+export interface FieldRenderProps {
+    /** The field ID */
+    id: string;
+    /** The field layout configuration */
+    layout: Layout;
+    /** Grid styles for container */
+    gridStyles: {
+        label: React.CSSProperties;
+        input: React.CSSProperties;
+    };
+}
+/**
+ * Props for Field headless component
+ */
+export interface FieldProps {
+    /** The unique identifier for this field */
+    id: string;
+    /** The field layout configuration */
+    layout: Layout;
+    /** Render prop function that receives field layout data */
+    children: (props: FieldRenderProps) => React.ReactNode;
+}
+/**
+ * Headless Field component that provides field layout data and grid styles.
+ * This component accesses field configuration and calculates grid positioning.
+ *
+ * @component
+ * @param {FieldProps} props - Component props
+ * @param {FieldProps['children']} props.children - Render prop function that receives field layout data
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * function CustomField({ id, layout }) {
+ *   return (
+ *     <Form.Field id={id} layout={layout}>
+ *       {({ id, layout, gridStyles }) => (
+ *         <div data-field-id={id}>
+ *           <div style={gridStyles.label}>Label</div>
+ *           <div style={gridStyles.input}>Input</div>
+ *         </div>
+ *       )}
+ *     </Form.Field>
+ *   );
+ * }
+ * ```
+ */
+export declare function Field(props: FieldProps): import("react").ReactNode;

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

@@ -6,10 +6,12 @@ exports.LoadingError = LoadingError;
 exports.Error = Error;
 exports.Submitted = Submitted;
 exports.Fields = Fields;
+exports.Field = Field;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const services_manager_react_1 = require("@wix/services-manager-react");
 const services_manager_1 = require("@wix/services-manager");
 const form_service_js_1 = require("../../services/form-service.js");
+const utils_js_1 = require("../utils.js");
 const DEFAULT_SUCCESS_MESSAGE = 'Your form has been submitted successfully.';
 /**
  * Root component that provides the Form service context to its children.
@@ -235,3 +237,42 @@ function Fields(props) {
         submitForm,
     });
 }
+/**
+ * Headless Field component that provides field layout data and grid styles.
+ * This component accesses field configuration and calculates grid positioning.
+ *
+ * @component
+ * @param {FieldProps} props - Component props
+ * @param {FieldProps['children']} props.children - Render prop function that receives field layout data
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * function CustomField({ id, layout }) {
+ *   return (
+ *     <Form.Field id={id} layout={layout}>
+ *       {({ id, layout, gridStyles }) => (
+ *         <div data-field-id={id}>
+ *           <div style={gridStyles.label}>Label</div>
+ *           <div style={gridStyles.input}>Input</div>
+ *         </div>
+ *       )}
+ *     </Form.Field>
+ *   );
+ * }
+ * ```
+ */
+function Field(props) {
+    const { id, children, layout } = props;
+    const { formSignal } = (0, services_manager_react_1.useService)(form_service_js_1.FormServiceDefinition);
+    const form = formSignal.get();
+    if (!form) {
+        return null;
+    }
+    const gridStyles = (0, utils_js_1.calculateGridStyles)(layout);
+    return children({
+        id,
+        layout,
+        gridStyles,
+    });
+}

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

@@ -0,0 +1,13 @@
+import { Layout } from './core/Form';
+export declare function calculateGridStyles(layout: Layout): {
+    label: {
+        gridRow: string;
+        gridColumn: string;
+        display: string;
+        alignItems: string;
+    };
+    input: {
+        gridRow: string;
+        gridColumn: string;
+    };
+};

package/cjs/dist/react/utils.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateGridStyles = calculateGridStyles;
+function calculateGridStyles(layout) {
+    const labelRow = 1;
+    const inputRow = 2;
+    const gridColumn = `${layout.column + 1} / span ${layout.width}`;
+    return {
+        label: {
+            gridRow: `${labelRow} / span 1`,
+            gridColumn,
+            display: 'flex',
+            alignItems: 'flex-end',
+        },
+        input: {
+            gridRow: `${inputRow} / span 1`,
+            gridColumn,
+        },
+    };
+}

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

@@ -13,6 +13,8 @@ export type SubmitResponse = {
     message: string;
 } | {
     type: 'idle';
+} | {
+    type: 'loading';
 };
 /**
  * API interface for the Form service, providing reactive form data management.

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

@@ -71,7 +71,10 @@ exports.FormService = services_definitions_1.implementService.withConfig()(expor
     }
     async function defaultSubmitHandler(formId, formValues) {
         try {
-            await forms_1.submissions.createSubmission({ formId, ...formValues });
+            await forms_1.submissions.createSubmission({
+                formId,
+                submissions: formValues,
+            });
             // TODO: add message
             return { type: 'success' };
         }
@@ -92,7 +95,7 @@ exports.FormService = services_definitions_1.implementService.withConfig()(expor
         }
         // @ts-expect-error
         const formId = form._id ? form._id : form.id;
-        submitResponseSignal.set({ type: 'idle' });
+        submitResponseSignal.set({ type: 'loading' });
         try {
             const handler = config.onSubmit || defaultSubmitHandler;
             const response = await handler(formId, formValues);

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';
 /**
@@ -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 {};