@ultimat3/admin 22.15.0 → 24.0.0

package/src/test-ctx.ts

@@ -0,0 +1,31 @@
+// A `CrudCtx` for a test: an actor, the grants it holds, and an audit log to read back. A custom
+// page's component is typed to need one (`AdminPageProps.ctx`), and until this existed the only
+// thing that minted one was the app's whole admin — so a generated page shipped with no render
+// test. Server-only, like everything in this barrel: never imported by an island.
+
+import { memoryAuditLog } from './audit';
+import { type AdminActor, staticAuthz } from './authz';
+import type { CrudCtx } from './crud';
+
+export interface AdminTestCtxInput {
+  /** Who is acting. Omitted: an actor with no role and no tenant. */
+  readonly actor?: AdminActor;
+  /** The permissions the actor holds. Omitted: none — every gate refuses, by name. */
+  readonly granted?: readonly string[];
+  readonly requestId?: string;
+}
+
+/**
+ * The handle a page or a CRUD call is given, built from a grant LIST. `staticAuthz` decides it, so
+ * the admin's own implications hold (`admin:write` reads) and nothing else does — a test says
+ * exactly what its actor may do, and a rule that reads the row or the tenant belongs in a test
+ * that builds the app's real authz.
+ */
+export function adminTestCtx(input: AdminTestCtxInput = {}): CrudCtx {
+  return {
+    actor: input.actor ?? { id: 'test-admin' },
+    authz: staticAuthz(input.granted ?? []),
+    audit: memoryAuditLog(),
+    requestId: input.requestId ?? 'test-admin-request',
+  };
+}

package/src/validate.ts

