@aircloudhq/web 1.0.0

package/src/model.js

@@ -0,0 +1,38 @@
+// ActiveModel::Naming and ActiveModel::Translation for a projection resource (spec S4 § @aircloudhq/web
+// public modules): the `activemodel.*` key of the current locale (and its declared fallbacks) when it
+// exists, else the projection's `display_name` — the default-locale name, whose one carrier is
+// db/schema/. No inflector is involved (ADR-213 D2).
+import { i18nFor } from './i18n/current.js';
+
+function fieldOf(resource, name) {
+  const f = resource.fields.find((x) => x.name === name);
+  if (!f) throw new Error(`resource "${resource.entity}" has no field "${name}"`);
+  return f;
+}
+
+/** Model.model_name.human — `modelName(resource).human({count})`. */
+export function modelName(resource, options = {}) {
+  const i18n = i18nFor(options);
+  return {
+    singular: resource.entity,
+    param_key: resource.entity,
+    route_key: resource.route_prefix,
+    human({ count } = {}) {
+      const v = i18n?.lookupDeclared(`activemodel.models.${resource.entity}`);
+      if (typeof v === 'string') return v;
+      if (v && typeof v === 'object') {
+        const one = count === undefined || count === 1 || /^1(\.0+)?$/.test(String(count));
+        const pick = one ? v.one ?? v.other : v.other ?? v.one;
+        if (typeof pick === 'string') return pick;
+      }
+      return resource.display_name;
+    },
+  };
+}
+
+/** Model.human_attribute_name(:field) */
+export function humanAttributeName(resource, field, options = {}) {
+  const f = fieldOf(resource, field);
+  const v = i18nFor(options)?.lookupDeclared(`activemodel.attributes.${resource.entity}.${field}`);
+  return typeof v === 'string' ? v : f.display_name;
+}

package/src/react/form.js

