@joewinke/jatui 0.26.0 → 0.27.0

package/dist/actions/listNav.js

@@ -61,6 +61,29 @@
  *     if (nav.handleKeydown(e)) return;
  *     // ...page-specific shortcuts
  *   }
+ *
+ * Windowed / virtualised lists (`getOrderedIds` + `revealItem`):
+ *
+ *   A windowed list only renders the rows near the viewport, so a DOM query
+ *   stops j/k at the window edge and `*` misses every unrendered row. Pass
+ *   `getOrderedIds` and the controller navigates over that id list instead;
+ *   the DOM query (or `getItems`) is then only used to find the elements that
+ *   ARE rendered, so the focus/selection classes can be painted on them.
+ *   When the cursor lands on an id with no rendered element, `revealItem(id)`
+ *   is called to scroll it into the window; the focus class is painted once
+ *   the row mounts (same frame if the reveal renders synchronously, otherwise
+ *   on a following animation frame, or on the next `refresh()`).
+ *
+ *   <div use:listNav={{
+ *     getOrderedIds: () => table.orderedRowIds(),
+ *     revealItem: (id) => table.scrollToRow(id),
+ *     onSelect: (el) => openDetail(el.dataset.navId!),
+ *   }}>
+ *     <!-- only the windowed rows, each with data-nav-id -->
+ *   </div>
+ *
+ *   Enter/Space need a rendered element (`onSelect` receives it), so they
+ *   pass through when the focused row has been scrolled out of the window.
  */
 /** How long a half-typed motion (count prefix, pending `g`, pending `z`) waits
  *  for its completion before resetting. Matches Vim's default `timeoutlen`. */
@@ -114,14 +137,12 @@ function wrapIndex(next, length, wrap) {
 }
 /**
  * Estimate how many list items fit in one 'page' of the nearest scrollable
- * ancestor, then halve it. Used for Ctrl+D / Ctrl+U. Returns {@link DEFAULT_HALF_PAGE}
- * when layout isn't available (SSR, jsdom, detached elements).
+ * ancestor, then halve it. Used for Ctrl+D / Ctrl+U. `pivot` is a rendered
+ * item to measure. Returns {@link DEFAULT_HALF_PAGE} when layout isn't
+ * available (SSR, jsdom, detached elements, nothing rendered).
  */
