@jielga/tmdatagrid 0.2.0 → 0.3.0

package/src/tmdatagrid/useTMDataGrid.tsx

@@ -1,24 +1,29 @@
 import { useCreateStore } from "@tanstack/react-store";
 import {
+  aggregationFns,
   type ColumnDef,
   columnFacetingFeature,
   columnFilteringFeature,
+  columnGroupingFeature,
   columnOrderingFeature,
   columnPinningFeature,
   columnResizingFeature,
   columnSizingFeature,
   columnVisibilityFeature,
   createColumnHelper,
+  createExpandedRowModel,
   createFacetedMinMaxValues,
   createFacetedRowModel,
   createFacetedUniqueValues,
   createFilteredRowModel,
+  createGroupedRowModel,
   createPaginatedRowModel,
   createSortedRowModel,
   filterFns,
   globalFilteringFeature,
   metaHelper,
   type RowData,
+  rowExpandingFeature,
   rowPaginationFeature,
   rowSelectionFeature,
   rowSortingFeature,
@@ -30,7 +35,7 @@ import {
   useTable,
 } from "@tanstack/react-table";
 import type { Store } from "@tanstack/store";
-import { useEffect, useMemo, useState } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
 import {
   type TMDataGridColumnType,
   tmDataGridFilterFn,
@@ -45,12 +50,16 @@ import {
 import {
   readFeatureFlags,
   type TMDataGridFeatureFlags,
-  type TMDataGridRowSelectionMode,
+  type TMDataGridSelectionMode,
 } from "./core/capabilities";
 import {
   createSelectColumn,
   SELECT_COLUMN_ID,
 } from "./components/TMDataGridSelectColumn";
+import {
+  createGroupColumn,
+  GROUP_COLUMN_ID,
+} from "./components/TMDataGridGroupColumn";
 
 /**
  * How long the grid waits after the last state change before writing to
@@ -105,9 +114,16 @@ export const tmDataGridFeatures = tableFeatures({
   columnSizingFeature,
   columnResizingFeature,
   columnFacetingFeature,
+  columnGroupingFeature,
+  // Registered for grouping's sake rather than for tree data: the grouped row
+  // model builds the parent rows, and this is what flattens the expanded ones
+  // back into the flat list the body virtualizes.
+  rowExpandingFeature,
 
   filteredRowModel: createFilteredRowModel(),
+  groupedRowModel: createGroupedRowModel(),
   sortedRowModel: createSortedRowModel(),
+  expandedRowModel: createExpandedRowModel(),
   paginatedRowModel: createPaginatedRowModel(),
   facetedRowModel: createFacetedRowModel(),
   facetedMinMaxValues: createFacetedMinMaxValues(),
@@ -115,6 +131,10 @@ export const tmDataGridFeatures = tableFeatures({
 
   filterFns: { ...filterFns, tmDataGrid: tmDataGridFilterFn },
   sortFns,
+  // The names `columnDef.aggregationFn` accepts. Only consulted for columns
+  // that ask for one — a column with no `aggregationFn` reports `undefined` on
+  // a group row, which is what keeps a plain "group by" free of aggregates.
+  aggregationFns,
 
   tableMeta: metaHelper<TMDataGridTableMeta>(),
   columnMeta: metaHelper<TMDataGridColumnMeta>(),
@@ -146,6 +166,20 @@ export type TMDataGridUiState = {
    * `dataTransfer`, which browsers keep unreadable until the drop.
    */
   draggedColumnId: string | null;
+  /**
+   * The single highlighted row — the one a detail panel would be showing. Its
+   * own concept, not a slice of `rowSelection`: under
+   * `selectionMode: "checkboxAndHighlight"` the two coexist, and TanStack's one
+   * selection map cannot hold both.
+   *
+   * Not pruned when the row is filtered out, paged away or dropped from `data`,
+   * matching how TanStack treats `rowSelection` — nothing there resets it
+   * either. The row simply renders unhighlighted, and highlights again if it
+   * comes back.
+   */
+  highlightedRowId: string | null;
+  /** The pivot a shift-click extends from. See resolveRowSelectionClick. */
+  selectionAnchorRowId: string | null;
 };
 
 export type TMDataGridUiActions = {
@@ -155,6 +189,12 @@ export type TMDataGridUiActions = {
   toggleColumnsPanel: () => void;
   startColumnDrag: (columnId: string) => void;
   endColumnDrag: () => void;
+  /**
+   * Moves the active row, or clears it with `null` — which is how a consumer
+   * closing its detail panel puts the grid back in step.
+   */
+  setHighlightedRow: (rowId: string | null) => void;
+  setSelectionAnchor: (rowId: string | null) => void;
 };
 
 export type TMDataGridUiStore = Store<TMDataGridUiState, TMDataGridUiActions>;
@@ -201,18 +241,29 @@ export type UseTMDataGridOptions<TData extends RowData> = Omit<
   /**
    * How rows are selected. Defaults to `"checkbox"`.
    *
-   * - `"checkbox"` — the generated checkbox column selects; clicking a row
-   *   elsewhere does not.
-   * - `"row"` — no checkbox column; clicking a row toggles it. Other rows keep
-   *   their state, so a click never clears the rest of the selection.
+   * | Mode | Checkbox column | Row click |
+   * | ---- | --------------- | --------- |
+   * | `"checkbox"` | yes, multi-select | nothing |
+   * | `"row"` | no | multi-selects, Ctrl/Shift modifiers |
+   * | `"checkboxAndHighlight"` | yes, multi-select | highlights one row |
+   * | `"highlight"` | no | highlights one row, no selection at all |
+   *
+   * One option rather than two, so the combination that cannot work — a click
+   * that both toggles a multi-selection and moves the highlight — is not
+   * expressible.
    *
-   * Ignored when `enableRowSelection` is `false`. Both modes write to the same
-   * `rowSelection` state.
+   * The first two write to TanStack's `rowSelection`. The highlight is separate
+   * state, which is what lets `"checkboxAndHighlight"` run both at once: tick
+   * rows for a bulk action, click one to open its detail panel. See
+   * `defaultHighlightedRowId` / `onHighlightedRowChange`.
+   *
+   * `enableRowSelection` still gates the selection half, predicate form
+   * included; under `"highlight"` there is nothing for it to gate.
    */
-  rowSelectionMode?: TMDataGridRowSelectionMode;
+  selectionMode?: TMDataGridSelectionMode;
   /**
    * Give selected rows the highlight background. Defaults to `true` under
-   * `rowSelectionMode: "row"`, where the highlight is the only feedback a click
+   * `selectionMode: "row"`, where the highlight is the only feedback a click
    * gives, and `false` under `"checkbox"`, where the box already shows it.
    *
    * The colour is the `--dg-row-selected-bg` CSS variable, so it can be changed
@@ -225,7 +276,31 @@ export type UseTMDataGridOptions<TData extends RowData> = Omit<
    * />
    * ```
    */
-  highlightSelectedRows?: boolean;
+  showSelectedBackground?: boolean;
+  /**
+   * The row that starts out highlighted, under a `selectionMode` that has a
+   * highlight. Read once on mount, like `initialState`.
+   *
+   * The grid never persists the highlighted row. Pair this with
+   * {@link onHighlightedRowChange} and keep it wherever it belongs — for a
+   * detail panel that is usually the route, which gets you a shareable link and
+   * a working back button as well as surviving a reload:
+   *
+   * ```tsx
+   * const { rowId } = useParams();
+   * useTMDataGrid({
+   *   selectionMode: "highlight",
+   *   defaultHighlightedRowId: rowId,
+   *   onHighlightedRowChange: (id) => navigate(id ? `/employees/${id}` : "/employees"),
+   * });
+   * ```
+   */
+  defaultHighlightedRowId?: string | null;
+  /**
+   * Called with the newly highlighted row id, or `null` when it is cleared.
+   * Fires for `ui.actions.setHighlightedRow` too, not only for clicks.
+   */
+  onHighlightedRowChange?: (rowId: string | null) => void;
 };
 
 type TMDataGridColumnDef<TData extends RowData> = ColumnDef<
@@ -235,8 +310,17 @@ type TMDataGridColumnDef<TData extends RowData> = ColumnDef<
 >;
 
 /**
- * Point every column at the operator-dispatching filter function unless the
- * column opted into its own.
+ * Point every column at the operator-dispatching filter function, and take
+ * grouping's aggregation defaults back off, unless the column opted into its
+ * own. Anything the consumer set wins — it is spread over these.
+ *
+ * The aggregation pair needs explaining. TanStack's grouping feature hands
+ * every column `aggregationFn: "auto"` and an `aggregatedCell` that stringifies
+ * whatever comes out, so merely registering the feature would have every
+ * numeric column silently sum itself and every date column show a range the
+ * moment anything is grouped. That is a summary table, and "group by" is not a
+ * request for one. Cleared here, so a grouped grid is a tree until a column
+ * says otherwise — `aggregationFn: "sum"` on the column that wants it.
  */
 function withTMDataGridDefaults<TData extends RowData>(
   columns: ReadonlyArray<TMDataGridColumnDef<TData>>,
@@ -248,7 +332,12 @@ function withTMDataGridDefaults<TData extends RowData>(
         columns: withTMDataGridDefaults<TData>(column.columns),
       };
     }
-    return { filterFn: "tmDataGrid", ...column } as TMDataGridColumnDef<TData>;
+    return {
+      filterFn: "tmDataGrid",
+      aggregationFn: undefined,
+      aggregatedCell: undefined,
+      ...column,
+    } as TMDataGridColumnDef<TData>;
   });
 }
 