@@ -0,0 +1,167 @@
+// FormWith (form_with over the framework-neutral form model), the field component of each Flex type,
+// and ErrorMessages (the platform error code's message, `errors.codes.<code>`, and the fields' full
+// messages). Every visible string is a translation: labels are human attribute names, the submit label
+// is helpers.submit.*, the relation prompt helpers.select.prompt.
+import { createContext, createElement as h, useContext, useEffect, useMemo, useState, useSyncExternalStore } from 'react';
+import { createForm, fullMessage, submitLabel } from '../helpers/form.js';
+import { humanAttributeName } from '../model.js';
+import { api } from '../api.js';
+import { recordLabel } from '../resource.js';
+import { useI18n } from './i18n.js';
+import { useSite } from './router.js';
+
+const FormContext = createContext(null);
+
+function useFormState(form) {
+  return useSyncExternalStore(form.subscribe, form.getState, form.getState);
+}
+
+/** The form model and its state inside a FormWith. */
+export function useForm() {
+  const f = useContext(FormContext);
+  if (!f) throw new Error('a field component renders inside <FormWith>');
+  return f;
+}
+
+function Field({ name, children, input }) {
+  const { form, state } = useForm();
+  const i18n = useI18n();
+  const errors = state.errors[name] ?? [];
+  return h(
+    'div',
+    { className: errors.length ? 'field field_with_errors' : 'field' },
+    h('label', { htmlFor: `${form.resource.entity}_${name}` }, humanAttributeName(form.resource, name, { i18n })),
+    input,
+    errors.length ? h('p', { className: 'field-error', role: 'alert' }, errors.join(', ')) : null,
+    children,
+  );
+}
+
+function inputProps(name, type) {
+  const { form, state } = useForm();
+  const field = form.fields.find((f) => f.name === name);
+  if (!field) throw new Error(`resource "${form.resource.entity}" has no field "${name}"`);
+  return {
+    id: `${form.resource.entity}_${name}`,
+    name,
+    required: field.required,
+    value: state.values[name],
+    onChange: (e) => form.set(name, e.target.value),
+    type,
+    'aria-invalid': (state.errors[name] ?? []).length ? 'true' : undefined,
+  };
+}
+
+const typed = (type, extra = {}) =>
+  function TypedField({ name }) {
+    return h(Field, { name, input: h('input', { ...inputProps(name, type), ...extra }) });
+  };
+
+export const TextField = typed('text');
+export const IntegerField = typed('number', { step: 1 });
+export const DecimalField = typed('text', { inputMode: 'decimal' });
+export const DateField = typed('date');
+export const DateTimeField = typed('datetime-local');
+export const FileField = typed('text');
+
+export function BooleanField({ name }) {
+  const { form, state } = useForm();
+  return h(Field, {
+    name,
+    input: h('input', {
+      id: `${form.resource.entity}_${name}`,
+      name,
+      type: 'checkbox',
+      checked: Boolean(state.values[name]),
+      onChange: (e) => form.set(name, e.target.checked),
+    }),
+  });
+}
+
+export function JsonField({ name }) {
+  return h(Field, { name, input: h('textarea', inputProps(name, undefined)) });
+}
+
+export const VectorField = JsonField;
+
+/** A relation: a select over the target resource's records (their label field). */
+export function RelationField({ name }) {
+  const { form } = useForm();
+  const i18n = useI18n();
+  const { projection } = useSite();
+  const field = form.fields.find((f) => f.name === name);
+  const [options, setOptions] = useState([]);
+  const prefix = field?.relation?.target_prefix;
+  const target = field?.relation ? projection?.resources?.[field.relation.target] : undefined;
+  useEffect(() => {
+    if (!prefix) return;
+    api('GET', `${prefix}?limit=200`).then((r) => setOptions(r?.records ?? []), () => setOptions([]));
+  }, [prefix]);
+  const props = inputProps(name, undefined);
+  delete props.type;
+  return h(Field, {
+    name,
+    input: h(
+      'select',
+      props,
+      h('option', { value: '' }, i18n.t('helpers.select.prompt')),
+      options.map((r) => h('option', { key: r.id, value: r.id }, target ? recordLabel(target, r) : r.id)),
+    ),
+  });
+}
+
+/** The field component of a Flex type. */
+export function fieldFor(type) {
+  return (
+    {
+      text: TextField, integer: IntegerField, decimal: DecimalField, boolean: BooleanField, date: DateField,
+      datetime: DateTimeField, json: JsonField, vector: VectorField, relation: RelationField, file: FileField,
+    }[type] ?? TextField
+  );
+}
+
+/**
+ * <FormWith resource={pet} record={record} onSubmit={(payload, form) => …} fields={{name: MyInput}}>
+ * — without children it renders every field of the projection, then the submit button.
+ */
+export function FormWith({ resource, record, form: given, onSubmit, fields = {}, children, className = 'form' }) {
+  const i18n = useI18n();
+  const form = useMemo(() => given ?? createForm(resource, { record, i18n }), [given, resource, record, i18n]);
+  const state = useFormState(form);
+  const value = useMemo(() => ({ form, state }), [form, state]);
+  function submit(event) {
+    event.preventDefault();
+    form.submit(onSubmit ?? (() => undefined));
+  }
+  const body =
+    children ??
+    h(
+      'div',
+      null,
+      form.fields.map((f) => h(fields[f.name] ?? fieldFor(f.type), { key: f.name, name: f.name })),
+      h('button', { type: 'submit', disabled: state.status === 'submitting' }, submitLabel(form.resource, form.id !== undefined, { i18n })),
+    );
+  return h(
+    FormContext.Provider,
+    { value },
+    h('form', { className, onSubmit: submit, noValidate: true }, h(ErrorMessages, { error: state.base[0], resource: form.resource, errors: state.errors }), body),
+  );
+}
+
+/**
+ * <ErrorMessages error={apiError} /> — the platform code's message (`errors.codes.<code>`, spec S4 §
+ * Locale files) and, with `resource` and `errors`, each field's full message.
+ */
+export function ErrorMessages({ error, resource, errors = {} }) {
+  const i18n = useI18n();
+  const fieldMessages = resource
+    ? Object.entries(errors).flatMap(([field, list]) => list.map((m) => fullMessage(resource, field, m, { i18n })))
+    : [];
+  if (!error && fieldMessages.length === 0) return null;
+  return h(
+    'div',
+    { className: 'error-messages', role: 'alert' },
+    error ? h('p', null, i18n.t(`errors.codes.${error.code}`)) : null,
+    fieldMessages.length ? h('ul', null, fieldMessages.map((m) => h('li', { key: m }, m))) : null,
+  );
+}

