@ultimat3/admin 22.14.0 → 23.0.0

package/src/list-request.ts

@@ -0,0 +1,127 @@
+// 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
+//   ?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';
+
+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 | 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 = 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();
+  if (location.scope !== undefined && location.scope !== null) {
+    query.set(SCOPE_PARAM, location.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]));
+}

package/src/list.tsx

@@ -1,33 +1,46 @@
-// The list view: derived columns, keyset pagination, and the three states a table actually
-// has (loading, empty, error) instead of the one it usually ships with. Prev/Next are the
-// only navigation — there is no page number, because there is no offset.
+// The list view: scope tabs, the filter bar, the batch bar, derived and computed columns, keyset
+// pagination, and the states a server-rendered table has (rows, empty, error). Every control is a
+// link or a native form — a row opens through a real `<a href>`, a header sorts through one,
+// paging is `<Pagination hrefFor>`, a row is selected by a checkbox the batch form owns — so the
+// page ships no script and there is nothing to hydrate.
+// Prev/Next are the only navigation: there is no page number, because there is no offset.
 
 import { t } from '@ultimat3/i18n';
 import { Card, DataTable, ErrorState } from '@ultimat3/ui';
 import type { JSX } from 'solid-js';
+import { decideAction } from './action-gate';
 import { AdminActions } from './actions';
 import type { AdminActor, AdminAuthz } from './authz';
+import { AdminBatchBar, BatchCheckbox } from './batch-bar';
 import { type AdminErrorParts, adminErrorFrom } from './errors';
+import { resourceColumns } from './list-columns';
+import { AdminFilterBar } from './list-filter-bar';
+import type { ListLocation } from './list-request';
+import type { AdminListRequest } from './list-scope';
+import { AdminScopeTabs } from './list-scope-tabs';
 import type { AdminPage } from './pagination';
-import type { AdminRow, AdminSort } from './registry';
+import type { AdminRow } from './registry';
 import { rowId } from './registry';
 import type { AdminResource } from './resource';
+import type { AdminScope } from './resource-list';
 import type { WidgetContext } from './widget-value';
-import { Widget } from './widgets';
 
 export interface AdminListProps<Row extends AdminRow> {
   readonly resource: AdminResource<Row>;
-  readonly page: AdminPage<Row> | null;
-  readonly loading: boolean;
+  readonly page: AdminPage<Row>;
   readonly error: AdminErrorParts | null;
   readonly ctx: WidgetContext;
   readonly actor: AdminActor;
   readonly authz: AdminAuthz;
   readonly basePath: string;
-  readonly onCursor: (cursor: string | null) => void;
-  readonly onOpen: (id: string) => void;
-  /** Absent means the table renders its current order without sortable headers. */
-  readonly onSort?: (sort: AdminSort) => void;
+  /** The list as it was asked for — its scope, filters and sort ride every link on the page. */
+  readonly request: AdminListRequest;
+  /** The scope the page was READ under: the request's, or the resource's default. */
+  readonly scope: AdminScope | null;
+  /** The count of each scope that declared `count: true`, and of no other. */
+  readonly counts: ReadonlyMap<string, number>;
+  /** The URL of one list state — `listHref()`, bound to this admin and this resource. */
+  readonly hrefFor: (location: ListLocation) => string;
 }
 
 export function AdminList<Row extends AdminRow>(props: AdminListProps<Row>): JSX.Element {
@@ -38,83 +51,109 @@ export function AdminList<Row extends AdminRow>(props: AdminListProps<Row>): JSX
     return <ErrorState error={adminErrorFrom(props.error)} />;
   }
 
-  if (props.loading || props.page === null) {
-    return (
-      <Card header={<h2>{t(props.resource.titleKey)}</h2>}>
-        <p aria-busy="true">{t('admin.list.loading')}</p>
-      </Card>
-    );
-  }
-
   const page = props.page;
