@embeddables/forms 0.0.4 → 0.2.0

package/README.md

@@ -14,8 +14,9 @@ npm install @embeddables/forms @embeddables/core
 ```
 
 For React apps, also install `react` (peer dependency) and wrap your tree in
-`EmbeddablesProvider` from `@embeddables/core/react`. Register forms through the
-provider's `modules` prop.
+`EmbeddablesProvider` from `@embeddables/core/react`. Register the static module
+through `modules`, then pass its runtime configuration through the provider's
+top-level `forms` prop.
 
 ## React
 
@@ -29,13 +30,6 @@ import { analytics } from '@embeddables/analytics/react'
 import { forms, useForm, useFormField } from '@embeddables/forms/react'
 import { config } from './embeddables/_dist/config.ts'
 
-const schemas = {
-  signup: {
-    id: 'signup',
-    fields: [{ key: 'email', label: 'Email', type: 'email', validations: { required: true } }],
-  },
-} as const
-
 function SignupField() {
   // No type arguments: the id narrows the form, and the schema map comes from
   // the registry `em build` writes into embeddables/_dist/register.ts.
@@ -55,11 +49,21 @@ export function App() {
   return (
     <EmbeddablesProvider
       config={config}
-      modules={[
-        analytics(),
-        // auto-wires analytics from Core when analytics() ran first
-        forms({ schemas }),
-      ]}
+      modules={[forms(), analytics()]}
+      forms={{
+        customValidations: [
+          {
+            formId: 'signup',
+            customValidations: {
+              // Return a message to fail, or null to pass.
+              email: ({ value }) =>
+                typeof value === 'string' && value.endsWith('@example.com')
+                  ? 'example.com addresses are not accepted.'
+                  : null,
+            },
+          },
+        ],
+      }}
     >
       <SignupField />
     </EmbeddablesProvider>
@@ -67,10 +71,17 @@ export function App() {
 }
 ```
 
-- `forms({ schemas, analyticsInstance? })` returns an `EmbeddablesReactModule`. When `analytics()` initialized
-  the same Core instance first, Forms auto-wires `core.getAnalyticsInstance()` — override
-  with `analyticsInstance` on the factory if needed.
-- `useFormField` uses commit-on-blur: local typing updates draft state; `form.set()` runs on blur.
+- `customValidations` and `serverFormData` go on the provider's `forms` prop.
+- Form schemas come from Core (`config.forms`, populated by `em build`) — they are not
+  passed to the provider.
+- A custom validator receives `{ value, values }` and returns a message to fail or
+  `null` to pass. `values` is the whole form, so a validator can read sibling fields.
+- When `analytics()` is enabled, form events are tracked automatically — the order of
+  `modules` does not matter. Add `'forms'` to `excludeAnalyticsInModules` to turn that off.
+- `useFormField` gives you two ways to write. `setValue` + `onBlur` is commit-on-blur, for
+  text inputs: typing updates local state and `form.set()` runs on blur. `commit(value)`
+  writes immediately, for controls with no meaningful blur — `select`, checkboxes, radios.
+- `form.set({ field: undefined })` clears one field; `form.clear()` clears the whole form.
 - One live `FormInstance` per `schema.id` is shared across hooks in the same client.
 - Imperative consumers can also call `form.subscribe(listener)` to observe value and error changes.
 