package/src/react/i18n.js

@@ -0,0 +1,52 @@
+// I18nProvider: negotiates the page's locale (spec S4 § Locale negotiation — the `locale` parameter,
+// the #632 preference hook, navigator.languages by RFC 4647 lookup, the default), binds the i18n
+// instance the helpers render with, and wires the run-time missing-key reporter to
+// POST /_air/i18n-missing (bounded per key per page load).
+import { createContext, createElement as h, useContext, useMemo } from 'react';
+import { createI18n, createMissingReporter, negotiateLocale } from '../i18n/index.js';
+import { setCurrentI18n } from '../i18n/current.js';
+
+const I18nContext = createContext(null);
+
+/**
+ * @param {{bundle: object, release?: string, locale?: string, url?: string, languages?: string[],
+ *          preferred?: () => string|undefined, reporter?: (key: string) => void, children?: any}} props
+ */
+export function I18nProvider({ bundle, release, locale, url, languages, preferred, reporter, children }) {
+  const i18n = useMemo(() => {
+    const chosen =
+      locale ??
+      negotiateLocale({
+        url: url ?? (typeof location !== 'undefined' ? location.href : undefined),
+        languages: languages ?? (typeof navigator !== 'undefined' ? navigator.languages : []),
+        available: bundle.available_locales,
+        defaultLocale: bundle.default_locale,
+        preferred,
+      });
+    const report = reporter ?? (release ? createMissingReporter({ release, locale: chosen }) : undefined);
+    const instance = createI18n({ bundle, locale: chosen, reporter: report });
+    setCurrentI18n(instance);
+    return instance;
+  }, [bundle, release, locale, url, languages, preferred, reporter]);
+  return h(I18nContext.Provider, { value: i18n }, children);
+}
+
+/** The i18n instance of the nearest provider (or page scope). */
+export function useI18n() {
+  const i = useContext(I18nContext);
+  if (!i) throw new Error('useI18n: no I18nProvider above this component');
+  return i;
+}
+
+/** `t` bound to the nearest provider — lazy keys resolve against the page's scope. */
+export function useT() {
+  const i = useI18n();
+  return i.t;
+}
+
+/** Provide the lazy-lookup scope of a page (`pages/<route>/index.jsx` → `<route>.index`). */
+export function PageScope({ page, children }) {
+  const parent = useI18n();
+  const scoped = useMemo(() => parent.withLazy({ site_page: `pages/${page}/index.jsx` }), [parent, page]);
+  return h(I18nContext.Provider, { value: scoped }, children);
+}

package/src/react/index.js

@@ -0,0 +1,21 @@
+// @aircloudhq/web/react — the React bindings (ADR-222 D3; spec S4 § @aircloudhq/web public modules).
+export { I18nProvider, PageScope, useI18n, useT } from './i18n.js';
+export { Layout, SiteRouter, useSite } from './router.js';
+export { ButtonTo, LinkTo } from './links.js';
+export {
+  BooleanField,
+  DateField,
+  DateTimeField,
+  DecimalField,
+  ErrorMessages,
+  FileField,
+  FormWith,
+  IntegerField,
+  JsonField,
+  RelationField,
+  TextField,
+  VectorField,
+  fieldFor,
+  useForm,
+} from './form.js';
+export { Resource, ResourceForm, ResourceList, ResourceShow, defaultColumns, resourcePage, useDisplay } from './resource.js';

package/src/react/links.js

