@jielga/tmdatagrid 0.3.0 → 0.5.0

package/src/tmdatagrid/core/cellExport.ts

@@ -0,0 +1,321 @@
+import type { Column, Row, RowData } from "@tanstack/react-table";
+import type { TMDataGridRowData } from "../TMDataGridContext";
+import type { TMDataGridFeatures, TMDataGridTable } from "../useTMDataGrid";
+import type { TMDataGridRangeBounds } from "./cellRange";
+import { getColumnLabel, isControlColumn } from "./columnUtils";
+
+/**
+ * The byte order mark Excel looks for before it will read a file as UTF-8.
+ * Built from its code point rather than pasted in: a literal BOM is invisible
+ * in a source file, and an invisible character nobody can see is one somebody
+ * eventually deletes.
+ */
+const UTF8_BOM = String.fromCharCode(0xfeff);
+
+/** The selected block, flattened to text. One inner array per row. */
+export type TMDataGridCellMatrix = Array<Array<string>>;
+
+/**
+ * How values are written out.
+ *
+ * The defaults are the Nordic ones, because they are the ones that need
+ * choosing: an Excel running a Swedish, Norwegian, Danish or Finnish locale
+ * reads `;` as its list separator and `,` as its decimal mark, and a file
+ * written the other way opens as one column of text. Both are settable for a
+ * grid whose users run something else.
+ */
+export type TMDataGridCellExportOptions = {
+  /** CSV field separator. Defaults to `";"`. */
+  separator?: string;
+  /** Write numbers as `1,5` rather than `1.5`. Defaults to `true`. */
+  decimalComma?: boolean;
+  /** Column labels as the first row. Defaults to `true`. */
+  includeHeaders?: boolean;
+  /** Without extension. Defaults to `"export"`. */
+  fileName?: string;
+};
+
+type ResolvedExportOptions = Required<TMDataGridCellExportOptions>;
+
+export const DEFAULT_CELL_EXPORT_OPTIONS: ResolvedExportOptions = {
+  separator: ";",
+  decimalComma: true,
+  includeHeaders: true,
+  fileName: "export",
+};
+
+/**
+ * One value as text.
+ *
+ * Deliberately not the rendered cell: what a cell renders is React, and often a
+ * badge, a link or an icon rather than the value. The value is what a
+ * spreadsheet wants, and it is the one thing every column is guaranteed to
+ * have.
+ */
+export function formatExportValue(
+  value: unknown,
+  { decimalComma }: { decimalComma: boolean },
+): string {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) return "";
+    const text = String(value);
+    return decimalComma ? text.replace(".", ",") : text;
+  }
+  if (typeof value === "string") return value;
+  if (typeof value === "boolean") return value ? "true" : "false";
+  // A multiSelect cell holds an array of values; a spreadsheet cell holds one
+  // string, so the elements are joined the way they read on screen.
+  if (Array.isArray(value)) {
+    return value
+      .map((entry) => formatExportValue(entry, { decimalComma }))
+      .join(", ");
+  }
+  // `sv-SE` is ISO-shaped — 2026-07-31, 2026-07-31 14:05:00 — which is both the
+  // Nordic form and the one Excel parses as a date rather than as text.
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? "" : value.toLocaleString("sv-SE");
+  }
+  // An object in a cell is a shape the grid cannot know. JSON at least keeps
+  // what was there, where `String(value)` would write "[object Object]".
+  if (typeof value === "object") {
+    try {
+      return JSON.stringify(value);
+    } catch {
+      return "";
+    }
+  }
+  return String(value);
+}
+
+export type BuildCellMatrixArgs = {
+  rows: ReadonlyArray<Row<TMDataGridFeatures, TMDataGridRowData>>;
+  /** Every visible column, in render order — the same list the bounds index into. */
+  columns: ReadonlyArray<Column<TMDataGridFeatures, TMDataGridRowData, unknown>>;
+  bounds: TMDataGridRangeBounds;
+  includeHeaders: boolean;
+  decimalComma: boolean;
+};
+
+/**
+ * The selected rectangle as rows of text.
+ *
+ * The generated lanes — the checkbox, the tree chevron, the details chevron —
+ * are dropped even when the rectangle covers them. They hold controls rather
+ * than data, so a column of empty strings is all they could contribute, and
+ * pasting one into a spreadsheet only shifts everything to its right.
+ */
+export function buildCellMatrix({
+  rows,
+  columns,
+  bounds,
+  includeHeaders,
+  decimalComma,
+}: BuildCellMatrixArgs): TMDataGridCellMatrix {
+  const selectedColumns = columns
+    .slice(bounds.left, bounds.right + 1)
+    .filter((column) => !isControlColumn(column.id));
+  if (selectedColumns.length === 0) return [];
+
+  const matrix: TMDataGridCellMatrix = [];
+  if (includeHeaders) {
+    matrix.push(selectedColumns.map((column) => getColumnLabel(column)));
+  }
+
+  for (let index = bounds.top; index <= bounds.bottom; index += 1) {
+    const row = rows[index];
+    if (row === undefined) continue;
+    matrix.push(
+      selectedColumns.map((column) =>
+        formatExportValue(row.getValue(column.id), { decimalComma }),
+      ),
+    );
+  }
+  return matrix;
+}
+
+/**
+ * The whole grid as rows of text: every filtered and sorted data row — all
+ * pages, not the one on screen — by every visible non-control column, in
+ * render order.
+ *
+ * The values are the same ones a cell-range export writes; only the bounds
+ * differ. Group rows are left out (their records are the rows themselves),
+ * and hidden columns are not exported — what you see is what you get, minus
+ * paging.
+ */
+export function buildGridCellMatrix<TData extends RowData>({
+  table,
+  includeHeaders = DEFAULT_CELL_EXPORT_OPTIONS.includeHeaders,
+  decimalComma = DEFAULT_CELL_EXPORT_OPTIONS.decimalComma,
+}: {
+  table: TMDataGridTable<TData>;
+  includeHeaders?: boolean;
+  decimalComma?: boolean;
+}): TMDataGridCellMatrix {
+  // The same erasure the context provider performs: the matrix only ever reads
+  // generic row and column APIs.
+  const erased = table as unknown as TMDataGridTable<TMDataGridRowData>;
+  const columns = [
+    ...erased.getLeftVisibleLeafColumns(),
+    ...erased.getCenterVisibleLeafColumns(),
+    ...erased.getRightVisibleLeafColumns(),
+  ];
+  // The sorted model: after filtering, grouping and sorting, before expansion
+  // and paging — so a paged grid exports the whole filtered set, and a grouped
+  // grid exports the records under every group whether or not it is open.
+  //
+  // Walked by hand rather than taken from `flatRows`: in table-core
+  // 9.0.0-beta.21 the grouped model lists every leaf twice there (once as a
+  // leaf row, once re-parented under its group), and its order puts the
+  // groups last. Depth-first over `rows` is exactly render order, once each.
+  const rows: Array<Row<TMDataGridFeatures, TMDataGridRowData>> = [];
+  const walk = (
+    list: ReadonlyArray<Row<TMDataGridFeatures, TMDataGridRowData>>,
+  ) => {
+    for (const row of list) {
+      if (row.getIsGrouped()) walk(row.subRows);
+      else rows.push(row);
+    }
+  };
+  walk(erased.getSortedRowModel().rows);
+
+  return buildCellMatrix({
+    rows,
+    columns,
+    bounds: {
+      top: 0,
+      bottom: rows.length - 1,
+      left: 0,
+      right: columns.length - 1,
+    },
+    includeHeaders,
+    decimalComma,
+  });
+}
+
+/**
+ * Downloads the whole grid as a CSV for Excel — {@link buildGridCellMatrix}
+ * through {@link toExcelCsv}, with the same Nordic defaults and overrides as
+ * the cell-range export.
+ *
+ * No built-in button: wire it to your own toolbar.
+ *
+ * ```tsx
+ * <Button onClick={() => exportGridToCsv({ table: grid.table })}>Export</Button>
+ * ```
+ */
+export function exportGridToCsv<TData extends RowData>({
+  table,
+  options,
+}: {
+  table: TMDataGridTable<TData>;
+  options?: TMDataGridCellExportOptions;
+}): void {
+  const resolved = { ...DEFAULT_CELL_EXPORT_OPTIONS, ...options };
+  const matrix = buildGridCellMatrix({
+    table,
+    includeHeaders: resolved.includeHeaders,
+    decimalComma: resolved.decimalComma,
+  });
+  if (matrix.length === 0) return;
+  downloadTextFile({
+    fileName: `${resolved.fileName}.csv`,
+    text: toExcelCsv(matrix, { separator: resolved.separator }),
+  });
+}
+
+/**
+ * Quotes a field when it holds something that would otherwise end it early.
+ * Doubling the quote is how both CSV and Excel's own clipboard format escape
+ * one, so the same rule serves both.
+ */
+function escapeField(value: string, separator: string): string {
+  const needsQuotes =
+    value.includes(separator) ||
+    value.includes('"') ||
+    value.includes("\n") ||
+    value.includes("\r");
+  return needsQuotes ? `"${value.replaceAll('"', '""')}"` : value;
+}
+
+/**
+ * The clipboard format spreadsheets read: tab between cells, CRLF between rows.
+ *
+ * Tabs rather than commas because that is what Excel, Sheets and Numbers all
+ * put on the clipboard themselves — paste it and the cells land in cells. A
+ * comma-separated string pastes into a single column, which is the thing this
+ * exists to avoid.
+ */
+export function toClipboardText(matrix: TMDataGridCellMatrix): string {
+  return matrix
+    .map((row) => row.map((value) => escapeField(value, "\t")).join("\t"))
+    .join("\r\n");
+}
+
+/**
+ * A CSV that opens straight into columns in Excel.
+ *
+ * Three things make that true, and all three are needed:
+ *
+ * | Part | Why |
+ * | ---- | --- |
+ * | `sep=;` first line | Excel's own directive — it stops guessing and uses this |
+ * | UTF-8 BOM | without it Excel reads the file as ANSI, and å ä ö arrive broken |
+ * | CRLF line endings | what Excel writes, and what its importer is happiest with |
+ *
+ * The `sep=` line is Excel's alone; other readers show it as a first row. That
+ * is the trade this makes — the file is for Excel, and "it just opens" is worth
+ * more than being a well-behaved CSV nobody was going to feed to a parser.
+ */
+export function toExcelCsv(
+  matrix: TMDataGridCellMatrix,
+  { separator }: { separator: string },
+): string {
+  const body = matrix
+    .map((row) => row.map((value) => escapeField(value, separator)).join(separator))
+    .join("\r\n");
+  return `${UTF8_BOM}sep=${separator}\r\n${body}\r\n`;
+}
+
+/**
+ * Puts text on the clipboard, reporting whether it landed.
+ *
+ * The async clipboard API only resolves for a document that has the focus and a
+ * user gesture behind it — both true when this runs off Ctrl+C or a menu item.
+ * It is still allowed to reject (a permissions policy, a page that lost focus
+ * mid-copy), so the result is a boolean rather than a promise nobody checks.
+ */
+export async function writeClipboardText(text: string): Promise<boolean> {
+  try {
+    await navigator.clipboard.writeText(text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Downloads text as a file, through the one mechanism a library can use: an
+ * anchor with an object URL behind it, clicked. Revoked on the next frame —
+ * immediately would race the browser's own read of it.
+ */
+export function downloadTextFile({
+  fileName,
+  text,
+  mimeType = "text/csv;charset=utf-8",
+}: {
+  fileName: string;
+  text: string;
+  mimeType?: string;
+}): void {
+  const url = URL.createObjectURL(new Blob([text], { type: mimeType }));
+  const anchor = document.createElement("a");
+  anchor.href = url;
+  anchor.download = fileName;
+  anchor.style.display = "none";
+  document.body.append(anchor);
+  anchor.click();
+  anchor.remove();
+  setTimeout(() => URL.revokeObjectURL(url), 0);
+}

package/src/tmdatagrid/core/cellNavigation.ts

@@ -0,0 +1,103 @@
+/**
+ * Which cell has the focus, by id rather than by position.
+ *
+ * Ids, because every other thing the grid does moves cells around: sorting
+ * reorders rows, filtering removes them, dragging a header reorders columns. A
+ * coordinate pair would silently come to mean a different cell after any of
+ * them, while a pair of ids either still resolves or does not resolve at all —
+ * and "does not resolve" is a state the grid can handle honestly.
+ *
+ * Indices are what navigation is actually computed in, so they are resolved
+ * from the ids on each keystroke and turned straight back. See resolveCellMove.
+ */
+export type TMDataGridCellPosition = {
+  rowId: string;
+  columnId: string;
+};
+
+/** Where the focused cell sits in the rows and columns on screen. */
+export type TMDataGridCellCoords = {
+  rowIndex: number;
+  columnIndex: number;
+};
+
+export type ResolveCellMoveArgs = {
+  /** `KeyboardEvent.key`. */
+  key: string;
+  /** Ctrl or Cmd — Home and End jump to the corner rather than the row end. */
+  ctrlKey: boolean;
+  from: TMDataGridCellCoords;
+  rowCount: number;
+  columnCount: number;
+  /**
+   * How far PageUp and PageDown travel: one viewport of rows. Passed in rather
+   * than assumed, since only the body knows how tall it is.
+   */
+  pageRows: number;
+};
+
+const clamp = (value: number, max: number) =>
+  Math.min(Math.max(value, 0), Math.max(max, 0));
+
+/**
+ * The next cell for a navigation key, or `null` when the key is not one.
+ *
+ * Moves clamp at the edges instead of wrapping. Wrapping suits a menu, where
+ * the items are a short ring; a grid is a coordinate space, and a Right at the
+ * last column that lands on the first column of the next row loses the one
+ * thing arrow keys are for — knowing where you will end up without looking.
+ *
+ * A clamped move returns the position it started from rather than `null`. The
+ * caller still needs to know the key was handled: an arrow at the last row must
+ * not fall through to the scroll container, which would scroll the body out
+ * from under a focus that did not move.
+ */
+export function resolveCellMove({
+  key,
+  ctrlKey,
+  from,
+  rowCount,
+  columnCount,
+  pageRows,
+}: ResolveCellMoveArgs): TMDataGridCellCoords | null {
+  if (rowCount === 0 || columnCount === 0) return null;
+
+  const lastRow = rowCount - 1;
+  const lastColumn = columnCount - 1;
+  const at = (rowIndex: number, columnIndex: number): TMDataGridCellCoords => ({
+    rowIndex: clamp(rowIndex, lastRow),
+    columnIndex: clamp(columnIndex, lastColumn),
+  });
+
+  switch (key) {
+    case "ArrowDown":
+      return at(from.rowIndex + 1, from.columnIndex);
+    case "ArrowUp":
+      return at(from.rowIndex - 1, from.columnIndex);
+    case "ArrowRight":
+      return at(from.rowIndex, from.columnIndex + 1);
+    case "ArrowLeft":
+      return at(from.rowIndex, from.columnIndex - 1);
+    case "PageDown":
+      return at(from.rowIndex + Math.max(pageRows, 1), from.columnIndex);
+    case "PageUp":
+      return at(from.rowIndex - Math.max(pageRows, 1), from.columnIndex);
+    // Ctrl+Home / Ctrl+End address the grid, plain Home / End the row — the
+    // convention every spreadsheet and APG's own grid pattern share.
+    case "Home":
+      return ctrlKey ? at(0, 0) : at(from.rowIndex, 0);
+    case "End":
+      return ctrlKey ? at(lastRow, lastColumn) : at(from.rowIndex, lastColumn);
+    default:
+      return null;
+  }
+}
+
+/** Whether two positions address the same cell. `null` equals only `null`. */
+export function isSameCell(
+  a: TMDataGridCellPosition | null,
+  b: TMDataGridCellPosition | null,
+): boolean {
+  if (a === null || b === null) return a === b;
+  return a.rowId === b.rowId && a.columnId === b.columnId;
+}

package/src/tmdatagrid/core/cellRange.ts

@@ -0,0 +1,118 @@
+import type { TMDataGridCellPosition } from "./cellNavigation";
+
+/**
+ * A selected rectangle of cells, held as the two cells that span it.
+ *
+ * Two corners rather than a list of cells, because a range is a gesture, not a
+ * set: dragging over 40 columns of a 100k-row grid would otherwise build — and
+ * rebuild, on every mouse move — a list with millions of entries in it. Two
+ * positions describe the same thing and cost nothing to extend.
+ *
+ * `anchor` is where the gesture started and stays put; `focus` is the end that
+ * moves. Which of the two is top-left depends on the direction it was dragged,
+ * so nothing here assumes an order — see {@link resolveRangeBounds}.
+ */
+export type TMDataGridCellRange = {
+  anchor: TMDataGridCellPosition;
+  focus: TMDataGridCellPosition;
+};
+
+/** The rectangle a range covers, in row and column indices, both ends included. */
+export type TMDataGridRangeBounds = {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+};
+
+export type ResolveRangeBoundsArgs = {
+  range: TMDataGridCellRange | null;
+  /** Index of a row id among the rows on screen, or `-1`. */
+  rowIndexOf: (rowId: string) => number;
+  columnIndexOf: (columnId: string) => number;
+};
+
+/**
+ * Turns a range into the rectangle to paint and copy, or `null` when either
+ * corner no longer exists.
+ *
+ * A corner goes missing whenever a filter drops its row or a column is hidden,
+ * and the honest answer then is that there is no rectangle — better than
+ * guessing at a replacement corner and quietly copying cells the user never
+ * selected. The range itself is left alone: clearing it here would throw away
+ * a selection that comes straight back when the filter is lifted.
+ */
+export function resolveRangeBounds({
+  range,
+  rowIndexOf,
+  columnIndexOf,
+}: ResolveRangeBoundsArgs): TMDataGridRangeBounds | null {
+  if (range === null) return null;
+
+  const anchorRow = rowIndexOf(range.anchor.rowId);
+  const focusRow = rowIndexOf(range.focus.rowId);
+  const anchorColumn = columnIndexOf(range.anchor.columnId);
+  const focusColumn = columnIndexOf(range.focus.columnId);
+  if (
+    anchorRow < 0 ||
+    focusRow < 0 ||
+    anchorColumn < 0 ||
+    focusColumn < 0
+  ) {
+    return null;
+  }
+
+  return {
+    top: Math.min(anchorRow, focusRow),
+    bottom: Math.max(anchorRow, focusRow),
+    left: Math.min(anchorColumn, focusColumn),
+    right: Math.max(anchorColumn, focusColumn),
+  };
+}
+
+/** Whether a cell is inside the rectangle. */
+export function isWithinBounds(
+  bounds: TMDataGridRangeBounds | null,
+  rowIndex: number,
+  columnIndex: number,
+): boolean {
+  if (bounds === null) return false;
+  return (
+    rowIndex >= bounds.top &&
+    rowIndex <= bounds.bottom &&
+    columnIndex >= bounds.left &&
+    columnIndex <= bounds.right
+  );
+}
+
+/** How many cells the rectangle covers. `0` for no range at all. */
+export function boundsCellCount(bounds: TMDataGridRangeBounds | null): number {
+  if (bounds === null) return 0;
+  return (
+    (bounds.bottom - bounds.top + 1) * (bounds.right - bounds.left + 1)
+  );
+}
+
+/**
+ * Which edges of the rectangle a cell sits on, for the outline.
+ *
+ * The border is drawn per cell rather than as one box over the top, because the
+ * body is a scrolling CSS grid with sticky columns in it: an overlay would have
+ * to be positioned against a moving target and would still be wrong the moment
+ * a pinned lane slid over it. Four booleans per cell need no positioning at all.
+ */
+export function boundsEdges(
+  bounds: TMDataGridRangeBounds | null,
+  rowIndex: number,
+  columnIndex: number,
+): { top: boolean; bottom: boolean; left: boolean; right: boolean } | null {
+  if (!isWithinBounds(bounds, rowIndex, columnIndex) || bounds === null) {
+    return null;
+  }
+  return {
+    top: rowIndex === bounds.top,
+    bottom: rowIndex === bounds.bottom,
+    left: columnIndex === bounds.left,
+    right: columnIndex === bounds.right,
+  };
+}

package/src/tmdatagrid/core/columnOptions.ts

@@ -0,0 +1,123 @@
+import type { Column, Row } from "@tanstack/react-table";
+import type { TMDataGridRowData } from "../TMDataGridContext";
+import type { TMDataGridFeatures, TMDataGridTable } from "../useTMDataGrid";
+
+/**
+ * One choice of a `select` / `multiSelect` column. A bare string in any options
+ * list is shorthand for `{ value }`.
+ */
+export type TMDataGridOption = {
+  value: string;
+  /** Shown in dropdowns. Defaults to the value itself. */
+  label?: string;
+  /** Mantine colour for the value's badge, where a cell renders one. */
+  color?: string;
+  disabled?: boolean;
+  /** Dropdown group heading. Ungrouped options render first. */
+  group?: string;
+};
+
+export type TMDataGridOptionsArgs = {
+  table: TMDataGridTable<TMDataGridRowData>;
+  column: Column<TMDataGridFeatures, TMDataGridRowData, unknown>;
+  /** The row an editor is standing on. Absent when the filter panel asks. */
+  row?: Row<TMDataGridFeatures, TMDataGridRowData>;
+  /**
+   * Source to use when the column declares none. The filter panel passes
+   * `"faceted"` so a select column with no `meta.options` still offers the
+   * values that exist, rather than an empty dropdown.
+   */
+  fallback?: TMDataGridOptionsSource;
+};
+
+/**
+ * Where a column's options come from — `meta.options`. One declaration feeds
+ * both the filter panel's value control and the cell editor.
+ *
+ * | Form | For |
+ * | --- | --- |
+ * | array | a known, fixed set |
+ * | `"faceted"` | low-cardinality data columns: the distinct values present, via `getFacetedUniqueValues` |
+ * | function | large or contextual sets — `row` is set when an editor asks, so options can depend on the record (city given country) |
+ */
+export type TMDataGridOptionsSource =
+  | ReadonlyArray<TMDataGridOption | string>
+  | "faceted"
+  | ((args: TMDataGridOptionsArgs) => ReadonlyArray<TMDataGridOption | string>);
+
+function addFacetValue(target: Set<string>, value: unknown): void {
+  if (value === null || value === undefined || value === "") return;
+  target.add(String(value));
+}
+
+/**
+ * A column's options as a normalised list, whatever form `meta.options` took.
+ * Empty for a column that declares none.
+ *
+ * `"faceted"` reads the distinct values actually present in the data. A
+ * multiSelect cell holds an array, so array values contribute their elements
+ * rather than the array itself.
+ */
+export function resolveColumnOptions({
+  table,
+  column,
+  row,
+  fallback,
+}: TMDataGridOptionsArgs): Array<TMDataGridOption> {
+  const source = column.columnDef.meta?.options ?? fallback;
+  if (!source) return [];
+
+  if (source === "faceted") {
+    const values = new Set<string>();
+    for (const key of column.getFacetedUniqueValues().keys()) {
+      if (Array.isArray(key)) {
+        for (const entry of key) addFacetValue(values, entry);
+      } else {
+        addFacetValue(values, key);
+      }
+    }
+    return [...values]
+      .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
+      .map((value) => ({ value }));
+  }
+
+  const list = typeof source === "function" ? source({ table, column, row }) : source;
+  return list.map((option) =>
+    typeof option === "string" ? { value: option } : option,
+  );
+}
+
+type ComboboxItem = { value: string; label: string; disabled?: boolean };
+type ComboboxData = Array<ComboboxItem | { group: string; items: ComboboxItem[] }>;
+
+/**
+ * The same list in the shape Mantine's `Select` / `MultiSelect` take, with
+ * `group` fields folded into Mantine's group entries. Ungrouped options come
+ * first, then the groups in first-appearance order.
+ */
+export function optionsToComboboxData(
+  options: ReadonlyArray<TMDataGridOption>,
+): ComboboxData {
+  const ungrouped: ComboboxItem[] = [];
+  const groups = new Map<string, ComboboxItem[]>();
+
+  for (const option of options) {
+    const item: ComboboxItem = {
+      value: option.value,
+      label: option.label ?? option.value,
+      ...(option.disabled ? { disabled: true } : {}),
+    };
+    if (option.group === undefined) {
+      ungrouped.push(item);
+    } else {
+      const bucket = groups.get(option.group);
+      if (bucket) bucket.push(item);
+      else groups.set(option.group, [item]);
+    }
+  }
+
+  return [
+    ...ungrouped,
+    ...[...groups].map(([group, items]) => ({ group, items })),
+  ];
+}

package/src/tmdatagrid/core/columnUtils.ts

@@ -1,4 +1,6 @@
 import type { TMDataGridColumnType } from "./filterOperators";
+import { DETAILS_COLUMN_ID } from "../components/TMDataGridDetailsColumn";
+import { SELECT_COLUMN_ID } from "../components/TMDataGridSelectColumn";
 import type { TMDataGridColumnMeta } from "../useTMDataGrid";
 
 /**
@@ -29,6 +31,22 @@ export function getColumnAlign(column: ColumnLike): "left" | "right" | "center"
   return column.columnDef.meta?.align ?? "left";
 }
 
+/**
+ * A generated lane holding one control at a fixed width — the checkbox and the
+ * details chevron.
+ *
+ * They are laid out differently from every other column: cell padding is sized
+ * for text and grows with the scale, which at `xl` squeezed a 16px checkbox out
+ * of its track, so these lanes centre their control in an unpadded cell.
+ * Their headers are controls too, and carry no column menu.
+ *
+ * The tree column is deliberately not one of them: it holds a label as well as a
+ * chevron, and wants the padding.
+ */
+export function isControlColumn(columnId: string): boolean {
+  return columnId === SELECT_COLUMN_ID || columnId === DETAILS_COLUMN_ID;
+}
+
 /**
  * Whether a column may be moved. Ordering is the one column feature TanStack
  * has no column option for, so the switch lives in `meta.enableOrdering`.