vlist 0.1.2 → 1.5.4

package/dist/features/groups/sticky.d.ts

@@ -0,0 +1,21 @@
+/**
+ * vlist - Sticky Header
+ *
+ * Manages a floating header that sticks to the viewport edge and transitions
+ * smoothly when the next group's header approaches (push-out effect).
+ *
+ * Two permanent slot elements are recycled — content is swapped via a
+ * caller-provided `renderInto` callback, keeping the sticky header
+ * template-agnostic (same pattern as item rendering).
+ *
+ * Header offsets and sizes are pre-cached into flat arrays on rebuild,
+ * keeping the per-tick scroll handler free of function calls.
+ *
+ *   .vlist-sticky-header (position: relative, overflow: hidden)
+ *   ├── .sticky-group  (active slot — translated during push)
+ *   └── .sticky-group  (standby slot — translated during push)
+ */
+import type { GroupLayout, StickyHeader } from "./types";
+import type { SizeCache } from "../../rendering/sizes";
+export declare const createStickyHeader: (root: HTMLElement, layout: GroupLayout, sizeCache: SizeCache, renderInto: (slot: HTMLElement, groupIndex: number) => void, classPrefix: string, horizontal?: boolean, stickyOffset?: number) => StickyHeader;
+//# sourceMappingURL=sticky.d.ts.map

