@wix/headless-forms 0.0.9 → 0.0.11

package/dist/react/Form.js

@@ -1,8 +1,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import React, { useState, useCallback } from 'react';
 import { AsChildSlot } from '@wix/headless-utils/react';
-import { Form as FormViewer, } from '@wix/form-public';
-import { Root as CoreRoot, Loading as CoreLoading, LoadingError as CoreLoadingError, Error as CoreError, Submitted as CoreSubmitted, Fields as CoreFields, } from './core/Form';
+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';
 var TestIds;
 (function (TestIds) {
     TestIds["formRoot"] = "form-root";
@@ -11,6 +11,9 @@ var TestIds;
     TestIds["formLoadingError"] = "form-loading-error";
     TestIds["formError"] = "form-error";
     TestIds["formSubmitted"] = "form-submitted";
+    TestIds["fieldRoot"] = "field-root";
+    TestIds["fieldLabel"] = "field-label";
+    TestIds["fieldInput"] = "field-input";
 })(TestIds || (TestIds = {}));
 /**
  * Root component that provides all necessary service contexts for a complete form experience.
@@ -312,6 +315,8 @@ export const Submitted = React.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';
@@ -330,7 +335,11 @@ export const Submitted = React.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>
  *   );
  * }
@@ -345,12 +354,15 @@ export const Submitted = React.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
@@ -418,7 +430,11 @@ export const Submitted = React.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>
@@ -428,23 +444,41 @@ export const Submitted = React.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
  * };
  * ```
  */
@@ -460,6 +494,164 @@ export const Fields = React.forwardRef((props, ref) => {
     return (_jsx(CoreFields, { children: ({ form, submitForm }) => {
             if (!form)
                 return null;
-            return (_jsx("div", { ref: ref, children: _jsx(FormViewer, { form: form, values: formValues, onChange: handleFormChange, errors: formErrors, onValidate: handleFormValidate, fields: props.fieldMap, submitForm: () => submitForm(formValues) }) }));
+            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 }) }) }));
+        } }));
+});
+const FieldsWithForm = ({ form, submitForm, values, onChange, errors, onValidate, fields: fieldMap, rowGapClassname, columnGapClassname, }) => {
+    const formData = useForm({
+        form,
+        values,
+        onChange,
+        errors,
+        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?
+    _jsx(FieldLayoutProvider, { value: fieldsLayout, children: _jsx("form", { onSubmit: (e) => e.preventDefault(), children: _jsx("fieldset", { style: { display: 'flex', flexDirection: 'column' }, className: rowGapClassname, children: fieldElements.map((rowElements, index) => {
+                    return (_jsx("div", { style: {
+                            display: 'grid',
+                            width: '100%',
+                            gridTemplateColumns: `repeat(${columnCount}, 1fr)`,
+                            gridAutoRows: 'minmax(min-content, max-content)',
+                        }, className: columnGapClassname, children: rowElements }, index));
+                }) }) }) }));
+};
+/**
+ * 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.
+ * 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.Input description={<span className="text-secondary-foreground">Required</span>}>
+ *         <input className="bg-background border-foreground text-foreground" />
+ *       </Form.Field.Input>
+ *     </Form.Field>
+ *   );
+ * }
+ * ```
+ */
+const FieldRoot = React.forwardRef((props, ref) => {
+    const { id, children, asChild, className, ...otherProps } = props;
+    const layout = useFieldLayout(id);
+    if (!layout) {
+        return null;
+    }
+    return (_jsx(CoreField, { id: id, layout: layout, children: (fieldData) => {
+            const contextValue = {
+                id,
+                layout: fieldData.layout,
+                gridStyles: fieldData.gridStyles,
+            };
+            return (_jsx(FieldContext.Provider, { value: contextValue, children: _jsx(AsChildSlot, { ref: ref, asChild: asChild, className: className, "data-testid": TestIds.fieldRoot, customElement: children, customElementProps: {}, ...otherProps, children: children }) }));
         } }));
 });
+FieldRoot.displayName = 'Form.Field';
+/**
+ * Label component for a form field with automatic grid positioning.
+ * Must be used within a Form.Field component.
+ * Renders in the label row of the field's grid layout.
+ *
+ * @component
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * <Form.Field id="email">
+ *   <Form.Field.Label>
+ *     <label className="text-foreground font-paragraph">Email Address</label>
+ *   </Form.Field.Label>
+ *   <Form.Field.Input>
+ *     <input type="email" className="bg-background border-foreground" />
+ *   </Form.Field.Input>
+ * </Form.Field>
+ * ```
+ */
+export const FieldLabel = React.forwardRef((props, ref) => {
+    const { children, asChild, className, ...otherProps } = props;
+    const { gridStyles } = useFieldContext();
+    return (_jsx(AsChildSlot, { ref: ref, asChild: asChild, className: className, style: gridStyles.label, "data-testid": TestIds.fieldLabel, customElement: children, customElementProps: {}, ...otherProps, children: _jsx("div", { children: children }) }));
+});
+FieldLabel.displayName = 'Form.Field.Label';
+/**
+ * Input component for a form field with automatic grid positioning.
+ * Must be used within a Form.Field component.
+ * Renders in the input row of the field's grid layout with optional description.
+ *
+ * @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.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>
+ * ```
+ */
+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 }) }));
+});
+FieldInput.displayName = 'Form.Field.Input';
+export const Field = FieldRoot;
+Field.Label = FieldLabel;
+Field.Input = FieldInput;

package/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/dist/react/core/Form.js

@@ -2,6 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useService, WixServices } from '@wix/services-manager-react';
 import { createServicesMap } from '@wix/services-manager';
 import { FormServiceDefinition, FormService, } from '../../services/form-service.js';
+import { calculateGridStyles } from '../utils.js';
 const DEFAULT_SUCCESS_MESSAGE = 'Your form has been submitted successfully.';
 /**
  * Root component that provides the Form service context to its children.
@@ -227,3 +228,42 @@ export 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>
+ *   );
+ * }
+ * ```
+ */
+export function Field(props) {
+    const { id, children, layout } = props;
+    const { formSignal } = useService(FormServiceDefinition);
+    const form = formSignal.get();
+    if (!form) {
+        return null;
+    }
+    const gridStyles = calculateGridStyles(layout);
+    return children({
+        id,
+        layout,
+        gridStyles,
+    });
+}

package/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/dist/react/utils.js

@@ -0,0 +1,17 @@
+export 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/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/dist/services/form-service.js

@@ -67,7 +67,10 @@ export const FormService = implementService.withConfig()(FormServiceDefinition,
     }
     async function defaultSubmitHandler(formId, formValues) {
         try {
-            await submissions.createSubmission({ formId, ...formValues });
+            await submissions.createSubmission({
+                formId,
+                submissions: formValues,
+            });
             // TODO: add message
             return { type: 'success' };
         }
@@ -88,7 +91,7 @@ export const FormService = implementService.withConfig()(FormServiceDefinition,
         }
         // @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/package.json

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