@jielga/tmdatagrid 2.1.4 → 2.3.0

package/src/core/autosize.ts

@@ -1,6 +1,7 @@
 import type { RowData } from "@tanstack/react-table";
 import type { TMDataGridRowData } from "../TMDataGridContext";
 import type { TMDataGridTable } from "../useTMDataGrid";
+import { DEFAULT_COLUMN_MIN_SIZE } from "./columnUtils";
 import { isHTMLElement } from "./dom";
 
 /**
@@ -40,30 +41,41 @@ function contentSpanWidth(content: HTMLElement): number {
   return width > 0 ? width : content.scrollWidth;
 }
 
-/** One column's body cells that are currently in the DOM. */
+/**
+ * One column's body cells that are currently in the DOM.
+ *
+ * `measurable` leaves out the cells spanning several columns (`meta.colSpan`):
+ * such a cell says nothing about this one column's width.
+ */
 function mountedCells(
   container: HTMLElement,
   columnId: string,
+  { measurable }: { measurable: boolean },
 ): NodeListOf<HTMLElement> {
   const id = CSS.escape(columnId);
+  const unspanned = measurable ? ":not([data-col-span])" : "";
   return container.querySelectorAll<HTMLElement>(
-    `[role="cell"][data-column-id="${id}"],` +
-      `[role="gridcell"][data-column-id="${id}"]`,
+    `[role="cell"][data-column-id="${id}"]${unspanned},` +
+      `[role="gridcell"][data-column-id="${id}"]${unspanned}`,
   );
 }
 
 /**
- * Whether this column has any body cell in the DOM to measure.
+ * Whether this column has any body cell in the DOM.
  *
  * A caller sizing a column on its own schedule rather than from a gesture has
  * to ask: the virtualizer mounts its first rows a render *after* the grid
  * itself mounts, and a measurement taken before that fits the header alone.
+ *
+ * A spanning cell counts. A column whose every mounted cell spans has its
+ * rows, and measuring it fits the header, which is the width it gets; left
+ * out, the column would wait for cells that never come.
  */
 export function hasMountedCells(
   container: HTMLElement,
   columnId: string,
 ): boolean {
-  return mountedCells(container, columnId).length > 0;
+  return mountedCells(container, columnId, { measurable: false }).length > 0;
 }
 
 /**
@@ -85,7 +97,7 @@ export function measureColumnContentWidth({
 }): number {
   let widest = 0;
 
-  for (const cell of mountedCells(container, columnId)) {
+  for (const cell of mountedCells(container, columnId, { measurable: true })) {
     const content = cell.firstElementChild;
     if (!isHTMLElement(content)) continue;
     const styles = getComputedStyle(cell);
@@ -143,7 +155,7 @@ export function autosizeColumn<TData extends RowData>({
   const measured = measureColumnContentWidth({ container, columnId });
   if (measured <= 0) return false;
 
-  const minSize = column.columnDef.minSize ?? 80;
+  const minSize = column.columnDef.minSize ?? DEFAULT_COLUMN_MIN_SIZE;
   const maxSize = column.columnDef.maxSize ?? Number.POSITIVE_INFINITY;
   const width = Math.round(Math.min(Math.max(measured, minSize), maxSize));
 

package/src/core/cellRange.ts

@@ -70,7 +70,13 @@ export function resolveRangeBounds({
   };
 }
 
-/** Whether a cell is inside the rectangle. */
+/**
+ * Whether a cell is inside the rectangle.
+ *
+ * A cell spanning several columns (`meta.colSpan`) is addressed by its first
+ * column: it is inside when that column is, and a rectangle over only the
+ * columns it covers leaves it out.
+ */
 export function isWithinBounds(
   bounds: TMDataGridRangeBounds | null,
   rowIndex: number,
@@ -105,14 +111,17 @@ export function boundsEdges(
   bounds: TMDataGridRangeBounds | null,
   rowIndex: number,
   columnIndex: number,
+  lastColumnIndex: number = columnIndex,
 ): { top: boolean; bottom: boolean; left: boolean; right: boolean } | null {
   if (!isWithinBounds(bounds, rowIndex, columnIndex) || bounds === null) {
     return null;
   }
+  // A cell spanning columns up to `lastColumnIndex` is one box: the
+  // rectangle's right edge falling anywhere inside it is drawn on its side.
   return {
     top: rowIndex === bounds.top,
     bottom: rowIndex === bounds.bottom,
     left: columnIndex === bounds.left,
-    right: columnIndex === bounds.right,
+    right: bounds.right <= lastColumnIndex,
   };
 }

package/src/core/colSpan.ts

@@ -0,0 +1,78 @@
+import { isGeneratedColumn } from "./columnUtils";
+
+/** Which pinned block a displayed column sits in. */
+export type TMDataGridColumnSection = "left" | "center" | "right";
+
+/**
+ * How wide each displayed cell of one row is, in columns.
+ *
+ * `spans[i]` is `n >= 1` for a cell that renders and covers `n` tracks from
+ * column `i` rightwards, and `0` for a cell covered by one to its left, which
+ * does not render. The array runs in display order, the order of
+ * `orderedColumns`, and its entries always sum to the column count.
+ *
+ * A span stops short at the first column it may not cover:
+ *
+ * - a generated lane - the checkbox, tree, details and edit lanes stay
+ *   where they are whatever a data cell asks for, which is also why
+ *   `Infinity` reads as "to the last of my columns";
+ * - the edge of the cell's pinned block - a pinned cell is sticky at the
+ *   offset of its own column, and one stretching into the scrolling centre
+ *   would slide over the cells it is meant to leave.
+ *
+ * A generated lane never spans, and a request below 1, or one that is not a
+ * number, is 1.
+ */
+export function resolveColSpans(
+  columns: ReadonlyArray<{ id: string; section: TMDataGridColumnSection }>,
+  requestedSpan: (columnIndex: number) => number,
+): Array<number> {
+  const spans: Array<number> = [];
+  let index = 0;
+  while (index < columns.length) {
+    const column = columns[index]!;
+    const requested = isGeneratedColumn(column.id) ? 1 : requestedSpan(index);
+    const wanted =
+      typeof requested === "number" && requested >= 1
+        ? Math.floor(requested)
+        : 1;
+    let span = 1;
+    while (span < wanted) {
+      const next = columns[index + span];
+      if (
+        next === undefined ||
+        next.section !== column.section ||
+        isGeneratedColumn(next.id)
+      ) {
+        break;
+      }
+      span += 1;
+    }
+    spans.push(span);
+    for (let covered = 1; covered < span; covered += 1) spans.push(0);
+    index += span;
+  }
+  return spans;
+}
+
+/**
+ * The column a position on a row lands on once spans are applied: itself
+ * when its cell renders, otherwise the spanning cell covering it.
+ */
+export function spanAnchorIndex(
+  spans: ReadonlyArray<number>,
+  columnIndex: number,
+): number {
+  let index = columnIndex;
+  while (index > 0 && spans[index] === 0) index -= 1;
+  return index;
+}
+
+/** The last column the cell at `columnIndex` covers - itself when unspanned. */
+export function spanEndIndex(
+  spans: ReadonlyArray<number>,
+  columnIndex: number,
+): number {
+  const anchor = spanAnchorIndex(spans, columnIndex);
+  return anchor + Math.max(1, spans[anchor] ?? 1) - 1;
+}

package/src/core/columnUtils.ts

@@ -160,6 +160,13 @@ export function isColumnReorderable(column: ColumnLike): boolean {
   return column.parent === undefined;
 }
 
+/**
+ * The `minSize` of a column that sets none: the floor of its fluid track, of a
+ * resize drag and of its pinned width. Passed to TanStack as
+ * `defaultColumn.minSize`, which otherwise fills in 20.
+ */
+export const DEFAULT_COLUMN_MIN_SIZE = 80;
+
 /** The list length from which a column chooser shows its search box. */
 export const COLUMN_SEARCH_MIN = 6;
 

package/src/core/filterControls.ts

@@ -106,4 +106,12 @@ export type TMDataGridColumnFilterOptions = {
    * See {@link TMDataGridFilterControlComponent}.
    */
   control?: TMDataGridFilterControlComponent;
+  /**
+   * Whether this column's filter goes into the `persist.urlKey` search param.
+   * Defaults to `true`. `false` keeps it out of the param, on read and on
+   * write. Only has an effect when `urlKey` carries `columnFilters`, and since such
+   * a slice is not stored under `dataKey` either, the filter is then not
+   * persisted anywhere.
+   */
+  url?: boolean;
 };

package/src/core/filterOperators.ts

@@ -1,10 +1,11 @@
 import type {
   ColumnFiltersState,
+  FilterMeta,
   Row,
   RowData,
   TableFeatures,
 } from "@tanstack/react-table";
-import type { TMDataGridTable } from "../useTMDataGrid";
+import type { TMDataGridFeatures, TMDataGridTable } from "../useTMDataGrid";
 
 /**
  * The value shape stored in `columnFilters` for every TMDataGrid column.
@@ -250,6 +251,19 @@ export function isFilterActive(value: unknown): boolean {
     : typeof value.value === "string" && value.value.trim() !== "";
 }
 
+/**
+ * Whether one `columnFilters` entry narrows the rows, by the one rule the grid
+ * uses for "active": an envelope counts once {@link isFilterActive} says so,
+ * and a value that is not an envelope always counts, since a raw value written
+ * by consumer code narrows the rows as far as the grid can tell.
+ *
+ * @internal Shared by the empty state and the `urlKey` param; not exported
+ * from the package.
+ */
+export function filterNarrowsRows(entry: { value: unknown }): boolean {
+  return !isTMDataGridFilterValue(entry.value) || isFilterActive(entry.value);
+}
+
 /** One column's filter, typed - what `columnFilters` holds per entry. */
 export type TMDataGridColumnFilter = {
   id: string;
@@ -474,6 +488,20 @@ export function matchesFilter(
   }
 }
 
+/**
+ * The signature of a column's own `filterFn`. The third argument is the
+ * `{ operator, value }` envelope the grid writes into `columnFilters`; a
+ * column `filterFn` replaces `tmDataGridFilterFn` outright, so it is handed
+ * the envelope, not the unwrapped value. Delegate to `tmDataGridFilterFn`
+ * for the operators the function does not handle itself.
+ */
+export type TMDataGridFilterFn<TData extends RowData> = (
+  row: Row<TMDataGridFeatures, TData>,
+  columnId: string,
+  filterValue: TMDataGridFilterValue,
+  addMeta?: (meta: FilterMeta) => void,
+) => boolean;
+
 /**
  * The single filter function every TMDataGrid column uses. It dispatches on the
  * operator carried by the filter value, which is what lets one column offer