From 01b0e5adbb8157fc2fcbd566c24d40206fab577c Mon Sep 17 00:00:00 2001
From: IzumiSy <beetle-noise@gmx.com>
Date: Tue, 13 Oct 2026 14:19:38 +0900
Subject: [PATCH 1/2] feat(data-table): add controlled and default row
 selection

---
 .changeset/clear-kites-select.md              |  13 +
 docs-manifest.json                            |   9 +-
 .../components/data-table.docs.outline.md     |  46 ++-
 docs/components/data-table.md                 |  46 ++-
 .../core/src/components/data-table/index.ts   |   1 +
 .../data-table/row-selection.test.tsx         | 310 ++++++++++++++++++
 .../core/src/components/data-table/types.ts   |  29 +-
 .../components/data-table/use-data-table.ts   | 111 +++++--
 packages/core/src/index.ts                    |   1 +
 9 files changed, 521 insertions(+), 45 deletions(-)
 create mode 100644 .changeset/clear-kites-select.md
 create mode 100644 packages/core/src/components/data-table/row-selection.test.tsx

diff --git a/.changeset/clear-kites-select.md b/.changeset/clear-kites-select.md
new file mode 100644
index 000000000..a810261c6
--- /dev/null
+++ b/.changeset/clear-kites-select.md
@@ -0,0 +1,13 @@
+---
+"@tailor-platform/app-shell": minor
+---
+
+Add controlled and uncontrolled row selection through `useDataTable`'s `rowSelection` option. Pass `selectedIds` with `onChange` to control selection, or `defaultSelectedIds` to initialize table-owned selection. The existing `onSelectionChange` callback remains supported.
+
+```tsx
+const table = useDataTable({
+  columns,
+  data,
+  rowSelection: { selectedIds, onChange: setSelectedIds },
+});
+```
diff --git a/docs-manifest.json b/docs-manifest.json
index 06036a7e7..b37762a98 100644
--- a/docs-manifest.json
+++ b/docs-manifest.json
@@ -421,6 +421,7 @@
         "PageInfo",
         "PaginationVariables",
         "RowAction",
+        "RowSelectionOptions",
         "SelectOption",
         "SelectionAction",
         "SelectionActionHelpers",
@@ -446,10 +447,10 @@
         "withURLCollectionState"
       ],
       "hashes": {
-        "typeSurface": "fe43108015be4a00",
-        "outline": "dc0b82256114191b",
+        "typeSurface": "6420153668673350",
+        "outline": "f0023a7c1ef0c535",
         "snapshot": null,
-        "outputMd": "3e8474e4d1437c91",
+        "outputMd": "af7a5f615cc91888",
         "examples": null
       }
     },
@@ -1693,7 +1694,7 @@
     "packages/core/skills/app-shell-patterns/references/components/combobox.md": "dfb775c7c4307409",
     "packages/core/skills/app-shell-patterns/references/components/command-palette.md": "7e5bc675a593791a",
     "packages/core/skills/app-shell-patterns/references/components/csv-importer.md": "53d3c795ca21b9dc",
-    "packages/core/skills/app-shell-patterns/references/components/data-table.md": "3e8474e4d1437c91",
+    "packages/core/skills/app-shell-patterns/references/components/data-table.md": "af7a5f615cc91888",
     "packages/core/skills/app-shell-patterns/references/components/date-picker.md": "f39002ad79625dc4",
     "packages/core/skills/app-shell-patterns/references/components/default-header.md": "375e55f4b12fa2be",
     "packages/core/skills/app-shell-patterns/references/components/default-sidebar.md": "3422388a0cc78571",
