@ultimat3/ui 29.4.0 → 30.1.0

package/src/time-range-url.ts

@@ -0,0 +1,200 @@
+// A time window in the URL — a preset id, or a custom `from`/`to` as wall-clock times in an
+// explicit IANA zone — read leniently and written as hrefs. It composes `listUrl`, so "keep every
+// other parameter, drop the cursor" is that module's one rule. Pure: no DOM, no router, no clock.
+
+import { renderCauseValue } from '@ultimat3/core';
+import {
+  assertTimeZone,
+  fromIso,
+  fromZoned,
+  type Instant,
+  instant,
+  isPlainDate,
+  type TimeZone,
+  toZoned,
+} from '@ultimat3/time';
+import { invalidValueError, UI_ERROR_CODES, UiError } from './errors';
+import { listUrl } from './list-url';
+
+/** One window the app offers. The list and its words are the app's; none ships (axiom 8). */
+export interface TimeRangePreset {
+  readonly id: string;
+  /** Already-translated. */
+  readonly label: string;
+  /** A window ending at `now`, this many seconds long. */
+  readonly seconds?: number | undefined;
+  /** A fixed window, as ISO instants with an offset. */
+  readonly from?: string | undefined;
+  readonly to?: string | undefined;
+}
+
+export interface TimeRangeUrlOptions {
+  readonly presets: readonly TimeRangePreset[];
+  /** The preset id shown when the URL names none, or names one that is not valid. */
+  readonly default: string;
+  /** Prefixes every parameter, for two windows on one page. */
+  readonly ns?: string | undefined;
+  /** The zone a custom `from`/`to` is wall-clock time in. Required: there is no ambient one. */
+  readonly timeZone: TimeZone;
+  /** Where a `seconds` preset ends — the caller's clock, read once per request. */
+  readonly now: Date;
+}
+
+export type TimeRangeChange =
+  | { readonly preset: string }
+  | { readonly from: Date; readonly to: Date };
+
+export interface TimeRangeUrl {
+  /** The preset shown; `undefined` for a custom window. */
+  readonly preset: string | undefined;
+  readonly from: Instant;
+  readonly to: Instant;
+  /** The URL asked for a window that is malformed, backwards or unknown, and got the default. */
+  readonly invalid: boolean;
+  /** `from` and `to` as `datetime-local` values in `timeZone`: a custom form's defaults. */
+  readonly local: { readonly from: string; readonly to: string };
+  /** The parameter names, `ns`-prefixed: a GET form's field names. */
+  readonly names: { readonly preset: string; readonly from: string; readonly to: string };
+  /** Every other parameter, cursor dropped: what a GET form must carry as hidden inputs. */
+  readonly hidden: readonly (readonly [string, string])[];
+  /** The URL's path: a GET form's `action`. */
+  readonly action: string;
+  readonly presets: readonly TimeRangePreset[];
+  readonly timeZone: TimeZone;
+  /** The page under `change`, every other parameter kept, every cursor dropped. */
+  href(change: TimeRangeChange): string;
+}
+
+const BASE = 'http://range.invalid';
+const WALL = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2}))?$/;
+
+function invalidPreset(preset: TimeRangePreset, why: string): UiError {
+  return new UiError({
+    code: UI_ERROR_CODES.invalidValue,
+    cause: `timeRangeUrl preset ${renderCauseValue(preset.id)} ${why}`,
+    fix: "presets: [{ id: 'day', label: labels.day, seconds: 86_400 }]   # each preset: seconds > 0, or an ISO from before an ISO to",
+  });
+}
+
+/** A preset's window at `now`. Neither `seconds` nor `from`/`to` is refused at construction. */
+function presetWindow(preset: TimeRangePreset, now: Instant): { from: Instant; to: Instant } {
+  if (preset.seconds !== undefined) {
+    if (!Number.isFinite(preset.seconds) || preset.seconds <= 0) {
+      throw invalidPreset(preset, `has seconds ${String(preset.seconds)}, not a length above 0`);
+    }
+    return { from: instant(new Date(now.getTime() - preset.seconds * 1000)), to: now };
+  }
+  if (preset.from === undefined || preset.to === undefined) {
+    throw invalidPreset(preset, 'has neither seconds nor both from and to');
+  }
+  const from = fromIso(preset.from);
+  const to = fromIso(preset.to);
+  if (to.getTime() <= from.getTime()) throw invalidPreset(preset, 'ends before it starts');
+  return { from, to };
+}
+
+const pad = (value: number): string => String(value).padStart(2, '0');
+
+/** `YYYY-MM-DDTHH:mm` in `zone`: what `<input type="datetime-local">` holds. */
+export function toLocalDateTime(at: Instant, zone: TimeZone): string {
+  const wall = toZoned(at, zone);
+  return `${String(wall.year).padStart(4, '0')}-${pad(wall.month)}-${pad(wall.day)}T${pad(wall.hour)}:${pad(wall.minute)}`;
+}
+
+/** A `datetime-local` value in `zone` as an instant; `undefined` for anything not one. */
+export function fromLocalDateTime(raw: string | null, zone: TimeZone): Instant | undefined {
+  const match = raw === null ? null : WALL.exec(raw);
+  if (match === null) return undefined;
+  const [, year, month, day, rawHour, rawMinute, rawSecond] = match;
+  const hour = Number(rawHour);
+  const minute = Number(rawMinute);
+  const second = rawSecond === undefined ? 0 : Number(rawSecond);
+  if (!isPlainDate(`${String(year)}-${String(month)}-${String(day)}`)) return undefined;
+  if (hour > 23 || minute > 59 || second > 59) return undefined;
+  // A wall time a spring-forward skipped resolves to the instant just after the gap.
+  return fromZoned(
+    { year: Number(year), month: Number(month), day: Number(day), hour, minute, second },
+    zone,
+  );
+}
+
+export function timeRangeUrl(url: URL | string, options: TimeRangeUrlOptions): TimeRangeUrl {
+  const zone = assertTimeZone(options.timeZone);
+  const now = instant(options.now);
+  const presets = new Map<string, TimeRangePreset>();
+  for (const preset of options.presets) {
+    if (presets.has(preset.id)) throw invalidPreset(preset, 'is declared twice');
+    presetWindow(preset, now);
+    presets.set(preset.id, preset);
+  }
+  const fallback = presets.get(options.default);
+  if (fallback === undefined) {
+    throw invalidValueError('timeRangeUrl default', options.default, 'the id of one of presets');
+  }
+  const name = (param: string): string =>
+    options.ns === undefined ? param : `${options.ns}.${param}`;
+  const names = { preset: name('range'), from: name('from'), to: name('to') };
+  const parsed = new URL(url, BASE);
+  const params = parsed.searchParams;
+
+  const rawFrom = params.get(names.from);
+  const rawTo = params.get(names.to);
+  const rawPreset = params.get(names.preset);
+  let preset: string | undefined = fallback.id;
+  let window = presetWindow(fallback, now);
+  let invalid = false;
+  if (rawFrom !== null || rawTo !== null) {
+    const from = fromLocalDateTime(rawFrom, zone);
+    const to = fromLocalDateTime(rawTo, zone);
+    if (from !== undefined && to !== undefined && to.getTime() > from.getTime()) {
+      preset = undefined;
+      window = { from, to };
+    } else invalid = true;
+  } else if (rawPreset !== null) {
+    const named = presets.get(rawPreset);
+    if (named === undefined) invalid = true;
+    else {
+      preset = named.id;
+      window = presetWindow(named, now);
+    }
+  }
+
+  // `listUrl` owns "every other parameter kept, every cursor dropped"; this only adds its own.
+  const base = new URL(listUrl(parsed, { sorts: [], ns: options.ns }).href({}), BASE);
+  for (const param of Object.values(names)) base.searchParams.delete(param);
+  const write = (edit: (next: URLSearchParams) => void): string => {
+    const next = new URLSearchParams(base.searchParams);
+    edit(next);
+    const search = next.toString();
+    return search === '' ? base.pathname : `${base.pathname}?${search}`;
+  };
+
+  return {
+    preset,
+    from: window.from,
+    to: window.to,
+    invalid,
+    local: { from: toLocalDateTime(window.from, zone), to: toLocalDateTime(window.to, zone) },
+    names,
+    hidden: [...base.searchParams.entries()],
+    action: base.pathname,
+    presets: options.presets,
+    timeZone: zone,
+    href: (change) =>
+      write((next) => {
+        if ('preset' in change) {
+          if (!presets.has(change.preset)) {
+            throw invalidValueError(
+              'timeRangeUrl href preset',
+              change.preset,
+              'the id of one of presets',
+            );
+          }
+          if (change.preset !== fallback.id) next.set(names.preset, change.preset);
+          return;
+        }
+        next.set(names.from, toLocalDateTime(instant(change.from), zone));
+        next.set(names.to, toLocalDateTime(instant(change.to), zone));
+      }),
+  };
+}

