@ultimat3/ui 29.4.0 → 30.1.0

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

@@ -0,0 +1,153 @@
+// The shell every `CommandPalette` caller used to write: the open flag, the query, the active row,
+// `⌘K` (a row of the page's one hotkey table, so `?` lists it) and focus back to the opener on
+// close. The rules stay in `command-palette-view.ts`; this file only holds the state they act on.
+
+import { debounce } from '../debounce';
+import { solid } from '../theme/solid-adapter';
+import { useHotkeys } from '../use-hotkeys';
+import type { CommandPaletteProps } from './CommandPalette';
+import {
+  type CommandPaletteItem,
+  filterItems,
+  keyAction,
+  settleActive,
+  stepActive,
+} from './command-palette-view';
+
+export interface UseCommandPaletteOptions {
+  /** Every item, unfiltered; a function when the list changes over the island's life. */
+  items: readonly CommandPaletteItem[] | (() => readonly CommandPaletteItem[]);
+  /** The chosen item. The palette closes first, so a navigation lands on a closed palette. */
+  onRun: (item: CommandPaletteItem) => void;
+  /** Already-translated legend of the shortcut in `ShortcutSheet` — usually the palette's title. */
+  label: string;
+  /** The binding that toggles it; `mod+k` (⌘K / Ctrl K) when omitted. */
+  hotkey?: string | undefined;
+  /**
+   * Items found for a query, for a list too long to ship: called debounced, and its answer
+   * replaces `items` while the query is non-empty. A slower answer to an older query is dropped.
+   */
+  onQuery?: ((query: string) => Promise<readonly CommandPaletteItem[]>) | undefined;
+  debounceMs?: number | undefined;
+}
+
+/** Everything `CommandPalette` takes except `labels` — spread it: `<CommandPalette {...p.props} />`. */
+export type CommandPaletteState = Omit<CommandPaletteProps, 'labels' | 'class' | 'id'>;
+
+export interface CommandPaletteController {
+  readonly props: CommandPaletteState;
+  readonly show: () => void;
+  readonly hide: () => void;
+}
+
+export function useCommandPalette(options: UseCommandPaletteOptions): CommandPaletteController {
+  const rt = solid();
+  const [open, setOpen] = rt.createSignal(false);
+  const [query, setQuery] = rt.createSignal('');
+  const [activeId, setActiveId] = rt.createSignal<string | undefined>(undefined);
+  const [found, setFound] = rt.createSignal<readonly CommandPaletteItem[]>([]);
+  const [loading, setLoading] = rt.createSignal(false);
+  let opener: HTMLElement | null = null;
+  let asked = 0;
+
+  const all = (): readonly CommandPaletteItem[] =>
+    typeof options.items === 'function' ? options.items() : options.items;
+  const visible = (): readonly CommandPaletteItem[] =>
+    options.onQuery !== undefined && query().trim() !== '' ? found() : filterItems(all(), query());
+  const active = (): string | undefined => settleActive(visible(), activeId());
+
+  const ask = debounce((value: string) => {
+    const onQuery = options.onQuery;
+    if (onQuery === undefined) return;
+    asked += 1;
+    const mine = asked;
+    onQuery(value).then(
+      (items) => {
+        if (mine !== asked) return;
+        setFound(items);
+        setLoading(false);
+      },
+      () => {
+        if (mine !== asked) return;
+        setFound([]);
+        setLoading(false);
+      },
+    );
+  }, options.debounceMs);
+  rt.onCleanup(() => ask.cancel());
+
+  const show = (): void => {
+    if (open()) return;
+    const active = typeof document === 'undefined' ? null : document.activeElement;
+    opener = typeof HTMLElement !== 'undefined' && active instanceof HTMLElement ? active : null;
+    setQuery('');
+    setActiveId(undefined);
+    setOpen(true);
+  };
+  /** Forgets the request waiting or in flight: its answer, when it comes, is stale. */
+  const drop = (): void => {
+    ask.cancel();
+    asked += 1;
+    setLoading(false);
+  };
+  const hide = (): void => {
+    if (!open()) return;
+    setOpen(false);
+    drop();
+    const back = opener;
+    opener = null;
+    back?.focus();
+  };
+  const run = (id: string | undefined): void => {
+    const item = visible().find((candidate) => candidate.id === id);
+    if (item === undefined) return;
+    hide();
+    options.onRun(item);
+  };
+
+  useHotkeys([
+    {
+      keys: [options.hotkey ?? 'mod+k'],
+      label: options.label,
+      run: () => (open() ? hide() : show()),
+    },
+  ]);
+
+  const props: CommandPaletteState = {
+    get open() {
+      return open();
+    },
+    get query() {
+      return query();
+    },
+    get items() {
+      return visible();
+    },
+    get activeId() {
+      return active();
+    },
+    get loading() {
+      return loading();
+    },
+    onQueryInput: (value) => {
+      setQuery(value);
+      if (options.onQuery === undefined) return;
+      if (value.trim() === '') return drop();
+      setLoading(true);
+      ask(value);
+    },
+    onFilterKeyDown: (event) => {
+      const action = keyAction(event.key);
+      if (action === null) return;
+      event.preventDefault();
+      if (action === 'next' || action === 'previous') {
+        setActiveId(stepActive(visible(), active(), action === 'next' ? 1 : -1));
+      } else if (action === 'run') run(active());
+      else hide();
+    },
+    onHoverItem: (id) => setActiveId(id),
+    onRunItem: (id) => run(id),
+    onClose: hide,
+  };
+  return { props, show, hide };
+}

