Introduce separate selection states for lists with distinct storeKey

docs/List.md

@@ -486,7 +486,7 @@ const Dashboard = () => (
 )
 ```
 
-Please note that the selection state is not synced in the URL but in a global store using the resource as key. Thus, all lists in the page using the same resource will share the same synced selection state. This is a design choice because if row selection is not tied to a resource, then when a user deletes a record it may remain selected without any ability to unselect it. If you want to allow custom `storeKey`'s for managing selection state, you will have to implement your own `useListController` hook and pass a custom key to the `useRecordSelection` hook. You will then need to implement your own `DeleteButton` and `BulkDeleteButton` to manually unselect rows when deleting records. You can still opt out of all store interactions including selection if you set it to `false`.
+Please note that the selection state is not synced in the URL but in a global store using the resource and, if provided, `storeKey` as part of the key. Thus, all lists in the page using the same resource and `storeKey` will share the same synced selection state. This is a design choice because if row selection is not tied to a resource, then when a user deletes a record it may remain selected without any ability to unselect it. You can still opt out of all store interactions for list state if you set it to `false`.
 
 ## `empty`
 
@@ -1097,7 +1097,9 @@ const Admin = () => {
 
 **Tip:** The `storeKey` is actually passed to the underlying `useListController` hook, which you can use directly for more complex scenarios. See the [`useListController` doc](./useListController.md#storekey) for more info.
 
-**Note:** *Selection state* will remain linked to a resource-based key regardless of the specified `storeKey` string. This is a design choice because if row selection is not tied to a resource, then when a user deletes a record it may remain selected without any ability to unselect it. If you want to allow custom `storeKey`'s for managing selection state, you will have to implement your own `useListController` hook and pass a custom key to the `useRecordSelection` hook. You will then need to implement your own `DeleteButton` and `BulkDeleteButton` to manually unselect rows when deleting records. You can still opt out of all store interactions including selection if you set it to `false`.
+**Tip:** The `storeKey` is also passed to the underlying `useRecordSelection` hook, so that lists with different storeKeys for same resource will have independent selection states.
+
+**Tip:** Setting `storeKey` to `false` will opt out of all store interactions including selection.
 
 ## `title`
 

docs/useUnselect.md

@@ -5,7 +5,9 @@ title: "useUnselect"
 
 # `useUnselect`
 
-This hook returns a function that unselects lines in the current `<DataTable>` that match an array of ids. Pass the name of the resource to the hook as argument.
+This hook returns a function that unselects lines in a `<DataTable>` that match an array of ids.
+
+## Usage
 
 ```jsx
 import { useListContext, useUnselect } from 'react-admin';
