@jielga/tmdatagrid 0.1.0 → 0.2.0

package/src/tmdatagrid/useTMDataGrid.tsx

@@ -1,4 +1,3 @@
-import { Checkbox } from "@mantine/core";
 import { useCreateStore } from "@tanstack/react-store";
 import {
   type ColumnDef,
@@ -27,6 +26,7 @@ import {
   type Table,
   tableFeatures,
   type TableOptions,
+  type TableState,
   useTable,
 } from "@tanstack/react-table";
 import type { Store } from "@tanstack/store";
@@ -35,16 +35,29 @@ import {
   type TMDataGridColumnType,
   tmDataGridFilterFn,
   getDefaultOperator,
-} from "./filterOperators";
+} from "./core/filterOperators";
 import {
   hasPersistenceKeys,
   readPersistedState,
   type TMDataGridPersistence,
   writePersistedState,
-} from "./persistence";
-import { readFeatureFlags, type TMDataGridFeatureFlags } from "./capabilities";
+} from "./core/persistence";
+import {
+  readFeatureFlags,
+  type TMDataGridFeatureFlags,
+  type TMDataGridRowSelectionMode,
+} from "./core/capabilities";
+import {
+  createSelectColumn,
+  SELECT_COLUMN_ID,
+} from "./components/TMDataGridSelectColumn";
 
-export const SELECT_COLUMN_ID = "__select__";
+/**
+ * How long the grid waits after the last state change before writing to
+ * storage. Long enough to collapse a resize drag into one write, short enough
+ * that a reload right after a change still sees it.
+ */
+const PERSIST_DEBOUNCE_MS = 200;
 
 /** Per-column configuration the TMDataGrid chrome reads. */
 export type TMDataGridColumnMeta = {
@@ -175,6 +188,44 @@ export type UseTMDataGridOptions<TData extends RowData> = Omit<
    * reordering is entirely a matter of interface.
    */
   enableColumnOrdering?: boolean;
+  /**
+   * Client-side pagination and the built-in `TMDataGrid.Footer` pager.
+   * Defaults to `false`: the grid renders every filtered row and relies on
+   * virtualization.
+   *
+   * The second grid-defined switch (TanStack defines no `enablePagination`
+   * option). `manualPagination: true` implies it — a server-paged grid needs
+   * no extra flag.
+   */
+  enablePagination?: boolean;
+  /**
+   * 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.
+   *
+   * Ignored when `enableRowSelection` is `false`. Both modes write to the same
+   * `rowSelection` state.
+   */
+  rowSelectionMode?: TMDataGridRowSelectionMode;
+  /**
+   * Give selected rows the highlight background. Defaults to `true` under
+   * `rowSelectionMode: "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
+   * without turning the flag on or off:
+   *
+   * ```tsx
+   * <TMDataGrid
+   *   {...grid}
+   *   style={{ "--dg-row-selected-bg": "var(--mantine-color-blue-0)" }}
+   * />
+   * ```
+   */
+  highlightSelectedRows?: boolean;
 };
 
 type TMDataGridColumnDef<TData extends RowData> = ColumnDef<
@@ -201,48 +252,6 @@ function withTMDataGridDefaults<TData extends RowData>(
   });
 }
 
