@uiresponse/renderer-react 0.1.0

package/src/core/actions.js

@@ -0,0 +1,201 @@
+/**
+ * Actions — the five verbs (actions.schema.json), and what this renderer does with each in v1.
+ *
+ *   set_param   ✅ executed. Writes a page parameter; datasets whose query reads it re-resolve.
+ *   refresh     ✅ executed. Re-resolves named datasets, or all of them.
+ *   open        ✅ executed. `url` opens (http/https only, mirroring A8). `record` calls the host's
+ *                  `onOpenRecord` — the renderer does not know where the source record lives.
+ *   navigate    ⛔ rendered DISABLED, wearing its reason. There is no page router in v1: the host
+ *                  owns page-to-page movement, and a navigate that silently did nothing would be
+ *                  worse than one that says it cannot.
+ *   mutate      ⛔ rendered DISABLED, wearing its reason. A write needs an authorizing resolver
+ *                  round-trip and an optimistic-update story; A5 puts authorization outside OBL, and
+ *                  a renderer that faked the write would be lying about the one thing that matters.
+ *
+ * `then` chains are SEQUENTIAL and ABORT ON FAILURE (A3). A chain whose first verb is disabled does
+ * not run its tail — "approve, then refresh" must not refresh without approving.
+ */
+import { isSelfRef } from "./value.js";
+import { evaluateCondition } from "./condition.js";
+
+export const DISABLED_VERBS = {
+  navigate: "Navigation between pages is the host application's job. This renderer draws one page.",
+  mutate: "Writes are disabled in v1. A mutation must be authorized by the resolver, and this renderer will not pretend a write succeeded.",
+};
+
+const NO_OVERLAY_HOST = "This page asks to be presented in an overlay, but the host supplied no `resolvePage`, so there is no page to present.";
+
+/**
+ * Why this renderer cannot execute this verb, or `null` if it can (DECISIONS A13).
+ *
+ * `navigate` is the one verb whose answer depends on the ACTION rather than only its type.
+ * `mode: "overlay"` says "present the destination without leaving here", and that is a thing this
+ * renderer CAN do — it draws a drawer over the page it is already drawing — provided the host handed
+ * it a way to obtain the destination document (`resolvePage`). Plain `push`/`replace` still belong to
+ * the host: this renderer draws one page and owns no router.
+ *
+ * Note what is NOT done here: an overlay-mode navigate is never silently downgraded to a push. §4's
+ * fallback (`overlay -> push`) is for a renderer that does not KNOW the member. This one knows it,
+ * and a renderer that knows a key and quietly does something else is the substitution §4 rule 3 is
+ * written against.
+ */
+export function verbReason(action, ctx) {
+  if (!action) return null;
+  if (action.type === "mutate") return DISABLED_VERBS.mutate;
+  if (action.type !== "navigate") return null;
+  if (action.mode === "overlay") return ctx?.openOverlay ? null : NO_OVERLAY_HOST;
+  return DISABLED_VERBS.navigate;
+}
+
+/** @deprecated Kept for hosts that inspect verbs without a context. Prefer `actionGate`. */
+export const isDisabledVerb = (action) => Boolean(action && DISABLED_VERBS[action.type]);
+
+/** The user-visible name of an action. Its own `label` — one source of truth (button has no label). */
+export const actionLabel = (action, fallback = "Run") => action?.label ?? fallback;
+
+/**
+ * Is this action currently allowed to run, and if not, why (DECISIONS A12)?
+ *
+ * Two independent gates, and they are different kinds of thing:
+ *   · `verbReason`   — THIS RENDERER cannot execute the verb. A property of the implementation.
+ *   · `enabled_when` — THE PAGE says the action does not apply right now. A property of the data.
+ *
+ * `enabled_when` is a UX AFFORDANCE, NEVER A SECURITY CONTROL. A 1.0 renderer does not know the key,
+ * ignores it, and draws an enabled button — a degradation that is a lie. The resolver owns
+ * authorization (A5) and is the only thing between a click and a write. We honour it here because a
+ * page that says "you cannot do this yet" should look like it means it, not because it protects
+ * anything.
+ *
+ * A condition that cannot be evaluated — an unresolved dataset — disables the action. An action that
+ * might not apply must not fire while we are still finding out whether it does.
+ */
+export function actionGate(action, ctx) {
+  if (!action) return { disabled: false, reason: null };
+
+  const unsupported = verbReason(action, ctx);
+  if (unsupported) return { disabled: true, reason: unsupported };
+  if (!action.enabled_when) return { disabled: false, reason: null };
+
+  let allowed;
+  try {
+    allowed = evaluateCondition(action.enabled_when, ctx?.scope);
+  } catch {
+    allowed = false;
+  }
+  if (allowed === true) return { disabled: false, reason: null };
+  return { disabled: true, reason: action.disabled_reason ?? "This action is not available right now." };
+}
+
+/**
+ * @param {object} action
+ * @param {object} ctx
+ * @param {(name:string, value:*) => void} ctx.setParam
+ * @param {(names:string[]|"all") => void} ctx.refresh
+ * @param {(spec:object) => void} [ctx.onOpenRecord]  host decides where a record lives
+ * @param {(msg:string) => void} [ctx.onNotice]
+ * @param {object} ctx.scope   binding scope, including `row` inside a repeating element
+ */
+export async function runAction(action, ctx) {
+  if (!action) return;
+
+  // The gate is checked HERE and not only at the button, because a `then` chain reaches actions no
+  // button ever drew — "approve, then mark reviewed" must not mark reviewed when the second action's
+  // own `enabled_when` says it does not apply.
+  const gate = actionGate(action, ctx);
+  if (gate.disabled) {
+    ctx.onNotice?.(gate.reason);
+    return; // abort the chain: a `then` after a verb that did not happen is a lie.
+  }
+
+  switch (action.type) {
+    case "navigate": {
+      // Only `overlay` reaches here; `verbReason` disabled the other two. The destination's params
+      // are resolved in the CURRENT scope — a row action passing `{"$bind": {…, "scope": "row"}}`
+      // means the row the user clicked, and it means it here, before the overlay exists.
+      const params = {};
+      for (const [key, value] of Object.entries(action.params ?? {})) params[key] = ctx.resolveValue(value, ctx.scope);
+      await ctx.openOverlay({ pageId: action.page, params });
+      break;
+    }
+    case "set_param": {
+      const value = ctx.resolveValue(action.value, ctx.scope);
+      ctx.setParam(action.param, value);
+      break;
+    }
+    case "refresh":
+      ctx.refresh(action.datasets === "all" ? "all" : action.datasets);
+      break;
+    case "open": {
+      if (action.url) {
+        // A8's scheme restriction, enforced again at the point of use. A page may be assembled from
+        // untrusted text, and a validator that ran yesterday is not a guarantee about this click.
+        if (!/^https?:\/\//i.test(action.url)) {
+          ctx.onNotice?.(`Refused to open a non-http(s) URL.`);
+          return;
+        }
+        window.open(action.url, action.target === "self" ? "_self" : "_blank", "noopener,noreferrer");
+      } else if (action.record) {
+        const id = ctx.resolveValue(action.record.id, ctx.scope);
+        if (!ctx.onOpenRecord) {
+          ctx.onNotice?.(`Opening ${action.record.dataset} record "${id}" needs a host. Pass \`onOpenRecord\` to <UIResponsePage>.`);
+          return;
+        }
+        ctx.onOpenRecord({ dataset: action.record.dataset, id, target: action.target ?? "new_window" });
+      }
+      break;
+    }
+    default:
+      ctx.onNotice?.(`Unknown action verb "${action.type}".`);
+      return;
+  }
+
+  for (const next of action.then ?? []) await runAction(next, ctx);
+}
+
+/**
+ * An `input`'s `on_change` — the one action that can name the control's own value, `{"$self": true}`.
+ *
+ * This function used to be an apology. A `select` could write the chosen option's row, because the
+ * page could spell that (`{"$bind": {…, "scope": "row"}}`); a `text`, `date` or `toggle` input wrote
+ * something the document had no way to name, so the renderer supplied it and DISCARDED the action's
+ * declared `value`. A renderer silently overriding the document it renders.
+ *
+ * `$self` ends that. The renderer supplies the control's value as `scope.self` and then resolves what
+ * the page actually wrote. Nothing is discarded, and a page whose text input declares
+ * `value: "hardcoded"` now writes "hardcoded", loudly and correctly, because that is what it says.
+ *
+ * ONE contract survives, and it is written down rather than inferred: clearing a `select` whose
+ * action binds the chosen option's row (the older, still-legal spelling) has no row to bind. Clearing
+ * means `set_param` to `null` — which is how "no filter" is spelled and why an unset predicate drops
+ * out entirely (DECISIONS R4) — so we say that, rather than resolve a binding against nothing. A
+ * select written with `{"$self": true}` needs none of this: its `self` is `null` when cleared.
+ */
+export async function runInputAction(action, ctx, { row, widgetValue }) {
+  const scope = { ...ctx.scope, row, self: widgetValue };
+
+  if (row === null && action?.type === "set_param" && !isSelfRef(action.value)) {
+    ctx.setParam(action.param, null);
+    for (const next of action.then ?? []) await runAction(next, { ...ctx, scope });
+    return;
+  }
+
+  await runWithConfirm(action, { ...ctx, scope });
+}
+
+/**
+ * A confirm gate. `mutate` with `operation: "delete"` cannot omit one; any verb may carry one.
+ *
+ * An action that cannot run is not confirmed first. Asking "Void this contract?" and then refusing
+ * to void it is a worse experience than the disabled button that should have been drawn instead.
+ */
+export async function runWithConfirm(action, ctx) {
+  if (action?.confirm && !actionGate(action, ctx).disabled) {
+    const { title, body, confirm_label } = action.confirm;
+    const ok = ctx.confirm
+      ? await ctx.confirm(action.confirm)
+      // eslint-disable-next-line no-alert
+      : window.confirm([title, body].filter(Boolean).join("\n\n") + (confirm_label ? `\n\n[${confirm_label}]` : ""));
+    if (!ok) return;
+  }
+  await runAction(action, ctx);
+}

