@joewinke/jatui 0.25.0 → 0.27.0

package/dist/actions/longpress.js

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+const DEFAULTS = {
+    duration: 450,
+    moveTolerance: 10,
+    enabled: true
+};
+export function longpress(node, initial = {}) {
+    let opts = { ...DEFAULTS, ...initial };
+    let timer = null;
+    let startX = 0;
+    let startY = 0;
+    let fired = false;
+    function clearTimer() {
+        if (timer) {
+            clearTimeout(timer);
+            timer = null;
+        }
+    }
+    function onTouchStart(e) {
+        if (!opts.enabled || e.touches.length !== 1)
+            return;
+        const t = e.touches[0];
+        startX = t.clientX;
+        startY = t.clientY;
+        fired = false;
+        clearTimer();
+        timer = setTimeout(() => {
+            timer = null;
+            fired = true;
+            // Haptic nudge where supported (Android Chrome, some others). No-op on iOS.
+            try {
+                navigator.vibrate?.(15);
+            }
+            catch {
+                /* ignore */
+            }
+            opts.onLongPress?.({ x: startX, y: startY, source: 'touch' });
+        }, opts.duration);
+    }
+    function onTouchMove(e) {
+        if (!timer)
+            return;
+        const t = e.touches[0];
+        if (Math.abs(t.clientX - startX) > opts.moveTolerance ||
+            Math.abs(t.clientY - startY) > opts.moveTolerance) {
+            clearTimer();
+        }
+    }
+    function onTouchEnd() {
+        clearTimer();
+    }
+    function onContextMenu(e) {
+        if (!opts.enabled)
+            return;
+        e.preventDefault();
+        opts.onLongPress?.({ x: e.clientX, y: e.clientY, source: 'mouse' });
+    }
+    // If a long-press fired, swallow the click that a touchend would otherwise
+    // synthesize so the card's own onclick (e.g. collapse toggle) doesn't also run.
+    function onClickCapture(e) {
+        if (fired) {
+            fired = false;
+            e.stopPropagation();
+            e.preventDefault();
+        }
+    }
+    node.addEventListener('touchstart', onTouchStart, { passive: true });
+    node.addEventListener('touchmove', onTouchMove, { passive: true });
+    node.addEventListener('touchend', onTouchEnd);
+    node.addEventListener('touchcancel', onTouchEnd);
+    node.addEventListener('contextmenu', onContextMenu);
+    node.addEventListener('click', onClickCapture, { capture: true });
+    return {
+        update(next) {
+            opts = { ...DEFAULTS, ...next };
+        },
+        destroy() {
+            clearTimer();
+            node.removeEventListener('touchstart', onTouchStart);
+            node.removeEventListener('touchmove', onTouchMove);
+            node.removeEventListener('touchend', onTouchEnd);
+            node.removeEventListener('touchcancel', onTouchEnd);
+            node.removeEventListener('contextmenu', onContextMenu);
+            node.removeEventListener('click', onClickCapture, { capture: true });
+        }
+    };
+}