@@ -26,3 +28,109 @@ const UnselectButton = () => {
 };
 ```
 
+## Parameters
+
+`useUnselect` accepts two parameters. Both are optional:
+
+- [`resource`](#resource): The resource name. If not specified, the hook will only update the locally stored selection state (changes are not persisted in the Store).
+- [`storeKey`](#storekey): The store key to use. If not specified, the hook will derive the store key from the `resource`. It should match with the `storeKey` used in the parent `<List>`.
+
+## `resource`
+
+Use `resource` to specify the resource name.
+
+```jsx
+import { useListContext, useUnselect } from 'react-admin';
+
+const UnselectButton = () => {
+    const { resource, selectedIds } = useListContext();
+    const unselect = useUnselect(resource);
+
+    const handleClick = () => {
+        unselect(selectedIds);
+    };
+
+    return (
+        <button onClick={handleClick}>
+            {`Unselect ${selectedIds.length} records`}
+        </button>
+    );
+};
+```
+
+If not specified, the hook will only update the locally stored selection state (changes are not persisted in the Store). This is notably useful when the parent `<List>` has the [`storeKey`](./List.md#storekey) prop set to `false`.
+
+```jsx
+import { useListContext, useUnselect } from 'react-admin';
+
+const UnselectButton = () => {
+    const { selectedIds } = useListContext();
+    // Call useUnselect without arguments - local selection only
+    const unselect = useUnselect();
+
+    const handleClick = () => {
+        unselect(selectedIds);
+    };
+
+    return (
+        <button onClick={handleClick}>
+            {`Unselect ${selectedIds.length} records`}
+        </button>
+    );
+};
+```
+
+## `storeKey`
+
+The default store key is derived from the resource name: `${resource}.selectedIds`.
+
+You can customize the store key used by passing a `storeKey` parameter to the hook. Make sure it matches the `storeKey` used in the parent `<List>`.
+
+The final store key used will be `${storeKey}.selectedIds`.
+
+```jsx
+import { useListContext, useUnselect } from 'react-admin';
+
+const UnselectButton = () => {
+    const { resource, selectedIds } = useListContext();
+    const unselect = useUnselect(resource, 'customStoreKey');
+
+    const handleClick = () => {
+        unselect(selectedIds);
+    };
+
+    return (
+        <button onClick={handleClick}>
+            {`Unselect ${selectedIds.length} records`}
+        </button>
+    );
+};
+```
+
+## Return value
+
+`useUnselect` returns a function taking up to two parameters:
+
+- `ids`: An array of record ids to unselect.
+- `fromAllStoreKeys`: A boolean indicating whether to unselect the records across all storeKeys used with this resource. Defaults to `false`. Set this to `true` for instance when the records are deleted, to ensure they don't remain selected in other lists.
+
+```jsx
+import { useListContext, useUnselect } from 'react-admin';
+
+const UnselectButton = () => {
+    const { resource, selectedIds } = useListContext();
+    const unselect = useUnselect(resource);
+
+    const handleClick = () => {
+        // Unselect across all store keys
+        unselect(selectedIds, true);
+    };
+
+    return (
+        <button onClick={handleClick}>
+            {`Unselect ${selectedIds.length} records`}
+        </button>
+    );
+};
+```
+

docs/useUnselectAll.md

@@ -5,16 +5,109 @@ title: "useUnselectAll"
 
 # `useUnselectAll`
 
-This hook returns a function that unselects all lines in the current `<DataTable>`. Pass the name of the resource as argument.
+This hook returns a function that unselects all lines in a `<DataTable>`.
+
+## Usage
+
+```jsx
+import { useListContext, useUnselectAll } from 'react-admin';
+
+const UnselectAllButton = () => {
+    const { resource } = useListContext();
+    const unselectAll = useUnselectAll(resource);
+
+    const handleClick = () => {
+        unselectAll();
+    };
+
+    return <button onClick={handleClick}>Unselect all</button>;
+};
+```
+
+## Parameters
+
+`useUnselectAll` accepts two parameters. Both are optional:
+
+- [`resource`](#resource): The resource name. If not specified, the hook will only update the locally stored selection state (changes are not persisted in the Store).
+- [`storeKey`](#storekey): The store key to use. If not specified, the hook will derive the store key from the `resource`. It should match with the `storeKey` used in the parent `<List>`.
+
+## `resource`
+
+Use `resource` to specify the resource name.
 
 ```jsx
-import { useUnselectAll } from 'react-admin';
+import { useListContext, useUnselectAll } from 'react-admin';
 
 const UnselectAllButton = () => {
-    const unselectAll = useUnselectAll('posts');
+    const { resource } = useListContext();
+    const unselectAll = useUnselectAll(resource);
+
+    const handleClick = () => {
+        unselectAll();
+    };
+
+    return <button onClick={handleClick}>Unselect all</button>;
+};
+```
+
+If not specified, the hook will only update the locally stored selection state (changes are not persisted in the Store). This is notably useful when the parent `<List>` has the [`storeKey`](./List.md#storekey) prop set to `false`.
+
+```jsx
+import { useListContext, useUnselectAll } from 'react-admin';
+
+const UnselectAllButton = () => {
+    // Call useUnselectAll without arguments - local selection only
+    const unselectAll = useUnselectAll();
+
     const handleClick = () => {
         unselectAll();
-    }
+    };
+
+    return <button onClick={handleClick}>Unselect all</button>;
+};
+```
+
+## `storeKey`
+
+The default store key is derived from the resource name: `${resource}.selectedIds`.
+
+You can customize the store key used by passing a `storeKey` parameter to the hook. Make sure it matches the `storeKey` used in the parent `<List>`.
+
+The final store key used will be `${storeKey}.selectedIds`.
+
+```jsx
+import { useListContext, useUnselectAll } from 'react-admin';
+
+const UnselectAllButton = () => {
+    const { resource } = useListContext();
+    const unselectAll = useUnselectAll(resource, 'customStoreKey');
+
+    const handleClick = () => {
+        unselectAll();
+    };
+
+    return <button onClick={handleClick}>Unselect all</button>;
+};
+```
+
+## Return value
+
+`useUnselectAll` returns a function taking one optional parameter:
+
+- `fromAllStoreKeys`: A boolean indicating whether to unselect the records across all storeKeys used with this resource. Defaults to `false`. Set this to `true` for instance when the records are deleted, to ensure they don't remain selected in other lists.
+
+```jsx
+import { useListContext, useUnselectAll } from 'react-admin';
+
+const UnselectAllButton = () => {
+    const { resource } = useListContext();
+    const unselectAll = useUnselectAll(resource);
+
+    const handleClick = () => {
+        // Unselect across all store keys
+        unselectAll(true);
+    };
+
     return <button onClick={handleClick}>Unselect all</button>;
 };
 ```

docs_headless/src/content/docs/useUnselect.md

@@ -2,7 +2,9 @@
 title: "useUnselect"
 ---
 
-This hook returns a function that unselects lines in the current data table (see `<DataTableBase>`) that match an array of ids. Pass the name of the resource to the hook as argument.
+This hook returns a function that unselects lines in a data table (see `<DataTableBase>`) that match an array of ids.
+
+## Usage
 
 ```jsx
 import { useListContext, useUnselect } from 'ra-core';
