@wix/headless-forms 0.0.2 → 0.0.4

package/README.md

@@ -0,0 +1,46 @@
+# @wix/headless-forms
+
+Headless React components for rendering and managing forms. It follows the compound component pattern and integrates with Wix Forms services.
+
+`@wix/headless-forms/react` and `@wix/headless-forms/services` are exported through forms public SDK `@wix/forms`.
+
+## Development Guide
+
+1. **Install Dependencies**
+   ```bash
+   yarn install
+   ```
+
+2. **Start Development**
+   ```bash
+   # Build in watch mode
+   yarn build:watch
+   ```
+
+3. **Test Changes Locally**
+   Run `examples/astro-forms-demo` to test changes locally.
+
+## Documentation
+
+All changes should be documented using `jsdoc` and updating `docs/api/FORM_INTERFACE.md`.
+
+## Publishing
+
+1. **Update Version**
+   - Update version in `package.json`
+   - Create PR and merge to main branch
+
+2. **Publish to NPM**
+   - Go to GitHub Actions
+   - Run "Publish Package" workflow
+   - Enter package name: `forms`
+   - Monitor the workflow for successful completion
+
+3. **Update SDK Exports**
+   - Go to Form app in Wix Dev Center
+   - Update SDK exports extensions:
+     - "Forms SDK Exports Components"
+     - "Forms SDK Exports Services"
+  - Release new app version
+  - Check if update has been commited to `auto-sdk-packages` repo
+

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