@@ -268,48 +357,91 @@ export function useTMDataGrid<TData extends RowData>({
   // Not TanStack options, so they are kept out of what `useTable` receives.
   enableColumnOrdering,
   enablePagination,
-  rowSelectionMode,
-  highlightSelectedRows,
+  selectionMode,
+  showSelectedBackground,
+  defaultHighlightedRowId,
+  onHighlightedRowChange,
   ...options
 }: UseTMDataGridOptions<TData>): TMDataGridApi<TData> {
-  const selectionEnabled = options.enableRowSelection !== false;
+  // Derived up here, rather than just before the return, because the rest of the
+  // hook needs `selectColumn` — one place decides what each mode means.
+  //
+  // Deliberately not memoized on `table`: the flags must re-derive whenever the
+  // caller passes different options, and `table` keeps the same identity when
+  // they do. See readFeatureFlags.
+  const features = readFeatureFlags({
+    ...options,
+    enableColumnOrdering,
+    enablePagination,
+    selectionMode,
+    showSelectedBackground,
+  });
+
   const pinningEnabled = options.enableColumnPinning !== false;
-  // Only "checkbox" mode owns a column; "row" mode selects from the row itself.
-  const selectColumnEnabled =
-    selectionEnabled && rowSelectionMode !== "row";
+  const selectColumnEnabled = features.selectColumn;
+  const groupColumnEnabled = features.grouping;
 
   const columns = useMemo(() => {
     const base = withTMDataGridDefaults<TData>(
       options.columns as ReadonlyArray<TMDataGridColumnDef<TData>>,
     );
-    return selectColumnEnabled ? [createSelectColumn<TData>(), ...base] : base;
-  }, [options.columns, selectColumnEnabled]);
+    // Both generated columns are always present when their feature is on, and
+    // the tree column hides itself while nothing is grouped. Adding it to the
+    // array only once a column is grouped would make the column list depend on
+    // table state, which is the one thing that cannot be a `useMemo` dependency
+    // here — the table is built from these columns.
+    return [
+      ...(selectColumnEnabled ? [createSelectColumn<TData>()] : []),
+      ...(groupColumnEnabled ? [createGroupColumn<TData>()] : []),
+      ...base,
+    ];
+  }, [options.columns, selectColumnEnabled, groupColumnEnabled]);
 
   // Read once on mount: `initialState` is only consumed on the first render,
   // and re-reading later would fight the user's live edits.
   const [persistedState] = useState(() => readPersistedState(persist));
 
