@aircloudhq/web 1.0.4 → 1.1.0

package/README.md

@@ -82,6 +82,22 @@ import { resourcePage } from "@aircloudhq/web/react";
 export default resourcePage("pet");
 ```
 
+Routing inside a page uses the router primitives `@aircloudhq/web/react` re-exports — `Link`, `NavLink`,
+`Routes`, `Route`, `Outlet`, `Navigate`, `useLocation`, `useNavigate`, `useParams`, `useSearchParams` — the
+same React Router instance the `SiteRouter` renders with. Import them from `@aircloudhq/web/react`, never from
+`react-router`: a second copy of the router breaks its context.
+
+Dates and times render through `l` (`useI18n().l`, or `l` from `@aircloudhq/web/helpers/translation`), never
+`Intl`. A named format is looked up by what the value is:
+
+- an **instant** — a `Date` or a timestamp — reads `time.formats.<name>` and renders in the product's time zone;
+- a **civil date** — a `"YYYY-MM-DD"` string — reads `date.formats.<name>`.
+
+So `l(new Date(), { format: "weekday" })` reads `time.formats.weekday`; for `date.formats.weekday` pass the civil
+date (`l("2026-03-08", { format: "weekday" })`). A format no locale of the chain defines renders humanized and
+is **reported**, like a missing key: with a `release`, to the product host; with none (a dev server, a preview),
+`I18nProvider` warns on the console, naming the rule.
+
 A function answers in the caller's locale (`app/functions/pet/index.js`):
 
 ```js
@@ -98,7 +114,7 @@ async function methodNotAllowed(request) {
 
 | Import | What it carries |
 |---|---|
-| `@aircloudhq/web/react` | `SiteRouter`, `I18nProvider`, `useT`, `useSite`, `LinkTo`, `FormWith`, `resourcePage` |
+| `@aircloudhq/web/react` | `SiteRouter`, `I18nProvider`, `useT`, `useSite`, `LinkTo`, `FormWith`, `resourcePage`, the data hooks `useList` / `useRecord`, and the router primitives (`Link`, `Routes`, `useParams`, …) |
 | `@aircloudhq/web/helpers/number` | `numberToCurrency`, `numberToPercentage`, `numberWithDelimiter`, … |
 | `@aircloudhq/web/helpers/date` | `timeAgoInWords`, `distanceOfTimeInWords`, `distanceOfTimeInWordsToNow` |
 | `@aircloudhq/web/helpers/text`, `…/tag`, `…/url`, `…/form`, `…/sanitize`, `…/navigation` | the Action View helper modules of the same name |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aircloudhq/web",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "The application package of an Air-Cloud product: the Rails Action View helpers, i18n over the product's locale bundle, resource pages over its models, and React bindings, for its site and its JavaScript functions.",
   "keywords": [
     "aircloud",

package/src/function.js

@@ -8,6 +8,15 @@
 //   const i18n = await i18nFor(request, { function: 'greet' });
 //   i18n.t('.title'); // functions.greet.title in the negotiated locale
 //
+// A user-facing error is a code and its details, never a sentence (#250 operator decision D37):
+//
+//   return errorResponse(request, 409, { code: 'slot_taken', details: { slot } }, { function: 'book' });
+//
+// answers the platform envelope {"error":{"code","message","correlation_id","details"}} whose message is the
+// code's translation in the caller's locale — the function's own functions.<name>.errors.<code>, else the
+// platform's errors.codes.<code> — interpolated from the details' scalar values. It accepts nothing else:
+// a string, a message or any other key is a TypeError, so free text cannot reach an end user.
+//
 // Negotiation, in S4's order: (1) the end-user and organisation preference — reserved for #632;
 // (2) the request's Accept-Language, RFC 4647 lookup; (3) for a trigger without a request (an
 // `x-air-trigger: event` delivery), the `locale` key of the event payload; (4) default_locale. The
@@ -18,7 +27,7 @@
 // A key no locale resolves renders humanized and is reported through the capability, which alarms
 // once per key per release.
 import { bundle, keyMissing, locales } from 'aircloud:functions/i18n@1.0.0';
-import { acceptLanguage, createI18n, lookupLocale } from './i18n/index.js';
+import { acceptLanguage, createI18n, lookupLocale, OPTION_KEYS } from './i18n/index.js';
 
 function canonical(available, tag) {
   if (typeof tag !== 'string') return undefined;
@@ -71,3 +80,55 @@ export async function i18nFor(request, { function: name } = {}) {
     },
   });
 }
