@volter/world-ui 0.1.0

package/client/consent.tsx

@@ -0,0 +1,96 @@
+// AN OAUTH CONSENT — the hosted flow every OAuth vendor puts between an application and its user
+// (docs/contributing/architecture.md, "Screens"): who asks, for which account, for what, and the two
+// answers. The page is a plain form rendered on the server, so a click posts and the vendor's redirect
+// follows with no script, as on the vendor's own page. A pack gives the words and the fields its
+// documented round trip carries, and its skin gives the look; the controls carry the vendor's names so
+// a test that finds them by role and name finds them.
+export type ConsentPermission = { title: string; detail: string; help?: string };
+
+export type ConsentProps = {
+  /** the page's heading, the vendor's words ("Authorize Acme") */
+  heading: string;
+  app: { name: string; by?: string };
+  /** the vendor's sentence under the app's name ("wants to access your octocat account") */
+  request: string;
+  permissions: ConsentPermission[];
+  /** where the form posts, and the fields the vendor's form carries */
+  action: string;
+  fields: Record<string, string>;
+  /** the two submit buttons: their field, value and label; without `allow` the person can only decline (a consent with
+   *  nothing to grant, as Slack's with no channel for an incoming webhook) */
+  deny: { name: string; value: string; label: string };
+  allow?: { name: string; value: string; label: string };
+  /** under the buttons: where authorizing sends the person */
+  note?: string;
+  /** what the person picks before answering (Slack's channel an incoming webhook posts to): each a labelled select the
+   *  form carries, as the payment and portal pieces carry theirs */
+  choices?: Array<{ id: string; label: string; value?: string; options: Array<{ value: string; label: string }> }>;
+};
+
+export function Consent(props: ConsentProps) {
+  return (
+    <main className="consent">
+      <div className="consent-badges" aria-hidden="true">
+        <span className="consent-badge">{props.app.name.slice(0, 1).toUpperCase()}</span>
+        <span className="consent-link" />
+        <span className="consent-badge consent-vendor" />
+      </div>
+      <h1 className="consent-heading">{props.heading}</h1>
+      <div className="consent-box">
+        <div className="consent-who">
+          <strong>{props.app.name}</strong>
+          {props.app.by ? <> by <strong>{props.app.by}</strong></> : null}
+          <small>{props.request}</small>
+        </div>
+        <ul className="consent-permissions">
+          {props.permissions.map((p) => (
+            <li key={p.title} className="consent-permission">
+              <details>
+                <summary>
+                  <strong className="consent-permission-title">{p.title}</strong>
+                  <small>{p.detail}</small>
+                </summary>
+                {p.help ? <p>{p.help}</p> : null}
+              </details>
+            </li>
+          ))}
+        </ul>
+        <form method="post" action={props.action} className="consent-form">
+          {Object.entries(props.fields).map(([name, value]) => <input key={name} type="hidden" name={name} id={name} value={value} />)}
+          {(props.choices ?? []).map((c) => (
+            <label key={c.id} className="consent-choice" htmlFor={c.id}>
+              <span>{c.label}</span>
+              <select id={c.id} name={c.id} defaultValue={c.value}>{c.options.map((o) => <option key={o.value} value={o.value}>{o.label}</option>)}</select>
+            </label>
+          ))}
+          <div className="consent-actions">
+            <button type="submit" name={props.deny.name} value={props.deny.value} className="consent-deny">{props.deny.label}</button>
+            {props.allow ? <button type="submit" name={props.allow.name} value={props.allow.value} className="consent-allow">{props.allow.label}</button> : null}
+          </div>
+          {props.note ? <p className="consent-note">{props.note}</p> : null}
+        </form>
+      </div>
+    </main>
+  );
+}
+
+/** The consent's layout; a pack's skin sets the colours and type over it. */
+export const CONSENT_CSS = `
+body { margin: 0; font: 14px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; }
+.consent { max-width: 530px; margin: 0 auto; padding: 24px 16px; }
+.consent-badges { display: flex; align-items: center; justify-content: space-between; width: 240px; margin: 16px auto; }
+.consent-badge { display: grid; place-items: center; width: 64px; height: 64px; border-radius: 50%; font-size: 28px; font-weight: 600; }
+.consent-link { flex: 1; margin: 0 12px; border-top: 2px dashed; }
+.consent-heading { text-align: center; font-weight: 400; font-size: 24px; margin: 16px 0 24px; }
+.consent-box { border: 1px solid; border-radius: 6px; padding: 16px 24px; }
+.consent-who small { display: block; }
+.consent-permissions { list-style: none; padding: 0; margin: 16px 0; }
+.consent-permission { padding: 8px 0; }
+.consent-permission summary { cursor: pointer; list-style: none; }
+.consent-permission summary small { display: block; }
+.consent-choice { display: flex; flex-direction: column; gap: 4px; margin: 8px 0 16px; font-weight: 600; }
+.consent-choice select { font: inherit; font-weight: 400; padding: 6px; }
+.consent-actions { display: flex; gap: 8px; padding-top: 16px; border-top: 1px solid; }
+.consent-actions button { flex: 1; padding: 6px 16px; border-radius: 6px; font: inherit; font-weight: 500; cursor: pointer; border: 1px solid; }
+.consent-note { text-align: center; font-size: 12px; margin: 12px 0 0; }
+`;