package/dist/actions/stickToBottom.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Reader-aware auto-scroll for streaming transcripts (chat, agent sessions,
+ * live transcription, message threads).
+ *
+ * The problem this solves: a naive `el.scrollTop = el.scrollHeight` fired on
+ * every streamed token/message yanks a reader who has scrolled up to re-read
+ * back to the bottom. This controller only follows the live edge **while the
+ * reader is already at it**, treats upward scroll/wheel/keyboard/selection as
+ * intent to stop following, coalesces per-frame stick requests into a single
+ * rAF scroll, and surfaces an unread count so a "Jump to latest" affordance can
+ * appear when content arrives off-screen.
+ *
+ * Implements shadcn's streaming-chat principles 1, 2, 3, 7, 8, 9 (never move the
+ * reader against their intent; follow only at the edge; jump-to-latest with an
+ * unread count; reduced-motion safe). Ported from JST (jst-91rqu) — JAT shares
+ * the exact Svelte 5 stack.
+ *
+ * Usage (Svelte 5):
+ *   <script lang="ts">
+ *     import { createStickToBottom, type StickState, JumpToLatest } from "../../../dist"
+ *     let stick = $state<StickState>({ atBottom: true, pinnedUp: false, unread: 0 })
+ *     const scroller = createStickToBottom({ onState: (s) => (stick = s) })
+ *   </script>
+ *
+ *   <div class="relative ...">
+ *     <div bind:this={el} use:scroller.action class="overflow-y-auto ...">…</div>
+ *     <JumpToLatest
+ *       visible={!stick.atBottom}
+ *       unreadCount={stick.unread}
+ *       onclick={scroller.jumpToLatest}
+ *     />
+ *   </div>
+ *
+ * Then replace every imperative `scrollToBottom()` / inline
+ * `el.scrollTop = el.scrollHeight` with `scroller.requestStick()` (gated), or
+ * `scroller.requestStick(true)` to force (e.g. the reader's own send, or an
+ * error that must come into view).
+ */
+export interface StickState {
+    /** Reader is within `threshold` px of the live edge. */
+    atBottom: boolean;
+    /** Reader deliberately scrolled up — auto-follow is suspended. */
+    pinnedUp: boolean;
+    /** Stick requests suppressed since the reader last sat at the edge. */
+    unread: number;
+}
+export interface StickToBottomOptions {
+    /** px from the bottom still considered "at the edge". Default 100. */
+    threshold?: number;
+    /** Called whenever {@link StickState} changes. Wire into host `$state`. */
+    onState?: (state: StickState) => void;
+}
+export interface StickController {
+    /** `use:scroller.action` on the scrollable element. */
+    action: (node: HTMLElement) => {
+        destroy(): void;
+    };
+    /**
+     * Request a follow-to-bottom. No-op (increments `unread`) when the reader has
+     * scrolled away, unless `force` is true.
+     */
+    requestStick: (force?: boolean) => void;
+    /** Force to the live edge and resume following (the "Jump to latest" action). */
+    jumpToLatest: () => void;
+}
+export declare function createStickToBottom(options?: StickToBottomOptions): StickController;

package/dist/actions/stickToBottom.js

