@ultimat3/admin 22.15.0 → 24.0.0

package/src/list-filters.ts

@@ -0,0 +1,242 @@
+// What a resource's filters ARE. Per filter shape: the operators a caller may name and the
+// control the filter bar draws. One validator — the URL parser, the MCP list tool and a `scopes:`
+// or `rows:` declaration all pass through it — so a predicate the admin sends a repo is one the
+// resource derived, on a column that is not sealed, with a value of the column's own type.
+
+import { adminColumnsOf, adminSealedColumnsOf } from './entity-columns';
+import { AdminFilterInvalidError } from './errors';
+import type { AdminField, AdminFilterKind } from './fields';
+import { type AdminFilter, FILTER_OPS, type FilterOp } from './registry';
+import type { AdminResource } from './resource';
+
+/** The URL prefix of a filter parameter: `f.<field>` or `f.<field>.<op>`. */
+export const FILTER_PREFIX = 'f.';
+
+/** Per shape, the operators it answers. The FIRST is what a bare `f.<field>=` means. */
+const OPS_BY_KIND: Readonly<Record<AdminFilterKind, readonly FilterOp[]>> = {
+  text: ['contains', 'eq', 'neq', 'is-null'],
+  exact: ['eq', 'neq', 'in', 'is-null'],
+  choice: ['eq', 'neq', 'in', 'is-null'],
+  boolean: ['eq'],
+  range: ['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'is-null'],
+  reference: ['eq', 'neq', 'in', 'is-null'],
+};
+
+/** The same table as a Map: a shape that is not one of the six has no operators, not a prototype's. */
+const OPS: ReadonlyMap<string, readonly FilterOp[]> = new Map(Object.entries(OPS_BY_KIND));
+
+/** The operators one field's filter answers; empty for a field with no filter shape. */
+export function filterOpsOf(field: AdminField): readonly FilterOp[] {
+  return field.filterKind === undefined ? [] : (OPS.get(field.filterKind) ?? []);
+}
+
+/** The parameter one filter is spelled as: the default operator is left off. */
+export function filterParam(field: AdminField, op: FilterOp): string {
+  return op === filterOpsOf(field)[0]
+    ? `${FILTER_PREFIX}${field.name}`
+    : `${FILTER_PREFIX}${field.name}.${op}`;
+}
+
+/** Every parameter spelling a resource answers — what a refusal names. */
+export function knownFilterParams(resource: AdminResource): readonly string[] {
+  return resource.filters.map((field) => `${FILTER_PREFIX}${field.name}`);
+}
+
+const isOp = (value: string): value is FilterOp =>
+  (FILTER_OPS as readonly string[]).includes(value);
+
+/** A value for a cause line: what was typed when it is text, its type when it is not. */
+const shown = (value: unknown): string =>
+  typeof value === 'string' ? `"${value}"` : `a ${value === null ? 'null' : typeof value}`;
+
+const TRUTH: ReadonlyMap<unknown, boolean> = new Map<unknown, boolean>([
+  ['true', true],
+  ['false', false],
+  [true, true],
+  [false, false],
+]);
+
+const DATE = /^\d{4}-\d{2}-\d{2}$/;
+const LOCAL_MINUTE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/;
+/** An instant names its offset. A bare local time has no zone, and the admin never invents one. */
+const ZONED = /(?:Z|[+-]\d{2}:\d{2})$/;
+
+/**
+ * A number as an operator types one: decimal digits, a sign, a point. `Number()` alone read a
+ * blank as `0`, `0x10` as 16 and `1e3` as 1000 — a filter nobody asked for, answered as a list.
+ */
+const DECIMAL = /^-?\d+(?:\.\d+)?$/;
+
+/**
+ * The `YYYY-MM-DD` a value opens with names a day the calendar HAS. `Date` rolls `2026-02-30`
+ * over to March 2nd without a word, so the shape test passed and the driver was handed a day
+ * nobody typed.
+ */
+const onCalendar = (raw: string): boolean => {
+  const match = /^(\d{4})-(\d{2})-(\d{2})/.exec(raw);
+  if (match === null) return false;
+  const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])];
+  if (month < 1 || month > 12 || day < 1) return false;
+  return day <= new Date(Date.UTC(year, month, 0)).getUTCDate();
+};
+
+/**
+ * A typed instant → the ISO string a driver compares. `datetime-local` posts `YYYY-MM-DDTHH:mm`
+ * and the control says UTC beside the box — the same contract the edit form states — and a bare
+ * date is that day's first instant in UTC.
+ */
+const instantOf = (raw: string): string | undefined => {
+  if (!onCalendar(raw)) return undefined;
+  const text = DATE.test(raw)
+    ? `${raw}T00:00:00.000Z`
+    : LOCAL_MINUTE.test(raw)
+      ? `${raw}:00.000Z`
+      : raw;
+  if (!ZONED.test(text)) return undefined;
+  const at = new Date(text);
+  return Number.isNaN(at.getTime()) ? undefined : at.toISOString();
+};
+
+interface Refusal {
+  readonly cause: string;
+}
+
+type Scalar = string | number | boolean;
+
+/** One value, as the column's own type — or why it is not one. */
+function scalarOf(field: AdminField, raw: unknown): Scalar | Refusal {
+  switch (field.filterKind) {
+    case 'boolean': {
+      const truth = TRUTH.get(raw);
+      return truth ?? { cause: `takes true or false, got ${shown(raw)}` };
+    }
+    case 'range': {
+      if (field.type === 'number') {
+        const parsed =
+          typeof raw === 'number'
+            ? raw
+            : typeof raw === 'string' && DECIMAL.test(raw)
+              ? Number(raw)
+              : NaN;
+        return Number.isFinite(parsed) ? parsed : { cause: `takes a number, got ${shown(raw)}` };
+      }
+      if (typeof raw !== 'string') return { cause: `takes a date as text, got ${shown(raw)}` };
+      if (field.type === 'date') {
+        return DATE.test(raw) && onCalendar(raw)
+          ? raw
+          : { cause: `takes a YYYY-MM-DD date, got ${shown(raw)}` };
+      }
+      return (
+        instantOf(raw) ?? {
+          cause: `takes a UTC instant (YYYY-MM-DDTHH:mm, or ISO-8601 with an offset), got ${shown(raw)}`,
+        }
+      );
+    }
+    case 'choice': {
+      if (typeof raw !== 'string') return { cause: `takes one of its values, got ${shown(raw)}` };
+      // An enum names its values; a locale or a zone column has no list to hold one against.
+      if (field.values !== undefined && !field.values.includes(raw)) {
+        return { cause: `takes one of ${field.values.join(', ')} — got ${shown(raw)}` };
+      }
+      return raw;
+    }
+    default:
+      if (typeof raw === 'string') return raw;
+      return typeof raw === 'number' && Number.isFinite(raw)
+        ? String(raw)
+        : { cause: `takes text, got ${shown(raw)}` };
+  }
+}
+
+const isRefusal = (value: unknown): value is Refusal =>
+  typeof value === 'object' && value !== null && 'cause' in value;
+
+const filterValueOf = (
+  field: AdminField,
+  op: FilterOp,
+  raw: unknown,
+): AdminFilter['value'] | Refusal => {
+  if (op === 'in') {
+    const list: readonly unknown[] = Array.isArray(raw) ? raw : [raw];
+    const out: string[] = [];
+    for (const one of list) {
+      const scalar = scalarOf(field, one);
+      if (isRefusal(scalar)) return scalar;
+      out.push(String(scalar));
+    }
+    return out;
+  }
+  // A scalar operator given a repeated parameter reads the LAST one, as a form field does.
+  const last: unknown = Array.isArray(raw) ? raw[raw.length - 1] : raw;
+  if (op === 'is-null') {
+    return TRUTH.get(last) ?? { cause: `takes true or false, got ${shown(last)}` };
+  }
+  return scalarOf(field, last);
+};
+
+export interface AskedFilter {
+  readonly field: string;
+  /** Absent is the field's default operator — `contains` for text, `eq` for everything else. */
+  readonly op?: string;
+  readonly value: unknown;
+}
+
+/**
+ * One filter a CALLER asked for — a URL parameter, an MCP argument — checked against what the
+ * resource derives. Refused by name: the field when it is not a filter, the operator when the
+ * field's shape has no meaning for it, the value when it is not the column's type.
+ */
+export function checkedFilter(resource: AdminResource, asked: AskedFilter): AdminFilter {
+  const spelled = `${FILTER_PREFIX}${asked.field}${asked.op === undefined ? '' : `.${asked.op}`}`;
+  const refuse = (cause: string, known: readonly string[]): never => {
+    throw new AdminFilterInvalidError({ entity: resource.name, asked: spelled, cause, known });
+  };
+  const field = resource.filters.find((known) => known.name === asked.field);
+  if (field === undefined) {
+    return refuse('is not a filter of this resource', knownFilterParams(resource));
+  }
+  const ops = filterOpsOf(field);
+  const op = asked.op ?? ops[0];
+  if (op === undefined || !isOp(op) || !ops.includes(op)) {
+    return refuse(
+      `names an operator "${field.name}" does not answer`,
+      ops.map((known) => filterParam(field, known)),
+    );
+  }
+  const value = filterValueOf(field, op, asked.value);
+  if (isRefusal(value)) return refuse(value.cause, [filterParam(field, op)]);
+  return { field: field.name, op, value };
+}
+
+/**
+ * Predicates the APP declared — a scope's `where`, a resource's `rows` — held to a narrower rule
+ * than a caller's: any column of the entity may be named (the app knows which of its columns are
+ * indexed), but never one that is not a column and never a sealed one, whose ciphertext no
+ * predicate can be written against.
+ */
+export function declaredFilters(
+  resource: Pick<AdminResource, 'name' | 'entity'>,
+  where: readonly AdminFilter[],
+  declaredAs: string,
+): readonly AdminFilter[] {
+  // Through the one flattener: it is the only reader of a column's declaration, and its two lists
+  // are exactly the two answers this needs — what may be named, and what is sealed.
+  const open = adminColumnsOf(resource.entity).map((column) => column.name);
+  const sealed = adminSealedColumnsOf(resource.entity).map((column) => column.name);
+  for (const filter of where) {
+    const refuse = (cause: string, known: readonly string[]): never => {
+      throw new AdminFilterInvalidError({
+        entity: resource.name,
+        asked: `${declaredAs}: ${filter.field} ${filter.op}`,
+        cause,
+        known,
+      });
+    };
+    if (sealed.includes(filter.field)) {
+      refuse('names a sealed column, which no predicate can read', open);
+    }
+    if (!open.includes(filter.field)) refuse('names a field that is not a column', open);
+    if (!isOp(filter.op)) refuse('names an operator the admin does not have', FILTER_OPS);
+  }
+  return where;
+}

