@ultimat3/admin 22.14.0 → 23.0.0

package/src/entity-columns.ts

@@ -81,15 +81,34 @@ const factsFor = (
   ...(references === undefined ? {} : { references }),
 });
 
+const factsOf = (entity: AdminEntity, sealed: boolean): readonly AdminColumnFacts[] => {
+  const references = referencesOf(entity);
+  const keys = new Set(entity.$primaryKey);
+  return Object.entries(entity.$columns)
+    .filter(([, column]) => (column.$meta.sealed !== undefined) === sealed)
+    .map(([name, column]) =>
+      factsFor(name, column.$meta, column.$meta.primaryKey || keys.has(name), references.get(name)),
+    );
+};
+
 /**
  * Declaration order, which is the order every list, form and MCP schema is built in. A
  * composite key marks each of its members, the way `$describe()` does — the admin then treats
  * them as it treats any key column: addressable, and never editable.
+ *
+ * A `.sealed()` column is NOT here. Every screen reads a row by column name — `row[field.name]`
+ * — and a repository row still answers a sealed property with its plaintext, so a derived field
+ * for one is the secret in the list, the detail, the search and the MCP schema. Leaving it out of
+ * this list is what makes "never shown" a property of the derivation rather than of each view.
  */
 export function adminColumnsOf(entity: AdminEntity): readonly AdminColumnFacts[] {
-  const references = referencesOf(entity);
-  const keys = new Set(entity.$primaryKey);
-  return Object.entries(entity.$columns).map(([name, column]) =>
-    factsFor(name, column.$meta, column.$meta.primaryKey || keys.has(name), references.get(name)),
-  );
+  return factsOf(entity, false);
+}
+
+/**
+ * The sealed columns, and only them: what a form may WRITE and nothing may read. Separate from
+ * `adminColumnsOf` so no caller can iterate one list and render both.
+ */
+export function adminSealedColumnsOf(entity: AdminEntity): readonly AdminColumnFacts[] {
+  return factsOf(entity, true);
 }

package/src/errors.ts