@@ -0,0 +1,155 @@
+/**
+ * Reader-aware auto-scroll for streaming transcripts (chat, agent sessions,
+ * live transcription, message threads).
+ *
+ * The problem this solves: a naive `el.scrollTop = el.scrollHeight` fired on
+ * every streamed token/message yanks a reader who has scrolled up to re-read
+ * back to the bottom. This controller only follows the live edge **while the
+ * reader is already at it**, treats upward scroll/wheel/keyboard/selection as
+ * intent to stop following, coalesces per-frame stick requests into a single
+ * rAF scroll, and surfaces an unread count so a "Jump to latest" affordance can
+ * appear when content arrives off-screen.
+ *
+ * Implements shadcn's streaming-chat principles 1, 2, 3, 7, 8, 9 (never move the
+ * reader against their intent; follow only at the edge; jump-to-latest with an
+ * unread count; reduced-motion safe). Ported from JST (jst-91rqu) — JAT shares
+ * the exact Svelte 5 stack.
+ *
+ * Usage (Svelte 5):
+ *   <script lang="ts">
+ *     import { createStickToBottom, type StickState, JumpToLatest } from "../../../dist"
+ *     let stick = $state<StickState>({ atBottom: true, pinnedUp: false, unread: 0 })
+ *     const scroller = createStickToBottom({ onState: (s) => (stick = s) })
+ *   </script>
+ *
+ *   <div class="relative ...">
+ *     <div bind:this={el} use:scroller.action class="overflow-y-auto ...">…</div>
+ *     <JumpToLatest
+ *       visible={!stick.atBottom}
+ *       unreadCount={stick.unread}
+ *       onclick={scroller.jumpToLatest}
+ *     />
+ *   </div>
+ *
+ * Then replace every imperative `scrollToBottom()` / inline
+ * `el.scrollTop = el.scrollHeight` with `scroller.requestStick()` (gated), or
+ * `scroller.requestStick(true)` to force (e.g. the reader's own send, or an
+ * error that must come into view).
+ */
+const REDUCED_MOTION = typeof window !== 'undefined' &&
+    window.matchMedia?.('(prefers-reduced-motion: reduce)').matches;
+export function createStickToBottom(options = {}) {
+    const threshold = options.threshold ?? 100;
+    const emit = options.onState;
+    let el = null;
+    let atBottom = true;
+    let pinnedUp = false;
+    let unread = 0;
+    let rafId = 0;
+    function publish() {
+        emit?.({ atBottom, pinnedUp, unread });
+    }
+    function computeAtBottom() {
+        if (!el)
+            return true;
+        return el.scrollTop + el.clientHeight >= el.scrollHeight - threshold;
+    }
+    function scrollNow() {
+        if (!el)
+            return;
+        el.scrollTop = el.scrollHeight;
+        atBottom = true;
+        pinnedUp = false;
+        unread = 0;
+    }
+    function scheduleStick() {
+        if (REDUCED_MOTION || typeof requestAnimationFrame !== 'function') {
+            scrollNow();
+            publish();
+            return;
+        }
+        if (rafId)
+            return;
+        rafId = requestAnimationFrame(() => {
+            rafId = 0;
+            scrollNow();
+            publish();
+        });
+    }
+    function requestStick(force = false) {
+        const at = computeAtBottom();
+        if (force || (at && !pinnedUp)) {
+            scheduleStick();
+            return;
+        }
+        // Reader is up the thread — leave them, but count the new arrival.
+        // New content just grew the scroll height, so the reader is now further from
+        // the edge than they were: re-publish `atBottom` so a "Jump to latest"
+        // affordance appears IMMEDIATELY on arrival, without waiting for a scroll
+        // event to recompute it (jat-93n6r.11 — the pill used to only show after the
+        // reader manually scrolled).
+        if (atBottom !== at)
+            atBottom = at;
+        unread += 1;
+        publish();
+    }
+    function jumpToLatest() {
+        pinnedUp = false;
+        scheduleStick();
+    }
+    function onScroll() {
+        const at = computeAtBottom();
+        if (at === atBottom && !at)
+            return;
+        atBottom = at;
+        if (at) {
+            pinnedUp = false;
+            unread = 0;
+        }
+        publish();
+    }
+    function markIntentUp() {
+        // Only treat upward intent as "stop following" if not already at the edge.
+        if (!computeAtBottom() && !pinnedUp) {
+            pinnedUp = true;
+            publish();
+        }
+    }
+    function onWheel(e) {
+        if (e.deltaY < 0)
+            markIntentUp();
+    }
+    function onKeydown(e) {
+        if (e.key === 'PageUp' || e.key === 'Home' || e.key === 'ArrowUp') {
+            markIntentUp();
+        }
+    }
+    function onSelectionChange() {
+        const sel = typeof window !== 'undefined' ? window.getSelection?.() : null;
+        if (sel && !sel.isCollapsed)
+            markIntentUp();
+    }
+    function action(node) {
+        el = node;
+        atBottom = computeAtBottom();
+        node.addEventListener('scroll', onScroll, { passive: true });
+        node.addEventListener('wheel', onWheel, { passive: true });
+        node.addEventListener('touchmove', markIntentUp, { passive: true });
+        node.addEventListener('keydown', onKeydown);
+        document.addEventListener('selectionchange', onSelectionChange);
+        publish();
+        return {
+            destroy() {
+                node.removeEventListener('scroll', onScroll);
+                node.removeEventListener('wheel', onWheel);
+                node.removeEventListener('touchmove', markIntentUp);
+                node.removeEventListener('keydown', onKeydown);
+                document.removeEventListener('selectionchange', onSelectionChange);
+                if (rafId)
+                    cancelAnimationFrame(rafId);
+                el = null;
+            }
+        };
+    }
+    return { action, requestStick, jumpToLatest };
+}

