@ultimat3/admin 22.15.0 → 24.0.0

package/src/actions.tsx

@@ -1,34 +1,71 @@
-// Action buttons. The component renders `actionButtons()` and nothing else: if the gate did
-// not return a button, no markup exists for it — not hidden with CSS, not disabled. The same
-// gate then decides the call, so there is one authz system and the UI cannot lie about it.
+// Action buttons, as native form submits. The component renders `actionButtons()` and nothing
+// else: if the gate did not return a button, no markup exists for it — not hidden with CSS, not
+// disabled. The same gate then decides the POST, so there is one authz system and the UI cannot
+// lie about it.
 //
-// Fully controlled (no local signals): the route owns "which destructive action is pending",
-// which keeps this file a pure function of props and keeps the confirmation state somewhere
-// the server round-trip can also see.
+// A `<form method="post">` and a `type="submit"`, because an admin screen is `hydrate: 'never'`:
+// the browser's own form handling is the client. These were `type="button"` with an `onClick`
+// until the screens were mounted — markup that reads as a control and can never act.
 
 import { t } from '@ultimat3/i18n';
-import { Dialog } from '@ultimat3/ui';
+import { Button, Field, Input, Link } from '@ultimat3/ui';
 import type { JSX } from 'solid-js';
-import { type AdminActionButton, actionButtons } from './action-gate';
+import { actionButtons } from './action-gate';
+import styles from './admin.module.scss';
 import type { AdminActor, AdminAuthz, AdminSubject } from './authz';
 import { confirmationToken } from './permissions';
 import type { AdminAction } from './registry';
 
+/** The posted field that names which write a form is: an action here, a delete on the detail. */
+export const OPERATION_FIELD = '_operation';
+export const ACTION_OPERATION = 'action';
+export const DELETE_OPERATION = 'delete';
+/** A batch: posted at the LIST's URL, whose query string is the filter "all matching" means. */
+export const BATCH_OPERATION = 'batch';
+
+/** The query parameter a row's URL opens an action's own form with: `<row>?action=<name>`. */
+export const ACTION_PARAM = 'action';
+
+/** Where an action's form lives: the row's own URL, asked for that action. */
+export const actionFormHref = (rowHref: string, name: string): string =>
+  `${rowHref}?${ACTION_PARAM}=${encodeURIComponent(name)}`;
+
+/**
+ * The echo a destructive write must carry. Typed, not pre-filled: the token is on screen so it
+ * can be copied, and copying it is the deliberate act.
+ */
+export function ConfirmationField(props: { readonly token: string }): JSX.Element {
+  return (
+    <Field label={t('admin.actions.confirm.body', { token: props.token })} required>
+      {(control) => (
+        <Input
+          id={control.id}
+          aria-describedby={control['aria-describedby']}
+          name="confirmation"
+          autocomplete="off"
+          size="sm"
+          required
+        />
+      )}
+    </Field>
+  );
+}
+
 export interface AdminActionsProps {
   readonly actions: readonly AdminAction[];
   readonly actor: AdminActor;
   readonly authz: AdminAuthz;
-  // `| undefined` is explicit on every optional prop: under exactOptionalPropertyTypes a
-  // parent that forwards its own optional handler would otherwise not typecheck.
+  // `| undefined` is explicit: under exactOptionalPropertyTypes a parent that forwards its own
+  // optional subject would otherwise not typecheck.
   readonly subject?: AdminSubject | undefined;
-  /** A non-destructive press, or a confirmed destructive one. */
-  readonly onRun?: ((button: AdminActionButton, confirmation: string) => void) | undefined;
-  /** A destructive press: the route sets `pending` and re-renders. */
-  readonly onRequestConfirm?: ((button: AdminActionButton) => void) | undefined;
-  readonly pending?: AdminActionButton | null | undefined;
-  readonly confirmation?: string | undefined;
-  readonly onConfirmationInput?: ((value: string) => void) | undefined;
-  readonly onCancel?: (() => void) | undefined;
+  /**
+   * Where the forms post: the URL of the row the action is about (`<base>/<resource>/<id>`), or
+   * the admin's base path for an app-wide action. The subject is the URL's, never a hidden field
+   * a stale page could have got wrong.
+   */
+  readonly href: string;
+  /** The resource's sealed column names: a `when` never reads one. */
+  readonly sealed?: readonly string[] | undefined;
 }
 
 export function AdminActions(props: AdminActionsProps): JSX.Element {
@@ -37,58 +74,44 @@ export function AdminActions(props: AdminActionsProps): JSX.Element {
     actor: props.actor,
     authz: props.authz,
     ...(props.subject === undefined ? {} : { subject: props.subject }),
+    ...(props.sealed === undefined ? {} : { sealed: props.sealed }),
   });
 
