feat(table): add onCheckedChange prop to CheckCell and CheckHead (#437)

Author: mattrothenberg

.changeset/table-on-checked-change.md

@@ -0,0 +1,21 @@
+---
+"@cloudflare/kumo": minor
+---
+
+feat(table): add `onCheckedChange` prop to `Table.CheckCell` and `Table.CheckHead`, aligning with the `Checkbox` component's signature.
+
+The new prop exposes an optional second argument with event details, matching Base UI's idiom:
+
+```tsx
+<Table.CheckCell
+  checked={selected.has(row.id)}
+  onCheckedChange={(checked, eventDetails) => {
+    toggle(row.id);
+    eventDetails?.event.stopPropagation();
+  }}
+/>
+```
+
+The existing `onValueChange` prop still works but is now deprecated and flagged by the `no-deprecated-props` lint rule. It will be removed in a future major version. Migrate by renaming the prop — the single-argument callback shape is preserved.
+
+This change is additive and does not require consumer code changes at this time.

packages/kumo-docs-astro/src/components/demos/TableDemo.tsx

@@ -108,7 +108,7 @@ export function TableWithCheckboxDemo() {
               indeterminate={
                 selectedIds.size > 0 && selectedIds.size < rows.length
               }
-              onValueChange={toggleAll}
+              onCheckedChange={toggleAll}
               aria-label="Select all rows"
             />
             <Table.Head>Subject</Table.Head>
@@ -121,7 +121,7 @@ export function TableWithCheckboxDemo() {
             <Table.Row key={row.id}>
               <Table.CheckCell
                 checked={selectedIds.has(row.id)}
-                onValueChange={() => toggleRow(row.id)}
+                onCheckedChange={() => toggleRow(row.id)}
                 aria-label={`Select ${row.subject}`}
               />
               <Table.Cell>{row.subject}</Table.Cell>
@@ -194,7 +194,7 @@ export function TableSelectedRowDemo() {
               indeterminate={
                 selectedIds.size > 0 && selectedIds.size < rows.length
               }
-              onValueChange={toggleAll}
+              onCheckedChange={toggleAll}
               aria-label="Select all rows"
             />
             <Table.Head>Subject</Table.Head>
@@ -210,7 +210,7 @@ export function TableSelectedRowDemo() {
             >
               <Table.CheckCell
                 checked={selectedIds.has(row.id)}
-                onValueChange={() => toggleRow(row.id)}
+                onCheckedChange={() => toggleRow(row.id)}
                 aria-label={`Select ${row.subject}`}
               />
               <Table.Cell>{row.subject}</Table.Cell>
@@ -450,7 +450,7 @@ export function TableFullDemo() {
               indeterminate={
                 selectedIds.size > 0 && selectedIds.size < emailData.length
               }
-              onValueChange={toggleAll}
+              onCheckedChange={toggleAll}
               aria-label="Select all rows"
             />
             <Table.Head>Subject</Table.Head>
@@ -467,7 +467,7 @@ export function TableFullDemo() {
             >
               <Table.CheckCell
                 checked={selectedIds.has(row.id)}
-                onValueChange={() => toggleRow(row.id)}
+                onCheckedChange={() => toggleRow(row.id)}
                 aria-label={`Select ${row.subject}`}
               />
               <Table.Cell>

packages/kumo-docs-astro/src/pages/components/table.mdx

@@ -90,7 +90,33 @@ export default function Example() {
 
 ### With Checkboxes
 
-<p>Add row selection with `Table.CheckHead` and `Table.CheckCell`.</p>
+<p>
+  Add row selection with `Table.CheckHead` and `Table.CheckCell`. Both accept
+  `onCheckedChange`, which matches the underlying `Checkbox` component's
+  signature and exposes optional event details as a second argument.
+</p>
+<p>
+  The older `onValueChange` prop still works but is deprecated — the lint
+  rule will flag it and it will be removed in a future major version. Migrate
+  by renaming the prop:
+</p>
+
+```tsx
+// Before (deprecated)
+<Table.CheckCell onValueChange={(checked) => toggleRow(id)} />
+
+// After
+<Table.CheckCell onCheckedChange={(checked) => toggleRow(id)} />
+
+// With event details
+<Table.CheckCell
+  onCheckedChange={(checked, eventDetails) => {
+    toggleRow(id);
+    eventDetails?.event.stopPropagation();
+  }}
+/>
+```
+
 <ComponentExample demo="TableWithCheckboxDemo">
   <TableWithCheckboxDemo client:visible />
 </ComponentExample>

packages/kumo/src/components/table/table.test.tsx

@@ -0,0 +1,70 @@
+import { describe, expect, it, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import { Table } from "./table";
+
+describe("Table.CheckCell / Table.CheckHead", () => {
+  it("calls onCheckedChange with the new checked state", async () => {
+    const onCheckedChange = vi.fn();
+    render(
+      <table>
+        <tbody>
+          <tr>
+            <Table.CheckCell
+              checked={false}
+              onCheckedChange={onCheckedChange}
+            />
+          </tr>
+        </tbody>
+      </table>,
+    );
+
+    const checkbox = screen.getByRole("checkbox");
+    checkbox.click();
+
+    expect(onCheckedChange).toHaveBeenCalledTimes(1);
+    expect(onCheckedChange.mock.calls[0][0]).toBe(true);
+    // second arg is optional event details object
+    expect(onCheckedChange.mock.calls[0][1]).toBeDefined();
+  });
+
+  it("still calls the deprecated onValueChange for backward compatibility", () => {
+    const onValueChange = vi.fn();
+    render(
+      <table>
+        <tbody>
+          <tr>
+            <Table.CheckCell checked={false} onValueChange={onValueChange} />
+          </tr>
+        </tbody>
+      </table>,
+    );
+
+    screen.getByRole("checkbox").click();
+
+    expect(onValueChange).toHaveBeenCalledTimes(1);
+    expect(onValueChange).toHaveBeenCalledWith(true);
+  });
+
+  it("calls both onCheckedChange and onValueChange when both are provided", () => {
+    const onCheckedChange = vi.fn();
+    const onValueChange = vi.fn();
+    render(
+      <table>
+        <thead>
+          <tr>
+            <Table.CheckHead
+              checked={false}
+              onCheckedChange={onCheckedChange}
+              onValueChange={onValueChange}
+            />
+          </tr>
+        </thead>
+      </table>,
+    );
+
+    screen.getByRole("checkbox").click();
+
+    expect(onCheckedChange).toHaveBeenCalledTimes(1);
+    expect(onValueChange).toHaveBeenCalledTimes(1);
+  });
+});

packages/kumo/src/components/table/table.tsx

@@ -1,6 +1,6 @@
 import { forwardRef } from "react";
 import { cn } from "../../utils";
-import { Checkbox } from "../checkbox";
+import { Checkbox, type CheckboxChangeEventDetails } from "../checkbox";
 
 /** Table layout and row variant definitions mapping names to their Tailwind classes. */
 export const KUMO_TABLE_VARIANTS = {
@@ -269,13 +269,31 @@ const TableCheckCell = forwardRef<
   React.TdHTMLAttributes<HTMLTableCellElement> & {
     checked?: boolean;
     indeterminate?: boolean;
+    /**
+     * Called when the checkbox's checked state changes. The optional second
+     * argument exposes event details from the underlying Checkbox, matching
+     * the Checkbox component's signature.
+     */
+    onCheckedChange?: (
+      checked: boolean,
+      eventDetails?: CheckboxChangeEventDetails,
+    ) => void;
+    /** @deprecated Use `onCheckedChange` instead. Will be removed in a future major version. */
     onValueChange?: (checked: boolean) => void;
     label?: string;
     disabled?: boolean;
   }
 >(
   (
-    { checked, indeterminate, onValueChange, label, disabled, ...props },
+    {
+      checked,
+      indeterminate,
+      onCheckedChange,
+      onValueChange,
+      label,
+      disabled,
+      ...props
+    },
     ref,
   ) => {
     return (
@@ -287,7 +305,8 @@ const TableCheckCell = forwardRef<
         <Checkbox
           checked={checked}
           indeterminate={indeterminate}
-          onCheckedChange={(newChecked) => {
+          onCheckedChange={(newChecked, eventDetails) => {
+            onCheckedChange?.(newChecked, eventDetails);
             onValueChange?.(newChecked);
           }}
           aria-label={label ?? "Select row"}
@@ -304,13 +323,31 @@ const TableCheckHead = forwardRef<
   React.ThHTMLAttributes<HTMLTableCellElement> & {
     checked?: boolean;
     indeterminate?: boolean;
+    /**
+     * Called when the checkbox's checked state changes. The optional second
+     * argument exposes event details from the underlying Checkbox, matching
+     * the Checkbox component's signature.
+     */
+    onCheckedChange?: (
+      checked: boolean,
+      eventDetails?: CheckboxChangeEventDetails,
+    ) => void;
+    /** @deprecated Use `onCheckedChange` instead. Will be removed in a future major version. */
     onValueChange?: (checked: boolean) => void;
     label?: string;
     disabled?: boolean;
   }
 >(
   (
-    { checked, indeterminate, onValueChange, label, disabled, ...props },
+    {
+      checked,
+      indeterminate,
+      onCheckedChange,
+      onValueChange,
+      label,
+      disabled,
+      ...props
+    },
     ref,
   ) => {
     return (
@@ -322,7 +359,8 @@ const TableCheckHead = forwardRef<
         <Checkbox
           checked={checked}
           indeterminate={indeterminate}
-          onCheckedChange={(newChecked) => {
+          onCheckedChange={(newChecked, eventDetails) => {
+            onCheckedChange?.(newChecked, eventDetails);
             onValueChange?.(newChecked);
           }}
           aria-label={label ?? "Select all rows"}
@@ -356,14 +394,14 @@ TableCheckHead.displayName = "Table.CheckHead";
  * <Table>
  *   <Table.Header>
  *     <Table.Row>
- *       <Table.CheckHead checked={allSelected} onValueChange={toggleAll} />
+ *       <Table.CheckHead checked={allSelected} onCheckedChange={toggleAll} />
  *       <Table.Head>Name</Table.Head>
  *     </Table.Row>
  *   </Table.Header>
  *   <Table.Body>
  *     {rows.map((row) => (
  *       <Table.Row key={row.id} variant={selected.has(row.id) ? "selected" : "default"}>
- *         <Table.CheckCell checked={selected.has(row.id)} onValueChange={() => toggle(row.id)} />
+ *         <Table.CheckCell checked={selected.has(row.id)} onCheckedChange={() => toggle(row.id)} />
  *         <Table.Cell>{row.name}</Table.Cell>
  *       </Table.Row>
  *     ))}