@ultimat3/admin 22.14.0 → 23.0.0

package/src/registry.ts

@@ -6,7 +6,7 @@
 // is the compile-time proof that a real `entity()` result satisfies it; it is checked by
 // `tsc`, not asserted in a comment, because the admin used to read fields no entity had.
 
-import type { Entity, Repo } from '@ultimat3/entity';
+import type { Entity, Operator, Table } from '@ultimat3/entity';
 
 /**
  * What the author declared about one column — `@ultimat3/entity`'s `ColumnMeta`, narrowed to
@@ -37,11 +37,21 @@ export interface AdminColumnMeta {
    * hands back the resolved target — but its presence is what makes the column a foreign key.
    */
   readonly references?: () => unknown;
+  /**
+   * `.sealed()`: encrypted at rest, opened on read, absent from every schema that leaves the
+   * server. Present means the admin derives NO readable field for it — see `entity-columns.ts`.
+   */
+  readonly sealed?: { readonly lookup: boolean };
 }
 
 /** One column of a registered entity. An `@ultimat3/entity` `Column` satisfies this. */
 export interface AdminColumn {
   readonly $meta: AdminColumnMeta;
+  /**
+   * The column's own guard. Optional in this surface only because a hand-built fixture has none;
+   * every `entity()` column carries it, and `repo-entity.ts` parses a URL's id through it.
+   */
+  readonly $parse?: (value: unknown) => unknown;
 }
 
 /** One column of `$describe()` output. Money is the one property that becomes two of these. */
@@ -65,6 +75,12 @@ export interface AdminEntity {
   readonly $columns: Readonly<Record<string, AdminColumn>>;
   /** The Standard Schema the entity validates with; forms hand input straight to it. */
   readonly $schema: unknown;
+  /**
+   * The column the handle scopes every read and write by, or `null`. Optional in this surface only
+   * because a hand-built fixture has none; every `entity()` result carries it. The admin never
+   * renders it as an input — the acting actor's tenant is the only value it may hold.
+   */
+  readonly $tenantColumn?: string | null;
   /** Resolves foreign-key targets. See `entity-columns.ts` for what the admin takes from it. */
   $describe(): AdminEntityDescription;
 }
@@ -80,14 +96,63 @@ type Satisfies<Surface, T extends Surface> = T;
 export type RegisteredEntity = Satisfies<AdminEntity, Entity<AdminRow>>;
 
 /**
- * A repo as `@ultimat3/entity` registers it — deliberately NOT claimed to be an `AdminRepo`:
- * the verbs differ (`findMany`/`insert` vs `list`/`create`) and its cursor is an opaque signed
- * string where the admin speaks a keyset bound, so the host binds an adapter over it.
+ * The slice of a typed handle's read chain the admin drives — `database()`'s `db.<entity>`. Named
+ * for the reason `AdminEntity` is: one file changes when the handle grows, and `RegisteredTable`
+ * is the `tsc`-checked proof a real one satisfies it.
  */
-export type RegisteredRepo = Repo;
+export interface AdminTableRead {
+  where(filter: Readonly<Record<string, unknown>>): AdminTableRead;
+  andWhere(column: string, op: Operator, value?: unknown): AdminTableRead;
+  orderBy(column: string, direction?: 'asc' | 'desc'): AdminTableRead;
+  limit(rows: number): AdminTableRead;
+  all(): Promise<readonly AdminRow[]>;
+  one(): Promise<AdminRow | null>;
+  count(): Promise<number>;
+  /** Read for the entity NAME only: it is how a handle is matched to the entity it serves. */
+  plan(): { readonly entity: string };
+}
+
+/** One table of the app's typed handle. Tenancy, soft delete and sealing are its own. */
+export interface AdminTable extends AdminTableRead {
+  insert(values: Readonly<Record<string, unknown>>): Promise<AdminRow>;
+  update(id: string, patch: Readonly<Record<string, unknown>>): Promise<AdminRow>;
+  delete(id: string): Promise<void>;
+}
+
+/** The app's `database()` result, as `defineAdmin({ db })` takes it. Keys are the app's spelling. */
+export type AdminDb = Readonly<Record<string, AdminTable>>;
+
+/** The claim, checked: `database()`'s table IS an `AdminTable`. */
+export type RegisteredTable = Satisfies<AdminTable, Table<AdminRow>>;
+
+export type FilterOp =
+  | 'eq'
+  | 'neq'
+  | 'contains'
+  | 'gt'
+  | 'gte'
+  | 'lt'
+  | 'lte'
+  | 'in'
+  /** `value: true` keeps the rows with no value, `value: false` the rows with one. */
+  | 'is-null';
 