@@ -25,6 +25,10 @@ export const ADMIN_OWNED_ERROR_CODES = [
   // default label key, and `callAdminTool`'s lookup. Two actions sharing it is refused where the
   // admin is DECLARED, so an app that never wires MCP still cannot ship the ambiguity.
   'X_ADMIN_ACTION_DUPLICATE',
+  'X_ADMIN_REPO_UNBOUND',
+  'X_ADMIN_FILTER_INVALID',
+  'X_ADMIN_ACTION_NOT_APPLICABLE',
+  'X_ADMIN_MOUNT_MISSING',
 ] as const;
 
 /**
@@ -53,6 +57,11 @@ export const ADMIN_ERROR_TITLES: Readonly<Record<AdminOwnedErrorCode, string>> =
   X_ADMIN_PAGE_UNGUARDED: 'a custom admin page declared no permissions',
   X_ADMIN_PAGE_PATH_INVALID: 'a custom admin page has an unusable or already-taken path',
   X_ADMIN_ACTION_DUPLICATE: 'two admin actions share one name',
+  X_ADMIN_REPO_UNBOUND: 'an admin resource has no database handle to read rows through',
+  X_ADMIN_FILTER_INVALID:
+    'an admin list was asked for a filter, sort or scope its resource does not derive',
+  X_ADMIN_ACTION_NOT_APPLICABLE: 'an admin action was run on a row its when() rule excludes',
+  X_ADMIN_MOUNT_MISSING: 'an admin batch job ran in a process that never declared its admin',
 };
 
 // One unconditional call, so a second package claiming one of admin's codes throws
@@ -135,6 +144,80 @@ export class AdminPolicyMissingError extends UltimateError {
   }
 }
 
+/**
+ * A resource with nothing to read rows through. Refused where the admin is DECLARED: the routes
+ * of a repo-less resource would mount, render their chrome, and fail on the first row they ask for.
+ */
+export class AdminRepoUnboundError extends UltimateError {
+  constructor(input: { entity: string; handles: readonly string[] }) {
+    const carried = input.handles.length > 0 ? input.handles.join(', ') : 'none';
+    super({
+      code: 'X_ADMIN_REPO_UNBOUND',
+      cause: `the admin resource "${input.entity}" has no repo: defineAdmin() was given no db handle that carries it (tables in the handle: ${carried}) and no resources.${input.entity}.repo`,
+      fix: `pass the app's handle once: defineAdmin({ entities, db })   # with "${input.entity}" in the database() call that built db`,
+    });
+  }
+}
+
+/**
+ * A list was asked for something its resource does not derive: a filter on a field that is not
+ * one, an operator the field's shape has no meaning for, a value that is not the column's type, a
+ * sort on an unsortable column, a scope nobody declared. Raised for a URL, an MCP call and a
+ * `scopes:` / `rows:` declaration alike — an ignored parameter is a list that silently shows
+ * every row to someone who asked for some of them.
+ */
+export class AdminFilterInvalidError extends UltimateError {
+  constructor(input: {
+    entity: string;
+    /** What was asked for, as the caller spelled it: `f.colour`, `sort=body:asc`, `scope=mine`. */
+    asked: string;
+    cause: string;
+    /** What the resource DOES answer, in the caller's own spelling. */
+    known: readonly string[];
+  }) {
+    const known = input.known.length > 0 ? input.known.join(', ') : 'none';
+    super({
+      code: 'X_ADMIN_FILTER_INVALID',
+      cause: `${input.entity}: "${input.asked}" ${input.cause} (this list answers: ${known})`,
+      // The manifest records every resource's filters, sorts and scopes, so the command prints the
+      // list this error names — for the resource, and for every other one.
+      fix: `x manifest --json   # admin[].resources lists the filters, sorts and scopes of "${input.entity}"`,
+    });
+  }
+}
+
+/**
+ * An action was run on a row its `when()` excludes. The button was never rendered for that row —
+ * so this is a stale page (the row changed state since it was drawn) or a forged call — and the
+ * gate answers it rather than the handler: a hidden button is not an authorization.
+ */
+export class AdminActionNotApplicableError extends UltimateError {
+  constructor(input: { action: string; entity: string; id: string | null }) {
+    const row = input.id === null ? 'no row at all' : `the row "${input.id}"`;
+    super({
+      code: 'X_ADMIN_ACTION_NOT_APPLICABLE',
+      cause: `the admin action "${input.action}" does not apply to ${row} of "${input.entity}": its when() rule answered false for the row as it is now`,
+      fix: `x manifest --json   # admin[].resources lists "${input.action}" with when: true — re-read the row (the detail page, or the admin.${input.entity}.read tool) and run it only while that rule holds`,
+    });
+  }
+}
+
+/**
+ * A queued batch chunk was claimed by a process that declared no admin at the path the batch was
+ * queued from. The worker role imports the API index and not the document graph, so an admin
+ * declared only from a page module does not exist there — and neither do its actions.
+ */
+export class AdminMountMissingError extends UltimateError {
+  constructor(input: { basePath: string; mounted: readonly string[] }) {
+    const mounted = input.mounted.length > 0 ? input.mounted.join(', ') : 'none';
+    super({
+      code: 'X_ADMIN_MOUNT_MISSING',
+      cause: `an admin.batch job was claimed by a process with no admin declared at "${input.basePath}" (admins declared here: ${mounted}), so the action it names has no handler to run`,
+      fix: 'import the module that calls defineAdmin() from apps/web/api/index.ts, so the worker role loads it; then x verify --only manifest',
+    });
+  }
+}
+
 /**
  * A `pages:` entry with an empty permission list. Refused where it is written, because the
  * alternative is an unauthenticated admin screen that `x verify` is perfectly happy with — the

package/src/fields.ts

@@ -18,7 +18,9 @@ export type AdminFieldType =
   | 'locale'
   | 'json'
   | 'relation'
-  | 'file';
+  | 'file'
+  /** A `.sealed()` column: written through a form, read by nothing. Never derived from a kind. */
+  | 'secret';
 
 export type AdminWidget =
   | 'text-input'
