@ultimat3/ui 29.4.0 → 30.1.0

package/src/components/command-palette-view.ts

@@ -2,24 +2,65 @@
 // roving selection goes on an arrow key, and what a key means. Pure, so the caller's island and
 // a page test decide the same thing — and so the component owns no rule a caller could get wrong.
 
+import { rankOptions } from './rank-options';
+
 export interface CommandPaletteItem {
   /** Stable across a re-filter — what roving selection and `onRunItem` both key off. */
   readonly id: string;
   readonly label: string;
   /** Secondary text — a target URL, a slug, a key chord. Empty renders nothing. */
   readonly hint: string;
+  /** Already-translated heading the item sits under; items of one group render together. */
+  readonly group?: string | undefined;
+  /** Words a reader may type that the label never shows — matched, never rendered. */
+  readonly keywords?: readonly string[] | undefined;
+}
+
+/** A run of items under one heading; `group` is `undefined` for the ungrouped run. */
+export interface CommandPaletteGroup {
+  readonly group: string | undefined;
+  readonly items: readonly CommandPaletteItem[];
 }
 
-/** Case-insensitive substring over label and hint; an empty query keeps everything. */
+/**
+ * `rankOptions` over label, hint and keywords — the ranker `SearchableSelect` uses, so `cafe`
+ * finds `Café` — then regrouped: a group keeps the place its first item had in the caller's list,
+ * and the rank decides the order inside it. An empty query keeps everything, in order.
+ */
 export function filterItems(
   items: readonly CommandPaletteItem[],
   query: string,
 ): readonly CommandPaletteItem[] {
-  const needle = query.trim().toLowerCase();
-  if (needle === '') return items;
-  return items.filter(
-    (item) => item.label.toLowerCase().includes(needle) || item.hint.toLowerCase().includes(needle),
-  );
+  const ranked = rankOptions(
+    items.map((item) => ({
+      label: item.label,
+      description: item.hint,
+      keywords: item.keywords,
+      item,
+    })),
+    query,
+    items.length,
+  ).matches.map((entry) => entry.item);
+  const order = new Map<string | undefined, number>();
+  for (const item of items) if (!order.has(item.group)) order.set(item.group, order.size);
+  return ranked
+    .map((item, index) => ({ item, index }))
+    .sort(
+      (a, b) =>
+        (order.get(a.item.group) ?? 0) - (order.get(b.item.group) ?? 0) || a.index - b.index,
+    )
+    .map((entry) => entry.item);
+}
+
+/** Consecutive items sharing a `group`, as the palette renders them under one heading each. */
+export function groupItems(items: readonly CommandPaletteItem[]): readonly CommandPaletteGroup[] {
+  const out: { group: string | undefined; items: CommandPaletteItem[] }[] = [];
+  for (const item of items) {
+    const last = out[out.length - 1];
+    if (last !== undefined && last.group === item.group) last.items.push(item);
+    else out.push({ group: item.group, items: [item] });
+  }
+  return out;
 }
 
 /** The active id after a step, wrapping at both ends; the first item when nothing was active. */

package/src/components/confirm-dialog-view.ts

@@ -0,0 +1,47 @@
+// A destructive confirmation's rules, apart from its markup: idle → busy → idle or refused, a
+// second submit while busy refused, and a confirm label that names the act. Pure, so the island
+// path and its test decide the same thing.
+
+import { invalidValueError } from '../errors';
+
+export type ConfirmState =
+  | { readonly kind: 'idle' }
+  | { readonly kind: 'busy' }
+  /** The act was refused: the dialog stays open with `message` in its form summary. */
+  | { readonly kind: 'refused'; readonly message: string };
+
+export type ConfirmEvent =
+  | { readonly type: 'submit' }
+  /** `onConfirm` settled: `undefined` is done, a string is the already-translated refusal. */
+  | { readonly type: 'settled'; readonly refusal: string | undefined }
+  /** The dialog closed, by Cancel or Esc: the next opening starts clean. */
+  | { readonly type: 'closed' };
+
+export const CONFIRM_IDLE: ConfirmState = { kind: 'idle' };
+
+/** The next state, or `null` for an event the current state refuses — a submit while busy. */
+export function confirmStep(state: ConfirmState, event: ConfirmEvent): ConfirmState | null {
+  switch (event.type) {
+    case 'submit':
+      return state.kind === 'busy' ? null : { kind: 'busy' };
+    case 'settled':
+      if (state.kind !== 'busy') return null;
+      return event.refusal === undefined
+        ? CONFIRM_IDLE
+        : { kind: 'refused', message: event.refusal };
+    case 'closed':
+      return state.kind === 'busy' ? null : CONFIRM_IDLE;
+  }
+}
+
+/**
+ * A confirm button says what it does — "Delete post", never "OK" — so there is no default and an
+ * empty one is `X_UI_INVALID_VALUE`: the label is the last thing read before an act that cannot
+ * be taken back.
+ */
+export function confirmLabelOf(label: string): string {
+  if (label.trim() === '') {
+    throw invalidValueError('ConfirmDialog confirmLabel', label, 'a verb naming the act');
+  }
+  return label;
+}

