@lowdefy/blocks-table 0.0.0-experimental-20260929110023

package/dist/features/serverData/createBlockCache.js

@@ -0,0 +1,205 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import getBlockRange from './getBlockRange.js';
+function getBlockId({ listKey, index }) {
+    return `${listKey}#${index}`;
+}
+// Rows of one server view, in blocks of `blockSize` per list (the root list and each expanded
+// group's list). Blocks are evicted least recently used beyond `maxBlocks` loaded blocks, never
+// one the caller still needs (`keep`) or one that is loading.
+//
+// `generation` counts invalidations. A load records the generation it started in and its
+// response is only accepted if nothing invalidated the cache since (triggerEvent cannot be
+// aborted, so stale responses are ignored instead). An invalidated block keeps its rows on screen
+// until its reload lands.
+function createBlockCache({ blockSize, maxBlocks }) {
+    const lists = new Map();
+    // Map iteration order is insertion order: touching a block re-inserts it, so the first entry
+    // is always the least recently used.
+    const blocks = new Map();
+    let generation = 0;
+    let loadedCount = 0;
+    function getList(listKey) {
+        let list = lists.get(listKey);
+        if (!list) {
+            list = {
+                total: null,
+                aggregates: null,
+                error: null
+            };
+            lists.set(listKey, list);
+        }
+        return list;
+    }
+    function evict(keep) {
+        for (const [id, block] of blocks){
+            if (loadedCount <= maxBlocks) return;
+            if (block.status !== 'loaded' || keep?.has(id)) continue;
+            blocks.delete(id);
+            loadedCount -= 1;
+        }
+    }
+    function setStatus(block, status) {
+        if (block.status === 'loaded') loadedCount -= 1;
+        if (status === 'loaded') loadedCount += 1;
+        block.status = status;
+    }
+    const cache = {
+        blockSize,
+        getBlockId,
+        get generation () {
+            return generation;
+        },
+        get loadedCount () {
+            return loadedCount;
+        },
+        getTotal (listKey) {
+            return lists.get(listKey)?.total ?? null;
+        },
+        getAggregates (listKey) {
+            return lists.get(listKey)?.aggregates ?? null;
+        },
+        getError (listKey) {
+            return lists.get(listKey)?.error ?? null;
+        },
+        hasList (listKey) {
+            return lists.has(listKey);
+        },
+        getBlock (listKey, index) {
+            return blocks.get(getBlockId({
+                listKey,
+                index
+            }));
+        },
+        getRow (listKey, rowIndex) {
+            const block = blocks.get(getBlockId({
+                listKey,
+                index: Math.floor(rowIndex / blockSize)
+            }));
+            return block?.rows?.[rowIndex % blockSize];
+        },
+        touch (listKey, index) {
+            const id = getBlockId({
+                listKey,
+                index
+            });
+            const block = blocks.get(id);
+            if (!block) return;
+            blocks.delete(id);
+            blocks.set(id, block);
+        },
+        // A block needs a load when it is missing or from an earlier generation. A block loading in
+        // this generation, or one that failed in it, does not (a refresh retries failures).
+        needsLoad (listKey, index) {
+            const block = blocks.get(getBlockId({
+                listKey,
+                index
+            }));
+            return !block || block.generation !== generation;
+        },
+        getMissingBlocks ({ listKey, startRow, endRow }) {
+            const { first, last } = getBlockRange({
+                startRow,
+                endRow,
+                blockSize,
+                total: cache.getTotal(listKey)
+            });
+            const missing = [];
+            for(let index = first; index <= last; index++){
+                if (cache.needsLoad(listKey, index)) missing.push(index);
+            }
+            return missing;
+        },
+        startLoad (listKey, index) {
+            getList(listKey);
+            const id = getBlockId({
+                listKey,
+                index
+            });
+            let block = blocks.get(id);
+            if (!block) {
+                block = {
+                    listKey,
+                    index,
+                    status: 'loading',
+                    rows: null,
+                    generation
+                };
+                blocks.set(id, block);
+            } else {
+                // An invalidated block keeps its rows (and status) on screen while it reloads.
+                block.generation = generation;
+                if (block.status !== 'loaded') setStatus(block, 'loading');
+                block.reloading = true;
+            }
+            return {
+                generation
+            };
+        },
+        finishLoad ({ listKey, index, generation: loadGeneration, rows, total, aggregates, keep }) {
+            if (loadGeneration !== generation) return false;
+            const block = blocks.get(getBlockId({
+                listKey,
+                index
+            }));
+            if (!block || block.generation !== loadGeneration) return false;
+            block.rows = rows;
+            block.reloading = false;
+            setStatus(block, 'loaded');
+            const list = getList(listKey);
+            list.total = total;
+            list.aggregates = aggregates ?? null;
+            list.error = null;
+            cache.touch(listKey, index);
+            evict(keep);
+            return true;
+        },
+        failLoad ({ listKey, index, generation: loadGeneration, error }) {
+            if (loadGeneration !== generation) return false;
+            const block = blocks.get(getBlockId({
+                listKey,
+                index
+            }));
+            if (!block || block.generation !== loadGeneration) return false;
+            block.reloading = false;
+            if (block.status !== 'loaded') setStatus(block, 'error');
+            getList(listKey).error = error;
+            return true;
+        },
+        invalidate () {
+            generation += 1;
+        },
+        // Visits the loaded rows of every list: `fn(rows, block)`.
+        forEachLoaded (fn) {
+            blocks.forEach((block)=>{
+                if (block.rows) fn(block.rows, block);
+            });
+        },
+        // Replaces a loaded block's rows (a transaction); `total` changes with removed rows.
+        setBlockRows ({ listKey, index, rows }) {
+            const block = blocks.get(getBlockId({
+                listKey,
+                index
+            }));
+            if (block) block.rows = rows;
+        },
+        adjustTotal (listKey, delta) {
+            const list = lists.get(listKey);
+            if (list && typeof list.total === 'number') list.total = Math.max(0, list.total + delta);
+        }
+    };
+    return cache;
+}
+export default createBlockCache;

