@dot-present/virtual-list 1.0.2-alpha.0 → 1.0.4-alpha.0

package/dist/index.js

@@ -0,0 +1 @@
+import{jsx as t}from"react/jsx-runtime";import{forwardRef as e,useRef as n,useState as r,useReducer as o,useMemo as c,useEffect as i,useCallback as s,useLayoutEffect as h,useImperativeHandle as l}from"react";const u=e((e,u)=>{const{data:f,itemKey:a,estimatedItemHeight:g=50,itemHeight:d,containerHeight:m="100%",bufferSize:p=3,overscanCount:x,onScroll:v,onReachEnd:M,renderItem:I}=e,H=x??p,b=void 0!==d,w=n(null),y=n(new Map),R=n(new Map),T=n(!1),[S,z]=r(0),[C,$]=r(0),[E,O]=o(t=>t+1,0),Y=c(()=>{if("number"==typeof m)return m;if("string"==typeof m){const t=m.trim().match(/^(\d+(?:\.\d+)?)px$/i);if(t)return Number(t[1])}return 0},[m]),j=n([]);i(()=>{if(b)return;f.length;let t=0;j.current=f.map((e,n)=>{const r={index:n,height:g,offset:t};return t+=g,r})},[f,g,b]),i(()=>()=>{R.current.forEach(t=>t.disconnect()),R.current.clear()},[]);const B=s((t,e)=>{if(b)return;const n=j.current[t];if(!n||n.height===e)return;const r=n.height;n.height=e;let o=e-r;for(let e=t+1;e<j.current.length;e++){const t=j.current[e];t&&(t.offset+=o)}O()},[b]);h(()=>{if(!w.current)return;const t=w.current.clientHeight;t>0&&$(t)},[]),i(()=>{if(!w.current)return;const t=new ResizeObserver(t=>{if(t.length>0){const e=t[0].contentRect.height;$(e)}});return t.observe(w.current),()=>t.disconnect()},[]);const{startIndex:K,endIndex:N,totalHeight:_}=c(()=>{if(0===f.length)return{startIndex:0,endIndex:-1,totalHeight:0};const t=C>0?C:Y>0?Y:8*g;if(b){const e=d,n=Math.max(0,Math.floor(S/e)-H),r=Math.max(1,Math.ceil(t/e));return{startIndex:n,endIndex:Math.min(f.length-1,n+r+H),totalHeight:f.length*e}}{const e=(t=>{let e=0,n=f.length-1,r=0;for(;e<=n;){const o=Math.floor((e+n)/2);(j.current[o]?.offset??0)<=t?(r=o,e=o+1):n=o-1}return r})(S);let n=e;const r=j.current[e];let o=(r?.offset??0)+(r?.height??0);for(;n<f.length-1&&o-S<t;){n++;const t=j.current[n];o=(t?.offset??0)+(t?.height??0)}return{startIndex:Math.max(0,e-H),endIndex:Math.min(f.length-1,n+H),totalHeight:j.current.length>0?(()=>{const t=j.current[j.current.length-1];return(t?.offset??0)+(t?.height??0)})():0}}},[S,C,f.length,H,d,b,E,Y,g]),k=s(t=>{const e=t.currentTarget,n=e.scrollTop;z(n),v?.(t);const r=e.scrollHeight-e.scrollTop-e.clientHeight<5;M&&r&&!T.current?(T.current=!0,M()):r||(T.current=!1)},[v,M]);l(u,()=>({scrollTo:t=>{if(!w.current)return;const e=Math.max(0,t);w.current.scrollTop=e,z(e)},scrollToIndex:(t,e="start")=>{if(!w.current||0===f.length)return;const n=Math.min(Math.max(0,t),f.length-1);let r=0;r=b?n*d:j.current[n]?.offset??0;const o=b?d:j.current[n]?.height??g;"center"===e?r-=(C-o)/2:"end"===e&&(r-=C-o);const c=Math.max(0,r);w.current.scrollTop=c,z(c)},getCurrentRange:()=>({start:K,end:N})}),[K,N,C,d,b,f.length,g]);const q=s((t,e)=>"function"==typeof a?a(t,e):t[a]?.toString()??`item_${e}`,[a]),A=c(()=>{const e=[];for(let n=K;n<=N&&n<f.length;n++){const r=f[n];if(void 0===r)continue;const o=q(r,n);let c=0;c=b?n*d:j.current[n]?.offset??0,e.push(t("div",{ref:t=>{if(b)return;if(!t){const t=R.current.get(o);return t&&(t.disconnect(),R.current.delete(o)),void y.current.delete(o)}const e=t;y.current.set(o,e);const r=R.current.get(o);r&&r.disconnect();const c=new ResizeObserver(t=>{const e=t[0]?.contentRect.height;e&&e>0&&B(n,e)});c.observe(t),R.current.set(o,c);const i=e.getBoundingClientRect().height;i&&j.current[n]?.height!==i&&B(n,i)},style:{position:"absolute",top:0,left:0,width:"100%",transform:`translateY(${c}px)`},children:I(r,n)},o))}return e},[K,N,f,q,b,d,I,B,E]);return t("div",{ref:w,style:{height:m,overflowY:"auto",position:"relative"},onScroll:k,children:t("div",{style:{position:"relative",height:_,width:"100%"},children:A})})});export{u as VirtualList};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dot-present/virtual-list",
-  "version": "1.0.2-alpha.0",
+  "version": "1.0.4-alpha.0",
   "description": "",
   "type": "module",
   "module": "./src/index.tsx",
