@lowdefy/blocks-table 0.0.0-experimental-20260929110023

package/dist/core/useFeatureItems.js

@@ -0,0 +1,78 @@
+/*
+  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 { useMemo, useRef } from 'react';
+import isDataItem from './isDataItem.js';
+function combineHeights(heightFns) {
+    if (heightFns.length === 0) return null;
+    if (heightFns.length === 1) return heightFns[0];
+    return function rowHeights(item, index) {
+        for(let f = 0; f < heightFns.length; f++){
+            const height = heightFns[f](item, index);
+            if (height !== undefined) return height;
+        }
+        return undefined;
+    };
+}
+// Stage 5 of the data pipeline (see TableRoot): the display list the body windows over. It starts
+// as TanStack's row model rows; each `useItems(ctx)` hook, in registry order, may return
+// `{ rows }` to replace it with display items: server mode's rows, group headers and `undefined`
+// holes for rows not loaded yet; client grouping's group headers; tree rows with a depth;
+// expanded detail rows after their row; and last the current page. A TanStack row is a data item
+// as it is; other items carry `kind` ('row' for wrapped data rows, 'group', 'detail') and `key`
+// (wrapped rows: `id` and `original`). A hook returns null when it has nothing to change.
+//
+// A hook may also return:
+// - `dataRows`: the view's data rows in display order when the list leaves some out (rows in
+//   collapsed groups, other pages). The first hook's wins (it saw the most); export and the
+//   summary read `api.dataRows`. By default it is the list's data items.
+// - `rowHeights(item, index)`: the height estimate of items that are not one row high (a detail
+//   row before it is measured), or undefined. The window then positions items by offsets built
+//   from measured heights and these estimates (virtualization's useRowOffsets).
+function useFeatureItems(ctx) {
+    let rows = ctx.rows;
+    let dataRows = null;
+    const heightFns = [];
+    ctx.api.features.list.forEach((feature)=>{
+        if (!feature.useItems) return;
+        const result = feature.useItems({
+            ...ctx,
+            rows
+        });
+        if (!result) return;
+        if (!dataRows && result.dataRows) dataRows = result.dataRows;
+        rows = result.rows;
+        if (result.rowHeights) heightFns.push(result.rowHeights);
+    });
+    const listDataRows = useMemo(()=>rows === ctx.rows ? rows : rows.filter(isDataItem), [
+        rows,
+        ctx.rows
+    ]);
+    // Memoised by hand: the number of height functions changes with config.
+    const memo = useRef({
+        heightFns: [],
+        rowHeights: null
+    });
+    const same = heightFns.length === memo.current.heightFns.length && heightFns.every((fn, index)=>fn === memo.current.heightFns[index]);
+    if (!same) memo.current = {
+        heightFns,
+        rowHeights: combineHeights(heightFns)
+    };
+    return {
+        dataRows: dataRows ?? listDataRows,
+        rowHeights: memo.current.rowHeights,
+        rows
+    };
+}
+export default useFeatureItems;

package/dist/core/useFeatureMethods.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.
+*/ import { useEffect } from 'react';
+// Registers the features' block methods (exportCsv, scrollToRow, clearSelection, ...) once per
+// engine methods object. Each method reads the live table through the API object.
+function useFeatureMethods({ api, methods }) {
+    useEffect(()=>{
+        api.features.list.forEach((feature)=>{
+            Object.entries(feature.methods ?? {}).forEach(([name, create])=>{
+                methods.registerMethod(name, create(api));
+            });
+        });
+    }, [
+        methods
+    ]);
+}
+export default useFeatureMethods;

package/dist/core/useFeatureRows.js

@@ -0,0 +1,36 @@
+/*
+  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.
+*/ // Stage 3 of the data pipeline (see TableRoot): the rows TanStack sees, after they are diffed by
+// key. Each `useRows(ctx)` hook, in registry order, returns the rows the next one sees:
+// transactions keep `applyTransaction` results over the rows until the app's data changes, then
+// editing lays its optimistic overlay (Table) or its changeset (TableInput) over them, never
+// writing `data`. These hooks see rows whose identity only changes when their content does, so
+// they can hold state on them. A hook returns its input rows (the same array) when it has nothing
+// to add, which keeps every row model memo warm.
+function useFeatureRows({ api, config, input, properties, rows }) {
+    let result = rows;
+    api.features.list.forEach((feature)=>{
+        if (!feature.useRows) return;
+        result = feature.useRows({
+            api,
+            config,
+            input,
+            properties,
+            rows: result
+        });
+    });
+    return result;
+}
+export default useFeatureRows;

