@ultimat3/admin 22.15.0 → 24.0.0

package/src/keyset-seek.ts

@@ -0,0 +1,189 @@
+// The keyset seek on the PAIR `(sort, id)`, for a typed handle whose chain is a conjunction: the
+// row-value comparison `(sort, id) > (v, id₀)` is read as disjoint segments in walk order — the
+// rest of the boundary's class by id, then everything past the class, then the NULLs — so a sort
+// value shared by any number of rows, and a NULL one, is a position like any other.
+
+import type { AdminListQuery, AdminRow, AdminTableRead, KeysetBound } from './registry';
+
+type TableOperator = Parameters<AdminTableRead['andWhere']>[1];
+type Direction = 'asc' | 'desc';
+
+/** One `andWhere` term. `value` is absent for the two null tests. */
+export interface SeekTerm {
+  readonly field: string;
+  readonly op: TableOperator;
+  readonly value?: unknown;
+}
+
+export interface SeekColumn {
+  readonly field: string;
+  readonly idField: string;
+  readonly nullable: boolean;
+  /**
+   * A `timestamptz`. The row hands it back as a `Date` — milliseconds — while Postgres keeps and
+   * orders microseconds, so a cursor can only name the boundary's MILLISECOND. Its class is that
+   * millisecond `[v, v + 1ms)`, ordered by id inside: the order both drivers can agree on.
+   */
+  readonly instant: boolean;
+  /** The bound's text back to what the handle compares: a `Date` for an instant. */
+  readonly typed: (value: string) => unknown;
+}
+
+const flip = (direction: Direction): Direction => (direction === 'asc' ? 'desc' : 'asc');
+
+const millisOf = (row: AdminRow, field: string): number | null => {
+  const value = row[field];
+  return value instanceof Date ? value.getTime() : null;
+};
+
+/** Where one walk segment reads. */
+interface Segments {
+  readonly read: (
+    where: readonly SeekTerm[],
+    order: 'id' | 'pair',
+    limit: number,
+  ) => Promise<AdminRow[]>;
+  readonly column: SeekColumn;
+  readonly walk: Direction;
+}
+
+/** The terms that hold the boundary's class: equal, the same millisecond, or NULL. */
+const classOf = (column: SeekColumn, value: unknown): readonly SeekTerm[] => {
+  if (value === null) return [{ field: column.field, op: 'is-null' }];
+  if (column.instant && value instanceof Date) {
+    return [
+      { field: column.field, op: 'gte', value },
+      { field: column.field, op: 'lt', value: new Date(value.getTime() + 1) },
+    ];
+  }
+  return [{ field: column.field, op: 'eq', value }];
+};
+
+/** Strictly past the class of a present `value`, in the walk's direction. NULLs never match. */
+const pastClass = (column: SeekColumn, value: unknown, walk: Direction): readonly SeekTerm[] => {
+  if (walk === 'desc') return [{ field: column.field, op: 'lt', value }];
+  if (column.instant && value instanceof Date) {
+    return [{ field: column.field, op: 'gte', value: new Date(value.getTime() + 1) }];
+  }
+  return [{ field: column.field, op: 'gt', value }];
+};
+
+/** One class, by id, after `afterId` when given — exact whatever the class's internal order. */
+const classRows = (
+  at: Segments,
+  where: readonly SeekTerm[],
+  afterId: string | undefined,
+  limit: number,
+): Promise<AdminRow[]> =>
+  limit <= 0
+    ? Promise.resolve([])
+    : at.read(
+        afterId === undefined
+          ? where
+          : [
+              ...where,
+              { field: at.column.idField, op: at.walk === 'asc' ? 'gt' : 'lt', value: afterId },
+            ],
+        'id',
+        limit,
+      );
+
+/**
+ * Present values past `where`, `limit` of them in `(sort, id)` order. For an instant the LAST
+ * millisecond read may be cut part-way through and its rows are in microsecond order, so it is
+ * dropped and re-read whole by id — the order the next page's seek resumes in. Every earlier
+ * millisecond on the page is complete, and is put in that same order.
+ */
+async function valueRows(
+  at: Segments,
+  where: readonly SeekTerm[],
+  limit: number,
+): Promise<AdminRow[]> {
+  if (limit <= 0) return [];
+  const { column } = at;
+  const present: readonly SeekTerm[] =
+    where.length === 0 && column.nullable ? [{ field: column.field, op: 'is-not-null' }] : where;
+  if (!column.instant) return at.read(present, 'pair', limit);
+  const rows = await at.read(present, 'pair', limit + 1);
+  if (rows.length <= limit) return byMillisecondThenId(rows, column, at.walk);
+  const tail = millisOf(rows[limit - 1] ?? {}, column.field);
+  const extra = millisOf(rows[limit] ?? {}, column.field);
+  const kept = rows.slice(0, limit);
+  if (tail === null || tail !== extra) return byMillisecondThenId(kept, column, at.walk);
+  const whole = kept.filter((row) => millisOf(row, column.field) !== tail);
+  const rest = await classRows(
+    at,
+    classOf(column, new Date(tail)),
+    undefined,
+    limit - whole.length,
+  );
+  return [...byMillisecondThenId(whole, column, at.walk), ...rest];
+}
+
+/**
+ * Rows of one millisecond in id order. Code-unit order: it agrees with the database for a `uuid`
+ * key, which is the framework's; a text key under a non-C collation can disagree inside one
+ * millisecond, and only there.
+ */
+const byMillisecondThenId = (
+  rows: readonly AdminRow[],
+  column: SeekColumn,
+  walk: Direction,
+): AdminRow[] => {
+  const sign = walk === 'asc' ? 1 : -1;
+  return [...rows].sort((a, b) => {
+    const at = (millisOf(a, column.field) ?? 0) - (millisOf(b, column.field) ?? 0);
+    if (at !== 0) return sign * at;
+    const left = String(a[column.idField]);
+    const right = String(b[column.idField]);
+    return sign * (left < right ? -1 : left > right ? 1 : 0);
+  });
+};
+
+/**
+ * The page a query asks for, read in WALK order — forward from an `after` bound (or from the top),
+ * backward from a `before` one — and answered in the query's own sort order either way.
+ *
+ * NULL is the largest value, as both drivers order it: last ascending, first descending.
+ */
+export async function seekPage(
+  query: AdminListQuery,
+  column: SeekColumn,
+  read: (
+    where: readonly SeekTerm[],
+    order: { readonly by: 'id' | 'pair'; readonly direction: Direction },
+    limit: number,
+  ) => Promise<AdminRow[]>,
+): Promise<readonly AdminRow[]> {
+  const backward = query.before !== undefined;
+  const walk = backward ? flip(query.sort.direction) : query.sort.direction;
+  const at: Segments = {
+    column,
+    walk,
+    read: (where, by, limit) => read(where, { by, direction: walk }, limit),
+  };
+  const out: AdminRow[] = [];
+  const room = (): number => query.limit - out.length;
+  const bound: KeysetBound | undefined = query.after ?? query.before;
+  const nulls = (afterId?: string): Promise<AdminRow[]> =>
+    column.nullable ? classRows(at, classOf(column, null), afterId, room()) : Promise.resolve([]);
+
+  if (bound === undefined) {
+    if (walk === 'desc') out.push(...(await nulls()));
+    out.push(...(await valueRows(at, [], room())));
+    if (walk === 'asc') out.push(...(await nulls()));
+  } else if (bound.value === null) {
+    out.push(...(await nulls(bound.id)));
+    if (walk === 'desc') out.push(...(await valueRows(at, [], room())));
+  } else {
+    const value = column.typed(bound.value);
+    // The id IS the sort: its class is one row, so only the strict half is read.
+    if (column.field !== column.idField) {
+      out.push(...(await classRows(at, classOf(column, value), bound.id, room())));
+    }
+    out.push(...(await valueRows(at, pastClass(column, value, walk), room())));
+    if (walk === 'asc') out.push(...(await nulls()));
+  }
+  const page = out.slice(0, query.limit);
+  return backward ? page.reverse() : page;
+}

