vlist 1.6.0 → 1.6.2

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

@@ -13,11 +13,56 @@
  * - Uses window.innerWidth/innerHeight for container dimensions
  * - Listens to window resize events instead of ResizeObserver
  * - Adjusts DOM styles (overflow: visible, height: auto)
+ * - Optionally accounts for fixed/sticky chrome via scrollPadding
+ * - Uses behavior: "instant" on all scrollTo calls to override CSS
+ *   scroll-behavior: smooth that may be set on the page
  *
  * Bundle impact: ~0.3 KB gzipped when used
  */
 import type { VListItem } from "../../types";
 import type { VListFeature } from "../../builder/types";
+/**
+ * Options for the window scroll mode feature.
+ */
+export interface WithPageOptions {
+    /**
+     * Scroll padding — insets from the viewport edges where fixed/sticky
+     * elements (headers, footers, toolbars) live.
+     *
+     * When keyboard focus moves an item behind a sticky bar, the list
+     * auto-scrolls to keep it within the visible (unobstructed) area.
+     * Also affects `scrollToIndex` alignment (start/center/end).
+     *
+     * Mirrors CSS `scroll-padding` semantics: defines the optimal viewing
+     * region within the scrollport.
+     *
+     * Values can be numbers (pixels) or functions that return pixels
+     * (useful when the sticky element's height is dynamic).
+     *
+     * @example
+     * ```ts
+     * withPage({
+     *   scrollPadding: { top: 60, bottom: 50 }
+     * })
+     * ```
+     *
+     * @example Dynamic values
+     * ```ts
+     * withPage({
+     *   scrollPadding: {
+     *     top: () => document.getElementById('sticky-header')!.offsetHeight,
+     *     bottom: 50
+     *   }
+     * })
+     * ```
+     */
+    scrollPadding?: {
+        top?: number | (() => number);
+        bottom?: number | (() => number);
+        left?: number | (() => number);
+        right?: number | (() => number);
+    };
+}
 /**
  * Create a window scroll mode feature.
  *
@@ -38,6 +83,17 @@ import type { VListFeature } from "../../builder/types";
  * .build()
  * ```
  *
+ * @example With scroll padding for sticky chrome
+ * ```ts
+ * const feed = vlist({
+ *   container: '#infinite-feed',
+ *   item: { height: 200, template: renderPost },
+ *   items: posts
+ * })
+ * .use(withPage({ scrollPadding: { top: 60, bottom: 50 } }))
+ * .build()
+ * ```
+ *
  * @example Horizontal window scrolling
  * ```ts
  * const timeline = vlist({
@@ -49,5 +105,5 @@ import type { VListFeature } from "../../builder/types";
  * .build()
  * ```
  */
-export declare const withPage: <T extends VListItem = VListItem>() => VListFeature<T>;
+export declare const withPage: <T extends VListItem = VListItem>(options?: WithPageOptions) => VListFeature<T>;
 //# sourceMappingURL=feature.d.ts.map

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

@@ -4,5 +4,6 @@
  * Entry point for the window scroll feature.
  */
 export { withPage } from "./feature";
+export type { WithPageOptions } from "./feature";
 export type { VListFeature } from "../../builder/types";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export type { ScaleConfig } from "./features/scale";
 export { withAsync } from "./features/async";
 export { withScrollbar } from "./features/scrollbar";
 export { withPage } from "./features/page";
+export type { WithPageOptions } from "./features/page";
 export { withGroups } from "./features/groups";
 export { withGrid } from "./features/grid";
 export { withMasonry } from "./features/masonry";