@jielga/tmdatagrid 0.1.0 → 0.2.0

package/src/tmdatagrid/{TMDataGridTable.tsx → components/TMDataGridTable.tsx}

@@ -7,14 +7,15 @@ import {
 } from "@tanstack/react-table";
 import { useSelector } from "@tanstack/react-store";
 import { useVirtualizer } from "@tanstack/react-virtual";
-import { useCallback, useRef } from "react";
-import classes from "./TMDataGrid.module.css";
-import { type TMDataGridRowData, useTMDataGridContext } from "./TMDataGridContext";
+import { useCallback, useEffect, useRef } from "react";
+import classes from "./TMDataGridTable.module.css";
+import sticky from "./sticky.module.css";
+import { type TMDataGridRowData, useTMDataGridContext } from "../TMDataGridContext";
 import { TMDataGridFilterPanel } from "./TMDataGridFilterPanel";
 import { TMDataGridHeaderCell } from "./TMDataGridHeaderCell";
-import { getColumnAlign } from "./columnUtils";
+import { getColumnAlign } from "../core/columnUtils";
 import { SearchIcon } from "./icons";
-import type { TMDataGridFeatures } from "./useTMDataGrid";
+import type { TMDataGridFeatures } from "../useTMDataGrid";
 
 /** Where a column sits relative to the pinned regions, resolved once per render. */
 export type TMDataGridColumnLayout = {
@@ -46,9 +47,9 @@ function TMDataGridBodyCell({
       data-align={getColumnAlign(cell.column)}
       className={[
         classes.bodyCell,
-        layout.isBoundary && layout.pinnedAt === "left" ? classes.stickyLeft : "",
+        layout.isBoundary && layout.pinnedAt === "left" ? sticky.stickyLeft : "",
         layout.isBoundary && layout.pinnedAt === "right"
-          ? classes.stickyRight
+          ? sticky.stickyRight
           : "",
       ]
         .filter(Boolean)
@@ -69,18 +70,23 @@ function TMDataGridBodyCell({
 }
 
 export type TMDataGridTableProps<TData extends RowData> = {
-  /** Called when a body row is clicked. */
+  /**
+   * Called when a body row is clicked. Runs in addition to row selection under
+   * `rowSelectionMode: "row"`, not instead of it.
+   */
   onRowClick?: (row: Row<TMDataGridFeatures, TData>) => void;
 };
 
 /**
  * The scrollable grid surface. Always virtualized: only the rows inside the
- * viewport (plus overscan) are mounted, regardless of page size.
+ * viewport (plus overscan) are mounted — which is what makes the default
+ * no-pagination mode viable at any row count. Pagination is opt-in via
+ * `enablePagination` (or implied by `manualPagination`).
  */
 export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
   onRowClick,
 }: TMDataGridTableProps<TData>) {
-  const { table, rowHeight, controlSize } = useTMDataGridContext();
+  const { table, features, rowHeight, controlSize } = useTMDataGridContext();
 
   // The body depends on every state slice (sorting, filters, paging, sizing,
   // visibility, selection), so it subscribes to the whole table store.
@@ -90,8 +96,23 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
     table.options.meta ?? {};
 
   const scrollContainerRef = useRef<HTMLDivElement>(null);
-  // Respects `manualPagination`: server-paged grids get the rows as delivered.
-  const rows = table.getPaginatedRowModel().rows;
+  // Pagination off (the default): every filtered+sorted row, virtualized.
+  // Pagination on: the current page; under `manualPagination` TanStack returns
+  // the rows as delivered, so the same branch serves server paging.
+  const rows = features.pagination
+    ? table.getPaginatedRowModel().rows
+    : table.getPrePaginatedRowModel().rows;
+
+  // A persisted pageIndex can outlive the data that produced it; TanStack only
+  // auto-resets on live filter/sort/data changes, not on restored state. The
+  // guard makes the dependency-free effect idempotent.
+  useEffect(() => {
+    if (!features.pagination) return;
+    const pageCount = table.getPageCount();
+    if (pageCount > 0 && table.store.state.pagination.pageIndex >= pageCount) {
+      table.setPageIndex(pageCount - 1);
+    }
+  });
 
   const virtualizer = useVirtualizer({
     count: rows.length,
@@ -200,17 +221,38 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
 
   const isEmpty = rows.length === 0;
 
+  // "row" mode: the row itself is the selection control — clicking it toggles
+  // that row and leaves the rest of the selection alone.
+  const selectsOnRowClick =
+    features.rowSelection && features.rowSelectionMode === "row";
+  const rowIsInteractive = selectsOnRowClick || onRowClick !== undefined;
+
+  const handleRowActivate = (row: Row<TMDataGridFeatures, TMDataGridRowData>) => {
+    if (selectsOnRowClick && row.getCanSelect()) row.toggleSelected();
+    onRowClick?.(row as unknown as Row<TMDataGridFeatures, TData>);
+  };
+
   return (
     <div className={classes.tableWrapper}>
       <div ref={scrollContainerRef} className={classes.scrollContainer}>
         <div
           role="table"
           className={classes.grid}
+          // Virtualization means most rows are not in the DOM, so the counts
+          // have to be stated rather than inferred from what is rendered. Every
+          // row carries its aria-rowindex for the same reason.
+          aria-rowcount={rows.length + headerGroups.length}
+          aria-colcount={orderedColumns.length}
           style={{ gridTemplateColumns, minWidth: gridMinWidth }}
         >
           <div role="rowgroup" style={{ display: "contents" }}>
-            {headerGroups.map((headerGroup) => (
-              <div key={headerGroup.id} role="row" className={classes.headerRow}>
+            {headerGroups.map((headerGroup, groupIndex) => (
+              <div
+                key={headerGroup.id}
+                role="row"
+                aria-rowindex={groupIndex + 1}
+                className={classes.headerRow}
+              >
                 {headerGroup.headers.map((header) => (
                   <TMDataGridHeaderCell
                     key={header.id}
@@ -234,19 +276,36 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
                 <div
                   key={virtualItem.key}
                   role="row"
+                  aria-rowindex={virtualItem.index + headerGroups.length + 1}
                   data-testid={`dg-row-${row.id}`}
                   data-selected={row.getIsSelected()}
+                  // Selection is state; the highlight is a display choice, so
+                  // the two are separate attributes.
+                  data-highlighted={
+                    features.highlightSelectedRows && row.getIsSelected()
+                  }
+                  data-selects-on-click={selectsOnRowClick}
+                  aria-selected={
+                    features.rowSelection ? row.getIsSelected() : undefined
+                  }
                   className={classes.bodyRow}
                   style={{
                     minHeight: rowHeight,
-                    cursor: onRowClick ? "pointer" : undefined,
+                    cursor: rowIsInteractive ? "pointer" : undefined,
                   }}
+                  // Keyboard parity with the checkbox the row replaces.
+                  tabIndex={selectsOnRowClick ? 0 : undefined}
                   onClick={
-                    onRowClick
-                      ? () =>
-                          onRowClick(
-                            row as unknown as Row<TMDataGridFeatures, TData>,
-                          )
+                    rowIsInteractive ? () => handleRowActivate(row) : undefined
+                  }
+                  onKeyDown={
+                    selectsOnRowClick
+                      ? (event) => {
+                          if (event.key !== " " && event.key !== "Enter") return;
+                          if (event.target !== event.currentTarget) return;
+                          event.preventDefault();
+                          handleRowActivate(row);
+                        }
                       : undefined
                   }
                 >

package/src/tmdatagrid/components/TMDataGridToolbar.module.css

@@ -0,0 +1,12 @@
+.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;
+}

package/src/tmdatagrid/{TMDataGridToolbar.tsx → components/TMDataGridToolbar.tsx}

@@ -1,13 +1,13 @@
 import { ActionIcon, Popover, Text, Tooltip } from "@mantine/core";
 import { useSelector } from "@tanstack/react-store";
 import type { ReactNode } from "react";
-import classes from "./TMDataGrid.module.css";
+import classes from "./TMDataGridToolbar.module.css";
 import { TMDataGridColumnsPanel } from "./TMDataGridColumnsPanel";
-import { useTMDataGridContext } from "./TMDataGridContext";
-import { getGridCapabilities } from "./capabilities";
-import { isFilterActive } from "./filterOperators";
+import { useTMDataGridContext } from "../TMDataGridContext";
+import { getGridCapabilities } from "../core/capabilities";
+import { isFilterActive } from "../core/filterOperators";
 import { BurgerIcon, FilterIcon } from "./icons";
-import { openColumnFilter } from "./useTMDataGrid";
+import { openColumnFilter } from "../useTMDataGrid";
 
 /** Row above the grid. Compose it from the pieces below, or anything else. */
 export function TMDataGridToolbar({ children }: { children?: ReactNode }) {

package/src/tmdatagrid/components/sticky.module.css

@@ -0,0 +1,45 @@
+/* Boundary of a pinned column group. Shared, because the edge is cast by both
+   the header cell and every body cell in the same column — the two have to
+   draw an identical band or the seam shows at the header.
+
+   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
+  );
+}

package/src/tmdatagrid/{capabilities.ts → core/capabilities.ts}

@@ -1,11 +1,11 @@
 import type { Column, RowData } from "@tanstack/react-table";
-import type { TMDataGridRowData } from "./TMDataGridContext";
+import type { TMDataGridRowData } from "../TMDataGridContext";
 import { isColumnReorderable } from "./columnUtils";
 import type {
   TMDataGridFeatures,
   TMDataGridTable,
   UseTMDataGridOptions,
-} from "./useTMDataGrid";
+} from "../useTMDataGrid";
 
 /**
  * Table-level feature switches, read straight off the options object.
@@ -19,6 +19,11 @@ import type {
  * TanStack still decides: these flags are combined with `getCanX()`, which is
  * what applies the per-column overrides.
  */
+/**
+ * How rows are selected — see `rowSelectionMode` on {@link UseTMDataGridOptions}.
+ */
+export type TMDataGridRowSelectionMode = "checkbox" | "row";
+
 export type TMDataGridFeatureFlags = {
   sorting: boolean;
   filtering: boolean;
@@ -27,6 +32,16 @@ export type TMDataGridFeatureFlags = {
   resizing: boolean;
   ordering: boolean;
   rowSelection: boolean;
+  /** Only meaningful while `rowSelection` is on. Defaults to `"checkbox"`. */
+  rowSelectionMode: TMDataGridRowSelectionMode;
+  /** Whether a selected row takes the highlight colour. Follows the mode. */
+  highlightSelectedRows: boolean;
+  /**
+   * The one default-off flag: pagination must be asked for, either with the
+   * grid's `enablePagination` or implicitly by declaring `manualPagination`.
+   * Off, the grid renders every filtered row and relies on virtualization.
+   */
+  pagination: boolean;
 };
 
 export function readFeatureFlags<TData extends RowData>(
@@ -39,6 +54,10 @@ export function readFeatureFlags<TData extends RowData>(
     | "enableColumnResizing"
     | "enableColumnOrdering"
     | "enableRowSelection"
+    | "rowSelectionMode"
+    | "highlightSelectedRows"
+    | "enablePagination"
+    | "manualPagination"
   >,
 ): TMDataGridFeatureFlags {
   return {
@@ -49,6 +68,13 @@ export function readFeatureFlags<TData extends RowData>(
     resizing: options.enableColumnResizing !== false,
     ordering: options.enableColumnOrdering !== false,
     rowSelection: options.enableRowSelection !== false,
+    rowSelectionMode: options.rowSelectionMode ?? "checkbox",
+    // In "row" mode the highlight *is* the feedback for a click, so it is on.
+    // With checkboxes the box already says it, so it is off unless asked for.
+    highlightSelectedRows:
+      options.highlightSelectedRows ?? options.rowSelectionMode === "row",
+    pagination:
+      options.enablePagination === true || options.manualPagination === true,
   };
 }
 
@@ -96,6 +122,7 @@ export type TMDataGridCapabilities = {
   canPinAny: boolean;
   canReorderAny: boolean;
   canSelectRows: boolean;
+  canPaginate: boolean;
 };
 
 export function getGridCapabilities(
@@ -113,5 +140,6 @@ export function getGridCapabilities(
     canPinAny: any((c) => c.canPin),
     canReorderAny: any((c) => c.canReorder),
     canSelectRows: features.rowSelection,
+    canPaginate: features.pagination,
   };
 }

package/src/tmdatagrid/{columnOrdering.ts → core/columnOrdering.ts}

@@ -1,7 +1,7 @@
 import type { Column, ColumnPinningState } from "@tanstack/react-table";
-import type { TMDataGridRowData } from "./TMDataGridContext";
+import type { TMDataGridRowData } from "../TMDataGridContext";
 import { isColumnReorderable } from "./columnUtils";
-import type { TMDataGridFeatures, TMDataGridTable } from "./useTMDataGrid";
+import type { TMDataGridFeatures, TMDataGridTable } from "../useTMDataGrid";
 
 type GridColumn = Column<TMDataGridFeatures, TMDataGridRowData, unknown>;
 type GridTable = TMDataGridTable<TMDataGridRowData>;

package/src/tmdatagrid/{columnUtils.ts → core/columnUtils.ts}

@@ -1,5 +1,5 @@
 import type { TMDataGridColumnType } from "./filterOperators";
-import type { TMDataGridColumnMeta } from "./useTMDataGrid";
+import type { TMDataGridColumnMeta } from "../useTMDataGrid";
 
 /**
  * Structural shape of the column bits the chrome reads. Kept minimal so these

package/src/tmdatagrid/{persistence.ts → core/persistence.ts}

@@ -1,5 +1,5 @@
 import type { TableState } from "@tanstack/react-table";
-import type { TMDataGridFeatures } from "./useTMDataGrid";
+import type { TMDataGridFeatures } from "../useTMDataGrid";
 
 type GridState = TableState<TMDataGridFeatures>;
 
@@ -100,6 +100,82 @@ function resolveStorage(
   }
 }
 
+/**
+ * Shape guards for restored state.
+ *
+ * A stored payload outlives the code that wrote it: a slice can change shape
+ * between releases, and nothing stops anyone from editing storage by hand. The
+ * value goes straight into `initialState`, where a wrong shape surfaces as a
+ * crash inside TanStack rather than as a bad read here. A slice that fails its
+ * guard is dropped; the rest still restore.
+ */
+function prop(value: unknown, key: string): unknown {
+  return typeof value === "object" && value !== null
+    ? (value as Record<string, unknown>)[key]
+    : undefined;
+}
+
+const isString = (value: unknown): value is string => typeof value === "string";
+
+const isFiniteNumber = (value: unknown): value is number =>
+  typeof value === "number" && Number.isFinite(value);
+
+function isArrayOf(
+  value: unknown,
+  isItem: (item: unknown) => boolean,
+): boolean {
+  return Array.isArray(value) && value.every(isItem);
+}
+
+function isRecordOf(
+  value: unknown,
+  isItem: (item: unknown) => boolean,
+): boolean {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  return Object.values(value).every(isItem);
+}
+
+const hasStringId = (entry: unknown): boolean => isString(prop(entry, "id"));
+
+const SLICE_GUARDS: Record<
+  TMDataGridDataSlice | TMDataGridSettingsSlice,
+  (value: unknown) => boolean
+> = {
+  columnFilters: (value) => isArrayOf(value, hasStringId),
+  // TanStack leaves the global filter value untyped — the grid's own default
+  // filters on a string, but a consumer may store anything here.
+  globalFilter: () => true,
+  sorting: (value) =>
+    isArrayOf(
+      value,
+      (entry) => hasStringId(entry) && typeof prop(entry, "desc") === "boolean",
+    ),
+  pagination: (value) => {
+    const pageIndex = prop(value, "pageIndex");
+    const pageSize = prop(value, "pageSize");
+    return (
+      isFiniteNumber(pageIndex) &&
+      pageIndex >= 0 &&
+      isFiniteNumber(pageSize) &&
+      pageSize > 0
+    );
+  },
+  columnVisibility: (value) =>
+    isRecordOf(value, (entry) => typeof entry === "boolean"),
+  columnSizing: (value) => isRecordOf(value, isFiniteNumber),
+  columnOrder: (value) => isArrayOf(value, isString),
+  columnPinning: (value) =>
+    isArrayOf(prop(value, "left"), isString) &&
+    isArrayOf(prop(value, "right"), isString),
+};
+
+function isValidSlice(slice: keyof GridState, value: unknown): boolean {
+  const guard = SLICE_GUARDS[slice as keyof typeof SLICE_GUARDS];
+  return guard === undefined || guard(value);
+}
+
 function readSlices(
   storage: Storage | null,
   resolved: ResolvedKey | null,
@@ -117,7 +193,9 @@ function readSlices(
     // Only copy the selected slices. A payload written before the selection was
     // narrowed cannot reintroduce slices the caller has since opted out of.
     for (const slice of resolved.slices) {
-      if (slice in record) restored[slice] = record[slice];
+      if (!(slice in record)) continue;
+      if (!isValidSlice(slice, record[slice])) continue;
+      restored[slice] = record[slice];
     }
     return restored as Partial<GridState>;
   } catch {

package/src/tmdatagrid/index.ts

@@ -1,13 +1,13 @@
-export { TMDataGrid, type TMDataGridProps } from "./TMDataGrid";
+export { TMDataGrid, type TMDataGridProps } from "./components/TMDataGrid";
 export {
   useTMDataGridContext,
   type TMDataGridContextValue,
   type TMDataGridRowData,
 } from "./TMDataGridContext";
+export { SELECT_COLUMN_ID } from "./components/TMDataGridSelectColumn";
 export {
   createTMDataGridColumnHelper,
   openColumnFilter,
-  SELECT_COLUMN_ID,
   tmDataGridFeatures,
   type TMDataGridApi,
   type TMDataGridColumnMeta,
@@ -26,12 +26,12 @@ export {
   type TMDataGridFilterValue,
   FILTER_OPERATOR_LABELS,
   isFilterActive,
-} from "./filterOperators";
+} from "./core/filterOperators";
 export {
   getColumnLabel,
   getColumnType,
   isColumnReorderable,
-} from "./columnUtils";
+} from "./core/columnUtils";
 export {
   getColumnRegion,
   getStepTargetColumn,
@@ -41,7 +41,7 @@ export {
   type MoveColumnArgs,
   type TMDataGridColumnRegion,
   type TMDataGridDropSide,
-} from "./columnOrdering";
+} from "./core/columnOrdering";
 export {
   getColumnCapabilities,
   getGridCapabilities,
@@ -49,13 +49,14 @@ export {
   type TMDataGridCapabilities,
   type TMDataGridColumnCapabilities,
   type TMDataGridFeatureFlags,
-} from "./capabilities";
+  type TMDataGridRowSelectionMode,
+} from "./core/capabilities";
 export {
   DEFAULT_TMDATAGRID_SIZE,
   SIZE_CONTROL_SIZE,
   SIZE_ROW_HEIGHT,
   type TMDataGridSize,
-} from "./sizes";
+} from "./core/sizes";
 export {
   DATA_STATE_SLICES,
   SETTINGS_STATE_SLICES,
@@ -64,5 +65,10 @@ export {
   type TMDataGridPersistKey,
   type TMDataGridSettingsSlice,
   type TMDataGridStorageMode,
-} from "./persistence";
-export type { TMDataGridColumnLayout } from "./TMDataGridTable";
+} from "./core/persistence";
+export type { TMDataGridColumnLayout } from "./components/TMDataGridTable";
+export {
+  getTMDataGridPaginationApi,
+  type TMDataGridFooterProps,
+  type TMDataGridPaginationApi,
+} from "./components/TMDataGridFooter";