package/src/layout.tsx

@@ -1,11 +1,18 @@
-// The admin shell: skip link, header, permission-filtered nav, main region. Landmarks and a
-// visible focus order are the accessibility contract; the theme attributes come from the
-// token system, so nothing here knows a colour.
+// The admin shell: skip link, sidebar (brand, who is acting, search, permission-filtered nav, the
+// way back to the app), main region. Landmarks and a visible focus order are the accessibility
+// contract; the theme attributes come from the token system, so nothing here knows a colour.
+// Every control is a link or a native form — the shell ships no script.
 
-import { type Locale, registeredLocales, t } from '@ultimat3/i18n';
-import { LocaleSwitcher, ThemeToggle } from '@ultimat3/ui';
+// why: `*.module.scss` is typed by ONE ambient declaration, and it is `@ultimat3/ui`'s. A copy
+// here would be a `.d.ts` in `src/`, which the package-shape gate reads as a build artifact.
+/// <reference path="../../ui/src/scss.d.ts" />
+
+import { t } from '@ultimat3/i18n';
+import { Input } from '@ultimat3/ui';
 import type { JSX } from 'solid-js';
 import type { AdminApp } from './admin';
+import styles from './admin.module.scss';
+import type { AdminActor } from './authz';
 import type { NavGroup } from './nav';
 
 export interface AdminLayoutProps {
@@ -13,26 +20,36 @@ export interface AdminLayoutProps {
   /** Already filtered by `app.navFor(ctx)`. The layout does not decide visibility. */
   readonly nav: readonly NavGroup[];
   readonly currentPath: string;
-  readonly onSearch?: (term: string) => void;
-  readonly onLocaleChange?: (locale: Locale) => void;
+  /** Who is acting. Absent or anonymous reads as "not signed in" — never as an empty line. */
+  readonly actor?: AdminActor | null;
+  /** The screen's heading, already translated. One `<h1>` per screen, and this is it. */
+  readonly title?: string;
   readonly children: JSX.Element;
 }
 
+/** The one rendering of "who am I acting as", so no two screens can disagree about it. */
+export const actorLabel = (actor: AdminActor | null | undefined): string =>
+  actor === null || actor === undefined || actor.id === 'anonymous'
+    ? t('admin.actor.anonymous')
+    : t('admin.actor.signedIn', { id: actor.id, roles: (actor.roles ?? []).join(', ') });
+
 export function AdminLayout(props: AdminLayoutProps): JSX.Element {
   const theme = props.app.theme;
+  const base = props.app.basePath;
   return (
     <div
-      class="x-admin"
+      class={styles['shell']}
+      data-admin=""
       data-theme={theme['data-theme']}
       data-density={theme['data-density']}
       style={theme.style}
     >
-      <a class="x-admin-skip" href="#x-admin-main">
-        {t('admin.a11y.skip-to-content')}
-      </a>
+      <aside class={styles['side']}>
+        <a class={styles['skip']} href="#x-admin-main">
+          {t('admin.a11y.skip-to-content')}
+        </a>
 
-      <header class="x-admin-header">
-        <a class="x-admin-brand" href={props.app.basePath}>
+        <a class={styles['brand']} href={base}>
           {props.app.branding.logo === undefined ? null : (
             <img
               src={props.app.branding.logo.src}
@@ -42,19 +59,16 @@ export function AdminLayout(props: AdminLayoutProps): JSX.Element {
           )}
           <span>{t(props.app.branding.nameKey)}</span>
         </a>
+        <p class={styles['actor']}>{actorLabel(props.actor)}</p>
 
-        <search class="x-admin-search">
-          <form
-            onSubmit={(event: SubmitEvent) => {
-              event.preventDefault();
-              const field = (event.currentTarget as HTMLFormElement).elements.namedItem('term');
-              props.onSearch?.(field instanceof HTMLInputElement ? field.value : '');
-            }}
-          >
-            <label class="x-admin-visually-hidden" for="x-admin-search-input">
+        {/* A native GET at the search route: the term rides the URL, so a result page is a link
+            an operator can send and the form needs no handler. */}
+        <search class={styles['search']}>
+          <form method="get" action={`${base}/search`}>
+            <label class={styles['hidden']} for="x-admin-search-input">
               {t('admin.search.label')}
             </label>
-            <input
+            <Input
               id="x-admin-search-input"
               name="term"
               type="search"
@@ -63,27 +77,18 @@ export function AdminLayout(props: AdminLayoutProps): JSX.Element {
           </form>
         </search>
 
-        <div class="x-admin-header-tools">
-          {/* The locales with a catalog: an option nobody translated is a broken page. */}
-          <LocaleSwitcher locales={registeredLocales()} onLocaleChange={props.onLocaleChange} />
-          <ThemeToggle />
-        </div>
-      </header>
-
-      <div class="x-admin-body">
-        <nav class="x-admin-nav" aria-label={t('admin.nav.label')}>
+        <nav class={styles['group']} aria-label={t('admin.nav.label')}>
           {props.nav.map((group) => (
-            <section>
-              <h2>{t(group.labelKey)}</h2>
-              <ul>
+            <section class={styles['group']}>
+              <h2 class={styles['groupTitle']}>{t(group.labelKey)}</h2>
+              <ul class={styles['navList']}>
                 {group.items.map((item) => (
                   <li>
                     <a
-                      href={`${props.app.basePath}${item.href}`}
+                      class={styles['navLink']}
+                      href={`${base}${item.href}`}
                       aria-current={
-                        props.currentPath === `${props.app.basePath}${item.href}`
-                          ? 'page'
-                          : undefined
+                        props.currentPath === `${base}${item.href}` ? 'page' : undefined
                       }
                     >
                       {t(item.labelKey)}
@@ -95,10 +100,17 @@ export function AdminLayout(props: AdminLayoutProps): JSX.Element {
           ))}
         </nav>
 
-        <main id="x-admin-main" class="x-admin-main" tabindex={-1}>
-          {props.children}
-        </main>
-      </div>
+        {/* The way out. The admin's route table never points back at the app, so without this an
+            operator who opened the dashboard has no link home and edits the URL bar. */}
+        <a class={styles['navLink']} href="/">
+          {t('admin.backToApp')}
+        </a>
+      </aside>
+
+      <main id="x-admin-main" class={styles['main']} tabindex={-1}>
+        {props.title === undefined ? null : <h1 class={styles['title']}>{props.title}</h1>}
+        {props.children}
+      </main>
     </div>
   );
 }

package/src/list-columns.tsx

@@ -0,0 +1,53 @@
+// The columns a resource's table has, wherever it is drawn: its own list page, and the related
+// card on another resource's detail page. One definition — the link that opens the row, the
+// derived list fields, the computed columns — so a related list IS the resource's list and never
+// a second table somebody declared beside it.
+
+import { t } from '@ultimat3/i18n';
+import type { Column } from '@ultimat3/ui';
+import { type AdminRow, computedRow, rowId } from './registry';
+import { ComputedCell } from './renderers';
+import type { AdminResource } from './resource';
+import type { WidgetContext } from './widget-value';
+import { Widget } from './widgets';
+
+export interface ResourceColumnsInput {
+  readonly resource: AdminResource;
+  readonly ctx: WidgetContext;
+  /** The URL of one row's detail page. */
+  readonly hrefOf: (id: string) => string;
+  /** A list field to leave out — the foreign key a related card is already filtered by. */
+  readonly omit?: string;
+}
+
+export function resourceColumns(input: ResourceColumnsInput): readonly Column<AdminRow>[] {
+  const { resource, ctx } = input;
+  const idOf = (row: AdminRow): string => rowId(row, resource.idField);
+  const sealed = resource.secretFields.map((field) => field.name);
+  return [
+    // A real link, not a row click handler: the detail view has to survive a middle-click, a
+    // keyboard, and a crawler that never runs an onClick.
+    {
+      key: 'open',
+      header: t('admin.list.open'),
+      cell: (row) => <a href={input.hrefOf(idOf(row))}>{idOf(row)}</a>,
+    },
+    ...resource.listFields
+      .filter((field) => field.name !== input.omit)
+      .map((field) => ({
+        key: field.name,
+        header: t(field.labelKey),
+        sortable: field.sortable,
+        cell: (row: AdminRow) => (
+          <Widget field={field} value={row[field.name]} ctx={ctx} mode="read" />
+        ),
+      })),
+    ...resource.columns.map((column) => ({
+      key: column.name,
+      header: t(column.labelKey),
+      cell: (row: AdminRow) => (
+        <ComputedCell column={column} row={computedRow(row, sealed)} ctx={ctx} />
+      ),
+    })),
+  ];
+}

package/src/list-filter-bar.tsx

@@ -0,0 +1,207 @@
+// The filter bar: one control per derived filter, in one native GET form. Submitting it IS the
+// navigation — every input is named for the URL parameter it sets (`list-filters.ts`), an empty
+// one is no parameter, and the list's scope and sort ride along hidden. No script, no handler.
+
+import { t } from '@ultimat3/i18n';
+import { Button, Field, type FieldControl, Input, Link, Select } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+import styles from './admin.module.scss';
+import type { AdminField, AdminFilterKind } from './fields';
+import { filterParam } from './list-filters';
+import { SCOPE_PARAM, SORT_PARAM } from './list-request';
+import type { AdminListRequest } from './list-scope';
+import type { AdminFilter, FilterOp } from './registry';
+import type { AdminResource } from './resource';
+import type { WidgetContext } from './widget-value';
+import { optionLabel } from './widgets';
+
+export interface AdminFilterBarProps {
+  readonly resource: AdminResource;
+  /** The list as it was asked for: what each control is prefilled from. */
+  readonly request: AdminListRequest;
+  readonly ctx: WidgetContext;
+  /** The bare list URL — the form's `action`, and where Clear goes with the scope kept. */
+  readonly action: string;
+  readonly clearHref: string;
+  /** This page's own URL: where a lookup screen sends the operator back with the id chosen. */
+  readonly returnTo: string;
+}
+
+/** The operators a shape's CONTROLS write. Any other active filter rides the form hidden. */
+const CONTROL_OPS: Readonly<Record<AdminFilterKind, readonly FilterOp[]>> = {
+  text: ['contains'],
+  exact: ['eq'],
+  choice: ['eq'],
+  boolean: ['eq'],
+  range: ['gte', 'lte'],
+  reference: ['eq'],
+};
+
+/** Read through a Map: an unknown shape draws no control rather than a prototype member. */
+const CONTROLS: ReadonlyMap<string, readonly FilterOp[]> = new Map(Object.entries(CONTROL_OPS));
+
+const controlOps = (field: AdminField): readonly FilterOp[] =>
+  field.filterKind === undefined ? [] : (CONTROLS.get(field.filterKind) ?? []);
+
+const written = (value: AdminFilter['value'] | undefined): readonly string[] =>
+  value === undefined || value === null ? [] : typeof value === 'object' ? value : [String(value)];
+
+const wiring = (control: FieldControl): { id: string; 'aria-describedby': string | undefined } => ({
+  id: control.id,
+  'aria-describedby': control['aria-describedby'],
+});
+
+export function AdminFilterBar(props: AdminFilterBarProps): JSX.Element | null {
+  const { resource, request } = props;
+  if (resource.filters.length === 0) return null;
+  const active = request.filters ?? [];
+  const current = (field: AdminField, op: FilterOp): string =>
+    written(active.find((one) => one.field === field.name && one.op === op)?.value)[0] ?? '';
+
+  const any = { value: '', label: t('admin.filter.any') };
+
+  const control = (field: AdminField, own: FieldControl): JSX.Element => {
+    const name = filterParam(field, controlOps(field)[0] ?? 'eq');
+    const value = current(field, controlOps(field)[0] ?? 'eq');
+    switch (field.filterKind) {
+      case 'boolean':
+        return (
+          <Select
+            {...wiring(own)}
+            name={name}
+            value={value}
+            options={[
+              any,
+              { value: 'true', label: t('admin.value.true') },
+              { value: 'false', label: t('admin.value.false') },
+            ]}
+          />
+        );
+      case 'choice':
+        return field.values === undefined ? (
+          <Input {...wiring(own)} name={name} value={value} />
+        ) : (
+          <Select
+            {...wiring(own)}
+            name={name}
+            value={value}
+            // The entity's own values, labelled by the catalog where it has them: no option list
+            // is written in the app.
+            options={[
+              any,
+              ...field.values.map((one) => ({ value: one, label: optionLabel(field, one) })),
+            ]}
+          />
+        );
+      case 'range': {
+        const type =
+          field.type === 'date' ? 'date' : field.type === 'timestamptz' ? 'datetime-local' : 'text';
+        // `datetime-local` shows minutes; the stored filter is the ISO instant it was parsed to.
+        const shown = (op: FilterOp): string =>
+          field.type === 'timestamptz' ? current(field, op).slice(0, 16) : current(field, op);
+        return (
+          <span class={styles['range']}>
+            <Input
+              {...wiring(own)}
+              name={filterParam(field, 'gte')}
+              type={type}
+              inputmode={field.type === 'number' ? 'decimal' : undefined}
+              aria-label={t('admin.filter.from', { field: t(field.labelKey) })}
+              value={shown('gte')}
+            />
+            <Input
+              name={filterParam(field, 'lte')}
+              type={type}
+              inputmode={field.type === 'number' ? 'decimal' : undefined}
+              aria-label={t('admin.filter.to', { field: t(field.labelKey) })}
+              // An instant is typed in UTC and says so beside the box, as the edit form does.
+              suffix={field.type === 'timestamptz' ? 'UTC' : undefined}
+              value={shown('lte')}
+            />
+          </span>
+        );
+      }
+      case 'reference': {
+        const entity = field.relation?.entity ?? '';
+        const options = props.ctx.optionsFor?.(entity) ?? null;
+        if (options !== null) {
+          return (
+            <Select
+              {...wiring(own)}
+              name={name}
+              value={value}
+              options={[any, ...options.map((one) => ({ value: one.id, label: one.label }))]}
+            />
+          );
+        }
+        // Too many rows for a select: the id is typed, or found on the target's lookup screen,
+        // which links back here with this parameter set.
+        const lookup = props.ctx.lookupHref?.(entity) ?? null;
+        const find =
+          lookup === null
+            ? null
+            : `${lookup}?${new URLSearchParams({ return: props.returnTo, as: name }).toString()}`;
+        return (
+          <span class={styles['range']}>
+            <Input {...wiring(own)} name={name} value={value} />
+            {find === null ? null : <a href={find}>{t('admin.filter.find')}</a>}
+          </span>
+        );
+      }
+      default:
+        return (
+          <Input
+            {...wiring(own)}
+            name={name}
+            type={field.filterKind === 'text' ? 'search' : 'text'}
+            value={value}
+          />
+        );
+    }
+  };
+
+  // A filter the URL carries that no control above writes (`f.status.in`, `f.stock.gt`): kept, so
+  // submitting the form narrows the list the operator is looking at instead of widening it.
+  const carried = active.filter((one) => {
+    const field = resource.filters.find((known) => known.name === one.field);
+    return field !== undefined && !controlOps(field).includes(one.op);
+  });
+
+  return (
+    <search>
+      <form class={styles['filters']} method="get" action={props.action}>
+        {request.scope === undefined || request.scope === null ? null : (
+          <input type="hidden" name={SCOPE_PARAM} value={request.scope} />
+        )}
+        {request.sort === undefined ? null : (
+          <input
+            type="hidden"
+            name={SORT_PARAM}
+            value={`${request.sort.field}:${request.sort.direction}`}
+          />
+        )}
+        {carried.flatMap((one) => {
+          const field = resource.filters.find((known) => known.name === one.field);
+          return field === undefined
+            ? []
+            : written(one.value).map((value) => (
+                <input type="hidden" name={filterParam(field, one.op)} value={value} />
+              ));
+        })}
+        {resource.filters.map((field) => (
+          <Field label={t(field.labelKey)}>{(own) => control(field, own)}</Field>
+        ))}
+        <div class={styles['actions']}>
+          <Button type="submit" variant="secondary">
+            {t('admin.filter.apply')}
+          </Button>
+          {active.length === 0 ? null : (
+            <Link appearance="button" variant="ghost" tone="neutral" href={props.clearHref}>
+              {t('admin.filter.clear')}
+            </Link>
+          )}
+        </div>
+      </form>
+    </search>
+  );
+}