@jielga/tmdatagrid 0.5.0 → 1.0.0

package/src/tmdatagrid/components/TMDataGridEntryRows.tsx

@@ -0,0 +1,164 @@
+import {
+  flexRender,
+  useTable,
+  type Column,
+  type Row,
+} from "@tanstack/react-table";
+import { useSelector } from "@tanstack/react-store";
+import { useMemo } from "react";
+import classes from "./TMDataGridTable.module.css";
+import sticky from "./sticky.module.css";
+import { type TMDataGridRowData, useTMDataGridContext } from "../TMDataGridContext";
+import { getColumnAlign, isControlColumn } from "../core/columnUtils";
+import { getEditFieldName } from "../core/editEngine";
+import {
+  tmDataGridFeatures,
+  type TMDataGridFeatures,
+} from "../useTMDataGrid";
+import { TMDataGridCellEditor } from "./TMDataGridCellEditor";
+import { EDIT_COLUMN_ID } from "./TMDataGridEditColumn";
+import type { TMDataGridColumnLayout } from "./TMDataGridTable";
+
+type ErasedColumn = Column<TMDataGridFeatures, TMDataGridRowData, unknown>;
+
+/**
+ * Whether an entry cell edits. `edit.canEditCell` asks the main table for
+ * the row, and an entry row is precisely not there yet — so the structural
+ * half of the same rule is applied to the entry table's own row.
+ */
+function isEntryCellEditable(
+  row: Row<TMDataGridFeatures, TMDataGridRowData>,
+  column: ErasedColumn,
+): boolean {
+  if (isControlColumn(column.id)) return false;
+  if (getEditFieldName(column) === null) return false;
+  const editable = column.columnDef.meta?.editable;
+  if (editable === false) return false;
+  if (typeof editable === "function" && !editable(row)) return false;
+  return true;
+}
+
+/**
+ * The sticky entry block — one row of open editors per `edit.addRow()`,
+ * pinned under the header. The one place stickiness is genuinely required:
+ * an existing row that scrolls away has a place to scroll back to, a row
+ * being typed into does not exist anywhere else.
+ *
+ * A second, tiny table instance over the new rows' seed values — same
+ * columns, its own `useTable`, no sorting or filtering ever exercised — so
+ * these are real `Cell`s and the editor host, the typed editors and the
+ * validators all apply unchanged. The forms live in the same engine map as
+ * every other draft, keyed by their temporary ids.
+ *
+ * Enter commits the entry (`onRowAdd`) under the immediate modes and parks
+ * it under batch, where `submitAll` reports it in `added`; Escape discards
+ * it. The edit lane, when present, offers the same pair as buttons.
+ */
+export function TMDataGridEntryRows({
+  orderedColumns,
+  layoutFor,
+  rowHeight,
+}: {
+  orderedColumns: ReadonlyArray<ErasedColumn>;
+  layoutFor: (columnId: string) => TMDataGridColumnLayout;
+  rowHeight: number;
+}) {
+  const { table, edit } = useTMDataGridContext();
+  const newRows = useSelector(edit.store, (state) => state.newRows);
+
+  // The seed values, frozen at addRow: the live values belong to the forms,
+  // which the editors read directly — this table only provides row and cell
+  // identity.
+  const data = useMemo(
+    () =>
+      newRows.map(
+        ({ tempId }) =>
+          (edit.getForm(tempId)?.options.defaultValues ??
+            {}) as TMDataGridRowData,
+      ),
+    [newRows, edit],
+  );
+
+  const entryTable = useTable({
+    features: tmDataGridFeatures,
+    columns: table.options.columns,
+    data,
+    getRowId: (_row, index) => newRows[index]?.tempId ?? String(index),
+  });
+
+  if (newRows.length === 0) return null;
+
+  const entryRows = entryTable.getCoreRowModel().rows;
+
+  return (
+    <div role="rowgroup" data-dg-entry-block className={classes.entryBlock}>
+      {entryRows.map((entryRow) => {
+        const cellsById = new Map(
+          entryRow.getAllCells().map((cell) => [cell.column.id, cell]),
+        );
+        const firstEditableColumnId = orderedColumns.find((column) =>
+          isEntryCellEditable(entryRow, column),
+        )?.id;
+        return (
+          <div
+            key={entryRow.id}
+            role="row"
+            data-dg-part="entry-row"
+            data-row-id={entryRow.id}
+            className={classes.entryRow}
+          >
+            {orderedColumns.map((column) => {
+              const cell = cellsById.get(column.id);
+              const layout = layoutFor(column.id);
+              const editable =
+                cell !== undefined && isEntryCellEditable(entryRow, column);
+              return (
+                <div
+                  key={column.id}
+                  role="cell"
+                  data-column-id={column.id}
+                  data-align={getColumnAlign(column)}
+                  data-control-column={isControlColumn(column.id)}
+                  className={[
+                    classes.entryCell,
+                    layout.isBoundary && layout.pinnedAt === "left"
+                      ? sticky.stickyLeft
+                      : "",
+                    layout.isBoundary && layout.pinnedAt === "right"
+                      ? sticky.stickyRight
+                      : "",
+                  ]
+                    .filter(Boolean)
+                    .join(" ")}
+                  style={{
+                    minHeight: rowHeight,
+                    left: layout.pinnedAt === "left" ? layout.offset : undefined,
+                    right:
+                      layout.pinnedAt === "right" ? layout.offset : undefined,
+                    position: layout.pinnedAt ? "sticky" : undefined,
+                    zIndex: layout.pinnedAt
+                      ? "var(--dg-z-pinned-row-pinned-cell, 5)"
+                      : undefined,
+                  }}
+                >
+                  {editable && cell !== undefined ? (
+                    <TMDataGridCellEditor
+                      cell={cell}
+                      row={entryRow}
+                      takeSeedText={() => undefined}
+                      autoFocus={column.id === firstEditableColumnId}
+                      onClose={() => {}}
+                    />
+                  ) : cell !== undefined && column.id === EDIT_COLUMN_ID ? (
+                    // The lane's cell — the entry row's ✓/✕ pair.
+                    flexRender(cell.column.columnDef.cell, cell.getContext())
+                  ) : null}
+                </div>
+              );
+            })}
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/src/tmdatagrid/components/TMDataGridFilterPanel.tsx

@@ -1,7 +1,6 @@
 import {
   ActionIcon,
   Button,
-  MultiSelect,
   Select,
   Stack,
   Text,
@@ -11,21 +10,25 @@ import { useSelector } from "@tanstack/react-store";
 import { useEffect, useRef } from "react";
 import classes from "./TMDataGridFilterPanel.module.css";
 import { useTMDataGridContext } from "../TMDataGridContext";
+import { resolveColumnOptions } from "../core/columnOptions";
 import {
-  optionsToComboboxData,
-  resolveColumnOptions,
-} from "../core/columnOptions";
-import { getColumnLabel, getColumnType } from "../core/columnUtils";
+  getColumnDefaultOperator,
+  getColumnLabel,
+  getColumnType,
+} from "../core/columnUtils";
 import {
   type TMDataGridFilterOperator,
   type TMDataGridFilterValue,
+  emptyValueForOperator,
   getDefaultOperator,
   getOperatorsForType,
   isTMDataGridFilterValue,
   operatorNeedsValue,
   operatorTakesArrayValue,
+  operatorTakesRangeValue,
 } from "../core/filterOperators";
 import { CloseIcon } from "./icons";
+import { TMDataGridFilterValueInput } from "./filters/TMDataGridFilterValueInput";
 
 const FALLBACK_FILTER: TMDataGridFilterValue = { operator: "contains", value: "" };
 
@@ -33,6 +36,19 @@ function asFilterValue(value: unknown): TMDataGridFilterValue {
   return isTMDataGridFilterValue(value) ? value : FALLBACK_FILTER;
 }
 
+/**
+ * The three value shapes an operator can take. A typed value survives an
+ * operator or column change only within its shape — a set is not a range,
+ * even though both are arrays.
+ */
+function valueShape(
+  operator: TMDataGridFilterOperator,
+): "scalar" | "set" | "range" {
+  if (operatorTakesArrayValue(operator)) return "set";
+  if (operatorTakesRangeValue(operator)) return "range";
+  return "scalar";
+}
+
 /**
  * The MUI-style filter surface: one row per active column filter, each row a
  * column / operator / value triple. It only ever reads and writes the table's
@@ -60,7 +76,7 @@ export function TMDataGridFilterPanel() {
       if (panelRef.current?.contains(target)) return;
       // The toolbar button toggles the panel itself. Closing from here first
       // would leave its click reopening what the user meant to close.
-      if (target.closest("[data-dg-filter-toggle]")) return;
+      if (target.closest('[data-dg-part="filter-button"]')) return;
       ui.actions.closeFilterPanel();
     };
 
@@ -90,18 +106,16 @@ export function TMDataGridFilterPanel() {
       columnFilters.find((filter) => filter.id === fromColumnId)?.value,
     );
     const target = table.getColumn(toColumnId);
-    const operator = getDefaultOperator(
-      target ? getColumnType(target) : "string",
-    );
+    const operator = target
+      ? getColumnDefaultOperator(target)
+      : getDefaultOperator("string");
     // The typed value only survives the move while it still fits the new
     // operator — a text needle has no meaning to an `isAnyOf` set, or a set
     // to a text input.
     const value =
-      operatorTakesArrayValue(operator) === Array.isArray(current.value)
+      valueShape(operator) === valueShape(current.operator)
         ? current.value
-        : operatorTakesArrayValue(operator)
-          ? []
-          : "";
+        : emptyValueForOperator(operator);
     table.setColumnFilters(
       columnFilters
         .filter((filter) => filter.id !== toColumnId)
@@ -132,13 +146,11 @@ export function TMDataGridFilterPanel() {
       columnFilters.find((filter) => filter.id === columnId)?.value,
     );
     // Same arity rule as changing the column: keep the value across operators
-    // of the same shape, reset it across the array/scalar boundary.
+    // of the same shape, reset it across any shape boundary.
     const value =
-      operatorTakesArrayValue(operator) === Array.isArray(current.value)
+      valueShape(operator) === valueShape(current.operator)
         ? current.value
-        : operatorTakesArrayValue(operator)
-          ? []
-          : "";
+        : emptyValueForOperator(operator);
     patchFilter(columnId, { operator, value });
   }
 
@@ -155,13 +167,14 @@ export function TMDataGridFilterPanel() {
       (column) => !columnFilters.some((filter) => filter.id === column.id),
     );
     if (!nextColumn) return;
+    const operator = getColumnDefaultOperator(nextColumn);
     table.setColumnFilters([
       ...columnFilters,
       {
         id: nextColumn.id,
         value: {
-          operator: getDefaultOperator(getColumnType(nextColumn)),
-          value: "",
+          operator,
+          value: emptyValueForOperator(operator),
         } satisfies TMDataGridFilterValue,
       },
     ]);
@@ -176,6 +189,7 @@ export function TMDataGridFilterPanel() {
       ref={panelRef}
       role="group"
       aria-label={labels.filters}
+      data-dg-part="filter-panel"
       className={classes.filterPanel}
       // Escape is what closes a floating surface, and every control that can
       // hold focus in here sits inside this element.
@@ -194,6 +208,7 @@ export function TMDataGridFilterPanel() {
           color="gray"
           size="sm"
           aria-label={labels.closeFilters}
+          data-dg-part="filter-panel-close"
           onClick={ui.actions.closeFilterPanel}
         >
           <CloseIcon size={16} stroke={1.6} />
@@ -206,16 +221,38 @@ export function TMDataGridFilterPanel() {
           const value = asFilterValue(filter.value);
           const type = column ? getColumnType(column) : "string";
           const needsValue = operatorNeedsValue(value.operator);
-          const takesArray = operatorTakesArrayValue(value.operator);
           const scalarValue = typeof value.value === "string" ? value.value : "";
+          // Pre-resolved only where options mean something out of the box —
+          // a declared set, or a select-shaped column's faceted values. A
+          // custom control wanting faceted values elsewhere resolves them
+          // itself; resolving here would build the faceted index for every
+          // filtered column.
+          const options =
+            column &&
+            (column.columnDef.meta?.options !== undefined ||
+              type === "select" ||
+              type === "multiSelect")
+              ? resolveColumnOptions({ table, column, fallback: "faceted" })
+              : [];
+          const ValueControl =
+            column?.columnDef.meta?.filterControl ?? TMDataGridFilterValueInput;
 
           return (
-            <div key={filter.id} className={classes.filterRow}>
+            <div
+              key={filter.id}
+              // The row is the handle: a `meta.filterControl` renders whatever
+              // it likes in the value slot, so the one thing a test can always
+              // count on is which row it is in.
+              data-dg-part="filter-row"
+              data-column-id={filter.id}
+              className={classes.filterRow}
+            >
               <ActionIcon
                 variant="subtle"
                 color="gray"
                 size="lg"
                 aria-label={labels.removeFilter}
+                data-dg-part="filter-remove"
                 onClick={() => removeFilter(filter.id)}
               >
                 <CloseIcon size={18} stroke={1.6} />
@@ -230,6 +267,7 @@ export function TMDataGridFilterPanel() {
                 // outside it in the DOM, and picking an option would read as a
                 // click away and close the panel under the user.
                 comboboxProps={{ withinPortal: false }}
+                data-dg-part="filter-column"
                 data={columnOptions}
                 value={filter.id}
                 onChange={(next) => next && changeFilterColumn(filter.id, next)}
@@ -241,6 +279,7 @@ export function TMDataGridFilterPanel() {
                 w={170}
                 allowDeselect={false}
                 comboboxProps={{ withinPortal: false }}
+                data-dg-part="filter-operator"
                 data={getOperatorsForType(type).map((operator) => ({
                   value: operator,
                   label: labels.operators[operator],
@@ -252,54 +291,28 @@ export function TMDataGridFilterPanel() {
                 }
               />
 
-              {takesArray && column ? (
-                // The set the cell is tested against. Options come from
-                // `meta.options`; a select column that declares none still
-                // gets the values present in the data, via the faceted index.
-                <MultiSelect
-                  label={labels.filterValue}
-                  size={controlSize}
-                  w={180}
-                  comboboxProps={{ withinPortal: false }}
-                  searchable
-                  data={optionsToComboboxData(
-                    resolveColumnOptions({ table, column, fallback: "faceted" }),
-                  )}
-                  value={Array.isArray(value.value) ? [...value.value] : []}
+              {column ? (
+                // The value slot: `meta.filterControl` if the column declares
+                // one, the built-in shape-by-operator input otherwise — both
+                // through the same value-only contract.
+                <ValueControl
+                  column={column}
+                  table={table}
+                  operator={value.operator}
+                  value={value.value}
                   onChange={(next) => patchFilter(filter.id, { value: next })}
-                />
-              ) : type === "boolean" ? (
-                <Select
-                  label={labels.filterValue}
+                  options={options}
                   size={controlSize}
-                  w={180}
-                  comboboxProps={{ withinPortal: false }}
-                  disabled={!needsValue}
-                  clearable
-                  placeholder={needsValue ? labels.filterValuePlaceholder : ""}
-                  data={[
-                    { value: "true", label: labels.booleanTrue },
-                    { value: "false", label: labels.booleanFalse },
-                  ]}
-                  value={needsValue && scalarValue !== "" ? scalarValue : null}
-                  onChange={(next) =>
-                    patchFilter(filter.id, { value: next ?? "" })
-                  }
+                  labels={labels}
                 />
               ) : (
+                // The column is gone from the definition; the row survives
+                // only to be re-pointed or removed.
                 <TextInput
                   label={labels.filterValue}
                   size={controlSize}
                   w={180}
-                  type={
-                    !needsValue
-                      ? "text"
-                      : type === "number"
-                        ? "number"
-                        : type === "date"
-                          ? "date"
-                          : "text"
-                  }
+                  data-dg-part="filter-value"
                   disabled={!needsValue}
                   placeholder={needsValue ? labels.filterValuePlaceholder : ""}
                   value={needsValue ? scalarValue : ""}
@@ -317,6 +330,7 @@ export function TMDataGridFilterPanel() {
             variant="subtle"
             size="compact-sm"
             disabled={!canAddFilter}
+            data-dg-part="filter-add"
             onClick={addFilter}
           >
             {labels.addFilter}
@@ -326,6 +340,7 @@ export function TMDataGridFilterPanel() {
             color="gray"
             size="compact-sm"
             disabled={columnFilters.length === 0}
+            data-dg-part="filter-clear-all"
             onClick={clearAllFilters}
           >
             {labels.clearAllFilters}

package/src/tmdatagrid/components/TMDataGridFilterPills.tsx

@@ -68,6 +68,7 @@ export function TMDataGridFilterPills<TData extends RowData>({
     <div
       role="group"
       aria-label={labels.activeFilters}
+      data-dg-part="filter-pills"
       className={[classes.filterPills, className].filter(Boolean).join(" ")}
     >
       <Pill.Group size={size}>
@@ -83,6 +84,8 @@ export function TMDataGridFilterPills<TData extends RowData>({
               key={filter.id}
               size={size}
               className={classes.pill}
+              data-dg-part="filter-pill"
+              data-column-id={filter.id}
               withRemoveButton
               onRemove={() =>
                 table.setColumnFilters(
@@ -93,6 +96,9 @@ export function TMDataGridFilterPills<TData extends RowData>({
               // the tab order, because inside a `PillsInput` Backspace is the
               // way out. These pills stand on their own, so the ✕ has to be a
               // real button.
+              // No test id of its own: Mantine types these props as
+              // `CloseButtonProps`, which has no room for `data-*`. The pill
+              // carries one, and the ✕ is the only button inside it.
               removeButtonProps={{
                 "aria-label": labels.clearFilter(label),
                 "aria-hidden": false,

package/src/tmdatagrid/components/TMDataGridFooter.tsx

@@ -78,7 +78,7 @@ export function TMDataGridFooter({
 
   if (pagination) {
     return (
-      <div className={classes.footer}>
+      <div data-dg-part="footer" className={classes.footer}>
         {pagination(getTMDataGridPaginationApi(table))}
       </div>
     );
@@ -108,7 +108,11 @@ export function TMDataGridFooter({
       w={260}
       position="top"
     >
-      <div className={classes.footer} data-paging-suspended={!paging}>
+      <div
+        data-dg-part="footer"
+        className={classes.footer}
+        data-paging-suspended={!paging}
+      >
         <Group gap="xs" wrap="nowrap">
           <Text size={controlSize} c="dimmed">
             {labels.rowsPerPage}
@@ -119,6 +123,7 @@ export function TMDataGridFooter({
             allowDeselect={false}
             variant="unstyled"
             disabled={!paging}
+            data-dg-part="page-size"
             data={sizeOptions.map(String)}
             value={String(pageSize)}
             onChange={(value) => {
@@ -128,7 +133,7 @@ export function TMDataGridFooter({
           />
         </Group>
 
-        <Text size={controlSize} c="dimmed">
+        <Text size={controlSize} c="dimmed" data-dg-part="page-range">
           {paging
             ? labels.pageRange({ from, to, total })
             : // Not a range: nothing is being sliced, so a range would be a lie.
@@ -142,6 +147,7 @@ export function TMDataGridFooter({
             variant="subtle"
             color="gray"
             aria-label={labels.previousPage}
+            data-dg-part="page-prev"
             disabled={!paging || !table.getCanPreviousPage()}
             onClick={() => table.previousPage()}
           >
@@ -151,6 +157,7 @@ export function TMDataGridFooter({
             variant="subtle"
             color="gray"
             aria-label={labels.nextPage}
+            data-dg-part="page-next"
             disabled={!paging || !table.getCanNextPage()}
             onClick={() => table.nextPage()}
           >

package/src/tmdatagrid/components/TMDataGridGroupColumn.tsx

@@ -72,6 +72,8 @@ function GroupCell<TData extends RowData>({
       aria-label={
         expanded ? labels.collapseGroup(label) : labels.expandGroup(label)
       }
+      data-dg-part="group-toggle"
+      data-row-id={row.id}
       // The row underneath may select or highlight on click; expanding is its
       // own gesture and must not also trigger those.
       onClick={(event) => {

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

@@ -28,8 +28,11 @@
   padding: 0;
 }
 
-/* Sorted or filtered columns read as active, like the MUI data grid. */
-.headerCell[data-active="true"] .headerTitle {
+/* A filtered column reads as active: its rows are a subset, and nothing else in
+   the header says so once the filter panel is closed. A sorted one is not
+   tinted — the arrow, pinned visible for as long as the sort lasts, already
+   says which column sorts and which way. */
+.headerCellFiltered .headerTitle {
   color: var(--mantine-primary-color-filled);
 }
 
@@ -85,6 +88,16 @@
   cursor: pointer;
 }
 
+/* See the sort ActionIcon: an unsorted column's arrow is an invitation, not a
+   state, so it sits back until the pointer is on it. */
+.sortAction[data-sorted="false"] {
+  opacity: 0.55;
+}
+
+.sortAction[data-sorted="false"]:hover {
+  opacity: 1;
+}
+
 /* Sort priority under multi-sort — "1", "2", … beside the arrow. Only rendered
    while more than one column sorts, so a single sort stays as it always was. */
 .sortIndex {

package/src/tmdatagrid/components/TMDataGridHeaderCell.tsx

@@ -435,6 +435,9 @@ export function TMDataGridHeaderCell({
   const cellClass = [
     classes.headerCell,
     canSort ? classes.headerCellSortable : "",
+    // Only the filter tints the title. `data-active` below stays
+    // sorted-or-filtered — it is the queryable state, not the styling hook.
+    isFiltered ? classes.headerCellFiltered : "",
     isDragged ? classes.headerCellDragging : "",
     dropSide === "before" ? classes.headerCellDropBefore : "",
     dropSide === "after" ? classes.headerCellDropAfter : "",
@@ -448,7 +451,10 @@ export function TMDataGridHeaderCell({
     <div
       ref={cellRef}
       role="columnheader"
-      data-testid={`dg-header-${column.id}`}
+      data-dg-part="header"
+      // The same coordinate the body, summary and entry cells carry, so one
+      // selector reaches a column's header and its cells alike.
+      data-column-id={column.id}
       data-active={isSorted || isFiltered}
       data-align={align}
       // A control lane is a fixed track, so it cannot take the cell padding the
@@ -525,6 +531,8 @@ export function TMDataGridHeaderCell({
               color="gray"
               size="xs"
               aria-label={labels.filterOn(label)}
+              data-dg-part="header-filter"
+              data-column-id={column.id}
               onClick={(event) => {
                 event.stopPropagation();
                 openColumnFilter(api, column.id);
@@ -536,12 +544,19 @@ export function TMDataGridHeaderCell({
 
           {canSort && (
             <ActionIcon
-              className={classes.headerAction}
+              className={`${classes.headerAction} ${classes.sortAction}`}
               data-pinned-visible={isSorted}
+              // The arrow is the whole signal now that the title no longer
+              // tints, so it takes the colour while the sort holds. On an
+              // unsorted column it is only the hover affordance, and stays a
+              // faded grey so the two never read alike.
+              data-sorted={isSorted}
               variant="subtle"
-              color="gray"
+              color={isSorted ? undefined : "gray"}
               size="xs"
               aria-label={labels.sortColumn(label)}
+              data-dg-part="header-sort"
+              data-column-id={column.id}
               onClick={column.getToggleSortingHandler()}
             >
               {sortDirection ? (
@@ -556,7 +571,7 @@ export function TMDataGridHeaderCell({
               `isMultiSortEvent`); the number is its priority. Outside the
               hover-revealed action so an active multi-sort stays readable. */}
           {sortIndex !== null && (
-            <span className={classes.sortIndex} data-testid="dg-sort-index">
+            <span className={classes.sortIndex} data-dg-part="sort-index">
               {sortIndex}
             </span>
           )}
@@ -581,6 +596,8 @@ export function TMDataGridHeaderCell({
                   color="gray"
                   size="xs"
                   aria-label={labels.columnMenu(label)}
+                  data-dg-part="header-menu"
+                  data-column-id={column.id}
                   onClick={(event) => {
                     event.stopPropagation();
                     setMenuOpened((opened) => !opened);

package/src/tmdatagrid/components/TMDataGridRowNumberColumn.tsx

@@ -0,0 +1,44 @@
+import type { ColumnDef, RowData } from "@tanstack/react-table";
+import type { TMDataGridFeatures } from "../useTMDataGrid";
+
+export const ROW_NUMBER_COLUMN_ID = "__rowNumber__";
+
+/**
+ * The generated row-number gutter, prepended under `enableRowNumbers` —
+ * outermost left, before even the checkbox lane, the way a spreadsheet keeps
+ * its gutter outside everything.
+ *
+ * The def renders nothing itself: a cell cannot know its display position,
+ * so the body computes the numbers — one pass over the view, group rows
+ * skipped (they are headings over the rows being counted), continuing across
+ * pages — and substitutes them in. See `TMDataGridTable`.
+ *
+ * A system lane: fixed width, no menu, no resize, never exported, and its
+ * visibility follows the option rather than the columns panel.
+ */
+export function createRowNumberColumn<TData extends RowData>(
+  label = "Row number",
+): ColumnDef<TMDataGridFeatures, TData, unknown> {
+  return {
+    id: ROW_NUMBER_COLUMN_ID,
+    meta: {
+      label,
+      align: "center",
+      // Anchors the left edge with the checkbox lane; nothing moves past it.
+      enableOrdering: false,
+    },
+    size: 48,
+    minSize: 48,
+    maxSize: 48,
+    enableResizing: false,
+    enableSorting: false,
+    enableColumnFilter: false,
+    enableGlobalFilter: false,
+    enablePinning: false,
+    enableHiding: false,
+    header: () => "#",
+    // The body substitutes the number; a row without one — a group row —
+    // falls through to this.
+    cell: () => null,
+  };
+}