package/dist/core/useFeatureSet.js

@@ -0,0 +1,54 @@
+/*
+  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 createFeatureSet from './createFeatureSet.js';
+import createMethodStubs from './createMethodStubs.js';
+import features from '../features/index.js';
+import loadOptionalFeature from './loadOptionalFeature.js';
+const sets = new Map();
+// The feature set a table renders with (`TableRoot`'s `features`, then `api.features`): the
+// always-on features and the optional ones its config needs (editing, server mode, group rows,
+// trees, expandable rows, the toolbar, saved views), in registry order. Until the needed chunks
+// have loaded this suspends, so the lazy block's fallback stays up and its methods are registered
+// only once the whole table is there. Sets are shared by signature (the needed optional names);
+// the table remounts when its signature changes (Table.lazy keys TableRoot on it).
+function useFeatureSet({ content, input, properties, rowWindowStrategy }) {
+    const context = {
+        content,
+        input: input === true,
+        properties,
+        rowWindowStrategy
+    };
+    const needed = features.filter((entry)=>entry.optional && entry.needs(context));
+    const signature = needed.map((entry)=>entry.name).join(',');
+    const existing = sets.get(signature);
+    if (existing !== undefined) return existing;
+    const records = needed.map(loadOptionalFeature);
+    const failed = records.find((record)=>record.error !== null);
+    if (failed) throw failed.error;
+    const pending = records.filter((record)=>record.feature === null);
+    if (pending.length > 0) throw Promise.all(pending.map((record)=>record.promise));
+    const list = features.map((entry)=>{
+        if (!entry.optional) return entry;
+        const index = needed.indexOf(entry);
+        return index === -1 ? createMethodStubs(entry) : records[index].feature;
+    });
+    const set = {
+        ...createFeatureSet(list),
+        signature
+    };
+    sets.set(signature, set);
+    return set;
+}
+export default useFeatureSet;

package/dist/core/useForeignKeys.js

@@ -0,0 +1,38 @@
+/*
+  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 { useEffect } from 'react';
+import { type } from '@lowdefy/helpers';
+import isSelectAllValue from '../features/selection/isSelectAllValue.js';
+// Selected keys can name rows that are not loaded (`rowSelection.preserve`). TanStack keeps them
+// as string ids; this remembers each key's own value so the selection writes back unchanged. The
+// same holds for the `except` keys of an `{ all: true, except }` selection.
+function useForeignKeys({ api, selected }) {
+    useEffect(()=>{
+        if (isSelectAllValue(selected)) {
+            api.selectionExcept = new Map((selected.except ?? []).filter((key)=>!type.isNone(key)).map((key)=>[
+                    String(key),
+                    key
+                ]));
+            return;
+        }
+        if (!type.isArray(selected)) return;
+        selected.forEach((key)=>{
+            if (!type.isNone(key)) api.foreignKeys.set(String(key), key);
+        });
+    }, [
+        selected
+    ]);
+}
+export default useForeignKeys;

package/dist/core/useGridFeatures.js

@@ -0,0 +1,26 @@
+/*
+  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.
+*/ // Grid-level feature hooks (virtualisation, keyboard, ...) in registry order. Each receives the
+// grid context with the earlier hooks' results merged in (keyboard reads virtualisation's
+// `range`). The registry is a module constant, so the hook order never changes between renders.
+function useGridFeatures(gridCtx) {
+    const ctx = gridCtx;
+    ctx.api.features.list.forEach((feature)=>{
+        if (!feature.useGridFeature) return;
+        Object.assign(ctx, feature.useGridFeature(ctx));
+    });
+    return ctx;
+}
+export default useGridFeatures;

package/dist/core/useStableConfig.js

