@embeddables/forms 0.0.1 → 0.0.2

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