-export type FilterOp = 'eq' | 'neq' | 'contains' | 'gt' | 'lt' | 'in' | 'is-null';
+export const FILTER_OPS: readonly FilterOp[] = [
+  'eq',
+  'neq',
+  'contains',
+  'gt',
+  'gte',
+  'lt',
+  'lte',
+  'in',
+  'is-null',
+];
 
+/**
+ * One predicate of a list read. Every list the admin issues is a CONJUNCTION of these — the URL's
+ * filters, the scope's, and the resource's row scope — so each maps to one indexed comparison.
+ */
 export interface AdminFilter {
   readonly field: string;
   readonly op: FilterOp;
@@ -147,10 +212,33 @@ export interface AdminActionCtx {
   readonly timeZone: string;
 }
 
+/** How a batch action behaves past the size a request should run inline. */
+export interface AdminBatchOptions {
+  /**
+   * The most rows one request runs INLINE. A selection larger than this is handed to the queue —
+   * one `admin.batch` job per chunk — and the answer says how many rows were queued, not done.
+   */
+  readonly threshold: number;
+  /** Rows per queued job. Omitted: `threshold`. */
+  readonly chunk?: number;
+}
+
+/** What a set-based "all matching" answers — the shape of a store's own bulk verb. */
+export interface AdminMatchingResult {
+  /** Rows this call changed. */
+  readonly affected: number;
+  /** Rows still matching afterwards. Run again until it is zero. */
+  readonly remaining: number;
+}
+
 /**
  * A registered `action` as the admin surfaces it. `permission` is not optional: an action
  * with no policy is an open door, and the admin refuses to render one
  * (X_ADMIN_POLICY_MISSING).
+ *
+ * One declaration, every projection: the button on the detail page and on each list row, the
+ * action's own form, the batch bar, the MCP tool, the audit entry. `when` and `batch` narrow WHERE
+ * it appears and never add a second handler.
  */
 export interface AdminAction<Input = Readonly<Record<string, unknown>>, Output = unknown> {
   readonly name: string;
@@ -158,15 +246,47 @@ export interface AdminAction<Input = Readonly<Record<string, unknown>>, Output =
   /** The entity the button belongs to. Absent = a global action in the toolbar. */
   readonly entity?: string;
   readonly destructive?: boolean;
+  /** Absent: `admin.action.<name>` — `actionLabelKey`, the one spelling every screen reads. */
   readonly labelKey?: string;
   /** Mirrors the action's own `mcp` block; the admin MCP surface honours `expose`. */
   readonly mcp?: { readonly expose?: boolean; readonly description?: string };
-  /** The action's Standard Schema, handed to the form and to the MCP tool definition. */
+  /**
+   * The action's input schema — a `t.object({ … })`. Rendered as the action's form (one control
+   * per property), validated before the handler runs with each issue shown against its field,
+   * and handed to the MCP tool definition. Absent: the action takes no input, and its button is a
+   * confirm only. The row's `id` is the admin's own envelope and is never a property here.
+   */
   readonly input?: unknown;
+  /**
+   * Whether the action applies to THIS row. Decides the button on the detail page and on each
+   * list row, and is evaluated again on the server before the handler runs — a hidden button is
+   * not an authorization: `X_ADMIN_ACTION_NOT_APPLICABLE`. The row it reads carries no sealed
+   * column. Absent: the action applies to every row.
+   */
+  readonly when?: (row: AdminRow) => boolean;
+  /**
+   * In the list's batch bar: run once per selected row through the same gate as the button, each
+   * row audited, the answer counting done, refused and failed. `true` runs every batch inline;
+   * `{ threshold }` queues a selection larger than that as one job per chunk.
+   */
+  readonly batch?: true | AdminBatchOptions;
+  /**
+   * The batch bar's "all matching" as ONE set-based call instead of a walk of rows: handed the
+   * list's own `where` — row scope, then scope, then filters — it changes what matches and answers
+   * how many it changed and how many still match. For a store with a bounded bulk verb of its own
+   * (the jobs operator's `requeueMany`). Decided and audited once, for the set; the per-row gate is
+   * not asked per row, so the verb's own predicate is where `when` holds. A checked selection
+   * still runs row by row through `handle`. Requires `batch`.
+   */
+  readonly matching?: (args: {
+    readonly where: readonly AdminFilter[];
+    readonly input: Input;
+    readonly ctx: AdminActionCtx;
+  }) => Promise<AdminMatchingResult>;
   handle(args: { input: Input; ctx: AdminActionCtx }): Promise<Output>;
 }
 
-/** A registered `job` as the admin's Jobs page needs it — `describeJobs()` output. */
+/** A registered `job` as an AI pane is told about it (`ai-panes.ts`) — `describeJobs()` output. */
 export interface AdminJobSummary {
   readonly name: string;
   readonly queue?: string;
@@ -185,3 +305,13 @@ export function rowId(row: AdminRow, idField: string): string {
   const value = row[idField];
   return typeof value === 'string' ? value : String(value ?? '');
 }
+
+/**
+ * A row as something DRAWN or DECIDED on reads it: its enumerable values, minus every sealed
+ * column. A repository row keeps a sealed property off its enumerable set already; a hand-written
+ * `repo:` may not, so the names are dropped explicitly — a computed cell is rendered and an
+ * action's `when` is evaluated per row, and a sealed value reaches neither.
+ */
+export function computedRow(row: AdminRow, sealed: readonly string[]): AdminRow {
+  return Object.fromEntries(Object.entries(row).filter(([key]) => !sealed.includes(key)));
+}

package/src/related.ts

@@ -0,0 +1,105 @@
+// A row's RELATED rows: the `hasMany` relations a resource names in `related`, each read as the
+// related resource's own list — its gate, its row scope, its columns — narrowed to the rows that
+// point at this one. No second table is declared anywhere: the related resource already is one.
+
+import { relationsFor as entityRelationsFor } from '@ultimat3/entity';
+import { adminList, type CrudCtx, canOperate } from './crud';
+import { AdminFieldUnsupportedError } from './errors';
+import type { AdminPage } from './pagination';
+import type { AdminFilter, AdminRow } from './registry';
+import type { AdminResource } from './resource';
+
+/** How many related rows a detail page shows per relation. The rest are one link away. */
+export const RELATED_PAGE_SIZE = 10;
+
+/** One declared relation, resolved against the admin it is declared in. */
+export interface AdminRelated {
+  /** The relation's name on the entity — what `related: [...]` spelled. */
+  readonly name: string;
+  /** The resource whose rows these are. */
+  readonly resource: AdminResource;
+  /** The property of THAT resource holding the foreign key. */
+  readonly field: string;
+  /** The property of the row in hand the foreign key points at. */
+  readonly localKey: string;
+}
+
+/**
+ * The `related` names of one resource, resolved. Every name is a `hasMany` of the entity whose
+ * target is a resource of this admin — anything else is refused here, where it is declared, never
+ * drawn as an empty card.
+ */
+export function relatedOf(
+  resources: readonly AdminResource[],
+  resource: AdminResource,
+): readonly AdminRelated[] {
+  if (resource.related.length === 0) return [];
+  // The one read of `@ultimat3/entity`'s relations in this package: the FK already written IS
+  // the relation, so the admin derives nothing of its own and names nothing twice.
+  const relations = entityRelationsFor(resource.name);
+  const offered = Object.values(relations)
+    .filter((relation) => relation.kind === 'hasMany')
+    .map((relation) => relation.name);
+  const hint = `resources.${resource.name}.related may name: ${offered.length > 0 ? offered.join(', ') : 'nothing — no entity references this one'}`;
+
+  return resource.related.map((name) => {
+    const refuse = (cause: string, fix: string): never => {
+      throw new AdminFieldUnsupportedError({ entity: resource.name, field: name, cause, fix });
+    };
+    const relation = Object.hasOwn(relations, name) ? relations[name] : undefined;
+    if (relation === undefined) {
+      return refuse('named in related and is not a relation of the entity', hint);
+    }
+    if (relation.kind !== 'hasMany') {
+      return refuse(
+        `named in related and is a belongsTo: the "${relation.localKey}" field already links to its row`,
+        hint,
+      );
+    }
+    const target = resources.find((known) => known.name === relation.to);
+    if (target === undefined) {
+      return refuse(
+        `named in related, and its rows are "${relation.to}", which is not a resource of this admin`,
+        `add the ${relation.to} entity to defineAdmin({ entities }) — its own list is what related draws`,
+      );
+    }
+    return { name, resource: target, field: relation.remoteKey, localKey: relation.localKey };
+  });
+}
+
+/** One related list as the detail page draws it. */
+export interface AdminRelatedList {
+  readonly related: AdminRelated;
+  readonly page: AdminPage<AdminRow>;
+  /** The one predicate that makes this list THIS row's. */
+  readonly filter: AdminFilter;
+}
+
+/**
+ * The related lists of one row — one statement each, read beside each other. A related resource
+ * this actor may not list is LEFT OUT, silently: they asked for this row, and the refusal they
+ * would get by opening that list is logged there. Everything else is `adminList`: the related
+ * resource's policy decides, its `rows` narrows, and the read is audited under its own name.
+ */
+export async function relatedLists(
+  related: readonly AdminRelated[],
+  row: AdminRow,
+  ctx: CrudCtx,
+): Promise<readonly AdminRelatedList[]> {
+  const readable = related.filter((one) => canOperate(one.resource, 'list', ctx));
+  const read = await Promise.all(
+    readable.map(async (one): Promise<AdminRelatedList | null> => {
+      const key = row[one.localKey];
+      if (key === null || key === undefined) return null;
+      const filter: AdminFilter = { field: one.field, op: 'eq', value: String(key) };
+      const result = await adminList<AdminRow>(one.resource, ctx, {
+        // No scope, not even the default one: a related row counts whatever tab it sits under.
+        scope: null,
+        filters: [filter],
+        limit: RELATED_PAGE_SIZE,
+      });
+      return result.ok ? { related: one, page: result.page, filter } : null;
+    }),
+  );
+  return read.filter((one): one is AdminRelatedList => one !== null);
+}

package/src/relations.ts

@@ -0,0 +1,224 @@
+// A resource read AS A TARGET: the label of each row another resource references, and the lookup
+// a picker searches. Both are reads of the target — decided by its `list` gate, narrowed by its
+// row scope, audited under its name — and both are batched: one statement per target resource per
+// page, never one per row and never one per cell.
+
+import { finiteCount } from '@ultimat3/core';
+import type { AuditEntry } from './audit';
+import type { AdminDecision } from './authz';
+import { type CrudCtx, decideOperation } from './crud';
+import { checkedFilter } from './list-filters';
+import { rowWhere } from './list-scope';
+import { type AdminPage, fetchPage } from './pagination';
+import type { AdminRow } from './registry';
+import { rowId } from './registry';
+import { type AdminResource, repoOf } from './resource';
+
+/** One row of a target, as a picker offers it and a reference cell shows it. */
+export interface AdminOption {
+  readonly id: string;
+  readonly label: string;
+}
+
+/**
+ * A target with at most this many visible rows is offered whole, as a `<select>`. One more and
+ * the picker is a search: an option list nobody can scan is not a control.
+ */
+export const LOOKUP_SELECT_MAX = 50;
+
+/** The most ids one label read names — the list's own page-size ceiling. */
+const MAX_LABEL_IDS = 200;
+
+/** The row's label-field value when it is text, else its id — never a blank cell. */
+export function labelOf(
+  row: AdminRow,
+  resource: Pick<AdminResource, 'labelField' | 'idField'>,
+): string {
+  const value = row[resource.labelField];
+  if (typeof value === 'string' && value !== '') return value;
+  return rowId(row, resource.idField);
+}
+
+const optionOf = (resource: AdminResource, row: AdminRow): AdminOption => ({
+  id: rowId(row, resource.idField),
+  label: labelOf(row, resource),
+});
+
+const readEntry = (resource: AdminResource, ctx: CrudCtx, decision: AdminDecision) =>
+  ctx.audit.append({
+    requestId: ctx.requestId,
+    actor: ctx.actor,
+    operation: 'list',
+    kind: 'operation',
+    entity: resource.name,
+    entityId: null,
+    permission: decision.permission,
+    outcome: 'allowed',
+    reason: decision.reason,
+  });
+
+export interface AdminLookupRequest {
+  /** Matched against the target's label, by its label filter's default operator. */
+  readonly term?: string;
+  readonly cursor?: string | null;
+  readonly limit?: number;
+}
+
+export type AdminLookupResult =
+  | {
+      readonly ok: true;
+      readonly options: readonly AdminOption[];
+      readonly page: AdminPage<AdminRow>;
+      readonly audit: AuditEntry;
+    }
+  | { readonly ok: false; readonly decision: AdminDecision };
+
+/**
+ * The one lookup of a target resource: `contains` on its label, keyset-paged in the resource's own
+ * default order, behind the same `list` gate and the same row scope as its list screen. Every
+ * filter and every input that references the resource asks this — an app writes no endpoint.
+ */
+export async function adminLookup(
+  resource: AdminResource,
+  ctx: CrudCtx,
+  request: AdminLookupRequest = {},
+): Promise<AdminLookupResult> {
+  const decision = decideOperation(resource, 'list', ctx);
+  if (!decision.allowed) return { ok: false, decision };
+  const term = request.term?.trim() ?? '';
+  const where = [
+    ...rowWhere(resource, ctx.actor),
+    // Through the validator, like any caller's filter: a label that takes no `contains` (an id)
+    // is matched exactly, and one that is no filter at all is refused by name.
+    ...(term === '' ? [] : [checkedFilter(resource, { field: resource.labelField, value: term })]),
+  ];
+  const page = await fetchPage(resource, {
+    ...(request.cursor === undefined ? {} : { cursor: request.cursor }),
+    // At least 1, and finite: a `NaN` here is a page that is never trimmed and never ends.
+    limit: finiteCount('adminLookup', 'limit', request.limit ?? LOOKUP_SELECT_MAX, 1),
+    ...(where.length === 0 ? {} : { where }),
+  });
+  return {
+    ok: true,
+    options: page.rows.map((row) => optionOf(resource, row)),
+    page,
+    audit: await readEntry(resource, ctx, decision),
+  };
+}
+
+/** What one page needs of one target: the ids its cells show, and whether a control picks from it. */
+export interface RelationNeed {
+  readonly ids: ReadonlySet<string>;
+  /** A filter or an input on the page picks a row of this target. */
+  readonly pick: boolean;
+}
+
+export interface RelationData {
+  /** id → label, for every id the page shows that this actor may see. */
+  readonly labels: ReadonlyMap<string, string>;
+  /**
+   * Every row of the target, when there are at most `LOOKUP_SELECT_MAX` — the `<select>`. `null`
+   * when there are more (the picker is the lookup screen) or when nothing on the page picks.
+   */
+  readonly options: readonly AdminOption[] | null;
+}
+
+const NOTHING: RelationData = { labels: new Map(), options: null };
+
+async function relationOf(
+  resource: AdminResource,
+  ctx: CrudCtx,
+  need: RelationNeed,
+): Promise<RelationData> {
+  if (!need.pick && need.ids.size === 0) return NOTHING;
+  const decision = decideOperation(resource, 'list', ctx);
+  // Not an event: the actor asked for another resource's page, and a label they may not read is
+  // an id shown as an id. The refusal they would get by opening the target is logged there.
+  if (!decision.allowed) return NOTHING;
+
+  const repo = repoOf(resource);
+  const visible = rowWhere(resource, ctx.actor);
+  const labels = new Map<string, string>();
+  let options: readonly AdminOption[] | null = null;
+  let wanted = [...need.ids].slice(0, MAX_LABEL_IDS);
+
+  if (need.pick) {
+    // One over the ceiling: the extra row is how "small enough for a select" is learned without
+    // a count, which on a large table is the slow query this probe exists to avoid.
+    const rows = await repo.list({
+      ...(visible.length === 0 ? {} : { where: visible }),
+      sort: resource.defaultSort,
+      limit: LOOKUP_SELECT_MAX + 1,
+    });
+    for (const row of rows) labels.set(rowId(row, resource.idField), labelOf(row, resource));
+    if (rows.length <= LOOKUP_SELECT_MAX) {
+      // The whole target is in hand, so every label the page needs is too: no second read.
+      options = rows
+        .map((row) => optionOf(resource, row))
+        .sort((a, b) => (a.label < b.label ? -1 : a.label > b.label ? 1 : 0));
+      wanted = [];
+    } else {
+      wanted = wanted.filter((id) => !labels.has(id));
+    }
+  }
+
+  if (wanted.length > 0) {
+    const rows = await repo.list({
+      where: [...visible, { field: resource.idField, op: 'in', value: wanted }],
+      sort: resource.defaultSort,
+      limit: wanted.length,
+    });
+    for (const row of rows) labels.set(rowId(row, resource.idField), labelOf(row, resource));
+  }
+
+  await readEntry(resource, ctx, decision);
+  return { labels, options };
+}
+
+/**
+ * Everything one page needs from the resources it references, keyed by target name. One statement
+ * per target — two for a picked target too large for a `<select>` — whatever the page's row count
+ * and however many columns point at the same target.
+ */
+export async function relationsFor(
+  resources: readonly AdminResource[],
+  ctx: CrudCtx,
+  needs: ReadonlyMap<string, RelationNeed>,
+): Promise<ReadonlyMap<string, RelationData>> {
+  const targets = resources.filter((resource) => needs.has(resource.name));
+  const read = await Promise.all(
+    targets.map((resource) => relationOf(resource, ctx, needs.get(resource.name) ?? NO_NEED)),
+  );
+  return new Map(targets.map((resource, index) => [resource.name, read[index] ?? NOTHING]));
+}
+
+const NO_NEED: RelationNeed = { ids: new Set(), pick: false };
+
+/**
+ * What a set of rows and fields needs: per target resource, the ids the rows hold in the fields
+ * that reference it, and whether any of `picked` — a filter, a form input — picks from it.
+ */
+export function relationNeeds(
+  rows: readonly AdminRow[],
+  shown: readonly { readonly name: string; readonly relation?: { readonly entity: string } }[],
+  picked: readonly { readonly relation?: { readonly entity: string } }[],
+): ReadonlyMap<string, RelationNeed> {
+  const needs = new Map<string, { ids: Set<string>; pick: boolean }>();
+  const need = (entity: string): { ids: Set<string>; pick: boolean } => {
+    const held = needs.get(entity) ?? { ids: new Set<string>(), pick: false };
+    needs.set(entity, held);
+    return held;
+  };
+  for (const field of shown) {
+    if (field.relation === undefined) continue;
+    const held = need(field.relation.entity);
+    for (const row of rows) {
+      const value = row[field.name];
+      if (value !== null && value !== undefined && value !== '') held.ids.add(String(value));
+    }
+  }
+  for (const field of picked) {
+    if (field.relation !== undefined) need(field.relation.entity).pick = true;
+  }
+  return needs;
+}

package/src/renderers.tsx

@@ -0,0 +1,89 @@
+// The six renderers a computed column names, and the one dispatch that draws a computed cell. A
+// closed set on purpose: each maps a VALUE SHAPE to an `@ultimat3/ui` component, so a column says
+// what its value is and never how it is drawn. A seventh shape is a component the app passes.
+
+import { safeUrl } from '@ultimat3/core';
+import { t } from '@ultimat3/i18n';
+import { Badge, Money, RelativeTime, TONES, type Tone } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+import { jsonText } from './json-text';
+import type { AdminRow } from './registry';
+import type { AdminComputedColumn, AdminRenderer } from './resource-list';
+import { assertMoney, type WidgetContext } from './widget-value';
+
+/** What `truncate` keeps. One line of a laptop-width table cell. */
+export const TRUNCATE_AT = 80;
+
+const isTone = (value: unknown): value is Tone => (TONES as readonly unknown[]).includes(value);
+
+const bag = (value: unknown): Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null ? (value as Readonly<Record<string, unknown>>) : {};
+
+const text = (value: unknown): string =>
+  typeof value === 'string' ? value : typeof value === 'number' ? String(value) : '';
+
+const empty = (): JSX.Element => <span>{t('admin.value.empty')}</span>;
+
+type Render = (value: unknown, column: AdminComputedColumn, ctx: WidgetContext) => JSX.Element;
+
+/**
+ * | renderer | value |
+ * |---|---|
+ * | `badge` | text, or `{ label, tone }` |
+ * | `relative-time` | a `Date` or an ISO instant |
+ * | `money` | `{ minor, currency }` — a float is refused, as everywhere |
+ * | `truncate` | text, cut at `TRUNCATE_AT` with the whole value on `title` |
+ * | `link` | `{ href, label }` — the href through `safeUrl` |
+ * | `json` | anything — keys sorted, a bigint as its digits (`json-text.ts`) |
+ */
+const RENDERERS: Readonly<Record<AdminRenderer, Render>> = {
+  badge: (value) => {
+    const tone = bag(value)['tone'];
+    const label = typeof value === 'object' ? text(bag(value)['label']) : text(value);
+    return label === '' ? empty() : <Badge tone={isTone(tone) ? tone : 'neutral'}>{label}</Badge>;
+  },
+  'relative-time': (value, _column, ctx) =>
+    value instanceof Date || typeof value === 'string' ? (
+      <RelativeTime value={value} locale={ctx.locale} timeZone={ctx.timeZone} />
+    ) : (
+      empty()
+    ),
+  money: (value, column, ctx) => {
+    // The guard names what it refuses; a computed column has no entity field to name.
+    const money = assertMoney({ entity: 'columns', name: column.name }, value);
+    return money === null ? empty() : <Money value={money} locale={ctx.locale} />;
+  },
+  truncate: (value) => {
+    const whole = text(value);
+    if (whole === '') return empty();
+    return whole.length <= TRUNCATE_AT ? (
+      <span>{whole}</span>
+    ) : (
+      <span title={whole}>{`${whole.slice(0, TRUNCATE_AT)}…`}</span>
+    );
+  },
+  link: (value) => {
+    const href = safeUrl(text(bag(value)['href']), 'href');
+    const label = text(bag(value)['label']);
+    if (label === '') return empty();
+    return href === null ? <span>{label}</span> : <a href={href}>{label}</a>;
+  },
+  json: (value) =>
+    value === undefined ? empty() : <pre class="x-admin-json">{jsonText(value)}</pre>,
+};
+
+/** The same table as a Map: a name that is not one of the six draws an empty cell. */
+const RENDER: ReadonlyMap<string, Render> = new Map(Object.entries(RENDERERS));
+
+/** One computed cell. */
+export function ComputedCell(props: {
+  readonly column: AdminComputedColumn;
+  readonly row: AdminRow;
+  readonly ctx: WidgetContext;
+}): JSX.Element {
+  const value = props.column.value(props.row);
+  const render = props.column.render;
+  return typeof render === 'function'
+    ? render({ value, row: props.row, ctx: props.ctx })
+    : (RENDER.get(render)?.(value, props.column, props.ctx) ?? empty());
+}