@neo4j-ndl/react 4.21.2 → 4.22.1

package/skills/ndl-react/components/next/tree-view.md

@@ -11,8 +11,23 @@ Import: `import { TreeView } from '@neo4j-ndl/react/next'`
 | `ariaLabel` | `string \| null` | ✅ |  | The aria-label for the tree. Required for accessibility, unless using ariaLabelledby. Pass null to omit. |
 | `ariaLabelledby` | `string` |  |  | The aria-labelledby for the tree. Pass a string of space-separated IDs of elements that label the tree. |
 | `children` | `ReactNode` |  |  | The children of the tree. Should be TreeView.Item components or TreeView.SkeletonItem components only. |
+| `defaultSelectedIds` | `string[]` |  |  | Initially selected item ids for an uncontrolled root-managed selection. |
+| `onSelectedIdsChange` | `((selectedIds: string[]) => void)` |  |  | Callback called with the complete next selection whenever the tree manages selection. Fires once per interaction. |
 | `ref` | `Ref<HTMLDivElement>` |  |  | A ref to apply to the root element. |
-| `selectionMode` | `'multiple' \| 'single'` |  | `single` | Selection mode for the tree. Defaults to "single". |
+| `selectedIds` | `string[]` |  |  | Selected item ids. Makes the tree manage selection itself, instead of each item managing its own. |
+| `selectionMode` | `'multiple-replace' \| 'multiple' \| 'single'` |  | `single` | Selection mode for the tree. Defaults to "single". |
+
+Selection can be managed per item, with `isSelected` and `onSelectedChange`
+on each `TreeView.Item`, or by the tree itself, by passing `selectedIds` (or
+`defaultSelectedIds`) together with `onSelectedIdsChange`. When the tree
+manages selection, every item needs an `id`, and each item's own
+`isSelected` and `onSelectedChange` are ignored.
+
+The available selection modes are:
+
+- `single` — one item at a time. An unmodified click selects the clicked item and never clears it.
+- `multiple` — multi-select with checkboxes. An unmodified click toggles an item, and `Shift` repeats that across a range without clearing anything outside it.
+- `multiple-replace` — multi-select without checkboxes. An unmodified click selects only that item, `Cmd`/`Ctrl` toggles it and moves the anchor, and `Shift` extends from that anchor while retaining its selection snapshot. `Shift` + arrow extends the range.
 
 ### TreeView.Item
 
@@ -23,14 +38,16 @@ Import: `import { TreeView } from '@neo4j-ndl/react/next'`
 | `children` | `ReactNode` |  |  | Nested TreeView.Item or TreeView.SkeletonItem elements rendered as sub-items in a collapsible group. |
 | `defaultExpanded` | `boolean` |  | `false` | Default expansion for uncontrolled items |
 | `hasChildren` | `boolean` |  |  | Whether the item has children. Decides if the item should render a chevron for expansion. Needed for lazy loading. |
+| `id` | `string` |  |  | Identifies the item. Required when the tree manages selection via `selectedIds`. |
 | `isDisabled` | `boolean` |  |  | Whether the item is disabled |
 | `isExpanded` | `boolean` |  |  | Whether the item is expanded. Makes the item controlled. |
 | `isIndeterminate` | `boolean` |  |  | Whether the item is in an indeterminate state. Only meaningful in multi-select mode for parent nodes. |
 | `isLoading` | `boolean` |  |  | Whether the item is loading. Applies aria-busy="true" to the item. |
-| `isSelected` | `boolean` |  |  | Whether the item is selected |
+| `isSelectable` | `boolean` |  |  | Whether the item can be selected. Defaults to true when the tree manages selection, and otherwise to whether `onSelectedChange` is set. |
+| `isSelected` | `boolean` |  |  | Whether the item is selected. Ignored when the tree manages selection via `selectedIds`. |
 | `leadingVisual` | `ReactNode` |  |  | Leading visual for the item. |
 | `onExpandedChange` | `(isExpanded: boolean) => void` |  |  | Callback called when the item is expanded/collapsed. |