package/src/components/virtual-list-anchor.ts

@@ -0,0 +1,35 @@
+// The reader's place, read off the DOM: the first drawn row still showing at the box's top edge,
+// and how far that edge is into it. The layout's numbers are estimates until a row is measured;
+// the DOM is what the reader sees, so it is what a correction has to hold still.
+
+import type { ScrollAnchor } from './virtual-list-view';
+
+/** The drawn row the box's top edge falls in; `undefined` with no row drawn. */
+export function readDomAnchor(
+  box: HTMLElement,
+  rows: Iterable<HTMLElement>,
+): ScrollAnchor | undefined {
+  const edge = box.getBoundingClientRect().top;
+  let best: { readonly key: string; readonly top: number } | undefined;
+  for (const row of rows) {
+    const rect = row.getBoundingClientRect();
+    const key = row.dataset['key'];
+    if (key === undefined || rect.bottom <= edge) continue;
+    if (best === undefined || rect.top < best.top) best = { key, top: rect.top };
+  }
+  return best === undefined ? undefined : { key: best.key, within: edge - best.top };
+}
+
+/** Where row `key` sits now, relative to the box's top edge; `undefined` when it is not drawn. */
+export function domRowOffset(
+  box: HTMLElement,
+  rows: Iterable<HTMLElement>,
+  key: string,
+): number | undefined {
+  for (const row of rows) {
+    if (row.dataset['key'] === key) {
+      return row.getBoundingClientRect().top - box.getBoundingClientRect().top;
+    }
+  }
+  return undefined;
+}

package/src/components/virtual-list-observer.ts

@@ -0,0 +1,58 @@
+// The one `ResizeObserver` a virtual list holds: its box (the viewport) and every rendered row (by
+// `data-key`), reported as numbers. Its own module so the component stays markup, and so a list
+// that never mounts in a browser — every server render — never constructs one.
+
+export interface VirtualListSizes {
+  /** The box's block size, when it changed. */
+  readonly viewport?: number | undefined;
+  /** Rows whose measured block size changed, by key. */
+  readonly rows: ReadonlyMap<string, number>;
+}
+
+export interface VirtualListObserver {
+  observe(element: Element): void;
+  unobserve(element: Element): void;
+  disconnect(): void;
+}
+
+/** `undefined` where there is no `ResizeObserver`: the estimate then stands for every row. */
+export function createVirtualListObserver(
+  box: Element,
+  report: (sizes: VirtualListSizes) => void,
+): VirtualListObserver | undefined {
+  if (typeof ResizeObserver === 'undefined') return undefined;
+  // Reported a frame later, batched: a report that re-lays the list out from inside the observer's
+  // own callback mounts rows it then has to measure in the same frame, which is the platform's
+  // "ResizeObserver loop completed with undelivered notifications" — an error event per frame.
+  let viewport: number | undefined;
+  let rows = new Map<string, number>();
+  let frame: number | undefined;
+  const flush = (): void => {
+    frame = undefined;
+    const sizes = { viewport, rows };
+    viewport = undefined;
+    rows = new Map();
+    report(sizes);
+  };
+  const observer = new ResizeObserver((entries) => {
+    for (const entry of entries) {
+      if (entry.target === box) {
+        viewport = (entry.target as HTMLElement).clientHeight;
+        continue;
+      }
+      const key = (entry.target as HTMLElement).dataset['key'];
+      const size = entry.borderBoxSize[0]?.blockSize ?? entry.contentRect.height;
+      if (key !== undefined) rows.set(key, size);
+    }
+    frame ??= requestAnimationFrame(flush);
+  });
+  observer.observe(box);
+  return {
+    observe: (element) => observer.observe(element),
+    unobserve: (element) => observer.unobserve(element),
+    disconnect: () => {
+      if (frame !== undefined) cancelAnimationFrame(frame);
+      observer.disconnect();
+    },
+  };
+}