-function createSelectColumn<TData extends RowData>(): TMDataGridColumnDef<TData> {
-  return {
-    id: SELECT_COLUMN_ID,
-    meta: {
-      label: "Checkbox selection",
-      align: "center",
-      // Structurally the first column; it also anchors the left pinned lane, so
-      // no other column can be moved in front of it.
-      enableOrdering: false,
-    },
-    size: 48,
-    minSize: 48,
-    maxSize: 48,
-    enableResizing: false,
-    enableSorting: false,
-    enableColumnFilter: false,
-    enableGlobalFilter: false,
-    // Structurally pinned to the left; users shouldn't be able to move it.
-    enablePinning: false,
-    header: ({ table }) => (
-      <Checkbox
-        size="xs"
-        aria-label="Select all rows"
-        checked={table.getIsAllRowsSelected()}
-        indeterminate={table.getIsSomeRowsSelected()}
-        onChange={table.getToggleAllRowsSelectedHandler()}
-      />
-    ),
-    cell: ({ row }) => (
-      <Checkbox
-        size="xs"
-        aria-label="Select row"
-        checked={row.getIsSelected()}
-        disabled={!row.getCanSelect()}
-        indeterminate={row.getIsSomeSelected()}
-        onChange={row.getToggleSelectedHandler()}
-        onClick={(event) => event.stopPropagation()}
-      />
-    ),
-  };
-}
-
 /**
  * Builds a TMDataGrid table plus its chrome store.
  *
@@ -250,23 +259,31 @@ function createSelectColumn<TData extends RowData>(): TMDataGridColumnDef<TData>
  * only needs `manualPagination` / `manualFiltering` / `manualSorting`,
  * `rowCount` and the matching `onXChange` callbacks — the chrome reads
  * `getRowCount()` / `getPageCount()` / `getPaginatedRowModel()`, all of which
- * already respect manual mode.
+ * already respect manual mode. `manualPagination` also switches the pagination
+ * flag on, so `<TMDataGrid.Footer />` renders its pager without further
+ * options.
  */
 export function useTMDataGrid<TData extends RowData>({
   persist,
-  // Not a TanStack option, so it is kept out of what `useTable` receives.
+  // Not TanStack options, so they are kept out of what `useTable` receives.
   enableColumnOrdering,
+  enablePagination,
+  rowSelectionMode,
+  highlightSelectedRows,
   ...options
 }: UseTMDataGridOptions<TData>): TMDataGridApi<TData> {
   const selectionEnabled = options.enableRowSelection !== false;
   const pinningEnabled = options.enableColumnPinning !== false;
+  // Only "checkbox" mode owns a column; "row" mode selects from the row itself.
+  const selectColumnEnabled =
+    selectionEnabled && rowSelectionMode !== "row";
 
   const columns = useMemo(() => {
     const base = withTMDataGridDefaults<TData>(
       options.columns as ReadonlyArray<TMDataGridColumnDef<TData>>,
     );
-    return selectionEnabled ? [createSelectColumn<TData>(), ...base] : base;
-  }, [options.columns, selectionEnabled]);
+    return selectColumnEnabled ? [createSelectColumn<TData>(), ...base] : base;
+  }, [options.columns, selectColumnEnabled]);
 
   // Read once on mount: `initialState` is only consumed on the first render,
   // and re-reading later would fight the user's live edits.