+  // The base `AdminResource`: this component's own `Row` is the app's, the pieces below read rows
+  // as `AdminRow`, and a resource is the same object either way.
+  const resource: AdminResource = props.resource as unknown as AdminResource;
+  const acts = resource.actions.length > 0;
+  const sealed = resource.secretFields.map((field) => field.name);
+  // The batch actions THIS actor may run — the gate's own answer, asked once for the list. A row
+  // the action's `when` excludes is still selectable: the server counts it `refused`, by name.
+  const batch = resource.actions.filter(
+    (action) =>
+      action.batch !== undefined &&
+      decideAction(action, props.actor, props.authz, { entity: resource.name }).allowed,
+  );
+  const { scope, filters, sort } = props.request;
+  /** Everything but the cursor: a cursor is a position IN this state, never part of it. */
+  const state: ListLocation = {
+    ...(scope === undefined ? {} : { scope }),
+    ...(filters === undefined ? {} : { filters }),
+    ...(sort === undefined ? {} : { sort }),
+  };
 
   return (
-    <Card header={<h2>{t(props.resource.titleKey)}</h2>}>
-      <AdminActions
-        actions={props.resource.actions}
-        actor={props.actor}
-        authz={props.authz}
-        subject={{ entity: props.resource.name }}
-        onRun={() => props.onCursor(null)}
+    <Card header={<h2>{t(resource.titleKey)}</h2>}>
+      <AdminScopeTabs
+        resource={resource}
+        active={props.scope}
+        counts={props.counts}
+        locale={props.ctx.locale}
+        hrefFor={(name) => props.hrefFor({ ...state, scope: name })}
       />
-
+      <AdminFilterBar
+        resource={resource}
+        request={props.request}
+        ctx={props.ctx}
+        action={props.hrefFor({})}
+        clearHref={props.hrefFor({
+          ...(scope === undefined ? {} : { scope }),
+          ...(sort === undefined ? {} : { sort }),
+        })}
+        returnTo={props.hrefFor(state)}
+      />
+      <AdminBatchBar actions={batch} href={props.hrefFor(state)} />
       {page.rows.length === 0 ? (
         <p class="x-admin-empty">{t('admin.list.empty')}</p>
       ) : (
         <DataTable
-          caption={t(props.resource.titleKey)}
+          caption={t(resource.titleKey)}
           columns={[
-            // 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 the onClick.
-            {
-              key: 'open',
-              header: t('admin.list.open'),
-              cell: (row: Row) => (
-                <a
-                  href={href(idOf(row))}
-                  onClick={(event) => {
-                    event.preventDefault();
-                    props.onOpen(idOf(row));
-                  }}
-                >
-                  {idOf(row)}
-                </a>
-              ),
-            },
-            ...props.resource.listFields.map((field) => ({
-              key: field.name,
-              header: t(field.labelKey),
-              sortable: field.sortable && props.onSort !== undefined,
-              cell: (row: Row) => (
-                <Widget field={field} value={row[field.name]} ctx={props.ctx} mode="read" />
-              ),
-            })),
+            ...(batch.length === 0
+              ? []
+              : [
+                  {
+                    key: 'select',
+                    header: t('admin.batch.select'),
+                    cell: (row: Row) => (
+                      <BatchCheckbox
+                        id={idOf(row)}
+                        label={t('admin.batch.select-row', { id: idOf(row) })}
+                      />
+                    ),
+                  },
+                ]),
+            // The resource's columns, the same ones a related card on another detail page draws.
+            ...resourceColumns({ resource, ctx: props.ctx, hrefOf: href }),
+            // Decided per ROW, with the row on the subject: a rule that reads it (ownership, a
+            // state) answers for this row and not for the table.
+            ...(acts
+              ? [
+                  {
+                    key: 'actions',
+                    header: t('admin.actions.label'),
+                    cell: (row: Row) => (
+                      <AdminActions
+                        actions={resource.actions}
+                        actor={props.actor}
+                        authz={props.authz}
+                        subject={{ entity: resource.name, id: idOf(row), row }}
+                        sealed={sealed}
+                        href={href(idOf(row))}
+                      />
+                    ),
+                  },
+                ]
+              : []),
           ]}
           rows={page.rows}
           rowKey={idOf}
           sort={{ key: page.sort.field, direction: page.sort.direction }}
-          onSortChange={(next) => {
-            if (next !== undefined) props.onSort?.({ field: next.key, direction: next.direction });
+          nextCursor={page.hasMore ? (page.nextCursor ?? undefined) : undefined}
+          prevCursor={page.prevCursor ?? undefined}
+          hrefFor={(cursor) => props.hrefFor({ ...state, cursor })}
+          // The header's NEXT state, as a URL. "Unsorted" is the list with no sort in it — the
+          // resource's own default order.
+          sortHrefFor={(next) => {
+            const { sort: _current, ...rest } = state;
+            return props.hrefFor(
+              next === undefined
+                ? rest
+                : { ...rest, sort: { field: next.key, direction: next.direction } },
+            );
           }}
         />
       )}
-
-      <nav class="x-admin-pager" aria-label={t('admin.list.pagination')}>
-        <button
-          type="button"
-          disabled={page.prevCursor === null}
-          onClick={() => props.onCursor(page.prevCursor)}
-        >
-          {t('admin.list.previous')}
-        </button>
-        <button
-          type="button"
-          disabled={!page.hasMore}
-          onClick={() => props.onCursor(page.nextCursor)}
-        >
-          {t('admin.list.next')}
-        </button>
-      </nav>
     </Card>
   );
 }