@uniweb/api 1.2.0 → 1.2.2

package/README.md

@@ -244,6 +244,54 @@ the item.
 Its `absent` covers both not-found and not-permitted, on purpose: render your paywall
 or sign-in prompt on it and never say "deleted".
 
+### A Model's definition — what a form is built from
+
+```jsx
+import { useDefinition } from '@uniweb/api'
+
+const { status, definition } = useDefinition('@acme/cv')
+const brief = definition?.sections.find((s) => s.brief)
+// brief.fields → [{ key: 'title', kind: 'string', required: true, label: 'Title', max_length: 250 }, …]
+```
+
+Each field is its declaration as the backend stores it — `key`, `kind`, `required`,
+`multi`, and what the schema declares: `label`, `description`, `localized`, `format`,
+`max_length`, `min`, `max`, and `enum`. Each section is `{ name, path, kind, brief,
+fields, rules }`, plus its `label` and `description`; `path` is the name a write takes,
+`parent/child` for a nested section. ⭐ **These are the rules every write is checked
+against**, so a form that reads them checks what the backend will. `readDefinition({
+schema })` is the same outside React.
+
+### A field's choices
+
+A field that picks from a list — in a schema, `type: item_ref` with `options:` naming a
+section of a lists type — stores the uuid of the item chosen. Its choices are that
+section's items:
+
+```jsx
+import { useChoices } from '@uniweb/api'
+
+const { items, hasMore } = useChoices({ schema: '@acme/cv', field: 'country', q, searchIn: 'label' })
+// items[i].uuid — the value to store; items[i].data — the choice, in the site's language
+
+// a dependent list: the provinces of the country chosen above
+const provinces = useChoices(country ? { schema: '@acme/cv', field: 'province', parent: country } : null)
+```
+
+- **A page at a time** — `limit`, 50 by default and at most 1000; pass `nextCursor` back as
+  `cursor`. ⚠️ A searched page can be short while more follow: `hasMore` is the end, never
+  the page's length.
+- **A search** — `q` anywhere in the choices' field `searchIn`, ignoring case; a
+  localized field in the site's language.
+- **One level at a time** — `parent` reads the items under one item: the next level of a
+  list whose items nest (each says `has_children`), or a dependent field's choices under
+  the item chosen in the field it depends on.
+- **Whose lists** — the items of every entry of the lists type the viewer may read.
+- **Read back**, the field answers `{ item, brief }`: the chosen item's uuid and its data.
+
+`listChoices` is the same outside React, and `listSectionItems({ section })` reads a
+section by its uuid.
+
 ## Writing
 
 An entity's content is **items, each in a section** of its Model. A section that holds
