@embeddables/forms 0.2.0 → 0.3.0

package/README.md

@@ -27,7 +27,7 @@ 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'
 
 function SignupField() {
@@ -85,6 +85,35 @@ export function App() {
 - 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 `value_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
@@ -98,7 +127,8 @@ const schema = {
     {
       key: 'email',
       label: 'Email',
-      type: 'email',
+      value_type: 'email',
+      field_type: 'user_input',
       validations: { required: true },
     },
   ],
@@ -126,15 +156,32 @@ 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`.
+Each form is one object: `id`, optional `name`, and `fields`. Each field has a
+`value_type` (`text`, `email`, `number`, `boolean`, `select`, `multiselect`,
+`json`, `file`).
+
+Use `getFieldByKey(fieldKey)` for presentation metadata (`display_text`,
+`display_description`, option `display_text`, `field_type`) instead of
+duplicating copy in markup. `local_only` values still persist but are omitted
+from `data:updated` / `field:updated` analytics patches.
+
+```ts
+const plan = form.getFieldByKey('plan')
+plan?.display_text
+plan?.options?.[0]?.display_text
+```
 
 Declarative rules: `required`, `minLength`, `maxLength`, `min`, `max`,
-`pattern`, `oneOf`, and optional synchronous `validations.custom`.
+`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
+array of `{ key, display_text, display_description?, exclusive? }`. The field's
+`value_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
@@ -156,9 +203,11 @@ on `initForms` / `forms()`.
 | ------ | ------- |
 | `set({ … })` | Validate and persist a patch atomically; optional analytics; best-effort durable R2 write when configured |
 | `get(key)` / `getAll()` | Read declared fields from storage |
+| `getFieldByKey(key)` | Read resolved schema metadata for one declared field |
 | `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 `value_type: file` field; returns `FormFileRef` (caller commits with `.set()`) |
 | `errors()` | Current validation messages |
 | `clear()` | Remove this form's stored values |