package/src/core/condition.js

@@ -0,0 +1,90 @@
+/**
+ * `visible_when` — the condition grammar of `binding.schema.json#condition`, evaluated client-side
+ * against resolved data.
+ *
+ * This is how OBL has empty states, "only show the overdue banner if something is overdue", and
+ * permission-shaped UI without any of them becoming a block type (DECISIONS P5). It is also why a
+ * review agent cannot statically prove what a user saw — a cost the spec accepted knowingly.
+ *
+ * A block whose condition cannot yet be evaluated is `pending`, and a `pending` conditional block
+ * draws NOTHING — not even a skeleton.
+ *
+ * This is the opposite of the rule for unconditional blocks, and the asymmetry is the point. A
+ * skeleton is a promise that content is coming. For a `table` bound to a dataset, that promise is
+ * true. For a `text` block gated on "show this only if the queue is empty", it is a coin flip — and
+ * a skeleton that resolves to nothing is a flash of a thing that was never going to be there. The
+ * page still says it is loading, in the masthead, where it is saying it once rather than per-block.
+ */
+import { resolveValue, isPresent, UIResponseResolveError } from "./value.js";
+
+const asArray = (v) => (Array.isArray(v) ? v : [v]);
+
+/** JSON has no total order across types; compare numbers as numbers, dates as time, else strings. */
+function compare(a, b) {
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  const da = Date.parse(a), db = Date.parse(b);
+  if (!Number.isNaN(da) && !Number.isNaN(db)) return da - db;
+  const na = Number(a), nb = Number(b);
+  if (Number.isFinite(na) && Number.isFinite(nb)) return na - nb;
+  return String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0;
+}
+
+const eq = (a, b) => (a === b ? true : compare(a, b) === 0 && typeof a === typeof b);
+
+function comparison(cond, scope) {
+  const left = resolveValue(cond.left, scope);
+
+  switch (cond.op) {
+    // Unary operators take no `right` — the schema enforces that, so we never read one.
+    case "is_empty": return !isPresent(left) || left === "" || (Array.isArray(left) && left.length === 0);
+    case "is_not_empty": return isPresent(left) && left !== "" && !(Array.isArray(left) && left.length === 0);
+    case "is_true": return left === true;
+    case "is_false": return left === false;
+    default: break;
+  }
+
+  const right = resolveValue(cond.right, scope);
+
+  switch (cond.op) {
+    case "eq": return eq(left, right);
+    case "neq": return !eq(left, right);
+    // A comparison against absent data is FALSE, never a coerced 0. `null > 0` must not be true.
+    case "gt": return isPresent(left) && isPresent(right) && compare(left, right) > 0;
+    case "gte": return isPresent(left) && isPresent(right) && compare(left, right) >= 0;
+    case "lt": return isPresent(left) && isPresent(right) && compare(left, right) < 0;
+    case "lte": return isPresent(left) && isPresent(right) && compare(left, right) <= 0;
+    case "in": return asArray(right).some((r) => eq(left, r));
+    case "not_in": return !asArray(right).some((r) => eq(left, r));
+    case "contains":
+      if (Array.isArray(left)) return left.some((l) => eq(l, right));
+      return isPresent(left) && String(left).toLowerCase().includes(String(right).toLowerCase());
+    default: throw new UIResponseResolveError(`unknown condition operator "${cond.op}"`);
+  }
+}
+
+/** @returns {boolean} */
+export function evaluateCondition(cond, scope) {
+  if (!cond || typeof cond !== "object") return true;
+  if (Array.isArray(cond.all)) return cond.all.every((c) => evaluateCondition(c, scope));
+  if (Array.isArray(cond.any)) return cond.any.some((c) => evaluateCondition(c, scope));
+  if (cond.not) return !evaluateCondition(cond.not, scope);
+  return comparison(cond, scope);
+}
+
+/**
+ * Evaluate a block's `visible_when` in the three states it can be in.
+ *
+ * @returns {"visible" | "hidden" | "pending"}  `pending` means "its data has not arrived": show the
+ *          block's skeleton, because an absent block and an unloaded one are different claims.
+ */
+export function visibility(block, scope, datasetsReady) {
+  if (!block.visible_when) return "visible";
+  if (!datasetsReady) return "pending";
+  try {
+    return evaluateCondition(block.visible_when, scope) ? "visible" : "hidden";
+  } catch {
+    // A condition that throws (an `only` assertion, a dataset that failed) must not silently hide
+    // content. Show the block; its own error state will say what went wrong.
+    return "visible";
+  }
+}

