@ultimat3/ui 29.3.2 → 30.0.0

package/src/components/searchable-select-view.ts

@@ -0,0 +1,187 @@
+// The rules of a SearchableSelect, apart from its markup: which options a query shows and in what
+// order, where the active row moves on a key, what a pick does to the chosen values, and which
+// option lists are refused. Pure, so the listbox and the no-script `<select>` read one answer.
+
+import { renderCauseValue } from '@ultimat3/core';
+import { UI_ERROR_CODES, UiError } from '../errors';
+import type { RankableOption } from './rank-options';
+import { rankOptions } from './rank-options';
+
+export interface SearchableOption extends RankableOption {
+  /** What the form posts. Unique within `options`. */
+  readonly value: string;
+  /** Already translated: the visible row text and, once picked, the field's text. */
+  readonly label: string;
+  /** A group's name, already translated. A group's options must be adjacent in `options`. */
+  readonly group?: string | undefined;
+  readonly disabled?: boolean | undefined;
+}
+
+/** One rendered row: the option, and the group heading it opens (`undefined` mid-group). */
+export interface SearchableRow {
+  readonly option: SearchableOption;
+  readonly opensGroup: string | undefined;
+}
+
+export interface SearchableView {
+  readonly rows: readonly SearchableRow[];
+  /** Matches before the cap; above `rows.length` the control says "first N of M". */
+  readonly total: number;
+}
+
+function refused(cause: string): UiError {
+  return new UiError({
+    code: UI_ERROR_CODES.invalidValue,
+    cause,
+    fix: 'options: [...loaded, ...chosen.filter((o) => !loaded.some((l) => l.value === o.value))]   # <SearchableSelect>: unique values, each group adjacent, every chosen value among them',
+  });
+}
+
+/**
+ * Refuses an option list the control cannot render honestly: two options under one value (a pick
+ * could post either), a group split in two (two headings with one name), and a chosen value that
+ * names no option — under `onSearch` the caller must keep the chosen options in what it hands back.
+ */
+export function checkOptions(
+  options: readonly SearchableOption[],
+  chosen: readonly string[],
+): void {
+  const values = new Set<string>();
+  const closed = new Set<string>();
+  let open: string | undefined;
+  for (const option of options) {
+    if (values.has(option.value)) {
+      throw refused(
+        `<SearchableSelect> has two options with value ${renderCauseValue(option.value)}`,
+      );
+    }
+    values.add(option.value);
+    if (option.group === open) continue;
+    if (open !== undefined) closed.add(open);
+    if (option.group !== undefined && closed.has(option.group)) {
+      throw refused(
+        `<SearchableSelect> group ${renderCauseValue(option.group)} is split: its options are not adjacent, at value ${renderCauseValue(option.value)}`,
+      );
+    }
+    open = option.group;
+  }
+  for (const value of chosen) {
+    if (!values.has(value)) {
+      throw refused(
+        `<SearchableSelect> value ${renderCauseValue(value)} names no option in options`,
+      );
+    }
+  }
+}
+
+/**
+ * The rows a query shows: ranked, capped, then regathered by group in the order groups first
+ * appear — a ranked list would otherwise open one group three times. Within a group, rank order.
+ */
+export function searchableView(
+  options: readonly SearchableOption[],
+  query: string,
+  limit: number,
+): SearchableView {
+  const ranked = rankOptions(options, query, limit);
+  const order: (string | undefined)[] = [];
+  const byGroup = new Map<string | undefined, SearchableOption[]>();
+  for (const option of ranked.matches) {
+    const bucket = byGroup.get(option.group);
+    if (bucket === undefined) {
+      order.push(option.group);
+      byGroup.set(option.group, [option]);
+    } else bucket.push(option);
+  }
+  const rows = order.flatMap((group) =>
+    (byGroup.get(group) ?? []).map((option, i) => ({
+      option,
+      opensGroup: i === 0 ? group : undefined,
+    })),
+  );
+  return { rows, total: ranked.total };
+}
+
+/** Rows a PageUp / PageDown skips: about one open listbox's height. */
+export const SEARCHABLE_PAGE = 10;
+
+const enabled = (rows: readonly SearchableRow[], index: number): boolean =>
+  rows[index] !== undefined && rows[index]?.option.disabled !== true;
+
+/** The first enabled row at or after `from` walking by `step`; -1 when none, never wrapping. */
+function seek(rows: readonly SearchableRow[], from: number, step: 1 | -1): number {
+  for (let i = from; i >= 0 && i < rows.length; i += step) if (enabled(rows, i)) return i;
+  return -1;
+}
+
+/**
+ * Where the active row goes on `key`, over ENABLED rows only (`roving.ts`'s rule: a disabled row
+ * that can be active pins the walk). Arrows wrap; Home/End and the page keys stop at the ends.
+ * `-1` is no active row; `undefined` is a key this rule does not own.
+ */
+export function stepActive(
+  rows: readonly SearchableRow[],
+  active: number,
+  key: string,
+): number | undefined {
+  const first = seek(rows, 0, 1);
+  const last = seek(rows, rows.length - 1, -1);
+  switch (key) {
+    case 'ArrowDown': {
+      const next = active < 0 ? -1 : seek(rows, active + 1, 1);
+      return next === -1 ? first : next;
+    }
+    case 'ArrowUp': {
+      const next = active < 0 ? -1 : seek(rows, active - 1, -1);
+      return next === -1 ? last : next;
+    }
+    case 'Home':
+      return first;
+    case 'End':
+      return last;
+    case 'PageDown': {
+      const to = seek(rows, Math.min(rows.length - 1, Math.max(0, active) + SEARCHABLE_PAGE), -1);
+      return to <= active ? last : to;
+    }
+    case 'PageUp': {
+      const to = seek(rows, Math.max(0, active - SEARCHABLE_PAGE), 1);
+      return to === -1 || to >= active ? first : to;
+    }
+    default:
+      return undefined;
+  }
+}
+
+/** The row a fresh query lands on: the best enabled match, so Enter picks what the eye sees first. */
+export function firstActive(rows: readonly SearchableRow[]): number {
+  return seek(rows, 0, 1);
+}
+
+/** A pick. One value replaces; under `multiple` a chosen value is removed, a new one appended. */
+export function pickValue(
+  chosen: readonly string[],
+  value: string,
+  multiple: boolean,
+): readonly string[] {
+  if (!multiple) return [value];
+  return chosen.includes(value) ? chosen.filter((v) => v !== value) : [...chosen, value];
+}
+
+/** Backspace on an empty query: the newest chip goes. */
+export function dropLast(chosen: readonly string[]): readonly string[] {
+  return chosen.slice(0, -1);
+}
+
+/** The option behind each chosen value, in chosen order; a value no option names is skipped. */
+export function chosenOptions(
+  options: readonly SearchableOption[],
+  chosen: readonly string[],
+): readonly SearchableOption[] {
+  const byValue = new Map(options.map((option) => [option.value, option] as const));
+  return chosen.flatMap((value) => byValue.get(value) ?? []);
+}
+
+/** A row's element id: derived from the control's own id and the row's index, never its value. */
+export function rowId(base: string, index: number): string {
+  return `${base}-row-${index}`;
+}