@@ -8,16 +8,21 @@
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
   },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "keywords": [],
   "author": "",
-  "license": "ISC",
   "packageManager": "pnpm@10.26.2",
   "peerDependencies": {
     "react": ">=18",
     "react-dom": ">=18"
   },
-  "gitHead": "72fefa9b04e7508cfea2590e760340770038aee0"
+  "gitHead": "33126b0d5ef1834105552afc9f693e31d1a7b5b5"
 }

package/src/App.tsx

@@ -1,395 +0,0 @@
-import React, {
-  useRef,
-  useState,
-  useEffect,
-  useLayoutEffect,
-  useMemo,
-  useCallback,
-  forwardRef,
-  useImperativeHandle,
-  useReducer,
-} from "react";
-
-// 位置缓存项
-interface Position {
-  index: number;
-  height: number;
-  offset: number;
-}
-
-export interface VirtualListRef {
-  scrollTo: (scrollTop: number) => void;
-  scrollToIndex: (index: number, align?: "start" | "center" | "end") => void;
-  getCurrentRange: () => { start: number; end: number };
-}
-
-interface VirtualListProps<T> {
-  data: T[];
-  itemKey: keyof T | ((item: T, index: number) => string);
-  estimatedItemHeight?: number; // 预估高度，动态高度模式必须
-  itemHeight?: number; // 若提供，则启用固定高度模式
-  containerHeight?: number | string;
-  bufferSize?: number;
-  overscanCount?: number; // 与 bufferSize 同义，可选
-  onScroll?: (e: React.UIEvent<HTMLDivElement>) => void;
-  onReachEnd?: () => void;
-  renderItem: (item: T, index: number) => React.ReactNode;
-}
-
-export const VirtualList = forwardRef(
-  <T,>(props: VirtualListProps<T>, ref: React.Ref<VirtualListRef>) => {
-    const {
-      data,
-      itemKey,
-      estimatedItemHeight = 50,
-      itemHeight: fixedItemHeight,
-      containerHeight = "100%",
-      bufferSize = 3,
-      overscanCount,
-      onScroll,
-      onReachEnd,
-      renderItem,
-    } = props;
-
-    const buffer = overscanCount ?? bufferSize;
-    const isFixedHeight = fixedItemHeight !== undefined;
-
-    // DOM refs
-    const containerRef = useRef<HTMLDivElement>(null);
-    const itemsRef = useRef<Map<string, HTMLElement>>(new Map());
-    const itemObserversRef = useRef<Map<string, ResizeObserver>>(new Map());
-    const isNearEndRef = useRef(false);
-
-    // 状态
-    const [scrollTop, setScrollTop] = useState(0);
-    const [containerHeightVal, setContainerHeightVal] = useState(0);
-    /** 动态高度测量后递增，驱动 range / visibleItems 的 memo 与真实 offset 同步 */
-    const [measureVersion, bumpMeasure] = useReducer((v: number) => v + 1, 0);
-
-    const parsedContainerHeight = useMemo(() => {
-      if (typeof containerHeight === "number") return containerHeight;
-      if (typeof containerHeight === "string") {
-        const matched = containerHeight.trim().match(/^(\d+(?:\.\d+)?)px$/i);
-        if (matched) return Number(matched[1]);
-      }
-      return 0;
-    }, [containerHeight]);
-
-    // ---------- 动态高度模式的位置缓存 ----------
-    const positions = useRef<Position[]>([]);
-
-    // 初始化 / 数据变化时重建位置缓存
-    useEffect(() => {
-      if (isFixedHeight) return;
-      const total = data.length;
-      let offset = 0;
-      positions.current = data.map((_, idx) => {
-        const height = estimatedItemHeight;
-        const pos = { index: idx, height, offset };
-        offset += height;
-        return pos;
-      });
-    }, [data, estimatedItemHeight, isFixedHeight]);
-
-    useEffect(() => {
-      return () => {
-        itemObserversRef.current.forEach((ro) => ro.disconnect());
-        itemObserversRef.current.clear();
-      };
-    }, []);
-
-    // 更新某个索引的高度，并修正后续偏移
-    const updateItemHeight = useCallback(
-      (index: number, newHeight: number) => {
-        if (isFixedHeight) return;
-        const pos = positions.current[index];
-        if (!pos || pos.height === newHeight) return;
-        const oldHeight = pos.height;
-        pos.height = newHeight;
-        // 修正从 index+1 开始的所有偏移量
-        let diff = newHeight - oldHeight;
-        for (let i = index + 1; i < positions.current.length; i++) {
-          const pos = positions.current[i];
-          if (pos) {
-            pos.offset += diff;
-          }
-        }
-        bumpMeasure();
-      },
-      [isFixedHeight],
-    );
-
-    // 监听容器高度变化
-    useLayoutEffect(() => {
-      if (!containerRef.current) return;
-      const initialHeight = containerRef.current.clientHeight;
-      if (initialHeight > 0) {
-        setContainerHeightVal(initialHeight);
-      }
-    }, []);
-
-    useEffect(() => {
-      if (!containerRef.current) return;
-      const observer = new ResizeObserver((entries) => {
-        if (entries.length > 0) {
-          const height = entries[0].contentRect.height;
-          setContainerHeightVal(height);
-        }
-      });
-      observer.observe(containerRef.current);
-      return () => observer.disconnect();
-    }, []);
-
-    // 计算当前可视区的起始/结束索引
-    const { startIndex, endIndex, totalHeight } = useMemo(() => {
-      if (data.length === 0) {
-        return { startIndex: 0, endIndex: -1, totalHeight: 0 };
-      }
-      const effectiveContainerHeight =
-        containerHeightVal > 0
-          ? containerHeightVal
-          : parsedContainerHeight > 0
-            ? parsedContainerHeight
-            : estimatedItemHeight * 8;
-
-      if (isFixedHeight) {
-        const itemHeight = fixedItemHeight!;
-        const start = Math.max(0, Math.floor(scrollTop / itemHeight) - buffer);
-        const visibleCount = Math.max(
-          1,
-          Math.ceil(effectiveContainerHeight / itemHeight),
-        );
-        const end = Math.min(data.length - 1, start + visibleCount + buffer);
-        const total = data.length * itemHeight;
-        return { startIndex: start, endIndex: end, totalHeight: total };
-      } else {
-        // 二分：最大 i 满足 offset[i] <= scrollTop（首项可见行的上沿）
-        const findStartIndex = (st: number) => {
-          let low = 0;
-          let high = data.length - 1;
-          let ans = 0;
-          while (low <= high) {
-            const mid = Math.floor((low + high) / 2);
-            const off = positions.current[mid]?.offset ?? 0;
-            if (off <= st) {
-              ans = mid;
-              low = mid + 1;
-            } else {
-              high = mid - 1;
-            }
-          }
-          // 返回包含当前 scrollTop 的最后一个起始 offset <= scrollTop 的元素
-          return ans;
-        };
-        const start = findStartIndex(scrollTop);
-        let end = start;
-        const startPos = positions.current[start];
-        let offsetEnd = (startPos?.offset ?? 0) + (startPos?.height ?? 0);
-        while (
-          end < data.length - 1 &&
-          offsetEnd - scrollTop < effectiveContainerHeight
-        ) {
-          end++;
-          const p = positions.current[end];
-          offsetEnd = (p?.offset ?? 0) + (p?.height ?? 0);
-        }
-        // 增加缓冲区
-        const startWithBuffer = Math.max(0, start - buffer);
-        const endWithBuffer = Math.min(data.length - 1, end + buffer);
-        const total =
-          positions.current.length > 0
-            ? (() => {
-                const lastPos = positions.current[positions.current.length - 1];
-                return (lastPos?.offset ?? 0) + (lastPos?.height ?? 0);
-              })()
-            : 0;
-        return {
-          startIndex: startWithBuffer,
-          endIndex: endWithBuffer,
-          totalHeight: total,
-        };
-      }
-    }, [
-      scrollTop,
-      containerHeightVal,
-      data.length,
-      buffer,
-      fixedItemHeight,
-      isFixedHeight,
-      measureVersion,
-      parsedContainerHeight,
-      estimatedItemHeight,
-    ]);
-
-    // 滚动事件处理（含节流）
-    const handleScroll = useCallback(
-      (e: React.UIEvent<HTMLDivElement>) => {
-        const target = e.currentTarget;
-        const newScrollTop = target.scrollTop;
-        setScrollTop(newScrollTop);
-        onScroll?.(e);
-        // 触底检测
-        const nearEnd =
-          target.scrollHeight - target.scrollTop - target.clientHeight < 5;
-        if (onReachEnd && nearEnd && !isNearEndRef.current) {
-          isNearEndRef.current = true;
-          onReachEnd();
-        } else if (!nearEnd) {
-          isNearEndRef.current = false;
-        }
-      },
-      [onScroll, onReachEnd],
-    );
-
-    // 暴露方法
-    useImperativeHandle(
-      ref,
-      () => ({
-        scrollTo: (top: number) => {
-          if (!containerRef.current) return;
-          const safeTop = Math.max(0, top);
-          containerRef.current.scrollTop = safeTop;
-          setScrollTop(safeTop);
-        },
-        scrollToIndex: (
-          index: number,
-          align: "start" | "center" | "end" = "start",
-        ) => {
-          if (!containerRef.current || data.length === 0) return;
-          const safeIndex = Math.min(Math.max(0, index), data.length - 1);
-          let targetTop = 0;
-          if (isFixedHeight) {
-            targetTop = safeIndex * fixedItemHeight!;
-          } else {
-            targetTop = positions.current[safeIndex]?.offset ?? 0;
-          }
-          const targetHeight = isFixedHeight
-            ? fixedItemHeight!
-            : (positions.current[safeIndex]?.height ?? estimatedItemHeight);
-          if (align === "center") {
-            targetTop -= (containerHeightVal - targetHeight) / 2;
-          } else if (align === "end") {
-            targetTop -= containerHeightVal - targetHeight;
-          }
-          const safeTop = Math.max(0, targetTop);
-          containerRef.current.scrollTop = safeTop;
-          setScrollTop(safeTop);
-        },
-        getCurrentRange: () => ({ start: startIndex, end: endIndex }),
-      }),
-      [
-        startIndex,
-        endIndex,
-        containerHeightVal,
-        fixedItemHeight,
-        isFixedHeight,
-        data.length,
-        estimatedItemHeight,
-      ],
-    );
-
-    // 获取唯一 key
-    const getKey = useCallback(
-      (item: T, idx: number): string => {
-        if (typeof itemKey === "function") return itemKey(item, idx);
-        return (item[itemKey] as any)?.toString() ?? `item_${idx}`;
-      },
-      [itemKey],
-    );
-
-    // 渲染可视区内的项
-    const visibleItems = useMemo(() => {
-      const items = [];
-      for (let i = startIndex; i <= endIndex && i < data.length; i++) {
-        const item = data[i];
-        if (item === undefined) continue;
-
-        const key = getKey(item, i);
-        let top = 0;
-        if (isFixedHeight) {
-          top = i * fixedItemHeight!;
-        } else {
-          top = positions.current[i]?.offset ?? 0;
-        }
-        items.push(
-          <div
-            key={key}
-            ref={(el) => {
-              if (isFixedHeight) return;
-              if (!el) {
-                const prev = itemObserversRef.current.get(key);
-                if (prev) {
-                  prev.disconnect();
-                  itemObserversRef.current.delete(key);
-                }
-                itemsRef.current.delete(key);
-                return;
-              }
-
-              const htmlEl = el as unknown as HTMLElement;
-              itemsRef.current.set(key, htmlEl);
-              const prevObs = itemObserversRef.current.get(key);
-              if (prevObs) prevObs.disconnect();
-              const ro = new ResizeObserver((entries) => {
-                const h = entries[0]?.contentRect.height;
-                if (h && h > 0) updateItemHeight(i, h);
-              });
-              ro.observe(el);
-              itemObserversRef.current.set(key, ro);
-
-              // 测量真实高度（初次渲染或内容变化）
-              const actualHeight = htmlEl.getBoundingClientRect().height;
-              if (
-                actualHeight &&
-                positions.current[i]?.height !== actualHeight
-              ) {
-                updateItemHeight(i, actualHeight);
-              }
-            }}
-            style={{
-              position: "absolute",
-              top: 0,
-              left: 0,
-              width: "100%",
-              transform: `translateY(${top}px)`,
-            }}
-          >
-            {renderItem(item, i)}
-          </div>,
-        );
-      }
-      return items;
-    }, [
-      startIndex,
-      endIndex,
-      data,
-      getKey,
-      isFixedHeight,
-      fixedItemHeight,
-      renderItem,
-      updateItemHeight,
-      measureVersion,
-    ]);
-
-    // 容器样式
-    const containerStyle: React.CSSProperties = {
-      height: containerHeight,
-      overflowY: "auto",
-      position: "relative",
-    };
-
-    const innerStyle: React.CSSProperties = {
-      position: "relative",
-      height: totalHeight,
-      width: "100%",
-    };
-
-    return (
-      // 可视区域容器
-      <div ref={containerRef} style={containerStyle} onScroll={handleScroll}>
-        {/* 容器占位，高度是总列表的高度，用于撑起容器的高度，出现滚动条*/}
-        <div style={innerStyle}>{visibleItems}</div>
-      </div>
-    );
-  },
-);