package/dist/features/groups/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * vlist - Group Types
+ * Types for sticky headers and grouped lists
+ */
+import type { VListItem, GroupsConfig } from "../../types";
+export type { GroupsConfig };
+/** A single group boundary */
+export interface GroupBoundary {
+    /** Group key (return value of getGroupForIndex) */
+    key: string;
+    /** Sequential group index (0-based) */
+    groupIndex: number;
+    /** Layout index of this group's header */
+    headerLayoutIndex: number;
+    /** Data index of the first item in this group */
+    firstDataIndex: number;
+    /** Number of data items in this group */
+    count: number;
+}
+/** Entry type in the layout — either a group header or a data item */
+export type LayoutEntry = {
+    type: "header";
+    group: GroupBoundary;
+} | {
+    type: "item";
+    dataIndex: number;
+    group: GroupBoundary;
+};
+/**
+ * Internal marker for group header pseudo-items inserted into the layout.
+ * These are interleaved with real data items in the transformed items array.
+ */
+export interface GroupHeaderItem extends VListItem {
+    /** Always `__group_header_{groupIndex}` */
+    id: string;
+    /** Discriminator flag */
+    __groupHeader: true;
+    /** The group key */
+    groupKey: string;
+    /** Sequential group index (0-based) */
+    groupIndex: number;
+}
+/**
+ * Type guard: check if an item is a group header pseudo-item
+ */
+export declare const isGroupHeader: (item: unknown) => item is GroupHeaderItem;
+/** Group layout — maps between data indices and layout indices */
+export interface GroupLayout {
+    /** Total layout entries (data items + group headers) */
+    readonly totalEntries: number;
+    /** Number of groups */
+    readonly groupCount: number;
+    /** All group boundaries, in order */
+    readonly groups: readonly GroupBoundary[];
+    /** Get the layout entry at a layout index — O(log g) */
+    getEntry: (layoutIndex: number) => LayoutEntry;
+    /** Map layout index → data index, or -1 if it's a header — O(log g) */
+    layoutToDataIndex: (layoutIndex: number) => number;
+    /** Map data index → layout index — O(log g) */
+    dataToLayoutIndex: (dataIndex: number) => number;
+    /** Get the group boundary that contains a given layout index — O(log g) */
+    getGroupAtLayoutIndex: (layoutIndex: number) => GroupBoundary;
+    /** Get the group boundary that contains a given data index — O(log g) */
+    getGroupAtDataIndex: (dataIndex: number) => GroupBoundary;
+    /** Get header height for a group */
+    getHeaderHeight: (groupIndex: number) => number;
+    /**
+     * Rebuild the layout from scratch.
+     * Call when items change (setItems, append, prepend, remove, etc.)
+     */
+    rebuild: (itemCount: number) => void;
+}
+/** Sticky header manager */
+export interface StickyHeader {
+    /** Update sticky header position and content based on scroll position */
+    update: (scrollTop: number) => void;
+    /** Force refresh the sticky header content (e.g. after items change) */
+    refresh: () => void;
+    /** Show the sticky header */
+    show: () => void;
+    /** Hide the sticky header */
+    hide: () => void;
+    /** Destroy and remove the sticky header DOM element */
+    destroy: () => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/features/masonry/feature.d.ts

@@ -0,0 +1,45 @@
+/**
+ * vlist/masonry - Builder Feature
+ * Switches from list layout to masonry/Pinterest-style layout.
+ *
+ * Priority: 10 (runs first — replaces the renderer before anything else renders)
+ *
+ * What it does:
+ * - Replaces renderer — swaps the list renderer with a masonry renderer
+ * - Calculates item placements using shortest-lane algorithm
+ * - Positions items using absolute coordinates (no row alignment)
+ * - Renders only visible items based on scroll position
+ * - CSS class — adds .vlist--masonry to the root element
+ *
+ * Key differences from grid:
+ * - No row-based virtualization (items flow into shortest column/row)
+ * - O(n) layout calculation (must track lane heights)
+ * - Items positioned by cached x/y coordinates
+ * - Variable heights create organic, packed layout
+ *
+ * Restrictions:
+ * - Cannot be combined with reverse: true
+ * - Item sizes must be deterministic (no dynamic content sizing)
+ *
+ * Can be combined with withSelection for selectable masonry layouts.
+ *
+ * Performance:
+ * - Early exit when scroll position + container size unchanged (zero work per redundant frame)
+ * - Cached empty Set for no-selection case (zero allocation per frame)
+ * - Viewport state mutated in place (no object creation per frame)
+ * - Cached getItem closure (no closure allocation per frame)
+ *
+ * - Items passed to renderer via data manager reference (no sparse array)
+ * - All data mutation methods intercepted for layout recalculation
+ */
+import type { VListItem } from "../../types";
+import type { VListFeature } from "../../builder/types";
+/** Masonry feature configuration */
+export interface MasonryFeatureConfig {
+    /** Number of cross-axis divisions (columns in vertical, rows in horizontal) */
+    columns: number;
+    /** Gap between items in pixels (default: 0) */
+    gap?: number;
+}
+export declare const withMasonry: <T extends VListItem = VListItem>(config: MasonryFeatureConfig) => VListFeature<T>;
+//# sourceMappingURL=feature.d.ts.map

package/dist/features/masonry/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * vlist - Masonry Domain
+ * Pinterest-style layout with shortest-lane placement
+ */
+export { withMasonry, type MasonryFeatureConfig } from "./feature";
+export { createMasonryLayout } from "./layout";
+export { createMasonryRenderer, type MasonryRenderer, type GetItemFn } from "./renderer";
+export type { MasonryConfig, MasonryLayout, ItemPlacement, } from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/features/masonry/layout.d.ts

@@ -0,0 +1,29 @@
+/**
+ * vlist - Masonry Layout
+ * Shortest-lane placement algorithm for masonry/Pinterest-style layouts.
+ *
+ * Algorithm:
+ * 1. Track the size (height/width) of each lane (column/row)
+ * 2. For each item:
+ *    - Find the shortest lane
+ *    - Place item at the end of that lane
+ *    - Update lane size
+ * 3. Cache all item positions for O(1) lookup during rendering
+ *
+ * Complexity:
+ * - Layout calculation: O(n) where n = total items
+ * - Position lookup: O(1) using cached placements
+ * - Visibility check: O(k * log(n/k)) using per-lane binary search
+ *   where k = columns, n = total items
+ */
+import type { MasonryConfig, MasonryLayout } from "./types";
+/**
+ * Create a MasonryLayout instance.
+ *
+ * @param config - Masonry configuration (columns, gap, containerSize)
+ * @returns MasonryLayout with placement algorithm
+ */
+export declare const createMasonryLayout: (config: MasonryConfig & {
+    containerSize: number;
+}) => MasonryLayout;
+//# sourceMappingURL=layout.d.ts.map

package/dist/features/masonry/renderer.d.ts

@@ -0,0 +1,55 @@
+/**
+ * vlist - Masonry Renderer
+ * Renders items in a masonry/Pinterest-style layout with absolute positioning.
+ *
+ * Unlike grid renderer (which uses row-based positioning), masonry renderer
+ * positions each item using its pre-calculated coordinates from the layout phase.
+ *
+ * Key differences from grid:
+ * - Items positioned using cached x/y coordinates (not row/col calculations)
+ * - Each item can have different height/width
+ * - No row alignment - items flow into shortest column/row
+ * - Visibility determined by checking each item's absolute position
+ *
+ * Performance:
+ * - Element pooling avoids createElement cost
+ * - Template re-evaluation skipped when item data + state unchanged
+ * - O(1) Set-based visibility diffing (not O(n) .some())
+ * - Release grace period prevents boundary thrashing (hover blink, transition replay)
+ * - Released elements removed from DOM immediately
+ */
+import type { VListItem, ItemTemplate } from "../../types";
+import type { ItemPlacement } from "./types";
+/** Item lookup function — avoids sparse array allocation on every frame */
+export type GetItemFn<T> = (index: number) => T | undefined;
+/** Masonry renderer instance */
+export interface MasonryRenderer<T extends VListItem = VListItem> {
+    /** Render visible items using pre-calculated placements */
+    render: (getItem: GetItemFn<T>, placements: ItemPlacement[], selectedIds: Set<string | number>, focusedIndex: number) => void;
+    /** Get rendered item element by flat item index */
+    getElement: (index: number) => HTMLElement | undefined;
+    /** Update only CSS classes on a rendered item (no template re-evaluation) */
+    updateItemClasses: (index: number, isSelected: boolean, isFocused: boolean) => void;
+    /**
+     * Reorder DOM children to match logical item order (by data-index).
+     * Called on scroll idle so screen readers encounter items in the correct
+     * sequence. Items are position:absolute so visual layout is unaffected.
+     */
+    sortDOM: () => void;
+    /** Clear all rendered items */
+    clear: () => void;
+    /** Destroy renderer and cleanup */
+    destroy: () => void;
+}
+/**
+ * Create a masonry renderer for managing DOM elements with absolute positioning.
+ *
+ * @param itemsContainer - The DOM element that holds rendered items
+ * @param template - Item template function
+ * @param classPrefix - CSS class prefix
+ * @param isHorizontal - Whether layout is horizontal (scrolls right)
+ * @param totalItemsGetter - Optional getter for total item count (for aria-setsize)
+ * @param ariaIdPrefix - Optional unique prefix for element IDs (for aria-activedescendant)
+ */
+export declare const createMasonryRenderer: <T extends VListItem = VListItem>(itemsContainer: HTMLElement, template: ItemTemplate<T>, classPrefix: string, isHorizontal?: boolean, totalItemsGetter?: () => number, ariaIdPrefix?: string) => MasonryRenderer<T>;
+//# sourceMappingURL=renderer.d.ts.map

package/dist/features/masonry/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * vlist - Masonry Types
+ * Types for masonry/Pinterest-style layout mode
+ *
+ * Masonry layout arranges items in columns (vertical) or rows (horizontal)
+ * where items flow into the shortest column/row, creating a packed layout
+ * with no alignment across the cross-axis.
+ */
+import type { MasonryConfig } from "../../types";
+export type { MasonryConfig };
+/** Cached item placement — flat structure for minimal allocation and fast access */
+export interface ItemPlacement {
+    /** Item index */
+    index: number;
+    /** X coordinate in pixels (cross-axis offset) */
+    x: number;
+    /** Y coordinate in pixels (main-axis offset) */
+    y: number;
+    /** Cross-axis division index (column in vertical, row in horizontal) */
+    lane: number;
+    /** Item size in main axis (height in vertical, width in horizontal) */
+    size: number;
+    /** Item size in cross axis (width in vertical, height in horizontal) */
+    crossSize: number;
+}
+/**
+ * MasonryLayout — places items in the shortest column/row.
+ *
+ * Unlike grid (O(1) calculations), masonry requires O(n) layout calculation
+ * because each item's position depends on the accumulated sizes of items
+ * before it in the same column/row.
+ *
+ * The layout algorithm:
+ * 1. Track size of each column/row (cross-axis divisions)
+ * 2. For each item, find the shortest column/row
+ * 3. Place item at the end of that column/row
+ * 4. Update that column/row's size
+ * 5. Cache the item's position for rendering
+ */
+export interface MasonryLayout {
+    /** Number of cross-axis divisions (columns in vertical, rows in horizontal) */
+    readonly columns: number;
+    /** Gap between items in pixels */
+    readonly gap: number;
+    /** Container width (for vertical) or height (for horizontal) */
+    readonly containerSize: number;
+    /** Update masonry configuration */
+    update: (config: Partial<MasonryConfig & {
+        containerSize: number;
+    }>) => void;
+    /**
+     * Calculate layout for all items.
+     * Returns array of item placements with positions.
+     * This is O(n) where n = totalItems.
+     */
+    calculateLayout: (totalItems: number, getSizeForItem: (index: number) => number) => ItemPlacement[];
+    /**
+     * Get the total size in the main axis (total height in vertical, total width in horizontal).
+     * This is the size of the tallest/widest column/row.
+     */
+    getTotalSize: (placements: ItemPlacement[]) => number;
+    /**
+     * Get items visible in the viewport.
+     * mainAxisStart/End = scroll position range (scrollTop/scrollLeft + viewport size)
+     */
+    getVisibleItems: (placements: ItemPlacement[], mainAxisStart: number, mainAxisEnd: number) => ItemPlacement[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/features/page/feature.d.ts

@@ -0,0 +1,53 @@
+/**
+ * vlist/window - Window Scroll Mode Feature
+ *
+ * Enables the list to scroll with the page instead of in its own container.
+ * Useful for infinite feeds, full-page lists, and chat UIs that integrate
+ * with page scroll.
+ *
+ * Priority: 5 (runs early, before other features that depend on scroll)
+ *
+ * What it does:
+ * - Uses window as scroll target instead of viewport element
+ * - Calculates scroll position relative to document
+ * - Uses window.innerWidth/innerHeight for container dimensions
+ * - Listens to window resize events instead of ResizeObserver
+ * - Adjusts DOM styles (overflow: visible, height: auto)
+ *
+ * Bundle impact: ~0.3 KB gzipped when used
+ */
+import type { VListItem } from "../../types";
+import type { VListFeature } from "../../builder/types";
+/**
+ * Create a window scroll mode feature.
+ *
+ * Use this when you want your list to scroll with the page instead of
+ * in a fixed-height container.
+ *
+ * @example
+ * ```ts
+ * import { vlist } from 'vlist/builder'
+ * import { withWindow } from 'vlist/window'
+ *
+ * const feed = vlist({
+ *   container: '#infinite-feed',
+ *   item: { height: 200, template: renderPost },
+ *   items: posts
+ * })
+ * .use(withWindow())
+ * .build()
+ * ```
+ *
+ * @example Horizontal window scrolling
+ * ```ts
+ * const timeline = vlist({
+ *   container: '#timeline',
+ *   item: { height: 100, template: renderEvent },
+ *   orientation: 'horizontal'
+ * })
+ * .use(withWindow())
+ * .build()
+ * ```
+ */
+export declare const withPage: <T extends VListItem = VListItem>() => VListFeature<T>;
+//# sourceMappingURL=feature.d.ts.map

package/dist/features/page/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * vlist/window - Window Scroll Mode Feature
+ *
+ * Entry point for the window scroll feature.
+ */
+export { withPage } from "./feature";
+export type { VListFeature } from "../../builder/types";
+//# sourceMappingURL=index.d.ts.map

package/dist/features/scale/feature.d.ts

@@ -0,0 +1,42 @@
+/**
+ * vlist/compression - Builder Feature
+ * Enables support for lists with 1M+ items by compressing the scroll space
+ * when the total height exceeds the browser's ~16.7M pixel limit.
+ *
+ * Priority: 20 (runs before scrollbar, after grid/groups)
+ *
+ * What it wires:
+ * - Scroll mode switch — transitions from native to compressed scrolling when needed
+ * - Scroll position mapping — maps compressed scroll positions to item indices
+ * - Item positioning — positions items relative to viewport in compressed mode
+ * - Custom scrollbar fallback — forces custom scrollbar in compressed mode
+ * - Compression slack — extends scroll range so the linear index formula reaches every item
+ * - Cached compression state — recalculates only when total item count changes
+ * - Smooth scroll interpolation — lerp-based wheel handling for cross-browser consistency
+ * - Touch scroll support — finger tracking + momentum for iOS Safari / mobile browsers
+ *
+ * No configuration needed — compression activates automatically when the total
+ * height exceeds the browser limit, and deactivates when items are removed.
+ */
+import type { VListItem } from "../../types";
+import type { VListFeature } from "../../builder/types";
+/** Configuration options for the scale feature */
+export interface ScaleConfig {
+    /**
+     * Force compressed scroll mode even when the total size is below the
+     * browser's ~16.7M pixel limit.
+     *
+     * When `true`, the feature always activates compressed scrolling
+     * (custom wheel/touch handling, lerp-based smooth scroll, custom
+     * scrollbar fallback) regardless of the list size. This is useful for:
+     *
+     * - **Testing** — verify compression behaviour with a small item set
+     * - **Consistent UX** — prefer the smooth scroll physics for all lists
+     * - **Pre-emptive** — avoid the mode switch when items are added at runtime
+     *
+     * @default false
+     */
+    force?: boolean;
+}
+export declare const withScale: <T extends VListItem = VListItem>(config?: ScaleConfig) => VListFeature<T>;
+//# sourceMappingURL=feature.d.ts.map

package/dist/features/scale/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * vlist - Compression Sub-module
+ * Re-exports compression utilities for tree-shakeable imports
+ *
+ * Usage: import { getCompressionInfo } from 'vlist/compression'
+ * Usage: import { withScale } from 'vlist/compression'
+ */
+export { MAX_VIRTUAL_SIZE, getCompressionState, needsCompression, getMaxItemsWithoutCompression, getCompressionInfo, calculateCompressedVisibleRange, calculateCompressedRenderRange, calculateCompressedItemPosition, calculateCompressedScrollToIndex, calculateIndexFromScrollPosition, type CompressionState, } from "../../rendering/scale";
+export { withScale, type ScaleConfig } from "./feature";
+//# sourceMappingURL=index.d.ts.map

package/dist/features/scrollbar/controller.d.ts

@@ -0,0 +1,121 @@
+/**
+ * vlist - Scroll Controller
+ * Handles both native scrolling and manual wheel-based scrolling for compressed lists
+ *
+ * When compression is active (large lists exceeding browser height limits),
+ * we switch from native scrolling to manual wheel event handling.
+ * This allows smooth scrolling through millions of items.
+ */
+import type { CompressionState } from "../../rendering/scale";
+/** Scroll direction */
+export type ScrollDirection = "up" | "down";
+/** Scroll event data */
+export interface ScrollEventData {
+    scrollTop: number;
+    direction: ScrollDirection;
+    velocity: number;
+}
+/** Scroll controller configuration */
+export interface ScrollControllerConfig {
+    /** Enable compressed scroll mode (manual wheel handling) */
+    compressed?: boolean;
+    /** Compression state for calculating bounds */
+    compression?: CompressionState;
+    /**
+     * External scroll element for window/document scrolling.
+     * When set, the controller listens to this element's scroll events
+     * and computes list-relative positions from the viewport's bounding rect.
+     */
+    scrollElement?: Window;
+    /** Allow mouse wheel to scroll (default: true) */
+    wheel?: boolean;
+    /** Wheel sensitivity multiplier (default: 1) */
+    sensitivity?: number;
+    /** Enable smooth scrolling interpolation */
+    smoothing?: boolean;
+    /** Scroll idle detection timeout in ms (default: 150) */
+    idleTimeout?: number;
+    /**
+     * Enable horizontal scrolling mode.
+     * When true, the controller reads scrollLeft instead of scrollTop,
+     * uses clientWidth instead of clientHeight, and maps wheel deltaX.
+     */
+    horizontal?: boolean;
+    /** Callback when scroll position changes */
+    onScroll?: (data: ScrollEventData) => void;
+    /** Callback when scrolling becomes idle */
+    onIdle?: () => void;
+}
+/** Scroll controller instance */
+export interface ScrollController {
+    /** Get current scroll position */
+    getScrollTop: () => number;
+    /** Set scroll position */
+    scrollTo: (position: number, smooth?: boolean) => void;
+    /** Scroll by delta */
+    scrollBy: (delta: number) => void;
+    /** Check if at top */
+    isAtTop: () => boolean;
+    /** Check if at bottom */
+    isAtBottom: (threshold?: number) => boolean;
+    /** Get scroll percentage (0-1) */
+    getScrollPercentage: () => number;
+    /** Get current scroll velocity (px/ms, absolute value) */
+    getVelocity: () => number;
+    /**
+     * Check if the velocity tracker is actively tracking with enough samples.
+     * Returns false during ramp-up (first few frames of a new scroll gesture)
+     * when the tracker doesn't have enough samples yet.
+     */
+    isTracking: () => boolean;
+    /** Check if currently scrolling */
+    isScrolling: () => boolean;
+    /** Update configuration (e.g., when compression state changes) */
+    updateConfig: (config: Partial<ScrollControllerConfig>) => void;
+    /** Enable compressed mode */
+    enableCompression: (compression: CompressionState) => void;
+    /** Disable compressed mode (revert to native scroll) */
+    disableCompression: () => void;
+    /** Check if compressed mode is active */
+    isCompressed: () => boolean;
+    /** Check if in window scroll mode */
+    isWindowMode: () => boolean;
+    /**
+     * Update the container height used for scroll calculations.
+     * In window mode, call this when the window resizes.
+     */
+    updateContainerHeight: (height: number) => void;
+    /** Destroy and cleanup */
+    destroy: () => void;
+}
+/**
+ * Create a scroll controller for a viewport element
+ *
+ * Supports two modes:
+ * 1. Native scrolling (default) - uses browser's built-in scroll
+ * 2. Compressed scrolling - manual wheel handling for large lists
+ */
+export declare const createScrollController: (viewport: HTMLElement, config?: ScrollControllerConfig) => ScrollController;
+/**
+ * Throttle scroll handler using requestAnimationFrame
+ */
+export declare const rafThrottle: <T extends (...args: any[]) => void>(fn: T) => ((...args: Parameters<T>) => void) & {
+    cancel: () => void;
+};
+/**
+ * Check if scroll position is at bottom
+ */
+export declare const isAtBottom: (scrollTop: number, scrollHeight: number, clientHeight: number, threshold?: number) => boolean;
+/**
+ * Check if scroll position is at top
+ */
+export declare const isAtTop: (scrollTop: number, threshold?: number) => boolean;
+/**
+ * Get scroll percentage (0-1)
+ */
+export declare const getScrollPercentage: (scrollTop: number, scrollHeight: number, clientHeight: number) => number;
+/**
+ * Check if a range is visible in the scroll viewport
+ */
+export declare const isRangeVisible: (rangeStart: number, rangeEnd: number, visibleStart: number, visibleEnd: number) => boolean;
+//# sourceMappingURL=controller.d.ts.map

package/dist/features/scrollbar/feature.d.ts

@@ -0,0 +1,60 @@
+/**
+ * vlist/scroll - Builder Feature
+ * Wraps the custom scrollbar into a VListFeature for the composable builder.
+ *
+ * Priority: 30 (runs after renderer/data setup but before selection)
+ *
+ * What it wires:
+ * - DOM elements — track, thumb, and optional hover zone appended to viewport
+ * - CSS class — .vlist-viewport--custom-scrollbar hides native scrollbar
+ * - Drag handlers — mousedown on thumb, mousemove/mouseup on document
+ * - Track click — click on track to jump to position
+ * - Hover handlers — mouseenter/leave on track, hover zone, and viewport
+ * - Scroll sync — updates thumb position on every scroll frame
+ * - Resize sync — updates thumb size when container or content height changes
+ *
+ * No public methods are added — the scrollbar is entirely automatic.
+ */
+import type { VListItem } from "../../types";
+import type { VListFeature } from "../../builder/types";
+/** Scrollbar feature configuration */
+export interface ScrollbarFeatureConfig {
+    /** Auto-hide scrollbar after idle (default: true) */
+    autoHide?: boolean;
+    /** Auto-hide delay in milliseconds (default: 1000) */
+    autoHideDelay?: number;
+    /** Minimum thumb size in pixels (default: 30) */
+    minThumbSize?: number;
+    /**
+     * Show scrollbar when hovering near the scrollbar edge (default: true).
+     * When true, an invisible hover zone is placed along the scrollbar edge.
+     */
+    showOnHover?: boolean;
+    /**
+     * Width of the invisible hover zone in pixels (default: 16).
+     * Only used when `showOnHover` is true.
+     */
+    hoverZoneWidth?: number;
+    /**
+     * Show scrollbar when the mouse enters the list viewport (default: true).
+     * When false, the scrollbar only appears on scroll or hover near edge.
+     */
+    showOnViewportEnter?: boolean;
+}
+/**
+ * Create a scrollbar feature for the builder.
+ *
+ * Replaces the native browser scrollbar with a custom, cross-browser
+ * consistent scrollbar.
+ *
+ * ```ts
+ * import { vlist } from 'vlist/builder'
+ * import { withScrollbar } from 'vlist/scroll'
+ *
+ * const list = vlist({ ... })
+ *   .use(withScrollbar({ autoHide: true, autoHideDelay: 1000 }))
+ *   .build()
+ * ```
+ */
+export declare const withScrollbar: <T extends VListItem = VListItem>(config?: ScrollbarFeatureConfig) => VListFeature<T>;
+//# sourceMappingURL=feature.d.ts.map

package/dist/features/scrollbar/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * vlist - Scroll Domain
+ * Scroll controller and custom scrollbar
+ */
+export { withScrollbar, type ScrollbarFeatureConfig } from "./feature";
+export { createScrollController, rafThrottle, isAtBottom, isAtTop, getScrollPercentage, isRangeVisible, type ScrollController, type ScrollControllerConfig, type ScrollEventData, type ScrollDirection, } from "./controller";
+export { createScrollbar, type Scrollbar, type ScrollbarConfig, type ScrollCallback, } from "./scrollbar";
+//# sourceMappingURL=index.d.ts.map