package/src/components/slider-view.ts

@@ -0,0 +1,47 @@
+// A slider's numbers: bounds checked, the value snapped onto the step grid and kept in range. Pure,
+// so the refusals — a zero step, a min above max, a non-finite anything — are tested without a DOM.
+
+import { finiteOption } from '@ultimat3/core';
+import { invalidValueError } from '../errors';
+
+export interface SliderNumbers {
+  readonly min: number;
+  readonly max: number;
+  readonly step: number;
+  readonly value: number;
+}
+
+/** Decimal places of `step`, so a snapped `0.1 * 3` reads `0.3`, not `0.30000000000000004`. */
+const decimals = (step: number): number => {
+  const text = String(step);
+  const dot = text.indexOf('.');
+  return dot === -1 ? 0 : text.length - dot - 1;
+};
+
+/**
+ * The slider's numbers, validated. `step` of zero or below, `min` not below `max`, and any
+ * non-finite number are refused naming the prop; `value` is clamped into range and snapped to the
+ * nearest step from `min`, which is what the native control would do with it anyway.
+ */
+export function sliderNumbers(input: {
+  readonly min?: number | undefined;
+  readonly max?: number | undefined;
+  readonly step?: number | undefined;
+  readonly value?: number | undefined;
+}): SliderNumbers {
+  const min = finiteOption('Slider', 'min', input.min ?? 0);
+  const max = finiteOption('Slider', 'max', input.max ?? 100);
+  const step = finiteOption('Slider', 'step', input.step ?? 1);
+  if (step <= 0) throw invalidValueError('Slider step', step, 'a step above 0');
+  if (min >= max)
+    throw invalidValueError(
+      'Slider min',
+      `${String(min)} not below max ${String(max)}`,
+      'a min below max',
+    );
+  const raw = finiteOption('Slider', 'value', input.value ?? min);
+  const clamped = Math.min(max, Math.max(min, raw));
+  const snapped = min + Math.round((clamped - min) / step) * step;
+  const value = Number(Math.min(max, snapped).toFixed(decimals(step)));
+  return { min, max, step, value };
+}