package/dist/features/serverData/createRefresh.js

@@ -0,0 +1,23 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ // Block method `refresh()`: in server mode, purges the block cache and refetches the visible
+// blocks (rows stay on screen until they land). In client mode `data` is the app's, so there is
+// nothing to refetch.
+function createRefresh(api) {
+    return function refresh() {
+        api.serverStore?.refresh();
+    };
+}
+export default createRefresh;

package/dist/features/serverData/createServerStore.js

@@ -0,0 +1,360 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import applyTransactionToRows from '../transactions/applyTransactionToRows.js';
+import buildServerItems from './buildServerItems.js';
+import createBlockCache from './createBlockCache.js';
+import getBlockRange from './getBlockRange.js';
+import getListKey from './getListKey.js';
+import getNeededBlocks from './getNeededBlocks.js';
+import readFetchResult from './readFetchResult.js';
+const ROOT = getListKey([]);
+// Range changes faster than this (rows per millisecond, about 2000px/s at 40px rows) are a fast
+// scroll or a scrollbar jump: loads wait until the range settles.
+const FAST_ROWS_PER_MS = 0.05;
+const SETTLE_MS = 120;
+// Server mode's data source (D9). It owns the block cache of the current view, fetches blocks
+// through the table's internal `__tableFetch` event, and keeps the previous view's cache on
+// screen (dimmed) until the new view's first block lands. React subscribes to `version`.
+function createServerStore({ api, server }) {
+    const { blockSize, maxBlocks } = server;
+    const listeners = new Set();
+    const store = {
+        cache: createBlockCache({
+            blockSize,
+            maxBlocks
+        }),
+        previous: null,
+        view: null,
+        viewKey: null,
+        groupKey: null,
+        selected: undefined,
+        expandedGroups: new Set(),
+        segments: [],
+        visible: new Set(),
+        lastRange: null,
+        timer: null,
+        version: 0,
+        requestCount: 0,
+        loadedRows: {
+            version: -1,
+            rows: [],
+            indices: new Map()
+        },
+        itemCache: new WeakMap()
+    };
+    function notify() {
+        store.version += 1;
+        listeners.forEach((listener)=>listener());
+    }
+    // The cache on screen: the current view's, or the previous view's until the first block of
+    // the current one lands.
+    function getDisplayCache() {
+        if (store.previous && store.cache.getTotal(ROOT) === null && !store.cache.getError(ROOT)) {
+            return store.previous;
+        }
+        return store.cache;
+    }
+    function fetchBlock({ listKey, groupPath, index }) {
+        const { cache } = store;
+        if (!cache.needsLoad(listKey, index)) return;
+        const { generation } = cache.startLoad(listKey, index);
+        const isGroupLevel = groupPath.length < (store.view.group ?? []).length;
+        store.requestCount += 1;
+        const event = {
+            startRow: index * blockSize,
+            endRow: (index + 1) * blockSize,
+            view: store.view,
+            groupPath,
+            selected: store.selected
+        };
+        Promise.resolve(api.methods.triggerEvent({
+            name: '__tableFetch',
+            event
+        })).then((result)=>{
+            // A later view has its own cache: this response belongs to a superseded view.
+            if (cache !== store.cache) return;
+            if (result?.success !== true) {
+                if (cache.failLoad({
+                    listKey,
+                    index,
+                    generation,
+                    error: result?.error ?? true
+                })) notify();
+                return;
+            }
+            let read;
+            try {
+                read = readFetchResult({
+                    result,
+                    isGroupLevel
+                });
+            } catch (error) {
+                cache.failLoad({
+                    listKey,
+                    index,
+                    generation,
+                    error
+                });
+                notify();
+                throw error;
+            }
+            const accepted = cache.finishLoad({
+                listKey,
+                index,
+                generation,
+                rows: read.entries,
+                total: read.total,
+                aggregates: read.aggregates,
+                keep: store.visible
+            });
+            if (!accepted) return;
+            if (listKey === ROOT) store.previous = null;
+            notify();
+        });
+    }
+    function loadVisible() {
+        store.timer = null;
+        const range = store.lastRange;
+        if (!range || !store.view) return;
+        let needed;
+        if (getDisplayCache() !== store.cache) {
+            // The items on screen belong to the previous view; only the new root list maps to them.
+            const { first, last } = getBlockRange({
+                startRow: range.rowStart,
+                endRow: range.rowEnd,
+                blockSize
+            });
+            needed = [];
+            for(let index = first; index <= last; index++){
+                needed.push({
+                    listKey: ROOT,
+                    groupPath: [],
+                    index
+                });
+            }
+        } else {
+            needed = getNeededBlocks({
+                segments: store.segments,
+                rowStart: range.rowStart,
+                rowEnd: range.rowEnd,
+                blockSize
+            });
+        }
+        store.visible = new Set(needed.map((block)=>store.cache.getBlockId(block)));
+        needed.forEach((block)=>{
+            store.cache.touch(block.listKey, block.index);
+            fetchBlock(block);
+        });
+    }
+    Object.assign(store, {
+        subscribe (listener) {
+            listeners.add(listener);
+            return ()=>listeners.delete(listener);
+        },
+        isLoading () {
+            const display = getDisplayCache();
+            return display.getTotal(ROOT) === null && !display.getError(ROOT);
+        },
+        isPending () {
+            return getDisplayCache() !== store.cache;
+        },
+        getAggregates () {
+            return getDisplayCache().getAggregates(ROOT);
+        },
+        getTotal () {
+            return getDisplayCache().getTotal(ROOT);
+        },
+        // The rows the view matches (the toolbar's record count). A grouped view's root list holds
+        // groups, whose counts add up to the rows; before the first block lands it is null.
+        getRecordCount () {
+            const display = getDisplayCache();
+            const total = display.getTotal(ROOT);
+            if (total === null || (store.view?.group ?? []).length === 0) return total;
+            let count = 0;
+            display.forEachLoaded((entries, block)=>{
+                if (block.listKey !== ROOT) return;
+                entries.forEach((entry)=>{
+                    count += entry.count;
+                });
+            });
+            return count;
+        },
+        // The view the request receives: `{ sort, filter, search, group, aggregates }`. A new view
+        // gets a new cache and starts from the top; the old rows stay until its first block lands.
+        setView ({ view, viewKey }) {
+            if (viewKey === store.viewKey) return;
+            const initial = store.viewKey === null;
+            const groupKey = JSON.stringify(view.group ?? []);
+            if (groupKey !== store.groupKey) store.expandedGroups = new Set();
+            store.groupKey = groupKey;
+            store.view = view;
+            store.viewKey = viewKey;
+            if (!initial) {
+                if (getDisplayCache() === store.cache) store.previous = store.cache;
+                store.cache = createBlockCache({
+                    blockSize,
+                    maxBlocks
+                });
+                const scroller = api.scrollerRef.current;
+                if (scroller) scroller.scrollTop = 0;
+                store.lastRange = null;
+            }
+            fetchBlock({
+                listKey: ROOT,
+                groupPath: [],
+                index: 0
+            });
+            notify();
+        },
+        onRange ({ rowStart, rowEnd }) {
+            const now = performance.now();
+            const last = store.lastRange;
+            if (last && last.rowStart === rowStart && last.rowEnd === rowEnd) {
+                // The same range with new items under it (a block landed, a group opened). A fast scroll
+                // still waiting to settle keeps waiting: loading here would load every position a
+                // landing block happens to find the scroll at.
+                if (!store.timer) loadVisible();
+                return;
+            }
+            const velocity = last ? Math.abs(rowStart - last.rowStart) / Math.max(1, now - last.time) : 0;
+            store.lastRange = {
+                rowStart,
+                rowEnd,
+                time: now
+            };
+            if (store.timer) clearTimeout(store.timer);
+            if (velocity <= FAST_ROWS_PER_MS) {
+                loadVisible();
+                return;
+            }
+            store.timer = setTimeout(loadVisible, SETTLE_MS);
+        },
+        buildItems ({ rowsById, getId }) {
+            const built = buildServerItems({
+                blockCache: getDisplayCache(),
+                groupKeys: (store.view?.group ?? []).map((entry)=>entry.key),
+                expandedGroups: store.expandedGroups,
+                rowsById,
+                getId,
+                itemCache: store.itemCache
+            });
+            store.segments = built.segments;
+            return built;
+        },
+        // Leaf rows of the cache on screen, for TanStack (selection, row lookup, events), and each
+        // one's index in its list on the server.
+        getLoadedRows () {
+            if (store.loadedRows.version === store.version) return store.loadedRows.rows;
+            const levels = (store.view?.group ?? []).length;
+            const display = getDisplayCache();
+            const rows = [];
+            const indices = new Map();
+            display.forEachLoaded((blockRows, block)=>{
+                if (JSON.parse(block.listKey).length < levels) return;
+                blockRows.forEach((row, offset)=>{
+                    rows.push(row);
+                    indices.set(String(api.config.getKey(row)), block.index * display.blockSize + offset);
+                });
+            });
+            store.loadedRows = {
+                version: store.version,
+                rows,
+                indices
+            };
+            return rows;
+        },
+        getRowIndex (rowKey) {
+            store.getLoadedRows();
+            return store.loadedRows.indices.get(String(rowKey)) ?? null;
+        },
+        toggleGroup ({ key, expanded }) {
+            const next = expanded ?? !store.expandedGroups.has(key);
+            if (next === store.expandedGroups.has(key)) return;
+            if (next) {
+                store.expandedGroups.add(key);
+                fetchBlock({
+                    listKey: key,
+                    groupPath: JSON.parse(key),
+                    index: 0
+                });
+            } else {
+                store.expandedGroups.delete(key);
+            }
+            notify();
+        },
+        collapseAllGroups () {
+            if (store.expandedGroups.size === 0) return false;
+            store.expandedGroups = new Set();
+            notify();
+            return true;
+        },
+        // Purges the cache: every block reloads when it is next visible, the visible ones now. Rows
+        // stay on screen until their reload lands.
+        refresh () {
+            store.cache.invalidate();
+            if (store.timer) clearTimeout(store.timer);
+            fetchBlock({
+                listKey: ROOT,
+                groupPath: [],
+                index: 0
+            });
+            loadVisible();
+            notify();
+        },
+        // Updates merge into loaded rows in place. Removed rows leave their block at once; adds and
+        // removes shift the server's row positions, so the cache is invalidated and the visible
+        // blocks reload.
+        applyTransaction (transaction) {
+            const changed = {
+                added: transaction.add.length,
+                updated: 0,
+                removed: 0
+            };
+            const levels = (store.view?.group ?? []).length;
+            store.cache.forEachLoaded((rows, block)=>{
+                if (JSON.parse(block.listKey).length < levels) return;
+                const result = applyTransactionToRows({
+                    rows,
+                    transaction: {
+                        ...transaction,
+                        add: []
+                    },
+                    getKey: api.config.getKey
+                });
+                if (result.changed.updated === 0 && result.changed.removed === 0) return;
+                changed.updated += result.changed.updated;
+                changed.removed += result.changed.removed;
+                store.cache.setBlockRows({
+                    listKey: block.listKey,
+                    index: block.index,
+                    rows: result.rows
+                });
+                store.cache.adjustTotal(block.listKey, -result.changed.removed);
+            });
+            if (transaction.add.length > 0 || changed.removed > 0) {
+                store.refresh();
+            } else {
+                notify();
+            }
+            return changed;
+        },
+        dispose () {
+            if (store.timer) clearTimeout(store.timer);
+            listeners.clear();
+        }
+    });
+    return store;
+}
+export default createServerStore;

