feat: onCellClick with native-button cells; fix Firefox HOME in CI e2e (B09)

Author: bronz3beard

.ai/output/features/react-data-matrix-1.0.feature

@@ -174,12 +174,24 @@ Feature: React Data Matrix 1.0
     Then every valid rating is still shown
     And a clear message names the rating that could not be placed
 
-  @planned @B09
+  @B09
   Scenario: A developer reacts to a cell being chosen
     Given a matrix with a cell selection handler
-    When a person chooses a cell by pointer or keyboard
+    When a person chooses a cell by pointer, Enter or Space
     Then the handler receives that cell's rating, likelihood and consequence
 
+  @B09
+  Scenario: Chosen cells are announced clearly
+    Given a matrix with a cell selection handler
+    Then every rating is a button named by its likelihood, consequence and rating
+    And a matrix without a handler shows its ratings as plain text
+
+  @B09
+  Scenario: Mistakes in the developer's handler are not hidden
+    Given a cell selection handler that fails
+    When a person chooses a cell
+    Then the failure reaches the host application
+
   @planned @B12
   Scenario: Every preset design is distinct
     Given all 26 preset designs

.github/workflows/ci.yml

@@ -56,6 +56,10 @@ jobs:
           persist-credentials: false
       - run: npm ci
       - run: npm run test:e2e
+        env:
+          # GitHub sets HOME=/github/home (owned by another user) in container jobs;
+          # Firefox refuses to run as root there. Playwright's documented workaround.
+          HOME: /root
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         if: failure()
         with:

e2e/site.spec.ts

@@ -43,6 +43,32 @@ test('the page never scrolls sideways; a wide matrix scrolls inside itself', asy
   expect(overflow).toBeLessThanOrEqual(0);
 });
 