@@ -0,0 +1,56 @@
+// LinkTo and ButtonTo: link_to / button_to as components. The URL goes through urlFor, so the
+// current page's `locale` parameter travels with every link (ADR-223 D7).
+import { createElement as h } from 'react';
+import { Link, useInRouterContext, useLocation, useNavigate, useResolvedPath } from 'react-router';
+import { api } from '../api.js';
+import { urlFor } from '../helpers/url.js';
+
+function useHere() {
+  const inRouter = useInRouterContext();
+  const loc = inRouter ? useLocation() : null; // stable per tree position: the router context never appears or vanishes under a mounted component
+  if (loc) return `http://x${loc.pathname}${loc.search}${loc.hash}`;
+  return typeof location !== 'undefined' ? location.href : undefined;
+}
+
+// A relative target resolves against the route hierarchy (React Router's rule), then gains the locale.
+function useTarget(to) {
+  const here = useHere();
+  const inRouter = useInRouterContext();
+  const resolved = inRouter ? useResolvedPath(to) : null; // stable per tree position (see useHere)
+  const path = resolved ? `${resolved.pathname}${resolved.search}${resolved.hash}` : to;
+  return urlFor(path, { currentUrl: here });
+}
+
+/** <LinkTo to="/profiles/1">Profile</LinkTo> — link_to "Profile", "/profiles/1" */
+export function LinkTo({ to, children, ...props }) {
+  const href = useTarget(to);
+  if (useInRouterContext()) return h(Link, { to: href, ...props }, children ?? href);
+  return h('a', { href, ...props }, children ?? href);
+}
+
+/**
+ * <ButtonTo to="/api/pets/1" method="delete" onDone={…}>Delete</ButtonTo> — button_to: a one-button
+ * form. `get` navigates; any other method calls the API (with `params` as the body) and hands the
+ * result to `onDone`, or `onError` the ApiError.
+ */
+export function ButtonTo({ to, method = 'post', params, onDone, onError, children, className, formClass = 'button_to', ...props }) {
+  const inRouter = useInRouterContext();
+  const navigate = inRouter ? useNavigate() : null; // stable per tree position: the router context never appears or vanishes under a mounted component
+  const action = useTarget(to);
+  const m = String(method).toLowerCase();
+  function onSubmit(event) {
+    event.preventDefault();
+    if (m === 'get') {
+      if (navigate) navigate(action);
+      else location.assign(action);
+      return;
+    }
+    api(m.toUpperCase(), action, params).then((r) => onDone?.(r), (e) => (onError ? onError(e) : undefined));
+  }
+  return h(
+    'form',
+    { className: formClass, method: m === 'get' ? 'get' : 'post', action, onSubmit },
+    ['patch', 'put', 'delete'].includes(m) ? h('input', { type: 'hidden', name: '_method', value: m, autoComplete: 'off' }) : null,
+    h('button', { type: 'submit', className, ...props }, children),
+  );
+}

package/src/react/resource.js