package/src/list-request.ts

@@ -0,0 +1,129 @@
+// URL ⇄ the list a resource is asked for. A list page's whole state lives in its query string —
+// cursor, sort, scope and filters — so paging, sorting, scoping and filtering are links and one
+// GET form, and a list needs no script. One parser and one builder, so the two cannot disagree
+// about a parameter's name. A parameter the resource does not derive is refused, never ignored:
+// a typo that silently showed every row is how an operator acts on the wrong list.
+//
+//   ?cursor=<signed>            keyset position (pagination.ts)
+//   ?sort=<field>:<asc|desc>    a sortable field; the direction defaults to desc
+//   ?scope=<name>               a declared scope; absent is the resource's default, `*` is none
+//   ?f.<field>=<value>          a filter, by the field's default operator
+//   ?f.<field>.<op>=<value>     a filter, by a named operator; repeat the parameter for `in`
+//
+// An EMPTY value is no parameter at all: a GET form submits every input it holds.
+
+import { AdminFilterInvalidError } from './errors';
+import { checkedFilter, FILTER_PREFIX, filterParam, knownFilterParams } from './list-filters';
+import type { AdminListRequest } from './list-scope';
+import { scopeNamed } from './list-scope';
+import type { AdminFilter, AdminSort } from './registry';
+import type { AdminResource } from './resource';
+import { NO_SCOPE } from './resource-list';
+
+export const CURSOR_PARAM = 'cursor';
+export const SORT_PARAM = 'sort';
+export const SCOPE_PARAM = 'scope';
+
+const sortable = (resource: AdminResource): readonly string[] =>
+  resource.fields.filter((field) => field.sortable).map((field) => `${SORT_PARAM}=${field.name}`);
+
+/** `createdAt:desc`. A bare field sorts descending — the default everywhere. */
+const sortOf = (resource: AdminResource, raw: string): AdminSort => {
+  const at = raw.lastIndexOf(':');
+  const name = at < 0 ? raw : raw.slice(0, at);
+  const direction = at < 0 ? 'desc' : raw.slice(at + 1);
+  const refuse = (cause: string): never => {
+    throw new AdminFilterInvalidError({
+      entity: resource.name,
+      asked: `${SORT_PARAM}=${raw}`,
+      cause,
+      known: sortable(resource),
+    });
+  };
+  // A column the resource derives as sortable: an arbitrary name here would be an `order by` on a
+  // column with no index, chosen by whoever typed the URL.
+  const field = resource.fields.find((known) => known.name === name && known.sortable);
+  if (field === undefined) return refuse('names a field this resource cannot sort by');
+  if (direction !== 'asc' && direction !== 'desc') {
+    return refuse('names a direction that is neither asc nor desc');
+  }
+  return { field: field.name, direction };
+};
+
+/** `f.title.eq` → `{ field: 'title', op: 'eq' }`. A field name never holds a dot. */
+const filterKey = (key: string): { readonly field: string; readonly op?: string } => {
+  const rest = key.slice(FILTER_PREFIX.length);
+  const dot = rest.indexOf('.');
+  return dot < 0 ? { field: rest } : { field: rest.slice(0, dot), op: rest.slice(dot + 1) };
+};
+
+/** The list a URL asks for. Absent parameters are the resource's own defaults. */
+export function pageRequestOf(resource: AdminResource, url: URL): AdminListRequest {
+  const filters: AdminFilter[] = [];
+  let cursor: string | undefined;
+  let sort: AdminSort | undefined;
+  let scope: string | null | undefined;
+
+  for (const key of new Set(url.searchParams.keys())) {
+    const values = url.searchParams.getAll(key).filter((value) => value !== '');
+    const last = values[values.length - 1];
+    if (last === undefined) continue;
+    if (key === CURSOR_PARAM) cursor = last;
+    else if (key === SORT_PARAM) sort = sortOf(resource, last);
+    // Resolved here for its refusal alone: the name is what travels, the actor decides its rows.
+    else if (key === SCOPE_PARAM)
+      scope = last === NO_SCOPE ? null : scopeNamed(resource, last)?.name;
+    else if (key.startsWith(FILTER_PREFIX)) {
+      filters.push(checkedFilter(resource, { ...filterKey(key), value: values }));
+    } else {
+      throw new AdminFilterInvalidError({
+        entity: resource.name,
+        asked: key,
+        cause: 'is not a parameter a list reads',
+        known: [CURSOR_PARAM, SORT_PARAM, SCOPE_PARAM, ...knownFilterParams(resource)],
+      });
+    }
+  }
+
+  return {
+    ...(cursor === undefined ? {} : { cursor }),
+    ...(sort === undefined ? {} : { sort }),
+    ...(scope === undefined ? {} : { scope }),
+    ...(filters.length === 0 ? {} : { filters }),
+  };
+}
+
+export interface ListLocation {
+  readonly cursor?: string | null;
+  readonly sort?: AdminSort;
+  readonly scope?: string | null;
+  readonly filters?: readonly AdminFilter[];
+}
+
+const written = (value: AdminFilter['value']): readonly string[] =>
+  value === null ? [] : typeof value === 'object' ? value : [String(value)];
+
+/** The URL of one list state, rooted at the admin's own base path. */
+export function listHref(
+  basePath: string,
+  resource: Pick<AdminResource, 'path' | 'filters'>,
+  location: ListLocation = {},
+): string {
+  const query = new URLSearchParams();
+  // `null` is "no scope, not even the default" — the request's own meaning of it — so it is
+  // written, as `*`; only an absent scope is left to the resource's default.
+  if (location.scope !== undefined) query.set(SCOPE_PARAM, location.scope ?? NO_SCOPE);
+  for (const filter of location.filters ?? []) {
+    const field = resource.filters.find((known) => known.name === filter.field);
+    if (field === undefined) continue;
+    for (const value of written(filter.value)) query.append(filterParam(field, filter.op), value);
+  }
+  if (location.sort !== undefined) {
+    query.set(SORT_PARAM, `${location.sort.field}:${location.sort.direction}`);
+  }
+  if (location.cursor !== undefined && location.cursor !== null) {
+    query.set(CURSOR_PARAM, location.cursor);
+  }
+  const search = query.toString();
+  return `${basePath}${resource.path}${search === '' ? '' : `?${search}`}`;
+}