package/dist/actions/swipe.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared swipe-gesture Svelte action.
+ *
+ * Extracted from SessionOverlay (page-swipe) and TasksActive (reveal/dismiss)
+ * so any surface that wants horizontal swipe gestures can opt in via a single
+ * action instead of re-implementing touch tracking.
+ *
+ * Behavior:
+ *  - Tracks one-finger horizontal drags.
+ *  - Ignores drags where |deltaY| exceeds deadzone before deltaX (vertical scroll).
+ *  - Ignores diagonal drags that violate the directional threshold
+ *    (requires |deltaX| > directionalRatio * |deltaY| to commit).
+ *  - While dragging, emits `onOffsetChange(offset)` so the caller can animate
+ *    transforms. Values past `maxOffset` are rubber-banded at 0.3×.
+ *  - On touchend, commits if either:
+ *      (a) |offset| >= commitThreshold, OR
+ *      (b) velocity >= velocityThreshold AND |offset| > threshold.
+ *    Commit fires `onSwipeLeft` or `onSwipeRight` based on direction.
+ *
+ * Usage:
+ *   <div
+ *     use:swipe={{
+ *       onSwipeLeft: () => revealActions(event),
+ *       onSwipeRight: () => dismissEvent(event),
+ *       onOffsetChange: (offset) => offsets.set(event.id, offset),
+ *       allowLeft: true,
+ *       allowRight: true
+ *     }}
+ *   >...</div>
+ */
+export interface SwipeOptions {
+    /** Fires when user commits a leftward swipe (deltaX negative). */
+    onSwipeLeft?: () => void;
+    /** Fires when user commits a rightward swipe (deltaX positive). */
+    onSwipeRight?: () => void;
+    /** Called on every drag frame with the current clamped offset (px). Reset to 0 on cancel/release. */
+    onOffsetChange?: (offset: number) => void;
+    /** Called when a drag has been recognized (after deadzone). Lets caller cancel hover / long-press. */
+    onSwipeStart?: () => void;
+    /** Called when drag ends regardless of commit. */
+    onSwipeEnd?: (committed: boolean) => void;
+    /** Max drag distance before rubber-band takes over. Default 100. */
+    maxOffset?: number;
+    /** Minimum distance to count as a slow-commit paired with velocity. Default 80. */
+    threshold?: number;
+    /** Distance at which commit always fires regardless of velocity. Default 140. */
+    commitThreshold?: number;
+    /** px/ms that qualifies as a fast-flick commit at `threshold` distance. Default 0.5. */
+    velocityThreshold?: number;
+    /** Pixels of movement ignored before committing to horizontal tracking. Default 10. */
+    deadzone?: number;
+    /** Require |deltaX| > directionalRatio * |deltaY| to treat as horizontal swipe. Default 2. */
+    directionalRatio?: number;
+    /** Allow left-swipe commits. Default true. */
+    allowLeft?: boolean;
+    /** Allow right-swipe commits. Default true. */
+    allowRight?: boolean;
+    /** When false, all handlers no-op (keeps listeners attached for toggling without remount). */
+    enabled?: boolean;
+}
+export declare function swipe(node: HTMLElement, initial?: SwipeOptions): {
+    update(next: SwipeOptions): void;
+    destroy(): void;
+};

package/dist/actions/swipe.js