@@ -32,7 +34,8 @@ export type AdminWidget =
   | 'locale-picker'
   | 'json-editor'
   | 'reference'
-  | 'upload';
+  | 'upload'
+  | 'secret-input';
 
 /**
  * A derived field: everything a list cell, a detail row, a form input, a filter, and an MCP
@@ -52,13 +55,34 @@ export interface AdminField {
   readonly sensitive: boolean;
   readonly inList: boolean;
   readonly filterable: boolean;
+  /**
+   * HOW the field filters, when a list offers it: which control the filter bar draws and which
+   * operators a URL may name (`list-filters.ts`). Absent for a type no predicate can be written
+   * against — money, JSON, a file, a sealed column — so such a field is never a filter.
+   */
+  readonly filterKind?: AdminFilterKind;
   readonly sortable: boolean;
   readonly searchable: boolean;
   readonly values?: readonly string[];
   readonly currency?: string;
-  readonly relation?: { readonly entity: string; readonly labelField?: string };
+  /** The resource a foreign key points at. Its label is THAT resource's `labelField`. */
+  readonly relation?: { readonly entity: string };
+  /** i18n key of the line under the form control. Declared, never derived. */
+  readonly hintKey?: string;
+  /**
+   * The one side of the form the field exists on: `create` is set once and never edited,
+   * `update` has no value until the row exists. Absent: both. Enforced on the write, not only
+   * on the form — `crud-input.ts` drops the field from the other side's input.
+   */
+  readonly on?: 'create' | 'update';
 }
 