@@ -95,11 +106,11 @@ const schema = {
 
 const core = initEmbeddables({
   projectId: 'proj_…',
-  forms: [],
+  forms: { [schema.id]: schema },
   experiments: [],
 })
 
-const { getForm } = initForms({ core, schemas: { signup: schema } })
+const { getForm } = initForms({ core })
 const form = getForm({ formId: 'signup' })
 
 const result = await form.set({ email: 'maria@gmail.com' })
@@ -119,9 +130,25 @@ Each form is one object: `id`, optional `name`, and `fields`. Supported field
 types: `text`, `email`, `number`, `boolean`, `select`, `multiselect`, `json`.
 
 Declarative rules: `required`, `minLength`, `maxLength`, `min`, `max`,
-`pattern`, `patternFlags`, `oneOf`, and optional synchronous `validations.custom`.
-Use string patterns, not `RegExp` objects. For YAML/JSON schemas without inline
-functions, pass validators via `customValidations` on `getForm`.
+`pattern`, `oneOf`, and optional synchronous `validations.custom`.
+
+A `select` or `multiselect` field declares its choices in a field-level `options`
+array of `{ value, label?, exclusive? }`, and the field's `type` — not the name of
+a rule — decides whether one or many of them may be selected. An option marked
+`exclusive` on a `multiselect` cannot coexist with any other value: selecting it
+clears the rest, and selecting a regular option afterwards clears it. Those two
+types no longer accept `validations.oneOf`, which stays available on every other
+field type. `em build` migrates it with a warning, carrying across the unique
+non-empty string entries and dropping the rest — an entry that is not a string
+could never have matched a stored value — so a field whose entries are all
+unusable keeps no constraint at all. A schema that reaches `initForms` still
+carrying `oneOf` on either type throws a `SchemaError`.
+
+Use string patterns, not `RegExp` objects. Regex flags go in an optional leading
+`(?flags)` prefix inside `pattern` — `(?u)^\p{L}+$` — using any of `dgimsuvy`;
+`g` and `y` are stripped before compilation. For YAML/JSON schemas without inline
+functions, pass validators via `customValidations: [{ formId, customValidations }]`
+on `initForms` / `forms()`.
 
 ## Form API
 
@@ -150,22 +177,43 @@ backend writes are also best-effort: a failing persistence request never rejects
 
 | Option | Purpose |
 | ------ | ------- |
-| `core` | Initialized `@embeddables/core` instance (required) |
-| `schemas` | Every form the app can open, keyed by form id (required). Each schema's own `id` must equal its key — `embeddables/_dist` already exports this shape as `forms` |
+| `core` | Initialized `@embeddables/core` instance with form schemas in `forms` (required) |
+| `customValidations` | Optional `{ formId, customValidations }[]` for schemas that need runtime validators |
+| `serverFormData` | Optional `{ formId, serverFormData }[]`; SSR hydration overrides localStorage on overlapping keys |
 | `analyticsInstance` | Optional analytics client for event tracking only |
 
-**`getForm({ formId, customValidations? })`**
+**`getForm({ formId })`**
 
 | Argument | Purpose |
 | ------ | ------- |
-| `formId` | Key of a schema declared on `initForms` (required); an unknown id throws `FormsError` |
-| `customValidations` | Per-field validators; overrides inline `validations.custom` |
+| `formId` | Id of a schema registered on Core (required); an unknown id throws `FormsError` |
 
 `getForm` returns **one instance per form id**: the first call builds it, every
 later call returns that same one, so two handles can never race each other for
-the same storage entry. `customValidations` belong to the first call — a later
-call that passes different validators gets the instance that already exists.
-The cache lives on the client, so hold one client per app.
+the same storage entry. The cache lives on the client, so hold one client per app.
+
+## Server (`@embeddables/forms/server`)
+
+```typescript
+import { initEmbeddablesServer } from '@embeddables/core/server'
+import { initFormsServer } from '@embeddables/forms/server'
+import { schema as signupSchema } from './embeddables/_dist/forms/<form-id>/schema.js'
+
+const server = initEmbeddablesServer({
+  projectId: '…',
+  forms: { [signupSchema.id]: signupSchema },
+  experiments: [],
+})
+const forms = initFormsServer({ server })
+
+await forms.getForm({ formId: signupSchema.id }).set({ email: 'maria@gmail.com' })
+const serverFormData = forms.getServerFormData()
+// Pass serverFormData into client initForms({ serverFormData: [{ formId: signupSchema.id, serverFormData: serverFormData[signupSchema.id] }] })
+```
+
+Server form instances expose `set`, `get`, `getAll`, and
+`getValueByProtocolFieldId` only. Storage is in-memory; nothing is written to
+`localStorage` or durable backends.
 
 ## Analytics