@wix/headless-forms 0.0.9 → 0.0.11

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,6 +1,6 @@
 import React from 'react';
-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';
-import { type FormServiceConfig } from '../services/form-service';
+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';
 /**
  * Props for the Form root component following the documented API
  */
@@ -303,6 +303,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 +404,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 +419,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 +435,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 +455,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 +474,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 +550,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 +564,130 @@ 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;
+    Input: typeof FieldInput;
+}
+/**
+ * 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.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;
+}
+/**
+ * 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 declare const FieldLabel: React.ForwardRefExoticComponent<FieldLabelProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * 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 declare const FieldInput: React.ForwardRefExoticComponent<FieldInputProps & React.RefAttributes<HTMLDivElement>>;
+export declare const Field: FieldComponent;
 export {};