@@ -0,0 +1,179 @@
+/**
+ * Shared swipe-gesture Svelte action.
+ *
+ * Extracted from SessionOverlay (page-swipe) and TasksActive (reveal/dismiss)
+ * so any surface that wants horizontal swipe gestures can opt in via a single
+ * action instead of re-implementing touch tracking.
+ *
+ * Behavior:
+ *  - Tracks one-finger horizontal drags.
+ *  - Ignores drags where |deltaY| exceeds deadzone before deltaX (vertical scroll).
+ *  - Ignores diagonal drags that violate the directional threshold
+ *    (requires |deltaX| > directionalRatio * |deltaY| to commit).
+ *  - While dragging, emits `onOffsetChange(offset)` so the caller can animate
+ *    transforms. Values past `maxOffset` are rubber-banded at 0.3×.
+ *  - On touchend, commits if either:
+ *      (a) |offset| >= commitThreshold, OR
+ *      (b) velocity >= velocityThreshold AND |offset| > threshold.
+ *    Commit fires `onSwipeLeft` or `onSwipeRight` based on direction.
+ *
+ * Usage:
+ *   <div
+ *     use:swipe={{
+ *       onSwipeLeft: () => revealActions(event),
+ *       onSwipeRight: () => dismissEvent(event),
+ *       onOffsetChange: (offset) => offsets.set(event.id, offset),
+ *       allowLeft: true,
+ *       allowRight: true
+ *     }}
+ *   >...</div>
+ */
+const DEFAULTS = {
+    maxOffset: 100,
+    threshold: 80,
+    commitThreshold: 140,
+    velocityThreshold: 0.5,
+    deadzone: 10,
+    directionalRatio: 2,
+    allowLeft: true,
+    allowRight: true,
+    enabled: true
+};
+export function swipe(node, initial = {}) {
+    let opts = { ...DEFAULTS, ...initial };
+    let state = null;
+    function resolve(key) {
+        const v = opts[key];
+        return (v === undefined ? DEFAULTS[key] : v);
+    }
+    function onTouchStart(e) {
+        if (!resolve('enabled'))
+            return;
+        if (e.touches.length !== 1)
+            return;
+        const t = e.touches[0];
+        state = {
+            startX: t.clientX,
+            startY: t.clientY,
+            startTime: Date.now(),
+            swiping: false,
+            committed: false
+        };
+    }
+    function onTouchMove(e) {
+        if (!state || state.committed || !resolve('enabled'))
+            return;
+        const t = e.touches[0];
+        const deltaX = t.clientX - state.startX;
+        const deltaY = t.clientY - state.startY;
+        const deadzone = resolve('deadzone');
+        const ratio = resolve('directionalRatio');
+        if (!state.swiping) {
+            // Vertical intent wins — let scroll happen, drop the gesture.
+            if (Math.abs(deltaY) > deadzone && Math.abs(deltaY) > Math.abs(deltaX)) {
+                state = null;
+                opts.onOffsetChange?.(0);
+                return;
+            }
+            if (Math.abs(deltaX) > deadzone && Math.abs(deltaX) > ratio * Math.abs(deltaY)) {
+                state.swiping = true;
+                opts.onSwipeStart?.();
+            }
+            else {
+                return;
+            }
+        }
+        // Direction gating — if caller disabled that side, don't preview offset past deadzone.
+        const allowLeft = resolve('allowLeft');
+        const allowRight = resolve('allowRight');
+        if (deltaX < 0 && !allowLeft)
+            return;
+        if (deltaX > 0 && !allowRight)
+            return;
+        e.preventDefault();
+        const maxOffset = resolve('maxOffset');
+        let clamped;
+        if (Math.abs(deltaX) <= maxOffset) {
+            clamped = deltaX;
+        }
+        else {
+            const excess = Math.abs(deltaX) - maxOffset;
+            clamped = Math.sign(deltaX) * (maxOffset + excess * 0.3);
+        }
+        opts.onOffsetChange?.(clamped);
+    }
+    function finish(commitOffset) {
+        if (!state)
+            return;
+        const cur = state;
+        state = null;
+        const wasSwiping = cur.swiping;
+        if (!wasSwiping) {
+            opts.onSwipeEnd?.(false);
+            return;
+        }
+        const offset = commitOffset ?? 0;
+        const elapsed = Math.max(1, Date.now() - cur.startTime);
+        const velocity = Math.abs(offset) / elapsed;
+        const threshold = resolve('threshold');
+        const commitThreshold = resolve('commitThreshold');
+        const velocityThreshold = resolve('velocityThreshold');
+        const shouldCommit = Math.abs(offset) >= commitThreshold ||
+            (velocity >= velocityThreshold && Math.abs(offset) > threshold);
+        let committed = false;
+        if (shouldCommit) {
+            if (offset > 0 && resolve('allowRight')) {
+                opts.onSwipeRight?.();
+                committed = true;
+            }
+            else if (offset < 0 && resolve('allowLeft')) {
+                opts.onSwipeLeft?.();
+                committed = true;
+            }
+        }
+        opts.onOffsetChange?.(0);
+        opts.onSwipeEnd?.(committed);
+    }
+    let lastOffset = 0;
+    const wrappedOffset = (v) => {
+        lastOffset = v;
+        initial.onOffsetChange?.(v);
+    };
+    opts = { ...opts, onOffsetChange: wrappedOffset };
+    function onTouchEnd() {
+        finish(lastOffset);
+        lastOffset = 0;
+    }
+    function onTouchCancel() {
+        if (state) {
+            state = null;
+            opts.onOffsetChange?.(0);
+            opts.onSwipeEnd?.(false);
+        }
+        lastOffset = 0;
+    }
+    node.addEventListener('touchstart', onTouchStart, { passive: true });
+    node.addEventListener('touchmove', onTouchMove, { passive: false });
+    node.addEventListener('touchend', onTouchEnd);
+    node.addEventListener('touchcancel', onTouchCancel);
+    return {
+        update(next) {
+            const userOffsetChange = next.onOffsetChange;
+            opts = {
+                ...DEFAULTS,
+                ...next,
+                onOffsetChange: (v) => {
+                    lastOffset = v;
+                    userOffsetChange?.(v);
+                }
+            };
+            initial = next;
+        },
+        destroy() {
+            node.removeEventListener('touchstart', onTouchStart);
+            node.removeEventListener('touchmove', onTouchMove);
+            node.removeEventListener('touchend', onTouchEnd);
+            node.removeEventListener('touchcancel', onTouchCancel);
+        }
+    };
+}