@embeddables/forms 0.0.1 → 0.0.3

package/README.md

@@ -13,6 +13,57 @@ and app user id, durable R2 writes run automatically on successful `.set()` and
 npm install @embeddables/forms @embeddables/core
 ```
 
+For React apps, also install `react` (peer dependency) and wrap your tree in
+`EmbeddablesProvider` from `@embeddables/core/react`. The React example below
+also imports `@embeddables/analytics/react`, so install `@embeddables/analytics`
+too if you want the auto-tracking shown there. If omitted, remove the
+`useAnalytics` import, hook call, and `analyticsInstance` option.
+
+## React
+
+Import hooks from `@embeddables/forms/react`:
+
+```tsx
+import { EmbeddablesProvider } from '@embeddables/core/react'
+import { useAnalytics } from '@embeddables/analytics/react'
+import { useForms, useForm, useFormField } from '@embeddables/forms/react'
+
+function SignupField() {
+  const analytics = useAnalytics()
+  useForms({ analyticsInstance: analytics ?? undefined })
+
+  const schema = {
+    id: 'signup',
+    fields: [{ key: 'email', label: 'Email', type: 'email', validations: { required: true } }],
+  } as const
+
+  const { form } = useForm(schema)
+  const { value, error, setValue, onBlur } = useFormField(form, 'email')
+
+  return (
+    <label>
+      Email
+      <input value={value ?? ''} onChange={(event) => setValue(event.target.value)} onBlur={() => void onBlur()} />
+      {error?.[0]}
+    </label>
+  )
+}
+
+export function App() {
+  return (
+    <EmbeddablesProvider config={{ projectId: 'proj_…', forms: [], experiments: [] }}>
+      <SignupField />
+    </EmbeddablesProvider>
+  )
+}
+```
+
+- `useForms` returns `null` until Core is ready inside `EmbeddablesProvider`.
+- Pass `analyticsInstance` explicitly when you want auto-tracking on `.set()` / `.submit()`. Do not also call `trackEvent` for the same submission or you will double-count `form:submitted`.
+- `useFormField` uses commit-on-blur: local typing updates draft state; `form.set()` runs on blur.
+- 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.
+
 ## Quick start
 
 ```typescript
@@ -68,6 +119,7 @@ functions, pass validators via `customValidations` on `initForm`.
 | ------ | ------- |
 | `set({ … })` | Validate and persist a patch atomically; optional analytics; best-effort durable R2 write when configured |
 | `get(key)` / `getAll()` | Read declared fields from storage |
+| `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 |
 | `errors()` | Current validation messages |
@@ -90,7 +142,6 @@ backend writes are also best-effort: a failing persistence request never rejects
 | ------ | ------- |
 | `core` | Initialized `@embeddables/core` instance (required) |
 | `analyticsInstance` | Optional analytics client for event tracking only |
-| `baseUrl` | Optional backend URL for durable R2 persistence writes |
 
 **`initForm`**