package/client/kit.css

@@ -0,0 +1,55 @@
+/* The twin UI kit's base: layout and pieces. A pack's own stylesheet is its skin: it sets the
+   variables below (and anything else of the vendor's look) and is loaded after this one. Unskinned,
+   the kit wears the Volter brand's roles (company decision 0018): the shell links the brand's tokens
+   (assets/brand/tokens.css, fetched at build) before this sheet, and the pre-commit hook refuses a
+   literal colour here. */
+:root {
+  --tw-accent: var(--volter-action-default);
+  --tw-bg: var(--volter-surface-page);
+  --tw-nav-bg: var(--volter-surface-subtle);
+  --tw-text: var(--volter-text-primary);
+  --tw-muted: var(--volter-text-muted);
+  --tw-border: var(--volter-border-default);
+  --tw-ok: var(--volter-status-healthy-text);
+  --tw-warn: var(--volter-status-attention-text);
+  --tw-bad: var(--volter-status-danger-text);
+  --tw-font: var(--volter-font-ui);
+}
+* { box-sizing: border-box; }
+body { margin: 0; font-family: var(--tw-font); color: var(--tw-text); background: var(--tw-bg); }
+button { font: inherit; }
+.tw-app { display: grid; grid-template-columns: 240px 1fr; min-height: 100vh; }
+.tw-nav { background: var(--tw-nav-bg); border-right: 1px solid var(--tw-border); padding: 12px 8px; display: flex; flex-direction: column; gap: 2px; overflow-y: auto; }
+.tw-nav button { text-align: left; background: none; border: 0; padding: 6px 10px; border-radius: 6px; color: var(--tw-text); cursor: pointer; display: flex; justify-content: space-between; }
+.tw-nav button:hover { background: var(--volter-overlay-hover); }
+.tw-nav .tw-on, .tw-nav .tw-on:hover { background: var(--tw-accent); color: var(--volter-text-on-strong); }
+.tw-brand { font-weight: 700; font-size: 16px; margin-bottom: 8px; flex-direction: column; }
+.tw-brand small { font-weight: 400; color: var(--tw-muted); font-size: 12px; }
+.tw-count { color: var(--tw-muted); font-size: 12px; margin-left: 8px; }
+.tw-main { padding: 20px 28px; overflow: auto; }
+.tw-main h1 { font-size: 20px; display: flex; align-items: center; gap: 8px; }
+.tw-list { list-style: none; padding: 0; margin: 0; border: 1px solid var(--tw-border); border-radius: 6px; }
+.tw-list li + li { border-top: 1px solid var(--tw-border); }
+.tw-list button { width: 100%; background: none; border: 0; padding: 10px 14px; display: grid; grid-template-columns: 1fr 1fr auto; gap: 12px; text-align: left; cursor: pointer; }
+.tw-list button:hover { background: var(--tw-nav-bg); }
+.tw-list span { color: var(--tw-muted); }
+.tw-empty { padding: 12px 14px; color: var(--tw-muted); }
+.tw-pill { font-size: 12px; padding: 1px 8px; border-radius: 10px; border: 1px solid currentColor; white-space: nowrap; }
+.tw-pill-ok { color: var(--tw-ok); }
+.tw-pill-warn { color: var(--tw-warn); }
+.tw-pill-bad { color: var(--tw-bad); }
+.tw-pill-muted { color: var(--tw-muted); }
+.tw-ref { font: inherit; font-size: 13px; background: none; border: 1px solid var(--tw-border); border-radius: 4px; padding: 0 6px; color: var(--tw-accent); cursor: pointer; }
+.tw-fields { margin: 12px 0; }
+.tw-field { display: grid; grid-template-columns: 220px 1fr; gap: 12px; padding: 3px 0; border-bottom: 1px dashed var(--tw-border); }
+.tw-field dt { color: var(--tw-muted); }
+.tw-field dd { margin: 0; word-break: break-all; }
+.tw-actions { display: flex; gap: 8px; flex-wrap: wrap; margin: 8px 0; }
+.tw-actions button, .tw-create button { background: var(--tw-accent); color: var(--volter-text-on-strong); border: 0; border-radius: 6px; padding: 6px 12px; cursor: pointer; text-transform: capitalize; }
+.tw-create { display: flex; gap: 8px; flex-wrap: wrap; align-items: end; margin-bottom: 12px; }
+.tw-create label { display: flex; flex-direction: column; font-size: 12px; color: var(--tw-muted); }
+.tw-create input { border: 1px solid var(--tw-border); border-radius: 6px; padding: 5px 8px; font: inherit; }
+.tw-back { background: none; border: 0; color: var(--tw-accent); cursor: pointer; padding: 0; }
+.tw-error { color: var(--tw-bad); width: 100%; }
+.tw-home ul { list-style: none; padding: 0; display: grid; grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: 8px; }
+.tw-home button { width: 100%; text-align: left; background: var(--tw-nav-bg); border: 1px solid var(--tw-border); border-radius: 6px; padding: 12px; cursor: pointer; }

