npm - @x-virtual/core - Versions diffs - 0.0.1 - Mend

@x-virtual/core 0.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/LICENSE ADDED Viewed

@@ -0,0 +1,21 @@
+MIT License
+Copyright (c) 2026 LiFi
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/xVirtualCore.js ADDED Viewed

@@ -0,0 +1,260 @@
+class S {
+  _options = {};
+  //配置项
+  _keyToIndexObj = {};
+  //key-index对照,包含脏数据,不做删除是因为需要On遍历收益不高
+  _chunkList = [];
+  //分块数据
+  _itemSizeMap = /* @__PURE__ */ new Map();
+  //高度缓存数据,包含脏数据,不做删除是因为需要On遍历收益不高
+  _itemCount = 0;
+  //总条数
+  constructor(t = {}) {
+    const { getKey: e = null, estimatedHeight: n = null, overscan: s = 10, chunkSize: r = 100, gap: i } = t || {};
+    if (typeof e != "function") throw new Error("The parameter getKey must be a function");
+    if (typeof n != "function") throw new Error("The parameter estimatedHeight must be a function");
+    this._options = { getKey: e, estimatedHeight: n, overscan: s, chunkSize: r, gap: Number(i) || 0 };
+  }
+  _getItemHeight = (t) => this._itemSizeMap.get(t) || 0;
+  _getChunkIndex = (t) => Math.floor(t / this._options.chunkSize);
+  _getItemTop = (t) => {
+    const e = this._keyToIndexObj[t], n = this._chunkList[this._getChunkIndex(e)];
+    let s = n?.top || 0;
+    return n && (s += n.prefixSums[Math.max(e - n.start, 0)] || 0), s + ((e || 0) + 1) * this._options.gap;
+  };
+  _setItemHeight = (t, e) => this._itemSizeMap.set(t, e || 0);
+  _getItemKey = (t) => this._options?.getKey?.(t) || null;
+  _computeChunk(t) {
+    let e = 0;
+    const n = t.prefixSums;
+    for (let s = t.start; s < t.end; s++)
+      n[s - t.start] = e, e += this._getItemHeight(this._getItemKey(s));
+    t.height = e;
+  }
+  _rebuildChunkListFrom(t = 0) {
+    const e = this._itemCount;
+    if (!e) return;
+    const { chunkSize: n } = this._options, s = this._getChunkIndex(t);
+    this._chunkList = this._chunkList?.slice?.(0, s) || [];
+    const r = this._chunkList[this._chunkList.length - 1];
+    let i = (r?.top || 0) + (r?.height || 0);
+    const o = Math.ceil(e / n) - s;
+    for (let h = 0; h < o; h++) {
+      const a = (s + h) * n, c = Math.min(a + n, e), _ = { start: a, end: c, top: i, height: 0, prefixSums: new Float32Array(c - a) };
+      this._computeChunk(_), this._chunkList.push(_), i += _.height;
+    }
+  }
+  _updateChunkListFrom(t = /* @__PURE__ */ new Set()) {
+    const e = this._chunkList, n = Array.from(t || []).sort((i, o) => i - o);
+    if (!n.length) return;
+    const s = n[0];
+    n?.forEach((i) => this._computeChunk(e[i]));
+    let r = (e[s]?.top || 0) + (e[s]?.height || 0);
+    for (let i = s + 1; i < e.length; i++)
+      e[i].top = r, r += e[i].height;
+  }
+  _binarySearch(t, e) {
+    if (e <= 0 || typeof t != "number" || isNaN(t)) return 0;
+    let n = 0, s = e - 1;
+    for (; n <= s; ) {
+      const r = Math.floor((n + s) / 2), i = this._getItemKey(r);
+      if (i == null || i === "") {
+        s = r - 1;
+        continue;
+      }
+      const o = this._getItemTop(i);
+      if (t >= o && t < o + this._getItemHeight(i)) return r;
+      t < o ? s = r - 1 : n = r + 1;
+    }
+    return Math.min(Math.max(0, s), e - 1);
+  }
+  getItemTop = (t) => this._getItemTop(this._getItemKey(t));
+  getTotalHeight() {
+    const t = this._getItemKey(this._itemCount - 1);
+    return this._getItemTop(t) + this._getItemHeight(t) + this._options.gap;
+  }
+  reset() {
+    this._itemSizeMap.clear(), this._keyToIndexObj = {}, this._chunkList = [], this._itemCount = 0, this._itemsPool = [];
+  }
+  setItemCount(t) {
+    if (!t || t < 0) return this.reset();
+    let e = -1;
+    const n = this._getItemKey(this._itemCount - 1), r = t > this._itemCount && this._itemCount - 1 == this._keyToIndexObj[n] ? this._itemCount : 0;
+    for (let i = r; i < t; i++) {
+      const o = this._getItemKey(i);
+      o && (e < 0 && this._keyToIndexObj[o] !== i && (e = i), this._keyToIndexObj[o] = i, this._itemSizeMap.has(o) || this._setItemHeight(o, Number(this._options.estimatedHeight?.(i) || 0)));
+    }
+    this._itemCount = t, e > -1 && this._rebuildChunkListFrom(e);
+  }
+  batchUpdateHeight(t = []) {
+    let e = 0;
+    if (!Array.isArray(t)) return e;
+    const n = /* @__PURE__ */ new Set();
+    return t.forEach((s) => {
+      const { index: r, height: i } = s || {};
+      if (typeof r != "number" || typeof i != "number" || r < 0) return;
+      const o = this._getItemKey(r);
+      !o || this._getItemHeight(o) === i || (e += i - this._getItemHeight(o), this._setItemHeight(o, i), n.add(this._getChunkIndex(r)));
+    }), n.size > 0 && this._updateChunkListFrom(n), e;
+  }
+  getVirtualItems(t, e) {
+    if (!t) return [];
+    const { overscan: n } = this._options, s = this._itemCount, r = this._binarySearch(e, s), i = n || 10;
+    let o = Math.max(r - i, 0), h = r, a = 0;
+    for (; h < s && a < t; )
+      a += this._getItemHeight(this._getItemKey(h)), h++;
+    h = Math.min(h + i, s);
+    const c = i + i, _ = h - o;
+    if (c > _) {
+      let l = c - _;
+      o == 0 ? h = Math.min(h + l, s) : h == s && (o = Math.max(o - l, 0));
+    }
+    this._itemsPool || (this._itemsPool = []);
+    const p = this._itemsPool;
+    for (let l = o; l < h; l++) {
+      const u = this._getItemKey(l);
+      if (!u) continue;
+      const m = p[l - o];
+      m ? (m.key = u, m.index = l, m.top = this._getItemTop(u)) : p.push({ key: u, index: l, top: this._getItemTop(u) });
+    }
+    return h - o ? p.slice(0, h - o) : [];
+  }
+}
+function f(d) {
+  let t = null;
+  return function(...e) {
+    const n = this;
+    t && cancelAnimationFrame(t), t = requestAnimationFrame(() => d?.apply(n, e));
+  };
+}
+class T {
+  static containerStyle = { position: "relative", "overflow-anchor": "none" };
+  _options = {};
+  //配置项
+  _containerEl = null;
+  //滚动容器
+  _resizeObserver = null;
+  //监听元素变化
+  _listTop = 0;
+  //列表顶部
+  isInitialized = !1;
+  //是否初始化
+  _core = null;
+  _sliceData = [];
+  _preScrollTop = 0;
+  _scrollingUp = !1;
+  constructor(t = {}) {
+    const {
+      isWindowScroll: e = !1,
+      getContainerElement: n = null,
+      getKey: s = null,
+      itemSelector: r,
+      overscan: i = 10,
+      estimatedHeight: o,
+      onChange: h = null,
+      gap: a
+    } = t || {};
+    if (typeof n != "function" || typeof s != "function")
+      throw new Error("The parameters `getContainerElement` `getKey` must be a function");
+    if (!r) throw new Error("The parameters `itemSelector` cannot be null");
+    this._options = {
+      isWindowScroll: e,
+      getContainerElement: n,
+      itemSelector: r,
+      onChange: h
+    };
+    const c = new S({
+      overscan: i,
+      getKey: s,
+      estimatedHeight: o,
+      chunkSize: 100,
+      gap: a
+    }), _ = f((p) => {
+      const l = p.map((m) => {
+        const I = Number(m.target.dataset.index);
+        let g = m.borderBoxSize;
+        g = Array.isArray(g) ? g[0] : g;
+        const y = g.blockSize;
+        return { index: I, height: y };
+      });
+      let u = c.batchUpdateHeight(l);
+      Math.abs(u) > 0 && this._onHeightChange(u);
+    });
+    this._resizeObserver = new ResizeObserver(_), this._core = c, this.isInitialized = !1;
+  }
+  _isHTMLElement = (t) => t instanceof HTMLElement;
+  _getScrollDom = () => this._options.isWindowScroll ? window : this._containerEl;
+  _scrollTo = (t) => this._getScrollDom()?.scrollTo?.(0, t);
+  _createItemStyle = (t = 0) => ({
+    position: "absolute",
+    top: 0,
+    left: 0,
+    width: this._options.columnWidth || "100%",
+    transform: `translate3d(${this._options.columnLeft || 0}, ${t}px, 0)`
+  });
+  _getItemTop = (t) => this._core?.getItemTop(t);
+  _getScrollTop() {
+    let t = this._options.isWindowScroll ? window.scrollY : this._containerEl?.scrollTop;
+    return Math.max(0, t - this._listTop);
+  }
+  _onHeightChange(t) {
+    this._changeData(!1), this._scrollingUp && this._scrollTo(this._getScrollTop() + t), this._scrollingUp = !1;
+  }
+  _handleScroll = f(() => {
+    const t = this._getScrollTop();
+    this._preScrollTop !== t && (this._changeData(!0), this._scrollingUp = this._preScrollTop > t, this._preScrollTop = t);
+  });
+  _changeData(t = !0) {
+    if (t) {
+      const e = this._options.isWindowScroll ? window.innerHeight : this._containerEl?.clientHeight;
+      this._sliceData = this._core.getVirtualItems(e, this._getScrollTop());
+    }
+    this._sliceData.forEach((e) => {
+      e.top = this._getItemTop(e.index), e.style = this._createItemStyle(e.top);
+    }), this._options?.onChange?.({ hasNewData: t });
+  }
+  _getCurrentRenderedItem = () => {
+    const t = this._options.isWindowScroll ? document : this._containerEl;
+    return Array.from(t.querySelectorAll(this._options.itemSelector) || []);
+  };
+  _calculateListTop() {
+    this._options.isWindowScroll ? this._listTop = window.scrollY + (this._containerEl?.getBoundingClientRect?.()?.top || 0) : this._listTop = 0;
+  }
+  init = () => {
+    if (this.isInitialized) return;
+    const { getContainerElement: t } = this._options;
+    if (this._containerEl = t?.(), !this._isHTMLElement(this._containerEl)) throw new Error("getContainerElement must return HTMLElement");
+    this._getScrollDom()?.addEventListener("scroll", this._handleScroll), this._calculateListTop(), this.isInitialized = !0;
+  };
+  reset = () => {
+    this.isInitialized && (this._resizeObserver?.disconnect(), this.isInitialized = !1, this._listTop = 0, this._preScrollTop = 0, this._core?.reset(), this._getScrollDom()?.removeEventListener("scroll", this._handleScroll), this._scrollTo(0), this._changeData(!0));
+  };
+  setItemCount(t) {
+    if (!this.isInitialized) throw new Error("library not initialized");
+    const e = Number(t || 0);
+    this._core?.setItemCount(e), this._changeData(!0);
+  }
+  updateRenderedItemSize() {
+    this._resizeObserver?.disconnect(), this._getCurrentRenderedItem().forEach((t, e) => {
+      t.dataset.index = this._sliceData[e]?.index, this._resizeObserver?.observe(t);
+    });
+  }
+  scrollToIndex(t) {
+    requestAnimationFrame(() => {
+      const e = this._getItemTop(t);
+      this._scrollTo(this._options.isWindowScroll ? this._listTop + e : e);
+    });
+  }
+  getTotalHeight = () => Math.max(0, this._core?.getTotalHeight());
+  getRangeItems = () => this._sliceData || [];
+  setColumnOffsetStyle(t, e) {
+    typeof t != "number" || typeof e != "number" || (this._options.columnWidth = t + "px", this._options.columnLeft = e + "px", this._changeData(!1));
+  }
+  calculateContainerPageTop() {
+    this._calculateListTop(), this._changeData(!0);
+  }
+}
+export {
+  T as VirtualListAdapter,
+  S as VirtualListCore
+};