package/src/index.tsx

@@ -1,3 +0,0 @@
-import { VirtualList } from "./App";
-export type { VirtualListRef } from "./App.tsx";
-export { VirtualList };

package/src/types.d.ts

@@ -1,2 +0,0 @@
-export { VirtualList } from "./App";
-export type { VirtualListRef } from "./App";

package/tsconfig.app.json

@@ -1,29 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ES2020",
-    "lib": ["ES2020", "DOM"],
-    "jsx": "react-jsx",
-    "jsxImportSource": "react",
-    "moduleResolution": "bundler",
-    "esModuleInterop": true,
-    "forceConsistentCasingInFileNames": true,
-    "strict": true,
-    "skipLibCheck": false,
-    "composite": true,
-    "declaration": true,
-    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
-    "noEmit": false,
-    "outDir": "../../dist/virtual-list"
-  },
-  "include": ["src/**/*.tsx", "src/**/*.ts"],
-  "exclude": [
-    "src/**/*.test.ts",
-    "node_modules",
-    "**/*.vue",
-    "../vue-shim.d.ts",
-    "../../vue-shim.d.ts",
-    "../../node_modules/@vue",
-    "../../node_modules/vue"
-  ]
-}

package/tsconfig.json

@@ -1,15 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2020",
-    "module": "ES2020",
-    "lib": ["ES2020", "DOM"],
-    "jsx": "react-jsx",
-    "moduleResolution": "node",
-    "esModuleInterop": true,
-    "forceConsistentCasingInFileNames": true,
-    "strict": true,
-    "declaration": true,
-    "emitDeclarationOnly": true,
-    "skipLibCheck": true
-  }
-}