+/**
+ * The six shapes a filter takes. A closed set: a control and an operator list hang off each in
+ * `list-filters.ts`, so a seventh shape cannot exist with one and not the other.
+ */
+export type AdminFilterKind = 'text' | 'exact' | 'choice' | 'boolean' | 'range' | 'reference';
+
 /** The table. Money always the Money widget; both date kinds always the DateTime widget. */
 export const WIDGET_BY_FIELD_TYPE: Readonly<Record<AdminFieldType, AdminWidget>> = {
   text: 'text-input',
@@ -74,6 +98,7 @@ export const WIDGET_BY_FIELD_TYPE: Readonly<Record<AdminFieldType, AdminWidget>>
   json: 'json-editor',
   relation: 'reference',
   file: 'upload',
+  secret: 'secret-input',
 };
 
 export function widgetFor(type: AdminFieldType): AdminWidget {
@@ -146,12 +171,46 @@ export function listable(type: AdminFieldType): boolean {
   return type !== 'json' && type !== 'file' && type !== 'textarea';
 }
 
-/** Only indexed, unique, enum, boolean, and FK columns are offered as filters. */
+/**
+ * Only indexed, unique, enum, boolean, and FK columns are offered as filters — and only when the
+ * type has a filter shape at all: an indexed money column is still two physical columns, and no
+ * single predicate names both.
+ */
 export function filterable(type: AdminFieldType, column: AdminColumnFacts): boolean {
+  if (filterKindFor(type, column) === undefined) return false;
   if (column.index || column.unique || column.primaryKey) return true;
   return type === 'enum' || type === 'boolean' || type === 'relation';
 }
 
+const FILTER_KIND_BY_FIELD_TYPE: Readonly<Partial<Record<AdminFieldType, AdminFilterKind>>> = {
+  boolean: 'boolean',
+  enum: 'choice',
+  timezone: 'choice',
+  locale: 'choice',
+  number: 'range',
+  date: 'range',
+  timestamptz: 'range',
+  relation: 'reference',
+};
+
+/**
+ * The shape a field filters in, or `undefined` for a type nothing can be compared against. A text
+ * box is `text` (a `contains`) only over a column `LIKE` runs against; a uuid, a `bigint` or a
+ * `numeric` renders in a text box too and takes an exact match instead — see
+ * `LIKE_ABLE_COLUMN_KINDS` below for what the other spelling costs.
+ */
+export function filterKindFor(
+  type: AdminFieldType,
+  column: AdminColumnFacts,
+): AdminFilterKind | undefined {
+  if (type === 'text' || type === 'textarea') {
+    return LIKE_ABLE_COLUMN_KINDS.has(column.kind) ? 'text' : 'exact';
+  }
+  return Object.hasOwn(FILTER_KIND_BY_FIELD_TYPE, type)
+    ? FILTER_KIND_BY_FIELD_TYPE[type]
+    : undefined;
+}
+
 /**
  * Sortable means "usable as the keyset cursor", so it is deliberately narrow: an ordered
  * scalar, or a text column with an index behind it. Sorting on an unindexed column would

package/src/form-decode.ts

@@ -0,0 +1,91 @@
+// A posted form → the typed input the entity's schema judges. A browser sends strings and omits
+// an unchecked box; the row holds a number, a boolean, a Date, a `{ minor, currency }`. This is
+// the one place that gap is closed, per WIDGET — the same table that rendered the control.
+//
+// It converts and never validates: a value that will not convert is passed through as the string
+// that was typed, so the schema refuses it in its own words against the field that carried it.
+
+import type { AdminField } from './fields';
+import type { AdminResource } from './resource';
+
+/** The posted name of a money field's currency, beside the minor-unit amount under the field's own. */
+export const currencyFieldOf = (field: string): string => `${field}.currency`;
+
+type Posted = Readonly<Record<string, unknown>>;
+
+/** The last value a posted name carried, as text. A repeated name arrives as a list. */
+export const posted = (form: Posted, name: string): string | undefined => {
+  if (!Object.hasOwn(form, name)) return undefined;
+  const value = form[name];
+  const last: unknown = Array.isArray(value) ? value[value.length - 1] : value;
+  return typeof last === 'string' ? last : undefined;
+};
+
+/** The widgets whose value is not text: an empty box of one is no value, never `''`. */
+const TYPED: ReadonlySet<AdminField['widget']> = new Set([
+  'money',
+  'number-input',
+  'datetime',
+  'json-editor',
+]);
+
+/**
+ * Empty is "no value" for a column that may hold none, and the empty string for a required TEXT
+ * one — so the schema refuses it in its own words. A typed widget has no empty string: `''` in a
+ * money field reached the widget on the 422 re-render and was refused as "money value is a
+ * string", a 500 where the form's own issue belonged.
+ */
+const blank = (field: AdminField): unknown =>
+  field.required && !TYPED.has(field.widget) ? '' : null;
+
+const numberOf = (raw: string): unknown => {
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) ? parsed : raw;
+};
+
+const jsonOf = (raw: string): unknown => {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    // Left as typed: the schema names the field, which a thrown SyntaxError would not.
+    return raw;
+  }
+};
+
+function decodeField(field: AdminField, form: Posted): unknown {
+  const raw = posted(form, field.name);
+  // An unchecked box posts nothing at all, so absence IS the answer for a checkbox.
+  if (field.widget === 'checkbox') return raw !== undefined && raw !== 'false';
+  if (raw === undefined || raw === '') return blank(field);
+  switch (field.widget) {
+    case 'number-input':
+      return numberOf(raw);
+    case 'money':
+      return {
+        minor: numberOf(raw),
+        currency: posted(form, currencyFieldOf(field.name)) ?? field.currency ?? '',
+      };
+    case 'datetime':
+      // `datetime-local` posts `YYYY-MM-DDTHH:mm` and the control says UTC beside the box; a
+      // calendar date stays the `YYYY-MM-DD` string its column holds.
+      return field.type === 'date' ? raw : new Date(`${raw.slice(0, 16)}:00.000Z`);
+    case 'json-editor':
+      return jsonOf(raw);
+    default:
+      return raw;
+  }
+}
+
+/**
+ * Every field the form rendered, decoded. A sealed column rides along as the string that was
+ * typed — `crud.ts` drops an empty one, which is what makes an untouched box mean "unchanged".
+ */
+export function decodeForm(
+  resource: AdminResource,
+  form: Posted,
+): Readonly<Record<string, unknown>> {
+  const out: Record<string, unknown> = {};
+  for (const field of resource.formFields) out[field.name] = decodeField(field, form);
+  for (const field of resource.secretFields) out[field.name] = posted(form, field.name) ?? '';
+  return out;
+}

