Row Grouping (glideapps#898)

Adds row grouping support. This is not a complete implementation yet as it does not yet support overriding vertical borders or implement sticky headers.

Author: jassmith

packages/core/src/data-editor/data-editor.tsx

@@ -81,6 +81,8 @@ import {
 } from "../internal/data-grid/event-args.js";
 import { type Keybinds, useKeybindingsWithDefaults } from "./data-editor-keybindings.js";
 import type { Highlight } from "../internal/data-grid/render/data-grid-render.cells.js";
+import { useRowGroupingInner, type RowGroupingOptions } from "./row-grouping.js";
+import { useRowGrouping } from "./row-grouping-api.js";
 
 const DataGridOverlayEditor = React.lazy(
     async () => await import("../internal/data-grid-overlay-editor/data-grid-overlay-editor.js")
@@ -121,6 +123,7 @@ type Props = Partial<
         | "getCellContent"
         | "getCellRenderer"
         | "getCellsForSelection"
+        | "getRowThemeOverride"
         | "gridRef"
         | "groupHeaderHeight"
         | "headerHeight"
@@ -443,6 +446,15 @@ export interface DataEditorProps extends Props, Pick<DataGridSearchProps, "image
      */
     readonly markdownDivCreateNode?: (content: string) => DocumentFragment;
 
+    /**
+     * Allows overriding the theme of any row
+     * @param row represents the row index of the row, increasing by 1 for every represented row. Collapsed rows are not included.
+     * @param groupRow represents the row index of the group row. Only distinct when row grouping enabled.
+     * @param contentRow represents the index of the row excluding group headers. Only distinct when row grouping enabled.
+     * @returns
+     */
+    readonly getRowThemeOverride?: (row: number, groupRow: number, contentRow: number) => Partial<Theme> | undefined;
+
     /** Callback for providing a custom editor for a cell.
      * @group Editing
      */
@@ -580,6 +592,11 @@ export interface DataEditorProps extends Props, Pick<DataGridSearchProps, "image
      */
     readonly verticalBorder?: DataGridSearchProps["verticalBorder"] | boolean;
 
+    /**
+     * Controls the grouping of rows to be drawn in the grid.
+     */
+    readonly rowGrouping?: RowGroupingOptions;
+
     /**
      * Called when data is pasted into the grid. If left undefined, the `DataEditor` will operate in a
      * fallback mode and attempt to paste the text buffer into the current cell assuming the current cell is not
@@ -722,12 +739,12 @@ const DataEditorImpl: React.ForwardRefRenderFunction<DataEditorRef, DataEditorPr
 
     const {
         imageEditorOverride,
-        getRowThemeOverride,
+        getRowThemeOverride: getRowThemeOverrideIn,
         markdownDivCreateNode,
         width,
         height,
         columns: columnsIn,
-        rows,
+        rows: rowsIn,
         getCellContent,
         onCellClicked,
         onCellActivated,
@@ -778,6 +795,7 @@ const DataEditorImpl: React.ForwardRefRenderFunction<DataEditorRef, DataEditorPr
         onHeaderMenuClick,
         onHeaderIndicatorClick,
         getGroupDetails,
+        rowGrouping,
         onSearchClose: onSearchCloseIn,
         onItemHovered,
         onSelectionCleared,
@@ -847,22 +865,28 @@ const DataEditorImpl: React.ForwardRefRenderFunction<DataEditorRef, DataEditorPr
         return window.getComputedStyle(document.documentElement);
     }, []);
 
-    const remSize = React.useMemo(() => Number.parseFloat(docStyle.fontSize), [docStyle]);
+    const {
+        rows,
+        rowNumberMapper,
+        rowHeight: rowHeightPostGrouping,
+        getRowThemeOverride,
+    } = useRowGroupingInner(rowGrouping, rowsIn, rowHeightIn, getRowThemeOverrideIn);
 
+    const remSize = React.useMemo(() => Number.parseFloat(docStyle.fontSize), [docStyle]);
     const { rowHeight, headerHeight, groupHeaderHeight, theme, overscrollX, overscrollY } = useRemAdjuster({
         groupHeaderHeight: groupHeaderHeightIn,
         headerHeight: headerHeightIn,
         overscrollX: overscrollXIn,
         overscrollY: overscrollYIn,
         remSize,
-        rowHeight: rowHeightIn,
+        rowHeight: rowHeightPostGrouping,
         scaleToRem,
         theme: themeIn,
     });
 
     const keybindings = useKeybindingsWithDefaults(keybindingsIn);
 
-    const rowMarkerWidth = rowMarkerWidthRaw ?? (rows > 10_000 ? 48 : rows > 1000 ? 44 : rows > 100 ? 36 : 32);
+    const rowMarkerWidth = rowMarkerWidthRaw ?? (rowsIn > 10_000 ? 48 : rowsIn > 1000 ? 44 : rowsIn > 100 ? 36 : 32);
     const hasRowMarkers = rowMarkers !== "none";
     const rowMarkerOffset = hasRowMarkers ? 1 : 0;
     const showTrailingBlankRow = onRowAppended !== undefined;
@@ -1267,13 +1291,15 @@ const DataEditorImpl: React.ForwardRefRenderFunction<DataEditorRef, DataEditorPr
                 if (isTrailing) {
                     return loadingCell;
                 }
+                const mappedRow = rowNumberMapper(row);
+                if (mappedRow === undefined) return loadingCell;
                 return {
                     kind: InnerGridCellKind.Marker,
                     allowOverlay: false,
                     checkboxStyle: rowMarkerCheckboxStyle,
                     checked: gridSelection?.rows.hasIndex(row) === true,
                     markerKind: rowMarkers === "clickable-number" ? "number" : rowMarkers,
-                    row: rowMarkerStartIndex + row,
+                    row: rowMarkerStartIndex + mappedRow,
                     drawHandle: onRowMoved !== undefined,
                     cursor: rowMarkers === "clickable-number" ? "pointer" : undefined,
                 };
@@ -1335,6 +1361,7 @@ const DataEditorImpl: React.ForwardRefRenderFunction<DataEditorRef, DataEditorPr
             showTrailingBlankRow,
             mangledRows,
             hasRowMarkers,
+            rowNumberMapper,
             rowMarkerCheckboxStyle,
             gridSelection?.rows,
             rowMarkers,
@@ -1721,6 +1748,10 @@ const DataEditorImpl: React.ForwardRefRenderFunction<DataEditorRef, DataEditorPr
         [getRowThemeOverride, mangledCols, mergedTheme]
     );
 
+    const { mapper } = useRowGrouping(rowGrouping, rowsIn);
+
+    const rowGroupingNavBehavior = rowGrouping?.navigationBehavior;
+
     const handleSelect = React.useCallback(
         (args: GridMouseEventArgs) => {
             const isMultiKey = browserIsOSX.value ? args.metaKey : args.ctrlKey;
@@ -1818,6 +1849,11 @@ const DataEditorImpl: React.ForwardRefRenderFunction<DataEditorRef, DataEditorPr
                                 return;
                             }
                         }
+
+                        if (rowGroupingNavBehavior === "block" && mapper(row).isGroupHeader) {
+                            return;
+                        }
+
                         const isLastStickyRow = lastRowSticky && row === rows;
 
                         const startedFromLastSticky =
@@ -1927,28 +1963,30 @@ const DataEditorImpl: React.ForwardRefRenderFunction<DataEditorRef, DataEditorPr
             }
         },
         [
-            appendRow,
+            rowSelect,
             columnSelect,
-            focus,
-            getCellRenderer,
-            getCustomNewRowTargetColumn,
-            getMangledCellContent,
             gridSelection,
             hasRowMarkers,
-            lastRowSticky,
-            onSelectionCleared,
-            onRowMoved,
             rowMarkerOffset,
+            showTrailingBlankRow,
+            rows,
             rowMarkers,
-            rowSelect,
+            getMangledCellContent,
+            onRowMoved,
+            focus,
             rowSelectionMode,
-            rows,
+            getCellRenderer,
+            themeForCell,
+            setSelectedRows,
+            getCustomNewRowTargetColumn,
+            appendRow,
+            rowGroupingNavBehavior,
+            mapper,
+            lastRowSticky,
             setCurrent,
-            setGridSelection,
             setSelectedColumns,
-            setSelectedRows,
-            showTrailingBlankRow,
-            themeForCell,
+            setGridSelection,
+            onSelectionCleared,
         ]
     );
     const isActivelyDraggingHeader = React.useRef(false);
@@ -2542,6 +2580,27 @@ const DataEditorImpl: React.ForwardRefRenderFunction<DataEditorRef, DataEditorPr
         isActivelyDragging.current = false;
     }, []);
 
+    const rowGroupingSelectionBehavior = rowGrouping?.selectionBehavior;
+
+    const getSelectionRowLimits = React.useCallback(
+        (selectedRow: number): readonly [number, number] | undefined => {
+            if (rowGroupingSelectionBehavior !== "block-spanning") return undefined;
+
+            const { isGroupHeader, path, groupRows } = mapper(selectedRow);
+
+            if (isGroupHeader) {
+                return [selectedRow, selectedRow];
+            }
+
+            const groupRowIndex = path[path.length - 1];
+            const lowerBounds = selectedRow - groupRowIndex;
+            const upperBounds = selectedRow + groupRows - groupRowIndex - 1;
+
+            return [lowerBounds, upperBounds];
+        },
+        [mapper, rowGroupingSelectionBehavior]
+    );
+
     const hoveredRef = React.useRef<GridMouseEventArgs>();
     const onItemHoveredImpl = React.useCallback(
         (args: GridMouseEventArgs) => {
@@ -2596,6 +2655,10 @@ const DataEditorImpl: React.ForwardRefRenderFunction<DataEditorRef, DataEditorPr
                     }
 
                     col = Math.max(col, rowMarkerOffset);
+                    const clampLimits = getSelectionRowLimits(selectedRow);
+                    row = clampLimits === undefined ? row : clamp(row, clampLimits[0], clampLimits[1]);
+
+                    // FIXME: Restrict row based on rowGrouping.selectionBehavior here
 
                     const deltaX = col - selectedCol;
                     const deltaY = row - selectedRow;
@@ -2622,7 +2685,6 @@ const DataEditorImpl: React.ForwardRefRenderFunction<DataEditorRef, DataEditorPr
             onItemHovered?.({ ...args, location: [args.location[0] - rowMarkerOffset, args.location[1]] as any });
         },
         [
-            allowedFillDirections,
             mouseState,
             rowMarkerOffset,
             rowSelect,
@@ -2632,6 +2694,8 @@ const DataEditorImpl: React.ForwardRefRenderFunction<DataEditorRef, DataEditorPr
             setSelectedRows,
             showTrailingBlankRow,
             rows,
+            allowedFillDirections,
+            getSelectionRowLimits,
             setCurrent,
         ]
     );
@@ -2676,20 +2740,23 @@ const DataEditorImpl: React.ForwardRefRenderFunction<DataEditorRef, DataEditorPr
             let top = old.y;
             let bottom = old.y + old.height;
 
+            const [minRow, maxRowRaw] = getSelectionRowLimits(row) ?? [0, rows - 1];
+            const maxRow = maxRowRaw + 1; // we need an inclusive value
+
             // take care of vertical first in case new spans come in
             if (y !== 0) {
                 switch (y) {
                     case 2: {
                         // go to end
-                        bottom = rows;
+                        bottom = maxRow;
                         top = row;
                         scrollTo(0, bottom, "vertical");
 
                         break;
                     }
                     case -2: {
                         // go to start
-                        top = 0;
+                        top = minRow;
                         bottom = row + 1;
                         scrollTo(0, top, "vertical");
 
@@ -2701,7 +2768,7 @@ const DataEditorImpl: React.ForwardRefRenderFunction<DataEditorRef, DataEditorPr
                             top++;
                             scrollTo(0, top, "vertical");
                         } else {
-                            bottom = Math.min(rows, bottom + 1);
+                            bottom = Math.min(maxRow, bottom + 1);
                             scrollTo(0, bottom, "vertical");
                         }
 
@@ -2713,7 +2780,7 @@ const DataEditorImpl: React.ForwardRefRenderFunction<DataEditorRef, DataEditorPr
                             bottom--;
                             scrollTo(0, bottom, "vertical");
                         } else {
-                            top = Math.max(0, top - 1);
+                            top = Math.max(minRow, top - 1);
                             scrollTo(0, top, "vertical");
                         }
 
@@ -2816,7 +2883,16 @@ const DataEditorImpl: React.ForwardRefRenderFunction<DataEditorRef, DataEditorPr
                 "keyboard-select"
             );
         },
-        [getCellsForSelection, gridSelection, mangledCols.length, rowMarkerOffset, rows, scrollTo, setCurrent]
+        [
+            getCellsForSelection,
+            getSelectionRowLimits,
+            gridSelection,
+            mangledCols.length,
+            rowMarkerOffset,
+            rows,
+            scrollTo,
+            setCurrent,
+        ]
     );
 
     const updateSelectedCell = React.useCallback(
@@ -2825,7 +2901,10 @@ const DataEditorImpl: React.ForwardRefRenderFunction<DataEditorRef, DataEditorPr
             col = clamp(col, rowMarkerOffset, columns.length - 1 + rowMarkerOffset);
             row = clamp(row, 0, rowMax);
 
-            if (col === currentCell?.[0] && row === currentCell?.[1]) return false;
+            const curCol = currentCell?.[0];
+            const curRow = currentCell?.[1];
+
+            if (col === curCol && row === curRow) return false;
             if (freeMove && gridSelection.current !== undefined) {
                 const newStack = [...gridSelection.current.rangeStack];
                 if (gridSelection.current.range.width > 1 || gridSelection.current.range.height > 1) {
@@ -3041,6 +3120,7 @@ const DataEditorImpl: React.ForwardRefRenderFunction<DataEditorRef, DataEditorPr
 
             if (gridSelection.current === undefined) return false;
             let [col, row] = gridSelection.current.cell;
+            const [, startRow] = gridSelection.current.cell;
             let freeMove = false;
             let cancelOnlyOnMove = false;
 
@@ -3174,6 +3254,37 @@ const DataEditorImpl: React.ForwardRefRenderFunction<DataEditorRef, DataEditorPr
             }
             // #endregion
 
+            const mustRestrictRow = rowGroupingNavBehavior !== undefined && rowGroupingNavBehavior !== "normal";
+
+            if (mustRestrictRow && row !== startRow) {
+                const skipUp =
+                    rowGroupingNavBehavior === "skip-up" ||
+                    rowGroupingNavBehavior === "skip" ||
+                    rowGroupingNavBehavior === "block";
+                const skipDown =
+                    rowGroupingNavBehavior === "skip-down" ||
+                    rowGroupingNavBehavior === "skip" ||
+                    rowGroupingNavBehavior === "block";
+                const didMoveUp = row < startRow;
+                if (didMoveUp && skipUp) {
+                    while (row >= 0 && mapper(row).isGroupHeader) {
+                        row--;
+                    }
+
+                    if (row < 0) {
+                        row = startRow;
+                    }
+                } else if (!didMoveUp && skipDown) {
+                    while (row < rows && mapper(row).isGroupHeader) {
+                        row++;
+                    }
+
+                    if (row >= rows) {
+                        row = startRow;
+                    }
+                }
+            }
+
             const moved = updateSelectedCell(col, row, false, freeMove);
 
             const didMatch = details.didMatch;
@@ -3185,13 +3296,15 @@ const DataEditorImpl: React.ForwardRefRenderFunction<DataEditorRef, DataEditorPr
             return didMatch;
         },
         [
+            rowGroupingNavBehavior,
             overlayOpen,
             gridSelection,
             keybindings,
             columnSelect,
             rowSelect,
             rangeSelect,
             rowMarkerOffset,
+            mapper,
             rows,
             updateSelectedCell,
             setGridSelection,