-  const expected = confirmationToken(props.subject?.entity ?? 'admin', props.subject?.id ?? '');
-  const pending = props.pending ?? null;
-  const typed = props.confirmation ?? '';
-
-  const press = (button: AdminActionButton): void => {
-    if (button.destructive) props.onRequestConfirm?.(button);
-    else props.onRun?.(button, '');
-  };
-
   if (buttons.length === 0) return <span class="x-admin-actions-empty" />;
 
-  return (
-    <fieldset class="x-admin-actions" aria-label={t('admin.actions.label')}>
-      {buttons.map((button) => (
-        <button
-          type="button"
-          data-destructive={button.destructive ? 'true' : undefined}
-          onClick={() => press(button)}
-        >
-          {t(button.labelKey)}
-        </button>
-      ))}
+  const expected = confirmationToken(props.subject?.entity ?? 'admin', props.subject?.id ?? '');
 
-      <Dialog
-        open={pending !== null}
-        title={t('admin.actions.confirm.title')}
-        onClose={() => props.onCancel?.()}
-      >
-        <p>{t('admin.actions.confirm.body', { token: expected })}</p>
-        <label for="x-admin-confirm">{t('admin.actions.confirm.label')}</label>
-        <input
-          id="x-admin-confirm"
-          name="confirmation"
-          autocomplete="off"
-          value={typed}
-          onInput={(event: InputEvent) => {
-            const target = event.currentTarget;
-            props.onConfirmationInput?.(target instanceof HTMLInputElement ? target.value : '');
-          }}
-        />
-        <button
-          type="button"
-          disabled={typed !== expected}
-          onClick={() => {
-            if (pending !== null) props.onRun?.(pending, typed);
-          }}
-        >
-          {t('admin.actions.confirm.submit')}
-        </button>
-      </Dialog>
-    </fieldset>
+  return (
+    <span class={styles['actions']}>
+      {buttons.map((button) =>
+        // An action that takes input is a LINK to its own form — a page the server renders, at
+        // the row's URL — and never a button that would post an input nobody typed.
+        button.form ? (
+          <Link
+            appearance="button"
+            size="sm"
+            variant="secondary"
+            tone={button.destructive ? 'danger' : 'neutral'}
+            href={actionFormHref(props.href, button.name)}
+          >
+            {t(button.labelKey)}
+          </Link>
+        ) : (
+          <form class={styles['actionForm']} method="post" action={props.href}>
+            <input type="hidden" name={OPERATION_FIELD} value={ACTION_OPERATION} />
+            <input type="hidden" name="name" value={button.name} />
+            {button.destructive ? <ConfirmationField token={expected} /> : null}
+            <Button
+              type="submit"
+              size="sm"
+              variant="secondary"
+              tone={button.destructive ? 'danger' : 'neutral'}
+            >
+              {t(button.labelKey)}
+            </Button>
+          </form>
+        ),
+      )}
+    </span>
   );
 }

package/src/actor.ts

