@wix/form-elements 0.0.0-stage → 1.54.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Wix.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# @wix/form-elements
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Wix Forms rendering element for Builder apps. `@wix/form-elements/Form` renders a form schema
+with the same engine the Forms app uses, and resolves language, currency, member context and
+submission on its own from the site's services.
+
+## How it reaches your site
+
+At runtime the Wix builder platform resolves `@wix/form-elements/Form` through an import map to the
+component the Forms app deploys. This package is what your project imports at development time: it
+carries the types, and a bundle that behaves like the deployed component in tests, Storybook and the
+builder sandbox.
+
+Declare the module as a component dependency so your build leaves the import to the platform:
+
+```ts
+resources: {
+  client: {
+    componentUrl,
+    dependencies: {
+      componentDependencies: ['@wix/form-elements/Form'],
+    },
+  },
+},
+```
+
+Install it as a dev dependency next to `react`, `react-dom` and `@wix/services-manager-react`,
+which the platform provides and this package expects from its host. Everything else the element
+needs from the public registry (the Wix SDK modules, react-aria, ajv and the like) is a regular
+dependency of this package; only Wix-internal packages are bundled.
+
+## Rendering a form
+
+```tsx
+import Form, {
+  type FormSchema,
+  type FormValues,
+  type ValidationError,
+} from '@wix/form-elements/Form';
+
+const Step = ({ form, compId }: { form: FormSchema; compId: string }) => {
+  const [values, setValues] = useState<FormValues>({});
+  const [errors, setErrors] = useState<ValidationError[]>([]);
+
+  return (
+    <Form
+      className="my-form"
+      form={form}
+      compId={compId}
+      values={values}
+      onChange={setValues}
+      errors={errors}
+      onValidate={setErrors}
+      onSubmitSuccess={(submission) => markComplete(submission)}
+    />
+  );
+};
+```
+
+Fetch the schema with the `@wix/forms` SDK and rename its `_id`-style keys with
+`renameKeysFromSDKRequestToRESTRequest` from `@wix/sdk-runtime/rename-all-nested-keys`; the element
+normalizes the layout itself.
+
+| Prop                                  | Purpose                                                                  |
+| ------------------------------------- | ------------------------------------------------------------------------ |
+| `form`                                | The schema to render. Without it the element shows a notice.             |
+| `values` / `onChange`                 | Controlled field values, keyed by field target.                          |
+| `errors` / `onValidate`               | Controlled validation state.                                             |
+| `stepId` / `onStepIdChange`           | Controlled multi-step navigation.                                        |
+| `onSubmit`                            | Fires when submission starts.                                            |
+| `onSubmitSuccess` / `onSubmitFailure` | The created submission, or the rejection.                                |
+| `compId`                              | Scopes field ids so two instances on a page do not collide.              |
+| `id` / `className`                    | On the element's wrapper, for layout and the editor selector.            |
+| `ref`                                 | `FormHandle`: `submit()`, `validate()`, `validateStep()`, `getValues()`. |
+
+The stylesheet is exported as `@wix/form-elements/Form/css`, following the
+`@wix/editor-react-components/<Name>/css` convention. It is for renders outside the Wix platform:
+Storybook, standalone pages and Site Export, which imports `<package>/<cssFile.path>` from a
+component's `moduleConfiguration`. Don't import it from component code: on a Wix site the platform
+loads the element's stylesheet itself, and the Wix CLI build would bundle a second copy into your
+component's CSS, since it only leaves `@wix/form-elements/Form` itself external.
+
+## What the package contains
+
+- `dist/component/form.js` and its lazy chunks: the pre-built element. Wix-internal packages are
+  bundled; packages on the public registry are imported from `dependencies`; `react`, `react-dom`
+  and `@wix/services-manager-react` come from the host. Stylesheets are always bundled, even when
+  they come from an external package such as `@wix/ricos`, so the JavaScript never imports CSS.
+- `dist/form.d.ts`: the public types, rolled into one file that imports only `react`.
+- `dist/component/form.css`.
+
+## Developing
+
+This package is a Wix CLI app. `yarn build` generates translation keys, typechecks, pre-builds the
+element into `dist/component`, builds the extension and rolls up the types. `yarn dev` serves the
+extension and rebuilds the pre-build on change.
+
+`yarn test` runs two Vitest projects. `unit` covers the source. `package` checks the built package
+in `dist/`, so it needs a build first; CI runs `test` after the build. It verifies that:
+
+- `dependencies` matches exactly what the bundle imports.
+- the bundle imports only peers and declared dependencies, that Node can load each of them without
+  a bundler, that none reaches a stylesheet through its own module graph, and that the types import
+  only `react`.
+- each chunk group stays within its gzipped limit in `.size-limit.json`, checked by size-limit.
+- the packed tarball passes publint and arethetypeswrong.
+- the tarball installs into a fresh Vitest project and renders, including a rich-text field that
+  loads `@wix/ricos` from that project's `node_modules`. It installs from Artifactory's mirror of
+  registry.npmjs.org, which serves only public packages, so it fails if anything internal is needed.
+  It takes a couple of minutes; `yarn test --project unit` skips the package checks.
+
+The dependency list is derived, not maintained by hand. The pre-build leaves every public package as
+a bare import, except the ones in `scripts/bundled-packages.mts`, which carry the reason they must
+stay inside the bundle. When form-fields or form-viewer start importing a new public package, the
+dependency test fails; run `node scripts/sync-dependencies.mts && yarn install` and commit the
+manifest change. If the new import cannot be loaded by Node (CSS, extension-less deep imports), the
+import test fails; add the package to `bundled-packages.mts` with its reason instead.
+
+See `src/form-fields/*/*.md` for the build and test integration notes.