@jielga/tmdatagrid 0.2.0 → 0.3.0

package/src/tmdatagrid/components/TMDataGridFooter.tsx

@@ -1,13 +1,18 @@
-import { ActionIcon, Group, Select, Text } from "@mantine/core";
+import { ActionIcon, Group, Select, Text, Tooltip } from "@mantine/core";
 import type { RowData } from "@tanstack/react-table";
 import { useSelector } from "@tanstack/react-store";
 import type { ReactNode } from "react";
 import classes from "./TMDataGridFooter.module.css";
 import { useTMDataGridContext } from "../TMDataGridContext";
 import { getGridCapabilities } from "../core/capabilities";
+import { isPagingActive } from "../core/rowSelection";
 import { ChevronLeftIcon, ChevronRightIcon } from "./icons";
 import type { TMDataGridTable } from "../useTMDataGrid";
 
+/** Shown on the greyed-out pager, and the reason it is greyed out. */
+const PAGING_SUSPENDED_HINT =
+  "Paging is off while the rows are grouped: the whole tree is rendered and virtualized. Ungroup to page again.";
+
 /** Distilled pagination state and actions for building a custom pager. */
 export type TMDataGridPaginationApi = {
   pageIndex: number;
@@ -83,6 +88,10 @@ export function TMDataGridFooter({
     );
   }
 
+  // Grouping suspends paging — see isPagingActive. The pager is greyed out
+  // rather than dropped, so that a footer going quiet reads as a state the grid
+  // is in rather than as something that broke.
+  const paging = isPagingActive(table, features);
   const { pageIndex, pageSize } = table.store.state.pagination;
   const total = table.getRowCount();
   const from = total === 0 ? 0 : pageIndex * pageSize + 1;
@@ -95,49 +104,68 @@ export function TMDataGridFooter({
     : [...pageSizeOptions, pageSize].sort((a, b) => a - b);
 
   return (
-    <div className={classes.footer}>
-      <Group gap="xs" wrap="nowrap">
+    <Tooltip
+      label={PAGING_SUSPENDED_HINT}
+      disabled={paging}
+      withArrow
+      multiline
+      w={260}
+      position="top"
+    >
+      <div className={classes.footer} data-paging-suspended={!paging}>
+        <Group gap="xs" wrap="nowrap">
+          <Text size={controlSize} c="dimmed">
+            Rows per page:
+          </Text>
+          <Select
+            size={controlSize}
+            w={78}
+            allowDeselect={false}
+            variant="unstyled"
+            disabled={!paging}
+            data={sizeOptions.map(String)}
+            value={String(pageSize)}
+            onChange={(value) => {
+              table.setPageSize(Number(value) || pageSizeOptions[0]);
+              table.setPageIndex(0);
+            }}
+          />
+        </Group>
+
         <Text size={controlSize} c="dimmed">
-          Rows per page:
+          {paging ? (
+            <>
+              {from}–{to} of {total}
+            </>
+          ) : (
+            // Not a range: nothing is being sliced, so a range would be a lie.
+            // Counted before grouping too — `getRowCount()` would be counting
+            // the tree, so a collapsed grid would claim to hold eight rows.
+            <>Grouped · all {table.getFilteredRowModel().rows.length} rows</>
+          )}
         </Text>
-        <Select
-          size={controlSize}
-          w={78}
-          allowDeselect={false}
-          variant="unstyled"
-          data={sizeOptions.map(String)}
-          value={String(pageSize)}
-          onChange={(value) => {
-            table.setPageSize(Number(value) || pageSizeOptions[0]);
-            table.setPageIndex(0);
-          }}
-        />
-      </Group>
 
-      <Text size={controlSize} c="dimmed">
-        {from}–{to} of {total}
-      </Text>
-
-      <Group gap={4} wrap="nowrap">
-        <ActionIcon
-          variant="subtle"
-          color="gray"
-          aria-label="Previous page"
-          disabled={!table.getCanPreviousPage()}
-          onClick={() => table.previousPage()}
-        >
-          <ChevronLeftIcon size={18} stroke={1.6} />
-        </ActionIcon>
-        <ActionIcon
-          variant="subtle"
-          color="gray"
-          aria-label="Next page"
-          disabled={!table.getCanNextPage()}
-          onClick={() => table.nextPage()}
-        >
-          <ChevronRightIcon size={18} stroke={1.6} />
-        </ActionIcon>
-      </Group>
-    </div>
+        <Group gap={4} wrap="nowrap">
+          <ActionIcon
+            variant="subtle"
+            color="gray"
+            aria-label="Previous page"
+            disabled={!paging || !table.getCanPreviousPage()}
+            onClick={() => table.previousPage()}
+          >
+            <ChevronLeftIcon size={18} stroke={1.6} />
+          </ActionIcon>
+          <ActionIcon
+            variant="subtle"
+            color="gray"
+            aria-label="Next page"
+            disabled={!paging || !table.getCanNextPage()}
+            onClick={() => table.nextPage()}
+          >
+            <ChevronRightIcon size={18} stroke={1.6} />
+          </ActionIcon>
+        </Group>
+      </div>
+    </Tooltip>
   );
 }

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

@@ -0,0 +1,48 @@
+/* The tree lane. Fills its cell so the whole indented width is a hit target,
+   which is what makes a deeply nested group as easy to click as a top-level
+   one. */
+.groupToggle {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  width: 100%;
+  min-width: 0;
+  font-size: var(--dg-font-size);
+  color: inherit;
+}
+
+.chevron {
+  display: flex;
+  flex: 0 0 auto;
+  align-items: center;
+  color: var(--mantine-color-dimmed);
+  transition: transform 120ms ease;
+}
+
+.chevron[data-expanded="true"] {
+  transform: rotate(90deg);
+}
+
+/* One icon rotated rather than two swapped: the turn is what reads as the
+   expand, and a swap would jump. */
+@media (prefers-reduced-motion: reduce) {
+  .chevron {
+    transition: none;
+  }
+}
+
+.groupLabel {
+  min-width: 0;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  font-weight: 600;
+}
+
+/* Never squeezed out by a long group value — the count is the part that tells
+   you whether the group is worth opening. */
+.groupCount {
+  flex: 0 0 auto;
+  color: var(--mantine-color-dimmed);
+  font-variant-numeric: tabular-nums;
+}

package/src/tmdatagrid/components/TMDataGridGroupColumn.tsx

@@ -0,0 +1,147 @@
+import { UnstyledButton } from "@mantine/core";
+import type { ColumnDef, Row, RowData } from "@tanstack/react-table";
+import { useSelector } from "@tanstack/react-store";
+import { shallow } from "@tanstack/store";
+import classes from "./TMDataGridGroupColumn.module.css";
+import { ChevronRightIcon } from "./icons";
+import { getColumnLabel } from "../core/columnUtils";
+import { getGroupDataRows } from "../core/grouping";
+import type { TMDataGridFeatures, TMDataGridTable } from "../useTMDataGrid";
+
+export const GROUP_COLUMN_ID = "__group__";
+
+/** Indent added per level of nesting, in px. */
+const INDENT_STEP = 16;
+
+/** Shown for a group whose value is empty — `String(null)` would read as "null". */
+const BLANK_GROUP_LABEL = "(Blank)";
+
+/**
+ * How a grouping value is written into the tree cell.
+ *
+ * Deliberately not the grouped column's own `cell` renderer: that renderer is
+ * written for a data row and is free to reach into `row.original`, which on a
+ * group row is the first leaf's record rather than anything about the group.
+ */
+export function formatGroupValue(value: unknown): string {
+  if (value === null || value === undefined || value === "") {
+    return BLANK_GROUP_LABEL;
+  }
+  if (value instanceof Date) return value.toLocaleDateString();
+  return String(value);
+}
+
+/**
+ * The tree cell: chevron, group value and leaf count, indented by depth.
+ *
+ * Expansion is read through a subscription rather than from `row.getIsExpanded()`
+ * in the component body for the same reason the select checkbox does it — the
+ * `row` identity survives an expand, so the React Compiler would cache the call
+ * along with it and the chevron would never turn. See TMDataGridSelectColumn.
+ */
+function GroupCell<TData extends RowData>({
+  row,
+}: {
+  row: Row<TMDataGridFeatures, TData>;
+}) {
+  const expanded = useSelector(row.table.store, () => row.getIsExpanded());
+
+  // Leaf rows keep the lane empty: their values are in the data columns, and
+  // the indent alone is what places them under their group.
+  if (!row.getIsGrouped()) return null;
+
+  const label = formatGroupValue(row.groupingValue);
+
+  return (
+    <UnstyledButton
+      className={classes.groupToggle}
+      // Padding rather than margin, so the whole indented width stays clickable.
+      style={{ paddingInlineStart: row.depth * INDENT_STEP }}
+      aria-expanded={expanded}
+      aria-label={`${expanded ? "Collapse" : "Expand"} ${label}`}
+      // The row underneath may select or highlight on click; expanding is its
+      // own gesture and must not also trigger those.
+      onClick={(event) => {
+        event.stopPropagation();
+        row.toggleExpanded();
+      }}
+    >
+      <span className={classes.chevron} data-expanded={expanded}>
+        <ChevronRightIcon size={16} stroke={1.6} />
+      </span>
+      <span className={classes.groupLabel}>{label}</span>
+      {/* Data rows, not direct children and not `getLeafRows()`: a nested group
+          counts the records under it, never the sub-groups in between. */}
+      <span className={classes.groupCount}>
+        ({getGroupDataRows(row).length})
+      </span>
+    </UnstyledButton>
+  );
+}
+
+/**
+ * Names the columns currently grouped on, so the lane says what it is showing
+ * rather than a static "Group".
+ */
+function GroupHeader<TData extends RowData>({
+  table,
+}: {
+  table: TMDataGridTable<TData>;
+}) {
+  const grouping = useSelector(table.store, (state) => state.grouping, {
+    compare: shallow,
+  });
+
+  if (grouping.length === 0) return "Group";
+  return grouping
+    .map((columnId) => {
+      const column = table.getColumn(columnId);
+      return column ? getColumnLabel(column) : columnId;
+    })
+    .join(" / ");
+}
+
+/**
+ * The generated tree column, prepended whenever grouping is enabled and hidden
+ * again while `grouping` is empty — see the visibility effect in
+ * `useTMDataGrid`.
+ *
+ * It exists because TanStack ships no auto group column: `groupedColumnMode:
+ * "remove"` takes the grouped column out of the grid, so something has to hold
+ * the tree. Modelled on the checkbox column, which is generated the same way.
+ *
+ * Not groupable itself, and nothing had to be written to make that true —
+ * `column.getCanGroup()` requires an `accessorFn`, which a display column has
+ * no reason to have.
+ */
+export function createGroupColumn<TData extends RowData>(): ColumnDef<
+  TMDataGridFeatures,
+  TData,
+  unknown
+> {
+  return {
+    id: GROUP_COLUMN_ID,
+    meta: {
+      label: "Group",
+      // Structurally the first column after the checkbox lane.
+      enableOrdering: false,
+    },
+    size: 260,
+    minSize: 180,
+    enableSorting: false,
+    enableColumnFilter: false,
+    enableGlobalFilter: false,
+    // Keeps it out of the columns panel and out of the header menu: its
+    // visibility is not the user's to set, it follows the grouping state.
+    enableHiding: false,
+    // Structurally pinned to the left; users shouldn't be able to move it.
+    enablePinning: false,
+    cell: ({ row }) => <GroupCell row={row} />,
+    // A group row has subRows, so every cell on it that is not the grouped
+    // column reports `getIsAggregated()` — this lane included. Without an
+    // `aggregatedCell` the body would take that as "nothing to summarise" and
+    // render the tree lane blank on exactly the rows it exists for.
+    aggregatedCell: ({ row }) => <GroupCell row={row} />,
+    header: ({ table }) => <GroupHeader table={table} />,
+  };
+}

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

@@ -21,6 +21,12 @@
   justify-content: center;
 }
 
+/* Same as the body cells: the select-all box sits in a fixed 48px track, which
+   the text padding would squeeze it out of at the larger sizes. */
+.headerCell[data-select-column="true"] {
+  padding: 0;
+}
+
 /* Sorted or filtered columns read as active, like the MUI data grid. */
 .headerCell[data-active="true"] .headerTitle {
   color: var(--mantine-primary-color-filled);

package/src/tmdatagrid/components/TMDataGridHeaderCell.tsx

@@ -23,16 +23,21 @@ import { isFilterActive } from "../core/filterOperators";
 import {
   ArrowDownIcon,
   ArrowUpIcon,
+  CollapseAllIcon,
   ColumnsIcon,
   DotsVerticalIcon,
+  ExpandAllIcon,
   EyeOffIcon,
   FilterIcon,
+  GroupIcon,
   MoveLeftIcon,
   MoveRightIcon,
   PinLeftIcon,
   PinOffIcon,
   PinRightIcon,
+  UngroupIcon,
 } from "./icons";
+import { GROUP_COLUMN_ID } from "./TMDataGridGroupColumn";
 import { SELECT_COLUMN_ID } from "./TMDataGridSelectColumn";
 import { type TMDataGridFeatures, openColumnFilter } from "../useTMDataGrid";
 
@@ -63,7 +68,7 @@ export function TMDataGridHeaderCell({
   // surrounding tree is memoized (React Compiler) or the table lives elsewhere.
   // `columnOrder` is in the list because the move menu items are derived from
   // the column's neighbours, which is exactly what an order change invalidates.
-  const { sorting, columnFilters, resizingColumnId, columnPinning } =
+  const { sorting, columnFilters, resizingColumnId, columnPinning, grouping } =
     useSelector(
       table.store,
       (state) => ({
@@ -72,6 +77,7 @@ export function TMDataGridHeaderCell({
         resizingColumnId: state.columnResizing.isResizingColumn,
         columnPinning: state.columnPinning,
         columnOrder: state.columnOrder,
+        grouping: state.grouping,
       }),
       { compare: shallow },
     );
@@ -97,9 +103,18 @@ export function TMDataGridHeaderCell({
   const canPin = isLeaf && capabilities.canPin;
   const canResize = capabilities.canResize;
   const canReorder = isLeaf && capabilities.canReorder;
+  const canGroup = isLeaf && capabilities.canGroup;
   const canManageColumns =
     isLeaf && getGridCapabilities(table, features).canHideAny;
 
+  // Read off the subscribed slice, not from `column.getIsGrouped()`: that is a
+  // call on a `column` whose identity survives a grouping change, so the React
+  // Compiler would cache the answer and the menu would keep offering to group
+  // a column that already is. Same reason the sort and filter flags above are
+  // derived from state rather than from `getIsSorted()`.
+  const isGrouped = grouping.includes(column.id);
+  const isGroupingActive = grouping.length > 0;
+
   // A column only moves inside its own pinned lane, so a header in another one
   // never lights up as a target. See TMDataGridColumnRegion.
   const isDragged = draggedColumnId === column.id;
@@ -205,6 +220,64 @@ export function TMDataGridHeaderCell({
       <Menu.Divider key="filter-divider" />,
     );
   }
+  if (canGroup) {
+    menuItems.push(
+      <Menu.Item
+        key="group"
+        className={isGrouped ? classes.menuItemActive : undefined}
+        leftSection={
+          isGrouped ? (
+            <UngroupIcon size={16} stroke={1.6} />
+          ) : (
+            <GroupIcon size={16} stroke={1.6} />
+          )
+        }
+        onClick={column.getToggleGroupingHandler()}
+      >
+        {isGrouped ? `Ungroup ${label}` : `Group by ${label}`}
+      </Menu.Item>,
+    );
+  }
+  if (isGroupingActive) {
+    // Under the default `groupedColumnMode: "remove"` a grouped column is taken
+    // out of the grid, so its own header — and the Ungroup item on it — is no
+    // longer reachable. The tree column that replaced it carries them instead,
+    // which is also where someone would look for them.
+    if (column.id === GROUP_COLUMN_ID) {
+      for (const groupedId of grouping) {
+        const groupedColumn = table.getColumn(groupedId);
+        if (!groupedColumn) continue;
+        menuItems.push(
+          <Menu.Item
+            key={`ungroup-${groupedId}`}
+            leftSection={<UngroupIcon size={16} stroke={1.6} />}
+            onClick={() => groupedColumn.toggleGrouping()}
+          >
+            {`Ungroup ${getColumnLabel(groupedColumn)}`}
+          </Menu.Item>,
+        );
+      }
+    }
+    menuItems.push(
+      <Menu.Item
+        key="expand-all"
+        leftSection={<ExpandAllIcon size={16} stroke={1.6} />}
+        onClick={() => table.toggleAllRowsExpanded(true)}
+      >
+        Expand all groups
+      </Menu.Item>,
+      <Menu.Item
+        key="collapse-all"
+        leftSection={<CollapseAllIcon size={16} stroke={1.6} />}
+        onClick={() => table.toggleAllRowsExpanded(false)}
+      >
+        Collapse all groups
+      </Menu.Item>,
+    );
+  }
+  if (canGroup || isGroupingActive) {
+    menuItems.push(<Menu.Divider key="group-divider" />);
+  }
   if (canPin) {
     menuItems.push(
       <Menu.Item
@@ -322,6 +395,9 @@ export function TMDataGridHeaderCell({
       data-testid={`dg-header-${column.id}`}
       data-active={isSorted || isFiltered}
       data-align={align}
+      // The checkbox lane is a fixed track, so it cannot take the cell padding
+      // the scale grows for text. See TMDataGridHeaderCell.module.css.
+      data-select-column={column.id === SELECT_COLUMN_ID}
       // Only meaningful on a sortable column: "none" advertises that this
       // header sorts, which is a lie on one that doesn't.
       aria-sort={

package/src/tmdatagrid/components/TMDataGridSelectColumn.tsx

@@ -1,6 +1,12 @@
 import { Checkbox } from "@mantine/core";
 import { useSelector } from "@tanstack/react-store";
 import type { ColumnDef, Row, RowData } from "@tanstack/react-table";
+import { useTMDataGridContext } from "../TMDataGridContext";
+import {
+  getDisplayedRows,
+  getSelectableRowIds,
+  resolveRowSelectionClick,
+} from "../core/rowSelection";
 import type { TMDataGridFeatures, TMDataGridTable } from "../useTMDataGrid";
 
 export const SELECT_COLUMN_ID = "__select__";
@@ -43,24 +49,90 @@ function SelectAllCheckbox<TData extends RowData>({
   );
 }
 
+/**
+ * Drops the select-all box when only one row may be selected. Read from the
+ * feature flags rather than `table.options.enableMultiRowSelection` directly:
+ * the flags are re-derived from a fresh object every render, so the switch
+ * cannot be cached along with a `table` identity that survives an options
+ * change — the same reason the rest of the chrome reads them. See
+ * readFeatureFlags.
+ */
+function SelectAllHeader<TData extends RowData>({
+  table,
+}: {
+  table: TMDataGridTable<TData>;
+}) {
+  const { features } = useTMDataGridContext();
+  if (!features.multiRowSelection) return null;
+  return <SelectAllCheckbox table={table} />;
+}
+
 function SelectRowCheckbox<TData extends RowData>({
   row,
 }: {
   row: Row<TMDataGridFeatures, TData>;
 }) {
-  const selected = useSelector(row.table.store, () => row.getIsSelected());
+  // Cells render inside the grid's provider, so the checkbox can reach the
+  // chrome store — it needs the shift-click pivot, and the feature flags to know
+  // which row model a range is measured over.
+  const { ui, features } = useTMDataGridContext();
+  const isGroupRow = row.subRows.length > 0;
+
+  // A group row is never selected by id: `rowSelection` only ever holds the
+  // leaves, and TanStack's `getIsSelected()` is a plain lookup in that map. So
+  // a group asks about its descendants instead, which is also the honest
+  // reading — the box means "all of these", and it goes indeterminate as soon
+  // as that stops being true.
+  const selected = useSelector(row.table.store, () =>
+    isGroupRow ? row.getIsAllSubRowsSelected() : row.getIsSelected(),
+  );
   const someSelected = useSelector(row.table.store, () =>
     row.getIsSomeSelected(),
   );
 
+  // The resolver expands a tick back out to the descendant ids; all the group
+  // case needs here is to know whether any of them may be selected at all.
+  const selectableIds = getSelectableRowIds(row);
+
+  // Single-select has no way to express "this group": one box for several rows
+  // would either overrun the limit or lie about what it did.
+  if (isGroupRow && !row.getCanMultiSelect()) return null;
+
   return (
     <Checkbox
       size="xs"
-      aria-label="Select row"
+      aria-label={isGroupRow ? "Select group" : "Select row"}
       checked={selected}
-      disabled={!row.getCanSelect()}
+      disabled={selectableIds.length === 0}
       indeterminate={someSelected && !selected}
-      onChange={row.getToggleSelectedHandler()}
+      // Every tick goes through the resolver, shift held or not — plain becomes
+      // a toggle that moves the pivot, so a later shift-click extends from the
+      // box the user last touched.
+      //
+      // All of it in `onChange`, not split with an `onClick`: React derives a
+      // checkbox's change event from the click, so the modifier keys ride along
+      // on the native event, and a `preventDefault()` in a click handler cannot
+      // stop the change from firing anyway. Trying to do the range in `onClick`
+      // silently loses the clicked row, which `onChange` then toggles back off.
+      onChange={(event) => {
+        const native = event.nativeEvent;
+        const isMouse = native instanceof MouseEvent;
+        const resolved = resolveRowSelectionClick({
+          rows: getDisplayedRows(row.table, features),
+          rowId: row.id,
+          anchorRowId: ui.state.selectionAnchorRowId,
+          modifiers: {
+            toggle: isMouse && (native.ctrlKey || native.metaKey),
+            extend: isMouse && native.shiftKey,
+          },
+          selection: row.table.store.state.rowSelection,
+          // A checkbox is only ever additive — ticking one has never cleared
+          // the others, so `canReplaceSelection` stays false whatever is held.
+          canReplaceSelection: false,
+        });
+        row.table.setRowSelection(resolved.selection);
+        ui.actions.setSelectionAnchor(resolved.anchorRowId);
+      }}
       // A row can select on click too; the checkbox must not toggle twice.
       onClick={(event) => event.stopPropagation()}
     />
@@ -69,7 +141,7 @@ function SelectRowCheckbox<TData extends RowData>({
 
 /**
  * The generated checkbox column, prepended under
- * `rowSelectionMode: "checkbox"` — the default whenever row selection is on.
+ * `selectionMode: "checkbox"` (the default) or `"checkboxAndHighlight"`.
  */
 export function createSelectColumn<TData extends RowData>(): ColumnDef<
   TMDataGridFeatures,
@@ -94,7 +166,12 @@ export function createSelectColumn<TData extends RowData>(): ColumnDef<
     enableGlobalFilter: false,
     // Structurally pinned to the left; users shouldn't be able to move it.
     enablePinning: false,
-    header: ({ table }) => <SelectAllCheckbox table={table} />,
+    header: ({ table }) => <SelectAllHeader table={table} />,
     cell: ({ row }) => <SelectRowCheckbox row={row} />,
+    // Every cell on a group row that is not the grouped column counts as
+    // aggregated, this lane included, and an aggregated cell with nothing
+    // declared renders blank. Without this the checkbox would disappear from
+    // exactly the rows that select a whole group. See renderCellContent.
+    aggregatedCell: ({ row }) => <SelectRowCheckbox row={row} />,
   };
 }

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

@@ -42,13 +42,39 @@
   --row-bg: var(--mantine-color-default-hover);
 }
 
-/* Selection and highlight are separate: a row is always `data-selected`, but it
-   only takes the highlight colour when `highlightSelectedRows` is on — the
-   default in row selection mode, off with checkboxes. */
-.bodyRow[data-highlighted="true"] {
+/* A group row takes no background of its own. Collapsed, every row on screen is
+   a group row, so a tint would grey out the whole grid and read as if
+   everything were selected. The bold label and the chevron carry the
+   distinction instead — and `--dg-row-group-bg` is there for a consumer who
+   wants the tint back. Declared before the selection rules, so a selected or
+   highlighted group still reads as one. */
+.bodyRow[data-grouped="true"] {
+  --row-bg: var(--dg-row-group-bg);
+}
+
+/* The row an open context menu is about. The pointer has usually left it by
+   then, so without this the menu would be the only thing saying which row it
+   acts on. Declared before the selection rules, which are the stronger
+   statement and win at equal specificity. */
+.bodyRow[data-context-menu="true"] {
+  --row-bg: var(--mantine-color-default-hover);
+}
+
+/* Being selected and being painted for it are separate: a row is always
+   `data-selected`, but only takes the background when `showSelectedBackground`
+   is on — the default under `"row"`, off with checkboxes. */
+.bodyRow[data-selected-bg="true"] {
   --row-bg: var(--dg-row-selected-bg);
 }
 
+/* The highlighted row wins over the selected background: under
+   `"checkboxAndHighlight"` the two coexist, and the highlighted row is the one
+   the detail panel is about, so it must stay distinguishable inside a
+   selection. Declared after, so the later rule takes it at equal specificity. */
+.bodyRow[data-highlighted="true"] {
+  --row-bg: var(--dg-row-highlight-bg);
+}
+
 /* Row selection mode: the row is the control, so it takes focus and must not
    start a text selection on the click that toggles it. */
 .bodyRow[data-selects-on-click="true"] {
@@ -72,6 +98,14 @@
   font-size: var(--dg-font-size);
 }
 
+/* The checkbox column is a fixed 48px track holding a control of a known width,
+   not text that can ellipsize. Cell padding is sized for text and grows with
+   the scale, so at `xl` its 18px a side left 12px for a 16px box and the
+   checkbox was clipped. The lane centres its control instead. */
+.bodyCell[data-select-column="true"] {
+  padding: 0;
+}
+
 .cellContent {
   min-width: 0;
   overflow: hidden;