@@ -0,0 +1,53 @@
+// Who the dashboard is acting as, by default: the actor the HTTP pipeline already resolved for
+// this request, read off the framework's own request context — so the admin cannot grow a session
+// lookup of its own beside the app's.
+
+import { type Actor, isAnonymous, tryUseContext } from '@ultimat3/core';
+import type { AdminActor } from './authz';
+
+/**
+ * `null` for anonymous, and that is a real answer rather than a missing one: every operation an
+ * unauthenticated caller asks about is refused by the same `decideAll()` that refuses a signed-in
+ * actor who lacks the grant. The tenant rides along — a role-only rule would otherwise allow a row
+ * from another org.
+ */
+export const adminActorFrom = (
+  actor: Actor,
+  locale: string,
+  timeZone: string,
+): AdminActor | null =>
+  isAnonymous(actor)
+    ? null
+    : {
+        id: actor.id,
+        roles: actor.roles,
+        locale,
+        timeZone,
+        ...(actor.orgId === undefined ? {} : { orgId: actor.orgId }),
+      };
+
+export interface AdminRequestActor {
+  readonly actor: AdminActor | null;
+  /** Every audit row is keyed by it, so a denial is traceable to the request that caused it. */
+  readonly requestId: string;
+}
+
+/** The id an audit row carries when no request is in flight — a prerender, a script, a test. */
+export const NO_REQUEST_ID = 'no-request';
+
+/**
+ * The actor for the in-flight request. `tryUseContext()` and not `useContext()`: a test calls a
+ * screen with no request in flight, and "no context" is anonymous, not a crash.
+ */
+export const requestActor = (): AdminRequestActor => {
+  const ctx = tryUseContext();
+  if (ctx === undefined) return { actor: null, requestId: NO_REQUEST_ID };
+  return { actor: adminActorFrom(ctx.actor, ctx.locale, ctx.tz), requestId: ctx.requestId };
+};
+
+/**
+ * Anonymous is a real actor id on a decision — `decideAll()` refuses it exactly as it refuses a
+ * signed-in actor missing the grant, and an audit row that says `anonymous` is more useful than
+ * one that says nothing.
+ */
+export const ANONYMOUS_ADMIN_ACTOR: AdminActor = Object.freeze({ id: 'anonymous', roles: [] });

package/src/admin.module.scss

