@embeddables/forms 0.0.1

package/README.md

@@ -0,0 +1,122 @@
+# @embeddables/forms
+
+Schema-driven form state for Embeddables funnels. Composes on
+[`@embeddables/core`](https://www.npmjs.com/package/@embeddables/core) for
+identity; optionally accepts an analytics client on `initForms` to emit events
+on `.set()` and `.submit()`. When core resolves a publishable key, project id,
+and app user id, durable R2 writes run automatically on successful `.set()` and
+`.submit()` — best-effort and independent of analytics.
+
+## Install
+
+```bash
+npm install @embeddables/forms @embeddables/core
+```
+
+## Quick start
+
+```typescript
+import { initEmbeddables } from '@embeddables/core'
+import { initForms, type FormSchema } from '@embeddables/forms'
+
+const schema = {
+  id: 'signup',
+  name: 'Signup',
+  fields: [
+    {
+      key: 'email',
+      label: 'Email',
+      type: 'email',
+      validations: { required: true },
+    },
+  ],
+} as const satisfies FormSchema
+
+const core = initEmbeddables({
+  projectId: 'proj_…',
+  forms: [],
+  experiments: [],
+})
+
+const { initForm } = initForms({ core })
+const form = initForm({ schema })
+
+const result = await form.set({ email: 'maria@gmail.com' })
+if (!result.ok) console.log(result.errors)
+
+const email = form.get('email')
+await form.submit()
+```
+
+Use `as const satisfies FormSchema` on hand-authored schemas so field keys and
+value types flow into `.set()`, `.get()`, and `.getAll()`. CLI-generated schemas
+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`.
+
+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 `initForm`.
+
+## Form API
+
+| Method | Purpose |
+| ------ | ------- |
+| `set({ … })` | Validate and persist a patch atomically; optional analytics; best-effort durable R2 write when configured |
+| `get(key)` / `getAll()` | Read declared fields from storage |
+| `validate({ … })` | Check values without writing or tracking |
+| `submit()` | Validate all fields, best-effort durable R2 write, and emit `form:submitted` when analytics is configured |
+| `errors()` | Current validation messages |
+| `clear()` | Remove this form's stored values |
+
+`.set()` applies all keys in one call or writes nothing. Bind it to `change`,
+`blur`, or a step button — not per-keystroke `input`. `.submit()` is not
+idempotent; guard against double-clicks in your UI.
+
+Returned promises from `set`, `submit`, and `validate` never reject for
+validation failures — check `result.ok` and `result.errors` instead. Durable
+backend writes are also best-effort: a failing persistence request never rejects
+`.set()` or `.submit()`.
+
+## Options
+
+**`initForms`**
+
+| Option | Purpose |
+| ------ | ------- |
+| `core` | Initialized `@embeddables/core` instance (required) |
+| `analyticsInstance` | Optional analytics client for event tracking only |
+| `baseUrl` | Optional backend URL for durable R2 persistence writes |
+
+**`initForm`**
+
+| Option | Purpose |
+| ------ | ------- |
+| `schema` | Form definition (required) |
+| `customValidations` | Per-field validators; overrides inline `validations.custom` |
+
+## Analytics
+
+To track form events, install [`@embeddables/analytics`](https://www.npmjs.com/package/@embeddables/analytics) and pass `initAnalytics({ core })` as `analyticsInstance` on `initForms`.
+
+When `analyticsInstance` is provided, a successful `.set()` emits `data:updated`
+and one `field:updated` per changed field; `.submit()` emits `form:submitted`.
+Analytics failures surface as `trackError` on the result — local field values
+are still persisted. Omitting analytics disables event tracking only; durable
+R2 writes still occur when core resolves persistence configuration.
+
+## Errors
+
+| When | Error |
+| ---- | ----- |
+| Bad core at init | `FormsError` (thrown) |
+| Bad schema at init | `SchemaError` (thrown) |
+| Validation / bad patch | `{ ok: false, errors }` on the result |
+| Analytics failure | `trackError` on the result |
+
+All SDK errors extend `FormsError`. Custom validators that throw propagate
+synchronously from `.set()` and `.submit()`.