@@ -4,7 +4,10 @@
 
 export interface ValidationIssue {
   readonly path: string;
+  /** The schema's own words, or the literal an agent reads for an issue the admin raised. */
   readonly message: string;
+  /** Set only on an issue the ADMIN raised: the i18n key a screen renders instead of `message`. */
+  readonly messageKey?: string;
 }
 
 interface StandardResult {

package/src/widget-value.ts

@@ -7,6 +7,7 @@ import type { Money } from '@ultimat3/money';
 import { isCurrencyCode } from '@ultimat3/schema';
 import { AdminFieldUnsupportedError } from './errors';
 import type { AdminField } from './fields';
+import type { AdminOption } from './relations';
 
 export interface WidgetContext {
   /** IANA zone. Required — there is no "server local time" in Ultimate. */
@@ -25,6 +26,15 @@ export interface WidgetContext {
    * caller that builds this context can. A wrong link is worse than no link.
    */
   readonly hrefFor?: (entity: string, id: string) => string | null;
+  /**
+   * The three things a reference widget shows that only the PAGE can know, because each is a read
+   * of another resource: a referenced row's label, a small target's whole option list, and where
+   * the target's lookup lives. Absent, a reference renders its id and edits as a text box — the
+   * widget never reads a row itself, so a cell cannot become a query.
+   */
+  readonly labelFor?: (entity: string, id: string) => string | undefined;
+  readonly optionsFor?: (entity: string) => readonly AdminOption[] | null;
+  readonly lookupHref?: (entity: string) => string | null;
 }
 
 export interface SelectOption {
@@ -60,15 +70,25 @@ export type WidgetProps =
       readonly field: string;
       readonly value: string | null;
       readonly entity: string;
-      readonly labelField: string;
+      /** The target row's label, when the page read it. `null` renders the id itself. */
+      readonly label: string | null;
+      /** Every row of a small target — a `<select>`. `null`: the picker is the lookup screen. */
+      readonly options: readonly AdminOption[] | null;
+      /** Where an operator finds a row of the target, or `null` when it is not an admin resource. */
+      readonly lookupHref: string | null;
     }
   | {
       readonly widget: 'upload';
       readonly field: string;
       readonly value: { readonly url: string; readonly name: string } | null;
-    };
+    }
+  /** No `value`, by type: a sealed column is written, never rendered and never prefilled. */
+  | { readonly widget: 'secret-input'; readonly field: string };
 
-const fail = (field: AdminField, cause: string, fix: string): never => {
+/** What a value guard names in its refusal — a field, or a computed column standing in for one. */
+export type GuardedField = Pick<AdminField, 'entity' | 'name'> & { readonly currency?: string };
+
+const fail = (field: GuardedField, cause: string, fix: string): never => {
   throw new AdminFieldUnsupportedError({ entity: field.entity, field: field.name, cause, fix });
 };
 
@@ -86,7 +106,7 @@ const minorUnits = (value: unknown): number | null => {
 };
 
 /** `Money = { minor: number; currency: string }` or nothing. A float is a bug, not a value. */
-export function assertMoney(field: AdminField, value: unknown): Money | null {
+export function assertMoney(field: GuardedField, value: unknown): Money | null {
   if (value === null || value === undefined) return null;
   if (typeof value === 'number') {
     return fail(
@@ -207,16 +227,24 @@ export function widgetProps(field: AdminField, value: unknown, ctx: WidgetContex
         field: field.name,
         value: value === undefined ? '' : JSON.stringify(value, null, 2),
       };
-    case 'reference':
+    case 'reference': {
+      const entity = field.relation?.entity ?? field.name;
+      const id = value === null || value === undefined || value === '' ? null : String(value);
       return {
         widget: 'reference',
         field: field.name,
-        value: value === null || value === undefined ? null : String(value),
-        entity: field.relation?.entity ?? field.name,
-        labelField: field.relation?.labelField ?? 'id',
+        value: id,
+        entity,
+        label: id === null ? null : (ctx.labelFor?.(entity, id) ?? null),
+        options: ctx.optionsFor?.(entity) ?? null,
+        lookupHref: ctx.lookupHref?.(entity) ?? null,
       };
+    }
     case 'upload':
       return { widget: 'upload', field: field.name, value: uploadValue(field, value) };
+    case 'secret-input':
+      // The row value is not read at all — not even to test it for null.
+      return { widget: 'secret-input', field: field.name };
   }
 }
 

package/src/widgets.tsx

@@ -3,8 +3,9 @@
 // every one of those places — there is no second place to get it wrong.
 
 import { safeUrl } from '@ultimat3/core';
-import { registeredLocales, t } from '@ultimat3/i18n';
+import { isMiss, registeredLocales, t } from '@ultimat3/i18n';
 import {
+  Badge,
   Checkbox,
   DateTime,
   type DateTimeFormatter,
@@ -16,6 +17,7 @@ import {
 } from '@ultimat3/ui';
 import type { JSX } from 'solid-js';
 import type { AdminField } from './fields';
+import { currencyFieldOf, datetimeInputValue } from './form-decode';
 import { type WidgetContext, type WidgetProps, widgetProps } from './widget-value';
 
 export interface WidgetInput {
@@ -68,9 +70,16 @@ export const formatCalendarDate: DateTimeFormatter = (at, options) =>
     dateStyle: 'medium',
   }).format(at);
 
-/** `<input type="date">` wants `YYYY-MM-DD`; `datetime-local` wants `YYYY-MM-DDTHH:mm`. */
-const inputValueFor = (iso: string, precision: 'date' | 'instant'): string =>
-  iso.slice(0, precision === 'date' ? 10 : 16);
+/**
+ * An enum value's label: its translation when the catalog has one, the value itself when it does
+ * not. The value is an identifier the ENTITY declares (`public`, `draft`), so showing it is true;
+ * a `⟦admin.posts.field.audience.option.public⟧` in every cell of a derived list is not, and the
+ * key is built at runtime, so no i18n gate could have asked the app for it.
+ */
+export const optionLabel = (field: AdminField, value: string): string => {
+  const label = t(`${field.labelKey}.option.${value}`);
+  return isMiss(label) ? value : label;
+};
 
 /** Read-mode rendering of already-guarded props. Never formats; the widgets do that. */
 function readView(props: WidgetProps, field: AdminField, ctx: WidgetContext): JSX.Element {
@@ -79,7 +88,9 @@ function readView(props: WidgetProps, field: AdminField, ctx: WidgetContext): JS
       return props.value === null ? (
         <span>{t('admin.value.empty')}</span>
       ) : (
-        <Money value={props.value} />
+        // The ACTOR's locale, handed over: ui's own default is the document's, and an operator
+        // whose dashboard is otherwise in their language read every amount and date in another.
+        <Money value={props.value} locale={ctx.locale} />
       );
     case 'datetime':
       return props.value === null ? (
@@ -87,6 +98,7 @@ function readView(props: WidgetProps, field: AdminField, ctx: WidgetContext): JS
       ) : (
         <DateTime
           value={props.value}
+          locale={ctx.locale}
           timeZone={props.timeZone}
           format={props.precision === 'date' ? formatCalendarDate : undefined}
         />
@@ -94,21 +106,25 @@ function readView(props: WidgetProps, field: AdminField, ctx: WidgetContext): JS
     case 'checkbox':
       return <span>{t(props.value ? 'admin.value.true' : 'admin.value.false')}</span>;
     case 'select':
-      return (
-        <span>
-          {props.value === null
-            ? t('admin.value.empty')
-            : t(`${field.labelKey}.option.${props.value}`)}
-        </span>
+      // A value from a closed set is a state, and a state reads as a badge. Only an enum: a
+      // locale or a zone is an identifier, and stays text.
+      if (props.value === null) return <span>{t('admin.value.empty')}</span>;
+      return field.type === 'enum' ? (
+        <Badge>{optionLabel(field, props.value)}</Badge>
+      ) : (
+        <span>{optionLabel(field, props.value)}</span>
       );
     case 'json-editor':
       return <pre class="x-admin-json">{props.value}</pre>;
     case 'reference': {
       if (props.value === null) return <span>{t('admin.value.empty')}</span>;
+      // The target's label when the page read it, the id when it did not — a row this actor may
+      // not see keeps its id and gains no name.
+      const shown = props.label ?? props.value;
       // `ctx.hrefFor` or nothing. The route table lives on `AdminApp`; this file only ever knew
       // the target entity's NAME, and turning that into a URL by appending an `s` is a guess.
       const href = ctx.hrefFor?.(props.entity, props.value) ?? null;
-      return href === null ? <span>{props.value}</span> : <a href={href}>{props.value}</a>;
+      return href === null ? <span>{shown}</span> : <a href={href}>{shown}</a>;
     }
     case 'upload':
       return props.value === null ? (
@@ -116,6 +132,9 @@ function readView(props: WidgetProps, field: AdminField, ctx: WidgetContext): JS
       ) : (
         <a href={safeUrl(props.value.url, 'href') ?? undefined}>{props.value.name}</a>
       );
+    case 'secret-input':
+      // Nothing to show, by type: `WidgetProps` carries no value for a sealed column.
+      return <span>{t('admin.value.sealed')}</span>;
     default:
       return <span>{String(props.value ?? '')}</span>;
   }
@@ -155,7 +174,9 @@ function editView(props: WidgetProps, input: WidgetInput): JSX.Element {
       // Minor units, not a decimal: turning "12,34" into cents is currency- and locale-aware
       // work owned by @ultimat3/money, and the design system has no money input to host it.
       const currency = props.value?.currency ?? input.field.currency ?? '';
-      return (
+      // The other half of the value, posted beside the amount: a known currency rides hidden, an
+      // unknown one is asked for — money is always both.
+      return [
         <Input
           {...shared}
           name={props.field}
@@ -167,8 +188,18 @@ function editView(props: WidgetProps, input: WidgetInput): JSX.Element {
             const next = event.currentTarget.value;
             emit(input, next === '' ? null : { minor: Number(next), currency });
           }}
-        />
-      );
+        />,
+        currency === '' ? (
+          <Input
+            name={currencyFieldOf(props.field)}
+            maxlength={3}
+            placeholder={t('admin.value.currency')}
+            disabled={disabled}
+          />
+        ) : (
+          <input type="hidden" name={currencyFieldOf(props.field)} value={currency} />
+        ),
+      ];
     }
     case 'checkbox':
       return (
@@ -203,7 +234,7 @@ function editView(props: WidgetProps, input: WidgetInput): JSX.Element {
           {...shared}
           name={props.field}
           type={props.precision === 'date' ? 'date' : 'datetime-local'}
-          value={props.value === null ? '' : inputValueFor(props.value, props.precision)}
+          value={props.value === null ? '' : datetimeInputValue(props.value, props.precision)}
           suffix={props.precision === 'date' ? undefined : 'UTC'}
           disabled={disabled}
           onInput={(event) => emit(input, event.currentTarget.value)}
@@ -242,6 +273,43 @@ function editView(props: WidgetProps, input: WidgetInput): JSX.Element {
           onInput={(event) => emit(input, event.currentTarget.value)}
         />
       );
+    case 'reference':
+      // A small target is a `<select>` of its rows, by label. A large one is the id in a text
+      // box, with its label and the target's lookup beside it — both work with scripting off.
+      if (props.options !== null) {
+        return (
+          <Select
+            {...shared}
+            name={props.field}
+            value={props.value ?? ''}
+            disabled={disabled}
+            options={[
+              { value: '', label: t('admin.value.empty') },
+              ...props.options.map((option) => ({ value: option.id, label: option.label })),
+            ]}
+            onChange={(event) => emit(input, event.currentTarget.value)}
+          />
+        );
+      }
+      return [
+        <Input
+          {...shared}
+          name={props.field}
+          value={props.value ?? ''}
+          disabled={disabled}
+          suffix={props.label ?? undefined}
+          onInput={(event) => emit(input, event.currentTarget.value)}
+        />,
+        props.lookupHref === null ? null : (
+          <a href={props.lookupHref} target="_blank" rel="noopener">
+            {t('admin.filter.find')}
+          </a>
+        ),
+      ];
+    case 'secret-input':
+      // Write-only: never a `value`, and `new-password` so a browser offers no saved credential
+      // of the operator's own. Empty on an edit means "unchanged" (`form-decode.ts`).
+      return <Input {...shared} name={props.field} type="password" autocomplete="new-password" />;
     default:
       return (
         <Input