package/client/kit.tsx

@@ -0,0 +1,312 @@
+// THE TWIN UI KIT — shared pieces for a derived pack's screens (docs/contributing/architecture.md,
+// "Screens"): the shell and navigation, lists and details, references, state pills, the moves a machine
+// allows from a row's state, and create forms, all through the vendor's own API. A pack builds the
+// screens people work in from these under its skin. It is not a vendor's UI on its own: TwinUi's
+// generic resource browser renders any declared resource and so answers what a World holds, which a
+// vendor's screens never pose as.
+import React, { useCallback, useEffect, useMemo, useState, type ReactNode } from 'react';
+import { createRoot } from 'react-dom/client';
+
+export type Row = Record<string, any>;
+
+export type UiAction = { operation: string; method: string; path: string; field: string; from: string[] | '*'; to?: string };
+export type UiResource = {
+  list?: string;
+  retrieve?: string;
+  create?: { path: string; encoding: string; body: Array<{ name: string; type: string; required: boolean }> };
+  actions: UiAction[];
+  states: Record<string, string[]>;
+  embeds: Record<string, string>;
+};
+export type UiData = { resources: Record<string, UiResource> };
+
+/** One entry of the navigation: a resource's list, titled the vendor's way. */
+export type Section = {
+  resource: string;
+  label: string;
+  /** where it is listed, when not the resource's own list (a sub-collection) */
+  list?: string;
+  title?: (row: Row) => string;
+  subtitle?: (row: Row) => string;
+  /** what the vendor's detail page shows beyond the fields (a balance panel, an error banner) */
+  extras?: (row: Row) => ReactNode;
+};
+
+/** A screen of the vendor's UI that is not a resource view (a chat, a board, a canvas). */
+export type Screen = { key: string; label: string; render: (api: Api) => ReactNode };
+
+export type TwinUiConfig = {
+  skin: { name: string; product?: string };
+  ui: UiData;
+  sections: Section[];
+  screens?: Screen[];
+  /** headers every call carries (the fake credential the vendor's API asks for) */
+  headers?: Record<string, string>;
+  /** how the vendor's lists hold their rows: `data` (Stripe, OpenAI), the whole body (GitHub), or a key */
+  rowsAt?: (body: any, resource: string) => Row[];
+  /** a value's tone for its status pill */
+  tone?: (value: string) => 'ok' | 'warn' | 'bad' | 'muted';
+};
+
+// ── talking to the vendor's API ────────────────────────────────────────────────────────────
+
+const BASE = typeof document === 'undefined' || document.querySelector('base[href]') === null ? '' : new URL('.', document.baseURI).pathname.replace(/\/$/, '');
+
+export type Api = {
+  get: (path: string) => Promise<any>;
+  send: (method: string, path: string, body?: Record<string, unknown>, encoding?: string) => Promise<{ status: number; body: any }>;
+};
+
+function formEncode(value: unknown, prefix: string, out: URLSearchParams): void {
+  if (value === undefined || value === '') return;
+  if (value && typeof value === 'object') {
+    for (const [k, v] of Object.entries(value as Record<string, unknown>)) formEncode(v, prefix ? `${prefix}[${k}]` : k, out);
+  } else out.append(prefix, String(value));
+}
+
+export function makeApi(headers: Record<string, string> = {}): Api {
+  return {
+    get: (path) => fetch(`${BASE}${path}`, { headers }).then((r) => r.json()),
+    send: async (method, path, body, encoding = 'json') => {
+      const init: RequestInit = { method, headers: { ...headers } };
+      if (body && Object.keys(body).length) {
+        if (encoding === 'form') {
+          const p = new URLSearchParams();
+          formEncode(body, '', p);
+          init.body = p.toString();
+          (init.headers as Record<string, string>)['content-type'] = 'application/x-www-form-urlencoded';
+        } else {
+          init.body = JSON.stringify(body);
+          (init.headers as Record<string, string>)['content-type'] = 'application/json';
+        }
+      }
+      const r = await fetch(`${BASE}${path}`, init);
+      const text = await r.text();
+      let parsed: any = text;
+      try { parsed = text ? JSON.parse(text) : null; } catch { /* a non-JSON answer stays text */ }
+      return { status: r.status, body: parsed };
+    },
+  };
+}
+
+const fill = (path: string, id: string): string => path.replace(/\{[^}]+\}/, encodeURIComponent(id));
+const defaultRows = (body: any): Row[] => (Array.isArray(body) ? body : Array.isArray(body?.data) ? body.data : []);
+
+// ── pieces ───────────────────────────────────────────────────────────────────────────────
+
+export function StatusPill({ value, tone }: { value: unknown; tone?: TwinUiConfig['tone'] }) {
+  if (value === undefined || value === null || value === '') return null;
+  const t = tone?.(String(value)) ?? (/(succeeded|paid|active|open|completed|ok|true)/.test(String(value)) ? 'ok' : /(fail|canceled|cancelled|void|closed|expired|error|false)/.test(String(value)) ? 'bad' : 'muted');
+  return <span className={`tw-pill tw-pill-${t}`}>{String(value)}</span>;
+}
+
+export function RefChip({ label, onJump }: { label: string; onJump: () => void }) {
+  return (
+    <button type="button" className="tw-ref" onClick={onJump}>
+      {label}
+    </button>
+  );
+}
+
+/** An object as the vendor's detail page lists it: one line per field, nested objects indented, references as chips. */
+export function Fields({ row, embeds, onJump }: { row: Row; embeds: Record<string, string>; onJump: (resource: string, id: string) => void }) {
+  const lines: Array<{ key: string; depth: number; value: ReactNode }> = [];
+  const walk = (obj: Row, depth: number, prefix: string) => {
+    for (const [k, v] of Object.entries(obj)) {
+      const key = prefix ? `${prefix}.${k}` : k;
+      if (v && typeof v === 'object' && !Array.isArray(v)) {
+        lines.push({ key, depth, value: '' });
+        walk(v, depth + 1, key);
+      } else if (depth === 0 && embeds[k] && typeof v === 'string') {
+        lines.push({ key, depth, value: <RefChip label={v} onJump={() => onJump(embeds[k]!, v)} /> });
+      } else lines.push({ key, depth, value: Array.isArray(v) ? JSON.stringify(v) : String(v) });
+    }
+  };
+  walk(row, 0, '');
+  return (
+    <dl className="tw-fields">
+      {lines.map((l) => (
+        <div key={l.key} className="tw-field" style={{ paddingLeft: `${l.depth * 16}px` }}>
+          <dt>{l.key.split('.').at(-1)}</dt>
+          <dd>{l.value}</dd>
+        </div>
+      ))}
+    </dl>
+  );
+}
+
+/** The moves the resource's machine allows from where this row stands, as buttons. */
+export function Actions({ resource, row, api, onDone }: { resource: UiResource; row: Row; api: Api; onDone: () => void }) {
+  const [error, setError] = useState<string | null>(null);
+  const legal = resource.actions.filter((a) => a.from === '*' || a.from.includes(String(row[a.field])));
+  const seen = new Set<string>();
+  const unique = legal.filter((a) => (seen.has(a.operation) ? false : (seen.add(a.operation), true)));
+  if (!unique.length) return null;
+  return (
+    <div className="tw-actions">
+      {unique.map((a) => (
+        <button
+          key={a.operation}
+          type="button"
+          onClick={async () => {
+            setError(null);
+            const r = await api.send(a.method, fill(a.path, String(row.id)), undefined, resource.create?.encoding);
+            if (r.status >= 400) setError(r.body?.error?.message ?? r.body?.message ?? r.body?.error ?? `HTTP ${r.status}`);
+            onDone();
+          }}
+        >
+          {a.path.split('/').at(-1)!.replace(/[_-]/g, ' ')}
+        </button>
+      ))}
+      {error ? <p className="tw-error">{String(error)}</p> : null}
+    </div>
+  );
+}
+
+/** A form for the resource's create operation: its required parameters, and any others the caller fills. */
+export function CreateForm({ resource, api, onCreated }: { resource: UiResource; api: Api; onCreated: (row: Row) => void }) {
+  const create = resource.create;
+  const [values, setValues] = useState<Record<string, string>>({});
+  const [error, setError] = useState<string | null>(null);
+  if (!create) return null;
+  const fields = create.body.filter((b) => b.required || ['name', 'email', 'description', 'title', 'amount', 'currency'].includes(b.name));
+  return (
+    <form
+      className="tw-create"
+      onSubmit={async (e) => {
+        e.preventDefault();
+        setError(null);
+        const r = await api.send('POST', create.path, values, create.encoding);
+        if (r.status >= 400) setError(r.body?.error?.message ?? r.body?.message ?? `HTTP ${r.status}`);
+        else onCreated(r.body);
+      }}
+    >
+      {fields.map((f) => (
+        <label key={f.name}>
+          {f.name}
+          {f.required ? ' *' : ''}
+          <input value={values[f.name] ?? ''} onChange={(e) => setValues({ ...values, [f.name]: e.target.value })} />
+        </label>
+      ))}
+      <button type="submit">Create</button>
+      {error ? <p className="tw-error">{String(error)}</p> : null}
+    </form>
+  );
+}
+
+// ── the app ──────────────────────────────────────────────────────────────────────────────
+
+type Route = { kind: 'home' } | { kind: 'list'; section: Section } | { kind: 'detail'; section: Section; id: string } | { kind: 'screen'; screen: Screen };
+
+export function TwinUi({ config }: { config: TwinUiConfig }) {
+  const api = useMemo(() => makeApi(config.headers), [config.headers]);
+  const [route, setRoute] = useState<Route>({ kind: 'home' });
+  const [rows, setRows] = useState<Row[]>([]);
+  const [detail, setDetail] = useState<Row | null>(null);
+  const [counts, setCounts] = useState<Record<string, number>>({});
+  const [tick, setTick] = useState(0);
+  const rowsOf = config.rowsAt ?? defaultRows;
+  const listPath = (s: Section) => s.list ?? config.ui.resources[s.resource]?.list;
+  const bySection = (resource: string) => config.sections.find((s) => s.resource === resource);
+
+  useEffect(() => {
+    for (const s of config.sections) {
+      const p = listPath(s);
+      if (p && !p.includes('{')) api.get(p).then((b) => setCounts((c) => ({ ...c, [s.label]: rowsOf(b, s.resource).length }))).catch(() => undefined);
+    }
+  }, [tick]);
+
+  useEffect(() => {
+    if (route.kind === 'list') {
+      const p = listPath(route.section);
+      if (p) api.get(p).then((b) => setRows(rowsOf(b, route.section.resource))).catch(() => setRows([]));
+    }
+    if (route.kind === 'detail') {
+      const r = config.ui.resources[route.section.resource];
+      const fromList = rows.find((x) => String(x.id) === route.id) ?? null;
+      if (r?.retrieve && (r.retrieve.match(/\{/g) ?? []).length === 1) api.get(fill(r.retrieve, route.id)).then(setDetail).catch(() => setDetail(fromList));
+      else setDetail(fromList);
+    }
+  }, [route, tick]);
+
+  const jump = useCallback((resource: string, id: string) => {
+    const s = bySection(resource);
+    if (s) setRoute({ kind: 'detail', section: s, id });
+  }, []);
+
+  return (
+    <div className="tw-app">
+      <nav className="tw-nav">
+        <button type="button" className="tw-brand" onClick={() => setRoute({ kind: 'home' })}>
+          {config.skin.name}
+          {config.skin.product ? <small>{config.skin.product}</small> : null}
+        </button>
+        {(config.screens ?? []).map((s) => (
+          <button key={s.key} type="button" className={route.kind === 'screen' && route.screen.key === s.key ? 'tw-on' : ''} onClick={() => setRoute({ kind: 'screen', screen: s })}>
+            {s.label}
+          </button>
+        ))}
+        {config.sections.map((s) => (
+          <button key={s.label} type="button" className={route.kind !== 'home' && route.kind !== 'screen' && route.section.label === s.label ? 'tw-on' : ''} onClick={() => setRoute({ kind: 'list', section: s })}>
+            {s.label}
+            {counts[s.label] !== undefined ? <span className="tw-count">{counts[s.label]}</span> : null}
+          </button>
+        ))}
+      </nav>
+      <main className="tw-main">
+        {route.kind === 'home' ? (
+          <section className="tw-home">
+            <h1>{config.skin.name}</h1>
+            <ul>
+              {config.sections.map((s) => (
+                <li key={s.label}>
+                  <button type="button" onClick={() => setRoute({ kind: 'list', section: s })}>
+                    {s.label} <span className="tw-count">{counts[s.label] ?? '…'}</span>
+                  </button>
+                </li>
+              ))}
+            </ul>
+          </section>
+        ) : null}
+        {route.kind === 'screen' ? route.screen.render(api) : null}
+        {route.kind === 'list' ? (
+          <section>
+            <h1>{route.section.label}</h1>
+            {config.ui.resources[route.section.resource] ? <CreateForm resource={config.ui.resources[route.section.resource]!} api={api} onCreated={() => setTick((t) => t + 1)} /> : null}
+            <ul className="tw-list">
+              {rows.map((r) => (
+                <li key={String(r.id)}>
+                  <button type="button" onClick={() => setRoute({ kind: 'detail', section: route.section, id: String(r.id) })}>
+                    <strong>{route.section.title?.(r) ?? String(r.name ?? r.title ?? r.id)}</strong>
+                    <span>{route.section.subtitle?.(r) ?? String(r.id)}</span>
+                    <StatusPill value={r.status ?? r.state} tone={config.tone} />
+                  </button>
+                </li>
+              ))}
+              {rows.length === 0 ? <li className="tw-empty">None yet.</li> : null}
+            </ul>
+          </section>
+        ) : null}
+        {route.kind === 'detail' && detail ? (
+          <section>
+            <button type="button" className="tw-back" onClick={() => setRoute({ kind: 'list', section: route.section })}>
+              ← {route.section.label}
+            </button>
+            <h1>
+              {route.section.title?.(detail) ?? String(detail.name ?? detail.title ?? detail.id)} <StatusPill value={detail.status ?? detail.state} tone={config.tone} />
+            </h1>
+            {route.section.extras?.(detail)}
+            {config.ui.resources[route.section.resource] ? <Actions resource={config.ui.resources[route.section.resource]!} row={detail} api={api} onDone={() => setTick((t) => t + 1)} /> : null}
+            <Fields row={detail} embeds={config.ui.resources[route.section.resource]?.embeds ?? {}} onJump={jump} />
+          </section>
+        ) : null}
+      </main>
+    </div>
+  );
+}
+
+/** Mount a pack's UI into the shell's #root. */
+export function mountTwinUi(config: TwinUiConfig): void {
+  if (typeof document === 'undefined') return;
+  createRoot(document.getElementById('root')!).render(<TwinUi config={config} />);
+}

package/client/payment.tsx

@@ -0,0 +1,121 @@
+// A HOSTED PAYMENT PAGE — the hosted flow a payments vendor puts between an application's "Buy" and its
+// success page (docs/contributing/architecture.md, "Screens"): what is being paid for, the fields the
+// customer fills, one submit, and the way back. A plain form rendered on the server: the submit posts and
+// the vendor's redirect follows with no script. A pack names its fields and controls the vendor's way
+// (ids, names, labels), since applications' tests fill a vendor's payment fields by those names; its skin
+// gives the look.
+export type PaymentField = {
+  id: string; label: string; type?: string; placeholder?: string; autoComplete?: string; value?: string; options?: Array<{ value: string; label: string }>;
+  /** a field that formats itself as it is typed, as payment vendors' card fields do: `card-expiry` reads the digits
+   *  `1230` as `12 / 30` (FORMAT_SCRIPT). The page still posts without a script; the pack reads what is posted. */
+  format?: 'card-expiry';
+};
+
+export type PaymentProps = {
+  merchant: string;
+  /** what is paid for, formatted the vendor's way */
+  lines: Array<{ name: string; amount: string; detail?: string }>;
+  /** the lead of the summary: a label over the amount, and a line under it ("Then $12.00 per month") */
+  total?: { label: string; amount: string; detail?: string };
+  action: string;
+  /** sections of fields, each under its heading ("Contact information", "Payment method") */
+  sections: Array<{ heading: string; fields: PaymentField[] }>;
+  submit: { label: string; testId?: string };
+  back?: { href: string; label: string };
+  /** the vendor's answer to the last submit, shown above the button */
+  error?: string;
+  /** terms shown under the button (what a trial's end will charge) */
+  note?: string;
+};
+
+/** Formats a `format`ted field as it is typed, a progressive enhancement over the plain form. `card-expiry`, as a card
+ *  form's expiry reads: four digits at most, ` / ` after the month; a first digit above 1 is the month on its own
+ *  (`5` → `05 / `), as is a single digit followed by a slash (`1/` → `01 / `); a pasted or filled `12/2030` or
+ *  `122030` keeps the year's last two digits; deleting the year's last digit leaves `12 / `, and deleting back into
+ *  the separator removes it. */
+export const FORMAT_SCRIPT = `document.querySelectorAll('input[data-format="card-expiry"]').forEach(function (el) {
+  el.addEventListener('input', function (e) {
+    var raw = el.value, deleting = typeof e.inputType === 'string' && e.inputType.indexOf('delete') === 0, mm, yy;
+    var cut = raw.indexOf('/');
+    if (cut >= 0) {
+      mm = raw.slice(0, cut).replace(/\\D/g, '').slice(0, 2);
+      yy = raw.slice(cut + 1).replace(/\\D/g, '');
+      if (mm.length === 1 && mm !== '0') mm = '0' + mm;
+    } else {
+      var d = raw.replace(/\\D/g, '');
+      if (d.length === 6 && d.slice(2, 4) === '20') d = d.slice(0, 2) + d.slice(4);
+      if (d.length >= 1 && d.charAt(0) > '1') d = '0' + d;
+      mm = d.slice(0, 2);
+      yy = d.slice(2);
+    }
+    yy = yy.length === 4 ? yy.slice(2) : yy.slice(0, 2);
+    el.value = mm.length < 2 || (deleting && !yy && raw.slice(-2) !== '/ ') ? mm : mm + ' / ' + yy;
+  });
+});`;
+
+export function Payment(props: PaymentProps) {
+  return (
+    <div className="pay">
+      <section className="pay-summary">
+        {props.back ? <a className="pay-back" href={props.back.href}>{props.back.label}</a> : null}
+        <div className="pay-merchant">{props.merchant}</div>
+        {props.total ? <div className="pay-total-lead"><span>{props.total.label}</span><strong>{props.total.amount}</strong>{props.total.detail ? <small className="pay-total-detail">{props.total.detail}</small> : null}</div> : null}
+        <ul className="pay-lines">
+          {props.lines.map((l, i) => (
+            <li key={`${l.name}:${i}`} className="pay-line">
+              <span className="pay-line-name">{l.name}{l.detail ? <small>{l.detail}</small> : null}</span>
+              <span className="pay-line-amount">{l.amount}</span>
+            </li>
+          ))}
+        </ul>
+      </section>
+      <main className="pay-form">
+        <form method="post" action={props.action}>
+          {props.sections.map((s) => (
+            <fieldset key={s.heading} className="pay-section">
+              <legend>{s.heading}</legend>
+              {s.fields.map((f) => (
+                <label key={f.id} className="pay-field" htmlFor={f.id}>
+                  <span>{f.label}</span>
+                  {f.options
+                    ? <select id={f.id} name={f.id} defaultValue={f.value}>{f.options.map((o) => <option key={o.value} value={o.value}>{o.label}</option>)}</select>
+                    : <input id={f.id} name={f.id} type={f.type ?? 'text'} placeholder={f.placeholder} autoComplete={f.autoComplete} defaultValue={f.value} {...(f.format ? { 'data-format': f.format, inputMode: 'numeric' as const } : {})} />}
+                </label>
+              ))}
+            </fieldset>
+          ))}
+          {props.error ? <p className="pay-error" role="alert">{props.error}</p> : null}
+          <button type="submit" className="pay-submit SubmitButton" data-testid={props.submit.testId}>{props.submit.label}</button>
+          {props.note ? <p className="pay-note">{props.note}</p> : null}
+        </form>
+        {props.sections.some((s) => s.fields.some((f) => f.format)) ? <script dangerouslySetInnerHTML={{ __html: FORMAT_SCRIPT }} /> : null}
+      </main>
+    </div>
+  );
+}
+
+/** The payment page's layout; a pack's skin sets the colours and type over it. */
+export const PAYMENT_CSS = `
+body { margin: 0; font: 14px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif; }
+.pay { display: grid; grid-template-columns: 1fr 1fr; min-height: 100vh; }
+@media (max-width: 800px) { .pay { grid-template-columns: 1fr; } }
+.pay-summary { padding: 48px 48px 24px; }
+.pay-back { display: inline-block; margin-bottom: 24px; text-decoration: none; }
+.pay-merchant { font-weight: 500; margin-bottom: 16px; }
+.pay-total-lead span { display: block; }
+.pay-total-lead strong { display: block; font-size: 36px; font-weight: 600; }
+.pay-total-lead { margin-bottom: 24px; }
+.pay-total-detail { display: block; }
+.pay-note { margin: 12px 0 0; font-size: 13px; text-align: center; }
+.pay-lines { list-style: none; padding: 0; margin: 0; }
+.pay-line { display: flex; justify-content: space-between; padding: 8px 0; }
+.pay-line small { display: block; }
+.pay-form { padding: 48px; }
+.pay-section { border: 0; padding: 0; margin: 0 0 24px; }
+.pay-section legend { font-weight: 500; margin-bottom: 8px; }
+.pay-field { display: block; margin-bottom: 12px; }
+.pay-field span { display: block; font-size: 13px; margin-bottom: 4px; }
+.pay-field input, .pay-field select { box-sizing: border-box; width: 100%; padding: 8px 12px; border-radius: 6px; border: 1px solid; font: inherit; }
+.pay-error { margin: 0 0 12px; }
+.pay-submit { width: 100%; padding: 12px; border: 0; border-radius: 6px; font: inherit; font-weight: 600; cursor: pointer; }
+`;