beautiful-grid 1.0.14 → 1.0.16

package/README.md

@@ -65,6 +65,8 @@ Watch 1-million row virtual scrolling, keyboard navigation, and interactive cell
   - [12. Cell Merging](#12-cell-merging)
   - [13. Pivot Table](#13-pivot-table)
   - [14. Column Visibility](#14-column-visibility)
+  - [15. Tree Grid](#15-tree-grid)
+  - [16. Master-Detail (Nested Grid)](#16-master-detail-nested-grid)
 - [Props Reference](#props-reference)
   - [BGridProps](#bgridprops)
   - [BGridColumn](#bgridcolumn)
@@ -660,6 +662,7 @@ Cell range selection and clipboard copy/paste are enabled by default.
   rowKey='id'
   cellSelectionOptions={{
     enabled: true,
+    multiSelectFocusMode: 'first',
     clearOnEscape: true,
     clearOnOutsideClick: true,
     maxClipboardCells: 100000,
@@ -675,6 +678,7 @@ Cell range selection and clipboard copy/paste are enabled by default.
 
 - `Ctrl+C` / `Cmd+C`: Copies selected cells as Tab-separated (`\t`) values and CRLF (`\r\n`) lines, directly pasteable into Excel or Google Sheets.
 - `Ctrl+V` / `Cmd+V`: Pastes clipboard matrix starting from the focused cell across editable columns.
+- `multiSelectFocusMode: 'last'` makes the last cell selected by a drag the active cell and the paste starting point. The default is `'first'` for backward compatibility.
 - Customize copied text on a per-column basis with `getClipboardText: ({ value, values }) => string`.
 
 ---
@@ -826,8 +830,9 @@ Enable drag-and-drop or keyboard row sorting:
 
 ### 11. Summary Row
 
-Add top or bottom summary/aggregation rows:
+Add top or bottom summary/aggregation rows (supports both single-row and multi-row configurations):
 
+#### Single-Row Summary
 ```typescript jsx
 <BGrid
   width={800}
@@ -840,7 +845,7 @@ Add top or bottom summary/aggregation rows:
     columns: [
       { columnIndex: 0, colSpan: 2, itemRender: () => <strong>Total Summary</strong> },
       {
-        columnIndex: 3,
+        columnIndex: 2,
         align: 'right',
         itemRender: ({ data }) => (
           <strong>${data.reduce((sum, item) => sum + (item.values.amount || 0), 0).toLocaleString()}</strong>
@@ -851,6 +856,48 @@ Add top or bottom summary/aggregation rows:
 />
 ```
 
+#### Multi-Row Summary (e.g. Average & Total)
+```typescript jsx
+<BGrid
+  width={800}
+  height={400}
+  columns={columns}
+  data={data}
+  rowKey='id'
+  summary={{
+    position: 'bottom',
+    rows: [
+      {
+        style: { backgroundColor: '#fffbeb', fontWeight: 600 },
+        columns: [
+          { columnIndex: 0, colSpan: 2, itemRender: () => <span>Average</span> },
+          {
+            columnIndex: 2,
+            align: 'right',
+            itemRender: ({ data }) => (
+              <span>${(data.reduce((sum, item) => sum + (item.values.amount || 0), 0) / (data.length || 1)).toFixed(2)}</span>
+            ),
+          },
+        ],
+      },
+      {
+        style: { backgroundColor: '#f1f5f9', fontWeight: 700 },
+        columns: [
+          { columnIndex: 0, colSpan: 2, itemRender: () => <strong>Total</strong> },
+          {
+            columnIndex: 2,
+            align: 'right',
+            itemRender: ({ data }) => (
+              <strong>${data.reduce((sum, item) => sum + (item.values.amount || 0), 0).toLocaleString()}</strong>
+            ),
+          },
+        ],
+      },
+    ],
+  }}
+/>
+```
+
 ---
 
 ### 12. Cell Merging
@@ -969,6 +1016,45 @@ Rows whose parent is missing are treated as roots. Cycles are contained, the sou
 
 ---
 
+### 16. Master-Detail (Nested Grid)
+
+Expand grid rows to reveal subgrids, nested forms, or detailed child records spanning the full width of the grid with isolated event handling.
+
+```typescript jsx
+const [expandedRowKeys, setExpandedRowKeys] = React.useState(['ORD-001']);
+
+<BGrid
+  width={800}
+  height={450}
+  columns={columns}
+  data={orders}
+  rowKey='orderId'
+  masterDetail={{
+    expandMode: 'multiple',
+    expandedRowKeys,
+    onExpandedRowKeysChange: setExpandedRowKeys,
+    hasDetail: item => item.values.items.length > 0,
+    detailRowHeight: 180,
+    detailRender: ({ item }) => (
+      <div style={{ padding: 12 }}>
+        <h4>Order Items ({item.values.items.length})</h4>
+        <BGrid
+          width={760}
+          height={130}
+          columns={itemColumns}
+          data={item.values.items.map(it => ({ values: it }))}
+          rowKey='itemCode'
+        />
+      </div>
+    ),
+  }}
+/>;
+```
+
+Even when frozen columns are configured, the detail panel renders in a unified full-width layer while master row cells preserve their natural row height. Pointer events, clicks, and keystrokes inside the detail view are isolated from parent table selections and shortcuts.
+
+---
+
 ## Props Reference
 
 ### BGridProps
@@ -990,8 +1076,11 @@ Below is a categorized reference of `<BGrid>` props. For exact TypeScript types,
 | `data`            | `BGridDataItem<T>[]`                                          | Array of row data wrapped in `{ values: T }`.                    |
 | `rowKey`          | `React.Key \| React.Key[]`                                    | Unique identifier field in `item.values` (string or array path). |
 | `selectedRowKey`  | `React.Key \| React.Key[]`                                    | Key of the currently focused/highlighted row.                    |
-| `rowChecked`      | `BGridRowChecked<T>`                                          | Checkbox / radio row selection configuration.                    |
-| `getRowClassName` | `(ri: number, item: BGridDataItem<T>) => string \| undefined` | Custom row class name generator.                                 |
+| `rowChecked`        | `BGridRowChecked<T>`                                          | Checkbox / radio row selection configuration.                    |
+| `getRowClassName`   | `(ri: number, item: BGridDataItem<T>) => string \| undefined` | Custom row class name generator.                                 |
+| `enableLoadMore`    | `boolean`                                                     | Enables infinite scroll / load-more mechanism.                   |
+| `onLoadMore`        | `(params: { scrollLeft: number; scrollTop: number }) => void` | Callback fired when scrolling reaches the load-more threshold.   |
+| `endLoadMoreRender` | `() => React.ReactNode`                                       | Custom renderer for the load-more indicator or end-of-list.     |
 
 #### Layout & Sizing
 
@@ -999,7 +1088,8 @@ Below is a categorized reference of `<BGrid>` props. For exact TypeScript types,
 | ------------------- | ----------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------ |
 | `headerHeight`      | `number`                            | `30`        | Header row height in pixels.                                                                                 |
 | `bottomBarHeight`   | `number`                            | `30`        | Bottom bar (pagination / status) height in pixels.                                                           |
-| `summaryHeight`     | `number`                            | `30`        | Summary row height in pixels.                                                                                |
+| `summaryHeight`     | `number`                            | Auto        | Total summary height in pixels. Defaults to `summaryRowHeight * number of rows` (or `30` for single-row).    |
+| `summaryRowHeight`  | `number`                            | `30`        | Default height in pixels for each individual summary row.                                                    |
 | `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`. |
@@ -1007,6 +1097,11 @@ Below is a categorized reference of `<BGrid>` props. For exact TypeScript types,
 | `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.                                                     |
 | `variant`           | `'default' \| 'vertical-bordered'`  | `'default'` | Visual border styling variant.                                                                               |
+| `className`         | `string`                            | —           | Custom CSS class name for the root grid container.                                                           |
+| `style`             | `React.CSSProperties`               | —           | Inline styles for the root grid container.                                                                   |
+| `disabled`          | `boolean`                           | `false`     | Disables user interactions while preserving view and scrolling.                                              |
+| `scrollTop`         | `number`                            | `0`         | Controlled vertical scroll position in pixels.                                                               |
+| `scrollLeft`        | `number`                            | `0`         | Controlled horizontal scroll position in pixels.                                                             |
 
 #### Columns & Headers
 
@@ -1025,7 +1120,7 @@ Below is a categorized reference of `<BGrid>` props. For exact TypeScript types,
 | `onChangeData`          | `(index, columnIndex, item, column, meta) => void` | -            | Callback fired after a cell edit commits.                    |
 | `onClick`               | `(params: BGridClickParams<T>) => void`            | -            | Cell click callback.                                         |
 | `cellNavigationOptions` | `BGridCellNavigationOptions`                       | -            | Active cell focus, arrow key navigation, and repeat options. |
-| `cellSelectionOptions`  | `BGridCellSelectionOptions`                        | -            | Range drag selection and clipboard copy/paste options.       |
+| `cellSelectionOptions`  | `BGridCellSelectionOptions`                        | -            | Range drag selection, active-cell focus, and clipboard copy/paste options. |
 
 #### Additional Features & Overlays
 
@@ -1040,11 +1135,14 @@ Below is a categorized reference of `<BGrid>` props. For exact TypeScript types,
 | `searchOptions`      | `BGridSearchOptions<T>`                                             | Grid in-memory search UI, shortcuts (`Cmd+F`), and highlights.                         |
 | `contextMenuOptions` | `BGridContextMenuOptions<T>`                                        | Right-click and `Shift+F10` cell context menu items.                                   |
 | `reorder`            | `BGridReorderInfo<T>`                                               | Drag and keyboard row reordering configuration.                                        |
-| `summary`            | `{ position: 'top' \| 'bottom'; columns: BGridSummaryColumn<T>[] }` | Static summary row configuration.                                                      |
+| `reorderingInfo`     | `BGridReorderingInfo`                                               | Reorder drop indicator and dragged state callbacks.                                    |
+| `summary`            | `BGridSummaryOptions<T>`                                            | Static summary row(s) configuration. Supports single row (`columns`) or multiple rows (`rows`). |
 | `cellMergeOptions`   | `{ columnsMap: Record<number, BGridCellMergeColumn> }`              | Vertical cell merge rules.                                                             |
 | `pivot`              | `BGridPivotOptions<T>`                                              | Pivot table dimensions, aggregation rules, and metrics.                                |
 | `columnVisibility`   | `boolean \| BGridColumnVisibilityOptions<T>`                        | Enables controlled or uncontrolled column hiding and restore controls (since `1.0.6`). |
+| `icons`              | `BGridToolboxIcons`                                                 | Custom SVG / ReactNode icons for column toolbox, filter, and sort buttons.             |
 | `tree`               | `BGridTreeOptions<T>`                                               | Renders flat parent-key data as collapsible hierarchical rows.                         |
+| `masterDetail`       | `BGridMasterDetailOptions<T>`                                       | Expands rows to display nested subgrids, forms, or custom detail panels.               |
 | `loading`            | `boolean`                                                           | Displays full-grid loading overlay.                                                    |
 | `spinning`           | `boolean`                                                           | Displays body-area spinner.                                                            |
 | `msg`                | `{ emptyList?: string }`                                            | Custom empty state text.                                                               |
@@ -1120,6 +1218,25 @@ interface BGridDataControl {
 }
 ```
 
+#### `BGridMasterDetailOptions`
+
+```typescript
+interface BGridMasterDetailOptions<T> {
+  expandMode?: 'multiple' | 'single';
+  expandedRowKeys?: React.Key[];
+  defaultExpandedRowKeys?: React.Key[];
+  onExpandedRowKeysChange?: (
+    expandedRowKeys: React.Key[],
+    event: BGridMasterDetailChangeEvent<T>,
+  ) => void;
+  hasDetail?: (item: BGridDataItem<T>, index: number) => boolean;
+  detailRowHeight?: number;
+  detailRender: (props: BGridMasterDetailRenderProps<T>) => React.ReactNode;
+  expandColumnId?: string;
+  icons?: BGridMasterDetailIcons;
+}
+```
+
 ---
 
 ## Developer Workflows