vlist 2.0.0 → 2.0.1

package/dist/plugins/scrollbar/scrollbar.js

@@ -1,556 +0,0 @@
-/**
- * vlist - Custom Scrollbar
- * Provides visual scroll indication for compressed mode where native scrollbar is hidden
- *
- * Features:
- * - Visual track and thumb
- * - Thumb size proportional to visible content
- * - Click on track to jump to position
- * - Drag thumb to scroll
- * - Auto-hide after idle (optional)
- * - Show on hover with configurable hover zone (optional)
- * - CSS variables for customization
- * - Horizontal mode support (direction-aware axis)
- */
-// =============================================================================
-// Constants
-// =============================================================================
-const AUTO_HIDE = true;
-const AUTO_HIDE_DELAY = 1000;
-const MIN_THUMB_SIZE = 15;
-const SHOW_ON_HOVER = true;
-const HOVER_ZONE_REACH = 16; // px of reach beyond the visible track (added to padding for the default)
-const SHOW_ON_VIEWPORT_ENTER = true;
-const PADDING = 2;
-const TRACK_CLICK_BEHAVIOR = 'scroll';
-const PAGE_SCROLL_INITIAL_DELAY = 350; // ms before continuous scroll starts (matches keyboard repeat)
-const PAGE_SCROLL_SPEED_PPS = 12; // pages per second during held continuous scroll
-const resolvePadding = (raw) => {
-    // typeof !== 'object' narrows raw to number | undefined in the true branch,
-    // avoiding a narrowing gap that occurs with the equivalent (raw === undefined || typeof raw === 'number') OR form.
-    if (typeof raw !== 'object') {
-        const v = raw ?? PADDING;
-        return { top: v, right: v, bottom: v, left: v };
-    }
-    return {
-        top: raw.top ?? PADDING,
-        right: raw.right ?? PADDING,
-        bottom: raw.bottom ?? PADDING,
-        left: raw.left ?? PADDING,
-    };
-};
-// =============================================================================
-// Factory
-// =============================================================================
-/**
- * Create a scrollbar instance
- *
- * @param viewport - The viewport element (used for events and CSS variables)
- * @param onScroll - Callback when scrollbar interaction causes scroll
- * @param config - Scrollbar configuration
- * @param classPrefix - CSS class prefix (default: 'vlist')
- * @param horizontal - Whether the scrollbar is horizontal (default: false)
- * @param parent - Element to append scrollbar DOM to (default: viewport)
- */
-export const createScrollbar = (viewport, onScroll, config = {}, classPrefix = "vlist", horizontal = false, parent) => {
-    const { autoHide = AUTO_HIDE, autoHideDelay = AUTO_HIDE_DELAY, minThumbSize = MIN_THUMB_SIZE, showOnHover = SHOW_ON_HOVER, showOnViewportEnter = SHOW_ON_VIEWPORT_ENTER, clickBehavior: rawClickBehavior = TRACK_CLICK_BEHAVIOR, } = config;
-    const clickBehavior = rawClickBehavior === 'page' ? 'scroll' : rawClickBehavior;
-    const attachTo = parent ?? viewport;
-    const pad = resolvePadding(config.padding);
-    // Axis-aware padding: start/end along the scroll axis, wall-side for hover zone default
-    const scrollAxisStartPad = horizontal ? pad.left : pad.top;
-    const scrollAxisEndPad = horizontal ? pad.right : pad.bottom;
-    const wallPad = horizontal ? pad.bottom : pad.right;
-    // Hover zone covers wall-gap + fixed reach beyond the track edge
-    const hoverZoneWidth = config.hoverZoneWidth ?? (wallPad + HOVER_ZONE_REACH);
-    // State
-    let totalSize = 0;
-    let containerSize = 0;
-    let thumbSize = 0;
-    let maxThumbTravel = 0;
-    let isDragging = false;
-    let isHovering = false;
-    let dragStartPos = 0;
-    let dragStartScrollPosition = 0;
-    let currentScrollPosition = 0;
-    let hideTimeout = null;
-    let visible = false;
-    let animationFrameId = null;
-    let pageClickPos = 0;
-    let pageScrollPosition = 0; // internal tracker — updated synchronously each tick
-    let repeatTimeout = null;
-    let repeatRafId = null;
-    let repeatLastTime = null;
-    // Axis helpers — select CSS property / mouse coordinate once
-    const thumbSizeProp = horizontal ? "width" : "height";
-    const translateFn = horizontal ? "translateX" : "translateY";
-    const mousePos = horizontal
-        ? (e) => e.clientX
-        : (e) => e.clientY;
-    const rectStart = horizontal ? "left" : "top";
-    // DOM elements
-    const track = document.createElement("div");
-    const thumb = document.createElement("div");
-    // Always created: extends click target into the padding margin + handles hover when showOnHover
-    const hoverZone = document.createElement("div");
-    // When the scrollbar lives on root, offset its top to align with the viewport.
-    // Uses the CSS variable for padding so runtime updates via CSS take effect
-    // without rebuilding the scrollbar.
-    const startPadVar = horizontal
-        ? "--vlist-custom-scrollbar-padding-left"
-        : "--vlist-custom-scrollbar-padding-top";
-    const syncTrackOffset = () => {
-        if (attachTo === viewport)
-            return;
-        const offset = viewport.offsetTop;
-        track.style[horizontal ? "left" : "top"] = offset
-            ? `calc(var(${startPadVar}) + ${offset}px)`
-            : `var(${startPadVar})`;
-        hoverZone.style[horizontal ? "left" : "top"] = `${offset}px`;
-    };
-    // =============================================================================
-    // DOM Setup
-    // =============================================================================
-    const setupDOM = () => {
-        track.className = `${classPrefix}-scrollbar`;
-        thumb.className = `${classPrefix}-scrollbar__thumb`;
-        if (horizontal) {
-            track.classList.add(`${classPrefix}-scrollbar--horizontal`);
-        }
-        if (config.padding !== undefined) {
-            attachTo.style.setProperty("--vlist-custom-scrollbar-padding-top", `${pad.top}px`);
-            attachTo.style.setProperty("--vlist-custom-scrollbar-padding-right", `${pad.right}px`);
-            attachTo.style.setProperty("--vlist-custom-scrollbar-padding-bottom", `${pad.bottom}px`);
-            attachTo.style.setProperty("--vlist-custom-scrollbar-padding-left", `${pad.left}px`);
-        }
-        if (config.minThumbSize !== undefined) {
-            track.style.setProperty("--vlist-custom-scrollbar-min-thumb-size", `${minThumbSize}px`);
-        }
-        track.appendChild(thumb);
-        attachTo.appendChild(track);
-        // Edge zone — covers the padding margin + track area along the scrollbar edge.
-        // Always present so clicks in the padding margin are captured regardless of showOnHover.
-        // pointer-events:auto so events fire even when the track is hidden (opacity:0).
-        hoverZone.className = `${classPrefix}-scrollbar__hover`;
-        if (horizontal) {
-            hoverZone.classList.add(`${classPrefix}-scrollbar__hover--horizontal`);
-            hoverZone.style.height = `${hoverZoneWidth}px`;
-        }
-        else {
-            hoverZone.style.width = `${hoverZoneWidth}px`;
-        }
-        attachTo.appendChild(hoverZone);
-        // When attached to root instead of viewport, offset track/hover to match
-        // the viewport's position (e.g. below a sticky header).
-        if (attachTo !== viewport) {
-            syncTrackOffset();
-        }
-    };
-    // =============================================================================
-    // Hide timeout helpers
-    // =============================================================================
-    const clearHideTimeout = () => {
-        if (hideTimeout) {
-            clearTimeout(hideTimeout);
-            hideTimeout = null;
-        }
-    };
-    const scheduleHide = () => {
-        if (!autoHide)
-            return;
-        clearHideTimeout();
-        hideTimeout = setTimeout(hide, autoHideDelay);
-    };
-    // =============================================================================
-    // Visibility
-    // =============================================================================
-    /**
-     * Show the scrollbar.
-     * When called from scroll events, auto-hide is scheduled (unless hovering).
-     * When called from hover events, no auto-hide is scheduled.
-     */
-    const show = () => {
-        if (totalSize <= containerSize)
-            return;
-        clearHideTimeout();
-        if (!visible) {
-            track.classList.add(`${classPrefix}-scrollbar--visible`);
-            visible = true;
-        }
-        // Schedule auto-hide only if not hovering and not dragging
-        if (autoHide && !isDragging && !isHovering) {
-            scheduleHide();
-        }
-    };
-    const hide = () => {
-        if (isDragging || isHovering)
-            return;
-        track.classList.remove(`${classPrefix}-scrollbar--visible`);
-        visible = false;
-    };
-    // =============================================================================
-    // Size & Position Calculations
-    // =============================================================================
-    const updateBounds = (newTotalSize, newContainerSize) => {
-        totalSize = newTotalSize;
-        containerSize = newContainerSize;
-        syncTrackOffset();
-        // Check if scrollbar is needed
-        if (totalSize <= containerSize) {
-            track.style.display = "none";
-            hide();
-            return;
-        }
-        track.style.display = "";
-        // Effective track length shrinks by the margin on both ends (start + end along scroll axis)
-        const trackLength = Math.max(0, containerSize - scrollAxisStartPad - scrollAxisEndPad);
-        // Calculate thumb size (proportional to visible content, scaled to track)
-        const scrollRatio = containerSize / totalSize;
-        thumbSize = Math.max(minThumbSize, scrollRatio * trackLength);
-        thumb.style[thumbSizeProp] = `${thumbSize}px`;
-        // Calculate max thumb travel distance
-        maxThumbTravel = trackLength - thumbSize;
-        // Update position with current scroll
-        updatePosition(currentScrollPosition);
-        if (!autoHide) {
-            show();
-        }
-    };
-    const updatePosition = (scrollTop) => {
-        currentScrollPosition = scrollTop;
-        if (totalSize <= containerSize || maxThumbTravel <= 0)
-            return;
-        // Calculate scroll percentage
-        const maxScroll = totalSize - containerSize;
-        const scrollRatio = Math.min(1, Math.max(0, scrollTop / maxScroll));
-        // Position thumb
-        thumb.style.transform = `${translateFn}(${scrollRatio * maxThumbTravel}px)`;
-    };
-    // =============================================================================
-    // Track Click Handlers
-    // =============================================================================
-    // 'jump' — instantly center thumb at clicked position
-    const handleTrackClick = (e) => {
-        if (e.target === thumb || clickBehavior !== 'jump' || maxThumbTravel <= 0)
-            return;
-        const maxScroll = totalSize - containerSize;
-        const trackRect = track.getBoundingClientRect();
-        const clickPos = mousePos(e) - trackRect[rectStart];
-        const clampedThumbStart = Math.max(0, Math.min(clickPos - thumbSize / 2, maxThumbTravel));
-        onScroll((clampedThumbStart / maxThumbTravel) * maxScroll);
-        show();
-    };
-    const clearRepeat = () => {
-        if (repeatTimeout !== null) {
-            clearTimeout(repeatTimeout);
-            repeatTimeout = null;
-        }
-        if (repeatRafId !== null) {
-            cancelAnimationFrame(repeatRafId);
-            repeatRafId = null;
-        }
-        repeatLastTime = null;
-    };
-    // Compute direction toward pageClickPos; returns -1 (back), 1 (forward), or 0 (arrived).
-    // Caller must provide maxScroll to avoid recomputing it.
-    const pageScrollDirection = (maxScroll) => {
-        const thumbCurrentStart = maxThumbTravel > 0 ? (pageScrollPosition / maxScroll) * maxThumbTravel : 0;
-        if (pageClickPos < thumbCurrentStart)
-            return -1;
-        if (pageClickPos >= thumbCurrentStart + thumbSize)
-            return 1;
-        return 0;
-    };
-    // 'scroll' — immediate first scroll by one containerSize toward click
-    const firePageScroll = () => {
-        const maxScroll = totalSize - containerSize;
-        const dir = pageScrollDirection(maxScroll);
-        if (dir === 0) {
-            clearRepeat();
-            return;
-        }
-        if (dir === -1) {
-            if (pageScrollPosition <= 0) {
-                clearRepeat();
-                return;
-            }
-            const newPos = Math.max(0, pageScrollPosition - containerSize);
-            pageScrollPosition = newPos;
-            onScroll(newPos);
-        }
-        else {
-            if (pageScrollPosition >= maxScroll) {
-                clearRepeat();
-                return;
-            }
-            const newPos = Math.min(maxScroll, pageScrollPosition + containerSize);
-            pageScrollPosition = newPos;
-            onScroll(newPos);
-        }
-        show();
-    };
-    // Continuous RAF loop — runs after initial delay while mouse is held
-    const tickContinuousScroll = (timestamp) => {
-        // First frame: record baseline time and reschedule without scrolling
-        if (repeatLastTime === null) {
-            repeatLastTime = timestamp;
-            repeatRafId = requestAnimationFrame(tickContinuousScroll);
-            return;
-        }
-        const maxScroll = totalSize - containerSize;
-        const dt = timestamp - repeatLastTime;
-        repeatLastTime = timestamp;
-        const dir = pageScrollDirection(maxScroll);
-        if (dir === 0) {
-            clearRepeat();
-            return;
-        }
-        // Speed in px/ms, capped so one frame never overshoots more than containerSize
-        const speed = (PAGE_SCROLL_SPEED_PPS * containerSize) / 1000;
-        const delta = Math.min(speed * dt, containerSize);
-        if (dir === -1) {
-            if (pageScrollPosition <= 0) {
-                clearRepeat();
-                return;
-            }
-            const newPos = Math.max(0, pageScrollPosition - delta);
-            pageScrollPosition = newPos;
-            onScroll(newPos);
-        }
-        else {
-            if (pageScrollPosition >= maxScroll) {
-                clearRepeat();
-                return;
-            }
-            const newPos = Math.min(maxScroll, pageScrollPosition + delta);
-            pageScrollPosition = newPos;
-            onScroll(newPos);
-        }
-        // Keep scrollbar visible without creating a new hide timer every frame
-        clearHideTimeout();
-        repeatRafId = requestAnimationFrame(tickContinuousScroll);
-    };
-    const handleRepeatMouseUp = () => {
-        clearRepeat();
-        // Begin auto-hide now that the hold has ended
-        scheduleHide();
-        document.removeEventListener('mouseup', handleRepeatMouseUp);
-    };
-    // 'scroll' — immediate first scroll then smooth continuous scroll while held
-    const handleTrackMouseDown = (e) => {
-        if (e.target === thumb || clickBehavior !== 'scroll')
-            return;
-        e.preventDefault();
-        const trackRect = track.getBoundingClientRect();
-        pageClickPos = mousePos(e) - trackRect[rectStart];
-        pageScrollPosition = currentScrollPosition;
-        firePageScroll();
-        // After initial delay, begin smooth RAF-driven continuous scroll
-        repeatTimeout = setTimeout(() => {
-            repeatRafId = requestAnimationFrame(tickContinuousScroll);
-        }, PAGE_SCROLL_INITIAL_DELAY);
-        document.addEventListener('mouseup', handleRepeatMouseUp);
-    };
-    // =============================================================================
-    // Thumb Drag Handlers
-    // =============================================================================
-    const handleThumbMouseDown = (e) => {
-        e.preventDefault();
-        e.stopPropagation();
-        isDragging = true;
-        dragStartPos = mousePos(e);
-        dragStartScrollPosition = currentScrollPosition;
-        // Cancel any hide while dragging
-        clearHideTimeout();
-        track.classList.add(`${classPrefix}-scrollbar--dragging`);
-        document.addEventListener("mousemove", handleMouseMove);
-        document.addEventListener("mouseup", handleMouseUp);
-    };
-    const handleMouseMove = (e) => {
-        if (!isDragging)
-            return;
-        const delta = mousePos(e) - dragStartPos;
-        // Convert thumb movement to scroll movement
-        const scrollRatio = maxThumbTravel > 0 ? delta / maxThumbTravel : 0;
-        const maxScroll = totalSize - containerSize;
-        const deltaScroll = scrollRatio * maxScroll;
-        const newPosition = Math.max(0, Math.min(dragStartScrollPosition + deltaScroll, maxScroll));
-        // Update thumb immediately for responsive feel
-        thumb.style.transform = `${translateFn}(${(newPosition / maxScroll) * maxThumbTravel}px)`;
-        // Call synchronously — rAF throttle causes a one-frame lag because
-        // the HTML spec processes scroll events BEFORE rAF callbacks, so the
-        // pipeline would always render for the previous frame's scroll position.
-        onScroll(newPosition);
-    };
-    const handleMouseUp = () => {
-        isDragging = false;
-        track.classList.remove(`${classPrefix}-scrollbar--dragging`);
-        // Schedule auto-hide only if not hovering
-        if (autoHide && !isHovering) {
-            scheduleHide();
-        }
-        document.removeEventListener("mousemove", handleMouseMove);
-        document.removeEventListener("mouseup", handleMouseUp);
-    };
-    // =============================================================================
-    // Touch Handlers (thumb drag)
-    // =============================================================================
-    const touchPos = horizontal
-        ? (e) => e.touches[0].clientX
-        : (e) => e.touches[0].clientY;
-    const handleThumbTouchStart = (e) => {
-        e.stopPropagation();
-        isDragging = true;
-        dragStartPos = touchPos(e);
-        dragStartScrollPosition = currentScrollPosition;
-        clearHideTimeout();
-        track.classList.add(`${classPrefix}-scrollbar--dragging`);
-    };
-    const handleThumbTouchMove = (e) => {
-        if (!isDragging)
-            return;
-        e.preventDefault();
-        const delta = touchPos(e) - dragStartPos;
-        const scrollRatio = maxThumbTravel > 0 ? delta / maxThumbTravel : 0;
-        const maxScroll = totalSize - containerSize;
-        const deltaScroll = scrollRatio * maxScroll;
-        const newPosition = Math.max(0, Math.min(dragStartScrollPosition + deltaScroll, maxScroll));
-        thumb.style.transform = `${translateFn}(${(newPosition / maxScroll) * maxThumbTravel}px)`;
-        onScroll(newPosition);
-    };
-    const handleThumbTouchEnd = () => {
-        isDragging = false;
-        track.classList.remove(`${classPrefix}-scrollbar--dragging`);
-        if (autoHide) {
-            scheduleHide();
-        }
-    };
-    const handleTrackTouchStart = (e) => {
-        if (e.target === thumb)
-            return;
-        if (maxThumbTravel <= 0)
-            return;
-        const touch = e.touches[0];
-        const trackRect = track.getBoundingClientRect();
-        const pos = (horizontal ? touch.clientX : touch.clientY) - trackRect[rectStart];
-        if (clickBehavior === 'jump') {
-            const maxScroll = totalSize - containerSize;
-            const clampedThumbStart = Math.max(0, Math.min(pos - thumbSize / 2, maxThumbTravel));
-            onScroll((clampedThumbStart / maxThumbTravel) * maxScroll);
-        }
-        else {
-            pageClickPos = pos;
-            pageScrollPosition = currentScrollPosition;
-            firePageScroll();
-        }
-        show();
-    };
-    // =============================================================================
-    // Viewport Hover Handlers (show on hover)
-    // =============================================================================
-    const handleViewportEnter = () => {
-        if (showOnViewportEnter) {
-            show();
-        }
-    };
-    const handleViewportLeave = () => {
-        if (!isDragging) {
-            isHovering = false;
-            if (autoHide) {
-                scheduleHide();
-            }
-        }
-    };
-    // =============================================================================
-    // Scrollbar Hover Handlers (keep visible while hovering over scrollbar area)
-    //
-    // Both the track and the hover zone set isHovering = true.
-    // While isHovering is true, show() will NOT schedule auto-hide,
-    // and hide() will refuse to run.
-    // =============================================================================
-    const handleScrollbarAreaEnter = () => {
-        isHovering = true;
-        clearHideTimeout();
-        show();
-    };
-    const handleScrollbarAreaLeave = () => {
-        isHovering = false;
-        if (!isDragging && autoHide) {
-            scheduleHide();
-        }
-    };
-    // =============================================================================
-    // Cleanup
-    // =============================================================================
-    const destroy = () => {
-        // Clear timers
-        clearHideTimeout();
-        clearRepeat();
-        if (animationFrameId !== null) {
-            cancelAnimationFrame(animationFrameId);
-            animationFrameId = null;
-        }
-        // Remove event listeners
-        track.removeEventListener("click", handleTrackClick);
-        track.removeEventListener("mousedown", handleTrackMouseDown);
-        track.removeEventListener("mouseenter", handleScrollbarAreaEnter);
-        document.removeEventListener("mouseup", handleRepeatMouseUp);
-        track.removeEventListener("mouseleave", handleScrollbarAreaLeave);
-        track.removeEventListener("touchstart", handleTrackTouchStart);
-        thumb.removeEventListener("mousedown", handleThumbMouseDown);
-        thumb.removeEventListener("touchstart", handleThumbTouchStart);
-        thumb.removeEventListener("touchmove", handleThumbTouchMove);
-        thumb.removeEventListener("touchend", handleThumbTouchEnd);
-        viewport.removeEventListener("mouseenter", handleViewportEnter);
-        viewport.removeEventListener("mouseleave", handleViewportLeave);
-        document.removeEventListener("mousemove", handleMouseMove);
-        document.removeEventListener("mouseup", handleMouseUp);
-        hoverZone.removeEventListener("click", handleTrackClick);
-        hoverZone.removeEventListener("mousedown", handleTrackMouseDown);
-        hoverZone.removeEventListener("mouseenter", handleScrollbarAreaEnter);
-        hoverZone.removeEventListener("mouseleave", handleScrollbarAreaLeave);
-        hoverZone.remove();
-        // Remove inline CSS variable overrides
-        attachTo.style.removeProperty("--vlist-custom-scrollbar-padding-top");
-        attachTo.style.removeProperty("--vlist-custom-scrollbar-padding-right");
-        attachTo.style.removeProperty("--vlist-custom-scrollbar-padding-bottom");
-        attachTo.style.removeProperty("--vlist-custom-scrollbar-padding-left");
-        // Remove DOM elements
-        track.remove();
-    };
-    // =============================================================================
-    // Initialize
-    // =============================================================================
-    setupDOM();
-    // Attach event listeners
-    track.addEventListener("click", handleTrackClick);
-    track.addEventListener("mousedown", handleTrackMouseDown);
-    track.addEventListener("mouseenter", handleScrollbarAreaEnter);
-    track.addEventListener("mouseleave", handleScrollbarAreaLeave);
-    track.addEventListener("touchstart", handleTrackTouchStart, { passive: true });
-    thumb.addEventListener("mousedown", handleThumbMouseDown);
-    thumb.addEventListener("touchstart", handleThumbTouchStart, { passive: true });
-    thumb.addEventListener("touchmove", handleThumbTouchMove, { passive: false });
-    thumb.addEventListener("touchend", handleThumbTouchEnd, { passive: true });
-    viewport.addEventListener("mouseenter", handleViewportEnter);
-    viewport.addEventListener("mouseleave", handleViewportLeave);
-    // Always: clicks in the padding margin behave the same as track clicks
-    hoverZone.addEventListener("click", handleTrackClick);
-    hoverZone.addEventListener("mousedown", handleTrackMouseDown);
-    // Conditional: hover-to-reveal behavior
-    if (showOnHover) {
-        hoverZone.addEventListener("mouseenter", handleScrollbarAreaEnter);
-        hoverZone.addEventListener("mouseleave", handleScrollbarAreaLeave);
-    }
-    // =============================================================================
-    // Public API
-    // =============================================================================
-    return {
-        show,
-        hide,
-        updateBounds,
-        updatePosition,
-        isVisible: () => visible,
-        destroy,
-    };
-};

package/dist/plugins/selection/index.js

@@ -1,7 +0,0 @@
-/**
- * vlist v2 — Selection Plugin
- */
-export { selection } from "./plugin";
-export { createSelectionState, selectOne, toggleOne, selectRange, selectRangeMut, selectAllItems, moveFocus, getSelectedArray, getSelectedItems, getSelectedItemsMut, 
-// v1 immutable API (re-exported for backwards compat)
-selectItems, deselectItems, toggleSelection, selectAll, clearSelection, isSelected, getSelectedIds, getSelectionCount, isSelectionEmpty, selectFocused, moveFocusUp, moveFocusDown, moveFocusToFirst, moveFocusToLast, moveFocusByPage, claimPlaceholderSelection, setFocusedIndex, } from "./state";