package/src/components/sort-pointer.ts

@@ -0,0 +1,141 @@
+// The DOM half of a reorder: where each group and row is, the pointer gesture bound to a handle,
+// the lifted row following the pointer (input, not animation, so reduced motion keeps it), the
+// edge scroll, and focus handed back to a handle a keyboard move re-parented.
+
+import {
+  autoScroller,
+  bindPointerDrag,
+  browserScrollEnv,
+  type Scrollable,
+} from '../drag/pointer-drag';
+import type { SortController, SortMeasure } from '../drag/sort-controller';
+import type { AxisSpan } from '../drag/sort-view';
+
+export interface SortGeometry extends SortMeasure {
+  root(el: HTMLElement): void;
+  group(id: string, el: HTMLElement): void;
+  row(id: string, el: HTMLElement): void;
+  rowOf(id: string): HTMLElement | undefined;
+  /** Every list in the document now, by group id. */
+  lists(): readonly (readonly [string, HTMLElement])[];
+  handle(id: string, el: HTMLElement): void;
+  refocus(id: string): void;
+  scrollers(): readonly Scrollable[];
+}
+
+const inline = (el: Element): AxisSpan => {
+  const rect = el.getBoundingClientRect();
+  return { start: rect.left, size: rect.width };
+};
+const block = (el: Element): AxisSpan => {
+  const rect = el.getBoundingClientRect();
+  return { start: rect.top, size: rect.height };
+};
+
+/** Registries filled by refs. Groups are read in document order, so a re-render cannot reorder them. */
+export function sortGeometry(): SortGeometry {
+  let root: HTMLElement | undefined;
+  const groups = new Map<string, HTMLElement>();
+  const rows = new Map<string, HTMLElement>();
+  const handles = new Map<string, HTMLElement>();
+  const live = (): HTMLElement[] =>
+    [...groups.values()]
+      .filter((el) => el.isConnected)
+      .sort((a, b) => (a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1));
+  return {
+    root: (el) => {
+      root = el;
+    },
+    group: (id, el) => groups.set(id, el),
+    row: (id, el) => rows.set(id, el),
+    rowOf: (id) => rows.get(id),
+    lists: () => [...groups].filter(([, el]) => el.isConnected),
+    handle: (id, el) => handles.set(id, el),
+    groupBoxes: () => live().map((el) => ({ inline: inline(el), block: block(el) })),
+    itemSpans: (g, without) => {
+      const list = live()[g];
+      if (list === undefined) return [];
+      return [...list.children]
+        .filter((child) => child.getAttribute('data-sort-key') !== without)
+        .map(block);
+    },
+    // A keyboard move re-parents the focused row, and the browser drops focus to <body> with it.
+    refocus: (id) => queueMicrotask(() => handles.get(id)?.focus()),
+    scrollers: () => {
+      const page: Scrollable = {
+        getBoundingClientRect: () => ({ top: 0, bottom: innerHeight, left: 0, right: innerWidth }),
+        scrollBy: (x, y) => scrollBy(x, y),
+      };
+      return root === undefined ? [page] : [page, root];
+    },
+  };
+}
+
+/** Binds one handle; the binding is undone when the row's owner is disposed. */
+export function bindSortRow<T>(
+  rt: { onCleanup(fn: () => void): void },
+  geometry: SortGeometry,
+  controller: SortController<T>,
+  id: string,
+  handle: HTMLElement,
+): void {
+  geometry.handle(id, handle);
+  if (typeof document === 'undefined' || typeof handle.setPointerCapture !== 'function') return;
+  const sort = controller.pointer(id, geometry);
+  let grab = { x: 0, y: 0 };
+  let shift = { x: 0, y: 0 };
+  let scroll: { update(p: { x: number; y: number }): void; stop(): void }[] = [];
+  const place = (row: HTMLElement | undefined, x: number, y: number): void => {
+    if (row === undefined) return;
+    const rect = row.getBoundingClientRect();
+    shift = { x: x - grab.x - (rect.left - shift.x), y: y - grab.y - (rect.top - shift.y) };
+    row.style.setProperty('--drag-x', `${shift.x}px`);
+    row.style.setProperty('--drag-y', `${shift.y}px`);
+  };
+  const settle = (): void => {
+    for (const scroller of scroll) scroller.stop();
+    scroll = [];
+    const row = geometry.rowOf(id);
+    row?.style.removeProperty('--drag-x');
+    row?.style.removeProperty('--drag-y');
+    shift = { x: 0, y: 0 };
+  };
+  const unbind = bindPointerDrag(handle, {
+    start: (origin) => {
+      const rect = geometry.rowOf(id)?.getBoundingClientRect();
+      grab = rect === undefined ? origin : { x: origin.x - rect.left, y: origin.y - rect.top };
+      const env = browserScrollEnv();
+      scroll = geometry.scrollers().map((box) => autoScroller(env, box));
+      sort.start(origin);
+    },
+    move: (point) => {
+      sort.move(point);
+      place(geometry.rowOf(id), point.x, point.y);
+      for (const scroller of scroll) scroller.update(point);
+    },
+    drop: (point) => {
+      settle();
+      sort.drop(point);
+    },
+    cancel: () => {
+      settle();
+      sort.cancel();
+    },
+  });
+  rt.onCleanup(unbind);
+}
+
+/**
+ * `list` holds exactly `rows`, in order, moving nodes that are elsewhere and dropping its own that
+ * are no longer listed. Only ever `insertBefore` and a removal of a child this list still holds.
+ */
+export function placeRows(list: HTMLElement, rows: readonly unknown[]): void {
+  const nodes = rows.filter(
+    (row): row is Node => typeof Node !== 'undefined' && row instanceof Node,
+  );
+  nodes.forEach((node, index) => {
+    const at = list.childNodes[index] ?? null;
+    if (at !== node) list.insertBefore(node, at);
+  });
+  while (list.childNodes.length > nodes.length) list.lastChild?.remove();
+}

