vlist 3.0.0-next.1 → 3.0.0-next.3

package/dist/types.d.ts

@@ -4,10 +4,13 @@
  */
 /** Base event map with index signature */
 export type EventMap = Record<string, unknown>;
-/** Base item interface - must have an id */
+/**
+ * Base item interface: an item only has to carry an id. Plugins that read
+ * arbitrary fields (search, table, tree) narrow the item themselves, so an
+ * ordinary `interface Row { id: number; name: string }` satisfies this.
+ */
 export interface VListItem {
     id: string | number;
-    [key: string]: unknown;
 }
 /** Groups configuration for createVList */
 export interface GroupHeaderConfig {
@@ -291,8 +294,11 @@ export interface ScrollConfig {
      * Useful for carousels, wizards, and circular navigation.
      */
     wrap?: boolean;
-    /** Options consumed by vlist/config; use scrollbar() with the core factory. */
-    scrollbar?: ScrollbarOptions;
+    /** Native visibility: "none" hides the browser scrollbar, "native" keeps it.
+     * Options are consumed by vlist/config; with the low-level factory install
+     * scrollbar() explicitly. The synthetic entry rejects both string values.
+     */
+    scrollbar?: "native" | "none" | ScrollbarOptions;
     /** External scroll element for window scrolling */
     element?: Window;
     /** Scroll idle detection timeout in ms (default: 150) */
@@ -338,20 +344,6 @@ export type ScrollbarPadding = number | {
     bottom?: number;
     left?: number;
 };
-/**
- * Scrollbar configuration.
- * @deprecated Use `scroll.scrollbar` in `ScrollConfig` instead.
- */
-export interface ScrollbarConfig {
-    /** Enable scrollbar (default: true) */
-    enabled?: boolean;
-    /** 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;
-}
 /** Item template function */
 export type ItemTemplate<T = VListItem> = (item: T, index: number, state: ItemState) => string | HTMLElement;
 /** Tree-specific state available in templates when the tree plugin is active */
@@ -465,19 +457,23 @@ export interface ErrorViewportSnapshot {
 }
 /** Event types and their payloads */
 export interface VListEvents<T extends VListItem = VListItem> extends EventMap {
-    /** Item clicked */
+    /**
+     * Item clicked. `index` is the DATA index — what `getItemAt`,
+     * `scrollToIndex` and `removeItem` take — not the layout index, which counts
+     * group headers and carousel laps as well.
+     */
     "item:click": {
         item: T;
         index: number;
         event: MouseEvent;
     };
-    /** Item double-clicked */
+    /** Item double-clicked. `index` is the data index, as for `item:click`. */
     "item:dblclick": {
         item: T;
         index: number;
         event: MouseEvent;
     };
-    /** Item right-clicked */
+    /** Item right-clicked. `index` is the data index, as for `item:click`. */
     "item:contextmenu": {
         item: T;
         index: number;

package/dist/utils/scroll-padding.d.ts

@@ -0,0 +1,36 @@
+/**
+ * vlist/utils — Scroll Padding Protocol
+ *
+ * page() keeps a band of the window clear at each end of the main axis — a
+ * sticky site header, a floating toolbar — and applies it to every scroll it
+ * computes. Layout plugins take over those computations: groups() and
+ * masonry() both override `_scrollItemIntoView` and install their own
+ * `setToIndexFn`, because only they know where an entry actually sits.
+ *
+ * So the band is published through the `_getScrollPadding` hook rather than
+ * baked into page's own scroll code alone, and the plugins that displace page
+ * read it back and fold it into their geometry. Without the hook a caller's
+ * `scrollPadding` silently disappeared as soon as either plugin was seated.
+ */
+import type { PluginContext } from "../core/types";
+import type { VListItem } from "../types";
+/** Band to keep clear at each end of the main axis, in pixels. */
+export interface ScrollPadding {
+    /** Top (vertical) or left (horizontal). */
+    readonly start: number;
+    /** Bottom (vertical) or right (horizontal). */
+    readonly end: number;
+}
+/** Internal hook name carrying the band across plugins. */
+export declare const SCROLL_PADDING_HOOK = "_getScrollPadding";
+/** No padding — the shape every list without page() sees. */
+export declare const NO_SCROLL_PADDING: ScrollPadding;
+/**
+ * Read the published scroll padding, or zero when no plugin publishes one.
+ *
+ * The hook is resolved on first read instead of during setup: the publisher is
+ * not guaranteed to be seated first. The band itself is read on every call,
+ * since page() accepts functions that measure a sticky header each time.
+ */
+export declare function createScrollPaddingReader<T extends VListItem>(ctx: PluginContext<T>): () => ScrollPadding;
+//# sourceMappingURL=scroll-padding.d.ts.map

package/dist/utils/stats.d.ts

@@ -1,5 +1,5 @@
 export interface StatsConfig {
-    /** Returns the current scroll position (scrollTop or scrollLeft) */
+    /** Returns the unscaled logical position, normally list.getScrollPosition(). */
     getScrollPosition: () => number;
     /** Returns the total number of items */
     getTotal: () => number;
@@ -33,6 +33,14 @@ export interface Stats {
  *
  * All inputs are provided via callbacks so the tracker always reflects
  * the latest values without needing to be recreated when the list changes.
+ * Position is an unscaled logical offset on both native and synthetic entries,
+ * clamped to the declared content's real scroll range. Progress counts items up
+ * to the viewport end (including partial rows), rather than just scroll distance.
+ *
+ * Native content beyond the browser limit still uses its full declared size:
+ * a browser-clamped position is not expanded to the end, so progress may never
+ * reach 100%. Handle the core's `content:size:overflow` error and use
+ * `vlist/synthetic` when the full range must remain reachable.
  *
  * ```ts
  * const stats = createStats({

package/dist/vlist.css

@@ -1 +1 @@
-@keyframes vlist-fade-in{from{opacity:0.6}to{opacity:1}}@keyframes vlist-placeholder-pulse{0%,100%{opacity:0.6}50%{opacity:0.4}}:root{--vlist-scrollbar-width:8px;--vlist-scrollbar-track-color:transparent;--vlist-scrollbar-radius:4px;--vlist-custom-scrollbar-track-color:transparent;--vlist-custom-scrollbar-padding-top:2px;--vlist-custom-scrollbar-padding-right:2px;--vlist-custom-scrollbar-padding-bottom:2px;--vlist-custom-scrollbar-padding-left:2px;--vlist-custom-scrollbar-min-thumb-size:15px;--vlist-item-padding-x:1rem;--vlist-item-padding-y:0.75rem;--vlist-border-radius:0.5rem;--vlist-transition-duration:150ms;--vlist-transition-timing:ease-in-out;--vlist-bg:#ffffff;--vlist-bg-hover:rgba(0,0,0,0.04);--vlist-bg-striped:rgba(0,0,0,0.02);--vlist-bg-selected:rgba(59,130,246,0.12);--vlist-bg-selected-hover:rgba(59,130,246,0.18);--vlist-border:#e5e7eb;--vlist-border-selected:#3b82f6;--vlist-text:#111827;--vlist-text-muted:#6b7280;--vlist-focus-ring:#3b82f6;--vlist-group-header-bg:#f3f4f6;--vlist-scrollbar-thumb-color:#d1d5db;--vlist-scrollbar-thumb-hover-color:#9ca3af;--vlist-custom-scrollbar-thumb-color:rgba(0,0,0,0.2);--vlist-custom-scrollbar-thumb-hover-color:rgba(0,0,0,0.3);--vlist-placeholder-bg:rgba(0,0,0,0.2);--vlist-placeholder-bg-strong:rgba(0,0,0,0.24)}[data-theme-mode="dark"]{--vlist-bg:#111827;--vlist-bg-hover:rgba(255,255,255,0.06);--vlist-bg-striped:rgba(255,255,255,0.02);--vlist-bg-selected:rgba(59,130,246,0.2);--vlist-bg-selected-hover:rgba(59,130,246,0.28);--vlist-border:#374151;--vlist-border-selected:#3b82f6;--vlist-text:#f9fafb;--vlist-text-muted:#9ca3af;--vlist-focus-ring:#3b82f6;--vlist-group-header-bg:#1e2433;--vlist-scrollbar-thumb-color:#4b5563;--vlist-scrollbar-thumb-hover-color:#6b7280;--vlist-custom-scrollbar-thumb-color:rgba(255,255,255,0.2);--vlist-custom-scrollbar-thumb-hover-color:rgba(255,255,255,0.3);--vlist-placeholder-bg:rgba(255,255,255,0.3);--vlist-placeholder-bg-strong:rgba(255,255,255,0.35)}@media (prefers-color-scheme:dark){:root:not([data-theme-mode="light"]):not([data-theme-mode="dark"]){--vlist-bg:#111827;--vlist-bg-hover:rgba(255,255,255,0.06);--vlist-bg-striped:rgba(255,255,255,0.02);--vlist-bg-selected:rgba(59,130,246,0.2);--vlist-bg-selected-hover:rgba(59,130,246,0.28);--vlist-border:#374151;--vlist-border-selected:#3b82f6;--vlist-text:#f9fafb;--vlist-text-muted:#9ca3af;--vlist-focus-ring:#3b82f6;--vlist-group-header-bg:#1e2433;--vlist-scrollbar-thumb-color:#4b5563;--vlist-scrollbar-thumb-hover-color:#6b7280;--vlist-custom-scrollbar-thumb-color:rgba(255,255,255,0.2);--vlist-custom-scrollbar-thumb-hover-color:rgba(255,255,255,0.3);--vlist-placeholder-bg:rgba(255,255,255,0.3);--vlist-placeholder-bg-strong:rgba(255,255,255,0.35)}}.dark{--vlist-bg:#111827;--vlist-bg-hover:rgba(255,255,255,0.06);--vlist-bg-striped:rgba(255,255,255,0.02);--vlist-bg-selected:rgba(59,130,246,0.2);--vlist-bg-selected-hover:rgba(59,130,246,0.28);--vlist-border:#374151;--vlist-border-selected:#3b82f6;--vlist-text:#f9fafb;--vlist-text-muted:#9ca3af;--vlist-focus-ring:#3b82f6;--vlist-group-header-bg:#1e2433;--vlist-scrollbar-thumb-color:#4b5563;--vlist-scrollbar-thumb-hover-color:#6b7280;--vlist-custom-scrollbar-thumb-color:rgba(255,255,255,0.2);--vlist-custom-scrollbar-thumb-hover-color:rgba(255,255,255,0.3);--vlist-placeholder-bg:rgba(255,255,255,0.3);--vlist-placeholder-bg-strong:rgba(255,255,255,0.35)}.vlist{position:relative;width:100%;height:100%;box-sizing:border-box;overflow:hidden;background-color:var(--vlist-bg);color:var(--vlist-text);color-scheme:light;border:1px solid var(--vlist-border);border-radius:var(--vlist-border-radius);outline:none}[data-theme-mode="dark"] .vlist,.dark .vlist{color-scheme:dark}@media (prefers-color-scheme:dark){:root:not([data-theme-mode="light"]) .vlist{color-scheme:dark}}.vlist:focus,.vlist:focus-visible,.vlist-content:focus,.vlist-content:focus-visible{outline:none}.vlist-viewport{width:100%;height:100%;overflow:auto;scrollbar-color:var(--vlist-scrollbar-thumb-color) var(--vlist-scrollbar-track-color)}@supports (-moz-appearance:none) and (scrollbar-width:1px){.vlist-viewport{scrollbar-width:var(--vlist-scrollbar-width)}}.vlist-viewport::-webkit-scrollbar{width:var(--vlist-scrollbar-width);height:var(--vlist-scrollbar-width)}.vlist-viewport::-webkit-scrollbar-track{background:var(--vlist-scrollbar-track-color)}.vlist-viewport::-webkit-scrollbar-thumb{background-color:var(--vlist-scrollbar-thumb-color);border-radius:var(--vlist-scrollbar-radius)}.vlist-viewport::-webkit-scrollbar-thumb:hover{background-color:var(--vlist-scrollbar-thumb-hover-color)}.vlist-content{position:relative;width:100%;contain:layout style}.vlist-item,.vlist-group-header{position:absolute;top:0;left:0;right:0;display:flex;align-items:center;background-color:var(--vlist-bg);cursor:default;user-select:none;opacity:1;transition:background-color var(--vlist-transition-duration) var(--vlist-transition-timing),opacity var(--vlist-transition-duration) var(--vlist-transition-timing);contain:content;box-sizing:border-box;will-change:transform}.vlist--scrolling .vlist-item,.vlist--settling .vlist-item,.vlist--scrolling .vlist-group-header,.vlist--settling .vlist-group-header{transition:none}.vlist--selectable .vlist-item{cursor:pointer}.vlist--selectable .vlist-item:hover{background-color:var(--vlist-bg-hover)}.vlist-item.vlist-item--odd{background:var(--vlist-bg-striped)}.vlist-item.vlist-item--selected{background-color:var(--vlist-bg-selected)}.vlist-item.vlist-item--odd.vlist-item--selected{background:var(--vlist-bg-selected)}.vlist-item.vlist-item--selected:hover{background-color:var(--vlist-bg-selected-hover)}.vlist-item.vlist-item--odd.vlist-item--selected:hover{background:var(--vlist-bg-selected-hover)}.vlist-item.vlist-item--focused{outline:2px solid var(--vlist-focus-ring,#3b82f6);outline-offset:-2px;z-index:1}.vlist-item--replaced{animation:vlist-fade-in 0.3s ease-out}.vlist-item--placeholder{opacity:0.6;animation:vlist-placeholder-pulse 2s ease-in-out infinite}.vlist-item--placeholder *:not(:has(*)){color:transparent;background-color:var(--vlist-placeholder-bg);border-radius:4px;width:fit-content;line-height:1.2;transform:scaleY(0.8)}.vlist-item--placeholder:is(strong,b,h1,h2,h3,h4):not(:has(*)){background-color:var(--vlist-placeholder-bg-strong)}.vlist-item.vlist-item--selected.vlist-item--focused{outline-color:var(--vlist-border-selected)}.vlist-scrollbar:focus-visible{outline:2px solid currentColor;outline-offset:-2px;opacity:1;pointer-events:auto}.vlist-scrollbar{position:absolute;top:var(--vlist-custom-scrollbar-padding-top);right:var(--vlist-custom-scrollbar-padding-right);bottom:var(--vlist-custom-scrollbar-padding-bottom);width:var(--vlist-custom-scrollbar-width);background-color:var(--vlist-custom-scrollbar-track-color);opacity:0;transition:opacity 0.2s ease-out;touch-action:none;z-index:10;pointer-events:none}.vlist-scrollbar__hover{position:absolute;top:0;right:0;height:100%;z-index:9;touch-action:none;pointer-events:auto}.vlist-scrollbar__hover--horizontal{top:auto;right:auto;bottom:0;left:0;width:100%;height:auto}.vlist-scrollbar--visible{opacity:1;pointer-events:auto}.vlist-scrollbar__thumb{position:absolute;top:0;left:0;right:0;width:100%;background-color:var(--vlist-custom-scrollbar-thumb-color);border-radius:var(--vlist-custom-scrollbar-radius);cursor:pointer;transition:background-color 0.15s ease-out}.vlist-scrollbar__thumb:hover{background-color:var(--vlist-custom-scrollbar-thumb-hover-color)}.vlist-scrollbar--dragging{opacity:1;pointer-events:auto}.vlist-scrollbar--dragging .vlist-scrollbar__thumb{background-color:var(--vlist-custom-scrollbar-thumb-hover-color)}@media (forced-colors:active){.vlist-scrollbar{forced-color-adjust:none;background-color:Canvas}.vlist-scrollbar__thumb{background-color:CanvasText}.vlist-scrollbar__thumb:hover,.vlist-scrollbar--dragging .vlist-scrollbar__thumb{background-color:Highlight}.vlist-scrollbar:focus-visible{outline-color:Highlight}}.vlist-group-header{cursor:default;background-color:var(--vlist-group-header-bg,#f3f4f6);z-index:1;overflow:hidden}.vlist-group-header:hover{background-color:var(--vlist-group-header-bg,#f3f4f6)}.vlist-sticky-header{left:0;right:0;background-color:var(--vlist-group-header-bg,#f3f4f6)}.vlist--horizontal{overflow:hidden}.vlist--horizontal .vlist-viewport{overflow-x:auto;overflow-y:hidden}.vlist--horizontal .vlist-content{height:100%;width:auto}.vlist--horizontal .vlist-item,.vlist--horizontal .vlist-group-header{position:absolute;top:0;bottom:0;left:0;right:auto;display:flex;align-items:center;justify-content:center;border-bottom:none}.vlist-scrollbar--horizontal{top:auto;left:var(--vlist-custom-scrollbar-padding-left);right:var(--vlist-custom-scrollbar-padding-right);bottom:var(--vlist-custom-scrollbar-padding-bottom);width:auto;height:var(--vlist-custom-scrollbar-width)}.vlist-scrollbar--horizontal .vlist-scrollbar__thumb{top:0;left:0;width:auto;height:100%}.vlist-viewport--gutter{padding-right:calc( var(--vlist-custom-scrollbar-padding-right) + var(--vlist-custom-scrollbar-width) + var(--vlist-custom-scrollbar-padding-left) )}.vlist--horizontal .vlist-viewport--gutter{padding-right:0;padding-bottom:calc( var(--vlist-custom-scrollbar-padding-bottom) + var(--vlist-custom-scrollbar-width) + var(--vlist-custom-scrollbar-padding-top) )}.vlist-viewport--custom-scrollbar{scrollbar-width:none;-ms-overflow-style:none}.vlist-viewport--custom-scrollbar::-webkit-scrollbar{display:none}.vlist-viewport--no-scrollbar{scrollbar-width:none;-ms-overflow-style:none}.vlist-viewport--no-scrollbar::-webkit-scrollbar{display:none}.vlist-viewport--gutter-stable{scrollbar-gutter:stable}.vlist-sort-ghost{opacity:0.85;box-shadow:0 4px 16px rgba(0,0,0,0.18);cursor:grabbing}.vlist-item--drag-source{opacity:0 !important;pointer-events:none}.vlist--sorting{cursor:grabbing;-webkit-user-select:none;user-select:none;-webkit-touch-callout:none}.vlist--sorting *{cursor:inherit !important}.vlist-item--kb-sorting{outline:2px solid var(--vlist-focus-ring,#3b82f6);outline-offset:-2px;background-color:var(--vlist-bg-selected);z-index:1}
+@keyframes vlist-fade-in{from{opacity:0.6}to{opacity:1}}@keyframes vlist-placeholder-pulse{0%,100%{opacity:0.6}50%{opacity:0.4}}:root{--vlist-scrollbar-width:8px;--vlist-scrollbar-track-color:transparent;--vlist-scrollbar-radius:4px;--vlist-custom-scrollbar-track-color:transparent;--vlist-custom-scrollbar-padding-top:2px;--vlist-custom-scrollbar-padding-right:2px;--vlist-custom-scrollbar-padding-bottom:2px;--vlist-custom-scrollbar-padding-left:2px;--vlist-custom-scrollbar-min-thumb-size:15px;--vlist-item-padding-x:1rem;--vlist-item-padding-y:0.75rem;--vlist-border-radius:0.5rem;--vlist-transition-duration:150ms;--vlist-transition-timing:ease-in-out;--vlist-bg:#ffffff;--vlist-bg-hover:rgba(0,0,0,0.04);--vlist-bg-striped:rgba(0,0,0,0.02);--vlist-bg-selected:rgba(59,130,246,0.12);--vlist-bg-selected-hover:rgba(59,130,246,0.18);--vlist-border:#e5e7eb;--vlist-border-selected:#3b82f6;--vlist-text:#111827;--vlist-text-muted:#6b7280;--vlist-focus-ring:#3b82f6;--vlist-group-header-bg:#f3f4f6;--vlist-scrollbar-thumb-color:#d1d5db;--vlist-scrollbar-thumb-hover-color:#9ca3af;--vlist-custom-scrollbar-thumb-color:rgba(0,0,0,0.2);--vlist-custom-scrollbar-thumb-hover-color:rgba(0,0,0,0.3);--vlist-placeholder-bg:rgba(0,0,0,0.2);--vlist-placeholder-bg-strong:rgba(0,0,0,0.24)}[data-theme-mode="dark"]{--vlist-bg:#111827;--vlist-bg-hover:rgba(255,255,255,0.06);--vlist-bg-striped:rgba(255,255,255,0.02);--vlist-bg-selected:rgba(59,130,246,0.2);--vlist-bg-selected-hover:rgba(59,130,246,0.28);--vlist-border:#374151;--vlist-border-selected:#3b82f6;--vlist-text:#f9fafb;--vlist-text-muted:#9ca3af;--vlist-focus-ring:#3b82f6;--vlist-group-header-bg:#1e2433;--vlist-scrollbar-thumb-color:#4b5563;--vlist-scrollbar-thumb-hover-color:#6b7280;--vlist-custom-scrollbar-thumb-color:rgba(255,255,255,0.2);--vlist-custom-scrollbar-thumb-hover-color:rgba(255,255,255,0.3);--vlist-placeholder-bg:rgba(255,255,255,0.3);--vlist-placeholder-bg-strong:rgba(255,255,255,0.35)}@media (prefers-color-scheme:dark){:root:not([data-theme-mode="light"]):not([data-theme-mode="dark"]){--vlist-bg:#111827;--vlist-bg-hover:rgba(255,255,255,0.06);--vlist-bg-striped:rgba(255,255,255,0.02);--vlist-bg-selected:rgba(59,130,246,0.2);--vlist-bg-selected-hover:rgba(59,130,246,0.28);--vlist-border:#374151;--vlist-border-selected:#3b82f6;--vlist-text:#f9fafb;--vlist-text-muted:#9ca3af;--vlist-focus-ring:#3b82f6;--vlist-group-header-bg:#1e2433;--vlist-scrollbar-thumb-color:#4b5563;--vlist-scrollbar-thumb-hover-color:#6b7280;--vlist-custom-scrollbar-thumb-color:rgba(255,255,255,0.2);--vlist-custom-scrollbar-thumb-hover-color:rgba(255,255,255,0.3);--vlist-placeholder-bg:rgba(255,255,255,0.3);--vlist-placeholder-bg-strong:rgba(255,255,255,0.35)}}.dark{--vlist-bg:#111827;--vlist-bg-hover:rgba(255,255,255,0.06);--vlist-bg-striped:rgba(255,255,255,0.02);--vlist-bg-selected:rgba(59,130,246,0.2);--vlist-bg-selected-hover:rgba(59,130,246,0.28);--vlist-border:#374151;--vlist-border-selected:#3b82f6;--vlist-text:#f9fafb;--vlist-text-muted:#9ca3af;--vlist-focus-ring:#3b82f6;--vlist-group-header-bg:#1e2433;--vlist-scrollbar-thumb-color:#4b5563;--vlist-scrollbar-thumb-hover-color:#6b7280;--vlist-custom-scrollbar-thumb-color:rgba(255,255,255,0.2);--vlist-custom-scrollbar-thumb-hover-color:rgba(255,255,255,0.3);--vlist-placeholder-bg:rgba(255,255,255,0.3);--vlist-placeholder-bg-strong:rgba(255,255,255,0.35)}.vlist{position:relative;width:100%;height:100%;box-sizing:border-box;overflow:hidden;background-color:var(--vlist-bg);color:var(--vlist-text);color-scheme:light;border:1px solid var(--vlist-border);border-radius:var(--vlist-border-radius);outline:none}[data-theme-mode="dark"] .vlist,.dark .vlist{color-scheme:dark}@media (prefers-color-scheme:dark){:root:not([data-theme-mode="light"]) .vlist{color-scheme:dark}}.vlist:focus,.vlist:focus-visible,.vlist-content:focus,.vlist-content:focus-visible{outline:none}.vlist-viewport{width:100%;height:100%;overflow:auto;scrollbar-color:var(--vlist-scrollbar-thumb-color) var(--vlist-scrollbar-track-color)}@supports (-moz-appearance:none) and (scrollbar-width:1px){.vlist-viewport{scrollbar-width:var(--vlist-scrollbar-width)}}.vlist-viewport::-webkit-scrollbar{width:var(--vlist-scrollbar-width);height:var(--vlist-scrollbar-width)}.vlist-viewport::-webkit-scrollbar-track{background:var(--vlist-scrollbar-track-color)}.vlist-viewport::-webkit-scrollbar-thumb{background-color:var(--vlist-scrollbar-thumb-color);border-radius:var(--vlist-scrollbar-radius)}.vlist-viewport::-webkit-scrollbar-thumb:hover{background-color:var(--vlist-scrollbar-thumb-hover-color)}.vlist-content{position:relative;width:100%;contain:layout style}.vlist-item,.vlist-group-header{position:absolute;top:0;left:0;right:0;display:flex;align-items:center;background-color:var(--vlist-bg);cursor:default;user-select:none;opacity:1;transition:background-color var(--vlist-transition-duration) var(--vlist-transition-timing),opacity var(--vlist-transition-duration) var(--vlist-transition-timing);contain:content;box-sizing:border-box;will-change:transform}.vlist--scrolling .vlist-item,.vlist--settling .vlist-item,.vlist--scrolling .vlist-group-header,.vlist--settling .vlist-group-header{transition:none}.vlist--selectable .vlist-item{cursor:pointer}.vlist--selectable .vlist-item:hover{background-color:var(--vlist-bg-hover)}.vlist-item.vlist-item--odd{background:var(--vlist-bg-striped)}.vlist-item.vlist-item--selected{background-color:var(--vlist-bg-selected)}.vlist-item.vlist-item--odd.vlist-item--selected{background:var(--vlist-bg-selected)}.vlist-item.vlist-item--selected:hover{background-color:var(--vlist-bg-selected-hover)}.vlist-item.vlist-item--odd.vlist-item--selected:hover{background:var(--vlist-bg-selected-hover)}.vlist-item.vlist-item--focused{outline:2px solid var(--vlist-focus-ring,#3b82f6);outline-offset:-2px;z-index:1}.vlist-item--replaced{animation:vlist-fade-in 0.3s ease-out}.vlist-item--placeholder{opacity:0.6;animation:vlist-placeholder-pulse 2s ease-in-out infinite}.vlist-item--placeholder *:not(:has(*)){color:transparent;background-color:var(--vlist-placeholder-bg);border-radius:4px;width:fit-content;line-height:1.2;transform:scaleY(0.8)}.vlist-item--placeholder:is(strong,b,h1,h2,h3,h4):not(:has(*)){background-color:var(--vlist-placeholder-bg-strong)}.vlist-item.vlist-item--selected.vlist-item--focused{outline-color:var(--vlist-border-selected)}.vlist-scrollbar:focus-visible{outline:2px solid currentColor;outline-offset:-2px;opacity:1;pointer-events:auto}.vlist-scrollbar{position:absolute;top:var(--vlist-custom-scrollbar-padding-top);right:var(--vlist-custom-scrollbar-padding-right);bottom:var(--vlist-custom-scrollbar-padding-bottom);width:var(--vlist-custom-scrollbar-width);background-color:var(--vlist-custom-scrollbar-track-color);opacity:0;transition:opacity 0.2s ease-out;touch-action:none;z-index:10;pointer-events:none}.vlist-scrollbar__hover{position:absolute;top:0;right:0;height:100%;z-index:9;touch-action:none;pointer-events:auto}.vlist-scrollbar__hover--horizontal{top:auto;right:auto;bottom:0;left:0;width:100%;height:auto}.vlist-scrollbar--visible{opacity:1;pointer-events:auto}.vlist-scrollbar__thumb{position:absolute;top:0;left:0;right:0;width:100%;background-color:var(--vlist-custom-scrollbar-thumb-color);border-radius:var(--vlist-custom-scrollbar-radius);cursor:pointer;transition:background-color 0.15s ease-out}.vlist-scrollbar__thumb:hover{background-color:var(--vlist-custom-scrollbar-thumb-hover-color)}.vlist-scrollbar--dragging{opacity:1;pointer-events:auto}.vlist-scrollbar--dragging .vlist-scrollbar__thumb{background-color:var(--vlist-custom-scrollbar-thumb-hover-color)}@media (forced-colors:active){.vlist-scrollbar{forced-color-adjust:none;background-color:Canvas}.vlist-scrollbar__thumb{background-color:CanvasText}.vlist-scrollbar__thumb:hover,.vlist-scrollbar--dragging .vlist-scrollbar__thumb{background-color:Highlight}.vlist-scrollbar:focus-visible{outline-color:Highlight}}.vlist-group-header{cursor:default;background-color:var(--vlist-group-header-bg,#f3f4f6);z-index:1;overflow:hidden}.vlist-group-header:hover{background-color:var(--vlist-group-header-bg,#f3f4f6)}.vlist-sticky-header{left:0;right:0;background-color:var(--vlist-group-header-bg,#f3f4f6)}.vlist--horizontal{overflow:hidden}.vlist--horizontal .vlist-viewport{overflow-x:auto;overflow-y:hidden}.vlist--horizontal .vlist-content{height:100%;width:auto}.vlist--horizontal .vlist-item,.vlist--horizontal .vlist-group-header{position:absolute;top:0;bottom:0;left:0;right:auto;display:flex;align-items:center;justify-content:center;border-bottom:none}.vlist-scrollbar--horizontal{top:auto;left:var(--vlist-custom-scrollbar-padding-left);right:var(--vlist-custom-scrollbar-padding-right);bottom:var(--vlist-custom-scrollbar-padding-bottom);width:auto;height:var(--vlist-custom-scrollbar-width)}.vlist-scrollbar--horizontal .vlist-scrollbar__thumb{top:0;left:0;width:auto;height:100%}.vlist-viewport--gutter{padding-right:calc( var(--vlist-custom-scrollbar-padding-right) + var(--vlist-custom-scrollbar-width) + var(--vlist-custom-scrollbar-padding-left) )}.vlist--horizontal .vlist-viewport--gutter{padding-right:0;padding-bottom:calc( var(--vlist-custom-scrollbar-padding-bottom) + var(--vlist-custom-scrollbar-width) + var(--vlist-custom-scrollbar-padding-top) )}.vlist-viewport--custom-scrollbar{scrollbar-width:none;-ms-overflow-style:none}.vlist-viewport--custom-scrollbar::-webkit-scrollbar{display:none}.vlist-viewport--no-scrollbar{scrollbar-width:none;-ms-overflow-style:none}.vlist-viewport--no-scrollbar::-webkit-scrollbar{display:none}.vlist-viewport--gutter-stable{scrollbar-gutter:stable}.vlist-sort-ghost{opacity:0.85;box-shadow:0 4px 16px rgba(0,0,0,0.18);cursor:grabbing}.vlist-item--touch-sort{-webkit-user-select:none;user-select:none;-webkit-touch-callout:none}.vlist-sort-ghost--touch{outline:2px solid var(--vlist-focus-ring,#3b82f6);outline-offset:2px}.vlist-item--drag-source{opacity:0 !important;pointer-events:none}.vlist--sorting{cursor:grabbing;-webkit-user-select:none;user-select:none;-webkit-touch-callout:none}.vlist--sorting *{cursor:inherit !important}.vlist-item--kb-sorting{outline:2px solid var(--vlist-focus-ring,#3b82f6);outline-offset:-2px;background-color:var(--vlist-bg-selected);z-index:1}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vlist",
-  "version": "3.0.0-next.1",
+  "version": "3.0.0-next.3",
   "description": "Lightweight, high-performance virtual list with zero dependencies",
   "author": {
     "name": "Floor IO",
@@ -79,12 +79,15 @@
     "dev": "bun run build.ts --watch",
     "test": "bun test",
     "test:changed": "bun test --changed",
-    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "test:browser": "bun scripts/rtl-cross-axis-browser.mjs && bun scripts/synthetic-browser.mjs && bun scripts/synthetic-carousel-browser.mjs && bun scripts/synthetic-sortable-browser.mjs",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.types.json && tsc --noEmit -p tsconfig.test.json",
     "bench": "bun run scripts/bench.ts",
     "bench:quick": "bun run scripts/bench.ts --quick",
     "bench:full": "bun run scripts/bench.ts --full",
     "bench:compare": "bun run scripts/bench.ts --quick --compare",
     "size": "bun run scripts/size.ts",
+    "heap": "bun run scripts/heap.ts",
+    "docs:check": "bun run scripts/docs-check.ts",
     "release": "bun run scripts/release.ts",
     "prepublishOnly": "bun run build -- --types && cp README.md README.github.md && cp npm-readme.md README.md",
     "postpublish": "cp README.github.md README.md && rm README.github.md"
@@ -99,6 +102,7 @@
     "@types/jsdom": "^27.0.0",
     "happy-dom": "^20.9.0",
     "jsdom": "^28.0.0",
+    "puppeteer-core": "^24.43.1",
     "typescript": "^5.0.0"
   }
 }

package/dist/plugins/grid/renderer.d.ts

@@ -1,68 +0,0 @@
-/**
- * vlist - Grid Renderer
- * Renders items in a 2D grid layout within the virtual scroll container.
- *
- * Extends the base renderer pattern but positions items using both
- * row offsets (translateY from the size cache) and column offsets
- * (translateX calculated from column index and container width).
- *
- * Key differences from the list renderer:
- * - Items are positioned with translate(x, y) instead of just translateY(y)
- * - Item width is set to columnWidth (containerWidth / columns - gaps)
- * - The "index" in the rendered map is the FLAT ITEM INDEX (not row index)
- * - Row offsets come from the size cache (which operates on row indices)
- * - Column offsets are calculated from itemIndex % columns
- *
- * Performance:
- * - Element pooling avoids createElement cost
- * - Template re-evaluation skipped when item data + state unchanged (change tracking)
- * - Position update skipped when coordinates unchanged (position tracking)
- * - 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
- * - DocumentFragment batched insertion for new elements
- */
-import type { VListItem, ItemTemplate, Range } from "../../types";
-import type { SizeCache } from "../../rendering/sizes";
-import type { GridLayout } from "./types";
-/** Grid renderer instance */
-export interface GridRenderer<T extends VListItem = VListItem> {
-    /** Render items for a flat item range, positioned in a 2D grid */
-    render: (items: T[], range: Range, selectedIds: Set<string | number>, focusedIndex: number) => void;
-    /** Update a single item (used by selection feature for focused item changes) */
-    updateItem: (index: number, item: T, isSelected: boolean, isFocused: boolean) => void;
-    /** Update only CSS classes on a rendered item (no template re-evaluation) */
-    updateItemClasses: (index: number, isSelected: boolean, isFocused: boolean) => void;
-    /** Get rendered item element by flat item index */
-    getElement: (index: number) => HTMLElement | undefined;
-    /**
-     * 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;
-    /** Update container width (call on resize) */
-    updateContainerWidth: (width: number) => void;
-    /** Clear all rendered items */
-    clear: () => void;
-    /** Destroy renderer and cleanup */
-    destroy: () => void;
-}
-/**
- * Create a grid renderer for managing DOM elements in a 2D layout.
- *
- * The grid renderer receives flat item ranges (not row ranges) and
- * positions each item at the correct (row, col) coordinate.
- *
- * @param itemsContainer - The DOM element that holds rendered items
- * @param template - Item template function
- * @param sizeCache - Size cache operating on ROW indices
- * @param gridLayout - Grid layout for row/col calculations
- * @param classPrefix - CSS class prefix
- * @param initialContainerWidth - Initial container width for column sizing
- * @param totalItemsGetter - Optional getter for total item count (for aria-setsize)
- * @param ariaIdPrefix - Optional unique prefix for element IDs (for aria-activedescendant)
- * @param isHorizontal - Whether layout is horizontal (scrolls right)
- */
-export declare const createGridRenderer: <T extends VListItem = VListItem>(itemsContainer: HTMLElement, template: ItemTemplate<T>, sizeCache: SizeCache, gridLayout: GridLayout, classPrefix: string, initialContainerWidth: number, totalItemsGetter?: () => number, ariaIdPrefix?: string, isHorizontal?: boolean, ariaPosInSetGetter?: (layoutIndex: number) => number, interactive?: boolean) => GridRenderer<T>;
-//# sourceMappingURL=renderer.d.ts.map