@cerebruminc/cerebellum 20.5.0 → 20.6.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # react-component-lib-boilerplate
 
+## [20.6.0](https://github.com/cerebruminc/cerebellum/compare/v20.5.0...v20.6.0) (2026-09-10)
+
+
+### Features
+
+* **data-table:** add warning if getRowId is missing when checkboxes are used ([60788a1](https://github.com/cerebruminc/cerebellum/commit/60788a15ef7b2e0fc868acc8d0744dc60234055e))
+* **datatable:** add a checkbox and radio row-selection column ([e79c816](https://github.com/cerebruminc/cerebellum/commit/e79c8164f5e424ffbcf02b37756b2da884c450be))
+* **datatable:** add row-selection stories for checkboxes and radios ([2d0d12d](https://github.com/cerebruminc/cerebellum/commit/2d0d12dd0a2865df06096fe6cf3b61527db2943a))
+* **mantine-theme:** support Radio in the mantineTheme ([72e8573](https://github.com/cerebruminc/cerebellum/commit/72e857346fe2d6d86aebcacd3044dc3fea250497))
+
+
+### Bug Fixes
+
+* **tooltip:** update the Tooltip styles ([155f939](https://github.com/cerebruminc/cerebellum/commit/155f939a1e5bc22c9a270de98775a681297a5884))
+* **userCard:** fix UserCard spacing ([0bcd605](https://github.com/cerebruminc/cerebellum/commit/0bcd605b0a6a94ee7e0994e20794e06328ef37b9))
+
 ## [20.5.0](https://github.com/cerebruminc/cerebellum/compare/v20.4.0...v20.5.0) (2026-09-09)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerebruminc/cerebellum",
-  "version": "20.5.0",
+  "version": "20.6.0",
   "description": "Cerebrum's React Component Library",
   "type": "module",
   "main": "src/index.ts",

package/src/components/UserCard/UserCard.module.css

@@ -70,7 +70,7 @@
 /* Layout groups */
 .optionsBox {
   margin-top: 27px;
-  padding-bottom: 10px;
+  padding-bottom: 27px;
 }
 
 .nonScrollingGroup {
@@ -314,7 +314,7 @@
 }
 
 .orgDivider.orgDivider {
-  margin: 16px -7px 16px;
+  margin: 0 -7px 16px;
 }
 
 .signOutDivider.signOutDivider {

package/src/helpers/deprecation.test.ts

@@ -1,6 +1,6 @@
 /**
  * @file src/helpers/deprecation.test.ts
- * @summary Pins the "once per session" contract of the styled-components deprecation notice.
+ * @summary Pins the "once" contract of both notices this package emits.
  * @remarks
  * The value of this notice depends entirely on it being quiet: one line, once. A regression
  * that made it fire per render would put it in front of developers hundreds of times a page
@@ -103,3 +103,76 @@ describe("warnStyledComponentsDeprecated", () => {
     expect(warn).toHaveBeenCalledTimes(1);
   });
 });
+
+/*
+ * `warnOnceFor` counts per scope rather than per session, which is the whole point:
+ * one misconfigured table should not swallow the warning owed to a second one, while
+ * that table's own re-renders and StrictMode double-mount stay a single line.
+ */
+describe("warnOnceFor", () => {
+  let warn: jest.SpyInstance;
+  const originalNodeEnv = process.env.NODE_ENV;
+
+  beforeEach(() => {
+    warn = jest.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    warn.mockRestore();
+    process.env.NODE_ENV = originalNodeEnv;
+  });
+
+  it("warns on the first call for a scope", () => {
+    freshModule().warnOnceFor({}, "first");
+
+    expect(warn).toHaveBeenCalledWith("first");
+  });
+
+  it("stays silent on every later call for the same scope", () => {
+    const { warnOnceFor } = freshModule();
+    const scope = {};
+
+    warnOnceFor(scope, "same");
+    warnOnceFor(scope, "same");
+    warnOnceFor(scope, "same");
+
+    expect(warn).toHaveBeenCalledTimes(1);
+  });
+
+  it("warns once for each scope, so a second offender is still heard", () => {
+    const { warnOnceFor } = freshModule();
+
+    warnOnceFor({}, "same");
+    warnOnceFor({}, "same");
+
+    expect(warn).toHaveBeenCalledTimes(2);
+  });
+
+  it("counts each distinct message separately within one scope", () => {
+    const { warnOnceFor } = freshModule();
+    const scope = {};
+
+    warnOnceFor(scope, "one");
+    warnOnceFor(scope, "two");
+
+    expect(warn).toHaveBeenCalledTimes(2);
+  });
+
+  it("stays silent in production, where the notice reaches no developer", () => {
+    process.env.NODE_ENV = "production";
+
+    freshModule().warnOnceFor({}, "hidden");
+
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  /* The deprecation opt-out is for a long migration; it should not hide a live bug. */
+  it("is not silenced by setDeprecationWarningsEnabled(false)", () => {
+    const { setDeprecationWarningsEnabled, warnOnceFor } = freshModule();
+
+    setDeprecationWarningsEnabled(false);
+    warnOnceFor({}, "still shown");
+
+    expect(warn).toHaveBeenCalledWith("still shown");
+  });
+});

package/src/helpers/deprecation.ts

@@ -1,8 +1,11 @@
 /**
  * @file src/helpers/deprecation.ts
- * @exports setDeprecationWarningsEnabled, warnStyledComponentsDeprecated
- * @summary The single place this package announces that its styled-components layer is deprecated.
+ * @exports setDeprecationWarningsEnabled, warnOnceFor, warnStyledComponentsDeprecated
+ * @summary The single place this package warns a developer about anything.
  * @remarks
+ * Two notices live here, for one reason: each depends on module state to stay quiet, and a
+ * stray `console.warn` elsewhere would not respect it. The deprecation notice is the
+ * original; `warnOnceFor` is the general form, for a misconfiguration a consumer can fix.
  * The original styled-components components are deprecated, but not removed, in
  * favor of the Mantine layer under `src/mantine`. The notice is emitted once per app
  * session from `ThemeProvider`'s mount effect rather than from each component — an effect
@@ -51,3 +54,27 @@ export const warnStyledComponentsDeprecated = () => {
   hasWarned = true;
   console.warn(MESSAGE);
 };
+
+const warnedByScope = new WeakMap<object, Set<string>>();
+
+/**
+ * Warns once per `scope` — a long-lived object the notice belongs to, such as a
+ * `useReactTable` instance, whose identity `useReactTable` keeps stable for the life of
+ * the component. Two misconfigured tables therefore each get heard, while re-renders and
+ * StrictMode's double-mount of one table are counted once. A `WeakMap` so a scope that
+ * unmounts is collectable rather than pinned for the session.
+ *
+ * Deliberately not gated on `setDeprecationWarningsEnabled`: that switch is for a team
+ * living with the deprecation through a long migration, and silencing it should not also
+ * hide a bug they can fix today.
+ */
+export const warnOnceFor = (scope: object, message: string) => {
+  if (typeof process !== "undefined" && process.env.NODE_ENV === "production") return;
+
+  const seen = warnedByScope.get(scope) ?? new Set<string>();
+  if (seen.has(message)) return;
+
+  seen.add(message);
+  warnedByScope.set(scope, seen);
+  console.warn(message);
+};

package/src/index.ts

@@ -681,6 +681,7 @@ export {
   DataTableRoot,
   DataTableRowActions,
   dataTableRowActionsColumn,
+  dataTableSelectionColumn,
   DataTableSidebar,
   DataTableTotalRecords,
 } from "./mantine/components/DataTable";
@@ -703,6 +704,8 @@ export type {
   DataTableRowOptionGroup,
   DataTableRowOptionIcon,
   DataTableSectionProps,
+  DataTableSelectionColumnOptions,
+  DataTableSelectionMode,
   DataTableSidebarProps,
   DataTableTotalRecordsProps,
 } from "./mantine/components/DataTable";

package/src/mantine/components/DataTable/DataTable.module.css

@@ -358,6 +358,48 @@
   justify-content: center;
 }
 
+/* ----- Row selection ----- */
+
+/*
+ * CheckboxCell's geometry: the control sits in the 40px track its `meta.fixedWidth`
+ * already cleared of side padding, with the legacy 17px lead. Single-class, like
+ * .rowActionsCell beside it -- this is our own div, not a Mantine slot, so there is
+ * nothing to outrank.
+ */
+.selectionCell {
+  align-items: center;
+  display: flex;
+  height: 100%;
+  padding-left: 17px;
+}
+
+/*
+ * Composed onto .selectionCell in the header, for `CheckboxHeaderCell`'s extra pixel
+ * of lead and to sit the control on the header labels rather than above them.
+ *
+ * `flex-end` rather than the centring above, and no `padding-bottom` of the legacy
+ * cell's own: the labels are bottom-aligned in the header, so the control belongs at
+ * the bottom of the cell's content box too. Centring put it 11px high, because
+ * `CheckboxHeaderCell` *was* the grid cell and owned that padding, whereas this
+ * wrapper sits inside a `.th` that already pads 11px at the bottom -- so restating it
+ * here counted it twice, once as the cell's inset and once as the control's.
+ */
+.selectionHeaderCell {
+  align-items: flex-end;
+  padding-left: 17px;
+}
+
+/*
+ * Mantine draws the checkbox glyph at 60% of the control, so the 20px control this
+ * column needs would render a 12px glyph -- smaller than the legacy Checkbox's 15px
+ * and than every other checkbox in the Mantine layer, which are both 25px x 60%.
+ * 75% puts it back at 15px. The radio needs no equivalent: its icon is pinned to
+ * the control's size, so it fills the 20px the legacy radio also measured.
+ */
+.selectionCheckboxIcon.selectionCheckboxIcon {
+  width: 75%;
+}
+
 /*
  * Keyed on plain `.tr.tr:hover` rather than the elevated-hover selector above, so
  * `disableHighlight` drops the row treatment without also disabling the button.

package/src/mantine/components/DataTable/DataTable.tsx

@@ -108,15 +108,17 @@ import Form, { FormProps as RJSFormProps } from "@rjsf/core";
 import { GenericObjectType, RJSFSchema } from "@rjsf/utils";
 import { Row, RowData, flexRender, useReactTable } from "@tanstack/react-table";
 import { clsx } from "clsx";
-import React, { createContext, FC, Fragment, PropsWithChildren, useCallback, useContext, useRef } from "react";
+import React, { createContext, FC, Fragment, PropsWithChildren, useCallback, useContext, useEffect, useRef } from "react";
 import { Sort, SortDown, SortUp } from "../../../components/Icons";
 
 import { EmptySearchIcon } from "../../../assets/EmptySearchIcon";
+import { warnOnceFor } from "../../../helpers/deprecation";
 import { MantineRJSForm } from "../../rjsf/createMantineRJSForm";
 import { mantineValidator } from "../../rjsf/mantineValidator";
 import { showBar } from "../../services/notifications";
 
 import classes from "./DataTable.module.css";
+import type { DataTableSelectionMode } from "./DataTableSelection";
 
 /**
  * The per-column styling a column def asks for, through `columnDef.meta`.
@@ -176,6 +178,14 @@ export type DataTableColumnMeta = {
    * for how it interacts with density and `fixedWidth`.
    */
   paddingRight?: number | string;
+  /**
+   * Set by `dataTableSelectionColumn`, and the only field here that is not styling.
+   * It is what tells `DataTableBody` the table has a selection column and which
+   * control it renders, so a row click can select without a prop saying so. Not for
+   * hand-authoring: it does not render a control, it only describes the one the
+   * factory rendered.
+   */
+  selectionMode?: DataTableSelectionMode;
   /**
    * The old ColumnType's `textStyle`, and the same four values: the legacy BodyS*
    * styles were all 15px and differed only in weight and colour.
@@ -832,6 +842,12 @@ const cellProps = (meta: DataTableColumnMeta | undefined) => {
  */
 const bodyCellProps = (meta: DataTableColumnMeta | undefined) => ({ ...cellProps(meta), "data-text-style": meta?.textStyle });
 
+const MISSING_GET_ROW_ID_WARNING = [
+  "[@cerebruminc/cerebellum] DataTable has a row-selection column but its table has no `getRowId`.",
+  "TanStack then keys row selection by each record's index in `data`, so a selection silently moves to whatever record takes that index whenever `data` changes -- filtered, reordered, or fetched a page at a time.",
+  "Pass `getRowId: (record) => record.id` -- or whatever identifies your record -- to useReactTable.",
+].join(" ");
+
 export const DataTableBody = <TRecord,>({
   density,
   disableHighlight,
@@ -850,6 +866,68 @@ export const DataTableBody = <TRecord,>({
   const rows = dataTable.rt.getRowModel().rows;
   const hasNoRecords = !dataTable.isLoading && rows.length === 0;
 
+  /*
+   * Read off `dataTableSelectionColumn`'s own meta rather than taken as a prop. Its
+   * presence is what says the table has selection at all -- which matters because
+   * TanStack's `enableRowSelection` defaults to on, so `row.getCanSelect()` is true
+   * for every table that never asked for selection and would make all of them
+   * click-to-select. Its value is the control the column renders, which is the one
+   * thing a row handler cannot otherwise know.
+   */
+  const selectionMode = dataTable.rt.getAllLeafColumns().find((column) => column.columnDef.meta?.selectionMode)?.columnDef
+    .meta?.selectionMode;
+
+  /*
+   * A selection column with no `getRowId` is always a bug, never a choice: TanStack keys
+   * `rowSelection` by `row.id`, which is the record's *index in `data`* until the caller
+   * configures one. Client-side paging and sorting are safe, because neither changes
+   * `data` -- it is replacing that array, as a filtered or server-paged table does, that
+   * silently moves the selection to whatever record now sits at the index. Nothing here
+   * can fix it -- `getRowId` is an option on the caller's own `useReactTable` call,
+   * resolved before DataTable is handed the result -- so saying so is the most this
+   * layer can do.
+   *
+   * In an effect, so a discarded or server-side render cannot spend the one warning.
+   */
+  useEffect(() => {
+    if (selectionMode && !dataTable.rt.options.getRowId) {
+      warnOnceFor(dataTable.rt, MISSING_GET_ROW_ID_WARNING);
+    }
+  }, [dataTable.rt, selectionMode]);
+
+  /*
+   * `onRowClick` wins, so a table can have both a row action and a selection column
+   * without the two fighting over the same click. Otherwise a selection column makes
+   * the whole row a selection target, so selection is never a 40px one. Undefined
+   * when neither applies, which leaves the row unclickable rather than clickable and
+   * inert.
+   *
+   * The row does what a click on its own control would: a checkbox toggles, and a
+   * radio only ever selects, because a native radio does not clear itself when
+   * clicked again.
+   */
+  const activateRow = onRowClick
+    ? onRowClick
+    : selectionMode
+      ? (row: Row<TRecord>) => row.toggleSelected(selectionMode === "radio" ? true : undefined)
+      : undefined;
+
+  /*
+   * Per row rather than per table: a row that cannot be selected must not carry the
+   * pointer cursor or a click that would do nothing.
+   */
+  const canActivateRow = (row: Row<TRecord>) => Boolean(activateRow) && (Boolean(onRowClick) || row.getCanSelect());
+
+  /*
+   * Only a row that carries a handler of its own is a tab stop. Under a selection
+   * column the control inside the row is already focusable and already does exactly
+   * what the row does, so a tab stop on the row as well would be two stops per row
+   * for one action -- and the keyboard user would meet the row's focus ring before
+   * the control that explains it. The mouse path is unaffected: the row keeps its
+   * pointer cursor and its click either way.
+   */
+  const rowIsFocusable = Boolean(onRowClick);
+
   return (
     /*
      * ScrollArea rather than a plain overflow container, so the scrollbar is the
@@ -967,19 +1045,25 @@ export const DataTableBody = <TRecord,>({
                   const selected = isRowSelected?.(row);
                   const isSelected = Boolean(selected);
                   const isBusy = Boolean(isRowLoading?.(row));
-                  // A busy row is inert: neither the mouse nor Enter/Space reaches the
-                  // caller, and the pointer cursor goes with them.
-                  const clickable = Boolean(onRowClick) && !isBusy;
+                  /*
+                   * A busy row is inert: neither the mouse nor Enter/Space reaches the
+                   * caller, and the pointer cursor goes with them. `canActivateRow`
+                   * rather than `onRowClick`, so that now covers a click that would
+                   * have selected the row as well as one the caller handles.
+                   */
+                  const isActivatable = canActivateRow(row) && !isBusy;
                   return (
                     <TableTr
                       aria-busy={isBusy || undefined}
                       /*
-                       * A clickable row is reachable by Tab and activated by Enter
-                       * or Space. No role="button" — that would strip the row's
-                       * own role and break the table for screen readers — so the
-                       * keys are handled explicitly instead of coming free.
+                       * A row with `onRowClick` is reachable by Tab and activated
+                       * by Enter or Space. No role="button" — that would strip the
+                       * row's own role and break the table for screen readers — so
+                       * the keys are handled explicitly instead of coming free.
+                       * A row that is clickable only because the table has a
+                       * selection column is not a tab stop; its control is.
                        */
-                      data-clickable={clickable || undefined}
+                      data-clickable={isActivatable || undefined}
                       // The same attribute the whole-table skeleton rows carry, so
                       // .tr:not([data-loading]) already excludes a busy row from hover.
                       data-loading={isBusy || undefined}
@@ -988,15 +1072,19 @@ export const DataTableBody = <TRecord,>({
                       data-selected={isSelected || undefined}
                       data-testid={getRowTestId?.(row, isSelected)}
                       key={row.id}
-                      onClick={clickable ? (e) => onRowClick?.(row, e) : undefined}
+                      onClick={isActivatable ? (e) => activateRow?.(row, e) : undefined}
                       /*
                        * Still bound while busy, unlike onClick: the row keeps the focus
                        * it had when it went busy, so Space has to keep being swallowed
                        * or it would scroll the table under the user. Only the call to
                        * the caller drops out.
+                       *
+                       * Bound on `rowIsFocusable` rather than on `isActivatable`, which
+                       * folds in `isBusy` — gating on that would unbind the handler for
+                       * exactly the row that still needs it.
                        */
                       onKeyDown={
-                        onRowClick
+                        rowIsFocusable && activateRow
                           ? (event) => {
                               // Only the row itself: a button or link inside a cell
                               // handles its own keys, and its event bubbles here.
@@ -1008,14 +1096,17 @@ export const DataTableBody = <TRecord,>({
                               if (isBusy) {
                                 return;
                               }
-                              onRowClick(row, event);
+                              activateRow(row, event);
                             }
                           : undefined
                       }
-                      // -1 rather than no attribute while busy: out of the tab order
-                      // either way, but still focusable, so a row focused when it went
-                      // busy keeps focus instead of dropping it on <body>.
-                      tabIndex={onRowClick ? (isBusy ? -1 : 0) : undefined}
+                      /*
+                       * -1 rather than no attribute while busy: out of the tab order
+                       * either way, but still focusable, so a row focused when it went
+                       * busy keeps focus instead of dropping it on <body>. A row that was
+                       * never a tab stop has no focus to keep, so it stays absent.
+                       */
+                      tabIndex={rowIsFocusable ? (isBusy ? -1 : 0) : undefined}
                     >
                       {row.getVisibleCells().map((cell) => {
                         const content = flexRender(cell.column.columnDef.cell, cell.getContext());