-function getHalfPageSize(items, currentIdx) {
-    if (items.length === 0)
-        return 0;
+function getHalfPageSize(pivot) {
     try {
-        const pivot = items[Math.max(0, Math.min(items.length - 1, currentIdx))] ?? items[0];
         if (!pivot || typeof window === 'undefined')
             return DEFAULT_HALF_PAGE;
         // Walk up looking for an ancestor that is actually scrolling.
@@ -147,9 +168,14 @@ function getHalfPageSize(items, currentIdx) {
     }
     return DEFAULT_HALF_PAGE;
 }
+/** How many animation frames a revealed row gets to mount before the
+ *  controller stops polling for it (a later `refresh()` still paints it). */
+const REVEAL_MAX_FRAMES = 10;
 function makeController(optsRef) {
     let focused = -1;
+    let focusedItemId = null;
     let lastEl = null;
+    let revealTimer = null;
     // Motion-buffer state. A motion is 'pending' until its follow-up key
     // arrives (e.g. the second `g` in `gg`) or the buffer times out.
     let pendingCount = null;
@@ -194,6 +220,57 @@ function makeController(optsRef) {
         const raw = resolver ? resolver(el) : el.dataset.navId;
         return raw == null ? null : String(raw);
     }
+    function resolveList() {
+        const items = resolveItems(optsRef);
+        const getOrderedIds = optsRef.current.getOrderedIds;
+        if (!getOrderedIds) {
+            return {
+                ordered: false,
+                length: items.length,
+                idAt: (i) => getId(items[i] ?? null),
+                el: (i) => items[i] ?? null,
+                indexOfId: (id) => items.findIndex((el) => getId(el) === id),
+                rendered: items,
+            };
+        }
+        const ids = Array.from(getOrderedIds());
+        // Lazily built: a plain j/k on a long list only ever needs one lookup.
+        let byId = null;
+        const renderedById = () => {
+            if (byId)
+                return byId;
+            byId = new Map();
+            for (const el of items) {
+                const id = getId(el);
+                if (id !== null && !byId.has(id))
+                    byId.set(id, el);
+            }
+            return byId;
+        };
+        return {
+            ordered: true,
+            length: ids.length,
+            idAt: (i) => ids[i] ?? null,
+            el: (i) => {
+                const id = ids[i];
+                return id === undefined ? null : (renderedById().get(id) ?? null);
+            },
+            indexOfId: (id) => ids.indexOf(id),
+            rendered: items,
+        };
+    }
+    /** Find the rendered element for `id`, re-querying the DOM. */
+    function findRendered(id) {
+        for (const el of resolveItems(optsRef)) {
+            if (getId(el) === id)
+                return el;
+        }
+        return null;
+    }
+    function cancelReveal() {
+        revealTimer?.cancel();
+        revealTimer = null;
+    }
     function applySelectionClasses(items) {
         const cls = selectedClass();
         for (const el of items) {
@@ -208,25 +285,101 @@ function makeController(optsRef) {
         applySelectionClasses(resolveItems(optsRef));
         optsRef.current.onSelectionChange?.(new Set(selected));
     }
-    function apply(items, idx) {
+    /** Move the focused class onto `next` (no scrolling). */
+    function paint(next) {
         const cls = focusedClass();
-        const next = items[idx] ?? null;
         if (lastEl && lastEl !== next)
             lastEl.classList.remove(cls);
-        if (next) {
+        if (next)
             next.classList.add(cls);
-            next.scrollIntoView?.({ block: 'nearest', inline: 'nearest' });
-        }
         lastEl = next;
-        focused = next ? idx : -1;
-        optsRef.current.onFocusChange?.(next, focused);
+    }
+    /**
+     * Ordered mode: the focused id was revealed but its row has not mounted
+     * yet (the window renders on a later tick). Poll a few frames for it, then
+     * paint it and re-announce the focus with the element.
+     */
+    function awaitReveal(id) {
+        cancelReveal();
+        const raf = typeof requestAnimationFrame !== 'undefined'
+            ? (fn) => {
+                const h = requestAnimationFrame(fn);
+                return () => cancelAnimationFrame(h);
+            }
+            : typeof setTimeout !== 'undefined'
+                ? (fn) => {
+                    const h = setTimeout(fn, 16);
+                    return () => clearTimeout(h);
+                }
+                : null;
+        if (!raf)
+            return;
+        let frames = 0;
+        let cancelFrame = () => { };
+        const tick = () => {
+            if (focusedItemId !== id)
+                return;
+            const el = findRendered(id);
+            if (el) {
+                revealTimer = null;
+                paint(el);
+                applySelectionClasses(resolveItems(optsRef));
+                optsRef.current.onFocusChange?.(el, focused, id);
+                return;
+            }
+            if (++frames >= REVEAL_MAX_FRAMES) {
+                revealTimer = null;
+                return;
+            }
+            cancelFrame = raf(tick);
+        };
+        cancelFrame = raf(tick);
+        revealTimer = { cancel: () => cancelFrame() };
+    }
+    function apply(list, idx) {
+        cancelReveal();
+        const inRange = idx >= 0 && idx < list.length;
+        const id = inRange ? list.idAt(idx) : null;
+        let next = inRange ? list.el(idx) : null;
+        let pendingReveal = false;
+        if (!next && inRange && list.ordered && id !== null) {
+            const reveal = optsRef.current.revealItem;
+            if (reveal) {
+                reveal(id);
+                // A synchronous reveal may already have mounted the row.
+                next = findRendered(id);
+                pendingReveal = next === null;
+            }
+        }
+        paint(next);
+        next?.scrollIntoView?.({ block: 'nearest', inline: 'nearest' });
+        // DOM mode only ever focuses a real element; ordered mode keeps the
+        // cursor on an id even while its row is outside the rendered window.
+        focused = list.ordered ? (inRange ? idx : -1) : next ? idx : -1;
+        focusedItemId = focused >= 0 ? id : null;
+        optsRef.current.onFocusChange?.(next, focused, focusedItemId);
+        if (pendingReveal && id !== null)
+            awaitReveal(id);
+    }
+    /**
+     * Ordered mode: re-derive the cursor's position from its id, since the id
+     * list may have been re-sorted or filtered since the last keypress.
+     */
+    function syncFocus(list) {
+        if (!list.ordered || focused < 0)
+            return;
+        const idx = focusedItemId !== null ? list.indexOfId(focusedItemId) : -1;
+        if (idx >= 0)
+            focused = idx;
+        else if (focused >= list.length)
+            focused = list.length - 1;
     }
     /**
      * Re-derive the selected set from the inclusive range [anchor..focus] while
      * visual mode is active. Items outside the range that were selected before
      * V was pressed are preserved (additive — Vim's `V` extends, doesn't reset).
      */
-    function extendVisualRange(items) {
+    function extendVisualRange(list) {
         if (!visualMode || visualAnchor < 0 || focused < 0)
             return;
         const lo = Math.min(visualAnchor, focused);
@@ -235,7 +388,7 @@ function makeController(optsRef) {
         // existing pre-V selections survive moving the anchor to a new region.
         let mutated = false;
         for (let i = lo; i <= hi; i++) {
-            const id = getId(items[i] ?? null);
+            const id = list.idAt(i);
             if (id !== null && !selected.has(id)) {
                 selected.add(id);
                 mutated = true;
@@ -244,50 +397,73 @@ function makeController(optsRef) {
         if (mutated)
             emitSelectionChange();
         else
-            applySelectionClasses(items);
+            applySelectionClasses(list.rendered);
     }
     function focus(idx) {
-        const items = resolveItems(optsRef);
-        if (items.length === 0)
+        const list = resolveList();
+        if (list.length === 0)
             return;
-        apply(items, Math.max(0, Math.min(items.length - 1, idx)));
+        apply(list, Math.max(0, Math.min(list.length - 1, idx)));
     }
     function focusFirst() {
         focus(0);
     }
     function focusLast() {
-        const items = resolveItems(optsRef);
-        if (items.length)
-            apply(items, items.length - 1);
+        const list = resolveList();
+        if (list.length)
+            apply(list, list.length - 1);
     }
     function clear() {
+        cancelReveal();
         if (lastEl)
             lastEl.classList.remove(focusedClass());
         lastEl = null;
         focused = -1;
+        focusedItemId = null;
         clearPending();
-        optsRef.current.onFocusChange?.(null, -1);
+        optsRef.current.onFocusChange?.(null, -1, null);
     }
     function refresh() {
-        const items = resolveItems(optsRef);
-        if (items.length === 0) {
+        const list = resolveList();
+        if (list.length === 0) {
             clear();
             return;
         }
-        // Re-home the focused element if the old node has been removed.
-        if (lastEl && !items.includes(lastEl)) {
-            const newIdx = Math.min(focused, items.length - 1);
-            apply(items, Math.max(0, newIdx));
+        if (list.ordered) {
+            // Repaint only — never reveal or scroll here: refresh() runs as the
+            // window re-renders during the user's own scrolling, and yanking the
+            // viewport back to the cursor would fight them.
+            const idx = focusedItemId !== null ? list.indexOfId(focusedItemId) : -1;
+            if (idx >= 0) {
+                focused = idx;
+                const el = list.el(idx);
+                if (el !== lastEl) {
+                    paint(el);
+                    if (el) {
+                        cancelReveal();
+                        optsRef.current.onFocusChange?.(el, focused, focusedItemId);
+                    }
+                }
+            }
+            else if (focused >= 0) {
+                // The focused id left the list (filtered out): re-home like DOM mode.
+                apply(list, Math.min(focused, list.length - 1));
+            }
+        }
+        else if (lastEl && !list.rendered.includes(lastEl)) {
+            // Re-home the focused element if the old node has been removed.
+            const newIdx = Math.min(focused, list.length - 1);
+            apply(list, Math.max(0, newIdx));
         }
-        else if (focused >= 0 && focused < items.length) {
-            apply(items, focused);
+        else if (focused >= 0 && focused < list.length) {
+            apply(list, focused);
         }
         // Re-paint selection classes — items may have been re-rendered, so the
         // CSS class needs to be re-applied to the new DOM nodes whose ids match.
-        applySelectionClasses(items);
+        applySelectionClasses(list.rendered);
     }
-    function toggleSelectionByIndex(items, idx) {
-        const id = getId(items[idx] ?? null);
+    function toggleSelectionByIndex(list, idx) {
+        const id = list.idAt(idx);
         if (id === null)
             return;
         if (selected.has(id))
@@ -306,7 +482,8 @@ function makeController(optsRef) {
             return false;
         if (isTypingTarget(e.target))
             return false;
-        const items = resolveItems(optsRef);
+        const list = resolveList();
+        syncFocus(list);
         const wrap = opts.wraparound ?? true;
         const selectable = opts.selectable === true;
         // --- Selection layer (opt-in) ----------------------------------------
@@ -317,7 +494,7 @@ function makeController(optsRef) {
             // selects the focused item; second press exits visual mode while
             // keeping the existing selection (Vim parity for re-entry).
             if (e.key === 'V') {
-                if (items.length === 0)
+                if (list.length === 0)
                     return false;
                 e.preventDefault();
                 if (visualMode) {
@@ -325,13 +502,13 @@ function makeController(optsRef) {
                 }
                 else {
                     if (focused < 0)
-                        apply(items, 0);
+                        apply(list, 0);
                     visualMode = true;
                     visualAnchor = focused;
-                    toggleSelectionByIndex(items, focused);
+                    toggleSelectionByIndex(list, focused);
                     // If the toggle deselected the anchor, re-add it — entering
                     // visual mode should always include the anchor.
-                    const anchorId = getId(items[focused] ?? null);
+                    const anchorId = list.idAt(focused);
                     if (anchorId !== null && !selected.has(anchorId)) {
                         selected.add(anchorId);
                         emitSelectionChange();
@@ -342,21 +519,22 @@ function makeController(optsRef) {
             }
             // x — toggle selection of the focused item (no movement, no visual).
             if (e.key === 'x' && !e.shiftKey) {
-                if (focused < 0 || items.length === 0)
+                if (focused < 0 || list.length === 0)
                     return false;
                 e.preventDefault();
-                toggleSelectionByIndex(items, focused);
+                toggleSelectionByIndex(list, focused);
                 clearPending();
                 return true;
             }
-            // * — toggle select-all of currently visible items.
+            // * — toggle select-all of the list (every id, rendered or not, when
+            // `getOrderedIds` is given; otherwise the rendered items).
             if (e.key === '*') {
-                if (items.length === 0)
+                if (list.length === 0)
                     return false;
                 e.preventDefault();
                 const allIds = [];
-                for (const el of items) {
-                    const id = getId(el);
+                for (let i = 0; i < list.length; i++) {
+                    const id = list.idAt(i);
                     if (id !== null)
                         allIds.push(id);
                 }
@@ -377,17 +555,17 @@ function makeController(optsRef) {
             // Preserves the existing /triage idiom (range-build without entering
             // visual mode). Always wraps within bounds (no wraparound for safety).
             if (e.key === 'J' || e.key === 'K') {
-                if (items.length === 0)
+                if (list.length === 0)
                     return false;
                 e.preventDefault();
                 const dir = e.key === 'J' ? 1 : -1;
-                const before = focused < 0 ? (dir > 0 ? 0 : items.length - 1) : focused;
-                const beforeId = getId(items[before] ?? null);
+                const before = focused < 0 ? (dir > 0 ? 0 : list.length - 1) : focused;
+                const beforeId = list.idAt(before);
                 if (beforeId !== null)
                     selected.add(beforeId);
-                const afterIdx = Math.max(0, Math.min(items.length - 1, before + dir));
-                apply(items, afterIdx);
-                const afterId = getId(items[afterIdx] ?? null);
+                const afterIdx = Math.max(0, Math.min(list.length - 1, before + dir));
+                apply(list, afterIdx);
+                const afterId = list.idAt(afterIdx);
                 if (afterId !== null)
                     selected.add(afterId);
                 emitSelectionChange();
@@ -401,13 +579,16 @@ function makeController(optsRef) {
         if (e.ctrlKey && !e.metaKey && !e.altKey && !e.shiftKey) {
             const lower = e.key.toLowerCase();
             if (lower === 'd' || lower === 'u') {
-                if (items.length === 0)
+                if (list.length === 0)
                     return false;
                 e.preventDefault();
-                const half = getHalfPageSize(items, focused);
+                const pivot = list.el(Math.max(0, Math.min(list.length - 1, focused))) ??
+                    list.rendered[0] ??
+                    null;
+                const half = getHalfPageSize(pivot);
                 const dir = lower === 'd' ? 1 : -1;
-                const start = focused < 0 ? (dir > 0 ? 0 : items.length - 1) : focused;
-                apply(items, wrapIndex(start + dir * half, items.length, wrap));
+                const start = focused < 0 ? (dir > 0 ? 0 : list.length - 1) : focused;
+                apply(list, wrapIndex(start + dir * half, list.length, wrap));
                 clearPending();
                 return true;
             }
@@ -431,16 +612,16 @@ function makeController(optsRef) {
         }
         // gg — jump to first item (or to line {count} when a count is pending).
         if (e.key === 'g' && !e.shiftKey) {
-            if (items.length === 0) {
+            if (list.length === 0) {
                 clearPending();
                 return false;
             }
             e.preventDefault();
             if (pendingG) {
                 const target = pendingCount !== null
-                    ? Math.max(0, Math.min(items.length - 1, pendingCount - 1))
+                    ? Math.max(0, Math.min(list.length - 1, pendingCount - 1))
                     : 0;
-                apply(items, target);
+                apply(list, target);
                 clearPending();
             }
             else {
@@ -452,15 +633,15 @@ function makeController(optsRef) {
         }
         // G — jump to last item (or to line {count}).
         if (e.key === 'G') {
-            if (items.length === 0) {
+            if (list.length === 0) {
                 clearPending();
                 return false;
             }
             e.preventDefault();
             const target = pendingCount !== null
-                ? Math.max(0, Math.min(items.length - 1, pendingCount - 1))
-                : items.length - 1;
-            apply(items, target);
+                ? Math.max(0, Math.min(list.length - 1, pendingCount - 1))
+                : list.length - 1;
+            apply(list, target);
             clearPending();
             return true;
         }
@@ -468,8 +649,13 @@ function makeController(optsRef) {
         if (e.key === 'z' && !e.shiftKey) {
             e.preventDefault();
             if (pendingZ) {
-                const el = lastEl ?? items[focused] ?? null;
-                el?.scrollIntoView?.({ block: 'center', inline: 'nearest' });
+                // Ordered mode: lastEl may be a row the window has since unmounted.
+                const el = list.ordered ? list.el(focused) : (lastEl ?? list.el(focused));
+                if (el)
+                    el.scrollIntoView?.({ block: 'center', inline: 'nearest' });
+                else if (list.ordered && focusedItemId !== null) {
+                    opts.revealItem?.(focusedItemId);
+                }
                 clearPending();
             }
             else {
@@ -482,37 +668,39 @@ function makeController(optsRef) {
         switch (e.key) {
             case 'j':
             case 'ArrowDown': {
-                if (items.length === 0)
+                if (list.length === 0)
                     return false;
                 e.preventDefault();
                 const step = pendingCount ?? 1;
                 // From an unfocused state, `{n}j` selects the n-th item
                 // (1-indexed) so it mirrors `{n}G` from the top.
                 const target = focused < 0 ? step - 1 : focused + step;
-                apply(items, wrapIndex(target, items.length, wrap));
+                apply(list, wrapIndex(target, list.length, wrap));
                 clearPending();
                 if (selectable && visualMode)
-                    extendVisualRange(items);
+                    extendVisualRange(list);
                 return true;
             }
             case 'k':
             case 'ArrowUp': {
-                if (items.length === 0)
+                if (list.length === 0)
                     return false;
                 e.preventDefault();
                 const step = pendingCount ?? 1;
-                const target = focused < 0 ? items.length - step : focused - step;
-                apply(items, wrapIndex(target, items.length, wrap));
+                const target = focused < 0 ? list.length - step : focused - step;
+                apply(list, wrapIndex(target, list.length, wrap));
                 clearPending();
                 if (selectable && visualMode)
-                    extendVisualRange(items);
+                    extendVisualRange(list);
                 return true;
             }
             case 'Enter':
             case ' ': {
                 if (focused < 0)
                     return false;
-                const el = items[focused];
+                // Ordered mode: no element while the focused row is scrolled out of
+                // the window — onSelect needs one, so the key passes through.
+                const el = list.el(focused);
                 if (!el)
                     return false;
                 // Focus honesty (mos-5lzns.59): when real DOM focus sits on a
@@ -573,13 +761,15 @@ function makeController(optsRef) {
         focusLast,
         clear,
         refresh,
+        focusedId: () => focusedItemId,
         selectedIds: () => new Set(selected),
         toggleSelection: (navId) => {
-            const items = resolveItems(optsRef);
             if (navId === undefined) {
                 if (focused < 0)
                     return;
-                toggleSelectionByIndex(items, focused);
+                const list = resolveList();
+                syncFocus(list);
+                toggleSelectionByIndex(list, focused);
                 return;
             }
             if (selected.has(navId))
@@ -602,9 +792,9 @@ function makeController(optsRef) {
             emitSelectionChange();
         },
         selectAll: () => {
-            const items = resolveItems(optsRef);
-            for (const el of items) {
-                const id = getId(el);
+            const list = resolveList();
+            for (let i = 0; i < list.length; i++) {
+                const id = list.idAt(i);
                 if (id !== null)
                     selected.add(id);
             }

package/dist/actions/longpress.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Long-press + right-click Svelte action.
+ *
+ * Opens a context menu on either gesture:
+ *  - Touch: press and hold past `duration` ms without moving more than `moveTolerance`
+ *    px (a drag/scroll cancels it). Fires once; a subsequent scroll/tap is unaffected.
+ *  - Mouse/pen: the native `contextmenu` event (right-click), suppressed so the browser
+ *    menu never shows.
+ *
+ * The callback receives the coordinates of the gesture so the caller can anchor a menu
+ * (though the mobile feed uses a fixed bottom-sheet and ignores them). A light haptic
+ * pulse fires on touch long-press where `navigator.vibrate` is available.
+ *
+ * Deliberately NOT built on lib/actions/swipe.ts: swipe tracks horizontal drags and
+ * commits on release, whereas long-press must fire mid-hold and be cancelled by any
+ * movement. They observe the same touch stream with opposite intent, so a card can use
+ * both — swipe preventDefault only kicks in once a horizontal drag is recognized, which
+ * is exactly the movement that cancels a long-press.
+ */
+export interface LongPressOptions {
+    /** Fires on long-press (touch) or right-click (mouse). */
+    onLongPress?: (detail: {
+        x: number;
+        y: number;
+        source: 'touch' | 'mouse';
+    }) => void;
+    /** Hold time in ms before a touch press counts as a long-press. Default 450. */
+    duration?: number;
+    /** Movement (px) that cancels an in-progress touch long-press. Default 10. */
+    moveTolerance?: number;
+    /** When false, both gestures no-op (listeners stay attached for cheap toggling). */
+    enabled?: boolean;
+}
+export declare function longpress(node: HTMLElement, initial?: LongPressOptions): {
+    update(next: LongPressOptions): void;
+    destroy(): void;
+};