@@ -0,0 +1,34 @@
+/*
+  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 { useRef } from 'react';
+// Config objects (columns, defaultView, rowSelection, ...) are small but the engine hands the
+// block a fresh copy whenever any property is re-evaluated. Comparing their JSON keeps downstream
+// memos (column model, TanStack column defs) from rebuilding for identical config. Never use this
+// for `data`, which is diffed by row key instead.
+function useStableConfig(value) {
+    const ref = useRef({
+        json: undefined,
+        value: undefined
+    });
+    const json = JSON.stringify(value ?? null);
+    if (ref.current.json !== json) {
+        ref.current = {
+            json,
+            value
+        };
+    }
+    return ref.current.value;
+}
+export default useStableConfig;

package/dist/core/useSummary.js

@@ -0,0 +1,73 @@
+/*
+  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 { useMemo } from 'react';
+import computeAggregate from '@lowdefy/blocks-antd/table/computeAggregate.js';
+import getAggregateText from '@lowdefy/blocks-antd/table/getAggregateText.js';
+import createAccessor from './createAccessor.js';
+import resolveAggregates from '../features/grouping/resolveAggregates.js';
+function computeClientValue({ column, fn, rows }) {
+    const accessor = createAccessor(column.field);
+    const values = new Array(rows.length);
+    for(let i = 0; i < rows.length; i++)values[i] = accessor(rows[i].original);
+    return computeAggregate({
+        fn,
+        values,
+        column
+    });
+}
+// The summary footer's values: the aggregates in effect (the view's `aggregates` over each
+// column's `aggregate` default, the same ones the group headers show), over all the table's
+// filtered rows (not a page, not the rendered window) with the shared column core, as TableLight
+// does. Keyed on the unsorted row model, so a sort never recomputes them. In server mode the
+// browser holds only some rows, so the values are the root list's `aggregates` from the
+// server's responses. Null when there is nothing to show (`summary: false`, or no aggregates).
+function useSummary({ api, config, state, table }) {
+    const rows = table.getPreSortedRowModel().rows;
+    const store = api.serverStore;
+    const serverAggregates = store ? store.getAggregates() : null;
+    return useMemo(()=>{
+        if (!config.summary) return null;
+        const resolved = resolveAggregates({
+            columns: config.columns,
+            aggregates: state.aggregates
+        });
+        if (resolved.length === 0) return null;
+        const byKey = new Map();
+        resolved.forEach(({ key, fn })=>{
+            const column = config.columnsByKey.get(key);
+            const value = store ? serverAggregates?.[key] ?? null : computeClientValue({
+                column,
+                fn,
+                rows
+            });
+            byKey.set(key, {
+                fn,
+                text: getAggregateText({
+                    fn,
+                    value,
+                    column
+                })
+            });
+        });
+        return byKey;
+    }, [
+        config,
+        rows,
+        state.aggregates,
+        store,
+        serverAggregates
+    ]);
+}
+export default useSummary;

package/dist/core/useTableConfig.js

@@ -0,0 +1,189 @@
+/*
+  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 { useMemo } from 'react';
+import { type } from '@lowdefy/helpers';
+import compileColumns from '@lowdefy/blocks-antd/table/compileColumns.js';
+import compileRules from '@lowdefy/blocks-antd/table/compileRules.js';
+import createRowKeyGetter from '@lowdefy/blocks-antd/table/createRowKeyGetter.js';
+import normalizeColumns from '@lowdefy/blocks-antd/table/normalizeColumns.js';
+import createColumnDefs from './createColumnDefs.js';
+import densityHeights from './densityHeights.js';
+import getHeaderLevels from './getHeaderLevels.js';
+import normalizeExpandable from '../features/expandable/normalizeExpandable.js';
+import normalizeServerData from '../features/serverData/normalizeServerData.js';
+import normalizeTree from '../features/tree/normalizeTree.js';
+import normalizePersist from '../features/views/normalizePersist.js';
+import normalizeToolbar from '../features/toolbar/normalizeToolbar.js';
+import useStableConfig from './useStableConfig.js';
+const DEFAULT_PAGE_SIZE = 50;
+// In server mode rows leave the block cache while they stay selected, so selection is always
+// preserved there.
+function normalizeRowSelection({ rowSelection, server }) {
+    if (!type.isObject(rowSelection)) return null;
+    return {
+        type: rowSelection.type === 'radio' ? 'radio' : 'checkbox',
+        preserve: rowSelection.preserve === true || Boolean(server),
+        cascade: rowSelection.cascade === true
+    };
+}
+// Pagination has TableLight's meaning when it is set (`true` always shows the pager), but it is
+// off unless asked for: the Table scrolls any number of rows virtually. Server mode loads rows in
+// blocks as they scroll into view, which is its own paging.
+function normalizePagination({ pagination, pageSize, server }) {
+    if (pagination !== true) return null;
+    if (server) {
+        throw new Error('Table "pagination" needs client data; server mode loads rows in blocks while scrolling.');
+    }
+    return {
+        pageSize: type.isInt(pageSize) && pageSize > 0 ? pageSize : DEFAULT_PAGE_SIZE
+    };
+}
+// Everything derived from properties except `data`, memoised on config content rather than
+// identity, so a re-evaluated but unchanged property set leaves the column model alone. Columns
+// go through the shared column core (`@lowdefy/blocks-antd/table`), the same normalisation and
+// compiled rules, tooltips and templates TableLight uses.
+function useTableConfig({ properties }) {
+    const columnsConfig = useStableConfig(properties.columns);
+    const defaultColumn = useStableConfig(properties.defaultColumn);
+    const defaultView = useStableConfig(properties.defaultView);
+    const rowSelection = useStableConfig(properties.rowSelection);
+    const rowLink = useStableConfig(properties.rowLink);
+    const rowRules = useStableConfig(properties.rowRules);
+    const user = useStableConfig(properties.user);
+    // Client `data` is an array of rows, never compared here; server mode is a small object.
+    const serverData = useStableConfig(type.isObject(properties.data) ? properties.data : null);
+    const tree = useStableConfig(properties.tree);
+    const expandable = useStableConfig(properties.expandable);
+    const toolbar = useStableConfig(properties.toolbar);
+    const persist = useStableConfig(properties.persist);
+    const keyboard = useStableConfig(properties.keyboard);
+    const getKey = useMemo(()=>createRowKeyGetter({
+            rowKey: properties.rowKey
+        }), [
+        properties.rowKey
+    ]);
+    const columnModel = useMemo(()=>{
+        const normalized = normalizeColumns({
+            columns: columnsConfig,
+            defaultColumn
+        });
+        // `$user` values resolve from an empty user when the app sets none.
+        const configUser = user ?? {};
+        const columns = compileColumns({
+            columns: normalized.columns,
+            columnsByKey: normalized.columnsByKey,
+            user: configUser
+        });
+        return {
+            columns,
+            columnsByKey: new Map(columns.map((column)=>[
+                    column.key,
+                    column
+                ])),
+            columnDefs: createColumnDefs({
+                columns
+            }),
+            expandable: normalizeExpandable({
+                expandable,
+                columns,
+                user: configUser
+            }),
+            headerLevels: getHeaderLevels({
+                headerGroups: normalized.headerGroups
+            }),
+            rowRules: compileRules({
+                rules: rowRules,
+                columnsByKey: normalized.columnsByKey,
+                user: configUser
+            }),
+            user: configUser
+        };
+    }, [
+        columnsConfig,
+        defaultColumn,
+        expandable,
+        rowRules,
+        user
+    ]);
+    return useMemo(()=>{
+        const server = normalizeServerData(serverData);
+        return {
+            ...columnModel,
+            bordered: properties.bordered === true,
+            defaultDensity: type.isUndefined(densityHeights[properties.size]) ? 'default' : properties.size,
+            defaultView: defaultView ?? {},
+            emptyText: properties.emptyText ?? 'No data',
+            getId: (row)=>String(getKey(row)),
+            getKey,
+            headerMenu: properties.headerMenu !== false,
+            height: properties.height,
+            keyboard: keyboard !== false,
+            keyboardNext: keyboard?.next === true,
+            maxHeight: properties.maxHeight ?? 600,
+            pagination: normalizePagination({
+                pagination: properties.pagination,
+                pageSize: properties.pageSize,
+                server
+            }),
+            persist: normalizePersist(persist),
+            reorderable: properties.reorderable !== false,
+            rowHeight: properties.rowHeight,
+            rowLink: type.isObject(rowLink) ? rowLink : null,
+            rowSelection: normalizeRowSelection({
+                rowSelection,
+                server
+            }),
+            rowVersionField: properties.rowVersionField,
+            server,
+            stickyHeader: properties.stickyHeader !== false,
+            summary: properties.summary !== false,
+            tree: normalizeTree({
+                tree,
+                server
+            }),
+            toolbar: normalizeToolbar({
+                toolbar,
+                columnsByKey: columnModel.columnsByKey
+            }),
+            virtual: properties.virtual ?? 'auto'
+        };
+    }, [
+        columnModel,
+        defaultView,
+        getKey,
+        properties.bordered,
+        keyboard,
+        persist,
+        properties.emptyText,
+        properties.headerMenu,
+        properties.height,
+        properties.maxHeight,
+        properties.pageSize,
+        properties.pagination,
+        properties.reorderable,
+        properties.rowHeight,
+        properties.rowVersionField,
+        properties.size,
+        properties.stickyHeader,
+        properties.summary,
+        properties.virtual,
+        rowLink,
+        rowSelection,
+        serverData,
+        tree,
+        toolbar
+    ]);
+}
+export default useTableConfig;