package/src/list-scope-tabs.tsx

@@ -0,0 +1,60 @@
+// Scope tabs, as links: each tab is the list's URL under that scope, with the filters and the
+// sort kept. A count is drawn only on the tabs that asked for one — the page read exactly those.
+
+import { t } from '@ultimat3/i18n';
+import { Badge } from '@ultimat3/ui';
+import type { JSX } from 'solid-js';
+import styles from './admin.module.scss';
+import type { AdminResource } from './resource';
+import type { AdminScope } from './resource-list';
+
+export interface AdminScopeTabsProps {
+  readonly resource: AdminResource;
+  /** The scope the page was read under, or `null` for the unscoped list. */
+  readonly active: AdminScope | null;
+  readonly counts: ReadonlyMap<string, number>;
+  /** The list's URL under a scope — `null` is the unscoped list. */
+  readonly hrefFor: (scope: string | null) => string;
+  readonly locale: string;
+}
+
+export function AdminScopeTabs(props: AdminScopeTabsProps): JSX.Element | null {
+  const scopes = props.resource.scopes;
+  if (scopes.length === 0) return null;
+
+  const tab = (name: string | null, label: string, current: boolean): JSX.Element => {
+    const count = name === null ? undefined : props.counts.get(name);
+    return (
+      <li>
+        <a
+          class={styles['navLink']}
+          href={props.hrefFor(name)}
+          aria-current={current ? 'page' : undefined}
+        >
+          {label}
+          {count === undefined ? null : (
+            <>
+              {' '}
+              <Badge size="sm">{new Intl.NumberFormat(props.locale).format(count)}</Badge>
+            </>
+          )}
+        </a>
+      </li>
+    );
+  };
+
+  return (
+    <nav aria-label={t('admin.scope.label')}>
+      <ul class={styles['scopes']}>
+        {/* With no default scope the bare list is every row, and it needs a tab to return to.
+            With one, "all rows" is a scope the app declares or does not offer. */}
+        {scopes.some((scope) => scope.default)
+          ? null
+          : tab(null, t('admin.scope.all'), props.active === null)}
+        {scopes.map((scope) =>
+          tab(scope.name, t(scope.labelKey), props.active?.name === scope.name),
+        )}
+      </ul>
+    </nav>
+  );
+}