@@ -23,3 +25,109 @@ const UnselectButton = () => {
 };
 ```
 
+## Parameters
+
+`useUnselect` accepts two parameters. Both are optional:
+
+- [`resource`](#resource): The resource name. If not specified, the hook will only update the locally stored selection state (changes are not persisted in the Store).
+- [`storeKey`](#storekey): The store key to use. If not specified, the hook will derive the store key from the `resource`. It should match the `storeKey` used by the parent controller (e.g. `useListController` or `<ListBase>`).
+
+## `resource`
+
+Use `resource` to specify the resource name.
+
+```jsx
+import { useListContext, useUnselect } from 'ra-core';
+
+const UnselectButton = () => {
+    const { resource, selectedIds } = useListContext();
+    const unselect = useUnselect(resource);
+
+    const handleClick = () => {
+        unselect(selectedIds);
+    };
+
+    return (
+        <button onClick={handleClick}>
+            {`Unselect ${selectedIds.length} records`}
+        </button>
+    );
+};
+```
+
+If not specified, the hook will only update the locally stored selection state (changes are not persisted in the Store). This is notably useful when the parent list has the [`storeKey`](./ListBase.md#storekey) prop set to `false`.
+
+```jsx
+import { useListContext, useUnselect } from 'ra-core';
+
+const UnselectButton = () => {
+    const { selectedIds } = useListContext();
+    // Call useUnselect without arguments - local selection only
+    const unselect = useUnselect();
+
+    const handleClick = () => {
+        unselect(selectedIds);
+    };
+
+    return (
+        <button onClick={handleClick}>
+            {`Unselect ${selectedIds.length} records`}
+        </button>
+    );
+};
+```
+
+## `storeKey`
+
+The default store key is derived from the resource name: `${resource}.selectedIds`.
+
+You can customize the store key used by passing a `storeKey` parameter to the hook. Make sure it matches the `storeKey` used in the controller (`useListController` or `<ListBase>`).
+
+The final store key used will be `${storeKey}.selectedIds`.
+
+```jsx
+import { useListContext, useUnselect } from 'ra-core';
+
+const UnselectButton = () => {
+    const { resource, selectedIds } = useListContext();
+    const unselect = useUnselect(resource, 'customStoreKey');
+
+    const handleClick = () => {
+        unselect(selectedIds);
+    };
+
+    return (
+        <button onClick={handleClick}>
+            {`Unselect ${selectedIds.length} records`}
+        </button>
+    );
+};
+```
+
+## Return value
+
+`useUnselect` returns a function taking up to two parameters:
+
+- `ids`: An array of record ids to unselect.
+- `fromAllStoreKeys`: A boolean indicating whether to unselect the records across all storeKeys used with this resource. Defaults to `false`. Set this to `true` for instance when the records are deleted, to ensure they don't remain selected in other lists.
+
+```jsx
+import { useListContext, useUnselect } from 'ra-core';
+
+const UnselectButton = () => {
+    const { resource, selectedIds } = useListContext();
+    const unselect = useUnselect(resource);
+
+    const handleClick = () => {
+        // Unselect across all store keys
+        unselect(selectedIds, true);
+    };
+
+    return (
+        <button onClick={handleClick}>
+            {`Unselect ${selectedIds.length} records`}
+        </button>
+    );
+};
+```
+