+test('a cell can be chosen by pointer, Enter or Space', async ({ page }) => {
+  await page.goto('./');
+  const status = page.getByRole('status');
+
+  await page
+    .getByRole('button', { name: 'Likelihood Rare, Consequence Minor: low (1)' })
+    .click();
+  await expect(status).toHaveText('Rare × Minor: low (1). Business as usual.');
+
+  await page
+    .getByRole('button', { name: 'Likelihood Almost Certain, Consequence Catastrophic: extreme (25)' })
+    .focus();
+  await page.keyboard.press('Enter');
+  await expect(status).toHaveText(
+    'Almost Certain × Catastrophic: extreme (25). Activity should not commence.'
+  );
+
+  await page
+    .getByRole('button', { name: 'Likelihood Possible, Consequence Moderate: medium (8)' })
+    .focus();
+  await page.keyboard.press('Space');
+  await expect(status).toHaveText(
+    'Possible × Moderate: medium (8). Requires routine to periodic monitoring.'
+  );
+});
+
 test('a matrix that scrolls sideways can be scrolled from the keyboard', async ({ page }) => {
   await page.goto('./');
   const matrix = page.locator('.rdm-root');

lib/components/MatrixRows.tsx

@@ -1,19 +1,30 @@
 import type { GridRow } from '../grid.js';
 import type { SeverityColour } from '../theme/types.js';
-import type { MatrixDetail, MatrixSlotStyles } from '../types/index.js';
+import type { MatrixDetail, MatrixSlotStyles, ReactMatrixProps } from '../types/index.js';
 import TableData from './TableData.js';
 
 interface MatrixRowsProps {
-  title: string;
+  rowTitle: string;
+  columnTitle: string;
   columns: MatrixDetail[];
   rows: GridRow[];
   tiers: ReadonlyMap<string, number>;
   /** Severity colour per value id; `null` when unstyled. */
   colours: ReadonlyMap<number, SeverityColour> | null;
   styles: MatrixSlotStyles;
+  onCellClick?: ReactMatrixProps['onCellClick'];
 }
 
-const MatrixRows = ({ title, columns, rows, tiers, colours, styles }: MatrixRowsProps) => (
+const MatrixRows = ({
+  rowTitle,
+  columnTitle,
+  columns,
+  rows,
+  tiers,
+  colours,
+  styles,
+  onCellClick,
+}: MatrixRowsProps) => (
   <tbody>
     {rows.map(({ detail, cells }, rowIndex) => (
       <tr key={detail.id} data-row={detail.likelihood}>
@@ -24,24 +35,38 @@ const MatrixRows = ({ title, columns, rows, tiers, colours, styles }: MatrixRows
             rowSpan={rows.length}
             style={styles.axisTitle}
           >
-            {title}
+            {rowTitle}
           </th>
         )}
         <th className="rdm-row-header" scope="row" style={styles.rowHeader}>
           {detail.row_header_title}
           <div className="rdm-subtitle">{detail.row_header_sub_title}</div>
         </th>
-        {cells.map((value, columnIndex) => (
-          <TableData
-            key={value?.id ?? `empty-${columnIndex}`}
-            value={value}
-            row={detail.likelihood}
-            column={columns[columnIndex].consequence}
-            tier={value ? tiers.get(value.colour) : undefined}
-            colours={value ? colours?.get(value.id) : undefined}
-            style={styles.cell}
-          />
-        ))}
+        {cells.map((value, columnIndex) => {
+          const column = columns[columnIndex];
+          const interactive = value && onCellClick;
+          return (
+            <TableData
+              key={value?.id ?? `empty-${columnIndex}`}
+              value={value}
+              row={detail.likelihood}
+              column={column.consequence}
+              tier={value ? tiers.get(value.colour) : undefined}
+              colours={value ? colours?.get(value.id) : undefined}
+              style={styles.cell}
+              onActivate={
+                interactive
+                  ? (event) => onCellClick(value, { row: detail, column, event })
+                  : undefined
+              }
+              accessibleName={
+                interactive
+                  ? `${rowTitle} ${detail.row_header_title}, ${columnTitle} ${column.header_title}: ${value.description} (${value.score_value})`
+                  : undefined
+              }
+            />
+          );
+        })}
       </tr>
     ))}
   </tbody>

lib/components/TableData.tsx

@@ -1,4 +1,4 @@
-import type { CSSProperties } from 'react';
+import type { CSSProperties, MouseEvent } from 'react';
 import type { SeverityColour } from '../theme/types.js';
 import type { MatrixValue } from '../types/index.js';
 
@@ -9,12 +9,25 @@ interface TableDataProps {
   tier?: number;
   colours?: SeverityColour;
   style?: CSSProperties;
+  /** Set when the consumer passed `onCellClick`: the cell becomes a native button. */
+  onActivate?: (event: MouseEvent<HTMLButtonElement>) => void;
+  /** Row, column and rating, so the button makes sense outside the table's context. */
+  accessibleName?: string;
 }
 
 // One matrix cell. The severity colour arrives as --rdm-cell-bg/--rdm-cell-fg,
 // consumed only by colour properties in the base stylesheet; `data-tier` lets
 // unstyled (e.g. strict-CSP) consumers colour cells from their own CSS.
-const TableData = ({ value, row, column, tier, colours, style }: TableDataProps) => {
+const TableData = ({
+  value,
+  row,
+  column,
+  tier,
+  colours,
+  style,
+  onActivate,
+  accessibleName,
+}: TableDataProps) => {
   if (!value) {
     return (
       <td className="rdm-cell rdm-cell-empty" data-row={row} data-col={column} style={style} />
@@ -24,6 +37,13 @@ const TableData = ({ value, row, column, tier, colours, style }: TableDataProps)
   const colourVariables = colours
     ? { '--rdm-cell-bg': colours.bg, '--rdm-cell-fg': colours.fg }
     : undefined;
+  const content = (
+    <>
+      <span className="rdm-cell-label">{value.description}</span>
+      <br />
+      <span className="rdm-cell-score">{`(${value.score_value})`}</span>
+    </>
+  );
 
   return (
     <td
@@ -33,9 +53,19 @@ const TableData = ({ value, row, column, tier, colours, style }: TableDataProps)
       data-tier={tier}
       style={{ ...colourVariables, ...style }}
     >
-      <span className="rdm-cell-label">{value.description}</span>
-      <br />
-      <span className="rdm-cell-score">{`(${value.score_value})`}</span>
+      {onActivate ? (
+        // No try/catch: errors from the consumer's handler must surface, not vanish.
+        <button
+          type="button"
+          className="rdm-cell-button"
+          aria-label={accessibleName}
+          onClick={onActivate}
+        >
+          {content}
+        </button>
+      ) : (
+        content
+      )}
     </td>
   );
 };

lib/index.tsx

@@ -44,6 +44,7 @@ const ReactMatrix = ({
   unstyled = false,
   reverseMatrixValues = true,
   nonce,
+  onCellClick,
 }: ReactMatrixProps) => {
   const grid = useMemo(
     () => buildGrid(data, { reverse: reverseMatrixValues }),
@@ -102,7 +103,9 @@ const ReactMatrix = ({
           styles={styles}
         />
         <MatrixRows
-          title={data.primary_row_header_title}
+          rowTitle={data.primary_row_header_title}
+          columnTitle={data.primary_header_title}
+          onCellClick={onCellClick}
           columns={grid.columns}
           rows={grid.rows}
           tiers={scale.tiers}
@@ -117,6 +120,7 @@ const ReactMatrix = ({
 export default ReactMatrix;
 export { original } from './theme/presets/original.js';
 export type {
+  CellClickContext,
   MatrixData,
   MatrixDetail,
   MatrixRootStyle,

lib/types/index.ts

@@ -1,4 +1,4 @@
-import type { CSSProperties } from 'react';
+import type { CSSProperties, MouseEvent } from 'react';
 import type { MatrixTheme } from '../theme/types.js';
 
 export interface MatrixDetail {
@@ -48,6 +48,16 @@ export type MatrixSlot =
 
 export type MatrixSlotStyles = Partial<Record<MatrixSlot, CSSProperties>>;
 
+/** What `onCellClick` receives besides the cell itself. */
+export interface CellClickContext {
+  /** The likelihood row the cell is in. */
+  row: Readonly<MatrixDetail>;
+  /** The consequence column the cell is in. */
+  column: Readonly<MatrixDetail>;
+  /** Also fired by Enter and Space: each cell is a native button when a handler is set. */
+  event: MouseEvent<HTMLButtonElement>;
+}
+
 /** Root inline style; also accepts theme variable overrides like `--rdm-radius`. */
 export type MatrixRootStyle = CSSProperties & { [variable: `--rdm-${string}`]: string };
 
@@ -65,4 +75,10 @@ export interface ReactMatrixProps {
   reverseMatrixValues?: boolean;
   /** CSP nonce for the base <style> element. */
   nonce?: string;
+  /**
+   * Called when a person chooses a cell by pointer or keyboard. Without it, cells
+   * are plain text. The data is the consumer's own and is rendered as text only;
+   * never inject it as HTML in the handler.
+   */
+  onCellClick?: (cell: Readonly<MatrixValue>, context: CellClickContext) => void;
 }

src/App.tsx

@@ -1,14 +1,29 @@
+import { useState } from "react";
 import ReactMatrix, { type MatrixData } from "../lib";
 import IconsRow from "./components/iconsRow";
 import Footer from "./components/footer";
 
-// Demo page: the matrix with the default Original preset. The preset gallery
-// replaces this page later in the 1.0 work.
+// Demo page: the matrix with the default Original preset, showing the chosen
+// cell's response through `onCellClick`. The preset gallery replaces this page
+// later in the 1.0 work.
 function App({ data }: { data: MatrixData }) {
+  const [selection, setSelection] = useState("Choose a cell to see its response.");
+
   return (
     <>
       <IconsRow />
-      <ReactMatrix data={data} styles={{ table: { width: '70rem' } }} />
+      <ReactMatrix
+        data={data}
+        styles={{ table: { width: '70rem' } }}
+        onCellClick={(cell, { row, column }) =>
+          setSelection(
+            `${row.row_header_title} × ${column.header_title}: ${cell.description} (${cell.score_value}). ${cell.response}.`
+          )
+        }
+      />
+      <p role="status" style={{ textAlign: 'center' }}>
+        {selection}
+      </p>
       <Footer />
     </>
   );