-| `onSelectedChange` | `(isSelected: boolean) => void` |  |  | Callback called when the item is selected/deselected. |
+| `onSelectedChange` | `(isSelected: boolean) => void` |  |  | Callback called when the item is selected/deselected. Receives the new selected state. Ignored when the tree manages selection via `selectedIds`. |
 | `ref` | `Ref<HTMLDivElement>` |  |  | A ref to apply to the root element. |
 | `title` | `ReactNode` |  |  | The label content displayed in the item row. |
 | `tooltipContent` | `ReactNode` |  |  | Content rendered inside the tooltip. When provided, the item is wrapped in a Tooltip. |
@@ -58,21 +75,53 @@ Implements the keyboard interactions defined in the [WAI-ARIA TreeView pattern](
 | `ArrowLeft` | Collapses an expanded parent item. If already collapsed (or a leaf), moves focus to the parent item |
 | `Home` | Moves focus to the first tree item |
 | `End` | Moves focus to the last visible tree item |
-| `Enter` | Toggles selection on the focused item, or toggles expansion if the item is not selectable |
-| `Space` | Toggles selection on the focused item, or toggles expansion if the item is not selectable |
+| `Enter` | Selects the focused item, or toggles expansion if the item is not selectable |
+| `Space` | Selects the focused item, or toggles expansion if the item is not selectable |
 | `Shift + F10` | Opens the action menu on the focused item (when `actionMenu` is provided) |
+| `Cmd/Ctrl + Enter`, `Cmd/Ctrl + Space` | `multiple-replace` only: toggles the focused item without clearing the rest |
+| `Shift + Enter`, `Shift + Space` | Both multiple modes: extends the range from the anchor to the focused item |
+| `Shift + ArrowUp`, `Shift + ArrowDown` | Both multiple modes: moves focus and extends the range to the newly focused item |
 
 The tree uses a roving tabindex strategy: only the currently focused item has `tabIndex={0}`, all other items have `tabIndex={-1}`. When the tree root receives focus it delegates to the previously focused item, or the first item if none was focused.
 
+The toggle modifier is `Cmd` on Apple platforms and `Ctrl` everywhere else, so `Ctrl` + click keeps its macOS meaning of opening the context menu.
+
+### Selection in the multiple modes
+
+Keyboard and pointer take the same modifiers and drive the same selection, so the two can be mixed freely. What each modifier means depends on the mode:
+
+| Modifier | `multiple-replace` | `multiple` |
+|----------|--------------------|------------|
+| none | Selects only that item, clearing the rest | Toggles that item |
+| `Cmd`/`Ctrl` | Toggles that item, leaving the rest alone | Nothing extra, since an unmodified click already toggles |
+| `Shift` | Selects the range from the anchor and keeps the selection the anchor was placed in | Repeats the anchor's state across the range, leaving anything outside it alone |
+| `Cmd`/`Ctrl` + `Shift` | Same as `Shift` alone | Same as `Shift` alone |
+
+`Shift` + `ArrowUp`/`ArrowDown` moves focus and extends the range in one step, and `Shift` + `Enter`/`Space` extends it to the focused item.
+
+Because `multiple` toggles, its ranges paint rather than replace: ticking an item and then `Shift`-clicking five rows down ticks all six, while unticking that item first unticks the same range. A keyboard range has no preceding click to repeat, so it selects outwards from the focused item.
+
+Ranges run between an anchor and a target. Any unmodified or `Cmd`/`Ctrl` selection moves the anchor to that item; extending a range leaves it where it is, so a range can be grown and shrunk repeatedly from the same starting point. In `multiple-replace`, the anchor also remembers the selection immediately after it was placed. This means selecting several disconnected items with `Cmd`/`Ctrl`, then using `Shift`, keeps those earlier picks and starts the range at the most recently toggled item. Toggling that item off still moves the anchor there, and the later range selects outwards from it. If no anchor exists when a range starts, the currently focused item becomes one. If the anchor ends up inside a collapsed group, the range is measured from its nearest visible ancestor, so collapsing a group cannot silently shrink a range to a single item.
+
+Ranges skip disabled items and never reach into collapsed groups. In `multiple-replace`, earlier picks from the anchor snapshot are retained only while visible; hidden selectable items are cleared, so collapsing a group never strands a selection the user can no longer see. `multiple` never clears outside the range, so nothing hidden is touched.
+
+Note that in `multiple-replace` an unmodified `Enter`/`Space` selects exclusively rather than toggling, which departs from the WAI-ARIA multi-select tree pattern. It is deliberate: it keeps the keyboard and the pointer behaving identically, and `Cmd`/`Ctrl` + `Enter`/`Space` still covers additive selection. `multiple` toggles, as the pattern describes.
+
+### Announcements
+
+Range selections are announced in a polite live region rendered next to the tree, as `4 items selected`, counting the whole selection rather than the rows the range just moved. A range can move any number of rows at once, so nothing else reports the total. Selections made without `Shift` clear the region instead, since the row they moved already carries its own `aria-selected`/`aria-checked`, and a count left behind would stop describing the tree as soon as the next selection changed it. The message is English and not currently configurable.
+
 ## WAI-ARIA roles and attributes
 
 The TreeView component follows the [WAI-ARIA TreeView pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/).
 
 - The root container has `role="tree"` and is labeled via `aria-label` or `aria-labelledby`
-- When `selectionMode` is `"multiple"`, the root sets `aria-multiselectable="true"`
+- When `selectionMode` is `"multiple"` or `"multiple-replace"`, the root sets `aria-multiselectable="true"`
 - Each item has `role="treeitem"` with `aria-level`, `aria-posinset`, and `aria-setsize` set automatically
 - Parent items (items with children) set `aria-expanded` and `aria-owns` linking to their child `role="group"` container
-- In single selection mode, selected items set `aria-selected`. In multiple selection mode, selected items set `aria-checked`, with `aria-checked="mixed"` for indeterminate parent nodes
+- In single and `multiple-replace` selection modes, selected items set `aria-selected`. In multiple selection mode, selected items set `aria-checked`, with `aria-checked="mixed"` for indeterminate parent nodes
+- Only selectable items expose `aria-selected`/`aria-checked`. An item is selectable when `isSelectable` says so, and otherwise when the tree manages selection or the item has an `onSelectedChange`. The rest are announced as non-selectable, which is what lets folders act as pure containers
+- The live region carrying selection announcements has `role="status"` and `aria-live="polite"`. It sits beside the tree rather than inside it, since `role="tree"` only allows `treeitem` and `group` children
 - Disabled items set `aria-disabled="true"`
 - Loading items set `aria-busy="true"`
 - When `actionMenu` is provided, the treeitem sets `aria-keyshortcuts="Shift+F10"` and the action button sets `aria-haspopup="menu"`, `aria-expanded`, and `aria-label="Actions"`
@@ -83,15 +132,19 @@ The TreeView component follows the [WAI-ARIA TreeView pattern](https://www.w3.or
 
 - Always provide either `ariaLabel` or `ariaLabelledby` on the root so the tree has an accessible name
 - `role="tree"` only allows children with roles `treeitem` or `group`. The built-in sub-components handle this automatically, but wrapping items in custom elements without a valid role will break the tree semantics for assistive technologies
-- In single selection mode (`selectionMode="single"`, the default), only one item should have `isSelected` set to `true` at a time. The component does not enforce this — it is the consumer's responsibility to manage the selection state
+- In single selection mode (`selectionMode="single"`, the default), selecting always replaces and never deselects. When the tree manages selection through `selectedIds`, that is enforced for you. With per-item `isSelected`/`onSelectedChange` only the clicked item is told about the change, so keeping at most one item selected at a time stays the consumer's responsibility
 - In multiple selection mode, manage `isIndeterminate` on parent nodes to communicate partial selection via `aria-checked="mixed"`. Screen reader users rely on this to understand that some but not all children are selected
+- The multiple modes compute the whole selection for you. With per-item callbacks that means `onSelectedChange` fires on every item that changed, so one gesture can mean many callbacks — keep those state updates cheap. Passing `selectedIds` and `onSelectedIdsChange` on the root instead reports the next selection once per gesture, which is easier to reconcile when a range flips many items at once
+- `isSelectable={false}` keeps an item out of selection entirely. Clicking it toggles its expansion instead, in every selection mode. When the tree manages selection through `selectedIds` every item is selectable by default, so folders that should stay pure containers have to opt out explicitly
+- `multiple-replace` has no checkbox. Selection shows up only as `aria-selected` and the accent bar, so keep those two states distinguishable by more than colour
+- Adjacent selected items merge into one rounded block. That is decorative only — each item still announces its own `aria-selected`
 - When using `hasChildren` for lazy loading, set `isLoading` to apply `aria-busy="true"` and render `TreeView.SkeletonItem` inside the expanded item so users know content is being fetched
 - The checkbox rendered in multiple selection mode has `tabIndex={-1}` — selection is driven from the treeitem via `Enter`/`Space`, not from the checkbox directly
 - The action menu button has `tabIndex={-1}` and is only reachable via `Shift+F10`, keeping arrow-key navigation within the tree clean
 
 ### Related WCAG criteria
 
-- [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A): All tree items are fully navigable and operable via keyboard
+- [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG22/Understanding/keyboard.html) (A): All tree items are fully navigable and operable via keyboard, including range selection in both multiple modes via `Shift` + arrow or `Shift` + `Enter`/`Space`
 - [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG22/Understanding/focus-order.html) (A): Roving tabindex ensures a logical focus order; `ArrowLeft` returns focus to the parent item
 - [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html) (A): Tree hierarchy is expressed via `aria-level`, `aria-posinset`, `aria-setsize`, and `role="group"` nesting
 - [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG22/Understanding/name-role-value.html) (A): Roles (`tree`, `treeitem`, `group`), states (`aria-expanded`, `aria-selected`/`aria-checked`, `aria-disabled`, `aria-busy`), and accessible names (`aria-label`/`aria-labelledby`) are set automatically by the component
@@ -268,6 +321,87 @@ const Component = () => {
 export default Component;
 ```
 
+### Large
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { DocumentIconOutline, FolderIconSolid } from '@neo4j-ndl/react/icons';
+import { TreeView } from '@neo4j-ndl/react/next';
+import { useState } from 'react';
+
+type FileNode = {
+  children?: FileNode[];
+  id: string;
+  title: string;
+};
+
+const TOP_FOLDER_COUNT = 7;
+const SUBFOLDER_COUNT = 9;
+const FILE_COUNT = 10;
+
+/**
+ * 7 top folders + 63 subfolders + 630 files = 700 items, all expanded so every
+ * row is mounted and visible. Exercises the worst-case performance paths:
+ * arrow-key navigation, Shift ranges, and the multiple-replace edge styling.
+ */
+const files: FileNode[] = Array.from(
+  { length: TOP_FOLDER_COUNT },
+  (_unused, folderIndex) => ({
+    children: Array.from({ length: SUBFOLDER_COUNT }, (_unused, subIndex) => ({
+      children: Array.from({ length: FILE_COUNT }, (_unused, fileIndex) => ({
+        id: `file-${folderIndex}-${subIndex}-${fileIndex}`,
+        title: `file-${folderIndex}-${subIndex}-${fileIndex}.txt`,
+      })),
+      id: `subfolder-${folderIndex}-${subIndex}`,
+      title: `Subfolder ${folderIndex}.${subIndex}`,
+    })),
+    id: `folder-${folderIndex}`,
+    title: `Folder ${folderIndex}`,
+  }),
+);
+
+const Component = () => {
+  const [selectedIds, setSelectedIds] = useState<string[]>([]);
+
+  const renderNode = (node: FileNode) => (
+    <TreeView.Item
+      key={node.id}
+      id={node.id}
+      title={node.title}
+      defaultExpanded
+      leadingVisual={
+        node.children === undefined ? (
+          <DocumentIconOutline />
+        ) : (
+          <FolderIconSolid />
+        )
+      }
+    >
+      {node.children?.map(renderNode)}
+    </TreeView.Item>
+  );
+
+  return (
+    <>
+      <p style={{ marginBottom: '8px' }}>
+        700 items, {selectedIds.length} selected
+      </p>
+      <TreeView
+        ariaLabel="Large file explorer"
+        selectionMode="multiple-replace"
+        selectedIds={selectedIds}
+        onSelectedIdsChange={setSelectedIds}
+      >
+        {files.map(renderNode)}
+      </TreeView>
+    </>
+  );
+};
+
+export default Component;
+```
+
 ### Lazy
 
 ```tsx
@@ -450,7 +584,12 @@ function renderNode(node: TreeNode, ctx: RenderContext) {
       {hasChildren && state.isLoading && !state.hasLoaded && (
         <TreeView.SkeletonItem rows={2} />
       )}
+      {/* Rendering children only while expanded keeps collapsed subtrees out
+          of the DOM, so large trees only pay for the rows the user can see.
+          All item state lives outside the tree (keyed by node id), so nothing
+          is lost when a subtree unmounts on collapse. */}
       {hasChildren &&
+        state.isExpanded &&
         state.hasLoaded &&
         node.children!.map((child) => renderNode(child, ctx))}
     </TreeView.Item>
@@ -489,75 +628,37 @@ import {
 import { TreeView } from '@neo4j-ndl/react/next';
 import { useCallback, useState } from 'react';
 
-type CheckedState = Record<string, boolean>;
-
-const WORK_CHILDREN = ['report', 'presentation'] as const;
-const DOC_CHILDREN = ['work', 'resume'] as const;
-const IMAGE_CHILDREN = ['photo', 'screenshot'] as const;
-const DISABLED_KEYS = new Set(['presentation']);
-
-function getParentChecked(
-  checked: CheckedState,
-  childKeys: readonly string[],
-): { isChecked: boolean; isIndeterminate: boolean } {
-  const enabledKeys = childKeys.filter((key) => !DISABLED_KEYS.has(key));
-  if (enabledKeys.length === 0) {
-    return { isChecked: false, isIndeterminate: false };
-  }
-  const checkedCount = enabledKeys.filter((key) => checked[key]).length;
-  if (checkedCount === 0) {
-    return { isChecked: false, isIndeterminate: false };
-  }
-  if (checkedCount === enabledKeys.length) {
-    return { isChecked: true, isIndeterminate: false };
-  }
-  return { isChecked: false, isIndeterminate: true };
-}
-
+/**
+ * Every row owns its own checkbox: `onSelectedChange` reports the state the row
+ * should end up in, and the story stores exactly that. Folders are ordinary
+ * selectable rows here, unrelated to what sits inside them.
+ *
+ * Deriving a folder's state from its children instead needs the tree to own the
+ * selection, since a Shift range moves several rows at once and a cascade has
+ * to be applied to the whole set in one pass. See the root-managed selection
+ * story for that.
+ */
 const Component = () => {
   const [expanded, setExpanded] = useState<Record<string, boolean>>({});
-  const [checked, setChecked] = useState<CheckedState>({});
+  const [selected, setSelected] = useState<Record<string, boolean>>({});
 
-  const toggle = (key: string) =>
+  const toggleExpanded = (key: string) =>
     setExpanded((prev) => ({ ...prev, [key]: !prev[key] }));
 
-  const toggleCheck = useCallback((key: string) => {
-    setChecked((prev) => ({ ...prev, [key]: !prev[key] }));
+  const setRowSelected = useCallback((key: string, isSelected: boolean) => {
+    setSelected((prev) => ({ ...prev, [key]: isSelected }));
   }, []);
 
-  const toggleParent = useCallback(
-    (childKeys: readonly string[]) => {
-      const enabledKeys = childKeys.filter((key) => !DISABLED_KEYS.has(key));
-      const isAllChecked = enabledKeys.every((key) => checked[key]);
-      setChecked((prev) => {
-        const next = { ...prev };
-        for (const key of enabledKeys) {
-          next[key] = !isAllChecked;
-        }
-        return next;
-      });
-    },
-    [checked],
-  );
-
-  const docState = getParentChecked(checked, [
-    ...DOC_CHILDREN,
-    ...WORK_CHILDREN,
-  ]);
-  const workState = getParentChecked(checked, WORK_CHILDREN);
-  const imageState = getParentChecked(checked, IMAGE_CHILDREN);
-
   return (
     <TreeView ariaLabel="File explorer" selectionMode="multiple">
       <TreeView.Item
         title="Documents"
         hasChildren
         isExpanded={expanded['documents']}
-        onExpandedChange={() => toggle('documents')}
-        isSelected={docState.isChecked}
-        isIndeterminate={docState.isIndeterminate}
-        onSelectedChange={() =>
-          toggleParent([...DOC_CHILDREN, ...WORK_CHILDREN])
+        onExpandedChange={() => toggleExpanded('documents')}
+        isSelected={selected['documents'] ?? false}
+        onSelectedChange={(isSelected) =>
+          setRowSelected('documents', isSelected)
         }
         leadingVisual={<FolderIconSolid />}
       >
@@ -565,29 +666,35 @@ const Component = () => {
           title="Work"
           hasChildren
           isExpanded={expanded['work']}
-          onExpandedChange={() => toggle('work')}
-          isSelected={workState.isChecked}
-          isIndeterminate={workState.isIndeterminate}
-          onSelectedChange={() => toggleParent(WORK_CHILDREN)}
+          onExpandedChange={() => toggleExpanded('work')}
+          isSelected={selected['work'] ?? false}
+          onSelectedChange={(isSelected) => setRowSelected('work', isSelected)}
           leadingVisual={<FolderIconSolid />}
         >
           <TreeView.Item
             title="Report.pdf"
-            isSelected={!!checked['report']}
-            onSelectedChange={() => toggleCheck('report')}
+            isSelected={selected['report'] ?? false}
+            onSelectedChange={(isSelected) =>
+              setRowSelected('report', isSelected)
+            }
             leadingVisual={<DocumentIconOutline />}
           />
           <TreeView.Item
             title="Presentation.pptx"
             isDisabled
-            onSelectedChange={() => null}
+            isSelected={selected['presentation'] ?? false}
+            onSelectedChange={(isSelected) =>
+              setRowSelected('presentation', isSelected)
+            }
             leadingVisual={<DocumentIconOutline />}
           />
         </TreeView.Item>
         <TreeView.Item
           title="Resume.pdf"
-          isSelected={!!checked['resume']}
-          onSelectedChange={() => toggleCheck('resume')}
+          isSelected={selected['resume'] ?? false}
+          onSelectedChange={(isSelected) =>
+            setRowSelected('resume', isSelected)
+          }
           leadingVisual={<DocumentIconOutline />}
         />
       </TreeView.Item>
@@ -595,22 +702,107 @@ const Component = () => {
         title="Images"
         hasChildren
         isExpanded={expanded['images']}
-        onExpandedChange={() => toggle('images')}
-        isSelected={imageState.isChecked}
-        isIndeterminate={imageState.isIndeterminate}
-        onSelectedChange={() => toggleParent(IMAGE_CHILDREN)}
+        onExpandedChange={() => toggleExpanded('images')}
+        isSelected={selected['images'] ?? false}
+        onSelectedChange={(isSelected) => setRowSelected('images', isSelected)}
         leadingVisual={<FolderIconSolid />}
       >
         <TreeView.Item
           title="Photo.jpg"
-          isSelected={!!checked['photo']}
-          onSelectedChange={() => toggleCheck('photo')}
+          isSelected={selected['photo'] ?? false}
+          onSelectedChange={(isSelected) => setRowSelected('photo', isSelected)}
           leadingVisual={<PhotoIconOutline />}
         />
         <TreeView.Item
           title="Screenshot.png"
-          isSelected={!!checked['screenshot']}
-          onSelectedChange={() => toggleCheck('screenshot')}
+          isSelected={selected['screenshot'] ?? false}
+          onSelectedChange={(isSelected) =>
+            setRowSelected('screenshot', isSelected)
+          }
+          leadingVisual={<PhotoIconOutline />}
+        />
+      </TreeView.Item>
+    </TreeView>
+  );
+};
+
+export default Component;
+```
+
+### Multiple Replace
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import {
+  DocumentIconOutline,
+  FolderIconSolid,
+  PhotoIconOutline,
+} from '@neo4j-ndl/react/icons';
+import { TreeView } from '@neo4j-ndl/react/next';
+import { useState } from 'react';
+
+/**
+ * Letting the tree own the selection keeps the items declarative: they carry an
+ * `id` and nothing else, and a Shift range that moves several rows at once
+ * arrives as a single `onSelectedIdsChange`.
+ */
+const Component = () => {
+  const [selectedIds, setSelectedIds] = useState<string[]>([]);
+
+  return (
+    <TreeView
+      ariaLabel="File explorer"
+      selectionMode="multiple-replace"
+      selectedIds={selectedIds}
+      onSelectedIdsChange={setSelectedIds}
+    >
+      <TreeView.Item
+        id="documents"
+        title="Documents"
+        hasChildren
+        defaultExpanded
+        leadingVisual={<FolderIconSolid />}
+      >
+        <TreeView.Item
+          id="work"
+          title="Work"
+          hasChildren
+          defaultExpanded
+          leadingVisual={<FolderIconSolid />}
+        >
+          <TreeView.Item
+            id="report"
+            title="Report.pdf"
+            isDisabled
+            leadingVisual={<DocumentIconOutline />}
+          />
+          <TreeView.Item
+            id="presentation"
+            title="Presentation.pptx"
+            leadingVisual={<DocumentIconOutline />}
+          />
+        </TreeView.Item>
+        <TreeView.Item
+          id="resume"
+          title="Resume.pdf"
+          leadingVisual={<DocumentIconOutline />}
+        />
+      </TreeView.Item>
+      <TreeView.Item
+        id="images"
+        title="Images"
+        hasChildren
+        leadingVisual={<FolderIconSolid />}
+      >
+        <TreeView.Item
+          id="photo"
+          title="Photo.jpg"
+          leadingVisual={<PhotoIconOutline />}
+        />
+        <TreeView.Item
+          id="screenshot"
+          title="Screenshot.png"
           leadingVisual={<PhotoIconOutline />}
         />
       </TreeView.Item>
@@ -630,66 +822,66 @@ import { DocumentIconOutline, FolderIconSolid } from '@neo4j-ndl/react/icons';
 import { TreeView } from '@neo4j-ndl/react/next';
 import { useState } from 'react';
 
+/**
+ * Folders here are pure containers: `isSelectable={false}` makes them expand on
+ * click without ever becoming part of the selection, and screen readers
+ * announce them as non-selectable rather than as unselected rows.
+ */
 const Component = () => {
-  const [expanded, setExpanded] = useState<Record<string, boolean>>({});
-  const [selected, setSelected] = useState<string | null>(null);
-
-  const toggle = (key: string) =>
-    setExpanded((prev) => ({ ...prev, [key]: !prev[key] }));
+  const [selectedIds, setSelectedIds] = useState<string[]>([]);
 
   return (
-    <TreeView ariaLabel="File explorer">
+    <TreeView
+      ariaLabel="File explorer"
+      selectedIds={selectedIds}
+      onSelectedIdsChange={setSelectedIds}
+    >
       <TreeView.Item
+        id="documents"
         title="Documents"
         hasChildren
-        isExpanded={expanded['documents']}
-        onExpandedChange={() => toggle('documents')}
+        isSelectable={false}
         leadingVisual={<FolderIconSolid />}
       >
         <TreeView.Item
+          id="work"
           title="Work"
           hasChildren
-          isExpanded={expanded['work']}
-          onExpandedChange={() => toggle('work')}
+          isSelectable={false}
           leadingVisual={<FolderIconSolid />}
         >
           <TreeView.Item
+            id="report"
             title="Report.pdf"
-            isSelected={selected === 'report'}
-            onSelectedChange={() => setSelected('report')}
             leadingVisual={<DocumentIconOutline />}
           />
           <TreeView.Item
+            id="presentation"
             title="Presentation.pptx"
-            isSelected={selected === 'presentation'}
-            onSelectedChange={() => setSelected('presentation')}
             leadingVisual={<DocumentIconOutline />}
           />
         </TreeView.Item>
         <TreeView.Item
+          id="resume"
           title="Resume.pdf"
-          isSelected={selected === 'resume'}
-          onSelectedChange={() => setSelected('resume')}
           leadingVisual={<DocumentIconOutline />}
         />
       </TreeView.Item>
       <TreeView.Item
+        id="images"
         title="Images"
         hasChildren
-        isExpanded={expanded['images']}
-        onExpandedChange={() => toggle('images')}
+        isSelectable={false}
         leadingVisual={<FolderIconSolid />}
       >
         <TreeView.Item
+          id="photo"
           title="Photo.jpg"
-          isSelected={selected === 'photo'}
-          onSelectedChange={() => setSelected('photo')}
           leadingVisual={<DocumentIconOutline />}
         />
         <TreeView.Item
+          id="screenshot"
           title="Screenshot.png"
-          isSelected={selected === 'screenshot'}
-          onSelectedChange={() => setSelected('screenshot')}
           leadingVisual={<DocumentIconOutline />}
         />
       </TreeView.Item>
@@ -700,6 +892,154 @@ const Component = () => {
 export default Component;
 ```
 
+### Root Selection
+
+```tsx
+import '@neo4j-ndl/base/lib/neo4j-ds-styles.css';
+
+import { DocumentIconOutline, FolderIconSolid } from '@neo4j-ndl/react/icons';
+import { TreeView } from '@neo4j-ndl/react/next';
+import { useCallback, useState } from 'react';
+
+type FileNode = {
+  children?: FileNode[];
+  id: string;
+  title: string;
+};
+
+const files: FileNode[] = [
+  {
+    children: [
+      {
+        children: [
+          { id: 'report', title: 'Report.pdf' },
+          { id: 'presentation', title: 'Presentation.pptx' },
+        ],
+        id: 'work',
+        title: 'Work',
+      },
+      { id: 'resume', title: 'Resume.pdf' },
+    ],
+    id: 'documents',
+    title: 'Documents',
+  },
+  {
+    children: [
+      { id: 'photo', title: 'Photo.jpg' },
+      { id: 'screenshot', title: 'Screenshot.png' },
+    ],
+    id: 'images',
+    title: 'Images',
+  },
+];
+
+const walk = (nodes: FileNode[], visit: (node: FileNode) => void) => {
+  nodes.forEach((node) => {
+    visit(node);
+    walk(node.children ?? [], visit);
+  });
+};
+
+const getDescendantIds = (node: FileNode): string[] =>
+  (node.children ?? []).flatMap((child) => [
+    child.id,
+    ...getDescendantIds(child),
+  ]);
+
+const getLeafIds = (node: FileNode): string[] =>
+  node.children === undefined ? [node.id] : node.children.flatMap(getLeafIds);
+
+/** Folders follow their contents: selected only when every leaf below them is. */
+const syncFolders = (nodes: FileNode[], selected: Set<string>) => {
+  nodes.forEach((node) => {
+    if (node.children === undefined) {
+      return;
+    }
+    syncFolders(node.children, selected);
+    if (getLeafIds(node).every((id) => selected.has(id))) {
+      selected.add(node.id);
+    } else {
+      selected.delete(node.id);
+    }
+  });
+};
+
+const Component = () => {
+  const [selectedIds, setSelectedIds] = useState<string[]>(['resume']);
+  const selected = new Set(selectedIds);
+
+  /**
+   * The tree reports the whole selection at once, so cascading folders onto
+   * their contents takes a single pass even when a Shift range flipped many
+   * rows.
+   */
+  const handleSelectedIdsChange = useCallback((nextIds: string[]) => {
+    setSelectedIds((previousIds) => {
+      const next = new Set(nextIds);
+      const previous = new Set(previousIds);
+      walk(files, (node) => {
+        const isSelected = next.has(node.id);
+        if (
+          node.children === undefined ||
+          isSelected === previous.has(node.id)
+        ) {
+          return;
+        }
+        getDescendantIds(node).forEach((id) => {
+          if (isSelected) {
+            next.add(id);
+          } else {
+            next.delete(id);
+          }
+        });
+      });
+      syncFolders(files, next);
+      return [...next];
+    });
+  }, []);
+
+  const renderNode = (node: FileNode) => {
+    const leafIds = getLeafIds(node);
+    const selectedLeafCount = leafIds.filter((id) => selected.has(id)).length;
+    return (
+      <TreeView.Item
+        key={node.id}
+        id={node.id}
+        title={node.title}
+        defaultExpanded
+        isIndeterminate={
+          node.children !== undefined &&
+          selectedLeafCount > 0 &&
+          selectedLeafCount < leafIds.length
+        }
+        leadingVisual={
+          node.children === undefined ? (
+            <DocumentIconOutline />
+          ) : (
+            <FolderIconSolid />
+          )
+        }
+      >
+        {node.children?.map(renderNode)}
+      </TreeView.Item>
+    );
+  };
+
+  return (
+    <TreeView
+      ariaLabel="File explorer"
+      selectionMode="multiple"
+      selectedIds={selectedIds}
+      onSelectedIdsChange={handleSelectedIdsChange}
+    >
+      {files.map(renderNode)}
+    </TreeView>
+  );
+};
+
+export default Component;
+```
+
 ### Single
 
 ```tsx