package/src/components/virtual-list-view.ts

@@ -0,0 +1,145 @@
+// The arithmetic of a virtual list, over numbers only: where each row starts, which rows a scroll
+// position shows, where the reader is anchored, and whether they are at the end. No DOM — the
+// component measures and these decide, so every rule here is tested without a browser.
+
+import { renderCauseValue } from '@ultimat3/core';
+import { UI_ERROR_CODES, UiError } from '../errors';
+
+/** Rows rendered before and after the visible ones, so a fast scroll lands on drawn rows. */
+export const VIRTUAL_LIST_OVERSCAN = 4;
+/** The block size of a row nobody has measured yet, in CSS px. */
+export const VIRTUAL_LIST_ESTIMATE = 48;
+/** Within this many px of the end the reader IS at the end... */
+export const AT_END_ENTER_PX = 4;
+/** ...and stays there until scrolled further than this: a measured row cannot unpin them. */
+export const AT_END_LEAVE_PX = 48;
+
+export interface VisibleRange {
+  readonly start: number;
+  /** Exclusive. */
+  readonly end: number;
+}
+
+/** Where the reader is: the first row on screen, and how far into it the box is scrolled. */
+export interface ScrollAnchor {
+  readonly key: string;
+  readonly within: number;
+}
+
+/** Two rows under one key cannot both keep a node. The cause names the key. */
+export function assertUniqueKeys(keys: readonly string[]): void {
+  const seen = new Set<string>();
+  for (const key of keys) {
+    if (seen.has(key)) {
+      throw new UiError({
+        code: UI_ERROR_CODES.invalidValue,
+        cause: `<VirtualList> itemKey answered ${renderCauseValue(key)} for two items, so one row node would have to be both`,
+        fix: 'itemKey: (item) => item.id   # on <VirtualList>: the primary key, unique within items',
+      });
+    }
+    seen.add(key);
+  }
+}
+
+/** Each row's start, plus the total as the last entry: `offsets[i]` is row `i`'s top. */
+export function rowOffsets(heights: readonly number[]): readonly number[] {
+  const offsets = [0];
+  let at = 0;
+  for (const height of heights) {
+    at += height;
+    offsets.push(at);
+  }
+  return offsets;
+}
+
+/** The last row whose top is at or above `position`. */
+function rowAt(offsets: readonly number[], position: number): number {
+  const rows = offsets.length - 1;
+  let low = 0;
+  let high = rows - 1;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if ((offsets[mid] ?? 0) <= position) low = mid;
+    else high = mid - 1;
+  }
+  return Math.max(0, low);
+}
+
+/**
+ * The rows to render. A box with no height (`viewport <= 0`) or one that holds the whole list is
+ * not bounding anything, so it renders EVERY row — never nothing, and never a window of a page
+ * that scrolls itself.
+ */
+export function visibleRange(
+  offsets: readonly number[],
+  scrollTop: number,
+  viewport: number,
+  overscan: number,
+): VisibleRange {
+  const rows = offsets.length - 1;
+  const total = offsets[rows] ?? 0;
+  if (rows <= 0 || viewport <= 0 || viewport >= total) return { start: 0, end: Math.max(0, rows) };
+  const top = Math.min(Math.max(0, scrollTop), total);
+  const first = rowAt(offsets, top);
+  const last = rowAt(offsets, Math.max(top, top + viewport - 1));
+  return {
+    start: Math.max(0, first - overscan),
+    end: Math.min(rows, last + 1 + overscan),
+  };
+}
+
+/** The reader's place, as a key rather than a pixel: pixels move when a row above changes. */
+export function anchorAt(
+  keys: readonly string[],
+  offsets: readonly number[],
+  scrollTop: number,
+): ScrollAnchor | undefined {
+  if (keys.length === 0) return undefined;
+  const index = rowAt(offsets, Math.max(0, scrollTop));
+  const key = keys[index];
+  return key === undefined ? undefined : { key, within: scrollTop - (offsets[index] ?? 0) };
+}
+
+/**
+ * Where to scroll so the anchored row sits exactly where it sat: rows prepended, or measured
+ * taller above it, move it down by their height and the box follows. `undefined` when the row is
+ * gone — then there is no place to keep.
+ */
+export function anchoredScrollTop(
+  anchor: ScrollAnchor,
+  keys: readonly string[],
+  offsets: readonly number[],
+): number | undefined {
+  const index = keys.indexOf(anchor.key);
+  return index === -1 ? undefined : (offsets[index] ?? 0) + anchor.within;
+}
+
+/**
+ * How far to scroll so the anchored row is back where the reader saw it: `offsetNow` is the row's
+ * top relative to the box's edge after the change, and the anchor holds the edge's depth into it
+ * before. Positive scrolls down — a row pushed down by a prepend comes back up.
+ */
+export function anchorCorrection(anchor: ScrollAnchor, offsetNow: number): number {
+  return offsetNow + anchor.within;
+}
+
+/** How far the box's bottom edge is from the list's. */
+export function endDistance(scrollTop: number, viewport: number, total: number): number {
+  return Math.max(0, total - scrollTop - viewport);
+}
+
+/** At the end, with hysteresis: entered close to it, left only well away from it. */
+export function nextAtEnd(wasAtEnd: boolean, distance: number): boolean {
+  return wasAtEnd ? distance <= AT_END_LEAVE_PX : distance <= AT_END_ENTER_PX;
+}
+
+/**
+ * Drops every measured height whose key left the list. A following log mounts and measures each
+ * arriving line, so an unpruned map would hold one entry per line ever shown, for the island's life.
+ */
+export function pruneHeights(
+  heights: Map<string, number>,
+  keep: ReadonlyMap<string, unknown>,
+): void {
+  for (const key of heights.keys()) if (!keep.has(key)) heights.delete(key);
+}