@@ -0,0 +1,225 @@
+// Resource pages (ADR-222 D5; spec S4 § Resource-page override points): a scaffold page is one line —
+// `export default resourcePage("pet")` — and the full CRUD interface comes from the resource projection.
+// The Builder's choices are overrides in the page:
+//
+//   listColumns: string[]                        fields in the list, in order (default: the label field,
+//                                                then the next fields in schema order, up to five)
+//   fields: {[field]: Component}                 the input component of one field in the form
+//   display: {[field]: (value, record) => node}  how one field shows in list and show views
+//   List, Show, Form                             replace a whole view (props: resource, Default, …)
+//   layout: string                               a layout other than `application`
+//
+// Every visible string is a translation (the human model and attribute names, helpers.resource.*,
+// helpers.submit.*); a value renders through `l` and the number helpers of the current locale.
+import { createElement as h, useEffect, useMemo, useState } from 'react';
+import { Route, Routes, useNavigate, useParams } from 'react-router';
+import { createResource, recordLabel } from '../resource.js';
+import { humanAttributeName, modelName } from '../model.js';
+import { useI18n } from './i18n.js';
+import { useSite } from './router.js';
+import { ErrorMessages, FormWith } from './form.js';
+import { ButtonTo, LinkTo } from './links.js';
+
+/** The listColumns default (spec S4 § Constants, Provisional): label field first, up to five. */
+export const LIST_COLUMNS_MAX = 5;
+
+export function defaultColumns(resource) {
+  const names = resource.fields.map((f) => f.name);
+  const first = resource.label_field && names.includes(resource.label_field) ? [resource.label_field] : [];
+  return [...first, ...names.filter((n) => !first.includes(n))].slice(0, LIST_COLUMNS_MAX);
+}
+
+/** A stored value as the current locale renders it. */
+export function useDisplay(resource, display = {}) {
+  const i18n = useI18n();
+  return (field, record) => {
+    const value = record?.data?.[field];
+    if (display[field]) return display[field](value, record);
+    if (value === undefined || value === null || value === '') return '';
+    const type = resource.fields.find((f) => f.name === field)?.type;
+    switch (type) {
+      case 'date':
+        return i18n.l(String(value));
+      case 'datetime':
+        return i18n.l(new Date(value));
+      case 'integer':
+      case 'decimal':
+        return i18n.formatNumber('delimited', value);
+      case 'boolean':
+        return i18n.t(`helpers.resource.boolean.${value ? 'true' : 'false'}`);
+      case 'json':
+      case 'vector':
+        return JSON.stringify(value);
+      default:
+        return String(value);
+    }
+  };
+}
+
+function useResourceOf(name) {
+  const { projection } = useSite();
+  const r = projection?.resources?.[name];
+  if (!r) throw new Error(`the resource projection has no resource "${name}"`);
+  return r;
+}
+
+/** The default list view. */
+export function ResourceList({ resource, listColumns, display, base = '.' }) {
+  const i18n = useI18n();
+  const client = useMemo(() => createResource(resource), [resource]);
+  const [records, setRecords] = useState([]);
+  const [cursor, setCursor] = useState(null);
+  const [error, setError] = useState(null);
+  const show = useDisplay(resource, display);
+  const columns = listColumns ?? defaultColumns(resource);
+  const load = (after) =>
+    client.list({ cursor: after ?? undefined }).then((page) => {
+      setRecords((prev) => (after ? prev.concat(page.records) : page.records));
+      setCursor(page.cursor);
+    }, setError);
+  useEffect(() => {
+    load(null);
+  }, [client]);
+  const model = modelName(resource, { i18n });
+  return h(
+    'section',
+    { className: 'resource-list' },
+    h('h1', null, model.human({ count: 2 })),
+    h(ErrorMessages, { error }),
+    h('p', null, h(LinkTo, { to: `${base}/new`, className: 'button' }, i18n.t('helpers.resource.new', { model: model.human() }))),
+    h(
+      'table',
+      null,
+      h('thead', null, h('tr', null, columns.map((c) => h('th', { key: c }, humanAttributeName(resource, c, { i18n }))))),
+      h(
+        'tbody',
+        null,
+        records.map((r) =>
+          h(
+            'tr',
+            { key: r.id },
+            columns.map((c, i) =>
+              h('td', { key: c }, i === 0 ? h(LinkTo, { to: `${base}/${encodeURIComponent(r.id)}` }, show(c, r) || recordLabel(resource, r)) : show(c, r)),
+            ),
+          ),
+        ),
+      ),
+    ),
+    cursor ? h('p', null, h('button', { type: 'button', onClick: () => load(cursor) }, i18n.t('helpers.resource.more'))) : null,
+  );
+}
+
+/** The default show view. */
+export function ResourceShow({ resource, display, id, base = '..' }) {
+  const i18n = useI18n();
+  const navigate = useNavigate();
+  const client = useMemo(() => createResource(resource), [resource]);
+  const [record, setRecord] = useState(null);
+  const [error, setError] = useState(null);
+  const show = useDisplay(resource, display);
+  useEffect(() => {
+    client.get(id).then(setRecord, setError);
+  }, [client, id]);
+  return h(
+    'section',
+    { className: 'resource-show' },
+    h('h1', null, record ? recordLabel(resource, record) : modelName(resource, { i18n }).human()),
+    h(ErrorMessages, { error }),
+    record
+      ? h(
+          'dl',
+          null,
+          resource.fields.flatMap((f) => [
+            h('dt', { key: `${f.name}-t` }, humanAttributeName(resource, f.name, { i18n })),
+            h('dd', { key: `${f.name}-d` }, show(f.name, record)),
+          ]),
+        )
+      : null,
+    h(
+      'div',
+      { className: 'actions' },
+      h(LinkTo, { to: `${base}/${encodeURIComponent(id)}/edit`, className: 'button' }, i18n.t('helpers.resource.edit')),
+      h(
+        ButtonTo,
+        {
+          to: `${resource.route_prefix}/${encodeURIComponent(id)}`,
+          method: 'delete',
+          onDone: () => navigate(base),
+          onError: setError,
+          className: 'button-danger',
+        },
+        i18n.t('helpers.resource.destroy'),
+      ),
+      h(LinkTo, { to: base }, i18n.t('helpers.resource.back')),
+    ),
+  );
+}
+
+/** The default form view (new when `id` is absent, edit otherwise). */
+export function ResourceForm({ resource, fields, id, base = '..' }) {
+  const i18n = useI18n();
+  const navigate = useNavigate();
+  const client = useMemo(() => createResource(resource), [resource]);
+  const [record, setRecord] = useState(id === undefined ? null : undefined);
+  const [error, setError] = useState(null);
+  useEffect(() => {
+    if (id !== undefined) client.get(id).then(setRecord, setError);
+  }, [client, id]);
+  const model = modelName(resource, { i18n });
+  if (record === undefined) return h(ErrorMessages, { error });
+  return h(
+    'section',
+    { className: 'resource-form' },
+    h('h1', null, id === undefined ? i18n.t('helpers.resource.new', { model: model.human() }) : `${i18n.t('helpers.resource.edit')} ${recordLabel(resource, record)}`),
+    h(ErrorMessages, { error }),
+    h(FormWith, {
+      resource,
+      record: record ?? undefined,
+      fields,
+      onSubmit: (payload) =>
+        (id === undefined ? client.create(payload) : client.update(id, payload)).then((r) => {
+          navigate(`${base}/${encodeURIComponent(r.id)}`);
+          return r;
+        }),
+    }),
+    h('p', null, h(LinkTo, { to: id === undefined ? base : `${base}/${encodeURIComponent(id)}` }, i18n.t('helpers.resource.cancel'))),
+  );
+}
+
+function ShowRoute({ resource, options }) {
+  const { id } = useParams();
+  const View = options.Show ?? ResourceShow;
+  return h(View, { resource, id, display: options.display, Default: ResourceShow, base: '..' });
+}
+
+function EditRoute({ resource, options }) {
+  const { id } = useParams();
+  const View = options.Form ?? ResourceForm;
+  return h(View, { resource, id, fields: options.fields, Default: ResourceForm, base: '..' });
+}
+
+/** The routes of one resource: list, new, show, edit (Rails `resources`). */
+export function Resource({ name, options = {} }) {
+  const resource = useResourceOf(name);
+  const List = options.List ?? ResourceList;
+  const Form = options.Form ?? ResourceForm;
+  return h(
+    Routes,
+    null,
+    h(Route, { index: true, element: h(List, { resource, listColumns: options.listColumns, display: options.display, Default: ResourceList, base: '.' }) }),
+    h(Route, { path: 'new', element: h(Form, { resource, fields: options.fields, Default: ResourceForm, base: '..' }) }),
+    h(Route, { path: ':id', element: h(ShowRoute, { resource, options }) }),
+    h(Route, { path: ':id/edit', element: h(EditRoute, { resource, options }) }),
+  );
+}
+
+/** export default resourcePage("pet", { listColumns: ["name", "species"] }) */
+export function resourcePage(name, options = {}) {
+  function ResourcePage() {
+    return h(Resource, { name, options });
+  }
+  ResourcePage.displayName = `resourcePage(${name})`;
+  // The router wrapper renders a page in `Component.layout` when its route names none.
+  if (options.layout) ResourcePage.layout = options.layout;
+  return ResourcePage;
+}