package/src/components/data-table-rows.ts

@@ -0,0 +1,93 @@
+// DataTable's keyed rows: one cell per `rowKey`, so a live update leaves an unchanged row's DOM —
+// its focus, its open "more" disclosure — exactly where it was. Pure over an injected runtime, so
+// the rule is proven under real Solid without a renderer; `solid-js` stays a type-only import.
+
+import { renderCauseValue } from '@ultimat3/core';
+import { UI_ERROR_CODES, UiError } from '../errors';
+import type { Accessor, Setter } from '../theme/solid-adapter';
+
+/**
+ * The slice of Solid the rule needs. `createRoot` is the load-bearing one: a row built inside the
+ * body's computation is OWNED by it, and Solid disposes what a computation owns each time it
+ * re-runs — so a kept node would keep its markup and lose every binding inside it on the next tick.
+ */
+export interface KeyedRowsRuntime {
+  createSignal<T>(value: T): [Accessor<T>, Setter<T>];
+  createRoot<T>(fn: (dispose: () => void) => T): T;
+  onCleanup(fn: () => void): void;
+}
+
+interface Cell<Row, Node> {
+  /** The object last seen under this key, held plainly: comparing it must not subscribe the body. */
+  row: Row;
+  readonly set: Setter<Row>;
+  readonly node: Node;
+  readonly dispose: () => void;
+}
+
+/** Two rows under one key cannot both keep a node. */
+function duplicateKeyError(key: string): UiError {
+  return new UiError({
+    code: UI_ERROR_CODES.invalidValue,
+    cause: `<DataTable> rowKey answered ${renderCauseValue(key)} for two rows, so one node would have to be both — rowKey must be unique per row`,
+    fix: 'rowKey: (row) => row.id   # on <DataTable>: the row primary key, unique within rows',
+  });
+}
+
+/**
+ * Call once, in the component body: the returned map is what the body runs on every update. The
+ * same object under a key returns the same node and runs nothing; a new object under a kept key
+ * returns the same node and sets its signal, so only the cells reading it redraw; a vanished key
+ * disposes its row. Disposing the owner disposes every row.
+ */
+export function keyedRows<Row, Node>(
+  runtime: KeyedRowsRuntime,
+  keyOf: (row: Row) => string,
+  build: (row: Accessor<Row>, key: string) => Node,
+): (rows: readonly Row[]) => Node[] {
+  const cells = new Map<string, Cell<Row, Node>>();
+  runtime.onCleanup(() => {
+    for (const cell of cells.values()) cell.dispose();
+    cells.clear();
+  });
+
+  const cellFor = (row: Row, key: string): Cell<Row, Node> => {
+    const kept = cells.get(key);
+    if (kept !== undefined) {
+      if (kept.row !== row) {
+        kept.row = row;
+        kept.set(row);
+      }
+      return kept;
+    }
+    const made = runtime.createRoot((dispose) => {
+      const [current, set] = runtime.createSignal(row);
+      try {
+        return { row, set, node: build(current, key), dispose };
+      } catch (error) {
+        // Never cached, so never disposed by a later run: what the build made so far goes now.
+        dispose();
+        throw error;
+      }
+    });
+    cells.set(key, made);
+    return made;
+  };
+
+  return (rows) => {
+    const seen = new Set<string>();
+    const nodes = rows.map((row) => {
+      const key = keyOf(row);
+      if (seen.has(key)) throw duplicateKeyError(key);
+      seen.add(key);
+      return cellFor(row, key).node;
+    });
+    for (const [key, cell] of cells) {
+      if (!seen.has(key)) {
+        cell.dispose();
+        cells.delete(key);
+      }
+    }
+    return nodes;
+  };
+}

