@ultimat3/admin 24.0.0 → 25.1.0

package/src/screen-home.module.scss

@@ -0,0 +1,169 @@
+// The `/admin` home's own layer: the KPI band and the access grid under it. Tiles wrap to two
+// across a phone and as many as fit beside the ring on a monitor; the matrix cards pair up only
+// once a card is wide enough that its permission column does not wrap mid-name.
+
+@use '@ultimat3/ui/tokens' as t;
+
+.band {
+  display: grid;
+  gap: t.space(4);
+  min-inline-size: 0;
+
+  @include t.respond-to('lg') {
+    grid-template-columns: minmax(0, 1fr) minmax(t.rem(320), t.rem(400));
+    align-items: start;
+  }
+}
+
+.heading {
+  @include t.label-caps;
+
+  grid-column: 1 / -1;
+  margin: 0;
+  color: t.role('fg-muted');
+}
+
+.kpis {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(t.rem(150), 1fr));
+  gap: t.space(3);
+  padding: 0;
+  margin: 0;
+  list-style: none;
+}
+
+// The whole tile is the link: one target for a pointer and for a keyboard alike, never smaller
+// than the touch target.
+.kpi {
+  @include t.focus-ring;
+
+  display: block;
+  block-size: 100%;
+  min-block-size: t.touch(target);
+  border-radius: t.radius('lg');
+  color: inherit;
+  text-decoration: none;
+
+  > * {
+    block-size: 100%;
+  }
+
+  &:hover > * {
+    border-color: t.role('accent', 0.6);
+  }
+}
+
+.share {
+  min-inline-size: 0;
+}
+
+.access {
+  display: grid;
+  gap: t.space(4);
+  min-inline-size: 0;
+
+  @include t.respond-to('xl') {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    align-items: start;
+  }
+}
+
+// One resource's matrix, closed by default: a native disclosure, so it opens with no script and its
+// summary row is one touch target with the name and the allowed-count badge on a line.
+.resource {
+  min-inline-size: 0;
+  border: t.stroke(hairline) solid t.role('line');
+  border-radius: t.radius('lg');
+  background: t.role('surface');
+}
+
+.summary {
+  @include t.focus-ring;
+
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: t.space(3);
+  min-block-size: t.touch(target);
+  padding: t.space(2) t.space(4);
+  cursor: pointer;
+  list-style: none;
+
+  .resource[open] > & {
+    border-block-end: t.stroke(hairline) solid t.role('line');
+  }
+}
+
+// `display: flex` drops the native marker, so the disclosure draws its own chevron: pointing along
+// the reading direction while closed, down once open.
+.summary::-webkit-details-marker {
+  display: none;
+}
+
+.summary::before {
+  flex: none;
+  inline-size: t.rem(8);
+  block-size: t.rem(8);
+  border-inline-end: t.stroke(thick) solid t.role('fg-muted');
+  border-block-end: t.stroke(thick) solid t.role('fg-muted');
+  content: '';
+  transform: rotate(-45deg);
+
+  @media (prefers-reduced-motion: no-preference) {
+    transition: transform t.duration(fast) t.easing(out);
+  }
+
+  [dir='rtl'] & {
+    transform: rotate(135deg);
+  }
+
+  .resource[open] > & {
+    transform: rotate(45deg);
+  }
+}
+
+.name {
+  flex: 1;
+  min-inline-size: 0;
+  font-weight: t.weight('semibold');
+  color: t.role('fg-strong');
+}
+
+.body {
+  display: grid;
+  gap: t.space(3);
+  padding: t.space(3) t.space(4) t.space(4);
+}
+
+// A matrix is three columns of short words and one of permission pairs. On a phone the pair takes
+// a line of its own under the operation and its verdict, so no column is cut at the card's edge;
+// the header row goes to assistive tech only, since each cell already reads in place.
+.matrixScroll {
+  min-inline-size: 0;
+
+  @include t.respond-down('sm') {
+    thead {
+      @include t.visually-hidden;
+    }
+
+    tr {
+      display: grid;
+      grid-template-columns: minmax(0, 1fr) auto;
+      column-gap: t.space(3);
+      padding-block: t.space(2);
+      border-block-end: t.stroke(hairline) solid t.role('line');
+    }
+
+    td {
+      padding: 0;
+      border: 0;
+    }
+
+    td:nth-child(2) {
+      grid-column: 1 / -1;
+      grid-row: 2;
+      overflow-wrap: anywhere;
+      color: t.role('fg-muted');
+    }
+  }
+}