package/src/react/router.js

@@ -0,0 +1,44 @@
+// The router wrapper over React Router (a pinned lockfile dependency — never copied source) and the
+// layouts (Rails `layouts/application`). A site's src/routes.js declares its named routes:
+//
+//   export default [{ name: "membros", path: "/membros/*", page: "membros", Component: MembrosPage }]
+//
+// and src/main.jsx renders <SiteRouter routes={routes} layouts={layouts} projection={projection} />.
+// Each page renders inside its layout and its lazy-lookup scope (`t(".title")` in
+// pages/membros/index.jsx is `membros.index.title`).
+import { createContext, createElement as h, useContext } from 'react';
+import { BrowserRouter, MemoryRouter, Route, Routes } from 'react-router';
+import { PageScope } from './i18n.js';
+
+const SiteContext = createContext({ layouts: {}, projection: null });
+
+/** The layouts and the resource projection the site renders with. */
+export function useSite() {
+  return useContext(SiteContext);
+}
+
+/** A named layout (default `application`); `site.layout_missing` when absent. */
+export function Layout({ name = 'application', children }) {
+  const { layouts } = useSite();
+  const L = layouts?.[name];
+  if (!L) throw new Error(`layout "${name}" does not exist (src/layouts/${name}.jsx)`);
+  return h(L, null, children);
+}
+
+/**
+ * @param {{routes: Array<{name: string, path: string, page: string, Component: any, layout?: string}>,
+ *          layouts?: Record<string, any>, projection?: object, basename?: string, initialEntries?: string[]}} props
+ *   `initialEntries` renders over a memory history (tests and previews).
+ */
+export function SiteRouter({ routes, layouts = {}, projection = null, basename, initialEntries }) {
+  const children = routes.map((r) =>
+    h(Route, {
+      key: r.name,
+      path: r.path,
+      element: h(Layout, { name: r.layout ?? r.Component.layout ?? 'application' }, h(PageScope, { page: r.page ?? r.name }, h(r.Component))),
+    }),
+  );
+  const table = h(Routes, null, children);
+  const router = initialEntries ? h(MemoryRouter, { initialEntries, basename }, table) : h(BrowserRouter, { basename }, table);
+  return h(SiteContext.Provider, { value: { layouts, projection } }, router);
+}