package/src/tokens/_mixins.scss

@@ -38,7 +38,7 @@
 /// and only takes it out of flow. After a long run of inline text the static position is already
 /// past the viewport edge; the box then escapes the truncating ancestor's `overflow: hidden`,
 /// because that ancestor is not positioned and so is not its containing block, and its right edge
-/// extends the scrollable area. Measured in ai-maxxing: `Link`'s `.hint` ("opens in a new tab")
+/// extends the scrollable area. Measured in one adopter: `Link`'s `.hint` ("opens in a new tab")
 /// after truncated titles put seven boxes at right edges of 753–1119px, making the document 1119px
 /// wide in a 390px viewport and 1480px wide in a 1440px one — a whole page scrolling sideways for
 /// text no sighted user sees.

package/src/tokens/_touch.scss

@@ -1,6 +1,8 @@
 // The touch target: the smallest box a finger can hit reliably. WCAG 2.5.5's 44 CSS px, as rem
 // so a reader's larger text grows the target with it. One rung, in a map so it emits and reads
-// back like every other scale.
+// back like every other scale. `safe-area-inset()` below is the device's unsafe edge, as a length.
+
+@use 'sass:string';
 
 $touch: (
   target: 2.75rem,
@@ -37,3 +39,30 @@ $touch: (
     min-inline-size: touch(target);
   }
 }
