@ultimat3/ui 29.3.2 → 30.0.0

package/src/form/field-path.ts

@@ -1,12 +1,9 @@
 // The ONE path grammar a form speaks, in both directions: the dotted, bracketed string a schema
-// issue carries (`items[2].price`) and the `name` attribute the control renders. One grammar is
-// what lets a rejection find its control at all — two would be a hand-written mapping table per
-// form, which is the 40-forms-40-mappings cost this binding exists to delete.
-
-/** A Standard Schema issue segment. Wrapped or bare — conforming libraries send both. */
-export interface IssuePathSegment {
-  readonly key: PropertyKey;
-}
+// issue carries (`items[2].price`, rendered by `@ultimat3/schema`'s `formatPath`, never copied)
+// and the `name` attribute the control renders.
+//
+// One grammar is what lets a rejection find its control at all — two would be a hand-written
+// mapping table per form, which is the 40-forms-40-mappings cost this binding exists to delete.
 
 export type FieldPathSegment = string | number;
 
@@ -16,31 +13,8 @@ export type FieldPathSegment = string | number;
  */
 export const MAX_FIELD_INDEX = 10_000;
 
-/**
- * Structural copy of `@ultimat3/schema`'s `formatPath`. **Keep in sync**: an issue that arrives
- * from the server was rendered by THAT function, so a divergence here is an error that lands on no
- * field. Copied rather than imported because `@ultimat3/ui` holds no dependency edge on
- * `@ultimat3/schema` — the tier table permits one, the manifest and the lockfile do not — the same
- * trade `@ultimat3/db`'s `entity-shape.ts` makes one tier down.
- */
-export function formatFieldPath(
-  path: readonly (PropertyKey | IssuePathSegment)[] | undefined,
-): string {
-  if (path === undefined || path.length === 0) return '';
-  let out = '';
-  for (const segment of path) {
-    const key = typeof segment === 'object' ? segment.key : segment;
-    if (typeof key === 'number') {
-      out += `[${key}]`;
-    } else {
-      out += out === '' ? String(key) : `.${String(key)}`;
-    }
-  }
-  return out;
-}
-
 const KEY = /^[A-Za-z_$][A-Za-z0-9_$]*/;
-/** `[0]`, never `[01]`: an index that does not round-trip through `formatFieldPath` is not one. */
+/** `[0]`, never `[01]`: an index that does not round-trip through schema's `formatPath` is not one. */
 const INDEX = /^\[(0|[1-9][0-9]*)\]/;
 
 /**
@@ -51,7 +25,7 @@ const INDEX = /^\[(0|[1-9][0-9]*)\]/;
 const UNSAFE_KEYS: ReadonlySet<string> = new Set(['__proto__', 'prototype', 'constructor']);
 
 /**
- * The reverse of `formatFieldPath`, or `null` for anything that is not a field path. Total and
+ * The reverse of `@ultimat3/schema`'s `formatPath`, or `null` for anything that is not a field path. Total and
  * silent by design: the caller decides whether an unusable name is a refusal (`valuesOfForm`, which
  * is building an object) or simply a path that matches no field (`distributeIssues`, which must
  * surface it and carry on).

package/src/form/form-binding.ts

@@ -5,14 +5,10 @@
 // produced in exactly one place — after the caller's `submit` resolves — and the local parse's
 // VALUE is discarded, so a client cannot decide either that a form is valid or what it said.
 
+import type { StandardSchemaV1 } from '@ultimat3/schema';
 import { invalidFieldPathError } from '../errors';
 import { parseFieldPath } from './field-path';
-import {
-  type FormIssue,
-  type FormSchema,
-  issuesFromRejection,
-  issuesFromValidation,
-} from './form-issue';
+import { type FormIssue, issuesFromRejection, issuesFromValidation } from './form-issue';
 import {
   distributeIssues,
   errorOf,
@@ -43,9 +39,10 @@ export interface FormBindingOptions<TValues, TResult> {
   /**
    * The action's `input`. Optional, and a LATENCY optimisation only: the action re-parses on the
    * server on every path, so omitting this changes when the user hears about a bad value, never
-   * whether it is rejected.
+   * whether it is rejected. Any Standard Schema; its OUTPUT is never read, so a browser cannot
+   * choose what the server is asked to store.
    */