package/src/resource.js

@@ -0,0 +1,57 @@
+// Framework-neutral resource operations over a resource's CRUD route (Rails `resources`): the route
+// prefix, the fields and the label field come from the resource projection
+// (contracts/deploy/v1/resource-projection-v1.json), never from a hand-kept field list.
+//
+//   GET <prefix>?cursor=&limit=   list   -> {records: [{id, data}], cursor}
+//   GET <prefix>/<id>             get    -> {id, data}
+//   POST <prefix>                 create -> {id, data}
+//   PATCH <prefix>/<id>           update -> {id, data}
+//   DELETE <prefix>/<id>          destroy
+import { api as defaultApi } from './api.js';
+
+/** The projection resource `name` of `projection` (a resource-projection-v1 document). */
+export function projectionResource(projection, name) {
+  const r = projection?.resources?.[name];
+  if (!r) throw new Error(`the resource projection has no resource "${name}"`);
+  return r;
+}
+
+/** A resource client. */
+export function createResource(resource, options = {}) {
+  const call = options.api ?? defaultApi;
+  const prefix = resource.route_prefix;
+  if (!prefix) throw new Error(`resource "${resource.entity}" has no route (site.resource_unrouted)`);
+  const item = (id) => `${prefix}/${encodeURIComponent(id)}`;
+  return {
+    resource,
+    /** list({cursor, limit, filter: {field: value}}) -> {records, cursor} */
+    list({ cursor, limit, filter } = {}) {
+      const q = new URLSearchParams();
+      for (const [k, v] of Object.entries(filter ?? {})) q.set(k, String(v));
+      if (cursor) q.set('cursor', cursor);
+      if (limit) q.set('limit', String(limit));
+      const s = q.toString();
+      return call('GET', s ? `${prefix}?${s}` : prefix).then((r) => ({ records: r?.records ?? [], cursor: r?.cursor ?? null }));
+    },
+    /** Every page, in order: for await (const page of pets.pages()) … */
+    async *pages(params = {}) {
+      let cursor = params.cursor ?? null;
+      do {
+        const page = await this.list({ ...params, cursor });
+        yield page.records;
+        cursor = page.cursor;
+      } while (cursor);
+    },
+    get: (id) => call('GET', item(id)),
+    create: (data) => call('POST', prefix, data),
+    update: (id, data) => call('PATCH', item(id), data),
+    destroy: (id) => call('DELETE', item(id)),
+  };
+}
+
+/** A record's label: its label field's value, else its id. */
+export function recordLabel(resource, record) {
+  const f = resource.label_field;
+  const v = f ? record?.data?.[f] : undefined;
+  return v === undefined || v === null || v === '' ? String(record?.id ?? '') : String(v);
+}