+  // Restored grouping decides whether the tree column starts out visible, so a
+  // reload comes back to the tree the user left rather than to a hidden lane.
+  const initialGrouping =
+    persistedState.grouping ?? options.initialState?.grouping ?? [];
+
   const table = useTable({
     columnResizeMode: "onChange",
     enableSorting: true,
     enableColumnResizing: true,
     globalFilterFn: "includesString",
+    // Grouping by a column takes it out of the grid, the way AG Grid does it:
+    // its values have moved into the tree column, so leaving it in place would
+    // show every row the same value it was grouped under. Overridable — pass
+    // `"reorder"` to keep the column and have it moved to the front instead.
+    groupedColumnMode: "remove",
     ...options,
     features: tmDataGridFeatures,
     columns: columns as TableOptions<TMDataGridFeatures, TData>["columns"],
     initialState: {
       ...options.initialState,
       ...persistedState,
+      columnVisibility: {
+        ...options.initialState?.columnVisibility,
+        ...persistedState.columnVisibility,
+        // Last word, because the tree column's visibility is not a user setting
+        // — it tracks the grouping state. See the effect below.
+        ...(groupColumnEnabled
+          ? { [GROUP_COLUMN_ID]: initialGrouping.length > 0 }
+          : {}),
+      },
       columnPinning: {
-        // The checkbox column is structurally pinned, so it is re-applied on
-        // top of anything restored from storage.
+        // The generated columns are structurally pinned, so they are re-applied
+        // on top of anything restored from storage.
         left: [
           ...(selectColumnEnabled && pinningEnabled ? [SELECT_COLUMN_ID] : []),
+          ...(groupColumnEnabled && pinningEnabled ? [GROUP_COLUMN_ID] : []),
           ...(
             persistedState.columnPinning?.left ??
             options.initialState?.columnPinning?.left ??
             []
-          ).filter((id) => id !== SELECT_COLUMN_ID),
+          ).filter((id) => id !== SELECT_COLUMN_ID && id !== GROUP_COLUMN_ID),
         ],
         right:
           persistedState.columnPinning?.right ??
@@ -325,6 +457,60 @@ export function useTMDataGrid<TData extends RowData>({
     },
   });
 
+  // Two things have to happen whenever `grouping` changes.
+  //
+  // One: the tree column appears with the first grouped column and goes away
+  // with the last, so an ungrouped grid looks exactly as it did before grouping
+  // existed. Driven from a subscription rather than by rebuilding the column
+  // array, because the array is what the table is built from — deriving it from
+  // table state would close the loop. Visibility is the one column property
+  // that can be changed after the fact without touching the definitions.
+  //
+  // Two, and this one is a workaround. In table-core 9.0.0-beta.21 the
+  // per-region column APIs do not list `grouping` among their memo
+  // dependencies, even though they all derive from `getAllLeafColumns()`, which
+  // does:
+  //
+  // | API | Declares |
+  // | --- | --- |
+  // | `getLeft/Center/RightVisibleLeafColumns` | columns, columnPinning, columnVisibility, columnOrder |
+  // | `getLeft/Center/RightHeaderGroups` | columnPinning, columnOrder |
+  // | `row.getLeft/Center/RightVisibleCells` | columnPinning, columnVisibility |
+  //
+  // So grouping a *second* column leaves every one of them returning the
+  // previous list: the column TanStack removed keeps its header and its grid
+  // track, and the row cells no longer line up with them. The first grouping
+  // appears to work only because the visibility write above happens to touch a
+  // dependency they share.
+  //
+  // Re-publishing `columnVisibility` and `columnOrder` — same contents, new
+  // identity — invalidates all three families. `columnOrder` is the only
+  // dependency the header groups declare, and `columnVisibility` the only one
+  // the cells do, so both are needed. Remove this once the deps are fixed
+  // upstream; the test that fails without it groups two columns and asserts the
+  // second one leaves the grid.
+  //
+  // Writing back into the store from its own subscriber is safe: the guard is
+  // on `grouping`'s identity, and neither write touches it, so the callback
+  // these writes trigger short-circuits.
+  useEffect(() => {
+    if (!groupColumnEnabled) return;
+    let previousGrouping = table.store.state.grouping;
+
+    const subscription = table.store.subscribe((state) => {
+      if (state.grouping === previousGrouping) return;
+      previousGrouping = state.grouping;
+
+      table.setColumnVisibility((old) => ({
+        ...old,
+        [GROUP_COLUMN_ID]: state.grouping.length > 0,
+      }));
+      table.setColumnOrder((old) => [...old]);
+    });
+
+    return () => subscription.unsubscribe();
+  }, [groupColumnEnabled, table]);
+
   // Mirror every state change back to storage. Subscribing (rather than writing
   // from an effect on a state snapshot) means nothing is missed, including
   // changes made straight through the table API by the consumer.
@@ -367,6 +553,10 @@ export function useTMDataGrid<TData extends RowData>({
       columnsPanelOpen: false,
       filterPanelColumnId: null,
       draggedColumnId: null,
+      // `useCreateStore` builds the store once per mount, so this is a genuine
+      // default rather than a value that would fight later clicks.
+      highlightedRowId: defaultHighlightedRowId ?? null,
+      selectionAnchorRowId: null,
     },
     ({ setState }) => ({
       openFilterPanel: (columnId = null) =>
@@ -389,19 +579,34 @@ export function useTMDataGrid<TData extends RowData>({
         setState((prev) => ({ ...prev, draggedColumnId: columnId })),
       endColumnDrag: () =>
         setState((prev) => ({ ...prev, draggedColumnId: null })),
+      setHighlightedRow: (rowId) =>
+        setState((prev) => ({ ...prev, highlightedRowId: rowId })),
+      setSelectionAnchor: (rowId) =>
+        setState((prev) => ({ ...prev, selectionAnchorRowId: rowId })),
     }),
   );
 
-  // Deliberately not memoized on `table`: the flags must re-derive whenever the
-  // caller passes different options, and `table` keeps the same identity when
-  // they do. See readFeatureFlags.
-  const features = readFeatureFlags({
-    ...options,
-    enableColumnOrdering,
-    enablePagination,
-    rowSelectionMode,
-    highlightSelectedRows,
-  });
+  // `onHighlightedRowChange` is fired from a subscription rather than from the store
+  // action, so it covers every route to a new active row — a row click, and a
+  // consumer calling `setHighlightedRow` itself. Held in a ref because the store is
+  // built once and its actions would otherwise close over the first render's
+  // callback.
+  const onHighlightedRowChangeRef = useRef(onHighlightedRowChange);
+  useEffect(() => {
+    onHighlightedRowChangeRef.current = onHighlightedRowChange;
+  }, [onHighlightedRowChange]);
+
+  useEffect(() => {
+    // Seeded from the current value so mounting with a `defaultHighlightedRowId`
+    // does not report a change that nothing made.
+    let previous = ui.state.highlightedRowId;
+    const subscription = ui.subscribe((state) => {
+      if (state.highlightedRowId === previous) return;
+      previous = state.highlightedRowId;
+      onHighlightedRowChangeRef.current?.(state.highlightedRowId);
+    });
+    return () => subscription.unsubscribe();
+  }, [ui]);
 
   return { table, ui, features };
 }