package/src/list-scope.ts

@@ -0,0 +1,113 @@
+// The predicates one read of a resource carries, composed in one place: the resource's row scope
+// (who may see which rows at all), then the list's scope, then the caller's filters. Every read
+// the admin issues — list, search, detail, lookup, labels, the MCP tools — builds its `where`
+// here, so "this actor never sees that row" is one function and not five call sites agreeing.
+
+import type { AdminActor } from './authz';
+import { AdminFilterInvalidError } from './errors';
+import type { AdminFilter, AdminRow, AdminSort } from './registry';
+import { type AdminResource, repoOf } from './resource';
+import type { AdminScope } from './resource-list';
+
+/** One list, as a caller asks for it. `scope` and `filters` are names the resource must derive. */
+export interface AdminListRequest {
+  readonly cursor?: string | null;
+  readonly limit?: number;
+  readonly sort?: AdminSort;
+  /**
+   * A declared scope's name. Absent is the resource's default scope, or none. `null` is "no scope,
+   * not even the default" — what a lookup asks, because a label is owed for a row in ANY scope.
+   */
+  readonly scope?: string | null;
+  /** Already checked — `checkedFilter` is the only thing that builds one from a caller's input. */
+  readonly filters?: readonly AdminFilter[];
+}
+
+/** The rows of `resource` this actor may see at all — empty when the resource declares no `rows`. */
+export function rowWhere(resource: AdminResource, actor: AdminActor): readonly AdminFilter[] {
+  return resource.rowScope?.(actor) ?? [];
+}
+
+/**
+ * The scope a request names; the default one when it names none; `undefined` when the resource
+ * has no default. A name nobody declared is refused — a typo must not read as "every row".
+ */
+export function scopeNamed(
+  resource: AdminResource,
+  name: string | null | undefined,
+): AdminScope | undefined {
+  if (name === null) return undefined;
+  if (name === undefined || name === '') return resource.scopes.find((scope) => scope.default);
+  const found = resource.scopes.find((scope) => scope.name === name);
+  if (found !== undefined) return found;
+  throw new AdminFilterInvalidError({
+    entity: resource.name,
+    asked: `scope=${name}`,
+    cause: 'is not a scope of this resource',
+    known: resource.scopes.map((scope) => `scope=${scope.name}`),
+  });
+}
+
+export interface ListWhere {
+  readonly scope: AdminScope | undefined;
+  readonly where: readonly AdminFilter[];
+}
+
+/** Row scope, then scope, then filters — a conjunction, in the order they narrow. */
+export function listWhere(
+  resource: AdminResource,
+  actor: AdminActor,
+  request: Pick<AdminListRequest, 'scope' | 'filters'>,
+): ListWhere {
+  const scope = scopeNamed(resource, request.scope);
+  return {
+    scope,
+    where: [
+      ...rowWhere(resource, actor),
+      ...(scope?.where(actor) ?? []),
+      ...(request.filters ?? []),
+    ],
+  };
+}
+
+/**
+ * One row by id, or `null` — for a row that does not exist AND for one this actor's row scope
+ * leaves out, which are the same answer on purpose: a 404 that distinguished them would confirm
+ * the row exists.
+ *
+ * The membership question is put to the repo, never re-evaluated here: a second implementation of
+ * `contains` or `in` in this file would be a second opinion about what a predicate means. It costs
+ * one extra read, and only for a resource that declares `rows`.
+ */
+export async function findRow<Row extends AdminRow>(
+  resource: AdminResource<Row>,
+  actor: AdminActor,
+  id: string,
+): Promise<Row | null> {
+  const repo = repoOf(resource);
+  const row = await repo.find(id);
+  if (row === null || resource.rowScope === undefined) return row;
+  const visible = await repo.list({
+    where: [...resource.rowScope(actor), { field: resource.idField, op: 'eq', value: id }],
+    sort: resource.defaultSort,
+    limit: 1,
+  });
+  return visible.length === 0 ? null : row;
+}
+
+/**
+ * The count behind each tab that asked for one — `count: true` — and no other. One query per
+ * counted scope: the row scope and the scope's own predicates, never the caller's filters, so a
+ * tab's number is the size of the scope and does not move as the operator types.
+ */
+export async function scopeCounts(
+  resource: AdminResource,
+  actor: AdminActor,
+): Promise<ReadonlyMap<string, number>> {
+  const counted = resource.scopes.filter((scope) => scope.count);
+  const count = repoOf(resource).count;
+  if (counted.length === 0 || count === undefined) return new Map();
+  const rows = rowWhere(resource, actor);
+  const totals = await Promise.all(counted.map((scope) => count([...rows, ...scope.where(actor)])));
+  return new Map(counted.map((scope, index) => [scope.name, totals[index] ?? 0]));
+}