package/dist/xVirtualCore.umd.cjs ADDED Viewed

@@ -0,0 +1 @@

package/index.d.ts ADDED Viewed

@@ -0,0 +1,164 @@
+/**
+ * Type declarations for VirtualListCore (index.d.ts)
+ * Generated from the provided JavaScript implementation.
+ *
+ * Notes:
+ * - Keys in the original code can be strings or numbers; we type them as `string | number`.
+ * - _keyToIndexObj in the JS uses a plain object (which coerces numeric keys to strings).
+ * - If you prefer preserving numeric keys, consider using `Map<string|number, number>` in the TS implementation.
+ */
+export interface VirtualListOptions {
+  /**
+   * Return the key for a given item index. May return null/undefined when the item key is not available.
+   */
+  getKey: (index: number) => string | number | null | undefined
+  /**
+   * Return the estimated height (in px) for a given item index.
+   */
+  estimatedHeight: (index: number) => number
+  /** Number of extra items to render before/after the visible window. Default: 10. */
+  overscan?: number
+  /** Size of each chunk used internally for prefix-sum grouping. Default: 100. */
+  chunkSize?: number
+  /** Gap in pixels between items. Default: 0. */
+  gap?: number
+}
+export interface Chunk {
+  start: number
+  end: number
+  top: number
+  height: number
+  prefixSums: Float32Array
+}
+export interface VirtualItem {
+  key: string | number
+  index: number
+  top: number
+}
+export interface BatchHeightItem {
+  index: number
+  height: number
+}
+/**
+ * VirtualListCore: core calculation engine for variable-height virtual lists.
+ *
+ * Only the public API is declared here. The original implementation contains
+ * many internal helpers and caches prefixed with `_` — these are declared
+ * as private fields for completeness, but you can remove them if you prefer
+ * a minimal declaration.
+ */
+export declare class VirtualListCore {
+  constructor(options: VirtualListOptions)
+  /** Internal options passed in constructor */
+  private _options: VirtualListOptions
+  /** Map/object from item key -> item index. Note: JS implementation used plain object. */
+  private _keyToIndexObj: Record<string, number>
+  /** Chunk array used for prefix-sum calculations */
+  private _chunkList: Chunk[]
+  /** Cache of measured heights: key -> height (px) */
+  private _itemSizeMap: Map<string | number, number>
+  /** Total number of items currently tracked */
+  private _itemCount: number
+  /** Optional reusable item pool used by getVirtualItems */
+  private _itemsPool?: VirtualItem[]
+  /**
+   * Get the top offset (px) of the item at `index`.
+   * Returns 0 when index is invalid in the original implementation.
+   */
+  getItemTop(index: number): number
+  /** Get the total scrollable height (px) computed from known measurements. */
+  getTotalHeight(): number
+  /** Reset all caches and counters (clears measured heights, keys, chunks, etc.). */
+  reset(): void
+  /**
+   * Update internal item count. Accepts non-negative integer. When newItemCount
+   * is falsy or negative, reset() is invoked.
+   */
+  setItemCount(newItemCount: number): void
+  /**
+   * Batch update measured heights. Returns the total delta in height (new - old).
+   * Invalid entries are ignored.
+   */
+  batchUpdateHeight(arr?: BatchHeightItem[]): number
+  /**
+   * Main API to retrieve the currently visible (and overscanned) virtual items.
+   * - viewportHeight: visible viewport height in pixels
+   * - scrollTop: current scrollTop in pixels
+   * Returns an array of VirtualItem objects { key, index, top } in ascending index order.
+   */
+  getVirtualItems(viewportHeight: number, scrollTop: number): VirtualItem[]
+}
+export function debounceRAF<T extends (...args: any[]) => any>(func: T): (...args: Parameters<T>) => void
+export interface VirtualListAdapterOptions {
+  isWindowScroll?: boolean
+  /** Should return the scrolling container HTMLElement (or null when unavailable) */
+  getContainerElement: () => HTMLElement | null
+  /** Return a stable key for the given index. May return null/undefined when not available. */
+  getKey: (index: number) => string | number | null | undefined
+  /** CSS selector for item elements that will be measured/observed (required) */
+  itemSelector: string
+  overscan?: number
+  estimatedHeight?: (index: number) => number
+  onChange?: (payload: { hasNewData: boolean }) => void
+  gap?: number
+}
+/** Minimal public surface of the adapter. Internal helpers prefixed with `_` are intentionally omitted from the public API here. */
+export declare class VirtualListAdapter {
+  static containerStyle: Record<string, string>
+  constructor(options?: VirtualListAdapterOptions)
+  /** Whether adapter has been initialized via `init()` */
+  isInitialized: boolean
+  /** Initialize the adapter and attach scroll listeners. Throws if `getContainerElement` does not return an HTMLElement. */
+  init(): void
+  /** Reset internal state, disconnect observers and remove listeners. */
+  reset(): void
+  /** Provide the current number of items. Will call through to the core and refresh rendered slice. */
+  setItemCount(newValLength: number): void
+  /** Observe currently rendered DOM nodes to measure their sizes. */
+  updateRenderedItemSize(): void
+  /** Scroll to a specific item index (animated via RAF). */
+  scrollToIndex(index: number): void
+  /** Return total content height as computed by the core. */
+  getTotalHeight(): number
+  /** Return the currently rendered virtual items array. */
+  getRangeItems(): import('./index.d.ts').VirtualItem[]
+  /** Set column width/left offset used to produce item styles. */
+  setColumnOffsetStyle(width: number, left: number): void
+  /** Recalculate top offset (useful when container position changes) and refresh slice. */
+  calculateContainerPageTop(): void
+}

package/package.json ADDED Viewed

@@ -0,0 +1,34 @@
+{
+  "name": "@x-virtual/core",
+  "private": false,
+  "version": "0.0.1",
+  "description": "A lightweight, cross-platform virtual layout library supporting dynamic-height lists and grid layouts with smooth scrolling and efficient rendering.",
+  "homepage": "https://github.com/LIFICN/x-virtual-layout",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LIFICN/x-virtual-layout.git",
+    "directory": "packages/core"
+  },
+  "type": "module",
+  "files": [
+    "dist",
+    "index.d.ts"
+  ],
+  "main": "./dist/xVirtualCore.umd.cjs",
+  "module": "./dist/xVirtualCore.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./dist/xVirtualCore.js",
+      "require": "./dist/xVirtualCore.umd.cjs"
+    }
+  },
+  "devDependencies": {
+    "vite": "^7.3.1"
+  },
+  "scripts": {
+    "dev": "vite build --watch",
+    "build": "vite build"
+  }
+}