package/src/components/date-picker-view.ts

@@ -0,0 +1,38 @@
+// When a date input gets its calendar, and what opens it. Pure, so the progressive-enhancement
+// rule is tested without a browser: the native input always renders and is always the value.
+
+import type { PlainDate } from '@ultimat3/time';
+import { isPlainDate } from '@ultimat3/time';
+
+/** The media query a calendar popover waits for. A coarse pointer keeps the platform's picker. */
+export const FINE_POINTER_QUERY = '(pointer: fine)';
+
+/** The calendar is an extra for a fine pointer with a script; a phone's native picker wins. */
+export function enhancesWithCalendar(
+  matchMedia: ((query: string) => { matches: boolean }) | undefined,
+): boolean {
+  return matchMedia?.(FINE_POINTER_QUERY).matches === true;
+}
+
+/** F4 and Alt+ArrowDown open a date control's picker on every desktop platform. */
+export function opensPicker(event: { readonly key: string; readonly altKey?: boolean }): boolean {
+  return event.key === 'F4' || (event.key === 'ArrowDown' && event.altKey === true);
+}
+
+/** What the input holds, as a date: `undefined` for empty or a value the browser half-typed. */
+export function inputDate(raw: string): PlainDate | undefined {
+  return isPlainDate(raw) ? raw : undefined;
+}
+
+/**
+ * Write a picked day into the native input the way typing would, so a form, a `Field` and any
+ * `onInput`/`onChange` listener see one path whether the day came from the keyboard or the grid.
+ */
+export function writeInputDate(
+  input: { value: string; dispatchEvent(event: Event): boolean },
+  date: PlainDate,
+): void {
+  input.value = date;
+  input.dispatchEvent(new Event('input', { bubbles: true }));
+  input.dispatchEvent(new Event('change', { bubbles: true }));
+}

package/src/components/date-range-view.ts

@@ -0,0 +1,46 @@
+// A date range's rules: which end a pick sets, a backwards pair swapped, and where a day sits in
+// the span (`aria-selected` covers it all). Pure over `PlainDate`, so `DateRangePicker` is wiring.
+
+import { comparePlainDates, type PlainDate } from '@ultimat3/time';
+
+export interface DateRange {
+  readonly from?: PlainDate | undefined;
+  readonly to?: PlainDate | undefined;
+}
+
+export type SpanPosition = 'start' | 'end' | 'inside';
+
+/** Ends in order: a `to` before its `from` is the same span read the other way. */
+export function orderedRange(range: DateRange): DateRange {
+  const { from, to } = range;
+  if (from !== undefined && to !== undefined && comparePlainDates(to, from) < 0) {
+    return { from: to, to: from };
+  }
+  return range;
+}
+
+/**
+ * The first pick starts a range, the second completes it — either side of the first, swapped into
+ * order. A pick after a complete range starts the next one.
+ */
+export function pickRange(
+  range: DateRange,
+  picked: PlainDate,
+): { readonly range: DateRange; readonly complete: boolean } {
+  if (range.from === undefined || range.to !== undefined) {
+    return { range: { from: picked, to: undefined }, complete: false };
+  }
+  return { range: orderedRange({ from: range.from, to: picked }), complete: true };
+}
+
+/** Where `date` sits in the span, `undefined` outside it. One end alone is its own start. */
+export function spanPosition(date: PlainDate, range: DateRange): SpanPosition | undefined {
+  const { from, to } = orderedRange(range);
+  if (from === undefined) return undefined;
+  if (date === from) return 'start';
+  if (to === undefined) return undefined;
+  if (date === to) return 'end';
+  return comparePlainDates(date, from) > 0 && comparePlainDates(date, to) < 0
+    ? 'inside'
+    : undefined;
+}

package/src/components/diff-view-view.ts

