@joewinke/jatui 0.33.0 → 0.34.0

package/CLAUDE.md

@@ -97,6 +97,21 @@ Requires peer `@xyflow/svelte` (install it — the IDE's build breaks on `import
 |-----------|---------|-----------|
 | `GraphCanvas` | Svelte Flow wrapper with the DaisyUI → `--xy-*` theme bridge — read-only status graphs AND node editors. Props mirror `SvelteFlow`'s own names, so xyflow docs apply. Custom `nodeTypes` merge over `{ jatuiNode }` (**keep the object stable** — xyflow re-mounts every node when its identity changes); `edgeTypes`/`defaultEdgeOptions`; editing (`isValidConnection`, `onconnect`, `onbeforedelete`/`ondelete`, `deleteKey`, `snapToGrid`/`snapGrid`, `connectionMode`, key options, `zoomOnDoubleClick`); events forwarded verbatim (`onnodeclick`/`onNodeClick` alias, `onnodecontextmenu`, `onnodedragstart`/`stop`, `onedgeclick`, `onpaneclick`, `onselectionchange`, `onmoveend`). `bind:viewport` stays live even when seeded `undefined`. `children` renders INSIDE `<SvelteFlow>` (Panels, anything calling `useSvelteFlow()`). `bind:this` exposes `api: GraphCanvasApi` (`fitView`, `zoomTo` — centre-anchored, `getZoom`, `setCenter`, `screenToFlowPosition`, `getViewport`; all no-ops before init) plus the same methods (except `fitView`, whose name the prop owns) directly. The no-at-rest-shadow rule strips the node **wrapper** shadow inside `.graph-canvas` only — draw status glows on an inner element. xyflow has no `onnodedoubleclick`: handle `ondblclick` inside the node component. Use `$state.raw` for nodes/edges. | `nodes`/`edges` (bindable), `viewport` (bindable), `nodeTypes?`, `edgeTypes?`, `readonly?`, `fitView?`, `minimap?: boolean \| MiniMapProps`, `background?: false \| BackgroundProps`, `controls?`, `minZoom?`/`maxZoom?`, `children?` |
 
+### Review (also subpath: `jatui/review`)
+
+Item-by-item review surfaces (MOS review-ux, design mos-z8vgx). One `VerdictOption[]` array (`{id, label, tone, key?, opensNote?}`) feeds the buttons, the note and the keys. Root `jatui` exports the components, the keyboard layer, the summary helpers and all types; `jatui/review` adds the zoom/pan math and `TONE_BG`/`TONE_TEXT`. Live: `/showcase/review` (all eight, light + dark).
+
+| Component | Purpose | Key Props |
+|-----------|---------|-----------|
+| `VerdictControl` | Always-labelled verdict row: repeat press is a no-op, explicit Undo, radio arrows + local one-key hotkeys | `options`, `value`, `onVerdict`, `onUndo`, `size?`, `label?`, `hotkeys?` |
+| `ReviewNote` | Optional note that opens + focuses when the verdict changes to an `opensNote` one; Esc returns focus to the `[data-item-id]` card; Saving… / Saved ✓ / Retry from async `onSave`. Exports `NOTE_HINT`. | `value`/`open` (bindable), `verdict`, `options`, `round?`, `onSave?` |
+| `ReviewShortcuts` | `?` help modal whose rows come from the SAME `ReviewKeysOptions` the handler uses (only wired actions show) | `open` (bindable), `config`, `extraRows?`, `footnote?` |
+| `reviewKeys` / `createReviewKeys` | The review keyboard layer over listNav: j/k/gg/G/f move, verdict keys, `u` undo, `n` note, Enter open, `[`/`]` rounds, 1–9 views, `?` help. `global: false` scopes it to the node. | `verdicts`, `onVerdict`, `onUndo`, `onNote`, `onOpen`, `needsYou`, `onHelp`, `global?` |
+| `RoundHistory` | Locked earlier rounds behind "▸ N earlier"; newest first; select a line to read its note; pairs with a version switcher | `rounds`, `verdicts?`, `selected`/`open` (bindable), `onSelect?` |
+| `ReviewProgress` | Segmented progress bar + "3 of 5 decided · …" sentence | `verdicts`, `counts`, `total`, `retest?`, `size?` |
+| `ReviewFilterBar` | All · Needs you · Undecided · per-verdict · Retest chips (from `buildReviewFilters`), optional sort/group menus and Shortcuts button | `filters`, `active` (bindable), `sortOptions?`, `groupOptions?`, `onHelp?` |
+| `MediaZoomLightbox` | Image + video lightbox for judging: wheel/key zoom + drag pan, view → item paging, play/speed/frame-step, `footer` snippet for the verdict | `items: MediaZoomView[]`, `onClose`, `onNextItem?`, `onPrevItem?`, `title?`, `position?`, `footer?`, `fps?` |
+
 ### Media
 
 | Component | Purpose | Key Props |

package/dist/actions/reviewKeys.d.ts

@@ -0,0 +1,159 @@
+/**
+ * reviewKeys — the one keyboard map for "accept, change or reject each item"
+ * review surfaces (mos-z8vgx proposal, "One keyboard map").
+ *
+ * Table-driven: REVIEW_KEY_TABLE is the single definition of every key, what
+ * it does and how it reads in the help modal. The handler dispatches FROM it,
+ * and `reviewKeyRows()` renders the help rows FROM it (ReviewShortcuts), so
+ * the docs can never drift from the behaviour. A surface only wires the
+ * handlers it supports; an unwired action's keys pass through untouched and
+ * its row is left out of the help.
+ *
+ *   j / k, ↓ / ↑, gg / G, counts   next / previous / first / last item (listNav)
+ *   a x r b (from `verdicts`)      cast that verdict on the current item
+ *   u                              undo the current-round verdict
+ *   n                              open / close the note
+ *   e                              edit the proposed text
+ *   Enter                          open big (lightbox / editor / test link)
+ *   [ / ]                          older / newer round
+ *   1–9                            pick a view (only when `onView` is wired —
+ *                                  digits are listNav counts otherwise)
+ *   f                              jump to the next item that needs you
+ *                                  (retest first, then undecided)
+ *   ?                              shortcuts
+ *
+ * Items are elements carrying `data-item-id` (the same hook ReviewNote's Esc
+ * returns focus to). Cards should be `tabindex="0"`: moving with j/k moves
+ * REAL focus onto the card (`domFocus`, default on), and a card focused by
+ * Tab or click becomes the cursor, so the keys always act on what the
+ * reviewer sees as focused.
+ *
+ * Never fires while typing (input/textarea/select/contenteditable), during
+ * IME composition, with Ctrl/Meta/Alt held, or for an event a nested control
+ * already handled (`defaultPrevented` — VerdictControl's own hotkeys).
+ *
+ *   <div use:reviewKeys={{
+ *     verdicts: OPTIONS,
+ *     onVerdict: (id, v) => setVerdict(id, v),
+ *     onUndo: (id) => undo(id),
+ *     onNote: (id) => toggleNote(id),
+ *     onOpen: (id) => openZoom(id),
+ *     needsYou: (id) => (retest.has(id) ? 'retest' : verdicts[id] ? false : 'undecided'),
+ *     onHelp: () => (helpOpen = true),
+ *   }}>
+ *     {#each items as it (it.id)}<article data-item-id={it.id} tabindex="0">…</article>{/each}
+ *   </div>
+ *   <ReviewShortcuts bind:open={helpOpen} config={sameConfig} />
+ */
+import type { Action } from 'svelte/action';
+import { type ListNavController } from './listNav';
+/** Verdict colour; maps to the filled DaisyUI button colour inside VerdictControl. */
+export type VerdictTone = 'success' | 'warning' | 'error' | 'info' | 'neutral';
+/**
+ * One verdict a reviewer can cast. The SAME array feeds VerdictControl (the
+ * buttons), ReviewNote (`opensNote`) and reviewKeys (`key`), so a block
+ * declares its vocabulary once.
+ */
+export interface VerdictOption {
+    id: string;
+    /** Always-visible button label ("Approve", "Needs work", "Fail"…). */
+    label: string;
+    tone: VerdictTone;
+    /**
+     * One-key hotkey. Use the shared slots: `a` positive, `x` changes / fail,
+     * `r` reject, `b` blocked.
+     */
+    key?: string;
+    /** Choosing this verdict opens + focuses the item's note (ReviewNote). */
+    opensNote?: boolean;
+}
+/** The kind of answer `needsYou` gives about an item. */
+export type NeedsYou = 'retest' | 'undecided' | false | null | undefined;
+export type ReviewKeyAction = 'move' | 'verdict' | 'undo' | 'note' | 'edit' | 'open' | 'round' | 'view' | 'needsYou' | 'help';
+export interface ReviewKeyEntry {
+    action: ReviewKeyAction;
+    /** `KeyboardEvent.key` values that trigger it (empty for the verdict slot). */
+    keys: readonly string[];
+    /** Keycaps as shown in the help modal. */
+    display: readonly string[];
+    description: string;
+    /** Help-modal section. */
+    group: 'Move' | 'Decide' | 'Item' | 'Help';
+}
+/**
+ * The key table. Order is help-modal order. The `verdict` row is a slot:
+ * its keys come from the surface's `verdicts[].key`, one help row each.
+ */
+export declare const REVIEW_KEY_TABLE: readonly ReviewKeyEntry[];
+export interface ReviewKeysOptions {
+    /** The surface's verdicts; each one with a `key` becomes a hotkey. */
+    verdicts?: readonly VerdictOption[];
+    onVerdict?: (itemId: string, verdictId: string) => void;
+    onUndo?: (itemId: string) => void;
+    onNote?: (itemId: string) => void;
+    onEdit?: (itemId: string) => void;
+    onOpen?: (itemId: string, el: HTMLElement | null) => void;
+    /** `[` → -1 (older round), `]` → +1 (newer round). */
+    onRound?: (itemId: string, delta: -1 | 1) => void;
+    /** 1–9 → index 0–8. Wiring this claims the digits (no listNav counts). */
+    onView?: (itemId: string, index: number) => void;
+    /** `f` support: does this item need the reviewer, and why? */
+    needsYou?: (itemId: string) => NeedsYou;
+    onHelp?: () => void;
+    /** Fired when the cursor moves (null when cleared). */
+    onFocusChange?: (itemId: string | null, el: HTMLElement | null) => void;
+    /** Escape with nothing half-typed. Default: clear the cursor. */
+    onEscape?: () => void;
+    /** Items in visual order. Action default: `[data-item-id]` under the node. */
+    getItems?: () => HTMLElement[] | ArrayLike<HTMLElement>;
+    itemSelector?: string;
+    /** Default: `el.dataset.itemId`. */
+    getItemId?: (el: HTMLElement) => string | null | undefined;
+    /** Move real DOM focus onto the card as the cursor moves. Default true. */
+    domFocus?: boolean;
+    wraparound?: boolean;
+    focusedClass?: string;
+    /** false → every key no-ops. Default true. */
+    enabled?: boolean;
+    /** Action-only: listen on window (default) or only on the node. */
+    global?: boolean;
+}
+/** One help row, as ReviewShortcuts renders it. */
+export interface ReviewKeyRow {
+    keys: string[];
+    description: string;
+    group: ReviewKeyEntry['group'];
+}
+/**
+ * The help rows for a configuration, straight from REVIEW_KEY_TABLE: only
+ * wired actions, verdict slot expanded to one row per keyed verdict.
+ */
+export declare function reviewKeyRows(o: ReviewKeysOptions): ReviewKeyRow[];
+/** Which table action a key resolves to under this configuration, if any. */
+export declare function resolveReviewKey(key: string, o: ReviewKeysOptions): {
+    action: ReviewKeyAction;
+    verdictId?: string;
+} | null;
+export interface ReviewKeysController {
+    /** True when the event was handled (preventDefault was called). */
+    handleKeydown(e: KeyboardEvent): boolean;
+    /** Id of the current item (focused card, else the j/k cursor). */
+    currentId(): string | null;
+    /** Move the cursor (and focus) to the item with this id. */
+    focusItem(id: string): void;
+    /** `f`: jump to the next item that needs you. False when there is none. */
+    nextNeedsYou(): boolean;
+    /** Re-apply the cursor after the item list changed. */
+    refresh(): void;
+    clear(): void;
+    /** Replace the options (the action's `update`). */
+    update(next: ReviewKeysOptions): void;
+    readonly nav: ListNavController;
+}
+/** Imperative form — use when you already own the keydown listener. */
+export declare function createReviewKeys(options: ReviewKeysOptions): ReviewKeysController;
+/**
+ * Svelte action. Items default to `[data-item-id]` inside the node; listens
+ * on window unless `global: false`.
+ */
+export declare const reviewKeys: Action<HTMLElement, ReviewKeysOptions | undefined>;

package/dist/actions/reviewKeys.js

@@ -0,0 +1,353 @@
+/**
+ * reviewKeys — the one keyboard map for "accept, change or reject each item"
+ * review surfaces (mos-z8vgx proposal, "One keyboard map").
+ *
+ * Table-driven: REVIEW_KEY_TABLE is the single definition of every key, what
+ * it does and how it reads in the help modal. The handler dispatches FROM it,
+ * and `reviewKeyRows()` renders the help rows FROM it (ReviewShortcuts), so
+ * the docs can never drift from the behaviour. A surface only wires the
+ * handlers it supports; an unwired action's keys pass through untouched and
+ * its row is left out of the help.
+ *
+ *   j / k, ↓ / ↑, gg / G, counts   next / previous / first / last item (listNav)
+ *   a x r b (from `verdicts`)      cast that verdict on the current item
+ *   u                              undo the current-round verdict
+ *   n                              open / close the note
+ *   e                              edit the proposed text
+ *   Enter                          open big (lightbox / editor / test link)
+ *   [ / ]                          older / newer round
+ *   1–9                            pick a view (only when `onView` is wired —
+ *                                  digits are listNav counts otherwise)
+ *   f                              jump to the next item that needs you
+ *                                  (retest first, then undecided)
+ *   ?                              shortcuts
+ *
+ * Items are elements carrying `data-item-id` (the same hook ReviewNote's Esc
+ * returns focus to). Cards should be `tabindex="0"`: moving with j/k moves
+ * REAL focus onto the card (`domFocus`, default on), and a card focused by
+ * Tab or click becomes the cursor, so the keys always act on what the
+ * reviewer sees as focused.
+ *
+ * Never fires while typing (input/textarea/select/contenteditable), during
+ * IME composition, with Ctrl/Meta/Alt held, or for an event a nested control
+ * already handled (`defaultPrevented` — VerdictControl's own hotkeys).
+ *
+ *   <div use:reviewKeys={{
+ *     verdicts: OPTIONS,
+ *     onVerdict: (id, v) => setVerdict(id, v),
+ *     onUndo: (id) => undo(id),
+ *     onNote: (id) => toggleNote(id),
+ *     onOpen: (id) => openZoom(id),
+ *     needsYou: (id) => (retest.has(id) ? 'retest' : verdicts[id] ? false : 'undecided'),
+ *     onHelp: () => (helpOpen = true),
+ *   }}>
+ *     {#each items as it (it.id)}<article data-item-id={it.id} tabindex="0">…</article>{/each}
+ *   </div>
+ *   <ReviewShortcuts bind:open={helpOpen} config={sameConfig} />
+ */
+import { createListNav } from './listNav';
+import { isTypingTarget } from '../utils/keyboardShortcutRegistry';
+/**
+ * The key table. Order is help-modal order. The `verdict` row is a slot:
+ * its keys come from the surface's `verdicts[].key`, one help row each.
+ */
+export const REVIEW_KEY_TABLE = [
+    {
+        action: 'move',
+        keys: [],
+        display: ['j', 'k'],
+        description: 'Next / previous item (↓ ↑ too; a number first moves that many)',
+        group: 'Move'
+    },
+    { action: 'move', keys: [], display: ['gg', 'G'], description: 'First / last item', group: 'Move' },
+    { action: 'needsYou', keys: ['f'], display: ['f'], description: 'Next item that needs you (retest first, then undecided)', group: 'Move' },
+    { action: 'verdict', keys: [], display: [], description: '', group: 'Decide' },
+    { action: 'undo', keys: ['u'], display: ['u'], description: 'Undo this round’s verdict (the note stays)', group: 'Decide' },
+    { action: 'note', keys: ['n'], display: ['n'], description: 'Open or close the note', group: 'Decide' },
+    { action: 'edit', keys: ['e'], display: ['e'], description: 'Edit the proposed text', group: 'Item' },
+    { action: 'open', keys: ['Enter'], display: ['Enter'], description: 'Open big', group: 'Item' },
+    { action: 'round', keys: ['[', ']'], display: ['[', ']'], description: 'Older / newer round', group: 'Item' },
+    { action: 'view', keys: ['1', '2', '3', '4', '5', '6', '7', '8', '9'], display: ['1–9'], description: 'Pick a view', group: 'Item' },
+    { action: 'help', keys: ['?'], display: ['?'], description: 'Shortcuts', group: 'Help' }
+];
+/** Is `entry` wired for this configuration? */
+function wired(entry, o) {
+    switch (entry.action) {
+        case 'move':
+            return true;
+        case 'verdict':
+            return !!o.onVerdict;
+        case 'undo':
+            return !!o.onUndo;
+        case 'note':
+            return !!o.onNote;
+        case 'edit':
+            return !!o.onEdit;
+        case 'open':
+            return !!o.onOpen;
+        case 'round':
+            return !!o.onRound;
+        case 'view':
+            return !!o.onView;
+        case 'needsYou':
+            return !!o.needsYou;
+        case 'help':
+            return !!o.onHelp;
+    }
+}
+/**
+ * The help rows for a configuration, straight from REVIEW_KEY_TABLE: only
+ * wired actions, verdict slot expanded to one row per keyed verdict.
+ */
+export function reviewKeyRows(o) {
+    const rows = [];
+    for (const entry of REVIEW_KEY_TABLE) {
+        if (!wired(entry, o))
+            continue;
+        if (entry.action === 'verdict') {
+            for (const v of o.verdicts ?? []) {
+                if (v.key)
+                    rows.push({ keys: [v.key], description: v.label, group: entry.group });
+            }
+            continue;
+        }
+        rows.push({ keys: [...entry.display], description: entry.description, group: entry.group });
+    }
+    return rows;
+}
+/** Which table action a key resolves to under this configuration, if any. */
+export function resolveReviewKey(key, o) {
+    if (o.onVerdict) {
+        const v = o.verdicts?.find((opt) => opt.key === key);
+        if (v)
+            return { action: 'verdict', verdictId: v.id };
+    }
+    for (const entry of REVIEW_KEY_TABLE) {
+        if (entry.action === 'verdict' || entry.action === 'move')
+            continue;
+        if (entry.keys.includes(key) && wired(entry, o))
+            return { action: entry.action };
+    }
+    return null;
+}
+/** Controls that own Enter by real DOM focus (mirrors listNav's focus honesty). */
+const ACTIVATABLE = 'a[href], button, summary, [role="button"], [role="radio"]';
+/** Imperative form — use when you already own the keydown listener. */
+export function createReviewKeys(options) {
+    let opts = options;
+    const itemId = (el) => {
+        const raw = opts.getItemId ? opts.getItemId(el) : el.dataset.itemId;
+        return raw == null ? null : String(raw);
+    };
+    const items = () => {
+        const got = opts.getItems?.() ?? [];
+        return Array.isArray(got) ? got : Array.from(got);
+    };
+    const nav = createListNav({
+        getItems: () => items(),
+        getItemId: (el) => itemId(el),
+        get wraparound() {
+            return opts.wraparound;
+        },
+        get focusedClass() {
+            return opts.focusedClass;
+        },
+        // Escape only reaches listNav's default (clear) when no handler is given.
+        get onEscape() {
+            return opts.onEscape;
+        },
+        onFocusChange: (el, _i, id) => {
+            if (el && opts.domFocus !== false && el !== document.activeElement && !el.contains(document.activeElement)) {
+                el.focus({ preventScroll: true });
+            }
+            opts.onFocusChange?.(id, el);
+        }
+    });
+    /** The item holding real focus, if any. */
+    function focusedCard() {
+        if (typeof document === 'undefined')
+            return null;
+        const active = document.activeElement;
+        if (!(active instanceof HTMLElement))
+            return null;
+        const list = items();
+        return list.find((el) => el === active || el.contains(active)) ?? null;
+    }
+    /** Make the listNav cursor follow real focus (Tab, click, ReviewNote's Esc). */
+    function syncCursor() {
+        const card = focusedCard();
+        if (!card)
+            return;
+        const id = itemId(card);
+        if (id === null || id === nav.focusedId())
+            return;
+        const idx = items().indexOf(card);
+        if (idx >= 0)
+            nav.focus(idx);
+    }
+    function currentId() {
+        const card = focusedCard();
+        if (card)
+            return itemId(card);
+        return nav.focusedId();
+    }
+    function currentEl(id) {
+        return items().find((el) => itemId(el) === id) ?? null;
+    }
+    function focusItem(id) {
+        const idx = items().findIndex((el) => itemId(el) === id);
+        if (idx >= 0)
+            nav.focus(idx);
+    }
+    function nextNeedsYou() {
+        const ask = opts.needsYou;
+        if (!ask)
+            return false;
+        const ids = items()
+            .map(itemId)
+            .filter((x) => x !== null);
+        if (ids.length === 0)
+            return false;
+        const cur = currentId();
+        const start = cur === null ? -1 : ids.indexOf(cur);
+        // Walk once from just after the cursor, wrapping; retest wins over undecided.
+        let firstUndecided = null;
+        for (let step = 1; step <= ids.length; step++) {
+            const id = ids[(start + step + ids.length) % ids.length];
+            const why = ask(id);
+            if (why === 'retest') {
+                focusItem(id);
+                return true;
+            }
+            if (why === 'undecided' && firstUndecided === null)
+                firstUndecided = id;
+        }
+        if (firstUndecided === null)
+            return false;
+        focusItem(firstUndecided);
+        return true;
+    }
+    /**
+     * A table key ends a half-typed listNav motion (`2a` must not leave a
+     * pending count for the next j). listNav drops pending state on any key it
+     * doesn't own, so hand it one.
+     */
+    function dropPendingMotion() {
+        if (typeof KeyboardEvent === 'undefined')
+            return;
+        nav.handleKeydown(new KeyboardEvent('keydown', { key: 'Unidentified' }));
+    }
+    function handleKeydown(e) {
+        if (opts.enabled === false)
+            return false;
+        if (e.defaultPrevented || e.isComposing)
+            return false;
+        if (isTypingTarget(e.target))
+            return false;
+        syncCursor();
+        if (!e.ctrlKey && !e.metaKey && !e.altKey) {
+            const hit = resolveReviewKey(e.key, opts);
+            if (hit) {
+                // `?` and `f` don't need a current item; everything else does.
+                if (hit.action === 'help') {
+                    e.preventDefault();
+                    dropPendingMotion();
+                    opts.onHelp?.();
+                    return true;
+                }
+                if (hit.action === 'needsYou') {
+                    e.preventDefault();
+                    dropPendingMotion();
+                    nextNeedsYou();
+                    return true;
+                }
+                const id = currentId();
+                if (id === null)
+                    return false;
+                if (hit.action === 'open') {
+                    // Focus honesty: Enter on a real control inside the card presses it.
+                    const card = currentEl(id);
+                    if (e.target instanceof HTMLElement && e.target !== card && e.target.matches(ACTIVATABLE))
+                        return false;
+                }
+                e.preventDefault();
+                dropPendingMotion();
+                switch (hit.action) {
+                    case 'verdict':
+                        opts.onVerdict?.(id, hit.verdictId);
+                        break;
+                    case 'undo':
+                        opts.onUndo?.(id);
+                        break;
+                    case 'note':
+                        opts.onNote?.(id);
+                        break;
+                    case 'edit':
+                        opts.onEdit?.(id);
+                        break;
+                    case 'open':
+                        opts.onOpen?.(id, currentEl(id));
+                        break;
+                    case 'round':
+                        opts.onRound?.(id, e.key === '[' ? -1 : 1);
+                        break;
+                    case 'view':
+                        opts.onView?.(id, Number(e.key) - 1);
+                        break;
+                }
+                return true;
+            }
+        }
+        // Enter is the table's `open`; Space keeps its native meaning (scroll /
+        // press) instead of listNav's select.
+        if (e.key === ' ' || e.key === 'Enter')
+            return false;
+        return nav.handleKeydown(e);
+    }
+    return {
+        handleKeydown,
+        currentId,
+        focusItem,
+        nextNeedsYou,
+        refresh: () => nav.refresh(),
+        clear: () => nav.clear(),
+        update(next) {
+            opts = next;
+            nav.refresh();
+        },
+        nav
+    };
+}
+/**
+ * Svelte action. Items default to `[data-item-id]` inside the node; listens
+ * on window unless `global: false`.
+ */
+export const reviewKeys = (node, initial = {}) => {
+    const withItems = (o) => o.getItems
+        ? o
+        : {
+            ...o,
+            getItems: () => Array.from(node.querySelectorAll(o.itemSelector ?? '[data-item-id]'))
+        };
+    let current = initial;
+    const ctl = createReviewKeys(withItems(current));
+    const onKeydown = (e) => ctl.handleKeydown(e);
+    let target = current.global === false ? node : window;
+    target.addEventListener('keydown', onKeydown);
+    return {
+        update(next = {}) {
+            const wasGlobal = current.global !== false;
+            current = next;
+            ctl.update(withItems(next));
+            if (wasGlobal !== (next.global !== false)) {
+                target.removeEventListener('keydown', onKeydown);
+                target = next.global === false ? node : window;
+                target.addEventListener('keydown', onKeydown);
+            }
+        },
+        destroy() {
+            target.removeEventListener('keydown', onKeydown);
+            ctl.clear();
+        }
+    };
+};