@@ -297,6 +345,79 @@ Every failure is an `ApiError` with a `kind`: `auth` (sign in), `unverified`, `a
 (`error.extensions.field` names a field the Model refused), `conflict`, `rule`,
 `rate-limited`, `unavailable`, `disabled`. Branch on `kind`; `detail` is prose.
 
+## Rules, lists, and what stays in your foundation
+
+The backend checks every write against the Model's declaration, and refuses to register
+a schema with a declaration it does not take. So where a rule is written decides who
+keeps it.
+
+### On a field — checked on every write
+
+| declare | the backend |
+|---|---|
+| `required: true` | refuses a write without the field |
+| `max_length` on `string`, `text` | counts characters — each language of a localized value on its own |
+| `min`, `max` on `int`, `decimal` | refuses a value outside them |
+| `format` — `email`, `url` on `string` and `text`; `currency` on `string`; `markdown`, `html` on `text` | checks `email`, `url` and `currency` (an ISO 4217 code); `markdown` and `html` mark what the text is |
+| `localized: true` on text | holds one string for every language, or one per language |
+| `format: year-month` or `format: year` on `date` | holds a month, `2024-05`, or a year, `2024` — ISO 8601's reduced precision, stored as written (a backend from before 2026-10-14 refuses the declaration). With no `format`, a `date` holds a day, `2024-05-14` |
+| `enum: [...]` | keeps the field to those values — in the definition, as its section's `one_of` rule |
+| `type: item_ref`, `options: '@acme/lists/countries'` | keeps the value to an item of that section — an item of another is `409`, `kind: 'rule'` |
+
+A refused value is `kind: 'invalid'`, its `extensions` naming the field (`data.title`,
+`data.label.fr` for one language), the `rule` it broke and the bound
+(`{ rule: 'max_length', max_length: 250 }`, `{ rule: 'format', format: 'year-month' }`). An
+`enum`'s refusal, `rule: 'one_of'`, names its field too — a backend from before 2026-10-14
+names it only in `detail`.
+
+⛔ **A declaration the backend does not take refuses the whole schema** when it reaches
+the backend, naming the field and the key: a `format` its kind does not have (`month-day`
+on a `date`, `year` on an `int`), a key it does not know (`help`), or one it does not check
+yet (`pattern`, `min_length`).
+
+### On a section — rules across fields, and across items
+
+A section's `constraints` — a list of rules, in its definition as `rules`:
+
+| rule | keeps |
+|---|---|
+| `{ kind: 'exclusive', fields: [...] }` | at most one of the fields set — "another organization" beside a picked one |
+| `{ kind: 'required_one_of', fields: [...] }` | at least one of them set |
+| `{ kind: 'required_when', field, when: { field, equals } }` | the field set whenever another field equals a value |
+| `{ kind: 'field_order', before, after }` | one date no later than another |
+| `{ kind: 'unique_field', field }`, `{ kind: 'unique_combination', fields }` | a value — or values together — once among an entry's items in the section |
+| `{ kind: 'max_items', value }`, `{ kind: 'min_items', value }` | how many items the section holds — `min_items` refuses a delete below it, and does not make anyone add one |
+| `{ kind: 'show_when', field, when: { field, equals } }` | nothing: when a form shows a field — read it from the definition |
+
+### Shared lists
+
+Put the lists your fields pick from in **one lists type, a section per list** — not a
+type per list — and its entries where the people who should see them can read them.
+Then:
+
+- **A field that picks from one** is `type: item_ref` with `options:` naming its section
+  (`'@acme/lists/countries'`, a nested one by its path), and `useChoices` offers it.
+- **A list too long for a dropdown** is searched: `q` with `searchIn`, a page at a time.
+- **A dependent list** — a country, then one of its provinces — is a section nested in
+  the other: `countries` holding `subdivisions`, a field picking from each. The second
+  field's choices are `useChoices({ …, parent: country })`, and it holds only a province.
+- **A list in levels** — a discipline, then its branches — is a section whose items nest
+  (`self_nesting: true`): read it a level at a time with `parent`.
+- **A list people may add to** is one they may edit: who may write an entry's items is
+  who may edit the entry. They add a choice with `useEntityWriter` on the lists entry,
+  and `refresh()` reads the choices again.
+
+### What stays in your foundation
+
+The backend keeps content and checks it. How a field is edited is your foundation's — the
+toolbar of a rich text field, a default for a new entry, a field shown read-only, an
+autocomplete, a value computed from others (a currency converted, shares summed to 100
+before an entry is complete). None of these is a declaration the backend keeps.
+
+⭐ **Who may change a field is who may edit its entry** — the backend decides access per
+entry, never per field. A field only some people may change belongs on an entry only they
+edit.
+
 ## The service on your machine
 
 Building against a live service is slow and puts a shared database behind your
@@ -343,8 +464,10 @@ production, and nothing in your site's configuration changes between the two.
 
 ⭐ **The mock answers what the backend answers** — the same statuses, bodies and
 refusals, for every route this package uses. It enforces what your schemas declare —
-which sections are insert-only, the fields a section takes — and it is as strict as
-the backend about requests, so a mistake fails here rather than in front of a user.
+which sections are insert-only, the fields a section takes and their rules (`required`,
+`max_length`, `min` and `max`, a date's form, an `enum`, the `email` and `url` formats, a
+choice from a list) — and it is as strict as the backend about requests, so a mistake
+fails here rather than in front of a user.
 Everyone signed in reads and writes their own entities, and a member nothing of anyone
 else's (`memberFloor: 'read'` in the seed models a service set up to let members read
 each other's — or per Model, `memberFloor: { '@acme/course': 'read' }`, so the
@@ -361,6 +484,20 @@ from the start.
 The operator's Admin link answers too, landing on a page of the mock's own — the backend's
 administration is not part of it. State is in memory: restart to reset.
 
+Write a seed's schemas as you write them for a backend — `type: 'int'`, `multiple: true`,
+`options:` — and the mock's definition answers what a backend keeps of them, so a key no
+backend takes is left out of it (a backend refuses it when you register). Seed a list's
+choices as items of a lists entry, each item holding the items that sit under it:
+
+```js
+{ section: 'countries', data: { code: 'CA', label: { en: 'Canada' } }, items: [
+  { section: 'countries/subdivisions', data: { name: { en: 'Ontario' } } },
+] }
+```
+
+A field whose `options:` names no section of a seeded Model is reported when the mock
+starts, and offers no choices — a backend refuses to register it.
+
 There is also a standalone server, for a frontend that is not a Uniweb site — `--site`
 names that frontend's origin, where the mail's links land:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/api",
-  "version": "1.2.0",
+  "version": "1.2.2",
   "description": "The client for a Uniweb site's own backend — session, records, entities — imported by a foundation the way it imports @uniweb/kit.",
   "type": "module",
   "exports": {

package/src/client.js

@@ -15,7 +15,7 @@ import { getUniweb, deriveCacheKey } from '@uniweb/core'
 import { resolveService } from '@uniweb/core'
 import { ApiError } from './errors.js'
 import { composeUrl, isCrossOrigin, readBody, UNSAFE } from './http.js'
-import { AUTH, ROUTES, PARAM, FIELD, LIST, OP, GUARDED_OPS, CREATE, READ, SCHEMA, PAGE, TOTP, VIEWER } from './wire.js'
+import { AUTH, ROUTES, PARAM, FIELD, LIST, OP, GUARDED_OPS, CREATE, READ, SCHEMA, SECTION_ITEMS, PAGE, TOTP, VIEWER } from './wire.js'
 import { Ledger } from './ledger.js'
 import { verifyEmailWith, claimOfferWith } from './mailed-links.js'
 import { listInvitationsWith, acceptInvitationWith, declineInvitationWith } from './invitations.js'
@@ -141,6 +141,68 @@ function labelSections(items, sections) {
   }
 }
 
+/** The values a `one_of` rule allows — `values`, or the `options: [{ value, label }]` form's values. */
+function allowedValues(rule) {
+  if (Array.isArray(rule?.[SCHEMA.ruleValues])) return rule[SCHEMA.ruleValues]
+  if (Array.isArray(rule?.options)) return rule.options.map((o) => o?.value)
+  return []
+}
+
+/**
+ * A definition as a form reads it (`ApiClient.readDefinition`): each field its own
+ * declaration, its `enum` folded back from its section's `one_of` rule; each section
+ * with what the schema declares of it, its `path`, and its rules.
+ *
+ * @param {object} body - `GET /models/@scope/name`, as the backend answers it (`SCHEMA`)
+ */
+function formOf(body) {
+  const rows = Array.isArray(body?.[SCHEMA.sections]) ? body[SCHEMA.sections] : []
+  const byId = new Map(rows.map((s) => [s[SCHEMA.id], s]))
+  const pathOf = (row) => {
+    const names = []
+    const seen = new Set()
+    for (let at = row; at && !seen.has(at[SCHEMA.id]); at = byId.get(at[SCHEMA.parent])) {
+      seen.add(at[SCHEMA.id])
+      names.unshift(at[SCHEMA.name])
+    }
+    return names.join('/')
+  }
+  const sections = rows.map((row) => {
+    const declared = row?.[SCHEMA.constraints]?.[SCHEMA.rules]
+    const rules = Array.isArray(declared) ? declared : []
+    const enums = new Map(
+      rules
+        .filter((r) => r?.kind === SCHEMA.oneOf && typeof r[SCHEMA.ruleField] === 'string')
+        .map((r) => [r[SCHEMA.ruleField], allowedValues(r)]),
+    )
+    const fields = (Array.isArray(row?.[SCHEMA.fields]) ? row[SCHEMA.fields] : []).map((f) => {
+      const declaration = f?.[SCHEMA.fieldType]?.[SCHEMA.fieldDecl] ?? {}
+      const field = {
+        ...declaration,
+        key: f?.key ?? declaration.key,
+        kind: declaration.kind ?? f?.[SCHEMA.fieldType]?.kind,
+        required: f?.required === true || declaration.required === true,
+        multi: f?.multi === true || declaration.multi === true,
+      }
+      if (enums.has(field.key)) field.enum = enums.get(field.key)
+      return field
+    })
+    const other = row?.[SCHEMA.otherData]
+    return {
+      ...(other && typeof other === 'object' ? other : {}),
+      id: row[SCHEMA.id],
+      name: row[SCHEMA.name],
+      path: pathOf(row),
+      kind: row[SCHEMA.kind],
+      brief: row[SCHEMA.isBrief] === true,
+      parent: row[SCHEMA.parent] ?? null,
+      rules,
+      fields,
+    }
+  })
+  return { model: body?.model ?? null, sections }
+}
+
 export class ApiClient {
   /**
    * @param {object} uniweb - the page's `Uniweb` singleton
@@ -770,23 +832,182 @@ export class ApiClient {
    */
   sections(schema, signal) {
     if (!schema) return Promise.reject(ApiError.invalid('No Model', 'sections needs a schema'))
-    const held = this._schemas.get(schema)
-    if (held) return held
-    const pending = this.request('GET', ROUTES.schema(schema), { signal }).then((body) =>
+    return this._definition(schema, signal).then((body) =>
       (Array.isArray(body?.[SCHEMA.sections]) ? body[SCHEMA.sections] : []).map((s) => ({
         id: s[SCHEMA.id],
         name: s[SCHEMA.name],
         parent: s[SCHEMA.parent] ?? null,
       })),
     )
+  }
+
+  /** Drop a Model's kept definition, so the next read asks the backend again. */
+  forgetDefinition(schema) {
+    this._schemas.delete(schema)
+  }
+
+  /** The definition as the backend answers it — read once per viewer, and kept. */
+  _definition(schema, signal) {
+    const held = this._schemas.get(schema)
+    if (held) return held
+    const pending = this.request('GET', ROUTES.schema(schema), { signal })
     this._schemas.set(schema, pending)
-    // A failure is not kept: the next write asks again.
+    // A failure is not kept: the next read asks again.
     pending.catch(() => {
       if (this._schemas.get(schema) === pending) this._schemas.delete(schema)
     })
     return pending
   }
 
+  /**
+   * A Model's definition — what an editor builds a form from.
+   *
+   * ```js
+   * const { sections } = await readDefinition({ schema: '@acme/cv' })
+   * const brief = sections.find((s) => s.brief)
+   * // brief.fields → [{ key: 'title', kind: 'string', required: true, label: 'Title', max_length: 250 }, …]
+   * ```
+   *
+   * Each section is `{ id, name, path, kind, brief, parent, rules, fields }` plus what the
+   * schema declares of it — `label`, `description`, `append_only`, `allow_self_nesting`:
+   * `path` is the name a write takes (`parent/child` for a nested section), `parent` the
+   * parent section's id, `rules` its rules (`[]` with none). Each field is its declaration
+   * as the backend stores it — `key`, `kind`, `required`, `multi`, and what it declares:
+   * `label`, `description`, `localized`, `format`, `max_length`, `min`, `max` — with
+   * `enum`, the values its section's `one_of` rule allows, when it has one. A field of
+   * kind `item_ref` is a choice from a list: `section_uuid` names the section whose items
+   * are its choices (`listChoices`), and `entity_uuid` the entry that holds them, when the
+   * field pins one. `model` is the Model's row.
+   *
+   * ⭐ **These are the rules the backend applies to every write**, so a form that reads
+   * them checks what will be checked. What a form does with them — how a field is edited,
+   * what it shows — is the foundation's.
+   *
+   * Read once per viewer and kept. Signed out, the backend answers `401` (`auth`); an
+   * unknown Model is `absent`.
+   *
+   * @param {object} args
+   * @param {string} args.schema - the Model, e.g. `@acme/cv`
+   * @param {AbortSignal} [args.signal]
+   * @returns {Promise<{ model: object|null, sections: object[] }>}
+   */
+  async readDefinition({ schema, signal } = {}) {
+    if (!schema) throw ApiError.invalid('No Model', 'readDefinition needs a schema')
+    return formOf(await this._definition(schema, signal))
+  }
+
+  /**
+   * One page of a section's items — the choices an `item_ref` field offers, read by the
+   * section the field names (`section_uuid` on its declaration). `listChoices` finds
+   * that section for you from a field.
+   *
+   * Each item is `{ uuid, entity, parent?, data, has_children? }`: `uuid` is the value the
+   * field stores; `data` the item's content, in the site's language (`locale`, as every
+   * read); `parent` the item it sits under; `has_children` — for a list whose items nest
+   * — whether items sit under it.
+   *
+   * - **Whose items:** every entry of the section's Model the viewer may read, or only
+   *   `entity`'s.
+   * - **One level at a time:** without `parent`, the section's top level; with it, the
+   *   items under that item — the next level of a nesting list, or a dependent list's
+   *   choices under the item chosen in the field it depends on.
+   * - **A search:** `q` matched, ignoring case, anywhere in the section's field `field`
+   *   (a `string` or `text` field), in the site's language for a localized one.
+   * - **Paging:** pass `nextCursor` back as `cursor`. ⚠️ A searched page can be short
+   *   while more follow, so `hasMore` — a cursor came back — is the only end signal.
+   *
+   * @param {object} args
+   * @param {string} args.section - the section's uuid
+   * @param {string} [args.entity] - only this entry's items
+   * @param {string} [args.parent] - the uuid of the item whose children to read
+   * @param {string} [args.field] - the field `q` is matched in
+   * @param {string} [args.q] - the search term
+   * @param {string} [args.cursor] - the previous page's `nextCursor`
+   * @param {number} [args.limit] - default 50, at most 1000
+   * @param {AbortSignal} [args.signal]
+   * @returns {Promise<{ items: object[], nextCursor: string|null, hasMore: boolean }>}
+   */
+  async listSectionItems({ section, entity, parent, field, q, cursor, limit, signal } = {}) {
+    if (!section) throw ApiError.invalid('No Section', 'listSectionItems needs a section uuid')
+    const query = {
+      [PARAM.entity]: entity || undefined,
+      [PARAM.parent]: parent || undefined,
+      [PARAM.field]: field || undefined,
+      [PARAM.q]: q || undefined,
+      [PARAM.cursor]: cursor || undefined,
+      [PARAM.limit]: limit ?? PAGE.size,
+      ...this._localeQuery(),
+    }
+    const body = await this.request('GET', ROUTES.sectionItems(section), { query, signal })
+    const items = Array.isArray(body?.[SECTION_ITEMS.items]) ? body[SECTION_ITEMS.items] : []
+    const nextCursor = typeof body?.[SECTION_ITEMS.next] === 'string' ? body[SECTION_ITEMS.next] : null
+    return { items, nextCursor, hasMore: nextCursor != null }
+  }
+
+  /**
+   * The choices a field offers — the field's own list, read from the Model's definition.
+   *
+   * ```js
+   * const { items } = await listChoices({ schema: '@acme/cv', field: 'country', q: 'can', searchIn: 'label' })
+   * // items[i].uuid is the value to store in `country`
+   * const provinces = await listChoices({ schema: '@acme/cv', field: 'province', parent: country })
+   * ```
+   *
+   * `field` is a field of kind `item_ref` — in a schema, `type: item_ref` with
+   * `options: '@scope/lists/countries'` — and `section` names its section when several
+   * declare a field of that name. Everything else is `listSectionItems`'s: `parent` reads
+   * the items under an item, which is how a dependent list follows the field it depends
+   * on; `q` searches the choices' field `searchIn`.
+   *
+   * @param {object} args
+   * @param {string} args.schema - the Model whose field offers the choices
+   * @param {string} args.field - the field's key
+   * @param {string} [args.section] - the field's section, by name or path
+   * @param {string} [args.parent]
+   * @param {string} [args.q]
+   * @param {string} [args.searchIn] - the field of the choices `q` is matched in
+   * @param {string} [args.cursor]
+   * @param {number} [args.limit]
+   * @param {AbortSignal} [args.signal]
+   * @returns {Promise<{ items: object[], nextCursor: string|null, hasMore: boolean }>}
+   */
+  async listChoices({ schema, field, section, parent, q, searchIn, cursor, limit, signal } = {}) {
+    if (!schema) throw ApiError.invalid('No Model', 'listChoices needs the schema whose field offers the choices')
+    if (!field) throw ApiError.invalid('No Field', 'listChoices needs the field whose choices to list')
+    const { sections } = await this.readDefinition({ schema, signal })
+    const found = sections
+      .filter((s) => section == null || s.name === section || s.path === section)
+      .flatMap((s) => s.fields.filter((f) => f.key === field))
+    if (found.length !== 1) {
+      throw ApiError.invalid(
+        'Unknown Field',
+        found.length
+          ? `${schema} declares '${field}' in several sections — name the section`
+          : `${schema} has no field '${field}'${section != null ? ` in section '${section}'` : ''}`,
+      )
+    }
+    const [declared] = found
+    const pinned = declared[SCHEMA.choicesSection]
+    if (!pinned) {
+      throw ApiError.invalid(
+        'No Choices',
+        declared.kind === 'item_ref'
+          ? `'${field}' of ${schema} names no list its choices are in`
+          : `'${field}' of ${schema} is not a choice from a list — its kind is ${declared.kind}`,
+      )
+    }
+    return this.listSectionItems({
+      section: pinned,
+      entity: declared[SCHEMA.choicesEntity],
+      parent,
+      field: searchIn,
+      q,
+      cursor,
+      limit,
+      signal,
+    })
+  }
+
   /**
    * The numeric id of a section, by name — or by `parent/child` path for a nested
    * one — which is how the item route names a section.
@@ -1082,6 +1303,12 @@ export const declineInvitation = (id) => declineInvitationWith(required(), id)
 export const readEntity = (args) => required().readEntity(args)
 /** @see ApiClient#listEntities */
 export const listEntities = (args) => required().listEntities(args)
+
+export const readDefinition = (args) => required().readDefinition(args)
+
+export const listSectionItems = (args) => required().listSectionItems(args)
+
+export const listChoices = (args) => required().listChoices(args)
 /** @see ApiClient#writeItems */
 export const writeItems = (args) => required().writeItems(args)
 /** @see ApiClient#createEntity */

package/src/hooks/useChoices.js

@@ -0,0 +1,102 @@
+import { useCallback, useEffect, useState, useSyncExternalStore } from 'react'
+import { getClient } from '../client.js'
+
+const noSubscribe = () => () => {}
+const noSnapshot = () => null
+const NONE = Object.freeze([])
+
+/**
+ * The choices a field offers — a page of its list, for a dropdown or a type-ahead.
+ *
+ * ```jsx
+ * const [q, setQ] = useState('')
+ * const { status, items } = useChoices({ schema: '@acme/cv', field: 'country', q, searchIn: 'label' })
+ * // items[i].uuid is the value to store in `country`; items[i].data.label what to show
+ *
+ * // a dependent list: the provinces of the country chosen above
+ * const provinces = useChoices(country ? { schema: '@acme/cv', field: 'province', parent: country } : null)
+ * ```
+ *
+ * `field` is a field of kind `item_ref` (`options:` in a schema); `listChoices` says
+ * what each parameter does. A page is `limit` items (50 by default): pass `nextCursor`
+ * back as `cursor` for the next. ⚠️ A searched page can be short while more follow —
+ * `hasMore` is the end signal, never the page's length.
+ *
+ * `absent` — no `backend` service, or nobody signed in. Cached under a key scoped to the
+ * viewer; a list edited elsewhere is read again by `refresh`.
+ *
+ * @param {{ schema: string, field: string, section?: string, parent?: string, q?: string, searchIn?: string, cursor?: string, limit?: number } | null} query
+ *   pass null to skip
+ * @returns {{ status: string, items: object[], nextCursor: string|null, hasMore: boolean, error: Error|null, refresh: Function }}
+ */
+export function useChoices(query) {
+  const client = getClient()
+  const store = client?.website?.dataStore ?? null
+
+  const session = useSyncExternalStore(
+    client ? client.subscribe : noSubscribe,
+    client ? () => client.session : noSnapshot,
+    client ? () => client.session : noSnapshot,
+  )
+
+  const active = !!(
+    client &&
+    client.enabled &&
+    store &&
+    query &&
+    query.schema &&
+    query.field &&
+    session?.status !== 'anonymous'
+  )
+  const spec = active
+    ? {
+        endpoint: '/sections',
+        schema: query.schema,
+        field: query.field,
+        section: query.section,
+        parent: query.parent,
+        q: query.q || undefined,
+        searchIn: query.searchIn,
+        cursor: query.cursor,
+        limit: query.limit,
+      }
+    : null
+  const key = spec ? client.cacheKey(spec) : null
+
+  const subscribe = useCallback((fn) => (key ? store.subscribe(key, fn) : noSubscribe()), [store, key])
+  const entry = useSyncExternalStore(
+    subscribe,
+    () => (key ? store.get(key) : null),
+    () => (key ? store.get(key) : null),
+  )
+
+  const [error, setError] = useState(null)
+  const [attempt, setAttempt] = useState(0)
+
+  useEffect(() => {
+    if (!key || entry) return undefined
+    let live = true
+    setError(null)
+    client.load(key, () => client.listChoices(query), spec).catch((err) => {
+      if (live) setError(err)
+    })
+    return () => {
+      live = false
+    }
+    // `query` is read through `key`, which encodes every part of it.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [client, key, entry, attempt])
+
+  const refresh = useCallback(() => {
+    if (key && store) store.delete(key)
+    setAttempt((n) => n + 1)
+  }, [store, key])
+
+  const empty = { items: NONE, nextCursor: null, hasMore: false }
+  if (!active) return { status: 'absent', ...empty, error: null, refresh }
+  if (entry) return { status: 'ready', ...entry.data, error: null, refresh }
+  if (error) return { status: 'error', ...empty, error, refresh }
+  return { status: 'loading', ...empty, error: null, refresh }
+}
+
+export default useChoices

package/src/hooks/useDefinition.js

@@ -0,0 +1,78 @@
+import { useCallback, useEffect, useState, useSyncExternalStore } from 'react'
+import { getClient } from '../client.js'
+
+const noSubscribe = () => () => {}
+const noSnapshot = () => null
+
+/**
+ * A Model's definition — the sections and fields a form is built from.
+ *
+ * ```jsx
+ * const { status, definition } = useDefinition('@acme/cv')
+ * if (status !== 'ready') return null
+ * const brief = definition.sections.find((s) => s.brief)
+ * // brief.fields → [{ key: 'title', kind: 'string', required: true, max_length: 250 }, …]
+ * ```
+ *
+ * Each field is its declaration as the backend stores it, with `enum` folded in from its
+ * section's rules (`readDefinition`). The rules a definition states are the rules every
+ * write is checked against.
+ *
+ * `absent` — no `backend` service, or nobody signed in: a definition is read by someone
+ * signed in. Cached under a key scoped to the viewer.
+ *
+ * @param {string|null} schema - the Model, e.g. `@acme/cv`; null to skip
+ * @returns {{ status: string, definition: object|null, error: Error|null, refresh: Function }}
+ */
+export function useDefinition(schema) {
+  const client = getClient()
+  const store = client?.website?.dataStore ?? null
+
+  const session = useSyncExternalStore(
+    client ? client.subscribe : noSubscribe,
+    client ? () => client.session : noSnapshot,
+    client ? () => client.session : noSnapshot,
+  )
+
+  const active = !!(client && client.enabled && store && schema && session?.status !== 'anonymous')
+  const spec = active ? { endpoint: '/models', schema } : null
+  const key = spec ? client.cacheKey(spec) : null
+
+  const subscribe = useCallback((fn) => (key ? store.subscribe(key, fn) : noSubscribe()), [store, key])
+  const entry = useSyncExternalStore(
+    subscribe,
+    () => (key ? store.get(key) : null),
+    () => (key ? store.get(key) : null),
+  )
+
+  const [error, setError] = useState(null)
+  const [attempt, setAttempt] = useState(0)
+
+  useEffect(() => {
+    if (!key || entry) return undefined
+    let live = true
+    setError(null)
+    client.load(key, () => client.readDefinition({ schema }), spec).catch((err) => {
+      if (live) setError(err)
+    })
+    return () => {
+      live = false
+    }
+    // `schema` is read through `key`, which encodes it.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [client, key, entry, attempt])
+
+  const refresh = useCallback(() => {
+    if (key && store) store.delete(key)
+    // The client keeps the definition too; a refresh reads it from the backend again.
+    if (schema) client?.forgetDefinition(schema)
+    setAttempt((n) => n + 1)
+  }, [store, key, client, schema])
+
+  if (!active) return { status: 'absent', definition: null, error: null, refresh }
+  if (entry) return { status: 'ready', definition: entry.data, error: null, refresh }
+  if (error) return { status: 'error', definition: null, error, refresh }
+  return { status: 'loading', definition: null, error: null, refresh }
+}
+
+export default useDefinition

package/src/index.js

@@ -35,6 +35,9 @@ export {
   forgetMailedLink,
   readEntity,
   listEntities,
+  readDefinition,
+  listSectionItems,
+  listChoices,
   writeItems,
   createEntity,
   deleteEntity,
@@ -52,5 +55,7 @@ export { useMailedLink } from './hooks/useMailedLink.js'
 export { useInvitations } from './hooks/useInvitations.js'
 export { useEntity } from './hooks/useEntity.js'
 export { useRecords } from './hooks/useRecords.js'
+export { useDefinition } from './hooks/useDefinition.js'
+export { useChoices } from './hooks/useChoices.js'
 export { useEntityWriter } from './hooks/useEntityWriter.js'
 export { SignedIn, SignedOut } from './components/gates.js'