@enhanced-dom/virtualizer 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023-present CD9B4A105290E17E0948E021DF4105107C88693C59C0B891CCC08366C51AEA990902A6A156AC87D88A2FC41422A5E1C3C4071F251F19441C4516000EC25F87DF
+
+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/README.md

@@ -0,0 +1 @@
+Helpers for item list virtualization in 1d or 2d

package/index.d.ts

@@ -0,0 +1,26 @@
+export type IVirtualizerEntry = {
+    level?: number;
+    id: string | number;
+    maxSize?: number;
+    weight?: number;
+} & ({
+    minSize: number;
+    fixedSize?: number;
+} | {
+    minSize?: number;
+    fixedSize: number;
+});
+export interface IVirtualizerConfig {
+    viewportSize: number;
+    offset?: number;
+    overscan?: number;
+}
+export interface IVirtualizerResult extends Pick<IVirtualizerEntry, 'id'> {
+    size: number;
+    offset?: number;
+    relativeOffset?: number;
+    minOffset?: number;
+    maxOffset?: number;
+    level?: number;
+}
+export declare const virtualize: (config: IVirtualizerConfig, entries: IVirtualizerEntry[]) => IVirtualizerResult[];

package/index.js

@@ -0,0 +1,333 @@
+var TreePartType;
+(function (TreePartType) {
+    TreePartType["NODE"] = "node";
+    TreePartType["FOREST"] = "forest";
+})(TreePartType || (TreePartType = {}));
+class StickyGroupNode {
+    static isInstance(treePart) {
+        return (treePart === null || treePart === void 0 ? void 0 : treePart.type) === TreePartType.NODE;
+    }
+    constructor(id, level) {
+        this.parent = null;
+        this.children = [];
+        this.type = TreePartType.NODE;
+        this._size = null;
+        this._depth = null;
+        this.id = id;
+        this.level = level;
+    }
+    addChild(child) {
+        child.parent = this;
+        this.children.push(child);
+        return child;
+    }
+    getAncestor(level) {
+        var _a;
+        if (this.level > level) {
+            return this;
+        }
+        return (_a = this.parent) === null || _a === void 0 ? void 0 : _a.getAncestor(level);
+    }
+    findNode(id) {
+        if (this.id == id) {
+            return this;
+        }
+        return this.children.map((c) => c.findNode(id)).find((n) => !!n);
+    }
+    findNextSibling() {
+        var _a;
+        const currentNodeIndex = this.parent.children.indexOf(this);
+        return (_a = this.parent.children[currentNodeIndex + 1]) !== null && _a !== void 0 ? _a : this.parent.findNextSibling();
+    }
+    findPreviousSibling() {
+        var _a;
+        const currentNodeIndex = this.parent.children.indexOf(this);
+        return (_a = this.parent.children[currentNodeIndex - 1]) !== null && _a !== void 0 ? _a : (StickyGroupNode.isInstance(this.parent) ? this.parent : null);
+    }
+    hasChildren() {
+        return !!this.children.length;
+    }
+    get size() {
+        if (this._size == null) {
+            this._size = this.hasChildren() ? Math.max(...this.children.map((c) => c.size)) + 1 : 0;
+        }
+        return this._size;
+    }
+    get depth() {
+        if (this._depth == null) {
+            this._depth = this.parent.depth + 1;
+        }
+        return this._depth;
+    }
+}
+class StickyGroupForest {
+    constructor() {
+        this.children = [];
+        this.type = TreePartType.FOREST;
+        this._size = null;
+    }
+    addChild(child) {
+        child.parent = this;
+        this.children.push(child);
+    }
+    hasChildren() {
+        return !!this.children.length;
+    }
+    getAncestor() {
+        return null;
+    }
+    size(id) {
+        var _a;
+        if (id != null) {
+            return (_a = this.findNode(id)) === null || _a === void 0 ? void 0 : _a.size;
+        }
+        if (this._size == null) {
+            this._size = this.hasChildren() ? Math.max(...this.children.map((c) => c.size)) + 1 : 0;
+        }
+        return this._size;
+    }
+    get depth() {
+        return 0;
+    }
+    findNode(id) {
+        return this.children.map((c) => c.findNode(id)).find((n) => !!n);
+    }
+    findAncestors(id) {
+        let node = this.findNode(id);
+        if (!node) {
+            return [];
+        }
+        const ancestors = [];
+        while (node.parent !== this) {
+            node = node.parent;
+            ancestors.unshift(node);
+        }
+        return ancestors;
+    }
+    findNextSibling() {
+        return null;
+    }
+    findPreviousSibling() {
+        return null;
+    }
+}
+export const virtualize = (config, entries) => {
+    var _a, _b, _c;
+    const { offset, overscan, viewportSize } = {
+        offset: 0,
+        overscan: 5,
+        ...config,
+    };
+    // first, let us figure out if the size is smaller than the viewport
+    // while we iterate over the entries, we should also find out some 'statisticts' about weights
+    let lowerBoundSize = 0;
+    const entriesWithDynamicSpace = [];
+    const unboundedEntries = [];
+    const entriesOffsets = [];
+    const stickyGroups = new StickyGroupForest();
+    const entryById = {};
+    let currentStickyGroupNode = null;
+    let minimumExplicitWeight = Infinity;
+    let minimumDerivedWeight = Infinity;
+    for (const e of entries) {
+        const entryMinSize = (_a = e.fixedSize) !== null && _a !== void 0 ? _a : e.minSize;
+        entriesOffsets.push({ id: e.id, offset: lowerBoundSize, size: entryMinSize });
+        lowerBoundSize += entryMinSize;
+        entryById[e.id] = e;
+        if (e.level != null) {
+            currentStickyGroupNode =
+                ((_b = currentStickyGroupNode === null || currentStickyGroupNode === void 0 ? void 0 : currentStickyGroupNode.level) !== null && _b !== void 0 ? _b : 0) > e.level ? currentStickyGroupNode : currentStickyGroupNode === null || currentStickyGroupNode === void 0 ? void 0 : currentStickyGroupNode.getAncestor(e.level);
+            if (!currentStickyGroupNode) {
+                currentStickyGroupNode = new StickyGroupNode(e.id, e.level);
+                stickyGroups.addChild(currentStickyGroupNode);
+            }
+            else {
+                currentStickyGroupNode = currentStickyGroupNode.addChild(new StickyGroupNode(e.id, e.level));
+            }
+        }
+        if (e.fixedSize == null && (e.weight || e.maxSize == null || e.maxSize > e.minSize)) {
+            entriesWithDynamicSpace.push(e);
+            if (e.maxSize == null) {
+                unboundedEntries.push(e.id);
+            }
+            if (e.weight && e.weight < minimumExplicitWeight) {
+                minimumExplicitWeight = e.weight;
+            }
+            // TODO: we assume that the input is 'sane', and maxSize > minSize if given
+            if (e.maxSize && e.maxSize - e.minSize < minimumDerivedWeight) {
+                minimumDerivedWeight = e.maxSize - e.minSize;
+            }
+        }
+    }
+    if (!isFinite(minimumExplicitWeight)) {
+        minimumExplicitWeight = 1;
+    }
+    if (!isFinite(minimumDerivedWeight)) {
+        minimumDerivedWeight = 1;
+    }
+    if (lowerBoundSize <= viewportSize) {
+        // we will show ALL entries
+        const totalSpaceToDistribute = viewportSize - lowerBoundSize;
+        if (entriesWithDynamicSpace.some((e) => e.weight)) {
+            // we will attempt distribute the rest of the available space among entries that have not maxSize based on their weights
+            const totalExplicitWeights = entriesWithDynamicSpace.reduce((acc, e) => {
+                var _a;
+                return acc + ((_a = e.weight) !== null && _a !== void 0 ? _a : minimumExplicitWeight);
+            }, 0);
+            const unitOfSpace = totalSpaceToDistribute / totalExplicitWeights;
+            let remainingSpaceToDistribute = totalSpaceToDistribute;
+            const transformedEntries = entries.map((e) => {
+                var _a;
+                const transformedEntry = { id: e.id, floating: false, size: e.fixedSize };
+                if (transformedEntry.size == null) {
+                    let computedSize = e.minSize;
+                    if (remainingSpaceToDistribute > 0) {
+                        const entryWeight = (_a = e.weight) !== null && _a !== void 0 ? _a : minimumExplicitWeight;
+                        let entryExtraSpace = Math.min(remainingSpaceToDistribute, Math.max(Math.round(entryWeight * unitOfSpace), 1));
+                        computedSize = e.minSize + entryExtraSpace;
+                        if (e.maxSize && computedSize > e.maxSize) {
+                            computedSize = e.maxSize;
+                            entryExtraSpace = e.maxSize - e.minSize;
+                        }
+                        remainingSpaceToDistribute -= entryExtraSpace;
+                    }
+                    transformedEntry.size = computedSize;
+                }
+                return transformedEntry;
+            });
+            if (remainingSpaceToDistribute > 0 && unboundedEntries.length) {
+                const outstandingUnitOfSpace = remainingSpaceToDistribute / unboundedEntries.length;
+                transformedEntries.forEach((e) => {
+                    if (unboundedEntries.includes(e.id) && remainingSpaceToDistribute > 0) {
+                        const extraEntrySpace = e.id === unboundedEntries[unboundedEntries.length - 1] ? remainingSpaceToDistribute : Math.round(outstandingUnitOfSpace);
+                        e.size = e.size + extraEntrySpace;
+                        remainingSpaceToDistribute -= extraEntrySpace;
+                    }
+                });
+            }
+            return transformedEntries;
+        }
+        // we attempt to distribute the remaining space based on the maxSize - minSize
+        const totalDerivedWeights = entriesWithDynamicSpace.reduce((acc, e) => {
+            return acc + (e.maxSize ? e.maxSize - e.minSize : minimumDerivedWeight);
+        }, 0);
+        if (minimumDerivedWeight) {
+            const unitOfSpace = totalSpaceToDistribute / totalDerivedWeights;
+            let remainingSpaceToDistribute = totalSpaceToDistribute;
+            const transformedEntries = entries.map((e) => {
+                const transformedEntry = { id: e.id, size: e.fixedSize };
+                if (transformedEntry.size == null) {
+                    let computedSize = e.minSize;
+                    if (remainingSpaceToDistribute > 0) {
+                        const entryWeight = e.maxSize ? e.maxSize - e.minSize : minimumDerivedWeight;
+                        let entryExtraSpace = Math.min(remainingSpaceToDistribute, Math.max(Math.round(entryWeight * unitOfSpace), 1));
+                        computedSize = e.minSize + entryExtraSpace;
+                        if (e.maxSize && computedSize > e.maxSize) {
+                            computedSize = e.maxSize;
+                            entryExtraSpace = e.maxSize - e.minSize;
+                        }
+                        remainingSpaceToDistribute -= entryExtraSpace;
+                    }
+                    transformedEntry.size = computedSize;
+                }
+                return transformedEntry;
+            });
+            if (remainingSpaceToDistribute > 0 && unboundedEntries.length) {
+                const outstandingUnitOfSpace = remainingSpaceToDistribute / unboundedEntries.length;
+                transformedEntries.forEach((e) => {
+                    if (unboundedEntries.includes(e.id) && remainingSpaceToDistribute > 0) {
+                        const extraEntrySpace = e.id === unboundedEntries[unboundedEntries.length - 1] ? remainingSpaceToDistribute : Math.round(outstandingUnitOfSpace);
+                        e.size = e.size + extraEntrySpace;
+                        remainingSpaceToDistribute -= extraEntrySpace;
+                    }
+                });
+            }
+            return transformedEntries;
+        }
+        // no luck distributing the weights - we will return the entries as they are...
+        return entries.map((e) => { var _a; return ({ id: e.id, floating: false, size: (_a = e.fixedSize) !== null && _a !== void 0 ? _a : e.minSize }); });
+    }
+    // we will show only 'some' entries. Let's figure out which ones are in the window
+    const firstOffsetInWindow = entriesOffsets.find((o) => o.offset <= offset && o.offset + o.size >= offset);
+    if (!firstOffsetInWindow) {
+        return [];
+    }
+    const firstEntryIdxInWindow = entriesOffsets.indexOf(firstOffsetInWindow);
+    const firstEntryIdx = Math.max(0, firstEntryIdxInWindow - overscan);
+    const firstOffsetOutOfWindow = entriesOffsets.find((o) => o.offset >= offset + viewportSize);
+    const lastEntryIdxInWindow = firstOffsetOutOfWindow ? entriesOffsets.indexOf(firstOffsetOutOfWindow) - 1 : entries.length - 1;
+    const lastEntryIdx = Math.min(entries.length - 1, lastEntryIdxInWindow + overscan);
+    // take the entries corresponding to the viewport and include the overscan
+    const selectedEntries = entries.slice(firstEntryIdx, lastEntryIdx + 1);
+    const entryOffsetById = entriesOffsets.reduce((acc, eo) => {
+        acc[eo.id] = { start: eo.offset, end: eo.offset + eo.size };
+        return acc;
+    }, {});
+    let transformedEntries = selectedEntries.map((e) => {
+        var _a;
+        return ({
+            id: e.id,
+            size: (_a = e.fixedSize) !== null && _a !== void 0 ? _a : e.minSize,
+            offset: entryOffsetById[e.id].start,
+            level: e.level,
+        });
+    });
+    // adjust selected entries off the window which have a stickyGroup
+    if (stickyGroups.hasChildren()) {
+        // first, we will adjust the maxOffset for the sticky entries within the view:
+        transformedEntries.forEach((e) => {
+            if (e.level) {
+                const entryGroupNode = stickyGroups.findNode(e.id);
+                const nextSiblingGroupNode = entryGroupNode.findNextSibling();
+                e.maxOffset = nextSiblingGroupNode ? entryOffsetById[nextSiblingGroupNode.id].start - e.size : null;
+                e.minOffset = e.offset;
+            }
+        });
+        const firstStickyEntryOutsideTheWindow = entries
+            .slice(0, firstEntryIdx)
+            .reverse()
+            .find((e) => !!e.level);
+        if (firstStickyEntryOutsideTheWindow) {
+            const stickyAncestors = stickyGroups.findAncestors(firstStickyEntryOutsideTheWindow.id);
+            // then, find and transform preceding sticky entries
+            const stickyTransformedEntries = stickyAncestors.map((stickyGroupNode) => {
+                var _a;
+                const entry = entryById[stickyGroupNode.id];
+                const size = (_a = entry.fixedSize) !== null && _a !== void 0 ? _a : entry.minSize;
+                return {
+                    id: entry.id,
+                    size,
+                    offset: entryOffsetById[entry.id].start,
+                    level: entry.level,
+                };
+            });
+            transformedEntries = [
+                ...stickyTransformedEntries,
+                {
+                    id: firstStickyEntryOutsideTheWindow.id,
+                    size: (_c = firstStickyEntryOutsideTheWindow.fixedSize) !== null && _c !== void 0 ? _c : firstStickyEntryOutsideTheWindow.minSize,
+                    offset: entryOffsetById[firstStickyEntryOutsideTheWindow.id].start,
+                    level: firstStickyEntryOutsideTheWindow.level,
+                },
+                ...transformedEntries,
+            ];
+        }
+        // then figure out the level of the sticky entries based on the depth of the tree of group nodes
+        const relativeOffsets = {};
+        transformedEntries
+            .filter((te) => !!te.level)
+            .sort((e1, e2) => e2.level - e1.level)
+            .forEach((te) => {
+            var _a;
+            const stickyGroupNode = stickyGroups.findNode(te.id);
+            const nextSiblingGroupNode = stickyGroupNode.findNextSibling();
+            te.maxOffset = nextSiblingGroupNode ? entryOffsetById[nextSiblingGroupNode.id].start - te.size : lowerBoundSize - te.size;
+            te.minOffset = te.offset;
+            const parentGroupNode = StickyGroupNode.isInstance(stickyGroupNode.parent) ? stickyGroupNode.parent : null;
+            const levelOffset = (_a = relativeOffsets[parentGroupNode === null || parentGroupNode === void 0 ? void 0 : parentGroupNode.id]) !== null && _a !== void 0 ? _a : 0;
+            te.relativeOffset = levelOffset;
+            relativeOffsets[te.id] = levelOffset + te.size;
+        });
+    }
+    return transformedEntries;
+};

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@enhanced-dom/virtualizer",
+  "version": "0.1.0",
+  "description": "Helpers for item list virtualization in 1d or 2d",
+  "repository": "https://github.com/enhanced-dom/virtualizer.git",
+  "main": "index.js",
+  "keywords": [],
+  "author": "CD9B4A105290E17E0948E021DF4105107C88693C59C0B891CCC08366C51AEA990902A6A156AC87D88A2FC41422A5E1C3C4071F251F19441C4516000EC25F87DF",
+  "license": "MIT",
+  "dependencies": {},
+  "devDependencies": {
+    "@enhanced-dom/build": "^0.1.0",
+    "@enhanced-dom/jest": "^0.1.0",
+    "@enhanced-dom/lint": "^0.1.4",
+    "@enhanced-dom/react": "^0.1.0",
+    "@enhanced-dom/webpack": "^0.1.0",
+    "@types/jest": "^29.5.12",
+    "@types/react": "^17.0.75",
+    "@types/react-dom": "^17.0.25",
+    "typescript": "^5.3.3",
+    "lodash.debounce": "^4.0.8",
+    "use-lodash-debounce": "^1.3.0"
+  },
+  "engines": {
+    "node": ">=18",
+    "npm": ">=10"
+  }
+}