@@ -22,6 +22,7 @@ export interface RootProps {
  * @param {RootProps} props - The component props
  * @param {React.ReactNode} props.children - Child components that will have access to form context
  * @param {FormServiceConfig} props.formServiceConfig - Form service configuration object
+ * @param {boolean} [props.asChild] - Whether to render as a child component
  * @param {string} [props.className] - CSS classes to apply to the root element
  * @example
  * ```tsx
@@ -368,7 +369,7 @@ export declare const Submitted: React.ForwardRefExoticComponent<SubmittedProps &
  * };
  * ```
  */
-interface FieldMap {
+export interface FieldMap {
     TEXT_INPUT: React.ComponentType<TextInputProps>;
     TEXT_AREA: React.ComponentType<TextAreaProps>;
     PHONE_INPUT: React.ComponentType<PhoneInputProps>;
@@ -416,7 +417,7 @@ interface FieldMap {
  * <Form.Fields fieldMap={FIELD_MAP} />
  * ```
  */
-export interface FieldsProps {
+interface FieldsProps {
     fieldMap: FieldMap;
 }
 /**
@@ -564,69 +565,4 @@ export interface FieldsProps {
  * ```
  */
 export declare const Fields: React.ForwardRefExoticComponent<FieldsProps & React.RefAttributes<HTMLDivElement>>;
-/**
- * Main Form namespace containing all form components following the compound component pattern.
- * Provides a headless, flexible way to render and manage forms with custom field components.
- *
- * @namespace Form
- * @property {typeof Root} Root - Form root component that provides service context to all child components
- * @property {typeof Loading} Loading - Form loading state component that displays content during form loading
- * @property {typeof LoadingError} LoadingError - Form loading error state component for handling form loading errors
- * @property {typeof Error} Error - Form submit error state component for handling form submission errors
- * @property {typeof Submitted} Submitted - Form submitted state component for displaying success messages
- * @property {typeof Fields} Fields - Form fields component for rendering form fields with custom field renderers
- * @example
- * ```tsx
- * import { Form } from '@wix/headless-forms/react';
- * import { loadFormServiceConfig } from '@wix/headless-forms/services';
- * import { TextInput, TextArea, Checkbox } from './field-components';
- *
- * const FIELD_MAP = {
- *   TEXT_INPUT: TextInput,
- *   TEXT_AREA: TextArea,
- *   CHECKBOX: Checkbox,
- *   // ... other field components
- * };
- *
- * // Pattern 1: Pre-loaded form data (SSR/SSG)
- * function MyForm({ formServiceConfig }) {
- *   return (
- *     <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.Error className="text-destructive p-4 rounded-lg mb-4" />
- *       <Form.Submitted className="text-green-500 p-4 rounded-lg mb-4" />
- *     </Form.Root>
- *   );
- * }
- *
- * // Pattern 2: Lazy loading with formId (Client-side)
- * function DynamicForm({ formId }) {
- *   return (
- *     <Form.Root formServiceConfig={{ formId }}>
- *       <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.Error className="text-destructive p-4 rounded-lg mb-4" />
- *       <Form.Submitted className="text-green-500 p-4 rounded-lg mb-4" />
- *     </Form.Root>
- *   );
- * }
- * ```
- */
-export declare const Form: {
-    /** Form root component that provides service context */
-    readonly Root: React.ForwardRefExoticComponent<RootProps & React.RefAttributes<HTMLDivElement>>;
-    /** Form loading state component */
-    readonly Loading: React.ForwardRefExoticComponent<LoadingProps & React.RefAttributes<HTMLElement>>;
-    /** Form loading error state component */
-    readonly LoadingError: React.ForwardRefExoticComponent<LoadingErrorProps & React.RefAttributes<HTMLElement>>;
-    /** Form error state component */
-    readonly Error: React.ForwardRefExoticComponent<ErrorProps & React.RefAttributes<HTMLElement>>;
-    /** Form submitted state component */
-    readonly Submitted: React.ForwardRefExoticComponent<SubmittedProps & React.RefAttributes<HTMLElement>>;
-    /** Form fields component for rendering form fields */
-    readonly Fields: React.ForwardRefExoticComponent<FieldsProps & React.RefAttributes<HTMLDivElement>>;
-};
 export {};

package/cjs/dist/react/Form.js

@@ -33,17 +33,17 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Form = exports.Fields = exports.Submitted = exports.Error = exports.LoadingError = exports.Loading = exports.Root = void 0;
+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 services_manager_react_1 = require("@wix/services-manager-react");
 const form_public_1 = require("@wix/form-public");
-const form_service_1 = require("../services/form-service");
-const CoreForm = __importStar(require("./core/Form"));
+const Form_1 = require("./core/Form");
 var TestIds;
 (function (TestIds) {
     TestIds["formRoot"] = "form-root";
+    TestIds["form"] = "form";
+    TestIds["formLoading"] = "form-loading";
     TestIds["formLoadingError"] = "form-loading-error";
     TestIds["formError"] = "form-error";
     TestIds["formSubmitted"] = "form-submitted";
@@ -57,6 +57,7 @@ var TestIds;
  * @param {RootProps} props - The component props
  * @param {React.ReactNode} props.children - Child components that will have access to form context
  * @param {FormServiceConfig} props.formServiceConfig - Form service configuration object
+ * @param {boolean} [props.asChild] - Whether to render as a child component
  * @param {string} [props.className] - CSS classes to apply to the root element
  * @example
  * ```tsx
@@ -99,7 +100,7 @@ var TestIds;
  */
 exports.Root = react_1.default.forwardRef((props, ref) => {
     const { children, formServiceConfig, asChild, ...otherProps } = props;
-    return ((0, jsx_runtime_1.jsx)(CoreForm.Root, { formServiceConfig: formServiceConfig, children: (0, jsx_runtime_1.jsx)(RootContent, { asChild: asChild, ref: ref, ...otherProps, children: children }) }));
+    return ((0, jsx_runtime_1.jsx)(Form_1.Root, { formServiceConfig: formServiceConfig, children: (0, jsx_runtime_1.jsx)(RootContent, { asChild: asChild, ref: ref, ...otherProps, children: children }) }));
 });
 /**
  * Internal component to handle the Root content with service access.
@@ -163,10 +164,10 @@ const RootContent = react_1.default.forwardRef((props, ref) => {
  */
 exports.Loading = react_1.default.forwardRef((props, ref) => {
     const { asChild, children, className, ...otherProps } = props;
-    return ((0, jsx_runtime_1.jsx)(CoreForm.Loading, { children: ({ isLoading }) => {
+    return ((0, jsx_runtime_1.jsx)(Form_1.Loading, { children: ({ isLoading }) => {
             if (!isLoading)
                 return null;
-            return ((0, jsx_runtime_1.jsx)(react_2.AsChildSlot, { ref: ref, asChild: asChild, className: className, "data-testid": "form-loading", customElement: children, content: "Loading form...", ...otherProps, children: (0, jsx_runtime_1.jsx)("div", { children: "Loading form..." }) }));
+            return ((0, jsx_runtime_1.jsx)(react_2.AsChildSlot, { "data-testid": TestIds.formLoading, ref: ref, asChild: asChild, className: className, customElement: children, content: "Loading form...", ...otherProps, children: (0, jsx_runtime_1.jsx)("div", { children: "Loading form..." }) }));
         } }));
 });
 /**
@@ -220,7 +221,7 @@ exports.Loading = react_1.default.forwardRef((props, ref) => {
  */
 exports.LoadingError = react_1.default.forwardRef((props, ref) => {
     const { asChild, children, className, ...otherProps } = props;
-    return ((0, jsx_runtime_1.jsx)(CoreForm.LoadingError, { children: ({ error, hasError }) => {
+    return ((0, jsx_runtime_1.jsx)(Form_1.LoadingError, { children: ({ error, hasError }) => {
             if (!hasError)
                 return null;
             const errorData = { error, hasError };
@@ -276,7 +277,7 @@ exports.LoadingError = react_1.default.forwardRef((props, ref) => {
  */
 exports.Error = react_1.default.forwardRef((props, ref) => {
     const { asChild, children, className, ...otherProps } = props;
-    return ((0, jsx_runtime_1.jsx)(CoreForm.Error, { children: ({ error, hasError }) => {
+    return ((0, jsx_runtime_1.jsx)(Form_1.Error, { children: ({ error, hasError }) => {
             if (!hasError)
                 return null;
             const errorData = { error, hasError };
@@ -332,7 +333,7 @@ exports.Error = react_1.default.forwardRef((props, ref) => {
  */
 exports.Submitted = react_1.default.forwardRef((props, ref) => {
     const { asChild, children, className, ...otherProps } = props;
-    return ((0, jsx_runtime_1.jsx)(CoreForm.Submitted, { children: ({ isSubmitted, message }) => {
+    return ((0, jsx_runtime_1.jsx)(Form_1.Submitted, { children: ({ isSubmitted, message }) => {
             if (!isSubmitted)
                 return null;
             const submittedData = { isSubmitted, message };
@@ -483,14 +484,7 @@ exports.Submitted = react_1.default.forwardRef((props, ref) => {
  * };
  * ```
  */
-exports.Fields = react_1.default.forwardRef(({ fieldMap }, ref) => {
-    const formService = (0, services_manager_react_1.useService)(form_service_1.FormServiceDefinition);
-    const form = formService.form.get();
-    const _form = {
-        ...form,
-        id: form?._id,
-        fields: form?.formFields?.map((field) => ({ ...field, id: field._id })),
-    };
+exports.Fields = react_1.default.forwardRef((props, ref) => {
     const [formValues, setFormValues] = (0, react_1.useState)({});
     const [formErrors, setFormErrors] = (0, react_1.useState)([]);
     const handleFormChange = (0, react_1.useCallback)((values) => {
@@ -499,72 +493,17 @@ exports.Fields = react_1.default.forwardRef(({ fieldMap }, ref) => {
     const handleFormValidate = (0, react_1.useCallback)((errors) => {
         setFormErrors(errors);
     }, []);
-    if (!form)
-        return (0, jsx_runtime_1.jsx)("div", { children: "Form not found, oops!" });
-    return ((0, jsx_runtime_1.jsx)("div", { ref: ref, children: (0, jsx_runtime_1.jsx)(form_public_1.Form, { form: _form, values: formValues, onChange: handleFormChange, errors: formErrors, onValidate: handleFormValidate, fields: fieldMap }) }));
+    return ((0, jsx_runtime_1.jsx)(Form_1.Fields, { children: ({ form }) => {
+            console.log('Fields form', form);
+            if (!form)
+                return null;
+            return ((0, jsx_runtime_1.jsx)("div", { ref: ref, children: (0, jsx_runtime_1.jsx)(form_public_1.Form, { form: {
+                        ...form,
+                        id: form?._id,
+                        fields: form?.formFields?.map((field) => ({
+                            ...field,
+                            id: field._id,
+                        })),
+                    }, values: formValues, onChange: handleFormChange, errors: formErrors, onValidate: handleFormValidate, fields: props.fieldMap }) }));
+        } }));
 });
-/**
- * Main Form namespace containing all form components following the compound component pattern.
- * Provides a headless, flexible way to render and manage forms with custom field components.
- *
- * @namespace Form
- * @property {typeof Root} Root - Form root component that provides service context to all child components
- * @property {typeof Loading} Loading - Form loading state component that displays content during form loading
- * @property {typeof LoadingError} LoadingError - Form loading error state component for handling form loading errors
- * @property {typeof Error} Error - Form submit error state component for handling form submission errors
- * @property {typeof Submitted} Submitted - Form submitted state component for displaying success messages
- * @property {typeof Fields} Fields - Form fields component for rendering form fields with custom field renderers
- * @example
- * ```tsx
- * import { Form } from '@wix/headless-forms/react';
- * import { loadFormServiceConfig } from '@wix/headless-forms/services';
- * import { TextInput, TextArea, Checkbox } from './field-components';
- *
- * const FIELD_MAP = {
- *   TEXT_INPUT: TextInput,
- *   TEXT_AREA: TextArea,
- *   CHECKBOX: Checkbox,
- *   // ... other field components
- * };
- *
- * // Pattern 1: Pre-loaded form data (SSR/SSG)
- * function MyForm({ formServiceConfig }) {
- *   return (
- *     <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.Error className="text-destructive p-4 rounded-lg mb-4" />
- *       <Form.Submitted className="text-green-500 p-4 rounded-lg mb-4" />
- *     </Form.Root>
- *   );
- * }
- *
- * // Pattern 2: Lazy loading with formId (Client-side)
- * function DynamicForm({ formId }) {
- *   return (
- *     <Form.Root formServiceConfig={{ formId }}>
- *       <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.Error className="text-destructive p-4 rounded-lg mb-4" />
- *       <Form.Submitted className="text-green-500 p-4 rounded-lg mb-4" />
- *     </Form.Root>
- *   );
- * }
- * ```
- */
-exports.Form = {
-    /** Form root component that provides service context */
-    Root: exports.Root,
-    /** Form loading state component */
-    Loading: exports.Loading,
-    /** Form loading error state component */
-    LoadingError: exports.LoadingError,
-    /** Form error state component */
-    Error: exports.Error,
-    /** Form submitted state component */
-    Submitted: exports.Submitted,
-    /** Form fields component for rendering form fields */
-    Fields: exports.Fields,
-};

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

@@ -1,4 +1,8 @@
+import { forms } from '@wix/forms';
 import { FormServiceConfig } from '../../services/form-service.js';
+/**
+ * Props for Root headless component
+ */
 export interface RootProps {
     children: React.ReactNode;
     formServiceConfig: FormServiceConfig;
@@ -9,8 +13,9 @@ export interface RootProps {
  *
  * @order 1
  * @component
- * @param {React.ReactNode} children - Child components that will have access to form context
- * @param {FormServiceConfig} formServiceConfig - Configuration object containing form data
+ * @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';
@@ -47,7 +52,7 @@ export interface RootProps {
  * }
  * ```
  */
-export declare function Root(props: RootProps): React.ReactNode;
+export declare function Root({ formServiceConfig, children, }: RootProps): React.ReactNode;
 /**
  * Props for FormLoading headless component
  */
@@ -213,3 +218,44 @@ export interface FormSubmittedRenderProps {
  * ```
  */
 export declare function Submitted(props: FormSubmittedProps): import("react").ReactNode;
+/**
+ * Render props for Fields component
+ */
+interface FieldsRenderProps {
+    form: forms.Form | null;
+}
+/**
+ * Props for Fields headless component
+ */
+interface FieldsProps {
+    children: (props: FieldsRenderProps) => React.ReactNode;
+}
+/**
+ * Fields component that provides form data to its children.
+ * This component accesses the form data from the service and passes it to children via render props.
+ *
+ * @component
+ * @param {FieldsProps} props - Component props
+ * @param {FieldsProps['children']} props.children - Render prop function that receives form data
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * function FormFields() {
+ *   return (
+ *     <Form.Fields>
+ *       {({ form }) => (
+ *         form ? (
+ *           <div>
+ *             <h2>{form.name}</h2>
+ *             <p>{form.description}</p>
+ *           </div>
+ *         ) : null
+ *       )}
+ *     </Form.Fields>
+ *   );
+ * }
+ * ```
+ */
+export declare function Fields(props: FieldsProps): import("react").ReactNode;
+export {};

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

@@ -5,10 +5,11 @@ exports.Loading = Loading;
 exports.LoadingError = LoadingError;
 exports.Error = Error;
 exports.Submitted = Submitted;
+exports.Fields = Fields;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const services_manager_react_1 = require("@wix/services-manager-react");
-const form_service_js_1 = require("../../services/form-service.js");
 const services_manager_1 = require("@wix/services-manager");
+const form_service_js_1 = require("../../services/form-service.js");
 const DEFAULT_SUCCESS_MESSAGE = 'Your form has been submitted successfully.';
 /**
  * Root component that provides the Form service context to its children.
@@ -16,8 +17,9 @@ const DEFAULT_SUCCESS_MESSAGE = 'Your form has been submitted successfully.';
  *
  * @order 1
  * @component
- * @param {React.ReactNode} children - Child components that will have access to form context
- * @param {FormServiceConfig} formServiceConfig - Configuration object containing form data
+ * @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';
@@ -54,8 +56,8 @@ const DEFAULT_SUCCESS_MESSAGE = 'Your form has been submitted successfully.';
  * }
  * ```
  */
-function Root(props) {
-    return ((0, jsx_runtime_1.jsx)(services_manager_react_1.WixServices, { servicesMap: (0, services_manager_1.createServicesMap)().addService(form_service_js_1.FormServiceDefinition, form_service_js_1.FormService, props.formServiceConfig), children: props.children }));
+function Root({ formServiceConfig, children, }) {
+    return ((0, jsx_runtime_1.jsx)(services_manager_react_1.WixServices, { servicesMap: (0, services_manager_1.createServicesMap)().addService(form_service_js_1.FormServiceDefinition, form_service_js_1.FormService, formServiceConfig), children: children }));
 }
 /**
  * Headless component for form loading state access
@@ -81,8 +83,8 @@ function Root(props) {
  * ```
  */
 function Loading(props) {
-    const service = (0, services_manager_react_1.useService)(form_service_js_1.FormServiceDefinition);
-    const isLoading = service.isLoading?.get() || false;
+    const { isLoadingSignal } = (0, services_manager_react_1.useService)(form_service_js_1.FormServiceDefinition);
+    const isLoading = isLoadingSignal.get();
     return props.children({
         isLoading,
     });
@@ -113,8 +115,8 @@ function Loading(props) {
  * ```
  */
 function LoadingError(props) {
-    const service = (0, services_manager_react_1.useService)(form_service_js_1.FormServiceDefinition);
-    const error = service.error?.get() || null;
+    const { errorSignal } = (0, services_manager_react_1.useService)(form_service_js_1.FormServiceDefinition);
+    const error = errorSignal.get();
     const hasError = !!error;
     return props.children({
         error,
@@ -147,10 +149,9 @@ function LoadingError(props) {
  * ```
  */
 function Error(props) {
-    const service = (0, services_manager_react_1.useService)(form_service_js_1.FormServiceDefinition);
-    const submitResponse = service.submitResponse?.get() || { type: 'idle' };
-    const error = submitResponse.type === 'error' ? submitResponse.message : null;
-    const hasError = submitResponse.type === 'error';
+    // TODO: Implement submit response handling when submitResponseSignal is added to service
+    const error = null;
+    const hasError = false;
     return props.children({
         error,
         hasError,
@@ -183,14 +184,45 @@ function Error(props) {
  * ```
  */
 function Submitted(props) {
-    const service = (0, services_manager_react_1.useService)(form_service_js_1.FormServiceDefinition);
-    const submitResponse = service.submitResponse?.get() || { type: 'idle' };
-    const isSubmitted = submitResponse.type === 'success';
-    const message = submitResponse.type === 'success'
-        ? submitResponse.message || DEFAULT_SUCCESS_MESSAGE
-        : DEFAULT_SUCCESS_MESSAGE;
+    // TODO: Implement submit response handling when submitResponseSignal is added to service
+    const isSubmitted = false;
+    const message = DEFAULT_SUCCESS_MESSAGE;
     return props.children({
         isSubmitted,
         message,
     });
 }
+/**
+ * Fields component that provides form data to its children.
+ * This component accesses the form data from the service and passes it to children via render props.
+ *
+ * @component
+ * @param {FieldsProps} props - Component props
+ * @param {FieldsProps['children']} props.children - Render prop function that receives form data
+ * @example
+ * ```tsx
+ * import { Form } from '@wix/headless-forms/react';
+ *
+ * function FormFields() {
+ *   return (
+ *     <Form.Fields>
+ *       {({ form }) => (
+ *         form ? (
+ *           <div>
+ *             <h2>{form.name}</h2>
+ *             <p>{form.description}</p>
+ *           </div>
+ *         ) : null
+ *       )}
+ *     </Form.Fields>
+ *   );
+ * }
+ * ```
+ */
+function Fields(props) {
+    const { formSignal } = (0, services_manager_react_1.useService)(form_service_js_1.FormServiceDefinition);
+    const form = formSignal.get();
+    return props.children({
+        form,
+    });
+}