package/src/form.tsx

@@ -1,13 +1,17 @@
-// Create/edit form. Fields, labels, and required flags come from the resource; validation
-// comes from the entity's own schema, so the form rejects exactly what the action would
-// reject. Issues render against the field they name, and the summary is focusable.
+// Create/edit form, as a native `<form method="post">`. Fields, labels, hints, groups and required
+// flags come from the resource; validation comes from the entity's own schema, so the form rejects
+// exactly what the action would reject. A refused submit re-renders this with the posted values and the
+// issues against the fields they name — there is no client state to lose.
 
 import { t } from '@ultimat3/i18n';
-import { Card, ErrorState, Field } from '@ultimat3/ui';
+import { Button, Card, ErrorState, Field, Link } from '@ultimat3/ui';
 import type { JSX } from 'solid-js';
+import styles from './admin.module.scss';
 import { type AdminErrorParts, adminErrorFrom } from './errors';
+import type { AdminField } from './fields';
 import type { AdminRow } from './registry';
 import type { AdminResource } from './resource';
+import { fieldsFor } from './resource-layout';
 import type { ValidationIssue } from './validate';
 import type { WidgetContext } from './widget-value';
 import { Widget } from './widgets';
@@ -15,20 +19,36 @@ import { Widget } from './widgets';
 export interface AdminFormProps<Row extends AdminRow> {
   readonly resource: AdminResource<Row>;
   readonly mode: 'create' | 'edit';
-  /** Current values, controlled by the route. Empty object for create. */
+  /** The stored row on a first render, the posted values on a refused one. Empty for create. */
   readonly values: Readonly<Record<string, unknown>>;
   readonly issues: readonly ValidationIssue[];
-  readonly submitting: boolean;
   readonly error: AdminErrorParts | null;
   readonly ctx: WidgetContext;
-  readonly onInput: (field: string, value: unknown) => void;
-  readonly onSubmit: () => void;
-  readonly onCancel: () => void;
+  /** Where the form posts: the URL that rendered it. */
+  readonly action: string;
+  /** Where Cancel goes — the list for a create, the row for an edit. */
+  readonly cancelHref: string;
 }
 
 const issuesFor = (issues: readonly ValidationIssue[], field: string): readonly ValidationIssue[] =>
   issues.filter((issue) => issue.path === field);
 
