@ultimat3/admin 1.0.0

package/src/search.ts

@@ -0,0 +1,108 @@
+// Cross-entity search, derived: every resource's text fields are the index. No separate
+// search config to drift from the entities, and no result an actor could not have opened —
+// the same `admin:read` + `<entity>:read` pair gates the hit and the detail page it links to.
+
+import type { CrudCtx } from './crud';
+import { canOperate } from './crud';
+import type { AdminFilter, AdminRow } from './registry';
+import { rowId } from './registry';
+import { type AdminResource, repoOf } from './resource';
+
+/** Per resource, and per field within it. Search is a jump box, not a report. */
+const MAX_FIELDS_PER_RESOURCE = 3;
+const DEFAULT_LIMIT_PER_RESOURCE = 5;
+
+export interface AdminSearchHit {
+  readonly entity: string;
+  readonly id: string;
+  /** The row's label-field value. Already a string; the view does not format it. */
+  readonly label: string;
+  readonly matchedField: string;
+  /** Mount-relative link to the detail page. */
+  readonly href: string;
+}
+
+export interface AdminSearchResult {
+  readonly term: string;
+  readonly hits: readonly AdminSearchHit[];
+  readonly searched: readonly string[];
+  /** Resources left out, and why — so an operator is never silently shown a subset. */
+  readonly skipped: readonly { readonly entity: string; readonly reason: string }[];
+}
+
+export interface AdminSearchInput {
+  readonly term: string;
+  readonly resources: readonly AdminResource[];
+  readonly ctx: CrudCtx;
+  readonly limitPerResource?: number;
+}
+
+/**
+ * One query per searchable field rather than one query with an OR: the admin's query IR is
+ * a conjunction by design (each filter maps to an indexed predicate), and three small
+ * indexed lookups beat one unindexed disjunction.
+ */
+async function searchResource(
+  resource: AdminResource,
+  term: string,
+  limit: number,
+): Promise<readonly AdminSearchHit[]> {
+  const repo = repoOf(resource);
+  const fields = resource.searchFields.slice(0, MAX_FIELDS_PER_RESOURCE);
+  const seen = new Set<string>();
+  const hits: AdminSearchHit[] = [];
+
+  for (const field of fields) {
+    const where: readonly AdminFilter[] = [{ field: field.name, op: 'contains', value: term }];
+    const rows = await repo.list({ where, sort: resource.defaultSort, limit });
+    for (const row of rows) {
+      const id = rowId(row, resource.idField);
+      if (id === '' || seen.has(id)) continue;
+      seen.add(id);
+      hits.push({
+        entity: resource.name,
+        id,
+        label: labelOf(row, resource),
+        matchedField: field.name,
+        href: `${resource.path}/${id}`,
+      });
+      if (hits.length >= limit) return hits;
+    }
+  }
+  return hits;
+}
+
+function labelOf(row: AdminRow, resource: AdminResource): string {
+  const value = row[resource.labelField];
+  if (typeof value === 'string' && value !== '') return value;
+  return rowId(row, resource.idField);
+}
+
+export async function adminSearch(input: AdminSearchInput): Promise<AdminSearchResult> {
+  const term = input.term.trim();
+  const limit = input.limitPerResource ?? DEFAULT_LIMIT_PER_RESOURCE;
+  const searched: string[] = [];
+  const skipped: { entity: string; reason: string }[] = [];
+  const hits: AdminSearchHit[] = [];
+
+  if (term === '') return { term, hits: [], searched: [], skipped: [] };
+
+  for (const resource of input.resources) {
+    if (!canOperate(resource, 'search', input.ctx)) {
+      skipped.push({ entity: resource.name, reason: 'admin.search.skipped.forbidden' });
+      continue;
+    }
+    if (resource.searchFields.length === 0) {
+      skipped.push({ entity: resource.name, reason: 'admin.search.skipped.no-text-fields' });
+      continue;
+    }
+    if (resource.repo === undefined) {
+      skipped.push({ entity: resource.name, reason: 'admin.search.skipped.no-repo' });
+      continue;
+    }
+    searched.push(resource.name);
+    hits.push(...(await searchResource(resource, term, limit)));
+  }
+
+  return { term, hits, searched, skipped };
+}

package/src/theme.ts

