Use mouse down event to select cell (#3774)

I checked a few popular grids and all select the cell on pointer down but they do not scroll the cell into view which we do. Not sure which behavior is better

🆕 onCellMouseDown event

Author: amanmahajan7

README.md

@@ -317,12 +317,26 @@ function MyGrid() {
 
 ###### `onFill?: Maybe<(event: FillEvent<R>) => R>`
 
-###### `onCellClick?: Maybe<(args: CellClickArgs<R, SR>, event: CellMouseEvent) => void>`
+###### `onCellMouseDown: Maybe<(args: CellMouseArgs<R, SR>, event: CellMouseEvent) => void>`
 
-Callback triggered when a cell is clicked. The default behavior is to select the cell. Call `preventGridDefault` to prevent the default behavior
+Callback triggered when a pointer becomes active in a cell. The default behavior is to select the cell. Call `preventGridDefault` to prevent the default behavior.
 
 ```tsx
-function onCellClick(args: CellClickArgs<R, SR>, event: CellMouseEvent) {
+function onCellMouseDown(args: CellMouseDownArgs<R, SR>, event: CellMouseEvent) {
+  if (args.column.key === 'id') {
+    event.preventGridDefault();
+  }
+}
+
+<DataGrid rows={rows} columns={columns} onCellMouseDown={onCellMouseDown} />;
+```
+
+###### `onCellClick?: Maybe<(args: CellMouseArgs<R, SR>, event: CellMouseEvent) => void>`
+
+Callback triggered when a cell is clicked.
+
+```tsx
+function onCellClick(args: CellMouseArgs<R, SR>, event: CellMouseEvent) {
   if (args.column.key === 'id') {
     event.preventGridDefault();
   }
@@ -334,17 +348,16 @@ function onCellClick(args: CellClickArgs<R, SR>, event: CellMouseEvent) {
 This event can be used to open cell editor on single click
 
 ```tsx
-function onCellClick(args: CellClickArgs<R, SR>, event: CellMouseEvent) {
+function onCellClick(args: CellMouseArgs<R, SR>, event: CellMouseEvent) {
   if (args.column.key === 'id') {
-    event.preventGridDefault();
     args.selectCell(true);
   }
 }
 ```
 
 Arguments:
 
-`args: CellClickArgs<R, SR>`
+`args: CellMouseArgs<R, SR>`
 
 - `args.rowIdx`: `number` - row index of the currently selected cell
 - `args.row`: `R` - row object of the currently selected cell
@@ -356,12 +369,12 @@ Arguments:
 - `event.preventGridDefault:`: `() => void`
 - `event.isGridDefaultPrevented`: `boolean`
 
-###### `onCellDoubleClick?: Maybe<(args: CellClickArgs<R, SR>, event: CellMouseEvent) => void>`
+###### `onCellDoubleClick?: Maybe<(args: CellMouseArgs<R, SR>, event: CellMouseEvent) => void>`
 
-Callback triggered when a cell is double-clicked. The default behavior is to open the editor if the cell is editable. Call `preventGridDefault` to prevent the default behavior
+Callback triggered when a cell is double-clicked. The default behavior is to open the editor if the cell is editable. Call `preventGridDefault` to prevent the default behavior.
 
 ```tsx
-function onCellDoubleClick(args: CellClickArgs<R, SR>, event: CellMouseEvent) {
+function onCellDoubleClick(args: CellMouseArgs<R, SR>, event: CellMouseEvent) {
   if (args.column.key === 'id') {
     event.preventGridDefault();
   }
@@ -370,14 +383,15 @@ function onCellDoubleClick(args: CellClickArgs<R, SR>, event: CellMouseEvent) {
 <DataGrid rows={rows} columns={columns} onCellDoubleClick={onCellDoubleClick} />;
 ```
 
-###### `onCellContextMenu?: Maybe<(args: CellClickArgs<R, SR>, event: CellMouseEvent) => void>`
+###### `onCellContextMenu?: Maybe<(args: CellMouseArgs<R, SR>, event: CellMouseEvent) => void>`
 
-Callback triggered when a cell is right-clicked. The default behavior is to select the cell. Call `preventGridDefault` to prevent the default behavior
+Callback triggered when a cell is right-clicked.
 
 ```tsx
-function onCellContextMenu(args: CellClickArgs<R, SR>, event: CellMouseEvent) {
+function onCellContextMenu(args: CellMouseArgs<R, SR>, event: CellMouseEvent) {
   if (args.column.key === 'id') {
-    event.preventGridDefault();
+    event.preventDefault();
+    // open custom context menu
   }
 }
 
@@ -412,11 +426,11 @@ function onCellKeyDown(args: CellKeyDownArgs<R, SR>, event: CellKeyboardEvent) {
 
 Check [more examples](website/routes/CellNavigation.tsx)
 
-###### `onCellCopy?: Maybe<(args: CellCopyEvent<NoInfer<R>, NoInfer<SR>>, event: CellClipboardEvent) => void>`
+###### `onCellCopy?: Maybe<(args: CellCopyArgs<NoInfer<R>, NoInfer<SR>>, event: CellClipboardEvent) => void>`
 
 Callback triggered when a cell's content is copied.
 
-###### `onCellPaste?: Maybe<(args: CellPasteEvent<NoInfer<R>, NoInfer<SR>>, event: CellClipboardEvent) => void>`
+###### `onCellPaste?: Maybe<(args: CellPasteArgs<NoInfer<R>, NoInfer<SR>>, event: CellClipboardEvent) => void>`
 
 Callback triggered when content is pasted into a cell.
 

src/Cell.tsx

@@ -1,9 +1,9 @@
-import { memo } from 'react';
+import { memo, type MouseEvent } from 'react';
 import { css } from '@linaria/core';
 
 import { useRovingTabIndex } from './hooks';
 import { createCellEvent, getCellClassname, getCellStyle, isCellEditableUtil } from './utils';
-import type { CellRendererProps } from './types';
+import type { CellMouseEventHandler, CellRendererProps } from './types';
 
 const cellDraggedOver = css`
   @layer rdg.Cell {
@@ -21,9 +21,14 @@ function Cell<R, SR>({
   row,
   rowIdx,
   className,
+  onMouseDown,
+  onCellMouseDown,
   onClick,
+  onCellClick,
   onDoubleClick,
+  onCellDoubleClick,
   onContextMenu,
+  onCellContextMenu,
   onRowChange,
   selectCell,
   style,
@@ -46,31 +51,43 @@ function Cell<R, SR>({
     selectCell({ rowIdx, idx: column.idx }, openEditor);
   }
 
-  function handleClick(event: React.MouseEvent<HTMLDivElement>) {
-    if (onClick) {
+  function handleMouseEvent(
+    event: React.MouseEvent<HTMLDivElement>,
+    eventHandler?: CellMouseEventHandler<R, SR>
+  ) {
+    let eventHandled = false;
+    if (eventHandler) {
       const cellEvent = createCellEvent(event);
-      onClick({ rowIdx, row, column, selectCell: selectCellWrapper }, cellEvent);
-      if (cellEvent.isGridDefaultPrevented()) return;
+      eventHandler({ rowIdx, row, column, selectCell: selectCellWrapper }, cellEvent);
+      eventHandled = cellEvent.isGridDefaultPrevented();
     }
-    selectCellWrapper();
+    return eventHandled;
   }
 
-  function handleContextMenu(event: React.MouseEvent<HTMLDivElement>) {
-    if (onContextMenu) {
-      const cellEvent = createCellEvent(event);
-      onContextMenu({ rowIdx, row, column, selectCell: selectCellWrapper }, cellEvent);
-      if (cellEvent.isGridDefaultPrevented()) return;
+  function handleMouseDown(event: MouseEvent<HTMLDivElement>) {
+    onMouseDown?.(event);
+    if (!handleMouseEvent(event, onCellMouseDown)) {
+      // select cell if the event is not prevented
+      selectCellWrapper();
     }
-    selectCellWrapper();
   }
 
-  function handleDoubleClick(event: React.MouseEvent<HTMLDivElement>) {
-    if (onDoubleClick) {
-      const cellEvent = createCellEvent(event);
-      onDoubleClick({ rowIdx, row, column, selectCell: selectCellWrapper }, cellEvent);
-      if (cellEvent.isGridDefaultPrevented()) return;
+  function handleClick(event: MouseEvent<HTMLDivElement>) {
+    onClick?.(event);
+    handleMouseEvent(event, onCellClick);
+  }
+
+  function handleDoubleClick(event: MouseEvent<HTMLDivElement>) {
+    onDoubleClick?.(event);
+    if (!handleMouseEvent(event, onCellDoubleClick)) {
+      // go into edit mode if the event is not prevented
+      selectCellWrapper(true);
     }
-    selectCellWrapper(true);
+  }
+
+  function handleContextMenu(event: MouseEvent<HTMLDivElement>) {
+    onContextMenu?.(event);
+    handleMouseEvent(event, onCellContextMenu);
   }
 
   function handleRowChange(newRow: R) {
@@ -91,6 +108,7 @@ function Cell<R, SR>({
         ...style
       }}
       onClick={handleClick}
+      onMouseDown={handleMouseDown}
       onDoubleClick={handleDoubleClick}
       onContextMenu={handleContextMenu}
       onFocus={onFocus}

src/DataGrid.tsx

@@ -40,14 +40,13 @@ import {
 } from './utils';
 import type {
   CalculatedColumn,
-  CellClickArgs,
   CellClipboardEvent,
-  CellCopyEvent,
+  CellCopyArgs,
   CellKeyboardEvent,
   CellKeyDownArgs,
-  CellMouseEvent,
+  CellMouseEventHandler,
   CellNavigationMode,
-  CellPasteEvent,
+  CellPasteArgs,
   CellSelectArgs,
   Column,
   ColumnOrColumnGroup,
@@ -186,29 +185,25 @@ export interface DataGridProps<R, SR = unknown, K extends Key = Key> extends Sha
   /**
    * Event props
    */
+  /** Callback triggered when a pointer becomes active in a cell */
+  onCellMouseDown?: CellMouseEventHandler<R, SR>;
   /** Callback triggered when a cell is clicked */
-  onCellClick?: Maybe<
-    (args: CellClickArgs<NoInfer<R>, NoInfer<SR>>, event: CellMouseEvent) => void
-  >;
+  onCellClick?: CellMouseEventHandler<R, SR>;
   /** Callback triggered when a cell is double-clicked */
-  onCellDoubleClick?: Maybe<
-    (args: CellClickArgs<NoInfer<R>, NoInfer<SR>>, event: CellMouseEvent) => void
-  >;
+  onCellDoubleClick?: CellMouseEventHandler<R, SR>;
   /** Callback triggered when a cell is right-clicked */
-  onCellContextMenu?: Maybe<
-    (args: CellClickArgs<NoInfer<R>, NoInfer<SR>>, event: CellMouseEvent) => void
-  >;
+  onCellContextMenu?: CellMouseEventHandler<R, SR>;
   /** Callback triggered when a key is pressed in a cell */
   onCellKeyDown?: Maybe<
     (args: CellKeyDownArgs<NoInfer<R>, NoInfer<SR>>, event: CellKeyboardEvent) => void
   >;
   /** Callback triggered when a cell's content is copied */
   onCellCopy?: Maybe<
-    (args: CellCopyEvent<NoInfer<R>, NoInfer<SR>>, event: CellClipboardEvent) => void
+    (args: CellCopyArgs<NoInfer<R>, NoInfer<SR>>, event: CellClipboardEvent) => void
   >;
   /** Callback triggered when content is pasted into a cell */
   onCellPaste?: Maybe<
-    (args: CellPasteEvent<NoInfer<R>, NoInfer<SR>>, event: CellClipboardEvent) => NoInfer<R>
+    (args: CellPasteArgs<NoInfer<R>, NoInfer<SR>>, event: CellClipboardEvent) => NoInfer<R>
   >;
   /** Function called whenever cell selection is changed */
   onSelectedCellChange?: Maybe<(args: CellSelectArgs<NoInfer<R>, NoInfer<SR>>) => void>;
@@ -274,6 +269,7 @@ export function DataGrid<R, SR = unknown, K extends Key = Key>(props: DataGridPr
     onSortColumnsChange,
     defaultColumnOptions,
     // Event props
+    onCellMouseDown,
     onCellClick,
     onCellDoubleClick,
     onCellContextMenu,
@@ -493,6 +489,7 @@ export function DataGrid<R, SR = unknown, K extends Key = Key>(props: DataGridPr
   const handleColumnResizeEndLatest = useLatestFunc(handleColumnResizeEnd);
   const onColumnsReorderLastest = useLatestFunc(onColumnsReorder);
   const onSortColumnsChangeLatest = useLatestFunc(onSortColumnsChange);
+  const onCellMouseDownLatest = useLatestFunc(onCellMouseDown);
   const onCellClickLatest = useLatestFunc(onCellClick);
   const onCellDoubleClickLatest = useLatestFunc(onCellDoubleClick);
   const onCellContextMenuLatest = useLatestFunc(onCellContextMenu);
@@ -525,23 +522,17 @@ export function DataGrid<R, SR = unknown, K extends Key = Key>(props: DataGridPr
   /**
    * effects
    */
-  useLayoutEffect(() => {
-    if (
-      focusSinkRef.current !== null &&
-      selectedCellIsWithinSelectionBounds &&
-      selectedPosition.idx === -1
-    ) {
-      focusSinkRef.current.focus({ preventScroll: true });
-      scrollIntoView(focusSinkRef.current);
-    }
-  }, [selectedCellIsWithinSelectionBounds, selectedPosition]);
-
   useLayoutEffect(() => {
     if (shouldFocusCell) {
+      if (focusSinkRef.current !== null && selectedPosition.idx === -1) {
+        focusSinkRef.current.focus({ preventScroll: true });
+        scrollIntoView(focusSinkRef.current);
+      } else {
+        focusCellOrCellContent();
+      }
       setShouldFocusCell(false);
-      focusCellOrCellContent();
     }
-  }, [shouldFocusCell, focusCellOrCellContent]);
+  }, [shouldFocusCell, focusCellOrCellContent, selectedPosition.idx]);
 
   useImperativeHandle(ref, () => ({
     element: gridRef.current,
@@ -1141,6 +1132,7 @@ export function DataGrid<R, SR = unknown, K extends Key = Key>(props: DataGridPr
           viewportColumns: rowColumns,
           isRowSelectionDisabled: isRowSelectionDisabled?.(row) ?? false,
           isRowSelected,
+          onCellMouseDown: onCellMouseDownLatest,
           onCellClick: onCellClickLatest,
           onCellDoubleClick: onCellDoubleClickLatest,
           onCellContextMenu: onCellContextMenuLatest,

src/GroupCell.tsx

@@ -50,6 +50,10 @@ function GroupCell<R, SR>({
         ...getCellStyle(column),
         cursor: isLevelMatching ? 'pointer' : 'default'
       }}
+      onMouseDown={(event) => {
+        // prevents clicking on the cell from stealing focus from focusSink
+        event.preventDefault();
+      }}
       onClick={isLevelMatching ? toggleGroup : undefined}
       onFocus={onFocus}
     >

src/GroupRow.tsx

@@ -72,7 +72,7 @@ function GroupedRow<R, SR>({
           selectedCellIdx === -1 && rowSelectedClassname,
           className
         )}
-        onClick={handleSelectGroup}
+        onMouseDown={handleSelectGroup}
         style={getRowStyle(gridRowStart)}
         {...props}
       >

src/GroupedColumnHeaderCell.tsx

@@ -27,7 +27,7 @@ export default function GroupedColumnHeaderCell<R, SR>({
   const rowSpan = getHeaderCellRowSpan(column, rowIdx);
   const index = column.idx + 1;
 
-  function onClick() {
+  function onMouseDown() {
     selectCell({ idx: column.idx, rowIdx });
   }
 
@@ -46,7 +46,7 @@ export default function GroupedColumnHeaderCell<R, SR>({
         gridColumnEnd: index + colSpan
       }}
       onFocus={onFocus}
-      onClick={onClick}
+      onMouseDown={onMouseDown}
     >
       {column.name}
     </div>

src/HeaderCell.tsx

@@ -145,9 +145,11 @@ export default function HeaderCell<R, SR>({
     }
   }
 
-  function onClick(event: React.MouseEvent<HTMLSpanElement>) {
+  function onMouseDown() {
     selectCell({ idx: column.idx, rowIdx });
+  }
 
+  function onClick(event: React.MouseEvent<HTMLSpanElement>) {
     if (sortable) {
       onSort(event.ctrlKey || event.metaKey);
     }
@@ -250,6 +252,7 @@ export default function HeaderCell<R, SR>({
         ...getHeaderCellStyle(column, rowIdx, rowSpan),
         ...getCellStyle(column, colSpan)
       }}
+      onMouseDown={onMouseDown}
       onFocus={onFocus}
       onClick={onClick}
       onKeyDown={onKeyDown}

src/Row.tsx

@@ -19,6 +19,7 @@ function Row<R, SR>({
   row,
   viewportColumns,
   selectedCellEditor,
+  onCellMouseDown,
   onCellClick,
   onCellDoubleClick,
   onCellContextMenu,
@@ -67,9 +68,10 @@ function Row<R, SR>({
           rowIdx,
           isDraggedOver: draggedOverCellIdx === idx,
           isCellSelected,
-          onClick: onCellClick,
-          onDoubleClick: onCellDoubleClick,
-          onContextMenu: onCellContextMenu,
+          onCellMouseDown,
+          onCellClick,
+          onCellDoubleClick,
+          onCellContextMenu,
           onRowChange: handleRowChange,
           selectCell
         })