package/dist/features/serverData/getBlockRange.js

@@ -0,0 +1,29 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ // The block indexes that hold rows `startRow` (inclusive) to `endRow` (exclusive), clipped to
+// `total` when it is known. `first > last` when the range is empty.
+function getBlockRange({ startRow, endRow, blockSize, total }) {
+    const end = typeof total === 'number' ? Math.min(endRow, total) : endRow;
+    const start = Math.max(0, startRow);
+    if (end <= start) return {
+        first: 0,
+        last: -1
+    };
+    return {
+        first: Math.floor(start / blockSize),
+        last: Math.floor((end - 1) / blockSize)
+    };
+}
+export default getBlockRange;

package/dist/features/serverData/getListKey.js

@@ -0,0 +1,20 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ // A server list is the rows (or groups) under one group path; the root list has path []. The key
+// is also the group item's key, so an expanded group's key names its child list.
+function getListKey(groupPath) {
+    return JSON.stringify(groupPath);
+}
+export default getListKey;

package/dist/features/serverData/getNeededBlocks.js

@@ -0,0 +1,45 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import getBlockRange from './getBlockRange.js';
+// The blocks behind display items `rowStart` to `rowEnd` (exclusive). `segments` map runs of
+// display items to the list rows they show: `{ itemStart, length, listKey, groupPath,
+// listStart }`, in item order.
+function getNeededBlocks({ segments, rowStart, rowEnd, blockSize }) {
+    const needed = [];
+    const seen = new Set();
+    segments.forEach((segment)=>{
+        const segmentEnd = segment.itemStart + segment.length;
+        if (segmentEnd <= rowStart || segment.itemStart >= rowEnd) return;
+        const from = Math.max(rowStart, segment.itemStart) - segment.itemStart + segment.listStart;
+        const to = Math.min(rowEnd, segmentEnd) - segment.itemStart + segment.listStart;
+        const { first, last } = getBlockRange({
+            startRow: from,
+            endRow: to,
+            blockSize
+        });
+        for(let index = first; index <= last; index++){
+            const id = `${segment.listKey}#${index}`;
+            if (seen.has(id)) continue;
+            seen.add(id);
+            needed.push({
+                listKey: segment.listKey,
+                groupPath: segment.groupPath,
+                index
+            });
+        }
+    });
+    return needed;
+}
+export default getNeededBlocks;