@@ -0,0 +1,59 @@
+// Admin branding through the token system only. `ThemeTokenRef` is a template-literal type,
+// so `accent: '#7c3aed'` is a compile error rather than a code-review comment: branding
+// aliases one design token to another, and every colour still resolves in @ultimat3/ui's
+// light and dark scales.
+
+/** Any framework design token. Raw hex, `rgb()`, and colour names cannot satisfy this. */
+export type ThemeTokenRef = `--x-${string}`;
+
+export type ThemeMode = 'system' | 'light' | 'dark';
+
+export interface AdminBranding {
+  /** i18n key for the product name in the header and the document title. */
+  readonly nameKey: string;
+  readonly logo?: { readonly src: string; readonly altKey: string; readonly width?: number };
+  /** Alias for `--x-color-accent`, e.g. `--x-color-brand`. */
+  readonly accent?: ThemeTokenRef;
+  /** Extra token aliases: `{ '--x-color-surface': '--x-color-brand-surface' }`. */
+  readonly tokens?: Readonly<Partial<Record<ThemeTokenRef, ThemeTokenRef>>>;
+  /** `system` follows `prefers-color-scheme`; the others pin `data-theme`. */
+  readonly mode?: ThemeMode;
+  readonly density?: 'comfortable' | 'compact';
+}
+
+export const defaultBranding: AdminBranding = {
+  nameKey: 'admin.brand.name',
+  mode: 'system',
+  density: 'comfortable',
+};
+
+export function adminBranding(input: Partial<AdminBranding> = {}): AdminBranding {
+  return { ...defaultBranding, ...input };
+}
+
+export interface ThemeAttributes {
+  /** Absent under `system` so the media query decides; present otherwise, and it wins. */
+  readonly 'data-theme'?: 'light' | 'dark';
+  readonly 'data-density': 'comfortable' | 'compact';
+  /** Inline custom-property declarations: token → token, never token → literal. */
+  readonly style: string;
+}
+
+/**
+ * The attributes the admin shell puts on its root element. Written as data attributes plus
+ * custom properties so a theme flip re-paints without re-rendering a single component.
+ */
+export function themeAttributes(branding: AdminBranding): ThemeAttributes {
+  const aliases: [ThemeTokenRef, ThemeTokenRef][] = [];
+  if (branding.accent !== undefined) aliases.push(['--x-color-accent', branding.accent]);
+  for (const [target, source] of Object.entries(branding.tokens ?? {})) {
+    if (source !== undefined) aliases.push([target as ThemeTokenRef, source]);
+  }
+
+  const mode = branding.mode ?? 'system';
+  return {
+    ...(mode === 'system' ? {} : { 'data-theme': mode }),
+    'data-density': branding.density ?? 'comfortable',
+    style: aliases.map(([target, source]) => `${target}: var(${source});`).join(' '),
+  };
+}

package/src/validate.ts

@@ -0,0 +1,65 @@
+// Form input → the entity's own schema. The admin never writes a second set of rules: it
+// calls the Standard Schema the entity already validates with, so a value the admin accepts
+// is a value the action would accept.
+
+export interface ValidationIssue {
+  readonly path: string;
+  readonly message: string;
+}
+
+interface StandardResult {
+  readonly value?: unknown;
+  readonly issues?: readonly {
+    readonly message: string;
+    readonly path?: readonly (string | number | { readonly key: string | number })[];
+  }[];
+}
+
+interface StandardSchema {
+  readonly '~standard': {
+    validate(value: unknown): StandardResult | Promise<StandardResult>;
+  };
+}
+
+const isStandardSchema = (schema: unknown): schema is StandardSchema =>
+  typeof schema === 'object' &&
+  schema !== null &&
+  '~standard' in schema &&
+  typeof (schema as StandardSchema)['~standard']?.validate === 'function';
+
+const pathOf = (
+  path: readonly (string | number | { readonly key: string | number })[] | undefined,
+): string =>
+  (path ?? [])
+    .map((part) => (typeof part === 'object' ? String(part.key) : String(part)))
+    .join('.');
+
+export type ValidationResult =
+  | { readonly ok: true; readonly value: Readonly<Record<string, unknown>> }
+  | { readonly ok: false; readonly issues: readonly ValidationIssue[] };
+
+/**
+ * An entity with no schema is accepted as-is: `x verify` fails on an entity without one, so
+ * a missing schema here means a hand-written test fixture, not a production hole.
+ */
+export async function validateInput(
+  schema: unknown,
+  input: Readonly<Record<string, unknown>>,
+): Promise<ValidationResult> {
+  if (!isStandardSchema(schema)) return { ok: true, value: input };
+
+  const result = await schema['~standard'].validate(input);
+  if (result.issues !== undefined && result.issues.length > 0) {
+    return {
+      ok: false,
+      issues: result.issues.map((issue) => ({
+        path: pathOf(issue.path),
+        message: issue.message,
+      })),
+    };
+  }
+  const value = result.value;
+  return typeof value === 'object' && value !== null
+    ? { ok: true, value: value as Readonly<Record<string, unknown>> }
+    : { ok: true, value: input };
+}