@@ -0,0 +1,85 @@
+// The pure half of `DiffView`: rows from either input, folded at `maxLines`; the side-by-side
+// pairing; a row's text cut into marked and unmarked segments; and where each change run starts.
+
+import { finiteCount } from '@ultimat3/core';
+import { type DiffRow, foldRows, lineDiff } from '../content/line-diff';
+import { parseUnifiedPatch } from '../content/unified-patch';
+
+export const DIFF_VIEW_MAX_LINES = 2_000;
+
+export interface DiffInput {
+  readonly old?: string | undefined;
+  readonly new?: string | undefined;
+  readonly patch?: string | undefined;
+  readonly maxLines?: number | undefined;
+}
+
+export function diffViewRows(input: DiffInput): readonly DiffRow[] {
+  const max = finiteCount('DiffView', 'maxLines', input.maxLines ?? DIFF_VIEW_MAX_LINES, 1);
+  const rows =
+    input.patch === undefined
+      ? lineDiff(input.old ?? '', input.new ?? '')
+      : parseUnifiedPatch(input.patch);
+  return foldRows(rows, max);
+}
+
+export type SidePair =
+  | { readonly kind: 'pair'; readonly left: DiffRow | null; readonly right: DiffRow | null }
+  | { readonly kind: 'whole'; readonly row: DiffRow };
+
+/** Context on both sides; a removed run beside the added run after it; headers and folds across. */
+export function sidePairs(rows: readonly DiffRow[]): SidePair[] {
+  const out: SidePair[] = [];
+  for (let r = 0; r < rows.length; ) {
+    const row = rows[r];
+    if (row === undefined) break;
+    if (row.kind === 'context') {
+      out.push({ kind: 'pair', left: row, right: row });
+      r += 1;
+      continue;
+    }
+    if (row.kind !== 'del' && row.kind !== 'add') {
+      out.push({ kind: 'whole', row });
+      r += 1;
+      continue;
+    }
+    let dels = r;
+    while (rows[dels]?.kind === 'del') dels += 1;
+    let adds = dels;
+    while (rows[adds]?.kind === 'add') adds += 1;
+    const span = Math.max(dels - r, adds - dels);
+    for (let p = 0; p < span; p += 1) {
+      out.push({
+        kind: 'pair',
+        left: p < dels - r ? (rows[r + p] ?? null) : null,
+        right: p < adds - dels ? (rows[dels + p] ?? null) : null,
+      });
+    }
+    r = adds;
+  }
+  return out;
+}
+
+/** `text` cut at the marks: `[segment, marked]` in order, covering the text exactly. */
+export function markedSegments(
+  text: string,
+  marks: readonly (readonly [number, number])[] | undefined,
+): readonly (readonly [string, boolean])[] {
+  if (marks === undefined || marks.length === 0) return [[text, false]];
+  const out: [string, boolean][] = [];
+  let at = 0;
+  for (const [from, to] of marks) {
+    if (from > at) out.push([text.slice(at, from), false]);
+    if (to > from) out.push([text.slice(from, to), true]);
+    at = Math.max(at, to);
+  }
+  if (at < text.length) out.push([text.slice(at), false]);
+  return out;
+}
+
+/** True for a changed row whose previous row is not a change: where "Next change" stops. */
+export function startsChange(rows: readonly DiffRow[], index: number): boolean {
+  const kind = rows[index]?.kind;
+  const before = rows[index - 1]?.kind;
+  return (kind === 'add' || kind === 'del') && before !== 'add' && before !== 'del';
+}

package/src/components/drawer-gesture-view.ts

