@opencorestack/opengridx 2.0.4 → 3.0.0

package/lib/hooks/features/useAggregation.ts

@@ -1,7 +1,7 @@
-
 import { useMemo, useEffect, useRef, useCallback, useState } from 'react';
 import type {
     GridRowModel,
+    GridValidRowModel,
     GridColDef,
     GridAggregationModel,
     GridAggregationResult,
@@ -9,45 +9,14 @@ import type {
     GridSortItem,
     GridDataSource,
 } from '../../types';
+import { computeAggregations } from '../../utils/aggregation';
 
-export type BuiltInAggFn = 'sum' | 'avg' | 'count' | 'min' | 'max' | 'unique';
-
-const AGGREGATION_FUNCTIONS: Record<BuiltInAggFn, (values: unknown[]) => unknown> = {
-    sum: (values) => {
-        const nums = values.filter((v) => v != null && !isNaN(Number(v)));
-        return nums.reduce((acc: number, v) => acc + Number(v), 0);
-    },
-    avg: (values) => {
-        const nums = values.filter((v) => v != null && !isNaN(Number(v)));
-        if (nums.length === 0) return null;
-        return nums.reduce((acc: number, v) => acc + Number(v), 0) / nums.length;
-    },
-    count: (values) => values.filter((v) => v != null).length,
-    min: (values) => {
-        const nums = values.filter((v) => v != null && !isNaN(Number(v))).map(Number);
-        return nums.length ? Math.min(...nums) : null;
-    },
-    max: (values) => {
-        const nums = values.filter((v) => v != null && !isNaN(Number(v))).map(Number);
-        return nums.length ? Math.max(...nums) : null;
-    },
-    unique: (values) => new Set(values.filter((v) => v != null)).size,
-};
-
-export function formatAggregationValue(value: unknown, fnName: string): string {
-    if (value == null) return '—';
-    if (typeof value === 'number') {
-        if (fnName === 'avg') {
-            return value.toLocaleString(undefined, { maximumFractionDigits: 2 });
-        }
-        return value.toLocaleString();
-    }
-    return String(value);
-}
+export type { BuiltInAggFn } from '../../utils/aggregation';
+export { formatAggregationValue } from '../../utils/aggregation';
 
-export interface UseAggregationParams<R extends GridRowModel> {
+export interface UseAggregationParams<R extends GridValidRowModel = GridRowModel> {
         rows: R[];
-        columns?: GridColDef[];
+        columns?: GridColDef<R>[];
         aggregationModel: GridAggregationModel;
         isServerSide: boolean;
         dataSource?: GridDataSource<R>;
@@ -62,6 +31,37 @@ export interface UseAggregationReturn {
         error: unknown;
 }
 
+const EMPTY_RESULT: GridAggregationResult = {};
+
+interface ServerAggregationState {
+    /** The request (model, filter, sort) this outcome belongs to. */
+    key: string;
+    result: GridAggregationResult | null;
+    error: unknown;
+}
+
+/**
+ * State for totals that arrive with a getRows response. The stored results are tagged with the
+ * aggregation model they were computed for and read back as `null` once the model changes, so the
+ * footer never shows a total under the wrong function.
+ */
+export function useServerAggregationResults(
+    aggregationModel: GridAggregationModel,
+): [GridAggregationResult | null, (results: GridAggregationResult) => void] {
+    const modelKey = JSON.stringify(aggregationModel);
+    const [state, setState] = useState<{ modelKey: string; results: GridAggregationResult } | null>(null);
+    const setResults = useCallback(
+        (results: GridAggregationResult) => setState({ modelKey, results }),
+        [modelKey],
+    );
+    return [state && state.modelKey === modelKey ? state.results : null, setResults];
+}
+
+export function useAggregation<R extends GridValidRowModel = GridRowModel>(params: UseAggregationParams<R>): UseAggregationReturn;
+export function useAggregation<R extends GridValidRowModel = GridRowModel>(
+    params: Omit<UseAggregationParams<R>, 'columns'> & { columns?: GridColDef[] },
+): UseAggregationReturn;
+// Internally rows are read as GridRowModel records; the signature above is the public one.
 export function useAggregation<R extends GridRowModel>(
     params: UseAggregationParams<R>
 ): UseAggregationReturn {
@@ -76,6 +76,8 @@ export function useAggregation<R extends GridRowModel>(
         serverAggregationResults,
     } = params;
 
+    const hasModel = Object.keys(aggregationModel).length > 0;
+
     const columnsLookup = useMemo(() => {
         const map = new Map<string, GridColDef>();
         (columns ?? []).forEach(col => map.set(col.field, col));
@@ -83,65 +85,59 @@ export function useAggregation<R extends GridRowModel>(
     }, [columns]);
 
     const clientResult = useMemo<GridAggregationResult>(() => {
-        if (isServerSide || Object.keys(aggregationModel).length === 0) return {};
-
-        const result: GridAggregationResult = {};
-        for (const [field, fnName] of Object.entries(aggregationModel)) {
-            const colDef = columnsLookup.get(field);
-            if (colDef?.availableAggregationFunctions && !colDef.availableAggregationFunctions.includes(fnName)) {
-                continue;
-            }
-            const fn = AGGREGATION_FUNCTIONS[fnName as BuiltInAggFn];
-            if (!fn) {
-                console.warn(`[useAggregation] Unknown aggregation function: "${fnName}"`);
-                continue;
-            }
-            const values = rows.map((row) => (row as GridRowModel)[field]);
-            result[field] = fn(values);
-        }
-        return result;
-    }, [rows, columnsLookup, aggregationModel, isServerSide]);
+        if (isServerSide || !hasModel) return EMPTY_RESULT;
+
+        return computeAggregations(rows, aggregationModel, columnsLookup, 'useAggregation');
+    }, [rows, columnsLookup, aggregationModel, isServerSide, hasModel]);
 
-    const [serverResult, setServerResult] = useState<GridAggregationResult>({});
-    const [isLoading, setIsLoading] = useState(false);
-    const [error, setError] = useState<unknown>(null);
-    const requestIdRef = useRef(0);
+    // Requests are identified by content, so an inline `aggregationModel={{ salary: 'sum' }}` (a new
+    // object on every parent render) neither refetches nor drops the result it already has.
+    const requestKey = JSON.stringify([aggregationModel, filterModel ?? null, sortModel ?? []]);
+    const shouldFetch = isServerSide && hasModel && Boolean(dataSource?.getAggregations) && !serverAggregationResults;
 
-    const fetchServerAggregations = useCallback(async () => {
-        if (!dataSource?.getAggregations || Object.keys(aggregationModel).length === 0) return;
+    const latestRequestRef = useRef({ aggregationModel, filterModel, sortModel });
+    useEffect(() => {
+        latestRequestRef.current = { aggregationModel, filterModel, sortModel };
+    });
 
-        const requestId = ++requestIdRef.current;
-        setIsLoading(true);
-        setError(null);
+    const [serverState, setServerState] = useState<ServerAggregationState | null>(null);
+
+    useEffect(() => {
+        const getAggregations = dataSource?.getAggregations;
+        if (!shouldFetch || !getAggregations) return;
 
+        let cancelled = false;
+        const request = latestRequestRef.current;
+        let pending: Promise<GridAggregationResult>;
         try {
-            const result = await dataSource.getAggregations({
-                sortModel: sortModel ?? [],
-                filterModel: filterModel ?? { items: [] },
+            pending = Promise.resolve(getAggregations({
+                sortModel: request.sortModel ?? [],
+                filterModel: request.filterModel ?? { items: [] },
                 groupKeys: [],
-                aggregationModel,
-            });
-
-            if (requestId === requestIdRef.current) {
-                setServerResult(result);
-            }
+                aggregationModel: request.aggregationModel,
+            }));
         } catch (err) {
-            if (requestId === requestIdRef.current) {
-                setError(err);
-                console.error('[useAggregation] Server aggregation error:', err);
-            }
-        } finally {
-            if (requestId === requestIdRef.current) {
-                setIsLoading(false);
-            }
-        }
-    }, [dataSource, aggregationModel, filterModel, sortModel]);
-
-    useEffect(() => {
-        if (isServerSide && dataSource?.getAggregations && !serverAggregationResults) {
-            fetchServerAggregations();
+            pending = Promise.reject(err);
         }
-    }, [fetchServerAggregations, isServerSide, dataSource, serverAggregationResults]);
+        pending
+            .then(
+                (result) => {
+                    if (!cancelled) setServerState({ key: requestKey, result, error: null });
+                },
+                (err: unknown) => {
+                    if (cancelled) return;
+                    console.error('[useAggregation] Server aggregation error:', err);
+                    setServerState({ key: requestKey, result: null, error: err });
+                },
+            );
+        return () => { cancelled = true; };
+    }, [shouldFetch, dataSource, requestKey]);
+
+    // An outcome only counts for the request it answered: while a new request is pending, or after it
+    // failed, there is no server result (the footer shows '—'), never the previous request's totals.
+    const current = serverState && serverState.key === requestKey ? serverState : null;
+    const isLoading = shouldFetch && current === null;
+    const error = shouldFetch ? current?.error ?? null : null;
 
     const aggregationResult = useMemo<GridAggregationResult>(() => {
         if (!isServerSide) return clientResult;
@@ -149,8 +145,8 @@ export function useAggregation<R extends GridRowModel>(
         if (serverAggregationResults && Object.keys(serverAggregationResults).length > 0) {
             return serverAggregationResults;
         }
-        return serverResult;
-    }, [isServerSide, clientResult, serverAggregationResults, serverResult]);
+        return current?.result ?? EMPTY_RESULT;
+    }, [isServerSide, clientResult, serverAggregationResults, current]);
 
     return { aggregationResult, isLoading, error };
 }

package/lib/hooks/features/useColumnGroupReorderGuard.ts

@@ -0,0 +1,34 @@
+import { useMemo } from 'react';
+import type { GridColumnGroupingModel } from '../../types';
+import type { UseColumnReorderReturn } from '../useColumnReorder';
+import { canReorderWithinColumnGroups } from '../../utils/columnGroups';
+
+/**
+ * Header drag-reorder under `columnGroupingModel`: a column can be dropped only onto a column of the
+ * same innermost group (or, for an ungrouped column, onto another ungrouped column), so a drag can
+ * never split a group. A disallowed target is not a drop target (no dragover `preventDefault`, no
+ * highlight) and a drop on it only ends the drag.
+ */
+export function useColumnGroupReorderGuard(
+    columnGroupingModel: GridColumnGroupingModel | undefined,
+    handlers: UseColumnReorderReturn,
+): UseColumnReorderReturn {
+    const { draggedColumn, onDragOver, onDrop, onDragEnd } = handlers;
+
+    const guarded = useMemo(() => {
+        if (!columnGroupingModel || columnGroupingModel.length === 0) return null;
+        const allowed = (target: string) =>
+            draggedColumn === null || canReorderWithinColumnGroups(columnGroupingModel, draggedColumn, target);
+        return {
+            onDragOver: onDragOver && ((field: string) => (allowed(field) ? onDragOver(field) : () => {})),
+            onDrop: onDrop && ((field: string) => (allowed(field)
+                ? onDrop(field)
+                : (event: React.DragEvent) => {
+                    event.preventDefault();
+                    onDragEnd?.();
+                })),
+        };
+    }, [columnGroupingModel, draggedColumn, onDragOver, onDrop, onDragEnd]);
+
+    return guarded ? { ...handlers, ...guarded } : handlers;
+}

package/lib/hooks/features/useDetailPanelHeights.ts

@@ -0,0 +1,29 @@
+import { useCallback, useState } from 'react';
+import type { GridRowId } from '../../types';
+
+export interface UseDetailPanelHeightsResult {
+    /** Rendered heights of `'auto'` detail panels, by row id. Pass to `useLayout`. */
+    detailPanelHeights: Map<GridRowId, number>;
+    /** Stable callback the panels report their rendered height through. */
+    reportDetailPanelHeight: (rowId: GridRowId, height: number) => void;
+}
+
+/**
+ * Keeps the measured heights of `'auto'` detail panels, so the layout reserves what the panel
+ * really renders at instead of a guess. A height is kept after its panel collapses or scrolls out
+ * of the render window: it is the best estimate for the next time the panel is shown.
+ */
+export function useDetailPanelHeights(): UseDetailPanelHeightsResult {
+    const [detailPanelHeights, setDetailPanelHeights] = useState<Map<GridRowId, number>>(() => new Map());
+
+    const reportDetailPanelHeight = useCallback((rowId: GridRowId, height: number) => {
+        setDetailPanelHeights(prev => {
+            if (prev.get(rowId) === height) return prev;
+            const next = new Map(prev);
+            next.set(rowId, height);
+            return next;
+        });
+    }, []);
+
+    return { detailPanelHeights, reportDetailPanelHeight };
+}

package/lib/hooks/features/useGridClipboard.ts

@@ -1,117 +1,165 @@
-import { useEffect, useCallback } from 'react';
+import { useEffect, useCallback, useLayoutEffect, useRef } from 'react';
 import type { GridColDef, GridRowModel, GridRowId } from '../../types';
-
-interface UseGridClipboardProps {
-  /** The currently selected row IDs — must come from the live selection source (not state.selection which is stale). */
-  selectedRowIds: Set<GridRowId>;
-  columns: GridColDef[];
-  getVisibleRows: () => GridRowModel[];
+import { getCellValue } from '../../utils/values';
+import { getExportColumns, formatExportValue } from '../../utils/export/exportShared';
+import { CHECKBOX_FIELD, EXPAND_FIELD, REORDER_FIELD } from '../../utils/focus';
+
+export interface UseGridClipboardProps {
+  /**
+   * The live selection. Read at copy time, so a copy made right after a selection change (from
+   * `onRowSelectionModelChange`, or after `apiRef.selectRows`) sees the new selection.
+   */
+  getSelectedRowIds: () => Iterable<GridRowId>;
+  /** The columns on screen, in screen order (hidden columns left out). */
+  getColumns: () => GridColDef[];
+  /**
+   * Every data row the selection can refer to, in display order: pinned rows, rows on other
+   * pages and rows inside collapsed groups included; rows removed by the filter and synthetic
+   * group rows left out.
+   */
+  getRows: () => GridRowModel[];
+  /** The grid's key for a row. Never the consumer's getRowId on a grid-made row. */
   getRowId: (row: GridRowModel) => GridRowId;
+  /**
+   * Returns the grid's root element. When given, Ctrl/Cmd+C only copies while focus is inside it,
+   * so a page with several grids (or other content) is not affected by a grid that is not in use.
+   */
+  getRootElement?: () => HTMLElement | null;
+  /** Turns the Ctrl/Cmd+C shortcut off. `copySelectedRows` still works. */
+  disableKeyboardShortcut?: boolean;
+}
+
+/** Grid-made columns that never hold row data. */
+const SYSTEM_FIELDS = new Set<string>([CHECKBOX_FIELD, EXPAND_FIELD, REORDER_FIELD]);
+
+const TSV_SPECIAL = /[\t\n\r"]/;
+
+/**
+ * One TSV field as Excel, Google Sheets and LibreOffice read it: a field holding a tab, line break
+ * or double quote is wrapped in double quotes, with inner quotes doubled.
+ */
+export function escapeTsvField(text: string): string {
+  return TSV_SPECIAL.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+}
+
+/** The copied columns: the on-screen columns minus system columns and `exportable: false` ones. */
+export function getClipboardColumns(columns: GridColDef[]): GridColDef[] {
+  return getExportColumns(columns).filter(col => !SYSTEM_FIELDS.has(col.field));
+}
+
+/** Header line plus one line per row, with values read and formatted the way the cells show them. */
+export function buildClipboardTsv(rows: GridRowModel[], columns: GridColDef[]): string {
+  const header = columns.map(col => escapeTsvField(col.headerName || col.field)).join('\t');
+  const lines = rows.map(row =>
+    columns
+      .map(col => escapeTsvField(formatExportValue(row, col, getCellValue(row, col.field, col))))
+      .join('\t')
+  );
+  return [header, ...lines].join('\n');
 }
 
+/**
+ * The textarea + execCommand fallback, for browsers without the async Clipboard API (plain http)
+ * or when it rejects. It has to focus the textarea, so focus and the page selection are put back
+ * afterwards: the focused grid cell (or button) keeps focus.
+ */
 function copyTextSynchronous(text: string): boolean {
+  if (typeof document.execCommand !== 'function') return false;
+  const previousFocus = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+  const selection = document.getSelection();
+  const previousRanges: Range[] = [];
+  if (selection) {
+    for (let i = 0; i < selection.rangeCount; i++) previousRanges.push(selection.getRangeAt(i));
+  }
+
   const textarea = document.createElement('textarea');
   textarea.value = text;
+  textarea.setAttribute('readonly', '');
+  textarea.setAttribute('aria-hidden', 'true');
   textarea.style.cssText = 'position:fixed;top:-9999px;left:-9999px;opacity:0;';
   document.body.appendChild(textarea);
-  textarea.focus();
-  textarea.select();
   let success = false;
   try {
+    textarea.focus({ preventScroll: true });
+    textarea.select();
     success = document.execCommand('copy');
   } finally {
     document.body.removeChild(textarea);
+    if (previousFocus && previousFocus.isConnected) previousFocus.focus({ preventScroll: true });
+    if (selection) {
+      selection.removeAllRanges();
+      previousRanges.forEach(range => selection.addRange(range));
+    }
   }
   return success;
 }
 
 /**
- * Writes text to clipboard.
- * Uses both execCommand (synchronous, needed for non-HTTPS or non-async-gesture environments)
- * and navigator.clipboard for modern browser support.
+ * Writes text to the clipboard: the async Clipboard API when there is one, the execCommand
+ * fallback when it is missing or rejects. Rejects when neither worked.
  */
 async function writeToClipboard(text: string): Promise<void> {
-  let fallbackSuccess = false;
-  try {
-    fallbackSuccess = copyTextSynchronous(text);
-  } catch {
-    // Ignore fallback errors
-  }
-
-  if (navigator.clipboard && typeof navigator.clipboard.writeText === 'function') {
+  const clipboard = typeof navigator !== 'undefined' ? navigator.clipboard : undefined;
+  if (clipboard && typeof clipboard.writeText === 'function') {
     try {
-      await navigator.clipboard.writeText(text);
+      await clipboard.writeText(text);
       return;
-    } catch (e) {
-      if (fallbackSuccess) return;
-      throw e;
+    } catch (error) {
+      if (copyTextSynchronous(text)) return;
+      throw error;
     }
-  } else if (!fallbackSuccess) {
+  }
+  if (!copyTextSynchronous(text)) {
     throw new Error('Clipboard API not available and fallback failed.');
   }
 }
 
+/** Ctrl/Cmd+C, also with Caps Lock on ("C") and on non-Latin layouts (the key printed "c" is KeyC). */
+function isCopyShortcut(event: KeyboardEvent): boolean {
+  if (!(event.ctrlKey || event.metaKey) || event.altKey || event.shiftKey) return false;
+  const key = event.key ?? '';
+  if (key.toLowerCase() === 'c') return true;
+  // A layout whose KeyC types a non-Latin letter (Cyrillic, Greek, ...): browsers copy on KeyC.
+  // A Latin layout that puts another letter there (Dvorak) copies on its own "c" key instead.
+  return event.code === 'KeyC' && !/^[a-z]$/i.test(key);
+}
+
 /**
  * Hook to handle clipboard operations.
  * Copies selected rows as Tab-Separated Values (TSV) on Ctrl+C / Cmd+C.
  * Also exposes `copySelectedRows` for programmatic use via apiRef.
  */
 export function useGridClipboard(props: UseGridClipboardProps) {
-  const { selectedRowIds, columns, getVisibleRows, getRowId } = props;
-
-  const copySelectedRows = useCallback(async () => {
-
-    if (selectedRowIds.size === 0) return;
-
-    const visibleRows = getVisibleRows();
-    const rowsToCopy = visibleRows.filter((row) => selectedRowIds.has(getRowId(row)));
-
-
-
+  const latestRef = useRef(props);
+  useLayoutEffect(() => {
+    latestRef.current = props;
+  });
+
+  /** Copies the selected rows. Resolves without writing when no selected row is found; rejects when the write fails. */
+  const copySelectedRows = useCallback(async (): Promise<void> => {
+    const { getSelectedRowIds, getColumns, getRows, getRowId } = latestRef.current;
+    const selected = new Set<GridRowId>(getSelectedRowIds());
+    if (selected.size === 0) return;
+
+    const rowsToCopy = getRows().filter(row => selected.has(getRowId(row)));
     if (rowsToCopy.length === 0) return;
 
-    // Exclude internal grid columns (checkbox, expand, reorder)
-    const visibleColumns = columns.filter((col) => !col.field.startsWith('__'));
-
-    // Header row
-    const headerRow = visibleColumns
-      .map((col) => col.headerName || col.field)
-      .join('\t');
-
-    // Data rows
-    const dataRows = rowsToCopy
-      .map((row) =>
-        visibleColumns
-          .map((col) => {
-            const value = row[col.field];
-            if (col.valueFormatter) {
-              return col.valueFormatter({ value, row, field: col.field });
-            }
-            return value ?? '';
-          })
-          .join('\t')
-      )
-      .join('\n');
-
-    const fullContent = `${headerRow}\n${dataRows}`;
+    const text = buildClipboardTsv(rowsToCopy, getClipboardColumns(getColumns()));
+    await writeToClipboard(text);
+  }, []);
 
-    try {
-      await writeToClipboard(fullContent);
-
-    } catch (err) {
-      console.error('[OpenGridX] Failed to copy to clipboard:', err);
-    }
-  }, [selectedRowIds, columns, getVisibleRows, getRowId]);
+  const disableKeyboardShortcut = Boolean(props.disableKeyboardShortcut);
 
-  // Keyboard shortcut: Ctrl+C / Cmd+C
+  // Keyboard shortcut: Ctrl+C / Cmd+C. Registered once; it reads the latest props through the ref.
   useEffect(() => {
+    if (disableKeyboardShortcut) return;
     const handleKeyDown = (event: KeyboardEvent) => {
-      if (!(event.ctrlKey || event.metaKey) || event.key !== 'c') return;
+      if (event.defaultPrevented || !isCopyShortcut(event)) return;
 
       // Don't intercept when user is typing in an input / editor
-      const activeEl = document.activeElement as HTMLElement;
+      const activeEl = document.activeElement as HTMLElement | null;
       const tag = activeEl?.tagName.toLowerCase();
-      const type = (activeEl as HTMLInputElement)?.type;
+      const type = (activeEl as HTMLInputElement | null)?.type;
 
       // Skip capturing Ctrl+C if we are genuinely inside a text input
       if (
@@ -122,12 +170,24 @@ export function useGridClipboard(props: UseGridClipboardProps) {
 
       if (activeEl?.isContentEditable) return;
 
-      copySelectedRows();
+      // Only the grid that has focus copies.
+      const { getRootElement } = latestRef.current;
+      if (getRootElement) {
+        const root = getRootElement();
+        if (!root || !activeEl || !root.contains(activeEl)) return;
+      }
+      // A text selection on the page is the user's copy target: leave it to the browser.
+      const selection = window.getSelection();
+      if (selection && !selection.isCollapsed && selection.toString() !== '') return;
+
+      copySelectedRows().catch((err: unknown) => {
+        console.error('[OpenGridX] Failed to copy to clipboard:', err);
+      });
     };
 
     window.addEventListener('keydown', handleKeyDown);
     return () => window.removeEventListener('keydown', handleKeyDown);
-  }, [copySelectedRows]);
+  }, [copySelectedRows, disableKeyboardShortcut]);
 
   return { copySelectedRows };
 }