@ultimat3/admin 22.14.0 → 23.0.0

package/src/screen-lookup.tsx

@@ -0,0 +1,157 @@
+// A resource's lookup screen: the picker for every filter and every input that references it.
+// Zero script — a GET form over the label, results as links, keyset paging as links. Opened from
+// a filter it carries `return` and `as`, and each result links back to that list with the
+// parameter set to the row's id; opened on its own, a result opens the row.
+
+import { t } from '@ultimat3/i18n';
+import { Button, Card, ErrorState, Input, Pagination } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+import type { AdminApp } from './admin';
+import styles from './admin.module.scss';
+import { canOperate } from './crud';
+import { AdminFilterInvalidError } from './errors';
+import { FILTER_PREFIX } from './list-filters';
+import { CURSOR_PARAM } from './list-request';
+import { adminLookup } from './relations';
+import type { AdminResource } from './resource';
+import { type AdminScreen, framed, lookupHref, refused } from './screen-frame';
+
+const TERM_PARAM = 'term';
+const RETURN_PARAM = 'return';
+const AS_PARAM = 'as';
+const KNOWN: readonly string[] = [TERM_PARAM, CURSOR_PARAM, RETURN_PARAM, AS_PARAM];
+
+interface Asked {
+  readonly term: string;
+  readonly cursor: string | null;
+  /** The list to go back to, and the filter parameter to set on it. Both, or neither. */
+  readonly back: { readonly to: string; readonly as: string } | null;
+}
+
+/**
+ * What the URL asks for. `return` is followed by a link this screen renders, so it is held to the
+ * admin's own paths — an absolute URL or a `//host` here is somebody else's page wearing the
+ * admin's chrome — and `as` to a filter parameter, the only thing a lookup ever sets.
+ */
+function askedOf(app: AdminApp, resource: AdminResource, url: URL): Asked {
+  const refuse = (asked: string, cause: string): never => {
+    throw new AdminFilterInvalidError({ entity: resource.name, asked, cause, known: KNOWN });
+  };
+  for (const key of url.searchParams.keys()) {
+    if (!KNOWN.includes(key)) refuse(key, 'is not a parameter a lookup reads');
+  }
+  const to = url.searchParams.get(RETURN_PARAM) ?? '';
+  const as = url.searchParams.get(AS_PARAM) ?? '';
+  if ((to === '') !== (as === ''))
+    refuse(RETURN_PARAM, 'and `as` are given together or not at all');
+  if (to !== '' && !(to === app.basePath || to.startsWith(`${app.basePath}/`))) {
+    refuse(`${RETURN_PARAM}=${to}`, `is not a path under ${app.basePath}`);
+  }
+  if (as !== '' && !as.startsWith(FILTER_PREFIX)) {
+    refuse(`${AS_PARAM}=${as}`, `is not a filter parameter (${FILTER_PREFIX}<field>)`);
+  }
+  return {
+    term: url.searchParams.get(TERM_PARAM) ?? '',
+    cursor: url.searchParams.get(CURSOR_PARAM),
+    back: to === '' ? null : { to, as },
+  };
+}
+
+/** The list a result returns to, with the picked id set and the old page position dropped. */
+const picked = (back: { readonly to: string; readonly as: string }, id: string): string => {
+  const [path = '', search = ''] = back.to.split('?', 2);
+  const query = new URLSearchParams(search);
+  query.set(back.as, id);
+  query.delete(CURSOR_PARAM);
+  return `${path}?${query.toString()}`;
+};
+
+export function lookupScreen(app: AdminApp, resource: AdminResource): AdminScreen {
+  const here = lookupHref(app.basePath, resource);
+  return async (request) => {
+    const url = new URL(request.url);
+    // Decided before the URL is read: an actor who may not list the target learns nothing about
+    // which parameters its lookup takes.
+    if (!canOperate(resource, 'list', request.ctx)) {
+      const denied = await adminLookup(resource, request.ctx);
+      if (!denied.ok) return refused(app, request, resource.titleKey, denied.decision);
+    }
+    let asked: Asked;
+    try {
+      asked = askedOf(app, resource, url);
+    } catch (error) {
+      if (!(error instanceof AdminFilterInvalidError)) throw error;
+      return framed(app, request, resource.titleKey, <ErrorState error={error} />, 400);
+    }
+    const result = await adminLookup(resource, request.ctx, {
+      term: asked.term,
+      cursor: asked.cursor,
+    });
+    if (!result.ok) return refused(app, request, resource.titleKey, result.decision);
+
+    const state = (cursor: string | null): string => {
+      const query = new URLSearchParams();
+      if (asked.term !== '') query.set(TERM_PARAM, asked.term);
+      if (asked.back !== null) {
+        query.set(RETURN_PARAM, asked.back.to);
+        query.set(AS_PARAM, asked.back.as);
+      }
+      if (cursor !== null) query.set(CURSOR_PARAM, cursor);
+      const search = query.toString();
+      return search === '' ? here : `${here}?${search}`;
+    };
+    const hidden = (name: string, value: string): JSX.Element => (
+      <input type="hidden" name={name} value={value} />
+    );
+    const { page } = result;
+
+    return framed(
+      app,
+      request,
+      resource.titleKey,
+      <Card header={<h2>{t('admin.lookup.title', { entity: t(resource.titleKey) })}</h2>}>
+        <search>
+          <form class={styles['filters']} method="get" action={here}>
+            <Input
+              name={TERM_PARAM}
+              type="search"
+              value={asked.term}
+              aria-label={t('admin.search.label')}
+              placeholder={t('admin.lookup.placeholder')}
+            />
+            {asked.back === null ? null : hidden(RETURN_PARAM, asked.back.to)}
+            {asked.back === null ? null : hidden(AS_PARAM, asked.back.as)}
+            <Button type="submit" variant="secondary">
+              {t('admin.filter.apply')}
+            </Button>
+          </form>
+        </search>
+        {result.options.length === 0 ? (
+          <p class="x-admin-empty">{t('admin.list.empty')}</p>
+        ) : (
+          <ul class={styles['list']}>
+            {result.options.map((option) => (
+              <li>
+                <a
+                  href={
+                    asked.back === null
+                      ? `${app.basePath}${resource.path}/${option.id}`
+                      : picked(asked.back, option.id)
+                  }
+                >
+                  {option.label}
+                </a>{' '}
+                <span class={styles['mono']}>{option.id}</span>
+              </li>
+            ))}
+          </ul>
+        )}
+        <Pagination
+          nextCursor={page.hasMore ? (page.nextCursor ?? undefined) : undefined}
+          prevCursor={page.prevCursor ?? undefined}
+          hrefFor={(cursor) => state(cursor)}
+        />
+      </Card>,
+    );
+  };
+}