package/src/core/empty.js

@@ -0,0 +1,44 @@
+/**
+ * `empty` — `binding.schema.json#emptyPolicy`.
+ *
+ * The most opinionated rule in OBL, and the one this renderer is built to keep:
+ *
+ *   "Rendering an unfiled royalty statement as '£0.00' is a lie the page tells confidently,
+ *    so `zero` must be typed by a human or chosen deliberately by a model."
+ *
+ * When `empty` is omitted, the default is `dash` — VISIBLE ABSENCE. Not a blank cell, not zero.
+ * A missing number must look missing, and it must look different from a number that happens to be
+ * small. That is why absence gets its own typographic treatment in this renderer rather than being
+ * the absence of treatment.
+ */
+
+/** The five dispositions, resolved from a policy that may be absent entirely. */
+export function emptyDisposition(policy) {
+  const show = policy?.show ?? "dash";
+  return { show, text: policy?.text };
+}
+
+/**
+ * Does this value need the empty policy at all?
+ *
+ * `0`, `""` and `false` are PRESENT. Only null/undefined are absent, plus NaN, which is what a
+ * failed numeric coercion leaves behind and must never render as "NaN".
+ */
+export function isEmptyValue(value) {
+  if (value === null || value === undefined) return true;
+  if (typeof value === "number" && Number.isNaN(value)) return true;
+  return false;
+}
+
+/** Does the whole BLOCK disappear? Only `hide` does that. */
+export const hidesBlock = (policy) => emptyDisposition(policy).show === "hide";
+
+/**
+ * What a renderer draws for an absent value.
+ * @returns {{kind: "dash"|"zero"|"blank"|"hide"|"text", text?: string}}
+ */
+export function emptyRender(policy) {
+  const { show, text } = emptyDisposition(policy);
+  if (show === "text") return { kind: "text", text: text ?? "" };
+  return { kind: show };
+}