+
+/** An error code: dot-separated snake_case segments (`slot_taken`, `flex.validation`). */
+const CODE = /^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)*$/;
+
+function isPlainObject(v) {
+  return v !== null && typeof v === 'object' && Object.getPrototypeOf(v) === Object.prototype;
+}
+
+/** The user-facing error, checked: exactly {code, details?}, a code that is a code, details an object. */
+function userError(error) {
+  if (!isPlainObject(error)) throw new TypeError('errorResponse: the error is {code, details}, never a message');
+  for (const k of Object.keys(error)) {
+    if (k !== 'code' && k !== 'details') throw new TypeError(`errorResponse: the error takes only {code, details}, not \`${k}\``);
+  }
+  if (typeof error.code !== 'string' || !CODE.test(error.code)) {
+    throw new TypeError(`errorResponse: ${JSON.stringify(error.code)} is not an error code (snake_case segments)`);
+  }
+  const details = error.details ?? {};
+  if (!isPlainObject(details)) throw new TypeError('errorResponse: details is an object');
+  return { code: error.code, details };
+}
+
+/**
+ * The response of a user-facing error (D37): the platform envelope with the code's translated message.
+ * @param {Request} request the invocation's request (its locale, its x-correlation-id)
+ * @param {number} status the HTTP status
+ * @param {{code: string, details?: object}} error the code and its details — nothing else
+ * @param {{function?: string}} [options] the function's name, the scope of its own error keys
+ * @returns {Promise<Response>}
+ */
+export async function errorResponse(request, status, error, { function: name } = {}) {
+  const { code, details } = userError(error);
+  let message;
+  try {
+    const i18n = await i18nFor(request, { function: name });
+    const args = {};
+    for (const [k, v] of Object.entries(details)) {
+      if (!OPTION_KEYS.has(k) && ['string', 'number', 'boolean'].includes(typeof v)) args[k] = v;
+    }
+    const platform = `errors.codes.${code}`;
+    message = name ? i18n.t(`.errors.${code}`, { ...args, default: [{ key: platform }] }) : i18n.t(platform, args);
+  } catch (e) {
+    // An error response is always answered: when the bundle cannot be read, the message is the refusal's code.
+    if (typeof e?.payload?.code !== 'string') throw e;
+    message = e.payload.code;
+  }
+  const correlationId = request.headers.get('x-correlation-id') ?? '';
+  return new Response(JSON.stringify({ error: { code, message, correlation_id: correlationId, details } }), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}

package/src/helpers/form.js

@@ -100,10 +100,22 @@ export function fullMessage(resource, field, message, options = {}) {
 /**
  * createForm(resource, {record, i18n}) — the form model of one resource: a new record, or the edit of
  * `record` ({id, data}).
+ *
+ * A new record starts each field at its projected literal default (ADR-259 decision 9); a generator
+ * default has no value until Flex evaluates it, so its field starts empty. An edit starts from the stored
+ * values, never the default. On create, a defaulted field the user did not touch is omitted from the
+ * payload (Flex fills the default in force for the record's subtree) and passes the client-side
+ * required check; a defaulted field the user cleared is sent as null, so the default does not return.
  */
 export function createForm(resource, options = {}) {
   const i18n = () => i18nFor(options);
-  const initial = Object.fromEntries(resource.fields.map((f) => [f.name, toInput(f.type, options.record?.data?.[f.name])]));
+  const start = (f) => {
+    if (options.record) return options.record.data?.[f.name];
+    return f.default && 'value' in f.default ? f.default.value : undefined;
+  };
+  const initial = Object.fromEntries(resource.fields.map((f) => [f.name, toInput(f.type, start(f))]));
+  // A defaulted field the user has not touched, on a new record: Flex applies its default.
+  const defaulted = (f) => model.id === undefined && Boolean(f.default) && !state.touched[f.name];
   let state = {
     values: { ...initial },
     initial: { ...initial },
@@ -147,19 +159,24 @@ export function createForm(resource, options = {}) {
     validate() {
       const errors = {};
       for (const f of resource.fields) {
+        if (defaulted(f)) continue;
         const kind = validationKind(f, state.values[f.name]);
         if (kind) errors[f.name] = [errorMessage(resource, f.name, kind, { i18n: i18n() })];
       }
       setState({ errors });
       return Object.keys(errors).length === 0;
     },
-    /** The JSON body of the submit: set fields; on an update a cleared field is null. */
+    /**
+     * The JSON body of the submit: set fields; on an update a cleared field is null. On a create an
+     * untouched defaulted field is omitted and a cleared one is null.
+     */
     payload() {
       const data = {};
       for (const f of resource.fields) {
+        if (defaulted(f)) continue;
         const v = toValue(f.type, state.values[f.name]);
         if (v !== undefined) data[f.name] = v;
-        else if (model.id !== undefined) data[f.name] = null;
+        else if (model.id !== undefined || f.default) data[f.name] = null;
       }
       return data;
     },

package/src/helpers/number.js

@@ -2,8 +2,8 @@
 // locale bundle's `number.*` keys: the same option names (camelCase accepted as well), the same
 // defaults, BigDecimal half-up rounding. Without a bound i18n instance the Rails defaults apply.
 import { i18nFor } from '../i18n/current.js';
-import { NUMBER_DEFAULTS, formatDelimited, formatRounded } from '../i18n/index.js';
-import { abs, parseDecimal } from '../i18n/decimal.js';
+import { NUMBER_DEFAULTS, formatDelimited, formatRounded, moneyValue, renderCurrency } from '../i18n/index.js';
+import { parseDecimal } from '../i18n/decimal.js';
 
 const SNAKE = {
   stripInsignificantZeros: 'strip_insignificant_zeros',
@@ -30,13 +30,15 @@ function lookup(options, key) {
   return i18nFor(options)?.lookup(key);
 }
 
-/** number_to_currency(1234567890.50) # => "$1,234,567,890.50" */
+/**
+ * number_to_currency(1234567890.50) # => "$1,234,567,890.50" — a plain number in the product currency,
+ * a monetary value `{amount: "79.90", currency: "USD"}` in its own (ADR-255 decision 8).
+ */
 export function numberToCurrency(number, options = {}) {
-  const o = optionsFor('currency', options);
-  const d = parseDecimal(number);
-  const rounded = formatRounded(abs(d), o);
-  const format = d.neg && /[1-9]/.test(rounded) ? o.negative_format : o.format;
-  return format.replace('%n', rounded).replace('%u', o.unit);
+  const i = i18nFor(options);
+  if (i) return i.formatNumber('currency', number, snake(options));
+  const money = moneyValue(number);
+  return renderCurrency(parseDecimal(money ? money.amount : number), optionsFor('currency', options));
 }
 
 /** number_with_delimiter(12345678) # => "12,345,678" */

package/src/i18n/index.js

@@ -11,13 +11,14 @@ import { zoneAt } from './zone.js';
 export { pluralCategory, operands } from './plural.js';
 export { zoneAt } from './zone.js';
 export { negotiateLocale, lookupLocale, acceptLanguage, localeFromUrl } from './negotiate.js';
-export { createMissingReporter } from './missing.js';
+export { createDevReporter, createMissingReporter } from './missing.js';
 
 /** The locale that ends every run-time chain with the platform defaults (S4 § [i18n]). */
 export const PLATFORM_TERMINAL_LOCALE = 'en';
 
 const PLURAL_KEYS = ['zero', 'one', 'two', 'few', 'many', 'other'];
-const OPTION_KEYS = new Set(['scope', 'default', 'count', 'lazy', 'context', 'locale']);
+/** The keys of a `t` call's options; every other key is an interpolation argument. */
+export const OPTION_KEYS = new Set(['scope', 'default', 'count', 'lazy', 'context', 'locale']);
 
 // ── chains ───────────────────────────────────────────────────────────────────────────────────
 
@@ -229,10 +230,19 @@ export function localize(bundle, locale, value, options = {}, report = () => {})
 
 // ── numbers ──────────────────────────────────────────────────────────────────────────────────
 
-/** ActiveSupport::NumberHelper::NumberConverter::DEFAULTS. */
+/** CLDR's generic currency sign (ISO 4217 XXX, "no currency"): the unit when none resolves (ADR-255 D5). */
+export const GENERIC_CURRENCY_SIGN = '¤';
+/** The key a currency rendering with no currency reports through the missing-key channel (ADR-255 D5). */
+export const CURRENCY_MISSING_KEY = 'number.currency.code';
+
+/**
+ * ActiveSupport::NumberHelper::NumberConverter::DEFAULTS — except the currency unit, which is never a
+ * locale or platform default (ADR-255): `¤`, CLDR's generic currency sign, stands until the product
+ * currency or the call's own `unit` resolves it.
+ */
 export const NUMBER_DEFAULTS = {
   format: { separator: '.', delimiter: ',', precision: 3, significant: false, strip_insignificant_zeros: false },
-  currency: { format: '%u%n', negative_format: '-%u%n', unit: '$', separator: '.', delimiter: ',', precision: 2, significant: false, strip_insignificant_zeros: false },
+  currency: { format: '%u%n', negative_format: '-%u%n', unit: GENERIC_CURRENCY_SIGN, separator: '.', delimiter: ',', precision: 2, significant: false, strip_insignificant_zeros: false },
   percentage: { delimiter: '', format: '%n%' },
   precision: { delimiter: '' },
   human: {
@@ -242,18 +252,82 @@ export const NUMBER_DEFAULTS = {
   storage_units: { format: '%n %u', units: { byte: 'Bytes', kb: 'KB', mb: 'MB', gb: 'GB', tb: 'TB', pb: 'PB', eb: 'EB', zb: 'ZB' } },
 };
 
+/**
+ * A monetary value — `{amount, currency}`, a decimal string and the ISO 4217 code it is in (ADR-255
+ * decision 8, D34: an amount carries its own currency, and the product currency never restates it) —
+ * or null for a plain number. A value naming a currency whose amount is not a decimal string (G12:
+ * never a binary float) or whose code is not ISO 4217-shaped is refused.
+ */
+export function moneyValue(value) {
+  if (value === null || typeof value !== 'object' || !Object.hasOwn(value, 'currency')) return null;
+  const { amount, currency } = value;
+  if (typeof amount !== 'string') {
+    throw new TypeError(`a monetary value's amount is a decimal string such as "79.90", not ${JSON.stringify(amount)}`);
+  }
+  parseDecimal(amount);
+  if (typeof currency !== 'string' || !/^[A-Z]{3}$/.test(currency)) {
+    throw new TypeError(`a monetary value's currency is an ISO 4217 code such as "USD", not ${JSON.stringify(currency)}`);
+  }
+  return { amount, currency };
+}
+
 /**
  * The effective options of a number style (Rails' i18n_format_options): defaults, then the first
  * `number.format` hash of the locale's declared chain (else its CLDR symbols), then the first
- * `number.<namespace>.format` hash of the run-time chain, then the call's options.
+ * `number.<namespace>.format` hash of the run-time chain, then the call's options. For `currency`
+ * the unit and precision then resolve from the value's own currency (`valueCurrency`, a monetary
+ * value's code) or the product currency (currencyOptions).
  */
-export function numberOptions(bundle, locale, namespace, options = {}) {
+export function numberOptions(bundle, locale, namespace, options = {}, report = () => {}, valueCurrency = undefined) {
   const base = firstIn(bundle, declaredChain(bundle, locale), 'number.format', isObject)?.value
     ?? cldrNumberFormat(bundle, locale)
     ?? firstIn(bundle, runtimeChain(bundle, locale), 'number.format', isObject)?.value
     ?? {};
   const ns = namespace ? firstIn(bundle, runtimeChain(bundle, locale), `number.${namespace}.format`, isObject)?.value ?? {} : {};
-  return { ...NUMBER_DEFAULTS.format, ...(namespace ? NUMBER_DEFAULTS[namespace] ?? {} : {}), ...base, ...ns, ...options };
+  const o = { ...NUMBER_DEFAULTS.format, ...(namespace ? NUMBER_DEFAULTS[namespace] ?? {} : {}), ...base, ...ns, ...options };
+  return namespace === 'currency' ? currencyOptions(bundle, locale, o, options, report, valueCurrency) : o;
+}
+
+/**
+ * The currency of a rendering (ADR-255 decisions 2, 3, 5, 8). The currency is the value's own (a
+ * monetary value's code, which must be in the bundle's active set) else the product currency. The unit
+ * is the call's explicit `unit`, else that currency's CLDR symbol in this locale, else `¤` — reported
+ * once as `number.currency.code`, never a guessed currency; a locale file's `unit` is not read. The
+ * precision is the call's explicit `precision`, else that currency's minor unit (CLDR's DEFAULT when
+ * there is none); a locale file's `precision` is not read. Where the symbol directly touches the number
+ * (`%u%n`, `%n%u`) the locale's CLDR currencySpacing is inserted.
+ */
+function currencyOptions(bundle, locale, o, options, report, valueCurrency) {
+  const facts = bundle.currency;
+  if (valueCurrency !== undefined && !Object.hasOwn(facts?.minor_units ?? {}, valueCurrency)) {
+    throw new RangeError(`currency ${valueCurrency} is not an ISO 4217 currency in tender use at the bundle's CLDR`);
+  }
+  const code = valueCurrency ?? facts?.code ?? null;
+  const minor = code ? facts.minor_units?.[code] : facts?.default_minor_unit;
+  const out = { ...o, precision: options.precision ?? minor ?? o.precision };
+  if (options.unit !== undefined) return out;
+  const symbol = code ? facts.symbols?.[locale]?.[code] : undefined;
+  if (!symbol) {
+    report(CURRENCY_MISSING_KEY);
+    return { ...out, unit: GENERIC_CURRENCY_SIGN };
+  }
+  const spaced = (format) => format.replace('%u%n', `%u${symbol.prefix_spacing}%n`).replace('%n%u', `%n${symbol.suffix_spacing}%u`);
+  return { ...out, unit: symbol.symbol, format: spaced(out.format), negative_format: spaced(out.negative_format) };
+}
+
+/** number_to_currency's rendering of a decimal over resolved currency options. */
+export function renderCurrency(d, o) {
+  const rounded = formatRounded(abs(d), o);
+  const zero = /^[^1-9]*$/.test(rounded);
+  const format = d.neg && !zero ? o.negative_format : o.format;
+  return format.replace('%n', rounded).replace('%u', o.unit);
+}
+
+/** number_to_currency over the bundle: a plain number in the product currency, a monetary value in its own. */
+export function formatCurrency(bundle, locale, value, options = {}, report = () => {}) {
+  const money = moneyValue(value);
+  const o = numberOptions(bundle, locale, 'currency', options, report, money?.currency);
+  return renderCurrency(parseDecimal(money ? money.amount : value), o);
 }
 
 function cldrNumberFormat(bundle, locale) {
@@ -278,7 +352,7 @@ export function formatRounded(value, o) {
 }
 
 /** The shared number styles: currency | delimited | precision | percentage. */
-export function formatNumber(bundle, locale, style, value, options = {}) {
+export function formatNumber(bundle, locale, style, value, options = {}, report = () => {}) {
   switch (style) {
     case 'delimited':
       return formatDelimited(value, numberOptions(bundle, locale, null, options));
@@ -288,14 +362,8 @@ export function formatNumber(bundle, locale, style, value, options = {}) {
       const o = numberOptions(bundle, locale, 'percentage', options);
       return o.format.replace('%n', formatRounded(value, o));
     }
-    case 'currency': {
-      const o = numberOptions(bundle, locale, 'currency', options);
-      const d = parseDecimal(value);
-      const rounded = formatRounded(abs(d), o);
-      const zero = /^[^1-9]*$/.test(rounded);
-      const format = d.neg && !zero ? o.negative_format : o.format;
-      return format.replace('%n', rounded).replace('%u', o.unit);
-    }
+    case 'currency':
+      return formatCurrency(bundle, locale, value, options, report);
     default:
       throw new Error(`formatNumber: unknown style ${style}`);
   }
@@ -355,8 +423,8 @@ export function createI18n({ bundle, locale, reporter, lazy } = {}) {
     locale: current,
     t: (key, options = {}) => translate(bundle, current, key, { lazy, ...options }, report),
     l: (value, options = {}) => localize(bundle, current, value, options, report),
-    formatNumber: (style, value, options) => formatNumber(bundle, current, style, value, options),
-    numberOptions: (namespace, options) => numberOptions(bundle, current, namespace, options),
+    formatNumber: (style, value, options) => formatNumber(bundle, current, style, value, options, report),
+    numberOptions: (namespace, options) => numberOptions(bundle, current, namespace, options, report),
     pluralize: (count, singular, plural) => pluralizeWord(bundle, current, count, singular, plural),
     exists: (key, options = {}) => resolve(bundle, current, key, { lazy, ...options }).found,
     /** The raw value of a key through the run-time chain (a hash, an array, a string), or undefined. */

package/src/i18n/missing.js

@@ -33,3 +33,33 @@ export function createMissingReporter({ release, locale, send }) {
     }
   };
 }
+
+const FORMAT_KEY = /^(date|time)\.formats\.(.+)$/;
+
+/** The rule a missing date/time format breaks (#664 item 28): an instant reads time.formats, a civil date date.formats. */
+function formatHint(key) {
+  const m = FORMAT_KEY.exec(key);
+  if (!m) return '';
+  const [, kind, name] = m;
+  return kind === 'time'
+    ? ` A Date or a timestamp is an instant and reads time.formats.${name}; pass a civil date as "YYYY-MM-DD" to read date.formats.${name}.`
+    : ` A "YYYY-MM-DD" string is a civil date and reads date.formats.${name}; an instant (a Date) reads time.formats.${name}.`;
+}
+
+/**
+ * The reporter of a page with no release to report to (a dev server, a preview, a test): a key still
+ * unresolved after its chain is rendered humanized and warned on the console — never silently — once per
+ * key per page load (at most MAX_KEYS_PER_PAGE_LOAD keys); a missing date/time format names the
+ * instant-vs-civil-date rule.
+ * @param {{locale: string, warn?: (message: string) => void}} init  `warn` defaults to console.warn
+ * @returns {(key: string) => void}
+ */
+export function createDevReporter({ locale, warn }) {
+  const seen = new Set();
+  const out = warn ?? ((message) => console.warn(message));
+  return (key) => {
+    if (seen.has(key) || seen.size >= MAX_KEYS_PER_PAGE_LOAD) return;
+    seen.add(key);
+    out(`@aircloudhq/web i18n: missing "${key}" (locale ${locale}) — rendered humanized.${formatHint(key)}`);
+  };
+}

package/src/model.js

@@ -30,8 +30,22 @@ export function modelName(resource, options = {}) {
   };
 }
 
-/** Model.human_attribute_name(:field) */
+/**
+ * Model.human_attribute_name(:field), and human_attribute_name("field.value") for an enum value (ADR-258
+ * decision 7): the nested key `activemodel.attributes.<entity>/<field>.<value>`, else the value's
+ * projection display_name (the default-locale label), else the value itself — a value the projection
+ * does not know renders as itself.
+ */
 export function humanAttributeName(resource, field, options = {}) {
+  const dot = field.indexOf('.');
+  if (dot >= 0) {
+    const name = field.slice(0, dot);
+    const value = field.slice(dot + 1);
+    const f = fieldOf(resource, name);
+    const v = i18nFor(options)?.lookupDeclared(`activemodel.attributes.${resource.entity}/${name}.${value}`);
+    if (typeof v === 'string') return v;
+    return f.enum?.values?.find((x) => x.value === value)?.display_name ?? value;
+  }
   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/data.js

@@ -0,0 +1,145 @@
+// Data hooks over a resource's CRUD route (#664 item 15): the React side of `@aircloudhq/web/resource`, for
+// pages that are not a whole resourcePage. A resource is its entity name (resolved in the site's resource
+// projection) or the projection resource itself.
+//
+//   const { records, cursor, loading, error, more, reload } = useList("pet", { filter: { owner: id } });
+//   const { record, loading, error, reload } = useRecord("pet", id);
+//
+// The typed per-entity client is Air-Reflect's typed SDK (#246, ADR-083); these hooks read the projection.
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { createResource, projectionResource, recordLabel } from '../resource.js';
+import { useSite } from './router.js';
+
+/** The projection resource a hook names: an entity name, the resource itself, or null (no resource). */
+export function useResource(resource) {
+  const { projection } = useSite();
+  if (resource === null || resource === undefined) return null;
+  return typeof resource === 'string' ? projectionResource(projection, resource) : resource;
+}
+
+/**
+ * The records of a resource, page by page (`cursor` paging; `more()` appends the next page).
+ * @param {string|object|null} resource  null lists nothing
+ * @param {{filter?: Record<string, string>, limit?: number}} [query]  `filter` compares fields by equality
+ */
+export function useList(resource, query = {}) {
+  const r = useResource(resource);
+  const client = useMemo(() => (r ? createResource(r) : null), [r]);
+  const key = JSON.stringify({ filter: query.filter ?? {}, limit: query.limit ?? null });
+  const [state, setState] = useState({ records: [], cursor: null, loading: Boolean(client), error: null });
+  const generation = useRef(0);
+  const load = useCallback(
+    (after) => {
+      if (!client) return Promise.resolve();
+      const g = generation.current;
+      const { filter, limit } = JSON.parse(key);
+      setState((s) => ({ ...s, loading: true }));
+      return client.list({ cursor: after ?? undefined, filter, limit: limit ?? undefined }).then(
+        (page) => {
+          if (g !== generation.current) return;
+          setState((s) => ({ records: after ? s.records.concat(page.records) : page.records, cursor: page.cursor, loading: false, error: null }));
+        },
+        (error) => {
+          if (g !== generation.current) return;
+          setState((s) => ({ ...s, loading: false, error }));
+        },
+      );
+    },
+    [client, key],
+  );
+  useEffect(() => {
+    generation.current += 1;
+    setState({ records: [], cursor: null, loading: Boolean(client), error: null });
+    load(null);
+  }, [load]);
+  return {
+    ...state,
+    /** The next page appended; a no-op on the last page. */
+    more: () => (state.cursor ? load(state.cursor) : Promise.resolve()),
+    /** The first page again. */
+    reload: () => load(null),
+  };
+}
+
+/**
+ * One record of a resource by id; an undefined id reads nothing (`record` null).
+ * @param {string|object} resource
+ * @param {string|undefined} id
+ */
+export function useRecord(resource, id) {
+  const r = useResource(resource);
+  const client = useMemo(() => createResource(r), [r]);
+  const [state, setState] = useState({ record: null, loading: id !== undefined, error: null });
+  const generation = useRef(0);
+  const load = useCallback(() => {
+    if (id === undefined) return Promise.resolve();
+    const g = generation.current;
+    setState((s) => ({ ...s, loading: true }));
+    return client.get(id).then(
+      (record) => g === generation.current && setState({ record, loading: false, error: null }),
+      (error) => g === generation.current && setState({ record: null, loading: false, error }),
+    );
+  }, [client, id]);
+  useEffect(() => {
+    generation.current += 1;
+    setState({ record: null, loading: id !== undefined, error: null });
+    load();
+  }, [load]);
+  return { ...state, reload: load };
+}
+
+/**
+ * The labels of the related records the given records point to, one read per distinct related record:
+ * `(field, id) => label | undefined` (undefined until read, or when the target is not routed).
+ */
+export function useRelationLabels(resource, records) {
+  const { projection } = useSite();
+  const wanted = useMemo(() => {
+    const out = [];
+    for (const f of resource.fields) {
+      const target = f.relation ? projection?.resources?.[f.relation.target] : undefined;
+      if (!target?.route_prefix) continue;
+      const ids = new Set(records.map((rec) => rec?.data?.[f.name]).filter((v) => v !== undefined && v !== null && v !== ''));
+      for (const id of ids) out.push({ target, id: String(id) });
+    }
+    return out;
+  }, [resource, records, projection]);
+  const [labels, setLabels] = useState({});
+  const requested = useRef(new Set());
+  const mounted = useRef(true);
+  useEffect(() => {
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+    };
+  }, []);
+  useEffect(() => {
+    for (const { target, id } of wanted) {
+      const k = `${target.entity}/${id}`;
+      if (requested.current.has(k)) continue;
+      requested.current.add(k);
+      const settle = (label) => mounted.current && setLabels((m) => ({ ...m, [k]: label }));
+      createResource(target)
+        .get(id)
+        .then((rec) => settle(recordLabel(target, rec)), () => settle(null));
+    }
+  }, [wanted]);
+  return (field, id) => {
+    const f = resource.fields.find((x) => x.name === field);
+    const target = f?.relation?.target;
+    const label = target === undefined ? undefined : labels[`${target}/${id}`];
+    return label ?? undefined;
+  };
+}
+
+/**
+ * The has-many relations of a resource: every relation field of a resource of the projection whose target
+ * is it, in projection order — [{entity, field}].
+ */
+export function hasManyRelations(projection, name) {
+  const out = [];
+  for (const [entity, r] of Object.entries(projection?.resources ?? {})) {
+    for (const f of r.fields) if (f.relation?.target === name) out.push({ entity, field: f.name });
+  }
+  return out;
+}

package/src/react/form.js

@@ -2,13 +2,16 @@
 // 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 { createContext, createElement as h, useContext, useMemo, 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';
+import { useList } from './data.js';
+
+/** The records a relation select offers: one Flex query page at its maximum (contracts/flex/v1/requests.json `limit`). */
+export const RELATION_OPTIONS_LIMIT = 200;
 
 const FormContext = createContext(null);
 
@@ -27,11 +30,15 @@ function Field({ name, children, input }) {
   const { form, state } = useForm();
   const i18n = useI18n();
   const errors = state.errors[name] ?? [];
+  // A generator default has no value until Flex evaluates it: a new record's field names it instead
+  // (ADR-259 decision 9).
+  const generator = form.id === undefined ? form.fields.find((f) => f.name === name)?.default?.generator : undefined;
   return h(
     'div',
     { className: errors.length ? 'field field_with_errors' : 'field' },
     h('label', { htmlFor: `${form.resource.entity}_${name}` }, humanAttributeName(form.resource, name, { i18n })),
     input,
+    generator ? h('p', { className: 'field-hint' }, i18n.t(`helpers.resource.default_generator.${generator}`)) : null,
     errors.length ? h('p', { className: 'field-error', role: 'alert' }, errors.join(', ')) : null,
     children,
   );
@@ -90,13 +97,9 @@ export function RelationField({ name }) {
   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]);
+  // The related resource's records (one Flex page, its maximum), through the same hook a page lists with.
+  const { records: options } = useList(target?.route_prefix ? target : null, { limit: RELATION_OPTIONS_LIMIT });
   const props = inputProps(name, undefined);
   delete props.type;
   return h(Field, {
@@ -110,12 +113,43 @@ export function RelationField({ name }) {
   });
 }
 
+/**
+ * An enum (ADR-258 decision 10): a select of the live values in declared order, each labelled by
+ * human_attribute_name("<field>.<value>"); a blank option when the field is optional, the select prompt
+ * when a required field has no value yet. A value outside the live list — removed, or unknown to this
+ * projection — stays as a selected, disabled option, so the form never silently changes it.
+ */
+export function EnumField({ name }) {
+  const { form, state } = useForm();
+  const i18n = useI18n();
+  const field = form.fields.find((f) => f.name === name);
+  const values = field?.enum?.values ?? [];
+  const live = values.filter((v) => !v.removed).map((v) => v.value);
+  const current = state.values[name];
+  const props = inputProps(name, undefined);
+  delete props.type;
+  const label = (value) => humanAttributeName(form.resource, `${name}.${value}`, { i18n });
+  let lead = null;
+  if (current !== '' && current !== undefined && !live.includes(current)) {
+    lead = h('option', { value: current, disabled: true }, label(current));
+  } else if (!field?.required) {
+    lead = h('option', { value: '' }, '');
+  } else if (current === '' || current === undefined) {
+    lead = h('option', { value: '' }, i18n.t('helpers.select.prompt'));
+  }
+  return h(Field, {
+    name,
+    input: h('select', props, lead, live.map((v) => h('option', { key: v, value: v }, label(v)))),
+  });
+}
+
 /** 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,
+      enum: EnumField,
     }[type] ?? TextField
   );
 }

package/src/react/i18n.js

@@ -1,9 +1,10 @@
 // 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).
+// POST /_air/i18n-missing (bounded per key per page load) — or, with no release, the dev reporter's console
+// warning (a missing key is never silently humanized).
 import { createContext, createElement as h, useContext, useMemo } from 'react';
-import { createI18n, createMissingReporter, negotiateLocale } from '../i18n/index.js';
+import { createDevReporter, createI18n, createMissingReporter, negotiateLocale } from '../i18n/index.js';
 import { setCurrentI18n } from '../i18n/current.js';
 
 const I18nContext = createContext(null);
@@ -23,7 +24,9 @@ export function I18nProvider({ bundle, release, locale, url, languages, preferre
         defaultLocale: bundle.default_locale,
         preferred,
       });
-    const report = reporter ?? (release ? createMissingReporter({ release, locale: chosen }) : undefined);
+    // A release reports to the product host; with none (a dev server, a preview) the console warns — a
+    // missing key or format is never silently humanized (#664 item 28).
+    const report = reporter ?? (release ? createMissingReporter({ release, locale: chosen }) : createDevReporter({ locale: chosen }));
     const instance = createI18n({ bundle, locale: chosen, reporter: report });
     setCurrentI18n(instance);
     return instance;

package/src/react/index.js

@@ -1,12 +1,27 @@
 // @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';
+// The router primitives of the one React Router instance the SiteRouter renders with (#664 item 13): a site
+// imports them from here, never from `react-router` itself — a second copy would break the router context.
+export {
+  Link,
+  NavLink,
+  Navigate,
+  Outlet,
+  Route,
+  Routes,
+  useLocation,
+  useNavigate,
+  useParams,
+  useSearchParams,
+} from 'react-router';
 export { ButtonTo, LinkTo } from './links.js';
 export {
   BooleanField,
   DateField,
   DateTimeField,
   DecimalField,
+  EnumField,
   ErrorMessages,
   FileField,
   FormWith,
@@ -18,4 +33,5 @@ export {
   fieldFor,
   useForm,
 } from './form.js';
-export { Resource, ResourceForm, ResourceList, ResourceShow, defaultColumns, resourcePage, useDisplay } from './resource.js';
+export { Resource, ResourceForm, ResourceList, ResourceShow, ResourceTabs, defaultColumns, resourcePage, useDisplay } from './resource.js';
+export { hasManyRelations, useList, useRecord } from './data.js';

package/src/react/resource.js

@@ -8,10 +8,15 @@
 //   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`
+//   tabs: string[]                               the show view's has-many tabs, one per relation of
+//                                                another resource that targets this one: "<entity>", or
+//                                                "<entity>.<field>" when that entity relates through
+//                                                more than one field
 //
 // 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';
+// helpers.submit.*); a value renders through `l` and the number helpers of the current locale, a relation
+// by the related record's label field.
+import { createElement as h, useMemo, useState } from 'react';
 import { Route, Routes, useNavigate, useParams } from 'react-router';
 import { createResource, recordLabel } from '../resource.js';
 import { humanAttributeName, modelName } from '../model.js';
@@ -19,6 +24,7 @@ import { useI18n } from './i18n.js';
 import { useSite } from './router.js';
 import { ErrorMessages, FormWith } from './form.js';
 import { ButtonTo, LinkTo } from './links.js';
+import { hasManyRelations, useList, useRecord, useRelationLabels } from './data.js';
 
 /** The listColumns default (spec S4 § Constants, Provisional): label field first, up to five. */
 export const LIST_COLUMNS_MAX = 5;
@@ -29,8 +35,11 @@ export function defaultColumns(resource) {
   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 = {}) {
+/**
+ * A stored value as the current locale renders it; a relation as `relationLabel(field, id)` gives it (the
+ * related record's label, useRelationLabels), else its id.
+ */
+export function useDisplay(resource, display = {}, relationLabel = () => undefined) {
   const i18n = useI18n();
   return (field, record) => {
     const value = record?.data?.[field];
@@ -47,6 +56,10 @@ export function useDisplay(resource, display = {}) {
         return i18n.formatNumber('delimited', value);
       case 'boolean':
         return i18n.t(`helpers.resource.boolean.${value ? 'true' : 'false'}`);
+      case 'relation':
+        return relationLabel(field, String(value)) ?? String(value);
+      case 'enum':
+        return humanAttributeName(resource, `${field}.${value}`, { i18n });
       case 'json':
       case 'vector':
         return JSON.stringify(value);
@@ -56,6 +69,21 @@ export function useDisplay(resource, display = {}) {
   };
 }
 
+/**
+ * The list and show views' cell: `show`'s rendering, with an enum value wrapped in a badge (ADR-258
+ * decision 10) — class `badge` plus `data-field` and `data-value`, the stable hooks a product's CSS styles
+ * each value by. A `display` override renders as given.
+ */
+function badged(resource, display = {}, show) {
+  return (field, record) => {
+    const node = show(field, record);
+    const value = record?.data?.[field];
+    if (display[field] || value === undefined || value === null || value === '') return node;
+    if (resource.fields.find((f) => f.name === field)?.type !== 'enum') return node;
+    return h('span', { className: 'badge', 'data-field': field, 'data-value': String(value) }, node);
+  };
+}
+
 function useResourceOf(name) {
   const { projection } = useSite();
   const r = projection?.resources?.[name];
@@ -63,30 +91,26 @@ function useResourceOf(name) {
   return r;
 }
 
-/** The default list view. */
-export function ResourceList({ resource, listColumns, display, base = '.' }) {
+/**
+ * The default list view. `filter` lists only the records whose fields equal it (a has-many tab); `base`
+ * null renders the rows without links to their pages (the related resource's pages are not mounted here).
+ */
+export function ResourceList({ resource, listColumns, display, base = '.', filter }) {
   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 { records, cursor, error, more } = useList(resource, { filter });
+  const show = badged(resource, display, useDisplay(resource, display, useRelationLabels(resource, records)));
   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 });
+  const first = (r, c) => {
+    const label = show(c, r) || recordLabel(resource, r);
+    return base === null ? label : h(LinkTo, { to: `${base}/${encodeURIComponent(r.id)}` }, label);
+  };
   return h(
     'section',
     { className: 'resource-list' },
-    h('h1', null, model.human({ count: 2 })),
+    base === null ? null : 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() }))),
+    base === null ? null : h('p', null, h(LinkTo, { to: `${base}/new`, className: 'button' }, i18n.t('helpers.resource.new', { model: model.human() }))),
     h(
       'table',
       null,
@@ -98,28 +122,71 @@ export function ResourceList({ resource, listColumns, display, base = '.' }) {
           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)),
-            ),
+            columns.map((c, i) => h('td', { key: c }, i === 0 ? first(r, c) : show(c, r))),
           ),
         ),
       ),
     ),
-    cursor ? h('p', null, h('button', { type: 'button', onClick: () => load(cursor) }, i18n.t('helpers.resource.more'))) : null,
+    cursor ? h('p', null, h('button', { type: 'button', onClick: () => more() }, i18n.t('helpers.resource.more'))) : null,
   );
 }
 
-/** The default show view. */
-export function ResourceShow({ resource, display, id, base = '..' }) {
+/** The has-many relations a `tabs` option names, resolved against the projection — [{entity, field}]. */
+export function resolveTabs(projection, resource, tabs = []) {
+  const all = hasManyRelations(projection, resource.entity);
+  return tabs.map((entry) => {
+    const [entity, field] = String(entry).split('.');
+    const matches = all.filter((r) => r.entity === entity && (field === undefined || r.field === field));
+    if (matches.length === 0) throw new Error(`resource "${resource.entity}" has no has-many relation "${entry}"`);
+    if (matches.length > 1) {
+      throw new Error(
+        `"${entity}" relates to "${resource.entity}" through more than one field (${matches.map((m) => `${m.entity}.${m.field}`).join(', ')}): name the tab "<entity>.<field>"`,
+      );
+    }
+    return { ...matches[0], qualified: field !== undefined };
+  });
+}
+
+/** The show view's has-many tabs: a tab per relation, its panel the related records of the shown one. */
+export function ResourceTabs({ resource, id, tabs }) {
+  const i18n = useI18n();
+  const { projection } = useSite();
+  const relations = useMemo(() => resolveTabs(projection, resource, tabs), [projection, resource, tabs]);
+  const [active, setActive] = useState(0);
+  if (relations.length === 0) return null;
+  const label = (rel) => {
+    const target = projection.resources[rel.entity];
+    const name = modelName(target, { i18n }).human({ count: 2 });
+    return rel.qualified ? `${name} (${humanAttributeName(target, rel.field, { i18n })})` : name;
+  };
+  const current = relations[Math.min(active, relations.length - 1)];
+  return h(
+    'section',
+    { className: 'resource-tabs' },
+    h(
+      'nav',
+      { role: 'tablist' },
+      relations.map((rel, i) =>
+        h('button', { key: `${rel.entity}.${rel.field}`, type: 'button', role: 'tab', 'aria-selected': String(rel === current), onClick: () => setActive(i) }, label(rel)),
+      ),
+    ),
+    h(
+      'div',
+      { role: 'tabpanel' },
+      h(ResourceList, { key: `${current.entity}.${current.field}`, resource: projection.resources[current.entity], filter: { [current.field]: id }, base: null }),
+    ),
+  );
+}
+
+/** The default show view (with `tabs`, the has-many tabs below the record). */
+export function ResourceShow({ resource, display, id, base = '..', tabs }) {
   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]);
+  const { record, error: readError } = useRecord(resource, id);
+  const [actionError, setError] = useState(null);
+  const error = actionError ?? readError;
+  const records = useMemo(() => (record ? [record] : []), [record]);
+  const show = badged(resource, display, useDisplay(resource, display, useRelationLabels(resource, records)));
   return h(
     'section',
     { className: 'resource-show' },
@@ -152,21 +219,18 @@ export function ResourceShow({ resource, display, id, base = '..' }) {
       ),
       h(LinkTo, { to: base }, i18n.t('helpers.resource.back')),
     ),
+    tabs?.length ? h(ResourceTabs, { resource, id, tabs }) : null,
   );
 }
 
-/** The default form view (new when `id` is absent, edit otherwise). */
+/** The default form view (new when `id` is absent, edit otherwise); a relation is a select over its target. */
 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 { record, error } = useRecord(resource, id);
   const model = modelName(resource, { i18n });
-  if (record === undefined) return h(ErrorMessages, { error });
+  if (id !== undefined && !record) return h(ErrorMessages, { error });
   return h(
     'section',
     { className: 'resource-form' },
@@ -189,7 +253,7 @@ export function ResourceForm({ resource, fields, id, base = '..' }) {
 function ShowRoute({ resource, options }) {
   const { id } = useParams();
   const View = options.Show ?? ResourceShow;
-  return h(View, { resource, id, display: options.display, Default: ResourceShow, base: '..' });
+  return h(View, { resource, id, display: options.display, tabs: options.tabs, Default: ResourceShow, base: '..' });
 }
 
 function EditRoute({ resource, options }) {
@@ -213,7 +277,7 @@ export function Resource({ name, options = {} }) {
   );
 }
 
-/** export default resourcePage("pet", { listColumns: ["name", "species"] }) */
+/** export default resourcePage("owner", { listColumns: ["name"], tabs: ["pet"] }) */
 export function resourcePage(name, options = {}) {
   function ResourcePage() {
     return h(Resource, { name, options });