+
+/// The device's unsafe edge — the home indicator, a notch, a rounded corner — as a length, `0rem`
+/// where there is none or the page did not opt in (`viewport-fit=cover`). Logical names: the
+/// block edges map to `env()`'s top and bottom; `inline` is the larger side inset, applied to both
+/// inline edges, since `env()` is physical and a notch can sit on either side.
+@function safe-area-inset($edge) {
+  @if $edge == block-start {
+    @return env(safe-area-inset-top, 0rem);
+  }
+  @if $edge == block-end {
+    @return env(safe-area-inset-bottom, 0rem);
+  }
+  @if $edge == inline {
+    @return max(env(safe-area-inset-left, 0rem), env(safe-area-inset-right, 0rem));
+  }
+  @error string.unquote('X_UI_INVALID_VALUE: safe-area-inset("#{$edge}") is not an edge. fix: write safe-area-inset(block-end), safe-area-inset(block-start) or safe-area-inset(inline)');
+}
+
+/// Padding that clears the unsafe edge on top of `$base`: a bottom bar keeps its own padding AND
+/// sits above the home indicator. `$edge` is `block-start`, `block-end` or `inline`.
+@mixin safe-area-padding($edge, $base: 0rem) {
+  @if $edge == inline {
+    padding-inline: calc(#{$base} + #{safe-area-inset(inline)});
+  } @else {
+    padding-#{$edge}: calc(#{$base} + #{safe-area-inset($edge)});
+  }
+}

package/src/tokens/contrast-pairs.ts

@@ -73,4 +73,16 @@ export const CONTRAST_PAIRS: readonly ContrastPair[] = [
   ...CHART_ROLES.flatMap((role) =>
     onSurfaces(role, AA_LARGE, `the ${role} series mark — a bar, line or slice — on a surface`),
   ),
+  // A `tone` replaces the slot colour on a series, a Gauge fill, a HeatStrip cell or a reference
+  // line: the same non-text floor. Text pairs above already hold most of these at 4.5:1; this
+  // names the use, so relaxing a text pairing cannot quietly drop a mark below 3:1.
+  ...(['fg-strong', 'accent', ...STATUS] as const).flatMap((role) =>
+    onSurfaces(role, AA_LARGE, `a ${role}-toned chart mark — series, fill, cell — on a surface`),
+  ),
+  // `TerminalView` writes ANSI magenta and cyan as these two series roles, and it is TEXT on the
+  // code surface (`bg-soft`): 4.5:1, not a mark's 3:1. `chart-6` measured 3.37 there, so cyan is
+  // `chart-1`. Every other code and terminal colour is a role already held as text above.
+  ...(['chart-1', 'chart-5'] as const).map((role) =>
+    pair(role, 'bg-soft', AA_TEXT, `ANSI ${role} terminal text on the code surface`),
+  ),
 ];

package/src/ui-keys.ts

@@ -0,0 +1,126 @@
+// Every string the design system needs but cannot receive as a prop, one export per key — the one
+// list. Read as `UI_KEYS.<name>` (`i18n-keys.ts` imports this module as a namespace), so a bundler
+// keeps exactly the keys an island's components read: an object literal kept all of them.
+
+export const close = 'ui.close';
+export const cancel = 'ui.cancel';
+export const confirm = 'ui.confirm';
+export const dismiss = 'ui.dismiss';
+export const loading = 'ui.loading';
+export const 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`.
+export const error = 'ui.error.title';
+export const retry = 'ui.retry';
+export const next = 'ui.next';
+export const previous = 'ui.previous';
+/** Pagination: back to the first page — the one way back a keyset list has. */
+export const first = 'ui.first';
+export const page = 'ui.page';
+export const sortAscending = 'ui.sort.ascending';
+export const sortDescending = 'ui.sort.descending';
+export const breadcrumb = 'ui.breadcrumb';
+/** AppShell's skip link — the first Tab stop on every page. */
+export const skip = 'ui.skip';
+/** AppShell's sidebar landmark name. */
+export const navigation = 'ui.navigation';
+export const menu = 'ui.menu';
+export const more = 'ui.more';
+export const required = 'ui.required';
+export const optional = 'ui.optional';
+export const theme = 'ui.theme.label';
+export const themeLight = 'ui.theme.light';
+export const themeDark = 'ui.theme.dark';
+export const themeSystem = 'ui.theme.system';
+export const language = 'ui.language';
+/** Combobox: how many suggestions the datalist currently offers. Takes `{ count }`. */
+export const suggestions = 'ui.suggestions';
+/** Combobox: the query matched nothing. */
+export const noResults = 'ui.results.empty';
+/** InfiniteScroll: the label on the next-page control. */
+export const loadMore = 'ui.load.more';
+/** InfiniteScroll: announced when the last page has arrived. */
+export const endOfList = 'ui.load.end';
+/** CopyButton: the control's name before a copy. */
+export const copy = 'ui.copy';
+/** CopyButton: announced, and the control's name, once the write succeeded. */
+export const copied = 'ui.copied';
+export const errorCode = 'ui.error.code';
+export const errorCause = 'ui.error.cause';
+export const errorFix = 'ui.error.fix';
+/** SearchableSelect: the field's text when nothing is chosen, and a required one's refusal. */
+export const selectNone = 'ui.select.none';
+/** SearchableSelect: the list is capped. Takes `{ shown, total }`. */
+export const selectMore = 'ui.select.more';
+/** SearchableSelect: a chip's remove control. Takes `{ label }`. */
+export const selectRemove = 'ui.select.remove';
+/** SearchableSelect: the control that empties a many-valued selection. */
+export const selectClear = 'ui.select.clear';
+/** Charts: a gap — the value is unknown, never zero. The data table's cell and a Gauge's readout. */
+export const chartNone = 'ui.chart.none';
+/** LiveIndicator: the four states of a live view, each one word beside a shape. */
+export const liveLive = 'ui.live.live';
+export const liveReconnecting = 'ui.live.reconnecting';
+export const livePaused = 'ui.live.paused';
+export const liveOffline = 'ui.live.offline';
+/** VirtualList: the one way back for a reader who scrolled up from a list that follows its end. */
+export const listToEnd = 'ui.list.toEnd';
+/** Tree: a node whose children `onExpand` is still fetching. */
+export const treeLoading = 'ui.tree.loading';
+/** DatePicker: the button that opens the calendar beside the native input. */
+export const dateOpen = 'ui.date.open';
+/** Calendar: the month controls. */
+export const datePreviousMonth = 'ui.date.previousMonth';
+export const dateNextMonth = 'ui.date.nextMonth';
+/** DateRangePicker: the button that opens the calendar beside the two inputs. */
+export const rangeOpen = 'ui.range.open';
+/** DateRangePicker/TimeRangePicker: the two ends' labels. */
+export const rangeFrom = 'ui.range.from';
+export const rangeTo = 'ui.range.to';
+/** TimeRangePicker: the custom window's submit. */
+export const rangeApply = 'ui.range.apply';
+/** TimeRangePicker: the disclosure holding the custom window's form. */
+export const rangeCustom = 'ui.range.custom';
+/** TimeRangePicker: the URL's window was malformed or backwards, and the default is shown. */
+export const rangeInvalid = 'ui.range.invalid';
+/** ShortcutSheet: its title, and the legend line of the `?` that opens it. */
+export const shortcuts = 'ui.shortcuts';
+/** Stepper, below `sm`: takes `{ current, total, label }`. */
+export const step = 'ui.step';
+/** PullToRefresh: the hint while pulling, past the threshold, and while the refresh runs. */
+export const refreshPull = 'ui.refresh.pull';
+export const refreshRelease = 'ui.refresh.release';
+export const refreshBusy = 'ui.refresh.busy';
+/** SortableList/Board: the drag handle's name, and the no-script move submit. */
+export const sortHandle = 'ui.sort.handle';
+/** Board, no script: the target column `Select`'s label. */
+export const sortTarget = 'ui.sort.target';
+/** SortableList/Board: announced on lift, each step, the drop and a cancel or refused move. Each takes `{ position, total, group }`. */
+export const sortLift = 'ui.sort.lift';
+export const sortMoved = 'ui.sort.moved';
+export const sortDropped = 'ui.sort.dropped';
+export const sortCancelled = 'ui.sort.cancelled';
+/** SortableList, no script: the two form buttons beside each row. */
+export const sortUp = 'ui.sort.up';
+export const sortDown = 'ui.sort.down';
+/** SplitPane: the separator's name. */
+export const paneResize = 'ui.pane.resize';
+/** CodeBlock: the scroll region's name, and the wrap toggle. */
+export const codeRegion = 'ui.code.region';
+export const codeWrap = 'ui.code.wrap';
+/** TerminalView: the output region's name. */
+export const codeTerminal = 'ui.code.terminal';
+/** DiffView: the region, the spoken gutters, the next-change control and a fold. `folded` takes `{ count }`. */
+export const diffRegion = 'ui.diff.region';
+export const diffAdded = 'ui.diff.added';
+export const diffRemoved = 'ui.diff.removed';
+export const diffNext = 'ui.diff.next';
+export const diffFolded = 'ui.diff.folded';
+/** LogViewer: the region, the text filter, the level filter and its "every level", follow, and a cap. `capped` takes `{ count }`. */
+export const logRegion = 'ui.log.region';
+export const logFilter = 'ui.log.filter';
+export const logLevel = 'ui.log.level';
+export const logAll = 'ui.log.all';
+export const logFollow = 'ui.log.follow';
+export const logCapped = 'ui.log.capped';

package/src/use-hotkeys.ts

@@ -0,0 +1,145 @@
+// The Solid shell over `hotkeys-view.ts`: ONE `keydown` listener per page, whatever number of
+// islands register tables. Every island bundles its own copy of this module, so the listener and
+// the merged table live on the document under one `Symbol.for` key, as `refresh-idle.ts` does.
+
+import {
+  type CompiledHotkeys,
+  compileHotkeys,
+  type HotkeyRow,
+  type HotkeyState,
+  type HotkeyTable,
+  hotkeyAction,
+} from './hotkeys-view';
+import type { Accessor } from './theme/solid-adapter';
+import { solid } from './theme/solid-adapter';
+
+const SLOT: unique symbol = Symbol.for('ultimate.hotkeys');
+
+/** Typing targets: a bare key there is text, never a shortcut. */
+export const EDITABLE_SELECTOR =
+  'input, textarea, select, [contenteditable]:not([contenteditable="false"])';
+
+/** What the slot needs of a document; the tests hand in a fake one. */
+export interface HotkeyHost {
+  addEventListener(type: 'keydown', fn: (event: KeyboardEvent) => void): void;
+}
+
+interface HotkeySlot {
+  readonly tables: HotkeyTable[];
+  compiled: CompiledHotkeys;
+  state: HotkeyState;
+  readonly watchers: Set<() => void>;
+}
+
+type SlotHost = HotkeyHost & { [SLOT]?: HotkeySlot };
+
+const isMac = (): boolean =>
+  typeof navigator !== 'undefined' && /Mac|iPhone|iPad|iPod/.test(navigator.platform);
+
+const editableTarget = (target: EventTarget | null): boolean => {
+  const element = target as { closest?: (selector: string) => unknown } | null;
+  return typeof element?.closest === 'function' && element.closest(EDITABLE_SELECTOR) !== null;
+};
+
+/** The page's one slot over `host`, created — with its one listener — on first use. */
+function slotOf(host: HotkeyHost, mac: boolean): HotkeySlot {
+  const holder = host as SlotHost;
+  const existing = holder[SLOT];
+  if (existing !== undefined) return existing;
+  const slot: HotkeySlot = {
+    tables: [],
+    compiled: compileHotkeys([]),
+    state: { mac, pending: null, since: 0 },
+    watchers: new Set(),
+  };
+  holder[SLOT] = slot;
+  host.addEventListener('keydown', (event) => {
+    const answer = hotkeyAction(
+      {
+        key: event.key,
+        ctrlKey: event.ctrlKey,
+        metaKey: event.metaKey,
+        altKey: event.altKey,
+        isComposing: event.isComposing === true,
+        editable: editableTarget(event.target),
+        at: event.timeStamp,
+      },
+      slot.state,
+      slot.compiled,
+    );
+    slot.state = answer.state;
+    if (answer.row === undefined) return;
+    event.preventDefault();
+    answer.row.run();
+  });
+  return slot;
+}
+
+const notify = (slot: HotkeySlot): void => {
+  for (const watcher of [...slot.watchers]) watcher();
+};
+
+/**
+ * Add a table to the page's merged one; answers the removal. A binding another table already holds
+ * is `X_UI_INVALID_VALUE`, thrown here and the table left out — never two rows for one key.
+ */
+export function registerHotkeys(
+  host: HotkeyHost,
+  table: HotkeyTable,
+  mac: boolean = isMac(),
+): () => void {
+  const slot = slotOf(host, mac);
+  slot.compiled = compileHotkeys([...slot.tables, table].flat());
+  slot.tables.push(table);
+  notify(slot);
+  return (): void => {
+    const at = slot.tables.indexOf(table);
+    if (at === -1) return;
+    slot.tables.splice(at, 1);
+    slot.compiled = compileHotkeys(slot.tables.flat());
+    notify(slot);
+  };
+}
+
+/** Every row registered on the page, in registration order, and whether `mod` is ⌘. */
+export function hotkeyRowsOn(host: HotkeyHost): {
+  readonly rows: readonly HotkeyRow[];
+  readonly mac: boolean;
+} {
+  const slot = (host as SlotHost)[SLOT];
+  return { rows: slot?.tables.flat() ?? [], mac: slot?.state.mac ?? isMac() };
+}
+
+/** Called whenever the merged table changes; answers the unsubscribe. */
+export function watchHotkeys(host: HotkeyHost, fn: () => void, mac: boolean = isMac()): () => void {
+  const slot = slotOf(host, mac);
+  slot.watchers.add(fn);
+  return (): void => {
+    slot.watchers.delete(fn);
+  };
+}
+
+/** Bind `table` for this component's life. Inert on the server: a shortcut needs a keyboard. */
+export function useHotkeys(table: HotkeyTable): void {
+  const rt = solid();
+  rt.createEffect(() => {
+    if (typeof document === 'undefined') return;
+    rt.onCleanup(registerHotkeys(document, table));
+  });
+}
+
+/** The page's merged rows, kept current — what `ShortcutSheet` lists. */
+export function useHotkeyRows(): Accessor<{
+  readonly rows: readonly HotkeyRow[];
+  readonly mac: boolean;
+}> {
+  const rt = solid();
+  const [rows, setRows] = rt.createSignal(hotkeyRowsOn({ addEventListener: () => {} }));
+  rt.createEffect(() => {
+    if (typeof document === 'undefined') return;
+    const read = (): void => setRows(hotkeyRowsOn(document));
+    read();
+    rt.onCleanup(watchHotkeys(document, read));
+  });
+  return rows;
+}