-  readonly schema?: FormSchema | undefined;
+  readonly schema?: StandardSchemaV1 | undefined;
   /** Called on every transition — how a reactive shell mirrors the state into a signal. */
   readonly onState?: ((state: FormState<TResult>) => void) | undefined;
   /**

package/src/form/form-issue.ts

@@ -3,7 +3,13 @@
 // — `FormIssue.message` is a schema's diagnostic text, never a translated string.
 
 import { renderThrowable, stringField } from '@ultimat3/core';
-import { formatFieldPath, type IssuePathSegment, parseFieldPath } from './field-path';
+import {
+  formatPath,
+  issueRuleFacts,
+  type SchemaIssueParams,
+  type StandardResult,
+} from '@ultimat3/schema';
+import { parseFieldPath } from './field-path';
 
 /**
  * One rejected value, addressed by the path the schema gave it.
@@ -18,47 +24,30 @@ export interface FormIssue {
   readonly message: string;
   /** The framework code that carried it, when a rejection named one. */
   readonly code: string | undefined;
-}
-
-/** One issue as a conforming schema library reports it. */
-export interface FormValidationIssue {
-  readonly message: string;
-  readonly path?: readonly (PropertyKey | IssuePathSegment)[] | undefined;
+  /**
+   * Which rule refused — `@ultimat3/schema`'s `SCHEMA_RULES` (`string.min`), the same from a local
+   * parse and a server rejection. What `messageFor` keys on, with `params` interpolated. Absent
+   * for a library that names none, so a translator falls back to `message`.
+   */
+  readonly rule?: string;
+  /** The declared facts the rule names (`{ min: 3 }`), for interpolation. Scalars only. */
+  readonly params?: SchemaIssueParams;
 }
 
 /**
- * Standard Schema's result: `issues` present is the failure, absent is the pass.
- *
- * The success member holds `value: unknown` and nothing reads it — the type says what the runtime
- * does. A client-side parse is a latency optimisation, so its OUTPUT is not something the server
- * agreed to, and typing it would invite a caller to submit it.
+ * A local parse's issues, addressed by path. A result with none answers `[]`. Standard Schema's own
+ * result, `@ultimat3/schema`'s types: its success `value` is never read, because a client-side
+ * parse is a latency optimisation and its OUTPUT is nothing the server agreed to.
  */
-export type FormValidationResult =
-  | { readonly value: unknown; readonly issues?: undefined }
-  | { readonly issues: readonly FormValidationIssue[] };
-
-/**
- * The minimum of an input schema this package needs — Standard Schema's one member, declared
- * structurally so `@ultimat3/ui` needs no dependency edge on `@ultimat3/schema`. An `action()`'s
- * own `input` satisfies it as written.
- *
- * The OUTPUT type is deliberately absent: a client-side parse is a latency optimisation, its value
- * is thrown away, and typing it would invite a caller to submit it.
- */
-export interface FormSchema {
-  readonly '~standard': {
-    readonly validate: (value: unknown) => FormValidationResult | Promise<FormValidationResult>;
-  };
-}
-
-/** A local parse's issues, addressed by path. A result with none answers `[]`. */
-export function issuesFromValidation(result: FormValidationResult): readonly FormIssue[] {
+export function issuesFromValidation(result: StandardResult<unknown>): readonly FormIssue[] {
   const issues = result.issues;
   if (issues === undefined) return [];
   return issues.map((issue) => ({
-    path: formatFieldPath(issue.path),
+    path: formatPath(issue.path),
     message: issue.message,
     code: undefined,
+    // Schema's one reader: a non-string rule dropped, scalar params only, total.
+    ...issueRuleFacts(issue),
   }));
 }
 
@@ -71,8 +60,8 @@ const LIST_PREFIX = 'failed validation: ';
 /**
  * `formatIssues()`'s separator, on both sides of the wire. A message that itself contains `'; '`
  * splits wrongly here — and degrades VISIBLY, because a fragment whose head is not a field path
- * lands at the form rather than on a control. That is the cost of the wire carrying no structured
- * issue list; see this file's note in `README.md`.
+ * lands at the form rather than on a control. Only for a rejection that lost its `meta.issues`
+ * (`toProblem` serves the list since 2026-10); see this file's note in `README.md`.
  */
 const ISSUE_SEPARATOR = '; ';
 
@@ -109,7 +98,12 @@ function issuesFromMeta(rejection: object, code: string | undefined): readonly F
   for (const entry of held as readonly unknown[]) {
     const message = stringField(entry, 'message');
     if (message === undefined) return null;
-    issues.push({ path: stringField(entry, 'path') ?? '', message, code });
+    issues.push({
+      path: stringField(entry, 'path') ?? '',
+      message,
+      code,
+      ...issueRuleFacts(entry),
+    });
   }
   return issues.length === 0 ? null : issues;
 }