diff --git a/docs-src/components/data-table.docs.outline.md b/docs-src/components/data-table.docs.outline.md
index 8e4b23a06..d33737243 100644
--- a/docs-src/components/data-table.docs.outline.md
+++ b/docs-src/components/data-table.docs.outline.md
@@ -30,6 +30,7 @@ import {
   type DataTablePaginationProps,
   type DataTableAction,
   type RowAction,
+  type RowSelectionOptions,
   type SelectionAction,
   type UseDataTableOptions,
   type UseDataTableReturn,
@@ -228,7 +229,7 @@ By default `DataTable.Filters` renders the active filter chips plus the **Add fi
 | Rows selected and `total` is not provided | `Y row(s) selected`      |
 | No selection enabled and no `total`       | _(nothing displayed)_    |
 
-Row selection is enabled by providing `onSelectionChange` or `selectionActions` to `useDataTable`. The `total` value comes from `DataTableData.total`. While the footer shows the bulk-action bar (see [Selection actions](#selection-actions)), the bar owns the selection count and this text is omitted.
+Row selection is enabled by providing `rowSelection`, `onSelectionChange`, or a non-empty `selectionActions` array to `useDataTable`. The `total` value comes from `DataTableData.total`. While the footer shows the bulk-action bar (see [Selection actions](#selection-actions)), the bar owns the selection count and this text is omitted.
 
 When pagination changes page or page size, `DataTable.Table` resets its own scroll container to the top automatically. That applies whether navigation comes from the built-in `DataTable.Pagination` or from custom controls using the same table context.
 
@@ -376,9 +377,45 @@ The trigger is a native `<button>`, so Enter/Space activation and the focus ring
 
 **Known limitation — row count.** Detail rows are real `<tr>` elements, so a screen reader counts them: ten records with two expanded announces as twelve rows. Fixing this needs `aria-rowcount` plus explicit `aria-rowindex` on every row (with detail rows sharing their parent's index) and correct interaction with pagination; `role="presentation"` on the detail row would fix the count but remove the panel from screen-reader table navigation. Neither is implemented.
 
+## Row selection
+
+Pass `rowSelection` to `useDataTable` to enable the checkbox column. Rows must have a string or number `id`; selected ids are their string-normalized values, and rows without an id are excluded. An empty configuration (`rowSelection: {}`) enables uncontrolled selection without a notification callback.
+
+### Controlled selection
+
+Provide `selectedIds` and `onChange` together to own the selection. The `RowSelectionOptions` type requires `onChange` in controlled mode and rejects combining `selectedIds` with `defaultSelectedIds`.
+
+```tsx
+const [selectedIds, setSelectedIds] = useState<string[]>([]);
+
+const table = useDataTable<Order>({
+  columns,
+  data,
+  rowSelection: { selectedIds, onChange: setSelectedIds },
+});
+```
+
+Commands such as `toggleRowSelection(row)` request a new array through `onChange`; the rendered selection changes only when the owner updates `selectedIds`. Each command derives from the current committed value, so multiple commands before the owner commits share the same base. Compute batched changes yourself and set `selectedIds` directly instead of issuing repeated commands.
+
+### Uncontrolled selection
+
+Omit `selectedIds` to let the table own selection state. `defaultSelectedIds` initializes it only when the hook mounts; later changes to that default do not reset selection. `onChange` is optional.
+
+```tsx
+const table = useDataTable<Order>({
+  columns,
+  data,
+  rowSelection: { defaultSelectedIds: ["INV-1001"] },
+});
+```
+
+Keep the controlled/uncontrolled mode stable while mounted. Callbacks notify user-driven selection changes, not mounting or external `selectedIds` updates. The existing `onSelectionChange` option remains supported: `rowSelection.onChange` takes precedence when both callbacks are supplied, and `onSelectionChange` is used when the new configuration has no callback.
+
+Selection spans pages. The header checkbox adds or removes only the current page's rows, preserving ids selected on other pages; `clearSelection()` clears every page. `selectedRows` contains current-page rows in their latest version and off-page rows as last loaded. Selected ids whose rows have never been loaded are omitted from `selectedRows` until seen, so the selection count can exceed the number of available row objects. Bulk actions operate only on those available rows.
+
 ## Selection actions
 
-Pass `selectionActions` to `useDataTable` and, while at least one row is selected, `DataTable.Footer` becomes a bulk-action bar: the selection count, your actions, and a **Clear** button, with the footer's own children (usually `DataTable.Pagination`) kept alongside. Providing the option also enables row selection, so `onSelectionChange` is optional. There is nothing new to compose in JSX — just keep `DataTable.Footer` in the tree.
+Pass `selectionActions` to `useDataTable` and, while at least one row is selected, `DataTable.Footer` becomes a bulk-action bar: the selection count, your actions, and a **Clear** button, with the footer's own children (usually `DataTable.Pagination`) kept alongside. A non-empty array also enables row selection, so `rowSelection` and `onSelectionChange` are optional. There is nothing new to compose in JSX — just keep `DataTable.Footer` in the tree.
 
 ```tsx
 const table = useDataTable<Vendor>({
@@ -450,7 +487,8 @@ const table = useDataTable({
 | `onClickRow`        | `(row: TRow) => void`              | Called when the user clicks a row. Adds a pointer cursor to rows.                                                                                                               |
 | `tableId`           | `string`                           | Stable id used to persist per-user column layout (visibility, order, pinning) to `localStorage`. When omitted, column layout is in-memory only and resets on reload.            |
 | `rowActions`        | `RowAction<TRow>[]`                | Per-row action items rendered in a kebab-menu column. The column is omitted when empty or not provided.                                                                         |
-| `onSelectionChange` | `(ids: string[]) => void`          | Called with selected row IDs on change. Providing this (or `selectionActions`) enables the checkbox column. Rows must have a string or number `id`.                             |
+| `rowSelection`      | `RowSelectionOptions`              | Controlled `selectedIds` + `onChange`, or uncontrolled `defaultSelectedIds` + optional `onChange`. Providing even `{}` enables checkboxes. See [Row selection](#row-selection). |
+| `onSelectionChange` | `(ids: string[]) => void`          | Existing selection notification; enables checkboxes. Used when `rowSelection.onChange` is absent. Rows must have a string or number `id`.                                       |
 | `selectionActions`  | `SelectionAction<TRow>[]`          | Bulk actions shown in `DataTable.Footer` while rows are selected. A non-empty array also enables selection. See [Selection actions](#selection-actions).                        |
 | `rowExpansion`      | `RowExpansionOptions<TRow>`        | Expandable detail rows: `render`, plus optional `canExpand` / `getLabel`, and `expandedIds` + `onChange` together for controlled mode. See [Expandable rows](#expandable-rows). |
 | `sort`              | `false \| { multiple?: boolean }`  | Sort behaviour. `false` disables sorting entirely. `{ multiple: true }` enables multi-column sorting. Omit or pass `{}` for single-column sort (default).                       |
@@ -1054,7 +1092,7 @@ function MyCustomPagination() {
 }
 ```
 
-The selection is here too — `selectedIds`, `selectedRows` (each selected row as last loaded, across pages), `selectAllRows` / `deselectAllRows` for the current page, and `clearSelection` — for the rare case the built-in [selection actions](#selection-actions) bar doesn't fit.
+The selection is here too — `selectedIds`, `selectedRows` (each loaded selected row as last seen, across pages; unseen ids are omitted), `selectAllRows` / `deselectAllRows` for the current page, and `clearSelection` — for the rare case the built-in [selection actions](#selection-actions) bar doesn't fit.
 
 ## SDK Plugin (`@tailor-platform/sdk-plugin-app-shell`)
 
diff --git a/docs/components/data-table.md b/docs/components/data-table.md
index 5dcc4c8ff..9b1ccd111 100644
--- a/docs/components/data-table.md
+++ b/docs/components/data-table.md
@@ -24,6 +24,7 @@ import {
   type DataTablePaginationProps,
   type DataTableAction,
   type RowAction,
+  type RowSelectionOptions,
   type SelectionAction,
   type UseDataTableOptions,
   type UseDataTableReturn,
@@ -222,7 +223,7 @@ By default `DataTable.Filters` renders the active filter chips plus the **Add fi
 | Rows selected and `total` is not provided | `Y row(s) selected`      |
 | No selection enabled and no `total`       | _(nothing displayed)_    |
 
-Row selection is enabled by providing `onSelectionChange` or `selectionActions` to `useDataTable`. The `total` value comes from `DataTableData.total`. While the footer shows the bulk-action bar (see [Selection actions](#selection-actions)), the bar owns the selection count and this text is omitted.
+Row selection is enabled by providing `rowSelection`, `onSelectionChange`, or a non-empty `selectionActions` array to `useDataTable`. The `total` value comes from `DataTableData.total`. While the footer shows the bulk-action bar (see [Selection actions](#selection-actions)), the bar owns the selection count and this text is omitted.
 
 When pagination changes page or page size, `DataTable.Table` resets its own scroll container to the top automatically. That applies whether navigation comes from the built-in `DataTable.Pagination` or from custom controls using the same table context.
 
@@ -370,9 +371,45 @@ The trigger is a native `<button>`, so Enter/Space activation and the focus ring
 
 **Known limitation — row count.** Detail rows are real `<tr>` elements, so a screen reader counts them: ten records with two expanded announces as twelve rows. Fixing this needs `aria-rowcount` plus explicit `aria-rowindex` on every row (with detail rows sharing their parent's index) and correct interaction with pagination; `role="presentation"` on the detail row would fix the count but remove the panel from screen-reader table navigation. Neither is implemented.
 
+## Row selection
+
+Pass `rowSelection` to `useDataTable` to enable the checkbox column. Rows must have a string or number `id`; selected ids are their string-normalized values, and rows without an id are excluded. An empty configuration (`rowSelection: {}`) enables uncontrolled selection without a notification callback.
+
+### Controlled selection
+
+Provide `selectedIds` and `onChange` together to own the selection. The `RowSelectionOptions` type requires `onChange` in controlled mode and rejects combining `selectedIds` with `defaultSelectedIds`.
+
+```tsx
+const [selectedIds, setSelectedIds] = useState<string[]>([]);
+
+const table = useDataTable<Order>({
+  columns,
+  data,
+  rowSelection: { selectedIds, onChange: setSelectedIds },
+});
+```
+
+Commands such as `toggleRowSelection(row)` request a new array through `onChange`; the rendered selection changes only when the owner updates `selectedIds`. Each command derives from the current committed value, so multiple commands before the owner commits share the same base. Compute batched changes yourself and set `selectedIds` directly instead of issuing repeated commands.
+
+### Uncontrolled selection
+
+Omit `selectedIds` to let the table own selection state. `defaultSelectedIds` initializes it only when the hook mounts; later changes to that default do not reset selection. `onChange` is optional.
+
+```tsx
+const table = useDataTable<Order>({
+  columns,
+  data,
+  rowSelection: { defaultSelectedIds: ["INV-1001"] },
+});
+```
+
+Keep the controlled/uncontrolled mode stable while mounted. Callbacks notify user-driven selection changes, not mounting or external `selectedIds` updates. The existing `onSelectionChange` option remains supported: `rowSelection.onChange` takes precedence when both callbacks are supplied, and `onSelectionChange` is used when the new configuration has no callback.
+
+Selection spans pages. The header checkbox adds or removes only the current page's rows, preserving ids selected on other pages; `clearSelection()` clears every page. `selectedRows` contains current-page rows in their latest version and off-page rows as last loaded. Selected ids whose rows have never been loaded are omitted from `selectedRows` until seen, so the selection count can exceed the number of available row objects. Bulk actions operate only on those available rows.
+
 ## Selection actions
 
-Pass `selectionActions` to `useDataTable` and, while at least one row is selected, `DataTable.Footer` becomes a bulk-action bar: the selection count, your actions, and a **Clear** button, with the footer's own children (usually `DataTable.Pagination`) kept alongside. Providing the option also enables row selection, so `onSelectionChange` is optional. There is nothing new to compose in JSX — just keep `DataTable.Footer` in the tree.
+Pass `selectionActions` to `useDataTable` and, while at least one row is selected, `DataTable.Footer` becomes a bulk-action bar: the selection count, your actions, and a **Clear** button, with the footer's own children (usually `DataTable.Pagination`) kept alongside. A non-empty array also enables row selection, so `rowSelection` and `onSelectionChange` are optional. There is nothing new to compose in JSX — just keep `DataTable.Footer` in the tree.
 
 ```tsx
 const table = useDataTable<Vendor>({
@@ -444,7 +481,8 @@ const table = useDataTable({
 | `onClickRow`        | `(row: TRow) => void`              | Called when the user clicks a row. Adds a pointer cursor to rows.                                                                                                               |
 | `tableId`           | `string`                           | Stable id used to persist per-user column layout (visibility, order, pinning) to `localStorage`. When omitted, column layout is in-memory only and resets on reload.            |
 | `rowActions`        | `RowAction<TRow>[]`                | Per-row action items rendered in a kebab-menu column. The column is omitted when empty or not provided.                                                                         |
-| `onSelectionChange` | `(ids: string[]) => void`          | Called with selected row IDs on change. Providing this (or `selectionActions`) enables the checkbox column. Rows must have a string or number `id`.                             |
+| `rowSelection`      | `RowSelectionOptions`              | Controlled `selectedIds` + `onChange`, or uncontrolled `defaultSelectedIds` + optional `onChange`. Providing even `{}` enables checkboxes. See [Row selection](#row-selection). |
+| `onSelectionChange` | `(ids: string[]) => void`          | Existing selection notification; enables checkboxes. Used when `rowSelection.onChange` is absent. Rows must have a string or number `id`.                                       |
 | `selectionActions`  | `SelectionAction<TRow>[]`          | Bulk actions shown in `DataTable.Footer` while rows are selected. A non-empty array also enables selection. See [Selection actions](#selection-actions).                        |
 | `rowExpansion`      | `RowExpansionOptions<TRow>`        | Expandable detail rows: `render`, plus optional `canExpand` / `getLabel`, and `expandedIds` + `onChange` together for controlled mode. See [Expandable rows](#expandable-rows). |
 | `sort`              | `false \| { multiple?: boolean }`  | Sort behaviour. `false` disables sorting entirely. `{ multiple: true }` enables multi-column sorting. Omit or pass `{}` for single-column sort (default).                       |
@@ -1048,7 +1086,7 @@ function MyCustomPagination() {
 }
 ```
 
-The selection is here too — `selectedIds`, `selectedRows` (each selected row as last loaded, across pages), `selectAllRows` / `deselectAllRows` for the current page, and `clearSelection` — for the rare case the built-in [selection actions](#selection-actions) bar doesn't fit.
+The selection is here too — `selectedIds`, `selectedRows` (each loaded selected row as last seen, across pages; unseen ids are omitted), `selectAllRows` / `deselectAllRows` for the current page, and `clearSelection` — for the rare case the built-in [selection actions](#selection-actions) bar doesn't fit.
 
 ## SDK Plugin (`@tailor-platform/sdk-plugin-app-shell`)
 
diff --git a/packages/core/src/components/data-table/index.ts b/packages/core/src/components/data-table/index.ts
index bc72bb919..27f0f45a0 100644
--- a/packages/core/src/components/data-table/index.ts
+++ b/packages/core/src/components/data-table/index.ts
@@ -25,6 +25,7 @@ export type {
   NumberCellOptions,
   DataTableAction,
   RowAction,
+  RowSelectionOptions,
   SelectionAction,
   SelectionActionHelpers,
   UseDataTableOptions,
diff --git a/packages/core/src/components/data-table/row-selection.test.tsx b/packages/core/src/components/data-table/row-selection.test.tsx
new file mode 100644
index 000000000..1eb1c8c88
--- /dev/null
+++ b/packages/core/src/components/data-table/row-selection.test.tsx
@@ -0,0 +1,310 @@
+import { act, cleanup, fireEvent, render, renderHook, screen } from "@testing-library/react";
+import { useState } from "react";
+import { afterEach, describe, expect, expectTypeOf, it, vi } from "vitest";
+import type { RowSelectionOptions } from "@/index";
+import { createAppShellWrapper } from "../../../tests/test-utils";
+import { DataTable } from "./data-table";
+import { useDataTable } from "./use-data-table";
+import type { Column, DataTableData } from "./types";
+
+type Row = { id: string; name: string };
+const columns: Column<Row>[] = [{ label: "Name", render: (row) => row.name }];
+const pageA: DataTableData<Row> = {
+  rows: [
+    { id: "1", name: "Alice" },
+    { id: "2", name: "Bob" },
+  ],
+};
+const pageB: DataTableData<Row> = { rows: [{ id: "3", name: "Carol" }] };
+const wrapper = createAppShellWrapper("en");
+
+afterEach(() => cleanup());
+
+function renderControlled(
+  initialSelectedIds = ["1"],
+  initialData: DataTableData<Row> | undefined = pageA,
+) {
+  const onChange = vi.fn();
+  return {
+    ...renderHook(
+      ({ selectedIds, data }) =>
+        useDataTable({ columns, data, rowSelection: { selectedIds, onChange } }),
+      { initialProps: { selectedIds: initialSelectedIds, data: initialData } },
+    ),
+    onChange,
+  };
+}
+
+function ControlledTable({
+  selectedIds,
+  data,
+  onChange,
+  onBulk,
+}: {
+  selectedIds: string[];
+  data: DataTableData<Row>;
+  onChange: (ids: string[]) => void;
+  onBulk: (rows: Row[]) => void;
+}) {
+  const table = useDataTable({
+    columns,
+    data,
+    rowSelection: { selectedIds, onChange },
+    selectionActions: [{ id: "archive", label: "Archive", onClick: onBulk }],
+  });
+  return (
+    <DataTable.Root value={table}>
+      <DataTable.Table />
+      <DataTable.Footer />
+    </DataTable.Root>
+  );
+}
+
+describe("rowSelection", () => {
+  it("initializes uncontrolled selection once and composes changes in one commit", () => {
+    const onChange = vi.fn();
+    const { result, rerender } = renderHook(
+      ({ defaults }) =>
+        useDataTable({
+          columns,
+          data: pageA,
+          rowSelection: { defaultSelectedIds: defaults, onChange },
+        }),
+      { initialProps: { defaults: ["1"] } },
+    );
+    expect(result.current.selectedIds).toEqual(["1"]);
+    expect(onChange).not.toHaveBeenCalled();
+    rerender({ defaults: ["2"] });
+    expect(result.current.selectedIds).toEqual(["1"]);
+    act(() => {
+      result.current.clearSelection!();
+      result.current.toggleRowSelection!(pageA.rows[1]);
+    });
+    expect(result.current.selectedIds).toEqual(["2"]);
+    expect(onChange).toHaveBeenLastCalledWith(["2"]);
+  });
+
+  it("notifies once per interaction under StrictMode", () => {
+    const onChange = vi.fn();
+    const { result } = renderHook(
+      () => useDataTable({ columns, data: pageA, rowSelection: { onChange } }),
+      { reactStrictMode: true },
+    );
+    act(() => result.current.toggleRowSelection!(pageA.rows[0]));
+    expect(onChange).toHaveBeenCalledExactlyOnceWith(["1"]);
+  });
+
+  it.each([false, true])("uses the new callback when supplied: %s", (useNewCallback) => {
+    const legacy = vi.fn();
+    const current = vi.fn();
+    const { result } = renderHook(() =>
+      useDataTable({
+        columns,
+        data: pageA,
+        onSelectionChange: legacy,
+        rowSelection: { onChange: useNewCallback ? current : undefined },
+      }),
+    );
+    expect(legacy).not.toHaveBeenCalled();
+    expect(current).not.toHaveBeenCalled();
+    act(() => result.current.toggleRowSelection!(pageA.rows[0]));
+    expect(useNewCallback ? current : legacy).toHaveBeenCalledExactlyOnceWith(["1"]);
+    expect(useNewCallback ? legacy : current).not.toHaveBeenCalled();
+    expect(result.current.selectedIds).toEqual(["1"]);
+  });
+
+  it("waits for controlled props, including externally changed selection", () => {
+    const { result, rerender, onChange } = renderControlled([]);
+    act(() => result.current.toggleRowSelection!(pageA.rows[0]));
+    expect(onChange).toHaveBeenCalledExactlyOnceWith(["1"]);
+    expect(result.current.selectedIds).toEqual([]);
+    expect(result.current.isRowSelected(pageA.rows[0])).toBe(false);
+    rerender({ selectedIds: ["2"], data: pageA });
+    expect(result.current.selectedIds).toEqual(["2"]);
+    expect(result.current.selectedRows).toEqual([pageA.rows[1]]);
+    expect(onChange).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps controlled proposals page-scoped and retains history when clear is rejected", () => {
+    const { result, rerender, onChange } = renderControlled(["1", "3"]);
+    rerender({ selectedIds: ["1", "3"], data: pageB });
+    act(() => result.current.deselectAllRows!());
+    expect(onChange).toHaveBeenLastCalledWith(["1"]);
+    expect(result.current.selectedIds).toEqual(["1", "3"]);
+    act(() => result.current.clearSelection!());
+    expect(onChange).toHaveBeenLastCalledWith([]);
+    expect(result.current.selectedRows).toEqual([pageA.rows[0], pageB.rows[0]]);
+    rerender({ selectedIds: ["1"], data: pageB });
+    act(() => result.current.selectAllRows!());
+    expect(onChange).toHaveBeenLastCalledWith(["1", "3"]);
+    expect(result.current.selectedIds).toEqual(["1"]);
+    expect(result.current.selectedRows).toEqual([pageA.rows[0]]);
+  });
+
+  it("derives repeated controlled commands from the owner's committed ids", () => {
+    const { result, onChange } = renderControlled([]);
+    act(() => {
+      result.current.toggleRowSelection!(pageA.rows[0]);
+      result.current.toggleRowSelection!(pageA.rows[1]);
+    });
+    expect(onChange.mock.calls).toEqual([[["1"]], [["2"]]]);
+    expect(result.current.selectedIds).toEqual([]);
+  });
+
+  it.each(["controlled", "uncontrolled"] as const)(
+    "remembers loaded preselected rows in %s mode",
+    (mode) => {
+      const onChange = vi.fn();
+      const ids = ["1", "unseen"];
+      const { result, rerender } = renderHook(
+        ({ data }: { data: DataTableData<Row> | undefined }) =>
+          useDataTable({
+            columns,
+            data,
+            rowSelection:
+              mode === "controlled"
+                ? { selectedIds: ids, onChange }
+                : { defaultSelectedIds: ids, onChange },
+          }),
+        { initialProps: { data: undefined as DataTableData<Row> | undefined } },
+      );
+      expect(result.current.selectedIds).toEqual(ids);
+      expect(result.current.selectedRows).toEqual([]);
+      rerender({ data: pageA });
+      expect(result.current.selectedRows).toEqual([pageA.rows[0]]);
+      const updated = { id: "1", name: "Alice updated" };
+      rerender({ data: { rows: [updated] } });
+      rerender({ data: pageB });
+      expect(result.current.selectedRows).toEqual([updated]);
+      expect(onChange).not.toHaveBeenCalled();
+    },
+  );
+
+  it("keeps refetched uncontrolled rows when selection changes on another page", () => {
+    const { result, rerender } = renderHook(
+      ({ data }) => useDataTable({ columns, data, rowSelection: {} }),
+      { initialProps: { data: pageA } },
+    );
+    act(() => result.current.toggleRowSelection!(pageA.rows[0]));
+    const updated = { id: "1", name: "Alice updated" };
+    rerender({ data: { rows: [updated] } });
+    rerender({ data: pageB });
+    expect(result.current.selectedRows).toEqual([updated]);
+    act(() => result.current.selectAllRows!());
+    expect(result.current.selectedRows).toEqual([updated, pageB.rows[0]]);
+    act(() => result.current.deselectAllRows!());
+    expect(result.current.selectedRows).toEqual([updated]);
+  });
+
+  it("remembers external preselection without any table interaction", () => {
+    const { result, rerender, onChange } = renderControlled([]);
+    rerender({ selectedIds: ["2"], data: pageA });
+    rerender({ selectedIds: ["2"], data: pageB });
+    expect(result.current.selectedRows).toEqual([pageA.rows[1]]);
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it("remembers a toggled row when its owner selects it and changes page in the same commit", () => {
+    const { result } = renderHook(() => {
+      const [state, setState] = useState({ selectedIds: [] as string[], data: pageA });
+      return useDataTable({
+        columns,
+        data: state.data,
+        rowSelection: {
+          selectedIds: state.selectedIds,
+          onChange: (selectedIds) => setState({ selectedIds, data: pageB }),
+        },
+      });
+    });
+    act(() => result.current.toggleRowSelection!(pageA.rows[0]));
+    expect(result.current.rows).toEqual(pageB.rows);
+    expect(result.current.selectedRows).toEqual([pageA.rows[0]]);
+  });
+
+  it("handles fresh inline selected ids and rows without a render loop", () => {
+    const onChange = vi.fn();
+    const { result, rerender } = renderHook(() =>
+      useDataTable({
+        columns,
+        data: { rows: [{ id: "1", name: "Alice" }] },
+        rowSelection: { selectedIds: ["1"], onChange },
+      }),
+    );
+    rerender();
+    expect(result.current.selectedRows).toEqual([pageA.rows[0]]);
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  it.each([{ selectedIds: [] }, { selectedIds: ["2"] }])(
+    "consults the latest selection and callback when an action settles: %j",
+    async ({ selectedIds }) => {
+      const first = vi.fn();
+      const latest = vi.fn();
+      let resolve!: () => void;
+      const request = new Promise<void>((done) => {
+        resolve = done;
+      });
+      const { result, rerender } = renderHook(
+        ({ ids, onChange }) =>
+          useDataTable({ columns, data: pageA, rowSelection: { selectedIds: ids, onChange } }),
+        { initialProps: { ids: ["1"], onChange: first } },
+      );
+      act(() => result.current.runSelectionAction!({ id: "archive" }, request));
+      rerender({ ids: selectedIds, onChange: latest });
+      await act(async () => {
+        resolve();
+        await request;
+      });
+      expect(first).not.toHaveBeenCalled();
+      if (selectedIds.length) expect(latest).toHaveBeenCalledExactlyOnceWith([]);
+      else expect(latest).not.toHaveBeenCalled();
+      expect(result.current.pendingActionId).toBeNull();
+    },
+  );
+
+  it("drives real checkboxes and bulk actions from controlled selection", () => {
+    const onChange = vi.fn();
+    const onBulk = vi.fn();
+    const { rerender } = render(
+      <ControlledTable selectedIds={[]} data={pageA} onChange={onChange} onBulk={onBulk} />,
+      { wrapper },
+    );
+    const checkbox = screen.getAllByLabelText("Select row")[0];
+    fireEvent.click(checkbox);
+    expect(onChange).toHaveBeenCalledExactlyOnceWith(["1"]);
+    expect(checkbox.getAttribute("aria-checked")).toBe("false");
+    rerender(
+      <ControlledTable selectedIds={["1"]} data={pageA} onChange={onChange} onBulk={onBulk} />,
+    );
+    expect(screen.getAllByLabelText("Select row")[0].getAttribute("aria-checked")).toBe("true");
+    rerender(
+      <ControlledTable selectedIds={["1"]} data={pageB} onChange={onChange} onBulk={onBulk} />,
+    );
+    fireEvent.click(screen.getByRole("button", { name: "Archive" }));
+    expect(onBulk).toHaveBeenCalledWith(
+      [pageA.rows[0]],
+      expect.objectContaining({ clearSelection: expect.any(Function) }),
+    );
+    rerender(
+      <ControlledTable selectedIds={["unseen"]} data={pageB} onChange={onChange} onBulk={onBulk} />,
+    );
+    const archive = screen.getByRole("button", { name: "Archive" });
+    expect(archive.hasAttribute("disabled")).toBe(true);
+    fireEvent.click(archive);
+    expect(onBulk).toHaveBeenCalledTimes(1);
+  });
+
+  it("requires an owner callback for controlled ids and rejects mixing controlled/default ids", () => {
+    expectTypeOf<{ selectedIds: string[] }>().not.toMatchTypeOf<RowSelectionOptions>();
+    expectTypeOf<{
+      selectedIds: string[];
+      onChange: (ids: string[]) => void;
+      defaultSelectedIds: string[];
+    }>().not.toMatchTypeOf<RowSelectionOptions>();
+    expectTypeOf<{
+      selectedIds: string[];
+      onChange: (ids: string[]) => void;
+    }>().toMatchTypeOf<RowSelectionOptions>();
+    expectTypeOf<{ defaultSelectedIds: string[] }>().toMatchTypeOf<RowSelectionOptions>();
+  });
+});
diff --git a/packages/core/src/components/data-table/types.ts b/packages/core/src/components/data-table/types.ts
index 513ab4813..e85aec5d3 100644
--- a/packages/core/src/components/data-table/types.ts
+++ b/packages/core/src/components/data-table/types.ts
@@ -397,6 +397,25 @@ export type RowExpansionOptions<TRow extends Record<string, unknown>> = {
     }
 );
 
+/** Controlled or uncontrolled row-selection configuration. Keep the mode stable while mounted. */
+export type RowSelectionOptions =
+  | {
+      /**
+       * Controlled selected ids. Update this array from `onChange`.
+       * Commands issued before the owner commits each derive from this value.
+       */
+      selectedIds: string[];
+      onChange: (ids: string[]) => void;
+      defaultSelectedIds?: never;
+    }
+  | {
+      selectedIds?: never;
+      /** Initial selected ids in uncontrolled mode; subsequent changes are ignored. */
+      defaultSelectedIds?: string[];
+      /** Notification of user-driven selection changes, including under StrictMode. */
+      onChange?: (ids: string[]) => void;
+    };
+
 /**
  * Options for `useDataTable` hook.
  */
@@ -434,11 +453,18 @@ export type UseDataTableOptions<
    * The column is omitted when this array is empty or not provided.
    */
   rowActions?: RowAction<TRow>[];
+  /**
+   * Controlled or uncontrolled row selection. Providing this option enables
+   * checkboxes. Uses string-normalized `row.id`; rows without an id are excluded.
+   * The header checkbox adds/removes only the current page, preserving other ids.
+   */
+  rowSelection?: RowSelectionOptions;
   /**
    * Called with the current array of selected row IDs whenever the selection
    * changes. Providing this prop — or a non-empty `selectionActions` — enables
    * the checkbox selection column. Selection is ID-based (`row.id`) and persists
-   * across page changes.
+   * across page changes. Remains supported; `rowSelection.onChange` takes
+   * precedence when both callbacks are supplied.
    *
    * **Requirement:** Each row must have a string or number `id` field.
    * Rows without `id` are excluded from selection.
@@ -668,6 +694,7 @@ export interface UseDataTableReturn<TRow extends Record<string, unknown>> {
   /**
    * The selected rows, in selection order. Rows on the current page are their
    * latest version; rows selected on other pages are the version last loaded.
+   * Selected ids whose rows have not been loaded are omitted until they are seen.
    */
   selectedRows: TRow[];
   isRowSelected: (row: TRow) => boolean;
diff --git a/packages/core/src/components/data-table/use-data-table.ts b/packages/core/src/components/data-table/use-data-table.ts
index 05d854515..c0aa7d1b9 100644
--- a/packages/core/src/components/data-table/use-data-table.ts
+++ b/packages/core/src/components/data-table/use-data-table.ts
@@ -1,4 +1,4 @@
-import { useCallback, useMemo, useRef, useState } from "react";
+import { useCallback, useLayoutEffect, useMemo, useRef, useState } from "react";
 import type { CollectionControl, Filter, PageInfo, SortState } from "@/types/collection";
 import { usePageCounter } from "./use-page-counter";
 import { usePersistentColumnState, type PersistedColumnState } from "./use-persistent-column-state";
@@ -29,6 +29,24 @@ function reconcileColumnOrder(order: string[], columnKeys: string[]): string[] {
   return result;
 }
 
+function createSelectedRowHistory<TRow>() {
+  const remembered = new Map<string, TRow>();
+  return {
+    get: (id: string) => remembered.get(id),
+    remember: (id: string, row: TRow) => remembered.set(id, row),
+    commit: (ids: string[], rows: TRow[], getId: (row: TRow) => string | null) => {
+      const selected = new Set(ids);
+      for (const id of remembered.keys()) {
+        if (!selected.has(id)) remembered.delete(id);
+      }
+      for (const row of rows) {
+        const id = getId(row);
+        if (id !== null && selected.has(id)) remembered.set(id, row);
+      }
+    },
+  };
+}
+
 /**
  * Hook that integrates data management, column visibility, row operations, and
  * sort/pagination state for the `DataTable.*` compound component.
@@ -75,6 +93,7 @@ export function useDataTable<
     onClickRow,
     rowActions,
     onSelectionChange,
+    rowSelection,
     selectionActions,
     rowExpansion,
     sort: sortOption,
@@ -286,49 +305,65 @@ export function useDataTable<
     return id != null ? String(id) : null;
   }, []);
 
-  // Bulk actions need rows to act on, so offering them turns selection on even
-  // without an `onSelectionChange` listener.
-  const selectionEnabled = !!onSelectionChange || (selectionActions?.length ?? 0) > 0;
-
-  // Selected ids in selection order, each mapped to the row as last seen. The
-  // row is kept so rows selected on other pages can still be counted and handed
-  // to `selectionActions`; `selectedRows` below prefers the current page's copy.
-  const [selection, setSelection] = useState<Map<string, TRow>>(() => new Map());
-  // Mirrors the state so the toggle can compute the next map outside an updater.
-  // Every writer below must also assign it: this render-time sync only catches
-  // up on commit, so without an eager write two dispatches in the same commit
-  // both read the same base and the first is lost. A functional updater got
-  // this for free from `prev`; computing outside one makes it our job.
-  const selectionRef = useRef(selection);
-  selectionRef.current = selection;
+  const selectionEnabled =
+    rowSelection !== undefined || !!onSelectionChange || (selectionActions?.length ?? 0) > 0;
+  const controlledSelectedIds = rowSelection?.selectedIds;
+  const selectionOnChange = rowSelection?.onChange ?? onSelectionChange;
+  const [uncontrolledSelection, setSelection] = useState<Map<string, TRow | undefined>>(
+    () => new Map(rowSelection?.defaultSelectedIds?.map((id) => [id, undefined])),
+  );
+  // Keep uncontrolled commands composable before React commits their state.
+  const selectionRef = useRef(uncontrolledSelection);
+  selectionRef.current = uncontrolledSelection;
+  const selectionOwnerRef = useRef({
+    selectedIds: controlledSelectedIds,
+    onChange: selectionOnChange,
+  });
+  const [rowHistory] = useState(createSelectedRowHistory<TRow>);
+  const selection = useMemo(
+    () =>
+      controlledSelectedIds !== undefined
+        ? new Map<string, TRow | undefined>(controlledSelectedIds.map((id) => [id, undefined]))
+        : uncontrolledSelection,
+    [controlledSelectedIds, uncontrolledSelection],
+  );
 
   const isRowSelected = useCallback(
     (row: TRow) => {
       const id = getRowId(row);
-      if (id === null) return false;
-      return selection.has(id);
+      return id !== null && selection.has(id);
     },
     [selection, getRowId],
   );
 
-  // Computed outside the updater: updaters must be pure, and StrictMode
-  // double-invokes them, so dispatching from inside fired `onSelectionChange`
-  // twice per toggle in dev. Every writer goes through here.
-  const commitSelection = (next: Map<string, TRow>) => {
-    selectionRef.current = next;
-    setSelection(next);
-    onSelectionChange?.([...next.keys()]);
+  // Async bulk-action completion must consult the current committed owner too.
+  const currentSelection = () => {
+    const ids = selectionOwnerRef.current.selectedIds;
+    return ids !== undefined
+      ? new Map(ids.map((id) => [id, rowHistory.get(id)]))
+      : new Map(selectionRef.current);
   };
 
+  // Notify outside the updater so StrictMode cannot invoke the callback twice.
+  const commitSelection = (next: Map<string, TRow | undefined>) => {
+    if (selectionOwnerRef.current.selectedIds === undefined) {
+      selectionRef.current = next;
+      setSelection(next);
+    }
+    selectionOwnerRef.current.onChange?.([...next.keys()]);
+  };
+
+  // Remember new event rows before an owner can also change page in the same commit.
   const toggleRowSelection = selectionEnabled
     ? (row: TRow) => {
         const id = getRowId(row);
         if (id === null) return;
-        const next = new Map(selectionRef.current);
+        const next = currentSelection();
         if (next.has(id)) {
           next.delete(id);
         } else {
           next.set(id, row);
+          rowHistory.remember(id, row);
         }
         commitSelection(next);
       }
@@ -338,10 +373,13 @@ export function useDataTable<
   // header checkbox never silently drops part of a cross-page selection.
   const selectAllRows = selectionEnabled
     ? () => {
-        const next = new Map(selectionRef.current);
+        const next = currentSelection();
         for (const row of rows) {
           const id = getRowId(row);
-          if (id !== null) next.set(id, row);
+          if (id !== null) {
+            next.set(id, row);
+            rowHistory.remember(id, row);
+          }
         }
         commitSelection(next);
       }
@@ -349,7 +387,7 @@ export function useDataTable<
 
   const deselectAllRows = selectionEnabled
     ? () => {
-        const next = new Map(selectionRef.current);
+        const next = currentSelection();
         for (const row of rows) {
           const id = getRowId(row);
           if (id !== null) next.delete(id);
@@ -363,7 +401,7 @@ export function useDataTable<
   // and that second call must not fire another `onSelectionChange([])`.
   const clearSelection = selectionEnabled
     ? () => {
-        if (selectionRef.current.size === 0) return;
+        if (currentSelection().size === 0) return;
         commitSelection(new Map());
       }
     : undefined;
@@ -407,14 +445,23 @@ export function useDataTable<
 
   const selectedIds = useMemo(() => [...selection.keys()], [selection]);
 
+  // Record committed row history without publishing mirrored state or extra renders.
+  useLayoutEffect(() => {
+    selectionOwnerRef.current = { selectedIds: controlledSelectedIds, onChange: selectionOnChange };
+    rowHistory.commit(selectedIds, rows, getRowId);
+  }, [controlledSelectedIds, selectionOnChange, selectedIds, rows, getRowId, rowHistory]);
+
   const selectedRows = useMemo(() => {
     const onPage = new Map<string, TRow>();
     for (const row of rows) {
       const id = getRowId(row);
       if (id !== null && selection.has(id)) onPage.set(id, row);
     }
-    return [...selection].map(([id, lastSeen]) => onPage.get(id) ?? lastSeen);
-  }, [selection, rows, getRowId]);
+    return selectedIds.flatMap((id) => {
+      const row = onPage.get(id) ?? rowHistory.get(id);
+      return row === undefined ? [] : [row];
+    });
+  }, [selection, selectedIds, rows, getRowId, rowHistory]);
 
   const selectableCount = rows.filter((r) => getRowId(r) !== null).length;
   const isAllSelected =
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 9a4cde02d..ba373cb82 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -311,6 +311,7 @@ export {
   type UseDataTableReturn,
   type MetadataFieldOptions,
   type DataTableContextValue,
+  type RowSelectionOptions,
 } from "./components/data-table";
 export { useCollectionVariables } from "./hooks/use-collection-variables";
 export { useURLCollectionVariables, withURLCollectionState } from "./lib/collection-url-state";

From 0e60a0bf66de7ba8fdb3860b87a7ba4c495b80e7 Mon Sep 17 00:00:00 2001
From: IzumiSy <beetle-noise@gmx.com>
Date: Tue, 13 Oct 2026 14:27:13 +0900
Subject: [PATCH 2/2] docs(data-table): deprecate legacy selection callback

---
 .changeset/clear-kites-select.md                 | 2 +-
 docs-manifest.json                               | 6 +++---
 docs-src/components/data-table.docs.outline.md   | 4 ++--
 docs/components/data-table.md                    | 4 ++--
 packages/core/src/components/data-table/types.ts | 2 ++
 5 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/.changeset/clear-kites-select.md b/.changeset/clear-kites-select.md
index a810261c6..b6bd62c55 100644
--- a/.changeset/clear-kites-select.md
+++ b/.changeset/clear-kites-select.md
@@ -2,7 +2,7 @@
 "@tailor-platform/app-shell": minor
 ---
 
-Add controlled and uncontrolled row selection through `useDataTable`'s `rowSelection` option. Pass `selectedIds` with `onChange` to control selection, or `defaultSelectedIds` to initialize table-owned selection. The existing `onSelectionChange` callback remains supported.
+Add controlled and uncontrolled row selection through `useDataTable`'s `rowSelection` option. Pass `selectedIds` with `onChange` to control selection, or `defaultSelectedIds` to initialize table-owned selection. The existing `onSelectionChange` callback is deprecated in favor of `rowSelection.onChange`, but remains supported for compatibility.
 
 ```tsx
 const table = useDataTable({
diff --git a/docs-manifest.json b/docs-manifest.json
index b37762a98..6181d4702 100644
--- a/docs-manifest.json
+++ b/docs-manifest.json
@@ -448,9 +448,9 @@
       ],
       "hashes": {
         "typeSurface": "6420153668673350",
-        "outline": "f0023a7c1ef0c535",
+        "outline": "8a885df3785f3a03",
         "snapshot": null,
-        "outputMd": "af7a5f615cc91888",
+        "outputMd": "8848cda0fe63b441",
         "examples": null
       }
     },
@@ -1694,7 +1694,7 @@
     "packages/core/skills/app-shell-patterns/references/components/combobox.md": "dfb775c7c4307409",
     "packages/core/skills/app-shell-patterns/references/components/command-palette.md": "7e5bc675a593791a",
     "packages/core/skills/app-shell-patterns/references/components/csv-importer.md": "53d3c795ca21b9dc",
-    "packages/core/skills/app-shell-patterns/references/components/data-table.md": "af7a5f615cc91888",
+    "packages/core/skills/app-shell-patterns/references/components/data-table.md": "8848cda0fe63b441",
     "packages/core/skills/app-shell-patterns/references/components/date-picker.md": "f39002ad79625dc4",
     "packages/core/skills/app-shell-patterns/references/components/default-header.md": "375e55f4b12fa2be",
     "packages/core/skills/app-shell-patterns/references/components/default-sidebar.md": "3422388a0cc78571",
diff --git a/docs-src/components/data-table.docs.outline.md b/docs-src/components/data-table.docs.outline.md
index d33737243..1cb633898 100644
--- a/docs-src/components/data-table.docs.outline.md
+++ b/docs-src/components/data-table.docs.outline.md
@@ -409,7 +409,7 @@ const table = useDataTable<Order>({
 });
 ```
 
-Keep the controlled/uncontrolled mode stable while mounted. Callbacks notify user-driven selection changes, not mounting or external `selectedIds` updates. The existing `onSelectionChange` option remains supported: `rowSelection.onChange` takes precedence when both callbacks are supplied, and `onSelectionChange` is used when the new configuration has no callback.
+Keep the controlled/uncontrolled mode stable while mounted. Callbacks notify user-driven selection changes, not mounting or external `selectedIds` updates. `onSelectionChange` is deprecated but remains supported for compatibility. Replace `onSelectionChange: handleSelectionChange` with `rowSelection: { onChange: handleSelectionChange }` to keep uncontrolled notification behavior. `rowSelection.onChange` takes precedence when both callbacks are supplied, and `onSelectionChange` is used when the new configuration has no callback.
 
 Selection spans pages. The header checkbox adds or removes only the current page's rows, preserving ids selected on other pages; `clearSelection()` clears every page. `selectedRows` contains current-page rows in their latest version and off-page rows as last loaded. Selected ids whose rows have never been loaded are omitted from `selectedRows` until seen, so the selection count can exceed the number of available row objects. Bulk actions operate only on those available rows.
 
@@ -488,7 +488,7 @@ const table = useDataTable({
 | `tableId`           | `string`                           | Stable id used to persist per-user column layout (visibility, order, pinning) to `localStorage`. When omitted, column layout is in-memory only and resets on reload.            |
 | `rowActions`        | `RowAction<TRow>[]`                | Per-row action items rendered in a kebab-menu column. The column is omitted when empty or not provided.                                                                         |
 | `rowSelection`      | `RowSelectionOptions`              | Controlled `selectedIds` + `onChange`, or uncontrolled `defaultSelectedIds` + optional `onChange`. Providing even `{}` enables checkboxes. See [Row selection](#row-selection). |
-| `onSelectionChange` | `(ids: string[]) => void`          | Existing selection notification; enables checkboxes. Used when `rowSelection.onChange` is absent. Rows must have a string or number `id`.                                       |
+| `onSelectionChange` | `(ids: string[]) => void`          | **Deprecated:** use `rowSelection.onChange`. Still supported for compatibility; enables checkboxes and is used when the new callback is absent.                                 |
 | `selectionActions`  | `SelectionAction<TRow>[]`          | Bulk actions shown in `DataTable.Footer` while rows are selected. A non-empty array also enables selection. See [Selection actions](#selection-actions).                        |
 | `rowExpansion`      | `RowExpansionOptions<TRow>`        | Expandable detail rows: `render`, plus optional `canExpand` / `getLabel`, and `expandedIds` + `onChange` together for controlled mode. See [Expandable rows](#expandable-rows). |
 | `sort`              | `false \| { multiple?: boolean }`  | Sort behaviour. `false` disables sorting entirely. `{ multiple: true }` enables multi-column sorting. Omit or pass `{}` for single-column sort (default).                       |
diff --git a/docs/components/data-table.md b/docs/components/data-table.md
index 9b1ccd111..92157bd87 100644
--- a/docs/components/data-table.md
+++ b/docs/components/data-table.md
@@ -403,7 +403,7 @@ const table = useDataTable<Order>({
 });
 ```
 
-Keep the controlled/uncontrolled mode stable while mounted. Callbacks notify user-driven selection changes, not mounting or external `selectedIds` updates. The existing `onSelectionChange` option remains supported: `rowSelection.onChange` takes precedence when both callbacks are supplied, and `onSelectionChange` is used when the new configuration has no callback.
+Keep the controlled/uncontrolled mode stable while mounted. Callbacks notify user-driven selection changes, not mounting or external `selectedIds` updates. `onSelectionChange` is deprecated but remains supported for compatibility. Replace `onSelectionChange: handleSelectionChange` with `rowSelection: { onChange: handleSelectionChange }` to keep uncontrolled notification behavior. `rowSelection.onChange` takes precedence when both callbacks are supplied, and `onSelectionChange` is used when the new configuration has no callback.
 
 Selection spans pages. The header checkbox adds or removes only the current page's rows, preserving ids selected on other pages; `clearSelection()` clears every page. `selectedRows` contains current-page rows in their latest version and off-page rows as last loaded. Selected ids whose rows have never been loaded are omitted from `selectedRows` until seen, so the selection count can exceed the number of available row objects. Bulk actions operate only on those available rows.
 
@@ -482,7 +482,7 @@ const table = useDataTable({
 | `tableId`           | `string`                           | Stable id used to persist per-user column layout (visibility, order, pinning) to `localStorage`. When omitted, column layout is in-memory only and resets on reload.            |
 | `rowActions`        | `RowAction<TRow>[]`                | Per-row action items rendered in a kebab-menu column. The column is omitted when empty or not provided.                                                                         |
 | `rowSelection`      | `RowSelectionOptions`              | Controlled `selectedIds` + `onChange`, or uncontrolled `defaultSelectedIds` + optional `onChange`. Providing even `{}` enables checkboxes. See [Row selection](#row-selection). |
-| `onSelectionChange` | `(ids: string[]) => void`          | Existing selection notification; enables checkboxes. Used when `rowSelection.onChange` is absent. Rows must have a string or number `id`.                                       |
+| `onSelectionChange` | `(ids: string[]) => void`          | **Deprecated:** use `rowSelection.onChange`. Still supported for compatibility; enables checkboxes and is used when the new callback is absent.                                 |
 | `selectionActions`  | `SelectionAction<TRow>[]`          | Bulk actions shown in `DataTable.Footer` while rows are selected. A non-empty array also enables selection. See [Selection actions](#selection-actions).                        |
 | `rowExpansion`      | `RowExpansionOptions<TRow>`        | Expandable detail rows: `render`, plus optional `canExpand` / `getLabel`, and `expandedIds` + `onChange` together for controlled mode. See [Expandable rows](#expandable-rows). |
 | `sort`              | `false \| { multiple?: boolean }`  | Sort behaviour. `false` disables sorting entirely. `{ multiple: true }` enables multi-column sorting. Omit or pass `{}` for single-column sort (default).                       |
diff --git a/packages/core/src/components/data-table/types.ts b/packages/core/src/components/data-table/types.ts
index e85aec5d3..37a08081d 100644
--- a/packages/core/src/components/data-table/types.ts
+++ b/packages/core/src/components/data-table/types.ts
@@ -472,6 +472,8 @@ export type UseDataTableOptions<
    * **Note:** The header checkbox acts on the **current page**: checking it adds
    * the page's rows to the selection and unchecking it removes them. Rows
    * selected on other pages are kept.
+   *
+   * @deprecated Use `rowSelection.onChange` instead.
    */
   onSelectionChange?: (ids: string[]) => void;
   /**