package/src/screen-resource.tsx

@@ -0,0 +1,393 @@
+// The four generated screens of one resource — list, detail, create, edit — and the writes each
+// one's forms post back at it. Every one asks `crud.ts` (or the action gate) FIRST and renders
+// what it answered: a row-level rule sees the row, a refusal is audited by the gate that made it,
+// and no screen holds a decision of its own.
+
+import { t } from '@ultimat3/i18n';
+import { ErrorState, Link } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+import {
+  ACTION_OPERATION,
+  ACTION_PARAM,
+  BATCH_OPERATION,
+  DELETE_OPERATION,
+  OPERATION_FIELD,
+} from './actions';
+import type { AdminApp, AdminRoute } from './admin';
+import styles from './admin.module.scss';
+import { auditCursorOf } from './audit';
+import {
+  adminCreate,
+  adminDestroy,
+  adminDetail,
+  adminList,
+  adminUpdate,
+  canOperate,
+  decideOperation,
+} from './crud';
+import { AdminDetail, HISTORY_PARAM, historyCursorOf, historyCursorText } from './detail';
+import { AdminFilterInvalidError } from './errors';
+import { AdminForm } from './form';
+import { decodeForm, posted } from './form-decode';
+import { AdminList } from './list';
+import { type ListLocation, listHref, pageRequestOf } from './list-request';
+import { type AdminListRequest, findRow, scopeCounts } from './list-scope';
+import type { AdminRow } from './registry';
+import { relatedLists, relatedOf } from './related';
+import { type RelationNeed, relationNeeds, relationsFor } from './relations';
+import type { AdminResource } from './resource';
+import { batchWrite, rowActionFormScreen, rowActionWrite } from './screen-action';
+import {
+  type AdminRouteRequest,
+  type AdminRouteResponse,
+  type AdminScreen,
+  framed,
+  missing,
+  refused,
+  refusedPage,
+  widgetContextOf,
+} from './screen-frame';
+import type { ValidationIssue } from './validate';
+import type { WidgetContext } from './widget-value';
+
+const rowHref = (app: AdminApp, resource: AdminResource, id: string): string =>
+  `${app.basePath}${resource.path}/${id}`;
+
+const idOf = (request: AdminRouteRequest): string => request.params['id'] ?? '';
+
+const notFound = (
+  app: AdminApp,
+  resource: AdminResource,
+  request: AdminRouteRequest,
+): AdminRouteResponse =>
+  missing(
+    app,
+    request,
+    resource.titleKey,
+    <AdminDetail
+      resource={resource}
+      row={null}
+      error={null}
+      ctx={widgetContextOf(app, request.ctx)}
+      actor={request.ctx.actor}
+      authz={request.ctx.authz}
+      audit={[]}
+      basePath={app.basePath}
+    />,
+  );
+
+export function listScreen(app: AdminApp, resource: AdminResource): AdminScreen {
+  const hrefFor = (location: ListLocation): string => listHref(app.basePath, resource, location);
+  return async (request) => {
+    // A batch is posted at the list's own URL: its query string is what "all matching" means.
+    if (request.method === 'POST') {
+      const form = request.form ?? {};
+      if (posted(form, OPERATION_FIELD) !== BATCH_OPERATION)
+        return notFound(app, resource, request);
+      try {
+        return await batchWrite(app, request, resource, form, () =>
+          notFound(app, resource, request),
+        );
+      } catch (error) {
+        if (!(error instanceof AdminFilterInvalidError)) throw error;
+        return framed(app, request, resource.titleKey, <ErrorState error={error} />, 400);
+      }
+    }
+    // Refused BEFORE the URL is read: an actor who may not list the table learns nothing about
+    // its filters or scopes from the answer. `adminList` makes and audits the refusal.
+    if (!canOperate(resource, 'list', request.ctx)) {
+      const denied = await adminList<AdminRow>(resource, request.ctx);
+      if (!denied.ok) return refused(app, request, resource.titleKey, denied.decision);
+    }
+    let asked: AdminListRequest;
+    let result: Awaited<ReturnType<typeof adminList<AdminRow>>>;
+    try {
+      asked = pageRequestOf(resource, new URL(request.url));
+      // Inside the same refusal: a repo that cannot answer a predicate the URL grammar allows (a
+      // store with one order, a filter it has no column for) refuses it by name too.
+      result = await adminList<AdminRow>(resource, request.ctx, asked);
+    } catch (error) {
+      if (!(error instanceof AdminFilterInvalidError)) throw error;
+      // 400, naming what the list does answer — and the way back to it.
+      return framed(
+        app,
+        request,
+        resource.titleKey,
+        <>
+          <ErrorState error={error} />
+          <Link href={hrefFor({})}>{t('admin.filter.clear')}</Link>
+        </>,
+        400,
+      );
+    }
+    if (!result.ok) return refused(app, request, resource.titleKey, result.decision);
+
+    // Everything else the page shows, read beside each other: one count per scope that asked for
+    // one, and one read per resource the page references — never one per row.
+    const [counts, relations] = await Promise.all([
+      scopeCounts(resource, request.ctx.actor),
+      relationsFor(
+        app.resources,
+        request.ctx,
+        relationNeeds(result.page.rows, resource.listFields, resource.filters),
+      ),
+    ]);
+
+    return framed(
+      app,
+      request,
+      resource.titleKey,
+      <>
+        {canOperate(resource, 'create', request.ctx) ? (
+          <div class={styles['toolbar']}>
+            <Link appearance="button" href={`${hrefFor({})}/new`}>
+              {t('admin.form.create', { entity: t(resource.titleKey) })}
+            </Link>
+          </div>
+        ) : null}
+        <AdminList
+          resource={resource}
+          page={result.page}
+          error={null}
+          ctx={widgetContextOf(app, request.ctx, relations)}
+          actor={request.ctx.actor}
+          authz={request.ctx.authz}
+          basePath={app.basePath}
+          request={asked}
+          scope={result.scope}
+          counts={counts}
+          hrefFor={hrefFor}
+        />
+      </>,
+    );
+  };
+}
+
+/** The labels, option lists and lookups one row's reference fields need, for a detail or a form. */
+const relationsOf = (
+  app: AdminApp,
+  resource: AdminResource,
+  request: AdminRouteRequest,
+  row: AdminRow,
+  picking: boolean,
+): Promise<WidgetContext> =>
+  relationsFor(
+    app.resources,
+    request.ctx,
+    relationNeeds([row], resource.fields, picking ? resource.formFields : []),
+  ).then((relations) => widgetContextOf(app, request.ctx, relations));
+
+/** A posted action or delete, decided by the same gate that decided whether its button rendered. */
+async function detailWrite(
+  app: AdminApp,
+  resource: AdminResource,
+  request: AdminRouteRequest,
+  form: Readonly<Record<string, unknown>>,
+): Promise<AdminRouteResponse> {
+  const id = idOf(request);
+  const confirmation = posted(form, 'confirmation');
+  const landing = listHref(app.basePath, resource);
+
+  if (posted(form, OPERATION_FIELD) === DELETE_OPERATION) {
+    const result = await adminDestroy(resource, request.ctx, id, confirmation);
+    if (result.ok) return { kind: 'redirect', location: landing };
+    if (result.kind === 'denied') return refused(app, request, resource.titleKey, result.decision);
+    return notFound(app, resource, request);
+  }
+
+  if (posted(form, OPERATION_FIELD) !== ACTION_OPERATION) return notFound(app, resource, request);
+  return rowActionWrite(app, request, resource, form, () => notFound(app, resource, request));
+}
+
+/** How many entries of a row's history one detail page shows. Older ones are a link away. */
+const HISTORY_PAGE = 20;
+
+/** Two pages' needs as one: each target is still read once for the whole page. */
+const mergedNeeds = (
+  all: readonly ReadonlyMap<string, RelationNeed>[],
+): ReadonlyMap<string, RelationNeed> => {
+  const out = new Map<string, { ids: Set<string>; pick: boolean }>();
+  for (const needs of all) {
+    for (const [entity, need] of needs) {
+      const held = out.get(entity) ?? { ids: new Set<string>(), pick: false };
+      for (const id of need.ids) held.ids.add(id);
+      held.pick ||= need.pick;
+      out.set(entity, held);
+    }
+  }
+  return out;
+};
+
+export function detailScreen(app: AdminApp, resource: AdminResource): AdminScreen {
+  return async (request) => {
+    if (request.method === 'POST') {
+      return detailWrite(app, resource, request, request.form ?? {});
+    }
+    const id = idOf(request);
+    const url = new URL(request.url);
+    const asked = url.searchParams.get(ACTION_PARAM);
+    if (asked !== null) {
+      return rowActionFormScreen(app, request, resource, asked, () =>
+        notFound(app, resource, request),
+      );
+    }
+    const result = await adminDetail<AdminRow>(resource, request.ctx, id);
+    if (!result.ok) {
+      return result.kind === 'denied'
+        ? refused(app, request, resource.titleKey, result.decision)
+        : notFound(app, resource, request);
+    }
+    if (result.row === null) return notFound(app, resource, request);
+    const row = result.row;
+
+    // Everything else the page shows, read beside each other: the related resources' own lists,
+    // and one keyset page of this row's history — what changed it or was refused, never who read.
+    const before = historyCursorOf(url.searchParams.get(HISTORY_PARAM));
+    const [related, history] = await Promise.all([
+      relatedLists(relatedOf(app.resources, resource), row, request.ctx),
+      request.ctx.audit.entries({
+        entity: resource.name,
+        entityId: id,
+        changes: true,
+        limit: HISTORY_PAGE,
+        ...(before === undefined ? {} : { before }),
+      }),
+    ]);
+    // ONE label read per referenced target for the whole page — this row's references and every
+    // related row's together.
+    const relations = await relationsFor(
+      app.resources,
+      request.ctx,
+      mergedNeeds([
+        relationNeeds([row], resource.fields, []),
+        ...related.map((list) =>
+          relationNeeds(list.page.rows, list.related.resource.listFields, []),
+        ),
+      ]),
+    );
+    const older = auditCursorOf(history);
+    const self = rowHref(app, resource, id);
+
+    return framed(
+      app,
+      request,
+      resource.titleKey,
+      <AdminDetail
+        resource={resource}
+        row={row}
+        error={null}
+        ctx={widgetContextOf(app, request.ctx, relations)}
+        actor={request.ctx.actor}
+        authz={request.ctx.authz}
+        audit={history}
+        olderHref={
+          history.length < HISTORY_PAGE || older === null
+            ? null
+            : `${self}?${HISTORY_PARAM}=${encodeURIComponent(historyCursorText(older))}`
+        }
+        related={related}
+        relatedHref={(list) =>
+          // Through the target's own list grammar — only when the key is one of its filters, or
+          // the link would be the unfiltered list.
+          list.related.resource.filters.some((field) => field.name === list.filter.field)
+            ? listHref(app.basePath, list.related.resource, { scope: null, filters: [list.filter] })
+            : listHref(app.basePath, list.related.resource)
+        }
+        basePath={app.basePath}
+        may={{
+          update: decideOperation(resource, 'update', request.ctx, id, row).allowed,
+          delete: decideOperation(resource, 'delete', request.ctx, id, row).allowed,
+        }}
+      />,
+    );
+  };
+}
+
+async function form(
+  app: AdminApp,
+  resource: AdminResource,
+  request: AdminRouteRequest,
+  mode: 'create' | 'edit',
+  values: Readonly<Record<string, unknown>>,
+  issues: readonly ValidationIssue[],
+): Promise<JSX.Element> {
+  const list = listHref(app.basePath, resource);
+  return (
+    <AdminForm
+      resource={resource}
+      mode={mode}
+      values={values}
+      issues={issues}
+      error={null}
+      // A reference input picks from its target: the option list of a small one, read once.
+      ctx={await relationsOf(app, resource, request, values, true)}
+      action={new URL(request.url).pathname}
+      cancelHref={mode === 'create' ? list : rowHref(app, resource, idOf(request))}
+    />
+  );
+}
+
+export function createScreen(
+  app: AdminApp,
+  route: AdminRoute,
+  resource: AdminResource,
+): AdminScreen {
+  return async (request) => {
+    if (request.method === 'GET') {
+      const decision = decideOperation(resource, 'create', request.ctx);
+      if (!decision.allowed) return refusedPage(app, request, route, decision);
+      return framed(
+        app,
+        request,
+        resource.titleKey,
+        await form(app, resource, request, 'create', {}, []),
+      );
+    }
+    const input = decodeForm(resource, request.form ?? {});
+    const result = await adminCreate<AdminRow>(resource, request.ctx, input);
+    if (result.ok) {
+      const id = String(result.row?.[resource.idField] ?? '');
+      return { kind: 'redirect', location: rowHref(app, resource, id) };
+    }
+    if (result.kind === 'denied') return refused(app, request, resource.titleKey, result.decision);
+    if (result.kind === 'missing') return notFound(app, resource, request);
+    // 422, with what was typed: a refused form that came back empty is a form filled in twice.
+    return framed(
+      app,
+      request,
+      resource.titleKey,
+      await form(app, resource, request, 'create', input, result.issues),
+      422,
+    );
+  };
+}
+
+export function editScreen(app: AdminApp, route: AdminRoute, resource: AdminResource): AdminScreen {
+  return async (request) => {
+    const id = idOf(request);
+    if (request.method === 'GET') {
+      const row = await findRow(resource, request.ctx.actor, id);
+      const decision = decideOperation(resource, 'update', request.ctx, id, row);
+      if (!decision.allowed) return refusedPage(app, request, route, decision);
+      if (row === null) return notFound(app, resource, request);
+      return framed(
+        app,
+        request,
+        resource.titleKey,
+        await form(app, resource, request, 'edit', row, []),
+      );
+    }
+    const input = decodeForm(resource, request.form ?? {});
+    const result = await adminUpdate<AdminRow>(resource, request.ctx, id, input);
+    if (result.ok) return { kind: 'redirect', location: rowHref(app, resource, id) };
+    if (result.kind === 'denied') return refused(app, request, resource.titleKey, result.decision);
+    if (result.kind === 'missing') return notFound(app, resource, request);
+    return framed(
+      app,
+      request,
+      resource.titleKey,
+      await form(app, resource, request, 'edit', input, result.issues),
+      422,
+    );
+  };
+}

