Add keepMounted and itemProps to Vue API to enable sticky groups

src/vue/ListItem.tsx

@@ -16,6 +16,7 @@ import {
   StateVersion,
   VirtualStore,
 } from "../core";
+import { ItemProps } from "./utils";
 
 /**
  * @internal
@@ -33,6 +34,7 @@ export const ListItem = /*#__PURE__*/ defineComponent({
     _isHorizontal: { type: Boolean },
     _isSSR: { type: Boolean },
     _as: { type: String as PropType<keyof NativeElements>, required: true },
+    _itemProps: Object as PropType<ReturnType<ItemProps>>,
   },
   setup(props) {
     const elementRef = ref<HTMLDivElement>();
@@ -65,20 +67,23 @@ export const ListItem = /*#__PURE__*/ defineComponent({
       } = props;
       const isHide = hide.value;
 
+      const { style: styleProp, ...rest } = props._itemProps ?? {};
+
       const style: StyleValue = {
         position: isHide && isSSR ? undefined : "absolute",
         [isHorizontal ? "height" : "width"]: "100%",
         [isHorizontal ? "top" : "left"]: "0px",
         [isHorizontal ? (isRTLDocument() ? "right" : "left") : "top"]:
           offset.value + "px",
         visibility: !isHide || isSSR ? "visible" : "hidden",
+        ...styleProp,
       };
       if (isHorizontal) {
         style.display = "flex";
       }
 
       return (
-        <Element ref={elementRef} style={style}>
+        <Element ref={elementRef} style={style} {...rest}>
           {children}
         </Element>
       );

src/vue/VList.tsx

@@ -7,8 +7,10 @@ import {
   ComponentObjectPropsOptions,
   ref,
   VNode,
+  PropType,
 } from "vue";
 import { Virtualizer, VirtualizerHandle } from "./Virtualizer";
+import { ItemProps } from "./utils";
 
 interface VListHandle extends VirtualizerHandle {}
 
@@ -41,6 +43,16 @@ const props = {
    * A prop for SSR. If set, the specified amount of items will be mounted in the initial rendering regardless of the container size until hydrated.
    */
   ssrCount: Number,
+  /**
+   * A function that provides properties/attributes for item element
+   *
+   * **This prop will be merged into `item` prop in the future**
+   */
+  itemProps: Function as PropType<ItemProps>,
+  /**
+   * List of indexes that should be always mounted, even when off screen.
+   */
+  keepMounted: Array as PropType<number[]>,
 } satisfies ComponentObjectPropsOptions;
 
 export const VList = /*#__PURE__*/ defineComponent({
@@ -93,9 +105,11 @@ export const VList = /*#__PURE__*/ defineComponent({
             data={props.data}
             overscan={props.overscan}
             itemSize={props.itemSize}
+            itemProps={props.itemProps}
             shift={props.shift}
             ssrCount={props.ssrCount}
             horizontal={horizontal}
+            keepMounted={props.keepMounted}
             onScroll={onScroll}
             onScrollEnd={onScrollEnd}
           >

src/vue/Virtualizer.tsx

@@ -27,9 +27,10 @@ import {
   ItemsRange,
   ScrollToIndexOpts,
   microtask,
+  sort,
 } from "../core";
 import { ListItem } from "./ListItem";
-import { getKey, isSameRange } from "./utils";
+import { getKey, isSameRange, ItemProps } from "./utils";
 
 export interface VirtualizerHandle {
   /**
@@ -127,6 +128,16 @@ const props = {
    * @defaultValue "div"
    */
   item: { type: String as PropType<keyof NativeElements>, default: "div" },
+  /**
+   * A function that provides properties/attributes for item element
+   *
+   * **This prop will be merged into `item` prop in the future**
+   */
+  itemProps: Function as PropType<ItemProps>,
+  /**
+   * List of indexes that should be always mounted, even when off screen.
+   */
+  keepMounted: Array as PropType<number[]>,
 } satisfies ComponentObjectPropsOptions;
 
 export const Virtualizer = /*#__PURE__*/ defineComponent({
@@ -248,9 +259,10 @@ export const Virtualizer = /*#__PURE__*/ defineComponent({
       const total = totalSize.value;
 
       const items: VNode[] = [];
-      for (let i = startIndex, j = endIndex; i <= j; i++) {
+
+      function getListItem(i: number) {
         const e = slots.default({ item: props.data![i]!, index: i })[0]!;
-        items.push(
+        return (
           <ListItem
             key={getKey(e, i)}
             _rerender={rerender}
@@ -261,9 +273,29 @@ export const Virtualizer = /*#__PURE__*/ defineComponent({
             _isHorizontal={isHorizontal}
             _isSSR={isSSR}
             _as={ItemElement}
+            _itemProps={props.itemProps?.({ item: props.data![i]!, index: i })}
           />
         );
       }
+      for (let i = startIndex, j = endIndex; i <= j; i++) {
+        items.push(getListItem(i));
+      }
+
+      if (props.keepMounted) {
+        const startItems: VNode[] = [];
+        const endItems: VNode[] = [];
+        sort(props.keepMounted).forEach((index) => {
+          if (index < startIndex) {
+            startItems.push(getListItem(index));
+          }
+          if (index > endIndex) {
+            endItems.push(getListItem(index));
+          }
+        });
+
+        items.unshift(...startItems);
+        items.push(...endItems);
+      }
 
       return (
         <Element

src/vue/utils.ts

@@ -1,4 +1,4 @@
-import { VNode } from "vue";
+import { CSSProperties, VNode } from "vue";
 import { ItemsRange } from "../core";
 
 /**
@@ -15,3 +15,8 @@ export const getKey = (e: VNode, i: number): Exclude<VNode["key"], null> => {
 export const isSameRange = (prev: ItemsRange, next: ItemsRange): boolean => {
   return prev[0] === next[0] && prev[1] === next[1];
 };
+
+export type ItemProps = (payload: {
+  item: any;
+  index: number;
+}) => { [key: string]: any; style?: CSSProperties; class?: string } | undefined;

stories/vue/StickyGroup.vue

@@ -0,0 +1,65 @@
+<script setup lang="ts">
+import { CSSProperties, ref } from "vue";
+import { Virtualizer, VList } from "../../src/vue";
+
+const sizes = [20, 40, 180, 77];
+const activeIndex = ref(0);
+const data = Array.from({ length: 1000 }).map((_, i) => sizes[i % 4]!);
+const itemProps = ({ index }: { index: number }) => {
+  if (index % 100 === 0)
+    return {
+      style: {
+        ...(activeIndex.value === index
+          ? {
+              position: "sticky",
+              top: 0,
+            }
+          : {}),
+        zIndex: 1,
+      } as CSSProperties,
+    };
+  return {};
+};
+const listRef = ref<InstanceType<typeof Virtualizer>>();
+
+function onScroll() {
+  if (!listRef.value) return;
+  const start = listRef.value.findStartIndex();
+  const activeStickyIndex = [0, 100, 200, 300, 400, 500, 600, 700, 800, 900]
+    .reverse()
+    .find((index) => start >= index)!;
+  activeIndex.value = activeStickyIndex;
+}
+</script>
+
+<template>
+  <VList
+    ref="listRef"
+    :data="data"
+    :style="{ height: '100vh' }"
+    #default="{ item, index }"
+    :item-props="itemProps"
+    :keep-mounted="[activeIndex]"
+    @scroll="onScroll"
+  >
+    <div
+      :key="index"
+      :style="{
+        height: item + 'px',
+        background: 'white',
+        borderBottom: 'solid 1px #ccc',
+        ...(index % 100 === 0
+          ? {
+              background: 'yellow',
+            }
+          : {}),
+      }"
+    >
+      {{ index }}
+    </div>
+  </VList>
+</template>
+
+<style scoped>
+/* NOP */
+</style>

stories/vue/VList.stories.ts

@@ -3,6 +3,7 @@ import { VList } from "../../src/vue";
 import DefaultComponent from "./Default.vue";
 import HorizontalComponent from "./Horizontal.vue";
 import ControllsComponent from "./Controlls.vue";
+import StickyGroupComponent from './StickyGroup.vue';
 
 export default {
   component: VList,
@@ -28,3 +29,10 @@ export const Controlls: StoryObj = {
     template: "<Component />",
   }),
 };
+
+export const StickyGroup: StoryObj = {
+  render: () => ({
+    components: { Component: StickyGroupComponent },
+    template: "<Component />",
+  }),
+}