+/**
+ * The line under a control: the declared `hintKey`, and — for a sealed column on an edit — that an
+ * empty box keeps the stored value. Both, when both apply.
+ */
+const hintOf = (field: AdminField, unchanged: boolean): string | undefined => {
+  const lines = [
+    ...(field.hintKey === undefined ? [] : [t(field.hintKey)]),
+    ...(unchanged ? [t('admin.form.secret-unchanged')] : []),
+  ];
+  return lines.length === 0 ? undefined : lines.join(' ');
+};
+
+/** An issue the admin raised itself carries a key; the schema's own carry their message. */
+export const issueText = (issue: ValidationIssue): string =>
+  issue.messageKey === undefined ? issue.message : t(issue.messageKey);
+
 export function AdminForm<Row extends AdminRow>(props: AdminFormProps<Row>): JSX.Element {
   if (props.error !== null) {
     return <ErrorState error={adminErrorFrom(props.error)} />;
@@ -36,60 +56,73 @@ export function AdminForm<Row extends AdminRow>(props: AdminFormProps<Row>): JSX
 
   const titleKey = props.mode === 'create' ? 'admin.form.create' : 'admin.form.edit';
 
+  const input = (field: AdminField): JSX.Element => {
+    const secret = field.type === 'secret';
+    const own = issuesFor(props.issues, field.name);
+    return (
+      // The anchor target the issue summary links to. <Field> owns the control's own
+      // id, so the deep link lands on the wrapper and the label still points at the input.
+      <div id={`x-admin-field-${field.name}`}>
+        <Field
+          label={t(field.labelKey)}
+          // A sealed column is required to CREATE a row and optional ever after: an empty box on
+          // an edit means "leave it as it is", because nothing can prefill it.
+          required={secret ? field.required && props.mode === 'create' : field.required}
+          hint={hintOf(field, secret && props.mode === 'edit')}
+          error={own.length === 0 ? undefined : own.map(issueText).join(' ')}
+        >
+          {(control) => (
+            <Widget
+              field={field}
+              // A sealed column's widget takes no value by TYPE (`widget-value.ts`), so what a
+              // refused post typed into it is dropped there, once, for every caller.
+              value={props.values[field.name]}
+              ctx={props.ctx}
+              mode="edit"
+              control={control}
+            />
+          )}
+        </Field>
+      </div>
+    );
+  };
+
   return (
     <Card header={<h2>{t(titleKey, { entity: t(props.resource.titleKey) })}</h2>}>
-      <form
-        onSubmit={(event: SubmitEvent) => {
-          event.preventDefault();
-          props.onSubmit();
-        }}
-      >
+      <form class={styles['form']} method="post" action={props.action}>
         {props.issues.length === 0 ? null : (
           <div class="x-admin-issues" role="alert" tabindex={-1}>
             <h3>{t('admin.form.issues')}</h3>
             <ul>
               {props.issues.map((issue) => (
                 <li>
-                  <a href={`#x-admin-field-${issue.path}`}>{issue.path}</a>: {issue.message}
+                  <a href={`#x-admin-field-${issue.path}`}>{issue.path}</a>: {issueText(issue)}
                 </li>
               ))}
             </ul>
           </div>
         )}
 
-        {props.resource.formFields.map((field) => {
-          const own = issuesFor(props.issues, field.name);
-          return (
-            // The anchor target the issue summary links to. <Field> owns the control's own
-            // id, so the deep link lands on the wrapper and the label still points at the input.
-            <div id={`x-admin-field-${field.name}`}>
-              <Field
-                label={t(field.labelKey)}
-                required={field.required}
-                error={own.length === 0 ? undefined : own.map((issue) => issue.message).join(' ')}
-              >
-                {(control) => (
-                  <Widget
-                    field={field}
-                    value={props.values[field.name]}
-                    ctx={props.ctx}
-                    mode="edit"
-                    control={control}
-                    onInput={props.onInput}
-                  />
-                )}
-              </Field>
-            </div>
+        {props.resource.formGroups.map((group) => {
+          // A field that exists on the other side only (`on`) is not drawn, and a group left
+          // with nothing to draw is not drawn either.
+          const fields = fieldsFor(group.fields, props.mode);
+          if (fields.length === 0) return null;
+          return group.titleKey === null ? (
+            fields.map(input)
+          ) : (
+            <fieldset class={styles['section']}>
+              <legend>{t(group.titleKey)}</legend>
+              {fields.map(input)}
+            </fieldset>
           );
         })}
 
-        <div class="x-admin-form-actions">
-          <button type="submit" disabled={props.submitting}>
-            {t(props.submitting ? 'admin.form.saving' : 'admin.form.save')}
-          </button>
-          <button type="button" onClick={() => props.onCancel()}>
+        <div class={styles['actions']}>
+          <Button type="submit">{t('admin.form.save')}</Button>
+          <Link appearance="button" variant="ghost" tone="neutral" href={props.cancelHref}>
             {t('admin.form.cancel')}
-          </button>
+          </Link>
         </div>
       </form>
     </Card>