package/src/core/format.js

@@ -0,0 +1,225 @@
+/**
+ * OBL `format` — the exact semantics of `binding.schema.json#format`, and nothing more.
+ *
+ * This file is the reason the first-party renderer exists (DECISIONS X4). Compiling OBL to OpenUI
+ * Lang dropped `format` entirely, so `1240000` drew as "1240000" where the page said
+ * `{as: "currency", currency: "GBP", compact: true}` and meant "£1.2M".
+ *
+ * Every key here passes the voice-renderer test (Principle 1): `compact: true` is "one point two
+ * million", which a speaker can say. There is no pattern string, no locale, no width. We format for
+ * the screen; a voice renderer formats the same object into speech from the same five keys.
+ *
+ *   as         number | currency | percent | date | relative_time | duration | bytes | text
+ *   currency   ISO 4217. May never contradict the bound column's own code (Phase 2 errors on that).
+ *   precision  fractional digits. Omitted lets us choose from magnitude.
+ *   compact    1_200_000 -> "1.2M"
+ *   sign       auto | always | never
+ *   date_style day | month | quarter | year | full | iso
+ */
+
+const COMPACT_STEPS = [
+  { at: 1e12, suffix: "T" },
+  { at: 1e9, suffix: "B" },
+  { at: 1e6, suffix: "M" },
+  { at: 1e3, suffix: "K" },
+];
+
+/** A number's "natural" precision when the page did not state one. */
+function inferPrecision(n, { compact, as }) {
+  const abs = Math.abs(n);
+  if (compact) return abs >= 1e3 && abs < 1e6 ? 0 : 1;
+  if (as === "currency") return abs >= 1000 ? 0 : 2;
+  if (as === "percent") return abs < 10 ? 1 : 0;
+  if (Number.isInteger(n)) return 0;
+  return abs < 1 ? 2 : abs < 100 ? 1 : 0;
+}
+
+function applySign(text, n, sign) {
+  if (sign === "never") return text.replace(/^-/, "");
+  if (sign === "always" && n > 0) return `+${text}`;
+  return text;
+}
+
+/** Group digits without a locale: OBL forbids locale in `format` (it is a rendering-host concern). */
+function group(intPart) {
+  return intPart.replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+}
+
+function fixed(n, precision) {
+  const s = Math.abs(n).toFixed(precision);
+  const [i, f] = s.split(".");
+  const body = f ? `${group(i)}.${f}` : group(i);
+  return n < 0 ? `-${body}` : body;
+}
+
+function compactNumber(n, precision) {
+  const abs = Math.abs(n);
+  for (const { at, suffix } of COMPACT_STEPS) {
+    if (abs >= at) {
+      const scaled = n / at;
+      // 1.0M reads worse than 1M; drop a trailing zero the page did not ask for.
+      const p = precision ?? (Math.abs(scaled) >= 100 ? 0 : 1);
+      const text = scaled.toFixed(p).replace(/\.0$/, "");
+      return `${text}${suffix}`;
+    }
+  }
+  return fixed(n, precision ?? 0);
+}
+
+const CURRENCY_SYMBOL = { GBP: "£", USD: "$", EUR: "€", JPY: "¥", AUD: "A$", CAD: "C$", CHF: "CHF ", SEK: "kr " };
+const currencyPrefix = (code) => CURRENCY_SYMBOL[code] ?? `${code} `;
+
+const MONTHS = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+
+function toDate(value) {
+  if (value instanceof Date) return value;
+  if (typeof value === "number") return new Date(value);
+  if (typeof value !== "string") return null;
+  // A bare `YYYY-MM-DD` is a calendar day, not an instant. Parsing it as UTC and rendering it in
+  // the viewer's zone moves a London contract to the previous day in New York. Pin it to noon.
+  const bare = /^\d{4}-\d{2}-\d{2}$/.test(value);
+  const d = new Date(bare ? `${value}T12:00:00` : value);
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+
+function formatDate(value, style) {
+  const d = toDate(value);
+  if (!d) return String(value);
+  const day = d.getDate();
+  const mon = MONTHS[d.getMonth()];
+  const year = d.getFullYear();
+  switch (style) {
+    case "iso": return d.toISOString().slice(0, 10);
+    case "year": return String(year);
+    case "quarter": return `Q${Math.floor(d.getMonth() / 3) + 1} ${year}`;
+    case "month": return `${mon} ${year}`;
+    case "full": return `${day} ${mon} ${year}`;
+    case "day":
+    default: return `${day} ${mon}`;
+  }
+}
+
+const MINUTE = 60, HOUR = 3600, DAY = 86400;
+
+/**
+ * "42 days ago", "in 3 weeks". Relative time is how OBL renders a date the page cares about the
+ * AGE of — and B7's whole point is that it cannot be sorted or filtered by, only stated.
+ */
+function formatRelative(value, now) {
+  const d = toDate(value);
+  if (!d) return String(value);
+  const seconds = Math.round((d.getTime() - now.getTime()) / 1000);
+  const past = seconds < 0;
+  const abs = Math.abs(seconds);
+  const say = (n, unit) => `${n} ${unit}${n === 1 ? "" : "s"}`;
+
+  let phrase;
+  if (abs < 45) return "just now";
+  else if (abs < 45 * MINUTE) phrase = say(Math.round(abs / MINUTE), "minute");
+  else if (abs < 22 * HOUR) phrase = say(Math.round(abs / HOUR), "hour");
+  else if (abs < 26 * DAY) phrase = say(Math.round(abs / DAY), "day");
+  else if (abs < 320 * DAY) phrase = say(Math.round(abs / (30 * DAY)), "month");
+  else phrase = say(Math.round(abs / (365 * DAY)), "year");
+
+  return past ? `${phrase} ago` : `in ${phrase}`;
+}
+
+/** A duration in SECONDS, stated the way a person says it. */
+function formatDuration(seconds, precision) {
+  const n = Number(seconds);
+  if (!Number.isFinite(n)) return String(seconds);
+  const abs = Math.abs(n);
+  if (abs < MINUTE) return `${fixed(n, precision ?? 0)}s`;
+  if (abs < HOUR) {
+    const m = Math.floor(abs / MINUTE);
+    const s = Math.round(abs % MINUTE);
+    return s ? `${m}m ${s}s` : `${m}m`;
+  }
+  if (abs < DAY) {
+    const h = Math.floor(abs / HOUR);
+    const m = Math.round((abs % HOUR) / MINUTE);
+    return m ? `${h}h ${m}m` : `${h}h`;
+  }
+  const d = Math.floor(abs / DAY);
+  const h = Math.round((abs % DAY) / HOUR);
+  return h ? `${d}d ${h}h` : `${d}d`;
+}
+
+const BYTE_STEPS = ["B", "KB", "MB", "GB", "TB", "PB"];
+function formatBytes(n, precision) {
+  let v = Number(n);
+  if (!Number.isFinite(v)) return String(n);
+  let i = 0;
+  while (Math.abs(v) >= 1024 && i < BYTE_STEPS.length - 1) { v /= 1024; i++; }
+  return `${fixed(v, precision ?? (i === 0 ? 0 : 1))} ${BYTE_STEPS[i]}`;
+}
+
+/**
+ * Render one resolved value under one `format` object.
+ *
+ * @param {*} value        the resolved value (already collapsed to a scalar by the binding layer)
+ * @param {object} [format] `binding.schema.json#format`
+ * @param {object} [ctx]
+ * @param {object} [ctx.column] the bound column declaration, so a `currency` column formats as
+ *                              money even when the block stated no `format` at all
+ * @param {Date}   [ctx.now]    the instant `relative_time` measures against
+ * @returns {string}
+ */
+export function formatValue(value, format, ctx = {}) {
+  const now = ctx.now ?? new Date();
+  const column = ctx.column;
+
+  if (value === null || value === undefined) return "";
+
+  // No `format`? The COLUMN still knows what it is. A currency column drawn with no format is
+  // money, and drawing it as a bare number is the lie of omission Phase 2 warns about.
+  const as = format?.as ?? (column?.type === "currency" ? "currency" : column?.type === "date" ? "date" : undefined);
+  const code = format?.currency ?? column?.currency;
+  const precision = format?.precision;
+  const compact = format?.compact ?? false;
+  const sign = format?.sign ?? "auto";
+
+  switch (as) {
+    case "currency": {
+      const n = Number(value);
+      if (!Number.isFinite(n)) return String(value);
+      const p = precision ?? inferPrecision(n, { compact, as });
+      const body = compact ? compactNumber(n, precision) : fixed(n, p);
+      const negative = body.startsWith("-");
+      const magnitude = negative ? body.slice(1) : body;
+      const text = `${negative ? "-" : ""}${currencyPrefix(code ?? "")}${magnitude}`;
+      return applySign(text, n, sign);
+    }
+    case "percent": {
+      const n = Number(value);
+      if (!Number.isFinite(n)) return String(value);
+      const p = precision ?? inferPrecision(n, { compact, as });
+      return applySign(`${fixed(n, p)}%`, n, sign);
+    }
+    case "number": {
+      const n = Number(value);
+      if (!Number.isFinite(n)) return String(value);
+      const p = precision ?? inferPrecision(n, { compact, as });
+      return applySign(compact ? compactNumber(n, precision) : fixed(n, p), n, sign);
+    }
+    case "date": return formatDate(value, format?.date_style ?? (column?.precision === "time" ? "full" : "day"));
+    case "relative_time": return formatRelative(value, now);
+    case "duration": return formatDuration(value, precision);
+    case "bytes": return formatBytes(value, precision);
+    case "text": return String(value);
+    default:
+      if (typeof value === "boolean") return value ? "Yes" : "No";
+      if (typeof value === "number") return applySign(compact ? compactNumber(value, precision) : fixed(value, precision ?? inferPrecision(value, { compact })), value, sign);
+      return String(value);
+  }
+}
+
+/**
+ * Numeric formats want tabular figures and right alignment; prose does not. A renderer decides
+ * this, not the page — it is exactly the kind of visual consequence `format.as` is allowed to have.
+ */
+export function isNumericFormat(format, column) {
+  const as = format?.as ?? (column?.type === "currency" ? "currency" : undefined);
+  return as === "number" || as === "currency" || as === "percent" || as === "bytes" || as === "duration"
+    || (!as && (column?.type === "number" || column?.type === "currency"));
+}

package/src/core/presentation.js

@@ -0,0 +1,58 @@
+/** Pure presentation decisions extracted from the approved element-system sheet. */
+
+export const TABLE_PAGE_SIZE = 5;
+
+export function initialsFor(value) {
+  const words = String(value ?? "").trim().split(/\s+/).filter(Boolean);
+  if (!words.length) return "—";
+  return `${words[0][0]}${words.length > 1 ? words[words.length - 1][0] : words[0][1] ?? ""}`.toUpperCase();
+}
+
+export function paginateRows(rows, page, pageSize = TABLE_PAGE_SIZE) {
+  const count = rows?.length ?? 0;
+  const pageCount = Math.max(1, Math.ceil(count / pageSize));
+  const current = Math.max(0, Math.min(Number.isFinite(page) ? page : 0, pageCount - 1));
+  const start = current * pageSize;
+  const items = (rows ?? []).slice(start, start + pageSize);
+  return { items, page: current, pageCount, start: count ? start + 1 : 0, end: Math.min(start + pageSize, count), count };
+}
+
+const monthLabel = (time) => new Intl.DateTimeFormat("en", { month: "short" }).format(new Date(time));
+
+export function timelineLayout(rows, dateField, endDateField, now) {
+  const parsed = (rows ?? [])
+    .map((row) => ({ row, t: Date.parse(row[dateField]), end: endDateField ? Date.parse(row[endDateField]) : NaN }))
+    .filter((item) => Number.isFinite(item.t))
+    .sort((a, b) => a.t - b.t);
+  if (!parsed.length) return { items: [], ticks: [], today: null };
+
+  const min = parsed[0].t;
+  const max = Math.max(...parsed.map((item) => (Number.isFinite(item.end) ? item.end : item.t)));
+  const span = max - min || 1;
+  const pct = (time) => 6 + ((time - min) / span) * 88;
+  const ticks = [0, 1 / 3, 2 / 3, 1].map((part) => {
+    const time = min + span * part;
+    return { label: monthLabel(time), left: pct(time) };
+  });
+  const nowTime = new Date(now).getTime();
+
+  return {
+    items: parsed.map((item) => ({
+      ...item,
+      left: pct(item.t),
+      width: Number.isFinite(item.end) ? pct(item.end) - pct(item.t) : 0,
+    })),
+    ticks,
+    today: Number.isFinite(nowTime) && nowTime >= min && nowTime <= max ? pct(nowTime) : null,
+  };
+}
+
+export function formatAudioTime(seconds) {
+  if (!Number.isFinite(seconds) || seconds < 0) return "0:00";
+  const whole = Math.floor(seconds);
+  return `${Math.floor(whole / 60)}:${String(whole % 60).padStart(2, "0")}`;
+}
+
+export const isDestructiveAction = (action) => Boolean(
+  action?.confirm?.destructive || (action?.type === "mutate" && action.operation === "delete"),
+);