package/src/widget-value.ts

@@ -0,0 +1,217 @@
+// Row value → widget props. This is where the two money/time axioms are actually enforced:
+// a money value that arrived as a float and a timestamp with no IANA zone both fail here,
+// loudly, instead of rendering a number that is wrong for somebody. Views render the props
+// this returns and make no decisions of their own.
+
+import type { Money } from '@ultimat3/money';
+import { AdminFieldUnsupportedError } from './errors';
+import type { AdminField } from './fields';
+
+export interface WidgetContext {
+  /** IANA zone. Required — there is no "server local time" in Ultimate. */
+  readonly timeZone: string;
+  /** BCP-47, for the number/date/money formatters the widgets call. */
+  readonly locale: string;
+}
+
+export interface SelectOption {
+  readonly value: string;
+  readonly labelKey: string;
+}
+
+export type WidgetProps =
+  | { readonly widget: 'text-input'; readonly field: string; readonly value: string }
+  | { readonly widget: 'textarea'; readonly field: string; readonly value: string }
+  | { readonly widget: 'number-input'; readonly field: string; readonly value: number | null }
+  | { readonly widget: 'money'; readonly field: string; readonly value: Money | null }
+  | { readonly widget: 'checkbox'; readonly field: string; readonly value: boolean }
+  | {
+      readonly widget: 'select';
+      readonly field: string;
+      readonly value: string | null;
+      readonly options: readonly SelectOption[];
+    }
+  | {
+      readonly widget: 'datetime';
+      readonly field: string;
+      /** Always UTC ISO-8601. The widget formats it into `timeZone`. */
+      readonly value: string | null;
+      readonly timeZone: string;
+      readonly precision: 'date' | 'instant';
+    }
+  | { readonly widget: 'timezone-picker'; readonly field: string; readonly value: string | null }
+  | { readonly widget: 'locale-picker'; readonly field: string; readonly value: string | null }
+  | { readonly widget: 'json-editor'; readonly field: string; readonly value: string }
+  | {
+      readonly widget: 'reference';
+      readonly field: string;
+      readonly value: string | null;
+      readonly entity: string;
+      readonly labelField: string;
+    }
+  | {
+      readonly widget: 'upload';
+      readonly field: string;
+      readonly value: { readonly url: string; readonly name: string } | null;
+    };
+
+const fail = (field: AdminField, cause: string, fix: string): never => {
+  throw new AdminFieldUnsupportedError({ entity: field.entity, field: field.name, cause, fix });
+};
+
+const CURRENCY = /^[A-Z]{3}$/;
+
+/**
+ * `money()` puts a `bigint` on the row — Postgres `bigint` minor units — where `Money` is a
+ * number. This is the one place that widening happens, and it refuses rather than round: a
+ * value past the safe integer range would render as a different amount than it is.
+ */
+const minorUnits = (value: unknown): number | null => {
+  if (typeof value === 'bigint') {
+    const widened = Number(value);
+    return Number.isSafeInteger(widened) ? widened : null;
+  }
+  return typeof value === 'number' && Number.isInteger(value) ? value : 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 {
+  if (value === null || value === undefined) return null;
+  if (typeof value === 'number') {
+    return fail(
+      field,
+      `money value arrived as the number ${value}; money is integer minor units + an ISO currency`,
+      `store ${field.name} as { minor, currency } — x g migration "money ${field.entity}.${field.name}"`,
+    );
+  }
+  if (typeof value !== 'object') {
+    return fail(
+      field,
+      `money value is a ${typeof value}`,
+      'return { minor, currency } from the repo',
+    );
+  }
+  const bag = value as { minor?: unknown; currency?: unknown };
+  const minor = minorUnits(bag.minor);
+  if (minor === null) {
+    return fail(
+      field,
+      `money.minor is ${String(bag.minor)}; minor units are integers`,
+      'multiply by the currency exponent before storing, never round at render time',
+    );
+  }
+  const currency = typeof bag.currency === 'string' ? bag.currency : field.currency;
+  if (currency === undefined || !CURRENCY.test(currency)) {
+    return fail(
+      field,
+      `money has no ISO-4217 currency (got ${String(bag.currency)})`,
+      `declare the currency with fields: { ${field.name}: { currency: 'EUR' } }`,
+    );
+  }
+  return { minor, currency };
+}
+
+/** No zone, no render. A timestamp shown in an implicit zone is a wrong timestamp. */
+export function assertZone(field: AdminField, timeZone: string | undefined): string {
+  if (timeZone === undefined || timeZone.trim() === '') {
+    return fail(
+      field,
+      'timestamp has no IANA time zone; the admin never formats a date in an implicit zone',
+      "pass ctx.timeZone (actor.timeZone ?? 'UTC') into the admin view",
+    );
+  }
+  return timeZone;
+}
+
+function isoOf(field: AdminField, value: unknown): string | null {
+  if (value === null || value === undefined) return null;
+  if (value instanceof Date) return value.toISOString();
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number') return new Date(value).toISOString();
+  return fail(field, `timestamp value is a ${typeof value}`, 'return an ISO string or a Date');
+}
+
+const optionsFor = (field: AdminField): readonly SelectOption[] =>
+  (field.values ?? []).map((value) => ({
+    value,
+    labelKey: `admin.${field.entity}.field.${field.name}.option.${value}`,
+  }));
+
+const asText = (value: unknown): string =>
+  value === null || value === undefined ? '' : String(value);
+
+/** The single dispatch from a field + a raw row value to renderable props. */
+export function widgetProps(field: AdminField, value: unknown, ctx: WidgetContext): WidgetProps {
+  switch (field.widget) {
+    case 'text-input':
+      return { widget: 'text-input', field: field.name, value: asText(value) };
+    case 'textarea':
+      return { widget: 'textarea', field: field.name, value: asText(value) };
+    case 'number-input':
+      return {
+        widget: 'number-input',
+        field: field.name,
+        value: typeof value === 'number' ? value : null,
+      };
+    case 'money':
+      return { widget: 'money', field: field.name, value: assertMoney(field, value) };
+    case 'checkbox':
+      return { widget: 'checkbox', field: field.name, value: value === true };
+    case 'select':
+      return {
+        widget: 'select',
+        field: field.name,
+        value: value === null || value === undefined ? null : String(value),
+        options: optionsFor(field),
+      };
+    case 'datetime':
+      return {
+        widget: 'datetime',
+        field: field.name,
+        value: isoOf(field, value),
+        timeZone: assertZone(field, ctx.timeZone),
+        precision: field.type === 'date' ? 'date' : 'instant',
+      };
+    case 'timezone-picker':
+      return {
+        widget: 'timezone-picker',
+        field: field.name,
+        value: typeof value === 'string' ? value : null,
+      };
+    case 'locale-picker':
+      return {
+        widget: 'locale-picker',
+        field: field.name,
+        value: typeof value === 'string' ? value : null,
+      };
+    case 'json-editor':
+      return {
+        widget: 'json-editor',
+        field: field.name,
+        value: value === undefined ? '' : JSON.stringify(value, null, 2),
+      };
+    case 'reference':
+      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',
+      };
+    case 'upload':
+      return { widget: 'upload', field: field.name, value: uploadValue(field, value) };
+  }
+}
+
+function uploadValue(
+  field: AdminField,
+  value: unknown,
+): { readonly url: string; readonly name: string } | null {
+  if (value === null || value === undefined) return null;
+  if (typeof value === 'string') return { url: value, name: value.split('/').pop() ?? field.name };
+  const bag = value as { url?: unknown; name?: unknown };
+  if (typeof bag.url !== 'string') {
+    return fail(field, 'file value has no url', 'return { url, name } from the repo');
+  }
+  return { url: bag.url, name: typeof bag.name === 'string' ? bag.name : field.name };
+}