package/src/screen-home.tsx

@@ -1,10 +1,8 @@
-// `/admin` — the dashboard: every resource this actor may open, the decision behind each of its
-// operations, and the app-wide actions. No row is read here: a dashboard that listed five rows of
-// every resource would be one query per entity on every visit to the front page.
+// `/admin` — the dashboard: how many rows of each resource this actor may open, the decision behind
+// each of its operations, and the app-wide actions. No row is READ here: a figure is one
+// `count()` per resource (`screen-home-counts.ts`), never a page of rows per entity per visit.
 
 import { t } from '@ultimat3/i18n';
-import { Card } from '@ultimat3/ui';
-import type { JSX } from 'solid-js';
 import { AdminActionForm } from './action-form';
 import { actionButtons, invokeAdminAction } from './action-gate';
 import { decodeActionInput, postedActionInput } from './action-input';
@@ -12,12 +10,10 @@ import { ACTION_OPERATION, ACTION_PARAM, AdminActions, OPERATION_FIELD } from '.
 import type { AdminApp, AdminRoute } from './admin';
 import styles from './admin.module.scss';
 import { decideAll } from './authz';
-import type { CrudCtx } from './crud';
-import { canOperate, decideOperation, permissionsForOperation } from './crud';
+import { canOperate } from './crud';
 import { posted } from './form-decode';
-import { ADMIN_OPERATIONS, type AdminOperation, confirmationToken } from './permissions';
+import { confirmationToken } from './permissions';
 import type { AdminAction } from './registry';
-import type { AdminResource } from './resource';
 import {
   type AdminRouteRequest,
   type AdminRouteResponse,
@@ -26,70 +22,12 @@ import {
   refused,
   refusedPage,
 } from './screen-frame';
+import { HomeAccess, operationMatrix } from './screen-home-access';
+import { resourceCounts } from './screen-home-counts';
+import { HomeKpis } from './screen-home-kpis';
 import type { ValidationIssue } from './validate';
 
-/** One row of an operation matrix: the decision the dashboard renders AND the call obeys. */
-export interface OperationDecision {
-  readonly operation: AdminOperation;
-  readonly allowed: boolean;
-  readonly permissions: readonly string[];
-  readonly reason: string;
-}
-
-/**
- * Every operation the resource OFFERS, with its decision. This IS the view-only proof, rendered
- * rather than asserted. One it does not offer has no row: "denied" would read as a missing grant
- * the operator should ask for, when no grant opens it.
- */
-export const operationMatrix = (
-  resource: AdminResource,
-  ctx: CrudCtx,
-): readonly OperationDecision[] =>
-  ADMIN_OPERATIONS.filter((operation) => resource.operations.includes(operation)).map(
-    (operation) => {
-      const decision = decideOperation(resource, operation, ctx);
-      return {
-        operation,
-        allowed: decision.allowed,
-        permissions: permissionsForOperation(resource.permission, operation),
-        reason: decision.reason,
-      };
-    },
-  );
-
-/**
- * The permission matrix, rendered. A reader can see that `create`, `update` and `delete` are
- * refused and WHICH permission refused them — the same decision the call obeys, not a note about
- * a button that was left out.
- */
-export function OperationMatrix(props: {
-  readonly rows: readonly OperationDecision[];
-}): JSX.Element {
-  return (
-    <table class={styles['matrix']}>
-      <thead>
-        <tr>
-          <th>{t('admin.matrix.operation')}</th>
-          <th>{t('admin.matrix.permissions')}</th>
-          <th>{t('admin.matrix.verdict')}</th>
-        </tr>
-      </thead>
-      <tbody>
-        {props.rows.map((row) => (
-          <tr class={row.allowed ? styles['allowed'] : styles['denied']}>
-            <td>{t(`admin.operation.${row.operation}`)}</td>
-            <td class={styles['mono']}>{row.permissions.join(' + ')}</td>
-            <td>
-              {row.allowed
-                ? t('admin.matrix.allowed')
-                : `${t('admin.matrix.deniedBy')} ${row.reason}`}
-            </td>
-          </tr>
-        ))}
-      </tbody>
-    </table>
-  );
-}
+export { type OperationDecision, OperationMatrix, operationMatrix } from './screen-home-access';
 
 /** An app-wide action's POST: the same gate, with no row for a subject. */
 async function globalWrite(
@@ -172,6 +110,8 @@ export function homeScreen(app: AdminApp, route: AdminRoute): AdminScreen {
     }
 
     const open = app.resources.filter((resource) => canOperate(resource, 'list', request.ctx));
+    // Counted only over what the actor may list: the size of a table is itself a fact to gate.
+    const counts = await resourceCounts(open, request.ctx.actor);
     return framed(
       app,
       request,
@@ -184,17 +124,16 @@ export function homeScreen(app: AdminApp, route: AdminRoute): AdminScreen {
           href={app.basePath}
         />
         {open.length === 0 ? <p class={styles['note']}>{t('admin.actions.none')}</p> : null}
-        {open.map((resource) => (
-          <Card
-            header={
-              <h2>
-                <a href={`${app.basePath}${resource.path}`}>{t(resource.titleKey)}</a>
-              </h2>
-            }
-          >
-            <OperationMatrix rows={operationMatrix(resource, request.ctx)} />
-          </Card>
-        ))}
+        {counts.length === 0 ? null : <HomeKpis basePath={app.basePath} counts={counts} />}
+        {open.length === 0 ? null : (
+          <HomeAccess
+            basePath={app.basePath}
+            entries={open.map((resource) => ({
+              resource,
+              rows: operationMatrix(resource, request.ctx),
+            }))}
+          />
+        )}
       </div>,
     );
   };

package/src/screen-lookup.tsx

@@ -147,7 +147,7 @@ export function lookupScreen(app: AdminApp, resource: AdminResource): AdminScree
           </ul>
         )}
         <Pagination