@@ -0,0 +1,33 @@
+// A bottom sheet's drag, as numbers: how far the panel follows the finger, and where it settles
+// on release — `half`, `full`, or closed. Pure, so the browser test and the unit test agree on the
+// thresholds, and the component only moves a custom property.
+
+export type DrawerSnap = 'half' | 'full';
+export type DrawerRelease = DrawerSnap | 'close';
+
+/** Past this share of the sheet's height, a release moves to the next snap. */
+export const SNAP_SHARE = 0.2;
+/** Past this share downwards, a release closes the sheet. */
+export const CLOSE_SHARE = 0.5;
+/** An upward drag past the top snap follows at a third: resistance, not a hard stop. */
+export const OVER_DRAG_RESISTANCE = 3;
+
+/**
+ * The panel's offset for a finger `delta` px below where it went down (negative is up). Down
+ * follows 1:1; up follows at a third, and not at all from `full`, where there is no further snap.
+ */
+export function dragOffset(delta: number, from: DrawerSnap): number {
+  if (!Number.isFinite(delta)) return 0;
+  if (delta >= 0) return delta;
+  return from === 'full' ? 0 : delta / OVER_DRAG_RESISTANCE;
+}
+
+/** Where a sheet `height` px tall, dragged `delta` px from `from`, settles on release. */
+export function releaseSnap(delta: number, height: number, from: DrawerSnap): DrawerRelease {
+  if (!Number.isFinite(delta) || !(height > 0)) return from;
+  const share = delta / height;
+  if (share > CLOSE_SHARE) return 'close';
+  if (from === 'full' && share > SNAP_SHARE) return 'half';
+  if (from === 'half' && share < -SNAP_SHARE) return 'full';
+  return from;
+}

package/src/components/gauge-view.ts

@@ -2,7 +2,9 @@
 // a value fills. `Gauge` takes that share from `meterShare` — one rule for "value of max", so a
 // Gauge and a Meter beside it can never disagree about what 7 of 4 draws.
 
+import { svgNumber } from './chart-frame-view';
 import { annularSector } from './donut-chart-view';
+import type { Tone } from './variants';
 
 /**
  * 200 wide, cropped to 172 tall: the dial's open quarter is at the bottom, and the box ends just
@@ -41,3 +43,30 @@ export function gaugeArcs(share: number): GaugeArcs {
     fill: annularSector(centre, centre, outer, inner, from, end),
   };
 }
+
+/** A target's tick: a radial stroke across the ring at `share`, a little proud of both edges. */
+export function gaugeTick(share: number): string {
+  const { centre, outer, inner } = GAUGE;
+  const angle = gaugeFillEnd(share);
+  const at = (r: number): string =>
+    `${svgNumber(centre + Math.sin(angle) * r)},${svgNumber(centre - Math.cos(angle) * r)}`;
+  return `M${at(inner - 4)} L${at(outer + 4)}`;
+}
+
+export interface GaugeThreshold {
+  /** In the value's own unit: the tone applies from this value up. Ascending. */
+  readonly at: number;
+  readonly tone: Tone;
+}
+
+/** The tone of the highest threshold `value` has reached, or `fallback` below them all. */
+export function thresholdTone(
+  value: number | null,
+  thresholds: readonly GaugeThreshold[] | undefined,
+  fallback: Tone,
+): Tone {
+  if (value === null || !Number.isFinite(value)) return fallback;
+  let tone = fallback;
+  for (const threshold of thresholds ?? []) if (value >= threshold.at) tone = threshold.tone;
+  return tone;
+}

package/src/components/heat-strip-view.ts