package/src/screen-system.tsx

@@ -0,0 +1,69 @@
+// The two built-in screens that are neither a resource nor the jobs dashboard (`jobs/`): the
+// audit trail and cross-entity search. Each is decided by its own route's permission pair through
+// `decideAll` — the same gate a custom page gets — before anything is read.
+
+import { t } from '@ultimat3/i18n';
+import { Card } from '@ultimat3/ui';
+import type { AdminApp, AdminRoute } from './admin';
+import styles from './admin.module.scss';
+import { operationLabel } from './detail';
+import { type AdminScreen, guardedScreen } from './screen-frame';
+import { adminSearch } from './search';
+
+/** How many audit entries one screen shows — newest first, from whichever log the admin names. */
+const AUDIT_PAGE = 100;
+
+export function auditScreen(app: AdminApp, route: AdminRoute): AdminScreen {
+  return guardedScreen(app, route, async () => {
+    const entries = await app.audit.entries({ limit: AUDIT_PAGE });
+    return (
+      <Card>
+        {entries.length === 0 ? (
+          <p class="x-admin-empty">{t('admin.audit.empty')}</p>
+        ) : (
+          <ol class={styles['list']}>
+            {entries.map((entry) => (
+              <li>
+                <code>{entry.at}</code> <span>{entry.actor.id}</span>{' '}
+                <span>{operationLabel(entry)}</span>{' '}
+                <span class={styles['mono']}>{entry.entity}</span>{' '}
+                <span data-outcome={entry.outcome}>
+                  {t(`admin.audit.outcome.${entry.outcome}`)}
+                </span>
+              </li>
+            ))}
+          </ol>
+        )}
+      </Card>
+    );
+  });
+}
+
+/** `?term=` — the shell's search box is a native GET at this route. */
+export function searchScreen(app: AdminApp, route: AdminRoute): AdminScreen {
+  return guardedScreen(app, route, async (request) => {
+    const term = new URL(request.url).searchParams.get('term') ?? '';
+    const result = await adminSearch({ term, resources: app.resources, ctx: request.ctx });
+    return (
+      <Card>
+        {result.hits.length === 0 ? (
+          <p class="x-admin-empty">{t('admin.list.empty')}</p>
+        ) : (
+          <ul class={styles['list']}>
+            {result.hits.map((hit) => (
+              <li>
+                <a href={`${app.basePath}${hit.href}`}>{hit.label}</a>{' '}
+                <span class={styles['mono']}>{hit.entity}</span>
+              </li>
+            ))}
+          </ul>
+        )}
+        {result.skipped.map((skip) => (
+          <p class={styles['note']}>
+            <span class={styles['mono']}>{skip.entity}</span> {t(skip.reason)}
+          </p>
+        ))}
+      </Card>
+    );
+  });
+}

