@ultimat3/admin 23.0.0 → 25.0.0

package/src/screen-home-access.tsx

@@ -0,0 +1,117 @@
+// The `/admin` home's "Access" half: per resource the actor may open, the decision behind every
+// operation it offers — the same decision the call obeys. Data-second on the page, so each matrix is
+// a native `<details>`, closed, its summary the resource and how many of its operations are allowed.
+
+import { t } from '@ultimat3/i18n';
+import { Badge } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+import styles from './admin.module.scss';
+import type { CrudCtx } from './crud';
+import { decideOperation, permissionsForOperation } from './crud';
+import { ADMIN_OPERATIONS, type AdminOperation } from './permissions';
+import type { AdminResource } from './resource';
+import homeStyles from './screen-home.module.scss';
+
+/** 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 interface HomeAccessProps {
+  readonly basePath: string;
+  readonly entries: readonly {
+    readonly resource: AdminResource;
+    readonly rows: readonly OperationDecision[];
+  }[];
+}
+
+/**
+ * Every matrix is in the document — closed is a presentation, never a withheld fact — and the
+ * summary's badge says at a glance whether the actor holds the whole resource or only part of it.
+ */
+export function HomeAccess(props: HomeAccessProps): JSX.Element {
+  return (
+    <section class={homeStyles['access']} aria-labelledby="admin-home-access">
+      <h2 id="admin-home-access" class={homeStyles['heading']}>
+        {t('admin.dashboard.access.title')}
+      </h2>
+      {props.entries.map(({ resource, rows }) => {
+        const allowed = rows.filter((row) => row.allowed).length;
+        return (
+          <details class={homeStyles['resource']}>
+            <summary class={homeStyles['summary']}>
+              <span class={homeStyles['name']}>{t(resource.titleKey)}</span>
+              <Badge tone={allowed === rows.length ? 'success' : 'neutral'} size="sm">
+                {t('admin.dashboard.access.allowed', { allowed, total: rows.length })}
+              </Badge>
+            </summary>
+            <div class={homeStyles['body']}>
+              <a href={`${props.basePath}${resource.path}`}>{t('admin.dashboard.access.open')}</a>
+              <div class={homeStyles['matrixScroll']}>
+                <OperationMatrix rows={rows} />
+              </div>
+            </div>
+          </details>
+        );
+      })}
+    </section>
+  );
+}

package/src/screen-home-counts.ts

@@ -0,0 +1,42 @@
+// The `/admin` home's figures: how many rows of each resource this actor could open. One
+// `AdminRepo.count` per resource that declared `count: true`, over its row scope and nothing else
+// — `rowWhere`, the predicate every list read starts from — so a tile never counts a hidden row.
+
+import type { AdminActor } from './authz';
+import { rowWhere } from './list-scope';
+import type { AdminResource } from './resource';
+
+export interface ResourceCount {
+  readonly resource: AdminResource;
+  readonly count: number;
+}
+
+/**
+ * The count of every resource handed in that declared `count: true`, in the order handed in. The caller hands in only what the
+ * actor may LIST (`canOperate(…, 'list', …)`): a size is a fact about a table, and a resource the
+ * actor may not open must not leak one. A repo with no `count()` — a hand-written one may leave it
+ * out — has no figure, so it is left out rather than shown as a zero it never measured.
+ *
+ * In parallel: these are independent reads, and the home page is the front door. A count the
+ * store refuses — a tenant-scoped table asked by an actor with no org is `X_TENANCY_UNSCOPED` —
+ * costs that resource its figure and nothing else, the way search lists a resource whose repo threw
+ * as skipped rather than answering 500 for the rest. The list behind the tile still reports it.
+ */
+export async function resourceCounts(
+  resources: readonly AdminResource[],
+  actor: AdminActor,
+): Promise<readonly ResourceCount[]> {
+  const countable = resources.flatMap((resource) => {
+    // Only a resource that asked: a home visit is otherwise one full count per table, every time.
+    if (!resource.count) return [];
+    const count = resource.repo?.count;
+    return count === undefined ? [] : [{ resource, count: count.bind(resource.repo) }];
+  });
+  const totals = await Promise.allSettled(
+    countable.map(({ resource, count }) => count(rowWhere(resource, actor))),
+  );
+  return countable.flatMap(({ resource }, index) => {
+    const total = totals[index];
+    return total?.status === 'fulfilled' ? [{ resource, count: total.value }] : [];
+  });
+}

package/src/screen-home-kpis.tsx

@@ -0,0 +1,64 @@
+// The `/admin` home's top band: one figure tile per resource the actor may open, each a link into
+// the list it counts, and the same figures as a ring of shares. Server markup only — the admin
+// ships no script — and a pure function of the counts it is handed.
+
+import { currentLocale, t } from '@ultimat3/i18n';
+import { Card, DonutChart, StatTile } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+import styles from './screen-home.module.scss';
+import type { ResourceCount } from './screen-home-counts';
+
+export interface HomeKpisProps {
+  readonly basePath: string;
+  readonly counts: readonly ResourceCount[];
+}
+
+/** `data-stat` for a resource's tile: the stable hook a test or a live check reads it through. */
+export const countStat = (entity: string): string => `admin-count-${entity}`;
+
+export function HomeKpis(props: HomeKpisProps): JSX.Element {
+  // The figure follows the page's locale: `Intl.NumberFormat` needs no time zone.
+  const count = new Intl.NumberFormat(currentLocale());
+  // Largest first, so the ring reads clockwise from the biggest share and the legend agrees. An
+  // empty table is no share of anything: its tile says 0, and a legend of "0 · 0%" rows is noise.
+  const ranked = props.counts
+    .filter((entry) => entry.count > 0)
+    .sort((left, right) => right.count - left.count);
+  return (
+    <section class={styles['band']} aria-labelledby="admin-home-records">
+      <h2 id="admin-home-records" class={styles['heading']}>
+        {t('admin.dashboard.records.title')}
+      </h2>
+      <ul class={styles['kpis']}>
+        {props.counts.map(({ resource, count: total }) => (
+          <li>
+            <a class={styles['kpi']} href={`${props.basePath}${resource.path}`}>
+              <StatTile
+                label={t(resource.titleKey)}
+                value={count.format(total)}
+                stat={countStat(resource.name)}
+              />
+            </a>
+          </li>
+        ))}
+      </ul>
+      {/* One non-empty resource is a whole with one part: a ring of 100% says nothing new. */}
+      {ranked.length < 2 ? null : (
+        <Card class={styles['share']}>
+          <DonutChart
+            label={t('admin.dashboard.records.label')}
+            showCaption
+            segments={ranked.map(({ resource, count: total }) => ({
+              label: t(resource.titleKey),
+              value: total,
+            }))}
+            centreLabel={t('admin.dashboard.records.total')}
+            keyLabel={t('admin.dashboard.records.resource')}
+            valueLabel={t('admin.dashboard.records.title')}
+            format={(value: number) => count.format(value)}
+          />
+        </Card>
+      )}
+    </section>
+  );
+}

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)}
         />