@embeddables/forms 0.0.5 → 0.2.1

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
 
@@ -26,16 +27,9 @@ Example:
 ```tsx
 import { EmbeddablesProvider } from '@embeddables/core/react'
 import { analytics } from '@embeddables/analytics/react'
-import { forms, useForm, useFormField } from '@embeddables/forms/react'
+import { forms, useForm, useFormField, useFormFileUpload } 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,13 +71,49 @@ 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.
 
+### File inputs
+
+For `type: file` fields, use `useFormFileUpload`. It uploads through the publishable-key API, commits the returned `FormFileRef`, and exposes `inputProps` for a native `<input type="file">`.
+
+Example:
+
+```tsx
+function IdPhotoField() {
+  const { form } = useForm({ formId: 'intake' })
+  const { value, error, isLoading, uploadError, inputProps } = useFormFileUpload({
+    form,
+    key: 'id_photo',
+  })
+
+  return (
+    <label>
+      ID photo
+      <input {...inputProps} accept="image/jpeg,image/png" />
+      {isLoading && <span>Uploading…</span>}
+      {uploadError && <span>{uploadError}</span>}
+      {error?.[0]}
+      {value?.name && <span>{value.name}</span>}
+    </label>
+  )
+}
+```
+
+Imperative equivalent: `const ref = await form.uploadFile({ key: 'id_photo', file })` then `await form.set({ id_photo: ref })`.
+
 ## Quick start
 
 ```typescript
@@ -95,11 +135,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' })
@@ -116,12 +156,33 @@ from `embeddables/_dist` are already typed.
 ## Schema
 
 Each form is one object: `id`, optional `name`, and `fields`. Supported field
-types: `text`, `email`, `number`, `boolean`, `select`, `multiselect`, `json`.
+types: `text`, `email`, `number`, `boolean`, `select`, `multiselect`, `json`,
+`file`.
 
 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`. File fields
+also accept `validations.accept` (MIME list) and `validations.maxSize` (bytes).
+Compatible field types may declare `protocolFieldId` to link a form field to a
+protocol question. `json` fields cannot. `FormFileRef` is exported for typed
+file values.
+
+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
 
@@ -132,6 +193,7 @@ functions, pass validators via `customValidations` on `getForm`.
 | `getValueByProtocolFieldId(protocolFieldId)` | Read by schema `protocolFieldId` (typed like `get()` for the backing field; `undefined` if unknown or unset) |
 | `validate({ … })` | Check values without writing or tracking |
 | `submit()` | Validate all fields, best-effort durable R2 write, and emit `form:submitted` when analytics is configured |
+| `uploadFile({ key, file, fileName? })` | Upload bytes for a `type: file` field; returns `FormFileRef` (caller commits with `.set()`) |
 | `errors()` | Current validation messages |
 | `clear()` | Remove this form's stored values |
 
@@ -150,22 +212,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