@@ -0,0 +1,298 @@
+// The admin's own layer, on @ultimat3/ui's tokens directly. Semantic roles and token rungs only:
+// a raw colour here would paint one theme correctly and the other one wrong, and a raw length is
+// a second scale beside the one every other screen is drawn on.
+
+@use '@ultimat3/ui/tokens' as t;
+
+.shell {
+  display: grid;
+  grid-template-columns: minmax(t.rem(192), t.rem(256)) 1fr;
+  gap: t.space(6);
+  min-block-size: 100dvh;
+  background: t.role('bg');
+  color: t.role('fg');
+
+  // One column under the `md` rung: the sidebar becomes a block above the screen it navigates.
+  @include t.respond-down('md') {
+    grid-template-columns: 1fr;
+  }
+}
+
+.skip {
+  @include t.visually-hidden;
+
+  &:focus-visible {
+    @include t.focus-ring;
+  }
+}
+
+.side {
+  @include t.surface('surface', 'sm');
+  @include t.padding-block(t.space(6));
+  @include t.padding-inline(t.space(4));
+  @include t.column(t.space(4));
+
+  border-inline-end: t.stroke(hairline) solid t.role('line');
+}
+
+.brand {
+  @include t.row(t.space(2));
+
+  font-size: t.text('lg');
+  font-weight: t.weight('semibold');
+  color: t.role('fg-strong');
+  text-decoration: none;
+}
+
+.actor {
+  margin: 0;
+  font-size: t.text('sm');
+  color: t.role('fg-muted');
+}
+
+.search {
+  display: grid;
+}
+
+.hidden {
+  @include t.visually-hidden;
+}
+
+.group {
+  display: grid;
+  gap: t.space(2);
+}
+
+.groupTitle {
+  @include t.label-caps;
+
+  margin: 0;
+  color: t.role('fg-muted');
+}
+
+.navList {
+  display: grid;
+  gap: t.space(1);
+  padding: 0;
+  margin: 0;
+  list-style: none;
+}
+
+.navLink {
+  @include t.transition(background-color, color);
+
+  display: block;
+  padding: t.space(2) t.space(3);
+  border-radius: t.radius('md');
+  color: t.role('fg');
+  text-decoration: none;
+
+  &:hover,
+  &[aria-current='page'] {
+    background: t.role('bg-soft');
+    color: t.role('fg-strong');
+  }
+
+  &:focus-visible {
+    @include t.focus-ring;
+  }
+}
+
+.main {
+  @include t.padding-block(t.space(8));
+  @include t.padding-inline(t.space(6));
+  @include t.column(t.space(6));
+
+  min-inline-size: 0;
+}
+
+.title {
+  margin: 0;
+  font-size: t.text('2xl');
+  color: t.role('fg-strong');
+}
+
+.toolbar {
+  @include t.row(t.space(3), center, space-between);
+
+  flex-wrap: wrap;
+}
+
+.panel {
+  display: grid;
+  gap: t.space(4);
+}
+
+.matrix {
+  inline-size: 100%;
+  border-collapse: collapse;
+  font-size: t.text('sm');
+
+  th,
+  td {
+    padding: t.space(2) t.space(3);
+    text-align: start;
+    border-block-end: t.stroke(hairline) solid t.role('line');
+    vertical-align: top;
+  }
+
+  th {
+    color: t.role('fg-muted');
+    font-weight: t.weight('semibold');
+  }
+}
+
+// The two verdict rows carry a tone, not a colour: `success` and `danger` both resolve in the
+// light and the dark scale.
+.allowed td:last-child {
+  color: t.role('success');
+}
+
+.denied td:last-child {
+  color: t.role('danger');
+}
+
+.mono {
+  @include t.data-text;
+}
+
+.fields {
+  display: grid;
+  grid-template-columns: minmax(t.rem(128), max-content) 1fr;
+  gap: t.space(2) t.space(4);
+  margin: 0;
+
+  dt {
+    color: t.role('fg-muted');
+    font-size: t.text('sm');
+  }
+
+  dd {
+    margin: 0;
+    min-inline-size: 0;
+    overflow-wrap: anywhere;
+  }
+}
+
+.form {
+  @include t.column(t.space(4));
+}
+
+// One titled group of a detail page or a form. A `<section>` on the detail, a `<fieldset>` on the
+// form — the same spacing, so the two read as one layout.
+.section {
+  @include t.column(t.space(3));
+
+  padding: 0;
+  margin: 0;
+  border: 0;
+
+  h3,
+  legend {
+    margin: 0;
+    padding: 0;
+    font-size: t.text('sm');
+    font-weight: t.weight('semibold');
+    color: t.role('fg-muted');
+  }
+}
+
+// The list's batch bar: what to run, over which rows, and the submit — one native form whose
+// row checkboxes sit in the table and join it through their `form` attribute.
+.batch {
+  @include t.row(t.space(3), end);
+
+  flex-wrap: wrap;
+  margin: 0;
+}
+
+// The counts a batch answers with, one term per outcome.
+.counts {
+  display: grid;
+  grid-template-columns: max-content max-content;
+  gap: t.space(1) t.space(4);
+  margin: 0;
+
+  dt {
+    color: t.role('fg-muted');
+  }
+
+  dd {
+    @include t.data-text;
+
+    margin: 0;
+  }
+}
+
+.actions {
+  @include t.row(t.space(2));
+
+  flex-wrap: wrap;
+}
+
+// One form per button — a native POST is the whole client on a page that never hydrates, and a
+// single form around several submits could not say which one was pressed.
+.actionForm {
+  @include t.row(t.space(2));
+
+  display: inline-flex;
+  margin: 0;
+}
+
+
+.note,
+.refusal {
+  margin: 0;
+  font-size: t.text('sm');
+  color: t.role('fg-muted');
+}
+
+.refusal {
+  @include t.surface('surface-raised', 'sm');
+  @include t.padding-block(t.space(4));
+  @include t.padding-inline(t.space(4));
+
+  border-inline-start: t.stroke(heavy) solid t.role('danger');
+  border-radius: t.radius('md');
+  color: t.role('fg');
+}
+
+.list {
+  display: grid;
+  gap: t.space(2);
+  padding: 0;
+  margin: 0;
+  list-style: none;
+}
+
+// The filter bar: controls flow and wrap, each as wide as its label needs, with the submit last.
+.filters {
+  @include t.row(t.space(3), end);
+
+  flex-wrap: wrap;
+  margin: 0;
+}
+
+// Two bounds of one filter, or a control and the link beside it.
+.range {
+  @include t.row(t.space(2), center);
+}
+
+.scopes {
+  @include t.row(t.space(1));
+
+  flex-wrap: wrap;
+  padding: 0;
+  margin: 0;
+  list-style: none;
+}
+
+// The jobs overview: a row of figure tiles that wraps, each a link to the list it counts.
+.tiles {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(t.rem(160), 1fr));
+  gap: t.space(3);
+  padding: 0;
+  margin: 0;
+  list-style: none;
+}