package/src/components/sort-surface.tsx

@@ -0,0 +1,231 @@
+// The markup `SortableList` and `Board` share: keyed rows (a live tick beneath a drag keeps every
+// node), a handle button carrying the keyboard and pointer gesture, and — with scripting off — a
+// real form per row. One module, so the two components cannot drift on the gesture.
+
+import type { JSX } from 'solid-js';
+import { announce } from '../a11y';
+import { cx } from '../cx';
+import { type SortController, type SortSpeech, sortController } from '../drag/sort-controller';
+import { type CanDrop, type SortGroup, type SortMove, sortPositions } from '../drag/sort-view';
+import { UI_KEYS } from '../i18n-keys';
+import { iconGripVertical } from '../icons/glyphs/grip-vertical';
+import { useUi } from '../theme/context';
+import { solid } from '../theme/solid-adapter';
+import boardStyles from './Board.module.scss';
+import { keyedRows } from './data-table-rows';
+import { Icon } from './Icon';
+import styles from './SortableList.module.scss';
+import { bindSortRow, placeRows, type SortGeometry, sortGeometry } from './sort-pointer';
+
+/** The form field names the no-script controls post. `null` leaves that field out. */
+export interface SortFields {
+  readonly id?: string | undefined;
+  readonly fromGroup?: string | null | undefined;
+  readonly toGroup?: string | null | undefined;
+  readonly toIndex?: string | null | undefined;
+}
+
+export interface SortSurfaceGroup<T> extends SortGroup<T> {
+  readonly label: string;
+}
+
+export interface SortSurfaceInput<T> {
+  readonly groups: () => readonly SortSurfaceGroup<T>[];
+  readonly itemKey: (item: T) => string;
+  readonly renderItem: (item: T) => JSX.Element;
+  readonly onMove: (move: SortMove) => unknown;
+  readonly canDrop?: CanDrop<T> | undefined;
+  readonly action?: string | undefined;
+  readonly fields?: SortFields | undefined;
+  readonly layout: 'list' | 'board';
+  readonly label: string;
+  readonly class?: string | undefined;
+}
+
+const SPEECH = new Map<SortSpeech, string>([
+  ['lift', UI_KEYS.sortLift],
+  ['moved', UI_KEYS.sortMoved],
+  ['dropped', UI_KEYS.sortDropped],
+  ['cancelled', UI_KEYS.sortCancelled],
+]);
+
+const field = (name: string | null | undefined, fallback: string): string | null =>
+  name === undefined ? fallback : name;
+
+export function sortSurface<T>(input: SortSurfaceInput<T>): JSX.Element {
+  const ui = useUi();
+  const rt = solid();
+  const [enhanced, setEnhanced] = rt.createSignal(false);
+  // Effects never run on the server, so the no-script form is what the document carries.
+  rt.createEffect(() => setEnhanced(true));
+  const labelOf = (id: string): string =>
+    input.groups().find((group) => group.id === id)?.label ?? id;
+  const controller: SortController<T> = sortController(rt, {
+    groups: input.groups,
+    itemKey: input.itemKey,
+    onMove: input.onMove,
+    canDrop: input.canDrop,
+    dir: () => ui.dir,
+    groupLabel: labelOf,
+    say: (what, params) => announce(ui.t(SPEECH.get(what) ?? UI_KEYS.sortMoved, params)),
+  });
+  const geometry: SortGeometry = sortGeometry();
+  const names = input.fields ?? {};
+
+  const hidden = (name: string | null, value: string): JSX.Element =>
+    name === null ? null : <input type="hidden" name={name} value={value} />;
+
+  /** The no-script move: Up and Down in a list, a target column in a board. */
+  const fallback = (item: T, id: string): JSX.Element => {
+    if (input.action === undefined) return null;
+    const groups = input.groups();
+    const g = groups.findIndex((group) => group.items.includes(item));
+    const group = groups[g];
+    if (group === undefined) return null;
+    const index = group.items.indexOf(item);
+    const targets = groups.filter(
+      (target) => target.id === group.id || input.canDrop?.(item, target.id) !== false,
+    );
+    // A card no other column accepts has no move to offer.
+    if (input.layout === 'board' && targets.length < 2) return null;
+    const toIndex = field(names.toIndex, 'toIndex');
+    return (
+      <form method="post" action={input.action} class={styles['fallback']}>
+        {hidden(field(names.id, 'id') ?? 'id', id)}
+        {hidden(field(names.fromGroup, 'fromGroup'), group.id)}
+        {input.layout === 'list' ? (
+          <>
+            {hidden(field(names.toGroup, 'toGroup'), group.id)}
+            <button
+              type="submit"
+              name={toIndex ?? undefined}
+              value={String(index - 1)}
+              disabled={index === 0}
+            >
+              {ui.t(UI_KEYS.sortUp)}
+            </button>
+            <button
+              type="submit"
+              name={toIndex ?? undefined}
+              value={String(index + 1)}
+              disabled={index === group.items.length - 1}
+            >
+              {ui.t(UI_KEYS.sortDown)}
+            </button>
+          </>
+        ) : (
+          <>
+            <select
+              name={field(names.toGroup, 'toGroup') ?? undefined}
+              aria-label={ui.t(UI_KEYS.sortTarget)}
+            >
+              {targets.map((target) => (
+                <option value={target.id} selected={target.id === group.id}>
+                  {target.label}
+                </option>
+              ))}
+            </select>
+            <button type="submit">{ui.t(UI_KEYS.sortHandle)}</button>
+          </>
+        )}
+      </form>
+    );
+  };
+
+  const rows = keyedRows<T, JSX.Element>(rt, input.itemKey, (row, id) => (
+    <li
+      class={styles['row']}
+      data-sort-key={id}
+      data-lifted={controller.lifted() === id ? 'true' : undefined}
+      ref={(el: HTMLLIElement) => geometry.row(id, el)}
+    >
+      <button
+        type="button"
+        class={styles['handle']}
+        aria-label={ui.t(UI_KEYS.sortHandle)}
+        aria-pressed={controller.lifted() === id ? 'true' : 'false'}
+        data-sort-handle={id}
+        ref={(el: HTMLButtonElement) => bindSortRow(rt, geometry, controller, id, el)}
+        onKeyDown={(event: KeyboardEvent) => {
+          if (!controller.key(id, event)) return;
+          event.preventDefault();
+          geometry.refocus(id);
+        }}
+        onFocusOut={(event: FocusEvent) => {
+          if (event.relatedTarget !== null) controller.leave(id);
+        }}
+      >
+        <Icon glyph={iconGripVertical} size="sm" />
+      </button>
+      <div class={styles['body']}>{input.renderItem(row())}</div>
+      {fallback(row(), id)}
+    </li>
+  ));
+
+  // One memo: every column reads its slice of ONE keyed pass, so a card crossing columns keeps
+  // its node. Keys are checked across every group first, naming the duplicate as the surface's.
+  const groupNodes = rt.createMemo((): Map<string, JSX.Element[]> => {
+    const view = controller.view();
+    sortPositions(view, input.itemKey);
+    const all = rows(view.flatMap((group) => group.items));
+    const out = new Map<string, JSX.Element[]>();
+    let at = 0;
+    for (const group of view) {
+      out.set(group.id, all.slice(at, at + group.items.length));
+      at += group.items.length;
+    }
+    return out;
+  });
+
+  // Built once per group: a lift re-orders the rows INSIDE a list and never replaces the list,
+  // so the lifted row's handle keeps its place in the document and a live tick touches nothing.
+  const list = (id: string, label: () => string | undefined): JSX.Element => (
+    <ul
+      class={styles['list']}
+      aria-label={label()}
+      ref={(el: HTMLUListElement) => geometry.group(id, el)}
+    >
+      {typeof document === 'undefined' ? (groupNodes().get(id) ?? []) : null}
+    </ul>
+  );
+
+  // In a browser ONE effect places every row in every list. Solid's own reconcile, run per list,
+  // removes a row it no longer lists with `node.remove()` — and when the destination list ran
+  // first, that detached the card it had just received. One pass only ever moves a node. A server
+  // render has no effects and writes the rows as children above.
+  rt.createEffect(() => {
+    const nodes = groupNodes();
+    for (const [id, list] of geometry.lists()) placeRows(list, nodes.get(id) ?? []);
+  });
+
+  const columns = keyedRows<SortSurfaceGroup<T>, JSX.Element>(
+    rt,
+    (group) => group.id,
+    (group, id) => (
+      // biome-ignore lint/a11y/useSemanticElements: a column is a group of the board, not a form's fieldset
+      <section class={boardStyles['column']} role="group" aria-label={group().label}>
+        <p class={boardStyles['columnLabel']} aria-hidden="true">
+          {group().label}
+        </p>
+        {list(id, () => group().label)}
+      </section>
+    ),
+  );
+  // A list's one group id, read once: a list never becomes another list.
+  const single =
+    input.layout === 'list' ? list(input.groups()[0]?.id ?? '', () => undefined) : null;
+
+  return (
+    // biome-ignore lint/a11y/useSemanticElements: the list or board as one named group, not a form's fieldset
+    <div
+      class={cx(styles['root'], input.layout === 'board' && boardStyles['board'], input.class)}
+      data-enhanced={enhanced() ? 'true' : undefined}
+      data-dragging={controller.lifted() === null ? undefined : 'true'}
+      role="group"
+      aria-label={input.label}
+      ref={(el: HTMLDivElement) => geometry.root(el)}
+    >
+      {single ?? columns(input.groups())}
+    </div>
+  );
+}