package/src/form/form-values.ts

@@ -4,8 +4,9 @@
 //
 // A form is user input reaching an object graph, so a name is refused, never repaired.
 
+import { formatPath } from '@ultimat3/schema';
 import { conflictingFieldNameError, invalidFieldPathError } from '../errors';
-import { type FieldPathSegment, formatFieldPath, parseFieldPath } from './field-path';
+import { type FieldPathSegment, parseFieldPath } from './field-path';
 
 type Container = Record<string, unknown> | readonly unknown[];
 
@@ -52,7 +53,7 @@ function place(
   const [head, ...rest] = segments;
   // `parseFieldPath` never answers an empty list, so this is the type's obligation, not a case.
   if (head === undefined) return;
-  const at = (): string => formatFieldPath([...prefix, head]);
+  const at = (): string => formatPath([...prefix, head]);
   const existing = childOf(container, head);
   const next = rest[0];
 

package/src/hotkeys-view.ts

@@ -0,0 +1,150 @@
+// What a key press means to a page's shortcut table, apart from any listener: never while typing,
+// never with a modifier, a two-key chord inside one window, and `mod+` that fires anywhere. Pure,
+// so `useHotkeys` and `ShortcutSheet` read ONE table and the binding and its legend cannot drift.
+
+import { invalidValueError } from './errors';
+
+/** One shortcut: the bindings that run it, its already-translated legend line, and the work. */
+export interface HotkeyRow {
+  /**
+   * Alternatives, each spelled as `KeyboardEvent.key` reports it: `'?'`, `'Escape'`, a chord of
+   * two steps `'g r'`, or the platform modifier `'mod+k'` (⌘ on Apple, Ctrl elsewhere).
+   */
+  readonly keys: readonly string[];
+  readonly label: string;
+  readonly run: () => void;
+}
+
+export type HotkeyTable = readonly HotkeyRow[];
+
+/** How long the second key of a chord may follow the first. */
+export const CHORD_WINDOW_MS = 1_000;
+
+/** The parts of a `KeyboardEvent` the rule reads; `editable` is the shell's `closest()` answer. */
+export interface HotkeyKeyEvent {
+  readonly key: string;
+  readonly ctrlKey: boolean;
+  readonly metaKey: boolean;
+  readonly altKey: boolean;
+  readonly isComposing: boolean;
+  readonly editable: boolean;
+  /** `event.timeStamp` — monotonic, which is all the chord window compares. */
+  readonly at: number;
+}
+
+export interface HotkeyState {
+  /** `mod` is ⌘ on Apple platforms, Ctrl everywhere else. */
+  readonly mac: boolean;
+  /** The first step of a chord in flight, or `null`. */
+  readonly pending: string | null;
+  readonly since: number;
+}
+
+export const IDLE_HOTKEY_STATE: HotkeyState = { mac: false, pending: null, since: 0 };
+
+/** A validated table: every binding to its row, and every chord's first step. */
+export interface CompiledHotkeys {
+  readonly bindings: ReadonlyMap<string, HotkeyRow>;
+  readonly prefixes: ReadonlySet<string>;
+}
+
+const MOD = 'mod+';
+const KEY = /^(?:\S|[A-Z][A-Za-z0-9]+)$/;
+
+/** The steps of one binding, or `null` when it is not in the grammar. */
+function stepsOf(binding: string): readonly string[] | null {
+  const steps = binding.split(' ');
+  if (steps.length > 2) return null;
+  for (const step of steps) {
+    const key = step.startsWith(MOD) && steps.length === 1 ? step.slice(MOD.length) : step;
+    if (!KEY.test(key)) return null;
+  }
+  return steps;
+}
+
+/**
+ * Validate and index rows — one table or every island's merged. A binding twice, a chord over two
+ * keys, a chord whose first step is also a binding of its own, or `mod+` inside a chord is
+ * `X_UI_INVALID_VALUE` naming the keys: each is a shortcut that can never fire as written.
+ */
+export function compileHotkeys(rows: HotkeyTable): CompiledHotkeys {
+  const bindings = new Map<string, HotkeyRow>();
+  const prefixes = new Set<string>();
+  const expected =
+    "unique bindings of one key ('?'), 'mod+<key>', or a two-key chord ('g r'), none a prefix of another";
+  for (const row of rows) {
+    if (row.keys.length === 0)
+      throw invalidValueError('useHotkeys', `${row.label}: no keys`, expected);
+    for (const binding of row.keys) {
+      const steps = stepsOf(binding);
+      if (steps === null) throw invalidValueError('useHotkeys', binding, expected);
+      if (bindings.has(binding)) throw invalidValueError('useHotkeys', binding, expected);
+      const first = steps[0] ?? '';
+      if (steps.length === 2) {
+        if (bindings.has(first)) throw invalidValueError('useHotkeys', first, expected);
+        prefixes.add(first);
+      } else if (prefixes.has(binding)) {
+        throw invalidValueError('useHotkeys', binding, expected);
+      }
+      bindings.set(binding, row);
+    }
+  }
+  return { bindings, prefixes };
+}
+
+export interface HotkeyAnswer {
+  /** The row to run, if the key completed one. The shell calls `preventDefault` then `run`. */
+  readonly row: HotkeyRow | undefined;
+  readonly state: HotkeyState;
+}
+
+const idle = (state: HotkeyState): HotkeyState =>
+  state.pending === null ? state : { ...state, pending: null };
+
+/** What one key press does, given the chord in flight and the table. */
+export function hotkeyAction(
+  event: HotkeyKeyEvent,
+  state: HotkeyState,
+  table: CompiledHotkeys,
+): HotkeyAnswer {
+  // An IME is mid-word: every key belongs to the composition, not the page.
+  if (event.isComposing || event.key === 'Process') return { row: undefined, state };
+  const mod = state.mac ? event.metaKey : event.ctrlKey;
+  const otherMod = state.mac ? event.ctrlKey : event.metaKey;
+  if (mod && !otherMod && !event.altKey) {
+    return { row: table.bindings.get(`${MOD}${event.key}`), state: idle(state) };
+  }
+  if (event.ctrlKey || event.metaKey || event.altKey) return { row: undefined, state: idle(state) };
+  if (event.editable && event.key !== 'Escape') return { row: undefined, state: idle(state) };
+
+  if (state.pending !== null && event.at - state.since <= CHORD_WINDOW_MS) {
+    const chord = table.bindings.get(`${state.pending} ${event.key}`);
+    if (chord !== undefined) return { row: chord, state: idle(state) };
+  }
+  const single = table.bindings.get(event.key);
+  if (single !== undefined) return { row: single, state: idle(state) };
+  if (table.prefixes.has(event.key)) {
+    return { row: undefined, state: { ...state, pending: event.key, since: event.at } };
+  }
+  return { row: undefined, state: idle(state) };
+}
+
+const NAMED = new Map<string, string>([
+  ['Escape', 'Esc'],
+  ['ArrowUp', '↑'],
+  ['ArrowDown', '↓'],
+  ['ArrowLeft', '←'],
+  ['ArrowRight', '→'],
+]);
+
+/**
+ * A binding as keycaps, one group per chord step: `mod+k` → `[['⌘', 'K']]` on Apple and
+ * `[['Ctrl', 'K']]` elsewhere — the glyphs printed on the keys, so they are not translated.
+ */
+export function hotkeyKeycaps(binding: string, mac: boolean): readonly (readonly string[])[] {
+  return binding.split(' ').map((step) => {
+    if (!step.startsWith(MOD)) return [NAMED.get(step) ?? step];
+    const key = step.slice(MOD.length);
+    return [mac ? '⌘' : 'Ctrl', key.length === 1 ? key.toUpperCase() : (NAMED.get(key) ?? key)];
+  });
+}

package/src/i18n-keys.ts

@@ -1,53 +1,10 @@
-// Every string the design system needs but cannot receive as a prop. Components
-// resolve these through the context translator, so an app can localise the whole
-// system by adding one namespace to its catalog — and a miss is loud (⟦key⟧).
+// `UI_KEYS`: every string the design system resolves through the context translator, so an app
+// localises the whole system with one catalog namespace (a miss is loud, ⟦key⟧). A NAMESPACE over
+// `ui-keys.ts`, never an object literal: `UI_KEYS.x` is then a static member read a bundler turns
+// into one string, so an island keeps only the keys it reads (`i18n-keys-shake.test.ts`).
 
-export const UI_KEYS = {
-  close: 'ui.close',
-  cancel: 'ui.cancel',
-  confirm: 'ui.confirm',
-  dismiss: 'ui.dismiss',
-  loading: 'ui.loading',
-  empty: 'ui.empty',
-  // `ui.error` cannot be a leaf: `ui.error.code|cause|fix` are branches under it, and a catalog is
-  // authored nested — `parseNestedCatalog` refuses a dot inside a key, so a name is a leaf or a
-  // branch, never both. Same reason `theme` is `ui.theme.label`.
-  error: 'ui.error.title',
-  retry: 'ui.retry',
-  next: 'ui.next',
-  previous: 'ui.previous',
-  page: 'ui.page',
-  sortAscending: 'ui.sort.ascending',
-  sortDescending: 'ui.sort.descending',
-  breadcrumb: 'ui.breadcrumb',
-  /** AppShell's skip link — the first Tab stop on every page. */
-  skip: 'ui.skip',
-  /** AppShell's sidebar landmark name. */
-  navigation: 'ui.navigation',
-  menu: 'ui.menu',
-  more: 'ui.more',
-  required: 'ui.required',
-  optional: 'ui.optional',
-  theme: 'ui.theme.label',
-  themeLight: 'ui.theme.light',
-  themeDark: 'ui.theme.dark',
-  themeSystem: 'ui.theme.system',
-  language: 'ui.language',
-  /** Combobox: how many suggestions the datalist currently offers. Takes `{ count }`. */
-  suggestions: 'ui.suggestions',
-  /** Combobox: the query matched nothing. */
-  noResults: 'ui.results.empty',
-  /** InfiniteScroll: the label on the next-page control. */
-  loadMore: 'ui.load.more',
-  /** InfiniteScroll: announced when the last page has arrived. */
-  endOfList: 'ui.load.end',
-  /** CopyButton: the control's name before a copy. */
-  copy: 'ui.copy',
-  /** CopyButton: announced, and the control's name, once the write succeeded. */
-  copied: 'ui.copied',
-  errorCode: 'ui.error.code',
-  errorCause: 'ui.error.cause',
-  errorFix: 'ui.error.fix',
-} as const;
+import * as UI_KEYS from './ui-keys';
+
+export { UI_KEYS };
 
 export type UiKey = (typeof UI_KEYS)[keyof typeof UI_KEYS];