@@ -287,7 +304,7 @@ export function useTMDataGrid<TData extends RowData>({
         // The checkbox column is structurally pinned, so it is re-applied on
         // top of anything restored from storage.
         left: [
-          ...(selectionEnabled && pinningEnabled ? [SELECT_COLUMN_ID] : []),
+          ...(selectColumnEnabled && pinningEnabled ? [SELECT_COLUMN_ID] : []),
           ...(
             persistedState.columnPinning?.left ??
             options.initialState?.columnPinning?.left ??
@@ -311,13 +328,37 @@ export function useTMDataGrid<TData extends RowData>({
   // 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.
+  //
+  // Writes are debounced because `columnResizeMode: "onChange"` publishes a new
+  // state on every pointer move of a resize drag, and `setItem` serialises
+  // synchronously on the main thread. The trailing edge is enough: storage only
+  // has to agree with the table once the user stops.
   useEffect(() => {
     if (!hasPersistenceKeys(persist)) return;
     writePersistedState(table.store.state, persist);
+
+    let timeout: ReturnType<typeof setTimeout> | undefined;
+    let pending: TableState<TMDataGridFeatures> | null = null;
+
+    const flush = () => {
+      timeout = undefined;
+      if (pending === null) return;
+      writePersistedState(pending, persist);
+      pending = null;
+    };
+
     const subscription = table.store.subscribe((state) => {
-      writePersistedState(state, persist);
+      pending = state;
+      if (timeout !== undefined) clearTimeout(timeout);
+      timeout = setTimeout(flush, PERSIST_DEBOUNCE_MS);
     });
-    return () => subscription.unsubscribe();
+
+    return () => {
+      subscription.unsubscribe();
+      if (timeout !== undefined) clearTimeout(timeout);
+      // An unmount mid-debounce would otherwise drop the last change.
+      flush();
+    };
   }, [persist, table]);
 
   const ui = useCreateStore<TMDataGridUiState, TMDataGridUiActions>(
@@ -354,7 +395,13 @@ export function useTMDataGrid<TData extends RowData>({
   // 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 });
+  const features = readFeatureFlags({
+    ...options,
+    enableColumnOrdering,
+    enablePagination,
+    rowSelectionMode,
+    highlightSelectedRows,
+  });
 
   return { table, ui, features };
 }

package/src/tmdatagrid/TMDataGrid.module.css

@@ -1,410 +0,0 @@
-/* Size scale. Row heights mirror SIZE_ROW_HEIGHT in sizes.ts — the virtualizer
-   needs the number in JS, so the two have to agree. */
-.root[data-size="xs"] {
-  --dg-row-height: 34px;
-  --dg-header-height: 32px;
-  --dg-font-size: var(--mantine-font-size-xs);
-  --dg-padding: 6px;
-}
-
-.root[data-size="sm"] {
-  --dg-row-height: 42px;
-  --dg-header-height: 38px;
-  --dg-font-size: var(--mantine-font-size-sm);
-  --dg-padding: 8px;
-}
-
-.root[data-size="md"] {
-  --dg-row-height: 52px;
-  --dg-header-height: 44px;
-  --dg-font-size: var(--mantine-font-size-sm);
-  --dg-padding: 10px;
-}
-
-.root[data-size="lg"] {
-  --dg-row-height: 62px;
-  --dg-header-height: 52px;
-  --dg-font-size: var(--mantine-font-size-md);
-  --dg-padding: 14px;
-}
-
-.root[data-size="xl"] {
-  --dg-row-height: 72px;
-  --dg-header-height: 60px;
-  --dg-font-size: var(--mantine-font-size-lg);
-  --dg-padding: 18px;
-}
-
-.root {
-  /* Fallbacks, so the parts still work if rendered outside a sized root. */
-  --dg-row-height: 52px;
-  --dg-header-height: 44px;
-  --dg-font-size: var(--mantine-font-size-sm);
-  --dg-padding: 10px;
-
-  display: flex;
-  flex-direction: column;
-  min-height: 0;
-  overflow: hidden;
-  /* Header text is a stretched flex item, so an inherited `text-align: center`
-     from the host page would centre headers away from their cell content. */
-  text-align: left;
-  border: 1px solid var(--mantine-color-default-border);
-  border-radius: var(--mantine-radius-md);
-  background-color: var(--mantine-color-body);
-}
-
-.toolbar {
-  display: flex;
-  align-items: center;
-  gap: var(--mantine-spacing-xs);
-  padding: 6px var(--mantine-spacing-xs);
-  min-height: 42px;
-  flex-shrink: 0;
-}
-
-.toolbarSpacer {
-  flex: 1;
-}
-
-/* Anchors the filter panel, which floats over the first body rows. */
-.tableWrapper {
-  position: relative;
-  flex: 1;
-  min-height: 0;
-  display: flex;
-  flex-direction: column;
-}
-
-.scrollContainer {
-  position: relative;
-  flex: 1;
-  min-height: 0;
-  overflow: auto;
-}
-
-/* Column tracks are set inline via gridTemplateColumns. */
-.grid {
-  display: grid;
-}
-
-/* Rows are real layout boxes (not display: contents) so position: sticky works,
-   and subgrid keeps their cells on the parent's column tracks. */
-.headerRow {
-  display: grid;
-  grid-column: 1 / -1;
-  grid-template-columns: subgrid;
-  position: sticky;
-  top: 0;
-  z-index: 3;
-}
-
-.headerCell {
-  position: relative;
-  display: flex;
-  align-items: center;
-  gap: 2px;
-  padding: 0 var(--dg-padding);
-  min-width: 0;
-  min-height: var(--dg-header-height);
-  font-weight: 600;
-  font-size: var(--dg-font-size);
-  background-color: var(--mantine-color-body);
-  border-bottom: 1px solid var(--mantine-color-default-border);
-  user-select: none;
-}
-
-.headerCell[data-align="right"] {
-  justify-content: flex-end;
-}
-
-.headerCell[data-align="center"] {
-  justify-content: center;
-}
-
-/* Sorted or filtered columns read as active, like the MUI data grid. */
-.headerCell[data-active="true"] .headerTitle {
-  color: var(--mantine-primary-color-filled);
-}
-
-.headerTitle {
-  flex: 1 1 auto;
-  min-width: 0;
-  overflow: hidden;
-  text-overflow: ellipsis;
-  white-space: nowrap;
-}
-
-/* Right-aligned headers stay text so the ellipsis still works; centered ones
-   hold a control (the select-all checkbox), so they become a flex box. */
-.headerCell[data-align="right"] .headerTitle {
-  text-align: right;
-}
-
-.headerCell[data-align="center"] .headerTitle {
-  display: flex;
-  justify-content: center;
-}
-
-.headerActions {
-  display: flex;
-  align-items: center;
-  gap: 0;
-  flex-shrink: 0;
-  margin-left: auto;
-}
-
-/* Actions always reserve their width. On right-aligned columns they move to the
-   leading edge so the header text stays flush with the cell values below it. */
-.headerCell[data-align="right"] .headerActions {
-  order: -1;
-  margin-left: 0;
-  margin-right: auto;
-}
-
-/* Idle actions are removed from layout, not just faded — reserving their width
-   would truncate header text that otherwise fits. Indicators that must stay
-   visible (active sort, active filter, open menu) set data-pinned-visible. */
-.headerAction {
-  display: none;
-}
-
-.headerCell:hover .headerAction,
-.headerCell:focus-within .headerAction,
-.headerAction[data-pinned-visible="true"] {
-  display: flex;
-}
-
-.headerCellSortable {
-  cursor: pointer;
-}
-
-/* Column reordering. The dragged header stays in place and dims — the browser
-   already carries a snapshot of it under the pointer — while the header being
-   dragged over draws a bar on the edge the column will land against. */
-.headerCellDragging {
-  opacity: 0.4;
-}
-
-.headerCellDropBefore::before,
-.headerCellDropAfter::before {
-  content: "";
-  position: absolute;
-  top: 0;
-  bottom: 0;
-  width: 2px;
-  background-color: var(--mantine-primary-color-filled);
-  z-index: 5;
-  pointer-events: none;
-}
-
-.headerCellDropBefore::before {
-  left: 0;
-}
-
-.headerCellDropAfter::before {
-  right: 0;
-}
-
-/* Doubles as the column divider seen between every header cell. */
-.columnSeparator {
-  position: absolute;
-  top: 25%;
-  right: 0;
-  height: 50%;
-  width: 10px;
-  transform: translateX(50%);
-  display: flex;
-  justify-content: center;
-  z-index: 1;
-}
-
-.columnSeparatorResizable {
-  cursor: col-resize;
-  touch-action: none;
-}
-
-/* The divider is a hover affordance, not permanent chrome — it only appears on
-   the header cell you are pointing at, or on the column being resized. */
-.columnSeparator::after {
-  content: "";
-  width: 1px;
-  height: 100%;
-  background-color: transparent;
-  transition:
-    background-color 120ms ease,
-    width 120ms ease;
-}
-
-.headerCell:hover .columnSeparator::after,
-.headerCell:focus-within .columnSeparator::after {
-  background-color: var(--mantine-color-default-border);
-}
-
-.columnSeparatorResizable:hover::after,
-.columnSeparatorActive::after {
-  width: 2px;
-  background-color: var(--mantine-primary-color-filled);
-}
-
-.bodyRow {
-  --row-bg: var(--mantine-color-body);
-  display: grid;
-  grid-column: 1 / -1;
-  grid-template-columns: subgrid;
-  align-items: stretch;
-}
-
-.bodyRow:hover {
-  --row-bg: var(--mantine-color-default-hover);
-}
-
-.bodyRow[data-selected="true"] {
-  --row-bg: var(--mantine-primary-color-light);
-}
-
-/* Clipping lives on .cellContent, not here — a pinned cell has to let its
-   boundary gradient escape past its own right/left edge. */
-.bodyCell {
-  display: flex;
-  align-items: center;
-  padding: 0 var(--dg-padding);
-  border-bottom: 1px solid var(--mantine-color-default-border);
-  /* Inherited from .bodyRow — sticky cells need an opaque background. */
-  background-color: var(--row-bg);
-  font-size: var(--dg-font-size);
-}
-
-.cellContent {
-  min-width: 0;
-  overflow: hidden;
-  white-space: nowrap;
-  text-overflow: ellipsis;
-}
-
-.bodyCell[data-align="right"] {
-  justify-content: flex-end;
-}
-
-.bodyCell[data-align="center"] {
-  justify-content: center;
-}
-
-/* Only stretch to fill when left-aligned, so right/centre stay put. */
-.bodyCell[data-align="left"] .cellContent {
-  flex: 1 1 auto;
-}
-
-/* Boundary of a pinned column group.
-   A box-shadow is drawn per cell, and its blur fades in at each cell's own top
-   and bottom edge — stacked down a column that reads as banding at every row
-   seam. Instead: a crisp 1px border for the hard edge, plus a gradient pseudo
-   element pinned to `top: 0; bottom: 0` so consecutive cells butt together into
-   one unbroken band. Mantine sets `color-scheme` on the root, so light-dark()
-   resolves without a second selector. */
-.stickyLeft {
-  border-right: 1px solid var(--mantine-color-default-border);
-}
-
-.stickyRight {
-  border-left: 1px solid var(--mantine-color-default-border);
-}
-
-.stickyLeft::after,
-.stickyRight::after {
-  content: "";
-  position: absolute;
-  top: 0;
-  bottom: 0;
-  width: 4px;
-  pointer-events: none;
-}
-
-.stickyLeft::after {
-  left: 100%;
-  background: linear-gradient(
-    to right,
-    light-dark(rgba(0, 0, 0, 0.08), rgba(0, 0, 0, 0.28)),
-    transparent
-  );
-}
-
-.stickyRight::after {
-  right: 100%;
-  background: linear-gradient(
-    to left,
-    light-dark(rgba(0, 0, 0, 0.08), rgba(0, 0, 0, 0.28)),
-    transparent
-  );
-}
-
-.messageRow {
-  grid-column: 1 / -1;
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  justify-content: center;
-  gap: var(--mantine-spacing-xs);
-  padding: var(--mantine-spacing-xl);
-}
-
-.footer {
-  display: flex;
-  align-items: center;
-  justify-content: flex-end;
-  gap: var(--mantine-spacing-lg);
-  padding: 4px var(--mantine-spacing-sm);
-  min-height: 48px;
-  flex-shrink: 0;
-  border-top: 1px solid var(--mantine-color-default-border);
-}
-
-.filterPanel {
-  position: absolute;
-  top: 46px;
-  left: var(--mantine-spacing-md);
-  z-index: 5;
-  padding: var(--mantine-spacing-sm);
-  border-radius: var(--mantine-radius-md);
-  border: 1px solid var(--mantine-color-default-border);
-  background-color: var(--mantine-color-body);
-  box-shadow: var(--mantine-shadow-md);
-}
-
-.filterRow {
-  display: flex;
-  align-items: flex-end;
-  gap: var(--mantine-spacing-xs);
-}
-
-/* Marks the pin position a column is currently in. */
-.menuItemActive {
-  background-color: var(--mantine-color-default-hover);
-  font-weight: 600;
-}
-
-.columnsPanel {
-  width: 280px;
-  display: flex;
-  flex-direction: column;
-}
-
-.columnsPanelSearch {
-  padding: var(--mantine-spacing-sm);
-}
-
-.columnsPanelList {
-  display: flex;
-  flex-direction: column;
-  gap: var(--mantine-spacing-sm);
-  padding: 0 var(--mantine-spacing-sm) var(--mantine-spacing-sm);
-}
-
-.columnsPanelFooter {
-  display: flex;
-  align-items: center;
-  justify-content: space-between;
-  gap: var(--mantine-spacing-sm);
-  padding: var(--mantine-spacing-sm);
-  border-top: 1px solid var(--mantine-color-default-border);
-}