package/src/content/ansi.ts

@@ -0,0 +1,144 @@
+// Terminal output to styled runs, line by line. SGR 30–37 and 90–97 map to semantic roles; 256 and
+// truecolor fall to the default foreground — no raw colour ever leaves here. Every other escape
+// (cursor moves, OSC titles, private modes) and every other control byte is dropped, never printed.
+
+/** The roles a run's colour can name; `TerminalView.module.scss` styles each. */
+export type AnsiRole =
+  | 'muted'
+  | 'danger'
+  | 'success'
+  | 'warning'
+  | 'info'
+  | 'chart-5'
+  | 'chart-1'
+  | 'strong';
+
+export interface AnsiStyle {
+  readonly fg?: AnsiRole | undefined;
+  readonly bold?: boolean | undefined;
+  readonly dim?: boolean | undefined;
+  readonly italic?: boolean | undefined;
+  readonly underline?: boolean | undefined;
+}
+
+export interface AnsiRun extends AnsiStyle {
+  readonly text: string;
+}
+
+export type AnsiLine = readonly AnsiRun[];
+
+/** Black, red, green, yellow, blue, magenta, cyan, white — normal and bright alike. */
+const PALETTE: readonly (AnsiRole | undefined)[] = [
+  'muted',
+  'danger',
+  'success',
+  'warning',
+  'info',
+  'chart-5',
+  'chart-1',
+  'strong',
+];
+
+const ESC = '\u001b';
+/** CSI: parameters, intermediates, one final byte. */
+const CSI = /\[([0-?]*)[ -/]*([@-~])/y;
+
+interface Pen {
+  fg?: AnsiRole | undefined;
+  bold?: boolean | undefined;
+  dim?: boolean | undefined;
+  italic?: boolean | undefined;
+  underline?: boolean | undefined;
+}
+
+/** One SGR sequence applied to the pen. Unknown codes change nothing. */
+function applySgr(pen: Pen, params: string): void {
+  const codes =
+    params === '' ? [0] : params.split(/[;:]/).map((part) => (part === '' ? 0 : Number(part)));
+  for (let i = 0; i < codes.length; i += 1) {
+    const code = codes[i] ?? 0;
+    if (code === 0) {
+      pen.fg = undefined;
+      pen.bold = pen.dim = pen.italic = pen.underline = undefined;
+    } else if (code === 1) pen.bold = true;
+    else if (code === 2) pen.dim = true;
+    else if (code === 3) pen.italic = true;
+    else if (code === 4) pen.underline = true;
+    else if (code === 22) pen.bold = pen.dim = undefined;
+    else if (code === 23) pen.italic = undefined;
+    else if (code === 24) pen.underline = undefined;
+    else if (code >= 30 && code <= 37) pen.fg = PALETTE[code - 30];
+    else if (code >= 90 && code <= 97) pen.fg = PALETTE[code - 90];
+    else if (code === 39) pen.fg = undefined;
+    else if (code === 38 || code === 48) {
+      // 256-colour and truecolor have no semantic role: the default foreground, and skip the args.
+      if (code === 38) pen.fg = undefined;
+      i += codes[i + 1] === 5 ? 2 : codes[i + 1] === 2 ? 4 : 0;
+    }
+  }
+}
+
+const isPrintable = (code: number): boolean =>
+  code === 9 || (code >= 0x20 && code !== 0x7f && (code < 0x80 || code > 0x9f));
+
+/** The lines of `text`, each a list of styled runs. Joined, the runs hold no control byte. */
+export function parseAnsi(text: string): AnsiLine[] {
+  const lines: AnsiLine[] = [];
+  let line: AnsiRun[] = [];
+  let pen: Pen = {};
+  let buf = '';
+  const flush = (): void => {
+    if (buf === '') return;
+    const run: AnsiRun = { text: buf, ...pen };
+    line.push(
+      Object.fromEntries(
+        Object.entries(run).filter(([, value]) => value !== undefined),
+      ) as unknown as AnsiRun,
+    );
+    buf = '';
+  };
+  for (let i = 0; i < text.length; ) {
+    const char = text[i] ?? '';
+    if (char === ESC) {
+      flush();
+      const next = text[i + 1];
+      if (next === '[') {
+        CSI.lastIndex = i + 1;
+        const csi = CSI.exec(text);
+        if (csi === null) {
+          i += 2;
+          continue;
+        }
+        if (csi[2] === 'm') {
+          pen = { ...pen };
+          applySgr(pen, csi[1] ?? '');
+        }
+        i += 1 + csi[0].length;
+      } else if (next === ']' || next === 'P' || next === '_' || next === '^') {
+        // OSC / DCS / APC / PM: a string ended by BEL or ST, swallowed whole.
+        let j = i + 2;
+        while (
+          j < text.length &&
+          text[j] !== '\u0007' &&
+          !(text[j] === ESC && text[j + 1] === '\\')
+        )
+          j += 1;
+        i = text[j] === '\u0007' ? j + 1 : j + 2;
+      } else i += next === undefined ? 1 : 2;
+      continue;
+    }
+    if (char === '\n') {
+      flush();
+      lines.push(line);
+      line = [];
+      i += 1;
+      continue;
+    }
+    const code = char.charCodeAt(0);
+    if (isPrintable(code)) buf += char;
+    i += 1;
+  }
+  flush();
+  if (line.length > 0 || lines.length === 0) lines.push(line);
+  return lines;
+}

package/src/content/heading-slug.ts

@@ -0,0 +1,32 @@
+// Heading anchors as the GitHub wiki writes them, so a `#anchor` link written against the wiki
+// scrolls on a page this package renders: lowercase, punctuation but `-` and `_` dropped, spaces to
+// `-`, and a repeat suffixed `-1`, `-2` in document order.
+
+import { plainText } from './markdown-inline';
+import type { MarkdownBlock } from './markdown-tree';
+
+/** One heading's text as a slug, before de-duplication. */
+export function headingSlug(text: string): string {
+  return text
+    .trim()
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\p{M}\s_-]/gu, '')
+    .replace(/\s/g, '-');
+}
+
+/** Every heading in the tree — quotes and list items included — to its unique id. */
+export function headingIds(blocks: readonly MarkdownBlock[]): Map<MarkdownBlock, string> {
+  const ids = new Map<MarkdownBlock, string>();
+  const seen = new Map<string, number>();
+  const visit = (block: MarkdownBlock): void => {
+    if (block.kind === 'heading') {
+      const base = headingSlug(plainText(block.children));
+      const count = seen.get(base) ?? 0;
+      seen.set(base, count + 1);
+      ids.set(block, count === 0 ? base : `${base}-${count}`);
+    } else if (block.kind === 'quote') block.children.forEach(visit);
+    else if (block.kind === 'list') for (const item of block.items) item.children.forEach(visit);
+  };
+  blocks.forEach(visit);
+  return ids;
+}