-          nextCursor={page.hasMore ? (page.nextCursor ?? undefined) : undefined}
+          nextCursor={page.hasMore ? page.nextCursor : undefined}
           prevCursor={page.prevCursor ?? undefined}
           hrefFor={(cursor) => state(cursor)}
         />

package/src/screen-resource.tsx

@@ -34,7 +34,7 @@ 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 RelationNeed, relationDataFor, relationNeeds } from './relations';
 import type { AdminResource } from './resource';
 import { ROW_CHANGED_REASON, rowVersion, VERSION_FIELD } from './row-version';
 import { batchWrite, rowActionFormScreen, rowActionWrite } from './screen-action';
@@ -127,7 +127,7 @@ export function listScreen(app: AdminApp, resource: AdminResource): AdminScreen
     // 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(
+      relationDataFor(
         app.resources,
         request.ctx,
         relationNeeds(result.page.rows, resource.listFields, resource.filters),
@@ -172,7 +172,7 @@ const relationsOf = (
   row: AdminRow,
   picking: boolean,
 ): Promise<WidgetContext> =>
-  relationsFor(
+  relationDataFor(
     app.resources,
     request.ctx,
     relationNeeds([row], resource.fields, picking ? resource.formFields : []),
@@ -259,7 +259,7 @@ export function detailScreen(app: AdminApp, resource: AdminResource): AdminScree
     ]);
     // ONE label read per referenced target for the whole page — this row's references and every
     // related row's together.
-    const relations = await relationsFor(
+    const relations = await relationDataFor(
       app.resources,
       request.ctx,
       mergedNeeds([

package/src/search.ts

@@ -6,7 +6,7 @@ import { finiteCount } from '@ultimat3/core';
 import { expectedQueryLoop } from '@ultimat3/db';
 import { type AuditEntry, deniedDraft } from './audit';
 import type { AdminActor } from './authz';
-import { denied } from './authz';
+import { adminDenied } from './authz';
 import type { CrudCtx } from './crud';
 import { decideOperation } from './crud';
 import { rowWhere } from './list-scope';
@@ -145,7 +145,7 @@ export async function adminSearch(input: AdminSearchInput): Promise<AdminSearchR
             entityId: null,
             // A resource that does not OFFER search was refused by the registry, not by a policy,
             // and the decision object would otherwise read `allow` on a denied entry.
-            decision: offered ? decision : denied(decision.permission, SKIPPED_FORBIDDEN),
+            decision: offered ? decision : adminDenied(decision.permission, SKIPPED_FORBIDDEN),
           }),
         ),
       );

package/src/inert-jsx.ts

@@ -1,182 +0,0 @@
-// TEST-ONLY. Calls an admin `.tsx` view as the plain function it is and walks what came back, so
-// a test can assert on the tree a screen produced rather than on a value it also constructed.
-//
-// Which JSX factory a `.tsx` in this package compiled to is NOT ours to choose: `@ultimat3/render`
-// installs a process-global `Bun.plugin` `onLoad` for `/\.tsx$/` at import (`routes.ts` imports it,
-// so any sibling suite can win the race) and `bun test` is one process. Both factories build the
-// same shape — a `type`, a `props`, children under `props.children` — so this walker recognises
-// both and the run's file order stops deciding. Recognising neither is what falls through to
-// `String(value)` and asserts against `"[object Object]"`.
-
-// The subpath, never the barrel: this is a test harness and the design system's `index.ts` is its
-// semver'd contract (`packages/ui/CLAUDE.md`). It is imported for `globalThis.React`'s ONE counter.
-import { probe, unprobe } from '@ultimat3/ui/jsx-probe';
-
-/** `@ultimat3/render`'s node brand, read off the GLOBAL symbol registry rather than imported. */
-const RENDER_NODE: symbol = Symbol.for('ultimate.render.jsx');
-
-export type InertComponent = (props: Record<string, unknown>) => unknown;
-
-export interface InertNode {
-  readonly type: string | InertComponent;
-  readonly props: Record<string, unknown>;
-}
-
-export function isInertNode(value: unknown): value is InertNode {
-  if (typeof value !== 'object' || value === null) return false;
-  return 'inert' in value || RENDER_NODE in value;
-}
-
-/**
- * Build a node by hand, the shape the installed factory builds. NOT the installed factory — that is
- * `@ultimat3/ui`'s, so there is one owner of `globalThis.React` (see `installFactory` below). This
- * is what a test uses to construct a tree it did not render.
- */
-export function h(
-  type: string | InertComponent,
-  props: Record<string, unknown> | null,
-  ...children: readonly unknown[]
-): InertNode {
-  const base = { ...(props ?? {}) };
-  if (children.length > 0) base['children'] = children.length === 1 ? children[0] : children;
-  return { inert: true, type, props: base } as unknown as InertNode;
-}
-
-/**
- * Install the classic-factory global, through `@ultimat3/ui`'s ONE counter over `globalThis.React`.
- *
- * This package kept its own `depth`/`saved` pair until 2026-08-22, and two counters over one
- * property restore in the wrong order: admin installs (saving the real binding), ui installs
- * (saving ADMIN's factory), admin restores (its counter hits 0 → the real binding is back), ui
- * restores (its counter hits 0 → admin's factory goes back over it). `bun test` is one process and
- * `packages/ui` and `packages/admin` are one run, so the interleave is reachable, and the global
- * was left holding a harness the run had already torn down. `admin` is tier 5 and `ui` is tier 4,
- * so importing down is the fix; the two factories build the same `{ inert, type, props }` shape,
- * which is what `isInertNode` recognises.
- */
-export function installFactory(): void {
-  probe();
-}
-
-/** Undo the matching `installFactory()`. Unbalanced calls are inert. */
-export function restoreFactory(): void {
-  unprobe();
-}
-
-/**
- * Every node in the tree, depth first, with nested components CALLED and thunks invoked — a
- * component that reads a prop inside one renders nothing until something asks.
- *
- * Component nodes are KEPT as well as expanded, so a test can assert on the props a view handed
- * `<Money>` — the admin's contract with the design system — and not only on the markup ui chose
- * to emit for them, which is ui's business and changes without this package changing.
- */
-export function nodesOf(value: unknown): InertNode[] {
-  if (value === null || value === undefined || typeof value === 'boolean') return [];
-  if (typeof value === 'string' || typeof value === 'number') return [];
-  if (Array.isArray(value)) return value.flatMap(nodesOf);
-  if (isInertNode(value)) {
-    if (typeof value.type === 'function') return [value, ...nodesOf(value.type(value.props))];
-    return [value, ...nodesOf(value.props['children'])];
-  }
-  if (typeof value === 'function') return nodesOf((value as () => unknown)());
-  return [];
-}
-
-/**
- * The tree this package itself built: component nodes are kept but NOT called, so the walk stops
- * at the design-system boundary. Use this when a design-system component's own internals would
- * otherwise answer a query about the admin's markup — `<Dialog>` renders a close `<button>`, and a
- * test asking "which buttons did the action bar render" must not be handed ui's.
- */
-export function shallowNodesOf(value: unknown): InertNode[] {
-  if (value === null || value === undefined || typeof value === 'boolean') return [];
-  if (typeof value === 'string' || typeof value === 'number') return [];
-  if (Array.isArray(value)) return value.flatMap(shallowNodesOf);
-  if (isInertNode(value)) return [value, ...shallowNodesOf(value.props['children'])];
-  if (typeof value === 'function') return shallowNodesOf((value as () => unknown)());
-  return [];
-}
-
-/** Nodes rendered by the named component — `byComponent(nodes, 'Money')`. */
-export function byComponent(nodes: readonly InertNode[], name: string): InertNode[] {
-  return nodes.filter((node) => typeof node.type === 'function' && node.type.name === name);
-}
-
-const SKIPPED_PROPS = new Set(['children', 'ref', 'innerHTML']);
-
-function attributes(props: Record<string, unknown>): string {
-  return Object.entries(props)
-    .filter(([name, value]) => {
-      if (SKIPPED_PROPS.has(name) || name.startsWith('on')) return false;
-      return value !== undefined && value !== null && value !== false;
-    })
-    .map(([name, value]) => (value === true ? ` ${name}` : ` ${name}="${String(value)}"`))
-    .join('');
-}
-
-/** The tree as markup. Unknown values are `String()`d, which the premise test refuses to allow. */
-export function renderHtml(value: unknown): string {
-  if (value === null || value === undefined || typeof value === 'boolean') return '';
-  if (typeof value === 'string' || typeof value === 'number') return String(value);
-  if (Array.isArray(value)) return value.map(renderHtml).join('');
-  if (isInertNode(value)) {
-    if (typeof value.type === 'function') return renderHtml(value.type(value.props));
-    const inner = renderHtml(value.props['children']);
-    return `<${value.type}${attributes(value.props)}>${inner}</${value.type}>`;
-  }
-  if (typeof value === 'function') return renderHtml((value as () => unknown)());
-  return String(value);
-}
-
-/** Render a component to its host nodes. `props` is the component's own, untyped on purpose. */
-export function renderNodes(component: unknown, props: Record<string, unknown> = {}): InertNode[] {
-  return nodesOf((component as InertComponent)(props));
-}
-
-/**
- * `renderNodes`, stopping at the design-system boundary — the `shallowNodesOf` sibling. The
- * `unknown` parameter is what makes it usable: a screen's props are typed and generic, so a test
- * calling one through `as (props: Record<string, unknown>) => unknown` is a conversion TypeScript
- * refuses outright. One widening here beats one per call site.
- */
-export function renderShallowNodes(
-  component: unknown,
-  props: Record<string, unknown> = {},
-): InertNode[] {
-  return shallowNodesOf((component as InertComponent)(props));
-}
-
-/** Render a component to markup. */
-export function renderComponent(component: unknown, props: Record<string, unknown> = {}): string {
-  return renderHtml((component as InertComponent)(props));
-}
-
-export function byTag(nodes: readonly InertNode[], tag: string): InertNode[] {
-  return nodes.filter((node) => node.type === tag);
-}
-
-/** Nodes whose attribute equals `value`; `undefined` matches "carries the attribute at all". */
-export function withAttr(nodes: readonly InertNode[], name: string, value?: unknown): InertNode[] {
-  return nodes.filter((node) =>
-    value === undefined ? node.props[name] !== undefined : node.props[name] === value,
-  );
-}
-
-/** The one node a test means, or a throw naming what it looked for — never a silent `undefined`. */
-export function one(nodes: readonly InertNode[], what: string): InertNode {
-  const node = nodes[0];
-  if (node === undefined || nodes.length !== 1) {
-    throw new Error(`expected exactly one ${what}, found ${nodes.length}`);
-  }
-  return node;
-}
-
-/** Call an element's event handler prop, e.g. `fire(button, 'onClick', {})`. */
-export function fire(node: InertNode, handler: string, event: unknown): void {
-  const fn = node.props[handler];
-  if (typeof fn !== 'function') {
-    throw new Error(`node <${String(node.type)}> carries no ${handler}`);
-  }
-  (fn as (e: unknown) => void)(event);
-}