beautiful-grid 1.0.9 → 1.0.11

package/README.md

@@ -18,14 +18,34 @@
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/axisj/beautiful-grid/pulls)
 [![Docs](https://img.shields.io/badge/docs-bgrid.axisj.com-blue?logo=googlechrome&logoColor=white)](https://bgrid.axisj.com)
 
+<p align="center">
+  <a href="https://bgrid.axisj.com">
+    <img src="https://raw.githubusercontent.com/axisj/beautiful-grid/main/site/public/og-image-en.png" alt="BeautifulGrid — Beautiful, Powerful Open-Source React Data Grid" width="100%" />
+  </a>
+</p>
+
+<p align="center">
+  <a href="https://bgrid.axisj.com"><strong>🌐 Interactive Docs & Live Demos</strong></a>&nbsp;&nbsp;•&nbsp;&nbsp;
+  <a href="https://youtu.be/BBq4hPsNDNI"><strong>▶️ Watch 1-Min Walkthrough (YouTube)</strong></a>
+</p>
+
 BeautifulGrid is a high-performance, feature-packed, and beautifully designed open-source React Data Grid for data-heavy business applications. It combines zero-runtime-CSS styling with virtual scrolling, spreadsheet-like cell selection and clipboard operations, built-in and plugin cell editing, multi-level grouped headers, filtering & sorting toolboxes, recoverable column visibility, server/client pagination, pivot table transforms, row reordering, and flexible theming.
 
 Explore live interactive examples and in-depth documentation at [bgrid.axisj.com](https://bgrid.axisj.com).
 
 ---
 
+## Video Walkthrough
+
+Watch 1-million row virtual scrolling, keyboard navigation, and interactive cell editing in action (1 min):
+
+[![BeautifulGrid 1-Minute Walkthrough](https://img.youtube.com/vi/BBq4hPsNDNI/maxresdefault.jpg)](https://youtu.be/BBq4hPsNDNI)
+
+---
+
 ## Table of Contents
 
+- [Video Walkthrough](#video-walkthrough)
 - [Install](#install)
 - [Quick Start](#quick-start)
 - [Core Concepts](#core-concepts)
@@ -180,6 +200,33 @@ export default function OrderGridPage() {
 5. **No Runtime CSS-in-JS**:
    - High performance and zero runtime overhead using static `.bgrid-*` classes and `--bgrid-*` CSS custom properties.
 
+### Variable Row Heights
+
+Use `getRowHeight(row, index)` when rows need explicit, data-driven heights. The callback receives the row's
+`values` object and its current displayed index (after client-side sorting or filtering), and returns the complete
+row height in pixels:
+
+```tsx
+<BGrid
+  itemHeight={20}
+  itemPadding={5}
+  getRowHeight={(row, index) => {
+    if (row.type === 'group') return 48;
+    if (index === 0) return 40;
+    return 30;
+  }}
+  {...props}
+/>
+```
+
+BeautifulGrid caches all returned heights and cumulative offsets when the displayed data, callback, or fixed-height
+fallback changes. Scrolling then finds rows with binary search and does not call `getRowHeight` again. Keep the
+callback reference stable (for example with `useCallback`) to avoid rebuilding the cache on parent renders.
+
+Automatic content-based row height measurement is intentionally not supported, because DOM measurement would make
+large virtualized datasets less predictable. When `getRowHeight` is omitted—or returns a non-finite or non-positive
+value—the existing `itemHeight + itemPadding * 2` fixed height is used.
+
 ---
 
 ## Styling & Theming
@@ -920,6 +967,7 @@ Below is a categorized reference of `<BGrid>` props. For exact TypeScript types,
 | `summaryHeight` | `number` | `30` | Summary row height in pixels. |
 | `itemHeight` | `number` | `15` | Body row content height. |
 | `itemPadding` | `number` | `7` | Body row top/bottom padding (total row height = `itemHeight + itemPadding * 2`). |
+| `getRowHeight` | `(row: T, index: number) => number` | — | Complete rendered height for each displayed row. Invalid values fall back to `itemHeight + itemPadding * 2`. |
 | `frozenColumnIndex` | `number` | `0` | Pinned column boundary index (columns `< frozenColumnIndex` are fixed). |
 | `frozenRowCount` | `number` | `0` | Number of leading rows pinned below the top summary row. |
 | `showLineNumber` | `boolean` | `false` | Shows row index numbers and reorder handles on the left. |

package/cjs/BGrid.js

@@ -92,7 +92,7 @@ function computeModelColumns(columns, frozenColumnIndex, duplicateToolboxColumnI
 }
 function BGrid(_a) {
     var _b, _c, _d;
-    var ref = _a.ref, width = _a.width, height = _a.height, _e = _a.headerHeight, headerHeight = _e === void 0 ? 30 : _e, footerHeight = _a.footerHeight, _f = _a.summaryHeight, summaryHeight = _f === void 0 ? 30 : _f, _g = _a.itemHeight, itemHeight = _g === void 0 ? 15 : _g, _h = _a.itemPadding, itemPadding = _h === void 0 ? 7 : _h, columns = _a.columns, columnsGroup = _a.columnsGroup, columnGroups = _a.columnGroups, onChangeColumns = _a.onChangeColumns, _j = _a.frozenColumnIndex, frozenColumnIndex = _j === void 0 ? 0 : _j, _k = _a.frozenRowCount, frozenRowCount = _k === void 0 ? 0 : _k, _l = _a.data, data = _l === void 0 ? [] : _l, page = _a.page, scrollbar = _a.scrollbar, status = _a.status, pagination = _a.pagination, bottomBarHeight = _a.bottomBarHeight, _m = _a.scrollTop, scrollTop = _m === void 0 ? 0 : _m, _o = _a.scrollLeft, scrollLeft = _o === void 0 ? 0 : _o, className = _a.className, style = _a.style, rowChecked = _a.rowChecked, sort = _a.sort, onClick = _a.onClick, _p = _a.loading, loading = _p === void 0 ? false : _p, spinning = _a.spinning, disabled = _a.disabled, rowKey = _a.rowKey, selectedRowKey = _a.selectedRowKey, editable = _a.editable, onChangeData = _a.onChangeData, showLineNumber = _a.showLineNumber, msg = _a.msg, getRowClassName = _a.getRowClassName, _q = _a.editTrigger, editTrigger = _q === void 0 ? 'dblclick' : _q, cellMergeOptions = _a.cellMergeOptions, cellSelectionOptions = _a.cellSelectionOptions, cellNavigationOptions = _a.cellNavigationOptions, variant = _a.variant, summary = _a.summary, columnSortable = _a.columnSortable, reorder = _a.reorder, pivot = _a.pivot, dataControl = _a.dataControl, icons = _a.icons, columnVisibility = _a.columnVisibility, searchOptions = _a.searchOptions, contextMenuOptions = _a.contextMenuOptions;
+    var ref = _a.ref, width = _a.width, height = _a.height, _e = _a.headerHeight, headerHeight = _e === void 0 ? 30 : _e, footerHeight = _a.footerHeight, _f = _a.summaryHeight, summaryHeight = _f === void 0 ? 30 : _f, _g = _a.itemHeight, itemHeight = _g === void 0 ? 15 : _g, _h = _a.itemPadding, itemPadding = _h === void 0 ? 7 : _h, getRowHeight = _a.getRowHeight, columns = _a.columns, columnsGroup = _a.columnsGroup, columnGroups = _a.columnGroups, onChangeColumns = _a.onChangeColumns, _j = _a.frozenColumnIndex, frozenColumnIndex = _j === void 0 ? 0 : _j, _k = _a.frozenRowCount, frozenRowCount = _k === void 0 ? 0 : _k, _l = _a.data, data = _l === void 0 ? [] : _l, page = _a.page, scrollbar = _a.scrollbar, status = _a.status, pagination = _a.pagination, bottomBarHeight = _a.bottomBarHeight, _m = _a.scrollTop, scrollTop = _m === void 0 ? 0 : _m, _o = _a.scrollLeft, scrollLeft = _o === void 0 ? 0 : _o, className = _a.className, style = _a.style, rowChecked = _a.rowChecked, sort = _a.sort, onClick = _a.onClick, _p = _a.loading, loading = _p === void 0 ? false : _p, spinning = _a.spinning, disabled = _a.disabled, rowKey = _a.rowKey, selectedRowKey = _a.selectedRowKey, editable = _a.editable, onChangeData = _a.onChangeData, showLineNumber = _a.showLineNumber, msg = _a.msg, getRowClassName = _a.getRowClassName, _q = _a.editTrigger, editTrigger = _q === void 0 ? 'dblclick' : _q, cellMergeOptions = _a.cellMergeOptions, cellSelectionOptions = _a.cellSelectionOptions, cellNavigationOptions = _a.cellNavigationOptions, variant = _a.variant, summary = _a.summary, columnSortable = _a.columnSortable, reorder = _a.reorder, pivot = _a.pivot, dataControl = _a.dataControl, icons = _a.icons, columnVisibility = _a.columnVisibility, searchOptions = _a.searchOptions, contextMenuOptions = _a.contextMenuOptions;
     var warnedSearchControlledRef = React.useRef({
         open: false,
         query: false,
@@ -387,31 +387,34 @@ function BGrid(_a) {
                 includeRows: false,
             });
         }
-        var sourceIndexByVisibleIndex = resolvedData.map(function (_, i) { return i; });
-        var visibleIndexBySourceIndex = new Map(resolvedData.map(function (_, i) { return [i, i]; }));
         return {
             rows: [],
             data: resolvedData,
-            sourceIndexByVisibleIndex: sourceIndexByVisibleIndex,
-            visibleIndexBySourceIndex: visibleIndexBySourceIndex,
+            sourceIndexByVisibleIndex: undefined,
+            visibleIndexBySourceIndex: undefined,
         };
     }, [queryColumns, resolvedData, resolvedDataControl === null || resolvedDataControl === void 0 ? void 0 : resolvedDataControl.mode, resolvedDataQuery, resolvedRowKey]);
     var displayData = processedResult.data;
+    var rowHeightMetrics = React.useMemo(function () { return (0, utils_1.createRowHeightMetrics)(displayData, itemHeight + itemPadding * 2, getRowHeight); }, [displayData, getRowHeight, itemHeight, itemPadding]);
     var resolvedFrozenRowCount = pivotEnabled
         ? 0
         : Math.min(Math.max(Math.floor(frozenRowCount), 0), displayData.length);
     var checkedIndexesMap = React.useMemo(function () {
         if ((resolvedRowChecked === null || resolvedRowChecked === void 0 ? void 0 : resolvedRowChecked.checkedRowKeys) && resolvedRowKey) {
-            var map_1 = new Map();
-            resolvedRowChecked.checkedRowKeys.forEach(function (key) {
-                var fIndex = resolvedData === null || resolvedData === void 0 ? void 0 : resolvedData.findIndex(function (item, index, obj) {
-                    return (0, utils_1.getCellValueByRowKey)(resolvedRowKey, item.values) === key;
-                });
-                if (fIndex > -1) {
-                    map_1.set(fIndex, true);
+            var remainingKeys = new Set(resolvedRowChecked.checkedRowKeys);
+            var map = new Map();
+            if (remainingKeys.size > 0 && resolvedData) {
+                for (var i = 0; i < resolvedData.length; i++) {
+                    var itemKey = (0, utils_1.getCellValueByRowKey)(resolvedRowKey, resolvedData[i].values);
+                    if (remainingKeys.has(itemKey)) {
+                        map.set(i, true);
+                        remainingKeys.delete(itemKey);
+                        if (remainingKeys.size === 0)
+                            break;
+                    }
                 }
-            });
-            return map_1;
+            }
+            return map;
         }
         if (resolvedRowChecked === null || resolvedRowChecked === void 0 ? void 0 : resolvedRowChecked.checkedIndexes) {
             return new Map(resolvedRowChecked === null || resolvedRowChecked === void 0 ? void 0 : resolvedRowChecked.checkedIndexes.map(function (id) { return [id, true]; }));
@@ -455,7 +458,7 @@ function BGrid(_a) {
         }
     }, [bottomBarHeight, footerHeight]);
     var initialStoreState = React.useMemo(function () {
-        var _a, _b;
+        var _a, _b, _c;
         var initialWidth = width !== undefined ? Math.max(width, 100) : 0;
         var initialHeight = height !== undefined ? Math.max(height, 100) : 0;
         var containerBorderWidth = 1;
@@ -467,7 +470,7 @@ function BGrid(_a) {
                 containerBorderWidth * 2, 0)
             : 0;
         var displayItemCount = contentBodyHeight > 0 ? Math.ceil(contentBodyHeight / (itemHeight + itemPadding * 2)) : 0;
-        var visibleCheckedCount = processedResult.sourceIndexByVisibleIndex.reduce(function (count, sourceIndex) { return count + (checkedIndexesMap.has(sourceIndex) ? 1 : 0); }, 0);
+        var visibleCheckedCount = (0, utils_1.countVisibleCheckedIndexes)(displayData.length, checkedIndexesMap, processedResult.sourceIndexByVisibleIndex);
         var checkedAll = displayData.length === 0
             ? false
             : visibleCheckedCount === displayData.length
@@ -489,7 +492,7 @@ function BGrid(_a) {
             itemPadding: itemPadding,
             frozenColumnIndex: resolvedFrozenColumnIndex,
             frozenRowCount: resolvedFrozenRowCount,
-            frozenRowsHeight: resolvedFrozenRowCount * (itemHeight + itemPadding * 2),
+            frozenRowsHeight: (_a = rowHeightMetrics.offsets[resolvedFrozenRowCount]) !== null && _a !== void 0 ? _a : resolvedFrozenRowCount * (itemHeight + itemPadding * 2),
             frozenColumnsWidth: (0, utils_1.getFrozenColumnsWidth)({
                 showLineNumber: resolvedShowLineNumber,
                 rowChecked: resolvedRowChecked,
@@ -497,7 +500,7 @@ function BGrid(_a) {
                 frozenColumnIndex: resolvedFrozenColumnIndex,
                 columns: computedColumns,
                 dataLength: displayData.length,
-                reorderable: (_a = resolvedReorder === null || resolvedReorder === void 0 ? void 0 : resolvedReorder.enabled) !== null && _a !== void 0 ? _a : false,
+                reorderable: (_b = resolvedReorder === null || resolvedReorder === void 0 ? void 0 : resolvedReorder.enabled) !== null && _b !== void 0 ? _b : false,
             }),
             columns: computedColumns,
             columnsGroup: visibilityProjection.columnsGroup,
@@ -520,7 +523,7 @@ function BGrid(_a) {
             searchOptions: resolvedSearchOptions,
             contextMenuOptions: resolvedContextMenuOptions,
             page: resolvedPage,
-            displayPaginationLength: resolvedPage ? (_b = resolvedPage.displayPaginationLength) !== null && _b !== void 0 ? _b : 5 : 0,
+            displayPaginationLength: resolvedPage ? (_c = resolvedPage.displayPaginationLength) !== null && _c !== void 0 ? _c : 5 : 0,
             loading: loading,
             disabled: resolvedDisabled,
             spinning: spinning,
@@ -558,6 +561,7 @@ function BGrid(_a) {
         summaryHeight,
         itemHeight,
         itemPadding,
+        rowHeightMetrics,
         resolvedPage,
         resolvedSummary,
         checkedIndexesMap,
@@ -609,7 +613,7 @@ function BGrid(_a) {
             onChangeColumns: resolvedOnChangeColumns, width: width, height: height, className: className, style: style, loading: loading, disabled: resolvedDisabled, spinning: spinning, scrollLeft: scrollLeft, scrollTop: scrollTop, headerHeight: headerHeight, footerHeight: footerHeight, bottomBarHeight: resolvedBottomBarHeight,
             scrollbar: resolvedScrollbar,
             status: resolvedStatus,
-            pagination: resolvedPagination, summaryHeight: summaryHeight, itemHeight: itemHeight, itemPadding: itemPadding, frozenColumnIndex: resolvedFrozenColumnIndex,
+            pagination: resolvedPagination, summaryHeight: summaryHeight, itemHeight: itemHeight, itemPadding: itemPadding, rowHeightMetrics: rowHeightMetrics, frozenColumnIndex: resolvedFrozenColumnIndex,
             frozenRowCount: resolvedFrozenRowCount,
             rowChecked: resolvedRowChecked, checkedIndexesMap: checkedIndexesMap, sort: resolvedSort, sortParams: sortParams, dataQuery: resolvedDataQuery,
             dataControl: resolvedDataControl, icons: icons, columnVisibilityState: columnVisibilityState, searchOptions: resolvedSearchOptions,