@wix/headless-forms 0.0.0

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

@@ -0,0 +1,342 @@
+import { forms } from '@wix/forms';
+import { FormServiceConfig } from '../../services/form-service.js';
+import { FormValues } from '../types.js';
+/**
+ * Props for Root headless component
+ */
+export interface RootProps {
+    children: React.ReactNode;
+    formServiceConfig: FormServiceConfig;
+}
+/**
+ * Root component that provides the Form service context to its children.
+ * This component sets up the necessary services for rendering and managing form data.
+ *
+ * @order 1
+ * @component
+ * @param {RootProps} props - Component props
+ * @param {React.ReactNode} props.children - Child components that will have access to form context
+ * @param {FormServiceConfig} props.formServiceConfig - Configuration object containing form data
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ * import { loadFormServiceConfig } from '@wix/headless-forms/services';
+ *
+ * // Pattern 1: Pre-loaded form data (SSR/SSG)
+ * function FormPage({ formServiceConfig }) {
+ *   return (
+ *     <Form.Root formServiceConfig={formServiceConfig}>
+ *       <Form.Loading>
+ *         {({ isLoading }) => isLoading ? <div>Loading form...</div> : null}
+ *       </Form.Loading>
+ *       <Form.LoadingError>
+ *         {({ error, hasError }) => hasError ? <div>{error}</div> : null}
+ *       </Form.LoadingError>
+ *       <Form.Fields fieldMap={FIELD_MAP} />
+ *     </Form.Root>
+ *   );
+ * }
+ *
+ * // Pattern 2: Lazy loading with formId (Client-side)
+ * function DynamicFormPage({ formId }) {
+ *   return (
+ *     <Form.Root formServiceConfig={{ formId }}>
+ *       <Form.Loading>
+ *         {({ isLoading }) => isLoading ? <div>Loading form...</div> : null}
+ *       </Form.Loading>
+ *       <Form.LoadingError>
+ *         {({ error, hasError }) => hasError ? <div>{error}</div> : null}
+ *       </Form.LoadingError>
+ *       <Form.Fields fieldMap={FIELD_MAP} />
+ *     </Form.Root>
+ *   );
+ * }
+ * ```
+ */
+export declare function Root({ formServiceConfig, children, }: RootProps): React.ReactNode;
+/**
+ * Props for FormLoading headless component
+ */
+export interface FormLoadingProps {
+    /** Render prop function that receives loading state data */
+    children: (props: FormLoadingRenderProps) => React.ReactNode;
+}
+/**
+ * Render props for FormLoading component
+ */
+export interface FormLoadingRenderProps {
+    /** Whether the form is currently loading */
+    isLoading: boolean;
+}
+/**
+ * Headless component for form loading state access
+ *
+ * @component
+ * @param {FormLoadingProps} props - Component props
+ * @param {FormLoadingProps['children']} props.children - Render prop function that receives loading state
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * function FormLoadingIndicator() {
+ *   return (
+ *     <Form.Loading>
+ *       {({ isLoading }) => (
+ *         isLoading ? (
+ *           <div>Loading form...</div>
+ *         ) : null
+ *       )}
+ *     </Form.Loading>
+ *   );
+ * }
+ * ```
+ */
+export declare function Loading(props: FormLoadingProps): import("react").ReactNode;
+/**
+ * Props for FormError headless component
+ */
+export interface FormErrorProps {
+    /** Render prop function that receives error state data */
+    children: (props: FormErrorRenderProps) => React.ReactNode;
+}
+/**
+ * Render props for FormError component
+ */
+export interface FormErrorRenderProps {
+    /** Error message if there's an error */
+    error: string | null;
+    /** Whether there's an error */
+    hasError: boolean;
+}
+/**
+ * Headless component for form error state access
+ *
+ * @component
+ * @param {FormErrorProps} props - Component props
+ * @param {FormErrorProps['children']} props.children - Render prop function that receives error state
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * function FormErrorDisplay() {
+ *   return (
+ *     <Form.LoadingError>
+ *       {({ error, hasError }) => (
+ *         hasError ? (
+ *           <div className="error-message">
+ *             {error}
+ *           </div>
+ *         ) : null
+ *       )}
+ *     </Form.LoadingError>
+ *   );
+ * }
+ * ```
+ */
+export declare function LoadingError(props: FormErrorProps): import("react").ReactNode;
+/**
+ * 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 Submit Error component
+ */
+export interface FormSubmitErrorRenderProps {
+    /** Submit error message */
+    error: string | null;
+    /** Whether there's a submit error */
+    hasError: boolean;
+}
+/**
+ * Headless component for form submit error state access
+ *
+ * @component
+ * @param {FormSubmitErrorProps} props - Component props
+ * @param {FormSubmitErrorProps['children']} props.children - Render prop function that receives submit error state
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * function FormSubmitErrorDisplay() {
+ *   return (
+ *     <Form.Error>
+ *       {({ error, hasError }) => (
+ *         hasError ? (
+ *           <div className="error-message">
+ *             {error}
+ *           </div>
+ *         ) : null
+ *       )}
+ *     </Form.Error>
+ *   );
+ * }
+ * ```
+ */
+export declare function Error(props: FormSubmitErrorProps): import("react").ReactNode;
+/**
+ * Props for Form Submitted headless component
+ */
+export interface FormSubmittedProps {
+    /** Render prop function that receives submission state data */
+    children: (props: FormSubmittedRenderProps) => React.ReactNode;
+}
+/**
+ * Render props for Form Submitted component
+ */
+export interface FormSubmittedRenderProps {
+    /** Whether the form has been submitted */
+    isSubmitted: boolean;
+    /** Success message */
+    message: string;
+}
+/**
+ * Headless component for form submission state access
+ *
+ * @component
+ * @param {FormSubmittedProps} props - Component props
+ * @param {FormSubmittedProps['children']} props.children - Render prop function that receives submission state
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * function FormSubmittedDisplay() {
+ *   return (
+ *     <Form.Submitted>
+ *       {({ isSubmitted, message }) => (
+ *         isSubmitted ? (
+ *           <div className="success-message">
+ *             <h2>Thank You!</h2>
+ *             <p>{message}</p>
+ *           </div>
+ *         ) : null
+ *       )}
+ *     </Form.Submitted>
+ *   );
+ * }
+ * ```
+ */
+export declare function Submitted(props: FormSubmittedProps): import("react").ReactNode;
+/**
+ * Render props for Fields component
+ */
+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
+ */
+export interface FieldsProps {
+    /** Render prop function that receives form data and submit handler */
+    children: (props: FieldsRenderProps) => React.ReactNode;
+}
+/**
+ * Fields component that provides form data and actions to its children.
+ * This component accesses the form data and submitForm action from the service
+ * and passes them to children via render props.
+ *
+ * @component
+ * @param {FieldsProps} props - Component props
+ * @param {FieldsProps['children']} props.children - Render prop function that receives form data and actions
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * function FormFields() {
+ *   return (
+ *     <Form.Fields>
+ *       {({ form, submitForm }) => (
+ *         form ? (
+ *           <div>
+ *             <h2>{form.name}</h2>
+ *             <p>{form.description}</p>
+ *             <button onClick={() => submitForm({ field1: 'value' })}>
+ *               Submit
+ *             </button>
+ *           </div>
+ *         ) : null
+ *       )}
+ *     </Form.Fields>
+ *   );
+ * }
+ * ```
+ */
+export declare function Fields(props: FieldsProps): import("react").ReactNode;
+/**
+ * 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

@@ -0,0 +1,269 @@
+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.
+ * This component sets up the necessary services for rendering and managing form data.
+ *
+ * @order 1
+ * @component
+ * @param {RootProps} props - Component props
+ * @param {React.ReactNode} props.children - Child components that will have access to form context
+ * @param {FormServiceConfig} props.formServiceConfig - Configuration object containing form data
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ * import { loadFormServiceConfig } from '@wix/headless-forms/services';
+ *
+ * // Pattern 1: Pre-loaded form data (SSR/SSG)
+ * function FormPage({ formServiceConfig }) {
+ *   return (
+ *     <Form.Root formServiceConfig={formServiceConfig}>
+ *       <Form.Loading>
+ *         {({ isLoading }) => isLoading ? <div>Loading form...</div> : null}
+ *       </Form.Loading>
+ *       <Form.LoadingError>
+ *         {({ error, hasError }) => hasError ? <div>{error}</div> : null}
+ *       </Form.LoadingError>
+ *       <Form.Fields fieldMap={FIELD_MAP} />
+ *     </Form.Root>
+ *   );
+ * }
+ *
+ * // Pattern 2: Lazy loading with formId (Client-side)
+ * function DynamicFormPage({ formId }) {
+ *   return (
+ *     <Form.Root formServiceConfig={{ formId }}>
+ *       <Form.Loading>
+ *         {({ isLoading }) => isLoading ? <div>Loading form...</div> : null}
+ *       </Form.Loading>
+ *       <Form.LoadingError>
+ *         {({ error, hasError }) => hasError ? <div>{error}</div> : null}
+ *       </Form.LoadingError>
+ *       <Form.Fields fieldMap={FIELD_MAP} />
+ *     </Form.Root>
+ *   );
+ * }
+ * ```
+ */
+export function Root({ formServiceConfig, children, }) {
+    return (_jsx(WixServices, { servicesMap: createServicesMap().addService(FormServiceDefinition, FormService, formServiceConfig), children: children }));
+}
+/**
+ * Headless component for form loading state access
+ *
+ * @component
+ * @param {FormLoadingProps} props - Component props
+ * @param {FormLoadingProps['children']} props.children - Render prop function that receives loading state
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * function FormLoadingIndicator() {
+ *   return (
+ *     <Form.Loading>
+ *       {({ isLoading }) => (
+ *         isLoading ? (
+ *           <div>Loading form...</div>
+ *         ) : null
+ *       )}
+ *     </Form.Loading>
+ *   );
+ * }
+ * ```
+ */
+export function Loading(props) {
+    const { isLoadingSignal } = useService(FormServiceDefinition);
+    const isLoading = isLoadingSignal.get();
+    return props.children({
+        isLoading,
+    });
+}
+/**
+ * Headless component for form error state access
+ *
+ * @component
+ * @param {FormErrorProps} props - Component props
+ * @param {FormErrorProps['children']} props.children - Render prop function that receives error state
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * function FormErrorDisplay() {
+ *   return (
+ *     <Form.LoadingError>
+ *       {({ error, hasError }) => (
+ *         hasError ? (
+ *           <div className="error-message">
+ *             {error}
+ *           </div>
+ *         ) : null
+ *       )}
+ *     </Form.LoadingError>
+ *   );
+ * }
+ * ```
+ */
+export function LoadingError(props) {
+    const { errorSignal } = useService(FormServiceDefinition);
+    const error = errorSignal.get();
+    const hasError = !!error;
+    return props.children({
+        error,
+        hasError,
+    });
+}
+/**
+ * Headless component for form submit error state access
+ *
+ * @component
+ * @param {FormSubmitErrorProps} props - Component props
+ * @param {FormSubmitErrorProps['children']} props.children - Render prop function that receives submit error state
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * function FormSubmitErrorDisplay() {
+ *   return (
+ *     <Form.Error>
+ *       {({ error, hasError }) => (
+ *         hasError ? (
+ *           <div className="error-message">
+ *             {error}
+ *           </div>
+ *         ) : null
+ *       )}
+ *     </Form.Error>
+ *   );
+ * }
+ * ```
+ */
+export function Error(props) {
+    const { submitResponseSignal } = useService(FormServiceDefinition);
+    const submitResponse = submitResponseSignal.get();
+    const error = submitResponse.type === 'error' ? submitResponse.message : null;
+    const hasError = submitResponse.type === 'error';
+    return props.children({
+        error,
+        hasError,
+    });
+}
+/**
+ * Headless component for form submission state access
+ *
+ * @component
+ * @param {FormSubmittedProps} props - Component props
+ * @param {FormSubmittedProps['children']} props.children - Render prop function that receives submission state
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * function FormSubmittedDisplay() {
+ *   return (
+ *     <Form.Submitted>
+ *       {({ isSubmitted, message }) => (
+ *         isSubmitted ? (
+ *           <div className="success-message">
+ *             <h2>Thank You!</h2>
+ *             <p>{message}</p>
+ *           </div>
+ *         ) : null
+ *       )}
+ *     </Form.Submitted>
+ *   );
+ * }
+ * ```
+ */
+export function Submitted(props) {
+    const { submitResponseSignal } = useService(FormServiceDefinition);
+    const submitResponse = submitResponseSignal.get();
+    const isSubmitted = submitResponse.type === 'success';
+    const message = submitResponse.type === 'success'
+        ? submitResponse.message || DEFAULT_SUCCESS_MESSAGE
+        : DEFAULT_SUCCESS_MESSAGE;
+    return props.children({
+        isSubmitted,
+        message,
+    });
+}
+/**
+ * Fields component that provides form data and actions to its children.
+ * This component accesses the form data and submitForm action from the service
+ * and passes them to children via render props.
+ *
+ * @component
+ * @param {FieldsProps} props - Component props
+ * @param {FieldsProps['children']} props.children - Render prop function that receives form data and actions
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * function FormFields() {
+ *   return (
+ *     <Form.Fields>
+ *       {({ form, submitForm }) => (
+ *         form ? (
+ *           <div>
+ *             <h2>{form.name}</h2>
+ *             <p>{form.description}</p>
+ *             <button onClick={() => submitForm({ field1: 'value' })}>
+ *               Submit
+ *             </button>
+ *           </div>
+ *         ) : null
+ *       )}
+ *     </Form.Fields>
+ *   );
+ * }
+ * ```
+ */
+export function Fields(props) {
+    const { formSignal, submitForm } = useService(FormServiceDefinition);
+    const form = formSignal.get();
+    return props.children({
+        form,
+        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/index.d.ts

@@ -0,0 +1,3 @@
+export * as Form from './Form.js';
+export * from './types.js';
+export * from './Phone.js';

package/dist/react/index.js

@@ -0,0 +1,3 @@
+export * as Form from './Form.js';
+export * from './types.js';
+export * from './Phone.js';

package/dist/react/types.d.ts

@@ -0,0 +1,3 @@
+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 '@wix/form-public';
+export type { CheckboxGroupProps, CheckboxProps, PhoneInputProps, DateInputProps, DatePickerProps, DateTimeInputProps, DropdownProps, FileUploadProps, MultilineAddressProps, NumberInputProps, RadioGroupProps, RatingInputProps, RichTextProps, SignatureProps, SubmitButtonProps, TagsProps, TextAreaProps, TextInputProps, TimeInputProps, ProductListProps, FixedPaymentProps, PaymentInputProps, DonationProps, AppointmentProps, ImageChoiceProps, };
+export type FormValues = Record<string, any>;

package/dist/react/types.js

@@ -0,0 +1 @@
+export {};

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,
+        },
+    };
+}