package/src/screens.ts

@@ -0,0 +1,56 @@
+// View → screen: the one table that says what renders at each route of the admin. A route whose
+// view has no row here does not compile, so a new `AdminView` cannot mount with nothing behind it.
+
+import type { AdminApp, AdminRoute, AdminView } from './admin';
+import { AdminPagePathInvalidError } from './errors';
+import { jobsOverviewScreen } from './jobs/overview';
+import { type AdminScreen, guardedScreen } from './screen-frame';
+import { homeScreen } from './screen-home';
+import { lookupScreen } from './screen-lookup';
+import { createScreen, detailScreen, editScreen, listScreen } from './screen-resource';
+import { auditScreen, searchScreen } from './screen-system';
+
+type Build = (app: AdminApp, route: AdminRoute) => AdminScreen;
+
+/** A resource view names its entity; the table and `defineAdmin` are built from the same list. */
+const resourceOf = (app: AdminApp, route: AdminRoute) => app.resource(route.entity ?? '');
+
+const SCREENS: Readonly<Record<AdminView, Build>> = {
+  dashboard: homeScreen,
+  search: searchScreen,
+  jobs: jobsOverviewScreen,
+  audit: auditScreen,
+  list: (app, route) => listScreen(app, resourceOf(app, route)),
+  lookup: (app, route) => lookupScreen(app, resourceOf(app, route)),
+  detail: (app, route) => detailScreen(app, resourceOf(app, route)),
+  create: (app, route) => createScreen(app, route, resourceOf(app, route)),
+  edit: (app, route) => editScreen(app, route, resourceOf(app, route)),
+  page: (app, route) => {
+    const component = route.component;
+    // `pages.ts` sets it on every `view: 'page'` it builds; a hand-made route without one is a
+    // path with nothing behind it, refused where it would have been mounted.
+    if (component === undefined) {
+      throw new AdminPagePathInvalidError({
+        path: route.path,
+        cause: 'is a page route with no component',
+        fix: 'declare it in `pages:` on defineAdmin() — { path, titleKey, permissions, component }',
+      });
+    }
+    return guardedScreen(app, route, (request) => component(request));
+  },
+};
+
+/** The same table as a Map: a view that is not one of the nine has no screen, not a prototype's. */
+const SCREEN_BY_VIEW: ReadonlyMap<string, Build> = new Map(Object.entries(SCREENS));
+
+export function screenFor(app: AdminApp, route: AdminRoute): AdminScreen {
+  const build = SCREEN_BY_VIEW.get(route.view);
+  if (build === undefined) {
+    throw new AdminPagePathInvalidError({
+      path: route.path,
+      cause: `has the view "${route.view}", which no screen renders`,
+      fix: 'declare the screen in `pages:` on defineAdmin() — { path, titleKey, permissions, component }',
+    });
+  }
+  return build(app, route);
+}