@@ -0,0 +1,68 @@
+// The rules of a HeatStrip, apart from its markup: each cell's accessible name (the whole reading,
+// never a colour), its shape per tone — so a cell reads in greyscale and to a colour-blind eye —
+// and the refusal of two cells under one key in a row, which would make two nodes one.
+
+import { renderCauseValue } from '@ultimat3/core';
+import { UI_ERROR_CODES, UiError } from '../errors';
+import type { Tone } from './variants';
+
+export interface HeatCell {
+  /** Unique within its row: a time bucket, a check id. */
+  readonly key: string;
+  /** Already translated, the whole reading: "12:00 — 3 failed of 40". It IS the cell's name. */
+  readonly label: string;
+  /** What the cell means; absent is no data. */
+  readonly tone?: Tone | undefined;
+  /** The page behind the cell: a linked cell is a link, an unlinked one no tab stop. */
+  readonly href?: string | undefined;
+}
+
+export interface HeatRow {
+  /** Already translated: the row's name — a service, a check. */
+  readonly label: string;
+  readonly cells: readonly HeatCell[];
+}
+
+/** A cell's mark: one shape per tone, so meaning never rides on colour alone. */
+export type HeatShape = 'square' | 'circle' | 'triangle' | 'diamond' | 'cross' | 'ring' | 'dash';
+
+export const HEAT_SHAPES: ReadonlyMap<Tone | 'none', HeatShape> = new Map([
+  ['success', 'square'],
+  ['info', 'circle'],
+  ['accent', 'ring'],
+  ['warning', 'triangle'],
+  ['danger', 'cross'],
+  ['neutral', 'diamond'],
+  ['none', 'dash'],
+]);
+
+export interface HeatCellView {
+  readonly key: string;
+  readonly name: string;
+  readonly tone: Tone | 'none';
+  readonly shape: HeatShape;
+  readonly href: string | undefined;
+}
+
+/** A row's cells as drawn, each named `row, reading` so a cell out of context still says whose. */
+export function heatCells(row: HeatRow): readonly HeatCellView[] {
+  const seen = new Set<string>();
+  return row.cells.map((cell) => {
+    if (seen.has(cell.key)) {
+      throw new UiError({
+        code: UI_ERROR_CODES.invalidValue,
+        cause: `<HeatStrip> row ${renderCauseValue(row.label)} has two cells with key ${renderCauseValue(cell.key)}`,
+        fix: 'cells: buckets.map((b) => ({ key: b.at.toISOString(), label, tone }))   # one cell per key in a row',
+      });
+    }
+    seen.add(cell.key);
+    const tone = cell.tone ?? 'none';
+    return {
+      key: cell.key,
+      name: `${row.label}, ${cell.label}`,
+      tone,
+      shape: HEAT_SHAPES.get(tone) ?? 'dash',
+      href: cell.href,
+    };
+  });
+}

package/src/components/json-view-view.ts

@@ -0,0 +1,54 @@
+// Any value to a tree `JsonView` draws as nested `<details>`: keys in the order given, a depth cap,
+// a cycle named rather than followed, and what JSON cannot hold (a bigint, a function) as text.
+// Never throws on content: a webhook body is whatever the sender sent.
+
+export const JSON_VIEW_MAX_DEPTH = 12;
+/** Entries past this many in one object or array fold into a count. */
+export const JSON_VIEW_MAX_ENTRIES = 500;
+
+export type JsonViewNode =
+  | { readonly kind: 'string'; readonly value: string }
+  | { readonly kind: 'number' | 'boolean' | 'null' | 'other'; readonly value: string }
+  | {
+      readonly kind: 'object' | 'array';
+      readonly entries: readonly (readonly [string, JsonViewNode])[];
+      /** Entries left out past `JSON_VIEW_MAX_ENTRIES`. */
+      readonly more: number;
+      readonly size: number;
+    }
+  | { readonly kind: 'deep' | 'circular' };
+
+export function jsonViewTree(
+  value: unknown,
+  depth = 0,
+  seen: Set<object> = new Set(),
+): JsonViewNode {
+  if (value === null || value === undefined) return { kind: 'null', value: 'null' };
+  if (typeof value === 'string') return { kind: 'string', value };
+  if (typeof value === 'number')
+    return { kind: 'number', value: Number.isFinite(value) ? String(value) : 'null' };
+  if (typeof value === 'boolean') return { kind: 'boolean', value: String(value) };
+  if (typeof value !== 'object') return { kind: 'other', value: String(value) };
+  if (value instanceof Date)
+    return {
+      kind: 'string',
+      value: Number.isNaN(value.getTime()) ? 'Invalid Date' : value.toISOString(),
+    };
+  if (seen.has(value)) return { kind: 'circular' };
+  if (depth >= JSON_VIEW_MAX_DEPTH) return { kind: 'deep' };
+  seen.add(value);
+  const array = Array.isArray(value);
+  const pairs: [string, unknown][] = array
+    ? (value as readonly unknown[]).map((item, index) => [String(index), item])
+    : Object.keys(value).map((key) => [key, (value as Record<string, unknown>)[key]]);
+  const entries = pairs
+    .slice(0, JSON_VIEW_MAX_ENTRIES)
+    .map(([key, item]) => [key, jsonViewTree(item, depth + 1, seen)] as const);
+  seen.delete(value);
+  return {
+    kind: array ? 'array' : 'object',
+    entries,
+    more: Math.max(0, pairs.length - JSON_VIEW_MAX_ENTRIES),
+    size: pairs.length,
+  };
+}