@jielga/tmdatagrid 2.1.4 → 2.2.0

package/src/components/TMDataGridTable.tsx

@@ -41,6 +41,7 @@ import {
 } from "./TMDataGridCellEditor";
 import { TMDataGridEntryRows } from "./TMDataGridEntryRows";
 import {
+  DEFAULT_COLUMN_MIN_SIZE,
   getColumnAlign,
   isControlColumn,
   isGeneratedColumn,
@@ -76,6 +77,12 @@ import {
   writeExportFile,
 } from "../core/export";
 import { autosizeColumn, hasMountedCells } from "../core/autosize";
+import {
+  resolveColSpans,
+  spanAnchorIndex,
+  spanEndIndex,
+  type TMDataGridColumnSection,
+} from "../core/colSpan";
 import {
   getDisplayedRows,
   getSelectableRowIds,
@@ -83,6 +90,7 @@ import {
   resolveRowSelectionClick,
 } from "../core/rowSelection";
 import { readPinnedRows } from "../core/rowPinning";
+import { isFilterActive, isTMDataGridFilterValue } from "../core/filterOperators";
 import { buildMatchNeedles, findMatchRanges } from "../core/matchHighlight";
 import { ROW_NUMBER_COLUMN_ID } from "./TMDataGridRowNumberColumn";
 import { SearchIcon } from "./icons";
@@ -253,6 +261,7 @@ function withMatchHighlights(
 function TMDataGridBodyCell({
   cell,
   rowHeight,
+  colSpan = 1,
   layout,
   nav,
   editor,
@@ -267,6 +276,8 @@ function TMDataGridBodyCell({
 }: {
   cell: Cell<TMDataGridFeatures, TMDataGridRowData, unknown>;
   rowHeight: number;
+  /** Columns this cell covers - see `meta.colSpan`. */
+  colSpan?: number;
   layout: TMDataGridColumnLayout;
   nav?: TMDataGridCellNav;
   /** The mounted editor, when this is the cell being edited. */
@@ -332,6 +343,10 @@ function TMDataGridBodyCell({
       // than always.
       role={nav ? "gridcell" : "cell"}
       aria-colindex={nav?.columnIndex}
+      aria-colspan={colSpan > 1 ? colSpan : undefined}
+      // Published for styling and for autosize, which leaves a spanning cell
+      // out of its column's measurement.
+      data-col-span={colSpan > 1 ? colSpan : undefined}
       tabIndex={nav?.tabIndex}
       // The marker the delegated key handler tests: a key event whose target is
       // a cell is the grid's, one from inside a cell belongs to whatever holds
@@ -381,6 +396,7 @@ function TMDataGridBodyCell({
         .join(" ")}
       style={{
         minHeight: rowHeight,
+        gridColumn: colSpan > 1 ? `span ${colSpan}` : undefined,
         left: layout.pinnedAt === "left" ? layout.offset : undefined,
         right: layout.pinnedAt === "right" ? layout.offset : undefined,
         // The focus ring is drawn inside the cell's own box, so the cell has to
@@ -1182,6 +1198,111 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
     ...rightLeafColumns,
   ];
 
+  // `meta.colSpan`, resolved per row over the displayed columns. Built from
+  // the three leaf arrays rather than `column.getIsPinned()`, for the reason
+  // the sticky offsets below give. `null` while no column asks to span, so a
+  // plain grid never calls into it.
+  const spanColumns = orderedColumns.some(
+    (column) => column.columnDef.meta?.colSpan !== undefined,
+  )
+    ? orderedColumns.map((column, index) => ({
+        id: column.id,
+        colSpan: column.columnDef.meta?.colSpan,
+        section: (index < leftLeafColumns.length
+          ? "left"
+          : index < leftLeafColumns.length + centerLeafColumns.length
+            ? "center"
+            : "right") as TMDataGridColumnSection,
+      }))
+    : null;
+  /**
+   * Row mode opens every editable cell of the row at once, and rows
+   * accumulate: a second row opening leaves the first one open, so every row
+   * holding a form shows its editors. Which of them holds the caret is not
+   * decided here - see placeEditCaret, which places it once per gesture.
+   *
+   * A parked row is not one of them. It keeps its form, so it is still
+   * "open", but it has been decided: it renders its draft through the
+   * column's own renderer until `begin` reopens it. A committed entry row in
+   * the body has a form too - every entry row does - but it is a value row
+   * until reopened, and reopening takes it back to the entry block.
+   *
+   * Such a row also drops its spans: the form has an editor in every column.
+   */
+  const isRowEditing = (row: Row<TMDataGridFeatures, TMDataGridRowData>) =>
+    features.editMode === "row" &&
+    editOpenRowIdSet.has(row.id) &&
+    !editDraftRowIdSet.has(row.id) &&
+    !newRowIdSet.has(row.id);
+  const colSpanCache = new Map<string, Array<number> | null>();
+  /**
+   * The spans of one row - see {@link resolveColSpans} - or `null` when every
+   * cell is one column wide. Group rows keep their cells: the tree cell and
+   * the aggregates are the grid's, not a record's.
+   */
+  const colSpansOf = (
+    row: Row<TMDataGridFeatures, TMDataGridRowData>,
+  ): Array<number> | null => {
+    if (spanColumns === null || row.getIsGrouped() || isRowEditing(row)) {
+      return null;
+    }
+    const cached = colSpanCache.get(row.id);
+    if (cached !== undefined) return cached;
+    const spans = resolveColSpans(spanColumns, (index) => {
+      const colSpan = spanColumns[index]?.colSpan;
+      return typeof colSpan === "function"
+        ? colSpan({ row, table })
+        : (colSpan ?? 1);
+    });
+    // The open cell editor lives in its column's cell. A span landing on that
+    // column - the row expanding under the edit, say - would unmount the
+    // editor without closing it, so the row keeps its cells until the edit
+    // ends.
+    const editIndex =
+      editActive !== null && editActive.rowId === row.id
+        ? orderedColumns.findIndex(
+            (column) => column.id === editActive.columnId,
+          )
+        : -1;
+    const resolved =
+      spans.every((span) => span === 1) ||
+      (editIndex >= 0 && spans[editIndex] === 0)
+        ? null
+        : spans;
+    colSpanCache.set(row.id, resolved);
+    return resolved;
+  };
+  /** Whether the column at `columnIndex` is covered by a span on `row`. */
+  const isCoveredCell = (
+    row: Row<TMDataGridFeatures, TMDataGridRowData>,
+    columnIndex: number,
+  ): boolean => {
+    const spans = colSpansOf(row);
+    return spans !== null && spans[columnIndex] === 0;
+  };
+  /**
+   * A position moved onto the cell that renders it, under spans: the input
+   * itself when its cell renders, so a caller can compare by identity. `row`
+   * is the position's row; `undefined` for a pinned row, which is not in
+   * `rows` and keeps its position as it is.
+   */
+  const toRenderedCell = (
+    position: TMDataGridCellPosition,
+    row: Row<TMDataGridFeatures, TMDataGridRowData> | undefined,
+  ): TMDataGridCellPosition => {
+    if (spanColumns === null || row === undefined) return position;
+    const spans = colSpansOf(row);
+    if (spans === null) return position;
+    const columnIndex = orderedColumns.findIndex(
+      (column) => column.id === position.columnId,
+    );
+    if (columnIndex < 0) return position;
+    const anchorIndex = spanAnchorIndex(spans, columnIndex);
+    if (anchorIndex === columnIndex) return position;
+    const anchor = orderedColumns[anchorIndex];
+    return anchor ? { ...position, columnId: anchor.id } : position;
+  };
+
   // Headers and cells must follow the same left → center → right order as the
   // column tracks, otherwise pinning a column would shuffle it out of its lane.
   const centerHeaderGroups = table.getCenterHeaderGroups();
@@ -1208,7 +1329,7 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
       const isFixed = column.columnDef.minSize === column.columnDef.maxSize;
       const isResized = column.id in columnSizing;
       const isPinned = column.getIsPinned() !== false;
-      const minWidth = column.columnDef.minSize ?? 80;
+      const minWidth = column.columnDef.minSize ?? DEFAULT_COLUMN_MIN_SIZE;
       if (isFixed || isResized || isPinned) {
         return {
           id: column.id,
@@ -1269,6 +1390,31 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
   }
   const layoutFor = (columnId: string) =>
     columnLayout.get(columnId) ?? UNPINNED_LAYOUT;
+  /**
+   * The layout of a cell spanning from `columnId` to the column at
+   * `lastIndex`. A span never leaves its pinned block, so only the sticky
+   * offset and the boundary shadow change: a right-pinned cell sticks at the
+   * offset of the last column it covers, and the cell covering a block's
+   * boundary column carries its shadow.
+   */
+  const spanLayout = (
+    firstIndex: number,
+    lastIndex: number,
+  ): TMDataGridColumnLayout => {
+    const first = layoutFor(orderedColumns[firstIndex]!.id);
+    if (first.pinnedAt === false) return first;
+    const covered = orderedColumns
+      .slice(firstIndex, lastIndex + 1)
+      .map((column) => layoutFor(column.id));
+    return {
+      ...first,
+      offset:
+        first.pinnedAt === "right"
+          ? (covered.at(-1)?.offset ?? first.offset)
+          : first.offset,
+      isBoundary: covered.some((layout) => layout.isBoundary),
+    };
+  };
 
   /**
    * A running resize drag paints itself, straight onto the grid element.
@@ -1332,11 +1478,20 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
   // Pinned rows count as content: with every visible row pinned to an edge,
   // an empty-state message beside them would contradict what is on screen.
   const isEmpty = rows.length === 0 && pinnedRowCount === 0;
-  // Which emptiness this is. The body already subscribes to the whole table
-  // store, so these reads are reactive.
+  // Which emptiness this is. A column filter counts by the rule the pills, the
+  // header indicator and the page reset use, so the grid has one definition
+  // of "active": an envelope counts once `isFilterActive` says so - the
+  // half-typed `{ operator, value: "" }` the filter panel seeds filters
+  // nothing - 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. The body already subscribes to the whole table store, so these
+  // reads are reactive.
   const emptyGlobalFilter = table.store.state.globalFilter;
   const hasActiveFilters =
-    table.store.state.columnFilters.length > 0 ||
+    table.store.state.columnFilters.some(
+      (entry) =>
+        !isTMDataGridFilterValue(entry.value) || isFilterActive(entry.value),
+    ) ||
     (typeof emptyGlobalFilter === "string"
       ? emptyGlobalFilter.trim() !== ""
       : emptyGlobalFilter != null);
@@ -1612,11 +1767,15 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
     findCellElement(container, tabStopCell)?.focus({ preventScroll: true });
   };
 
-  const isCellAt = (
-    position: TMDataGridCellPosition | null,
-    rowId: string,
-    columnId: string,
-  ) => position !== null && position.rowId === rowId && position.columnId === columnId;
+  /**
+   * Whether the focused cell is on this row, in columns `first` to `last` -
+   * one column for most cells, every column it covers for a spanning one.
+   */
+  const isFocusedWithin = (rowId: string, first: number, last: number) =>
+    focusedCell !== null &&
+    focusedCell.rowId === rowId &&
+    focusedColumnIndex >= first &&
+    focusedColumnIndex <= last;
 
   // The rectangle, resolved from ids to the indices the cells are rendered at.
   // `null` whenever a corner has been filtered or hidden away - the range keeps
@@ -1771,7 +1930,9 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
     const row = rows[coords.rowIndex];
     const column = orderedColumns[coords.columnIndex];
     if (!row || !column) return;
-    const cell = { rowId: row.id, columnId: column.id };
+    // A column covered by a span on this row has no cell; the one covering it
+    // takes the focus.
+    const cell = toRenderedCell({ rowId: row.id, columnId: column.id }, row);
     // The state moves; the effect below is what makes the DOM follow, because
     // the element for an off-screen row does not exist yet to be focused.
     wantsCellFocusRef.current = true;
@@ -1911,12 +2072,15 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
       direction: move,
       rowCount: rows.length,
       columnCount: orderedColumns.length,
+      // A column covered by a span on its row has no cell to hold an editor,
+      // and a move onto it would land back on the spanning cell just left.
       isEditable: (coords) => {
         const row = rows[coords.rowIndex];
         const column = orderedColumns[coords.columnIndex];
         return (
           row !== undefined &&
           column !== undefined &&
+          !isCoveredCell(row, coords.columnIndex) &&
           edit.canEditCell(row, column)
         );
       },
@@ -2035,10 +2199,13 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
           const nextCell =
             container === null
               ? null
-              : findCellElement(container, {
-                  rowId: nextRow.id,
-                  columnId: nextColumn.id,
-                });
+              : findCellElement(
+                  container,
+                  toRenderedCell(
+                    { rowId: nextRow.id, columnId: nextColumn.id },
+                    nextRow,
+                  ),
+                );
           if (nextCell !== null) nextCell.focus({ preventScroll: true });
           else target.blur();
           return;
@@ -2175,10 +2342,19 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
       return;
     }
 
+    // Right steps off a spanning cell from the last column it covers, or it
+    // would land back on itself.
+    const spans = rows[rowIndex] ? colSpansOf(rows[rowIndex]) : null;
     const next = resolveCellMove({
       key: event.key,
       ctrlKey: event.ctrlKey || event.metaKey,
-      from: { rowIndex, columnIndex },
+      from: {
+        rowIndex,
+        columnIndex:
+          spans !== null && event.key === "ArrowRight"
+            ? spanEndIndex(spans, columnIndex)
+            : columnIndex,
+      },
       rowCount: rows.length,
       columnCount: orderedColumns.length,
       pageRows: Math.max(
@@ -2192,7 +2368,11 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
     // through at the last row would scroll the body out from under a focus that
     // did not move.
     event.preventDefault();
-    if (next.rowIndex === rowIndex && next.columnIndex === columnIndex) return;
+    // A move landing on this cell again - clamped at an edge, or onto a column
+    // this cell covers - changes nothing, the rectangle included.
+    const landing =
+      spans === null ? next.columnIndex : spanAnchorIndex(spans, next.columnIndex);
+    if (next.rowIndex === rowIndex && landing === columnIndex) return;
     // Shift extends the rectangle instead of collapsing it - the same key that
     // extends a text selection, a file list and a spreadsheet range.
     moveFocusedCell(next, { extend: event.shiftKey && cellRangeSelection });
@@ -2230,6 +2410,23 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
     // never in this grid.
     const activeElement = container.ownerDocument.activeElement;
 
+    // The column the focus sits on has just been covered by a span - the row
+    // expanded under it, say. Its cell is gone, and the browser dropped the
+    // focus with it, so the state follows the cell that now stands for the
+    // column, and the render after this one puts the focus there. A focus
+    // that had moved elsewhere on the page stays there: only the ring moves.
+    const rendered = toRenderedCell(focusedCell, rows[focusedRowIndex]);
+    if (rendered !== focusedCell) {
+      if (
+        activeElement === null ||
+        activeElement === container.ownerDocument.body
+      ) {
+        wantsCellFocusRef.current = true;
+      }
+      ui.actions.setFocusedCell(rendered);
+      return;
+    }
+
     // Never take the focus from elsewhere on the page. A consumer moving the
     // cell while the user is typing in a form somewhere means "move the ring",
     // not "move the caret" - the scroll above already did the visible part.
@@ -2250,7 +2447,7 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
       return;
     }
 
-    const cellElement = findCellElement(container, focusedCell);
+    const cellElement = findCellElement(container, rendered);
     // Still scrolling. The intent stays up, and the next render tries again.
     if (cellElement === null) return;
     wantsCellFocusRef.current = false;
@@ -2641,23 +2838,8 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
                 ...row.getCenterVisibleCells(),
                 ...row.getEndVisibleCells(),
               ];
-              // Row mode opens every editable cell of the row at once, and
-              // rows accumulate: a second row opening leaves the first one
-              // open, so every row holding a form shows its editors. Which of
-              // them holds the caret is not decided here - see
-              // placeEditCaret, which places it once per gesture.
-              //
-              // A parked row is not one of them. It keeps its form, so it is
-              // still "open", but it has been decided: it renders its draft
-              // through the column's own renderer until `begin` reopens it.
-              // A committed entry row in the body has a form too - every
-              // entry row does - but it is a value row until reopened, and
-              // reopening takes it back to the entry block.
-              const rowEditing =
-                features.editMode === "row" &&
-                editOpenRowIdSet.has(row.id) &&
-                !editDraftRowIdSet.has(row.id) &&
-                !newRowIdSet.has(row.id);
+              const rowEditing = isRowEditing(row);
+              const spans = colSpansOf(row);
               // Cell selection takes the body's tab stop off the row and puts
               // it on a cell - two stops per row would make Tab a way of
               // walking the grid, which is what the arrow keys are for. Space
@@ -2835,6 +3017,10 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
                   }
                 >
                   {rowCells.map((cell, cellIndex) => {
+                    // Covered by a spanning cell to its left - see colSpansOf.
+                    if (spans !== null && spans[cellIndex] === 0) return null;
+                    const colSpan = spans?.[cellIndex] ?? 1;
+                    const lastIndex = cellIndex + colSpan - 1;
                     const isEditingCell =
                       (editActive !== null &&
                         editActive.rowId === row.id &&
@@ -2845,7 +3031,12 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
                       key={cell.id}
                       cell={cell}
                       rowHeight={rowHeight}
-                      layout={layoutFor(cell.column.id)}
+                      colSpan={colSpan}
+                      layout={
+                        colSpan > 1
+                          ? spanLayout(cellIndex, lastIndex)
+                          : layoutFor(cell.column.id)
+                      }
                       contentOverride={
                         rowNumberById !== null &&
                         cell.column.id === ROW_NUMBER_COLUMN_ID
@@ -2897,10 +3088,12 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
                           ? {
                               rowId: row.id,
                               columnIndex: cellIndex + 1,
-                              focused: isCellAt(
-                                focusedCell,
+                              // A spanning cell stands for every column it
+                              // covers, wherever the focus was put.
+                              focused: isFocusedWithin(
                                 row.id,
-                                cell.column.id,
+                                cellIndex,
+                                lastIndex,
                               ),
                               // Focusable by click and by the grid, never by
                               // Tab - the guards are the way in. See
@@ -2908,11 +3101,18 @@ export function TMDataGridTable<TData extends RowData = TMDataGridRowData>({
                               tabIndex: -1,
                               // "Selected" means "in the block Ctrl+C would
                               // take" - which under `"single"` is the one cell
-                              // the user is standing on.
+                              // the user is standing on. A spanning cell is in
+                              // it by its first column alone - see
+                              // isWithinBounds.
                               selected: cellRangeSelection
                                 ? isWithinBounds(rangeBounds, viewIndex, cellIndex)
-                                : isCellAt(focusedCell, row.id, cell.column.id),
-                              edges: boundsEdges(rangeBounds, viewIndex, cellIndex),
+                                : isFocusedWithin(row.id, cellIndex, lastIndex),
+                              edges: boundsEdges(
+                                rangeBounds,
+                                viewIndex,
+                                cellIndex,
+                                lastIndex,
+                              ),
                             }
                           : undefined
                       }

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;