@neo4j-ndl/react 4.21.2 → 4.22.0

package/lib/cjs/next/tree-view/TreeView.js

@@ -40,29 +40,71 @@ const react_1 = require("@floating-ui/react");
 const classnames_1 = __importDefault(require("classnames"));
 const react_2 = require("react");
 const use_semi_controlled_state_1 = require("../../_common/use-semi-controlled-state");
+const utils_1 = require("../../_common/utils");
 const checkbox_1 = require("../../checkbox");
 const clean_icon_button_1 = require("../../clean-icon-button");
 const conditional_wrap_1 = require("../../conditional-wrap");
+const platform_1 = require("../../helpers/platform");
 const ChevronRightIconOutline_1 = require("../../icons/generated/heroIcons/ChevronRightIconOutline");
 const EllipsisHorizontalIconOutline_1 = require("../../icons/generated/heroIcons/EllipsisHorizontalIconOutline");
 const menu_1 = require("../../menu");
 const skeleton_1 = require("../../skeleton");
 const tooltip_1 = require("../../tooltip");
+const selection_1 = require("./selection");
 const noop = () => undefined;
+const EMPTY_EDGES = new Map();
+const EMPTY_IDS = new Set();
+const EMPTY_ID_LIST = [];
+/**
+ * Volatile per-interaction state (focus, root-managed selection, edge
+ * styling) lives in this store instead of React context, so each item can
+ * subscribe to its own primitive slice via `useSyncExternalStore` and an
+ * interaction only re-renders the rows whose slice actually changed.
+ */
+function createTreeViewStore(initialState) {
+    let state = Object.assign({ edgeById: EMPTY_EDGES, focusedId: null, selectedIds: EMPTY_IDS }, initialState);
+    const listeners = new Set();
+    return {
+        getState: () => state,
+        setState: (partial) => {
+            state = Object.assign(Object.assign({}, state), partial);
+            listeners.forEach((listener) => listener());
+        },
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+}
 const TREE_EVENTS = {
     action: 'treeitem-action',
     collapse: 'treeitem-collapse',
     expand: 'treeitem-expand',
-    select: 'treeitem-select',
 };
 const TreeViewContext = (0, react_2.createContext)({
-    focusedId: null,
+    isRootManaged: false,
     level: 1,
+    onSelectionIntent: noop,
+    parentId: null,
+    registerItem: noop,
     selectionMode: 'single',
     setFocusedId: noop,
+    store: createTreeViewStore(),
 });
+/**
+ * On Apple platforms Ctrl+click is the context menu gesture, so only Cmd may
+ * stand for an additive selection there.
+ */
+function getSelectionIntent(event) {
+    return {
+        isRange: event.shiftKey,
+        isToggle: (0, platform_1.isApplePlatform)() ? event.metaKey : event.ctrlKey,
+    };
+}
 function getVisibleTreeItems(root) {
-    return Array.from(root.querySelectorAll('[role="treeitem"]:not([role="group"][hidden] [role="treeitem"])')).filter((el) => {
+    return Array.from(root.querySelectorAll('[role="treeitem"]')).filter((el) => {
         let parent = el.parentElement;
         while (parent && parent !== root) {
             if (parent.getAttribute('role') === 'group' && parent.hidden) {
@@ -73,6 +115,31 @@ function getVisibleTreeItems(root) {
         return true;
     });
 }
+function getVisibleItemIds(root) {
+    return getVisibleTreeItems(root).map((el) => el.id);
+}
+function areIdSetsEqual(first, second) {
+    if (first.size !== second.size) {
+        return false;
+    }
+    for (const id of first) {
+        if (!second.has(id)) {
+            return false;
+        }
+    }
+    return true;
+}
+function areEdgeMapsEqual(first, second) {
+    if (first.size !== second.size) {
+        return false;
+    }
+    for (const [id, edge] of first) {
+        if (second.get(id) !== edge) {
+            return false;
+        }
+    }
+    return true;
+}
 function annotateTreeItems(children) {
     const items = react_2.Children.toArray(children);
     const treeItemCount = items.filter((child) => (0, react_2.isValidElement)(child) && child.type === Item).length;
@@ -105,10 +172,186 @@ function annotateTreeItems(children) {
  * @alpha - this component is still in development and may change in the future. It might not have feature parity with the old tree view yet.
  */
 const Root = (_a) => {
-    var { children, selectionMode = 'single', ariaLabel, ariaLabelledby, className, style, htmlAttributes, ref } = _a, restProps = __rest(_a, ["children", "selectionMode", "ariaLabel", "ariaLabelledby", "className", "style", "htmlAttributes", "ref"]);
+    var _b, _c;
+    var { children, defaultSelectedIds, selectedIds: selectedIdsProp, selectionMode = 'single', ariaLabel, ariaLabelledby, className, style, htmlAttributes, onSelectedIdsChange, ref } = _a, restProps = __rest(_a, ["children", "defaultSelectedIds", "selectedIds", "selectionMode", "ariaLabel", "ariaLabelledby", "className", "style", "htmlAttributes", "onSelectedIdsChange", "ref"]);
     const treeRef = (0, react_2.useRef)(null);
     const mergedRef = (0, react_1.useMergeRefs)([treeRef, ref]);
-    const [focusedId, setFocusedId] = (0, react_2.useState)(null);
+    const [announcement, setAnnouncement] = (0, react_2.useState)('');
+    const anchorRef = (0, react_2.useRef)(null);
+    const entriesRef = (0, react_2.useRef)(new Map());
+    const isRootManaged = selectedIdsProp !== undefined || defaultSelectedIds !== undefined;
+    const storeRef = (0, react_2.useRef)(null);
+    if (storeRef.current === null) {
+        storeRef.current = createTreeViewStore({
+            selectedIds: new Set((_b = selectedIdsProp !== null && selectedIdsProp !== void 0 ? selectedIdsProp : defaultSelectedIds) !== null && _b !== void 0 ? _b : EMPTY_ID_LIST),
+        });
+    }
+    const store = storeRef.current;
+    const setFocusedId = (0, react_2.useCallback)((id) => {
+        if (store.getState().focusedId !== id) {
+            store.setState({ focusedId: id });
+        }
+    }, [store]);
+    const [selectedIdList, setSelectedIdList] = (0, use_semi_controlled_state_1.useSemicontrolledState)({
+        isControlled: selectedIdsProp !== undefined,
+        onChange: onSelectedIdsChange,
+        state: (_c = selectedIdsProp !== null && selectedIdsProp !== void 0 ? selectedIdsProp : defaultSelectedIds) !== null && _c !== void 0 ? _c : EMPTY_ID_LIST,
+    });
+    // useSemicontrolledState recreates its setter whenever the value changes;
+    // reading it through a ref keeps onSelectionIntent (and with it the
+    // memoized context value) stable across selection changes.
+    const setSelectedIdListRef = (0, react_2.useRef)(setSelectedIdList);
+    (0, react_2.useLayoutEffect)(() => {
+        setSelectedIdListRef.current = setSelectedIdList;
+    });
+    const readSelectedIds = (0, react_2.useCallback)(() => {
+        if (isRootManaged) {
+            return new Set(store.getState().selectedIds);
+        }
+        const selected = new Set();
+        entriesRef.current.forEach((entry, itemId) => {
+            if (entry.isSelected) {
+                selected.add(itemId);
+            }
+        });
+        return selected;
+    }, [isRootManaged, store]);
+    const readItemMaps = (0, react_2.useCallback)(() => {
+        const parentIdById = new Map();
+        const selectableIds = new Set();
+        entriesRef.current.forEach((entry, itemId) => {
+            if (entry.parentId !== null) {
+                parentIdById.set(itemId, entry.parentId);
+            }
+            if (entry.isSelectable && !entry.isDisabled) {
+                selectableIds.add(itemId);
+            }
+        });
+        return { parentIdById, selectableIds };
+    }, []);
+    const recomputeEdges = (0, react_2.useCallback)(() => {
+        const root = treeRef.current;
+        const previousEdges = store.getState().edgeById;
+        if (!root || selectionMode !== 'multiple-replace') {
+            if (previousEdges.size > 0) {
+                store.setState({ edgeById: EMPTY_EDGES });
+            }
+            return;
+        }
+        const selectedIds = readSelectedIds();
+        if (selectedIds.size === 0 && previousEdges.size === 0) {
+            return;
+        }
+        const nextEdges = (0, selection_1.computeSelectionEdges)(getVisibleItemIds(root), selectedIds);
+        if (!areEdgeMapsEqual(previousEdges, nextEdges)) {
+            store.setState({ edgeById: nextEdges });
+        }
+    }, [readSelectedIds, selectionMode, store]);
+    const recomputeEdgesRef = (0, react_2.useRef)(recomputeEdges);
+    (0, react_2.useLayoutEffect)(() => {
+        recomputeEdgesRef.current = recomputeEdges;
+    });
+    // Debounced through a microtask so a commit that touches many items (mount,
+    // expansion, range selection) triggers a single recompute, after all item
+    // layout effects have registered and before the browser paints.
+    const isEdgeRecomputeScheduledRef = (0, react_2.useRef)(false);
+    const scheduleEdgeRecompute = (0, react_2.useCallback)(() => {
+        if (isEdgeRecomputeScheduledRef.current) {
+            return;
+        }
+        isEdgeRecomputeScheduledRef.current = true;
+        queueMicrotask(() => {
+            isEdgeRecomputeScheduledRef.current = false;
+            recomputeEdgesRef.current();
+        });
+    }, []);
+    const registerItem = (0, react_2.useCallback)((itemId, entry) => {
+        if (entry === null) {
+            entriesRef.current.delete(itemId);
+        }
+        else {
+            entriesRef.current.set(itemId, entry);
+        }
+        // Covers item mount/unmount and expansion toggles (a collapsing parent
+        // re-registers because its toggleExpanded callback is recreated).
+        scheduleEdgeRecompute();
+    }, [scheduleEdgeRecompute]);
+    const onSelectionIntent = (0, react_2.useCallback)((itemId, intent) => {
+        var _a;
+        const root = treeRef.current;
+        const entry = entriesRef.current.get(itemId);
+        if (!root || !entry || entry.isDisabled) {
+            return;
+        }
+        if (!entry.isSelectable) {
+            entry.toggleExpanded();
+            return;
+        }
+        const { parentIdById, selectableIds } = readItemMaps();
+        const selectedIds = readSelectedIds();
+        const result = (0, selection_1.computeNextSelection)({
+            anchor: anchorRef.current,
+            intent,
+            parentIdById,
+            selectableIds,
+            selectedIds,
+            selectionMode,
+            targetId: itemId,
+            visibleIds: getVisibleItemIds(root),
+        });
+        anchorRef.current = result.anchor;
+        const nextSelectedIds = result.selectedIds;
+        const changedCount = (0, selection_1.countChangedIds)(selectedIds, nextSelectedIds);
+        if (isRootManaged) {
+            if (changedCount > 0) {
+                setSelectedIdListRef.current([...nextSelectedIds]);
+            }
+        }
+        else if (selectionMode === 'single') {
+            // Single mode leaves clearing the previously selected item to the
+            // consumer, so only the clicked item is told about the change.
+            if (!selectedIds.has(itemId)) {
+                (_a = entry.onSelectedChange) === null || _a === void 0 ? void 0 : _a.call(entry, true);
+            }
+        }
+        else {
+            entriesRef.current.forEach((itemEntry, id) => {
+                var _a;
+                const isSelected = nextSelectedIds.has(id);
+                if (itemEntry.isSelected !== isSelected) {
+                    (_a = itemEntry.onSelectedChange) === null || _a === void 0 ? void 0 : _a.call(itemEntry, isSelected);
+                }
+            });
+        }
+        scheduleEdgeRecompute();
+        if (selectionMode !== 'single') {
+            setAnnouncement(intent.isRange
+                ? (0, selection_1.formatSelectionAnnouncement)(nextSelectedIds.size)
+                : '');
+        }
+    }, [
+        isRootManaged,
+        readItemMaps,
+        readSelectedIds,
+        scheduleEdgeRecompute,
+        selectionMode,
+    ]);
+    // Mirrors the root-managed selection into the store, so items subscribe to
+    // their own slice and event handlers read it without a state dependency.
+    (0, react_2.useLayoutEffect)(() => {
+        const next = isRootManaged ? new Set(selectedIdList) : EMPTY_IDS;
+        if (areIdSetsEqual(store.getState().selectedIds, next)) {
+            return;
+        }
+        store.setState({ selectedIds: next });
+        scheduleEdgeRecompute();
+    }, [isRootManaged, scheduleEdgeRecompute, selectedIdList, store]);
+    // Computes edges on mount and whenever the edge inputs change identity
+    // (selection mode, root-managed flag). Interaction-driven recomputes go
+    // through scheduleEdgeRecompute instead.
+    (0, react_2.useLayoutEffect)(() => {
+        recomputeEdges();
+    }, [recomputeEdges]);
     const handleKeyDown = (0, react_2.useCallback)((event) => {
         const root = treeRef.current;
         if (!root) {
@@ -118,13 +361,35 @@ const Root = (_a) => {
         if (items.length === 0) {
             return;
         }
-        const currentIndex = items.findIndex((el) => el.id === focusedId);
+        const currentIndex = items.findIndex((el) => el.id === store.getState().focusedId);
         let isHandled = true;
+        const extendRangeTo = (item) => {
+            if (selectionMode === 'single' || currentIndex < 0) {
+                return;
+            }
+            const entry = entriesRef.current.get(item.id);
+            if (!(entry === null || entry === void 0 ? void 0 : entry.isSelectable) || entry.isDisabled) {
+                return;
+            }
+            if (anchorRef.current === null) {
+                // A keyboard range has no preceding click to repeat, so it grows the
+                // selection outwards from wherever focus already is.
+                anchorRef.current = {
+                    baseSelectedIds: readSelectedIds(),
+                    id: items[currentIndex].id,
+                    isSelected: true,
+                };
+            }
+            onSelectionIntent(item.id, { isRange: true, isToggle: false });
+        };
         switch (event.key) {
             case 'ArrowDown': {
                 const nextIndex = currentIndex < items.length - 1 ? currentIndex + 1 : currentIndex;
                 const nextItem = items[nextIndex];
                 if (nextItem) {
+                    if (event.shiftKey) {
+                        extendRangeTo(nextItem);
+                    }
                     setFocusedId(nextItem.id);
                     nextItem.focus();
                 }
@@ -134,6 +399,9 @@ const Root = (_a) => {
                 const prevIndex = currentIndex > 0 ? currentIndex - 1 : 0;
                 const prevItem = items[prevIndex];
                 if (prevItem) {
+                    if (event.shiftKey) {
+                        extendRangeTo(prevItem);
+                    }
                     setFocusedId(prevItem.id);
                     prevItem.focus();
                 }
@@ -199,7 +467,7 @@ const Root = (_a) => {
             case ' ': {
                 const current = currentIndex >= 0 ? items[currentIndex] : null;
                 if (current) {
-                    current.dispatchEvent(new CustomEvent(TREE_EVENTS.select));
+                    onSelectionIntent(current.id, getSelectionIntent(event));
                 }
                 break;
             }
@@ -222,7 +490,7 @@ const Root = (_a) => {
             event.preventDefault();
             event.stopPropagation();
         }
-    }, [focusedId]);
+    }, [onSelectionIntent, readSelectedIds, selectionMode, setFocusedId, store]);
     const handleFocus = (0, react_2.useCallback)((event) => {
         const root = treeRef.current;
         if (!root) {
@@ -230,6 +498,7 @@ const Root = (_a) => {
         }
         if (event.target === root) {
             const items = getVisibleTreeItems(root);
+            const { focusedId } = store.getState();
             const alreadyFocused = focusedId
                 ? items.find((el) => el.id === focusedId)
                 : null;
@@ -239,9 +508,36 @@ const Root = (_a) => {
                 target.focus();
             }
         }
-    }, [focusedId]);
-    const classes = (0, classnames_1.default)(className, 'ndl-tree-view-new');
-    return ((0, jsx_runtime_1.jsx)(TreeViewContext.Provider, { value: { focusedId, level: 1, selectionMode, setFocusedId }, children: (0, jsx_runtime_1.jsx)("div", Object.assign({ ref: mergedRef, role: "tree", "aria-multiselectable": selectionMode === 'multiple' || undefined, tabIndex: 0, className: classes, onKeyDown: handleKeyDown, onFocus: handleFocus, "aria-label": ariaLabel !== null && ariaLabel !== void 0 ? ariaLabel : undefined, "aria-labelledby": ariaLabelledby, style: style }, htmlAttributes, restProps, { children: annotateTreeItems(children) })) }));
+    }, [setFocusedId, store]);
+    const classes = (0, classnames_1.default)(className, 'ndl-tree-view-new', {
+        'ndl-tree-view-new--checkbox': selectionMode === 'multiple',
+    });
+    // Cached on children identity so Root-internal state commits (announcement,
+    // uncontrolled selection) reuse the same annotated elements and React bails
+    // out of the whole item subtree instead of re-rendering every row.
+    const annotatedChildren = (0, react_2.useMemo)(() => annotateTreeItems(children), [children]);
+    // Everything in here is stable or primitive, so items only re-render via
+    // context when the tree's configuration changes, not per interaction.
+    const contextValue = (0, react_2.useMemo)(() => ({
+        isRootManaged,
+        level: 1,
+        onSelectionIntent,
+        parentId: null,
+        registerItem,
+        selectionMode,
+        setFocusedId,
+        store,
+    }), [
+        isRootManaged,
+        onSelectionIntent,
+        registerItem,
+        selectionMode,
+        setFocusedId,
+        store,
+    ]);
+    return ((0, jsx_runtime_1.jsxs)(TreeViewContext.Provider, { value: contextValue, children: [(0, jsx_runtime_1.jsx)("div", Object.assign({ ref: mergedRef, role: "tree", "aria-multiselectable": selectionMode === 'multiple' || selectionMode === 'multiple-replace'
+                    ? true
+                    : undefined, tabIndex: 0, className: classes, onKeyDown: handleKeyDown, onFocus: handleFocus, "aria-label": ariaLabel !== null && ariaLabel !== void 0 ? ariaLabel : undefined, "aria-labelledby": ariaLabelledby, style: style }, htmlAttributes, restProps, { children: annotatedChildren })), (0, jsx_runtime_1.jsx)("div", { role: "status", "aria-live": "polite", "aria-atomic": "true", className: "ndl-tree-view-new-live-region", children: announcement })] }));
 };
 /**
  * A single item within a `TreeView`. Renders a `role="treeitem"` element that
@@ -266,16 +562,23 @@ const Root = (_a) => {
  * ```
  */
 const Item = (_a) => {
-    var { actionMenuItems, children, defaultExpanded = false, hasChildren: hasChildrenProp, isDisabled, isExpanded: isExpandedProp, isIndeterminate, isLoading, isSelected, leadingVisual, title, tooltipContent, tooltipProps, trailingContent, onExpandedChange, onSelectedChange, actionMenuProps, className, style, htmlAttributes, ref } = _a, restProps = __rest(_a, ["actionMenuItems", "children", "defaultExpanded", "hasChildren", "isDisabled", "isExpanded", "isIndeterminate", "isLoading", "isSelected", "leadingVisual", "title", "tooltipContent", "tooltipProps", "trailingContent", "onExpandedChange", "onSelectedChange", "actionMenuProps", "className", "style", "htmlAttributes", "ref"]);
+    var _b;
+    var { actionMenuItems, children, defaultExpanded = false, hasChildren: hasChildrenProp, id: idProp, isDisabled, isExpanded: isExpandedProp, isIndeterminate, isLoading, isSelectable: isSelectableProp, isSelected: isSelectedProp, leadingVisual, title, tooltipContent, tooltipProps, trailingContent, onExpandedChange, onSelectedChange, actionMenuProps, className, style, htmlAttributes, ref } = _a, restProps = __rest(_a, ["actionMenuItems", "children", "defaultExpanded", "hasChildren", "id", "isDisabled", "isExpanded", "isIndeterminate", "isLoading", "isSelectable", "isSelected", "leadingVisual", "title", "tooltipContent", "tooltipProps", "trailingContent", "onExpandedChange", "onSelectedChange", "actionMenuProps", "className", "style", "htmlAttributes", "ref"]);
     const generatedId = (0, react_2.useId)();
-    const itemId = `ndl-treeitem-${generatedId}`;
+    const itemId = (_b = idProp !== null && idProp !== void 0 ? idProp : htmlAttributes === null || htmlAttributes === void 0 ? void 0 : htmlAttributes.id) !== null && _b !== void 0 ? _b : `ndl-treeitem-${generatedId}`;
     const titleId = `ndl-treeitem-title-${generatedId}`;
     const groupId = `ndl-treegroup-${generatedId}`;
     const itemRef = (0, react_2.useRef)(null);
     const actionButtonRef = (0, react_2.useRef)(null);
     const didOpenViaKeyboard = (0, react_2.useRef)(false);
     const [isMenuOpen, setIsMenuOpen] = (0, react_2.useState)(false);
-    const { focusedId, level, selectionMode, setFocusedId } = (0, react_2.useContext)(TreeViewContext);
+    const treeViewContext = (0, react_2.useContext)(TreeViewContext);
+    const { isRootManaged, level, onSelectionIntent, parentId, registerItem, selectionMode, setFocusedId, store, } = treeViewContext;
+    // Primitive slices of the store, so Object.is bails out of re-renders for
+    // rows whose focus/selection/edge state did not change.
+    const isFocused = (0, react_2.useSyncExternalStore)(store.subscribe, () => store.getState().focusedId === itemId, () => store.getState().focusedId === itemId);
+    const isRootSelected = (0, react_2.useSyncExternalStore)(store.subscribe, () => store.getState().selectedIds.has(itemId), () => store.getState().selectedIds.has(itemId));
+    const edge = (0, react_2.useSyncExternalStore)(store.subscribe, () => store.getState().edgeById.get(itemId), () => store.getState().edgeById.get(itemId));
     const isControlledExpansion = isExpandedProp !== undefined;
     const [isExpanded, setIsExpanded] = (0, use_semi_controlled_state_1.useSemicontrolledState)({
         isControlled: isControlledExpansion,
@@ -283,7 +586,10 @@ const Item = (_a) => {
         state: isExpandedProp !== null && isExpandedProp !== void 0 ? isExpandedProp : defaultExpanded,
     });
     const hasChildren = hasChildrenProp !== null && hasChildrenProp !== void 0 ? hasChildrenProp : react_2.Children.count(children) > 0;
-    const isSelectable = onSelectedChange !== undefined;
+    const isSelectable = isRootManaged
+        ? (isSelectableProp !== null && isSelectableProp !== void 0 ? isSelectableProp : true)
+        : (isSelectableProp !== null && isSelectableProp !== void 0 ? isSelectableProp : onSelectedChange !== undefined);
+    const isSelected = isRootManaged ? isRootSelected : (isSelectedProp !== null && isSelectedProp !== void 0 ? isSelectedProp : false);
     const isMultiple = selectionMode === 'multiple';
     const toggleExpanded = (0, react_2.useCallback)(() => {
         if (isDisabled) {
@@ -293,31 +599,46 @@ const Item = (_a) => {
             setIsExpanded(!isExpanded);
         }
     }, [isDisabled, hasChildren, setIsExpanded, isExpanded]);
-    const handleSelect = (0, react_2.useCallback)(() => {
-        if (isDisabled) {
+    (0, react_2.useLayoutEffect)(() => {
+        registerItem(itemId, {
+            isDisabled: isDisabled !== null && isDisabled !== void 0 ? isDisabled : false,
+            isSelectable,
+            isSelected,
+            onSelectedChange,
+            parentId,
+            toggleExpanded,
+        });
+    }, [
+        isDisabled,
+        isSelectable,
+        isSelected,
+        itemId,
+        onSelectedChange,
+        parentId,
+        registerItem,
+        toggleExpanded,
+    ]);
+    (0, react_2.useLayoutEffect)(() => {
+        return () => registerItem(itemId, null);
+    }, [itemId, registerItem]);
+    (0, react_2.useEffect)(() => {
+        if (!isRootManaged) {
             return;
         }
-        onSelectedChange === null || onSelectedChange === void 0 ? void 0 : onSelectedChange(!isSelected);
-    }, [isDisabled, isSelected, onSelectedChange]);
-    const handleClick = (0, react_2.useCallback)(() => {
+        if (idProp === undefined) {
+            (0, utils_1.needleWarningMessage)('TreeView.Item needs an `id` when the tree manages selection with `selectedIds`.');
+        }
+        if (isSelectedProp !== undefined || onSelectedChange !== undefined) {
+            (0, utils_1.needleWarningMessage)('TreeView.Item `isSelected` and `onSelectedChange` are ignored when the tree manages selection with `selectedIds`.');
+        }
+    }, [idProp, isRootManaged, isSelectedProp, onSelectedChange]);
+    const handleClick = (0, react_2.useCallback)((event) => {
         if (isDisabled) {
             return;
         }
         setFocusedId(itemId);
-        if (isSelectable) {
-            handleSelect();
-        }
-        else {
-            toggleExpanded();
-        }
-    }, [
-        isDisabled,
-        setFocusedId,
-        itemId,
-        isSelectable,
-        handleSelect,
-        toggleExpanded,
-    ]);
+        onSelectionIntent(itemId, getSelectionIntent(event));
+    }, [isDisabled, setFocusedId, itemId, onSelectionIntent]);
     const handleChevronClick = (0, react_2.useCallback)((event) => {
         event.stopPropagation();
         if (isDisabled) {
@@ -347,15 +668,6 @@ const Item = (_a) => {
                 setIsExpanded(false);
             }
         }
-        else if (event.type === TREE_EVENTS.select) {
-            event.stopPropagation();
-            if (isSelectable) {
-                handleSelect();
-            }
-            else {
-                toggleExpanded();
-            }
-        }
         else if (event.type === TREE_EVENTS.action) {
             event.stopPropagation();
             if (actionMenuItems && !isDisabled) {
@@ -363,59 +675,51 @@ const Item = (_a) => {
                 setIsMenuOpen(true);
             }
         }
-    }, [
-        actionMenuItems,
-        hasChildren,
-        isExpanded,
-        isDisabled,
-        isSelectable,
-        setIsExpanded,
-        handleSelect,
-        toggleExpanded,
-    ]);
+    }, [actionMenuItems, hasChildren, isExpanded, isDisabled, setIsExpanded]);
     const callbackRef = (0, react_2.useCallback)((node) => {
         const prev = itemRef.current;
         if (prev) {
             prev.removeEventListener(TREE_EVENTS.expand, handleCustomEvents);
             prev.removeEventListener(TREE_EVENTS.collapse, handleCustomEvents);
-            prev.removeEventListener(TREE_EVENTS.select, handleCustomEvents);
             prev.removeEventListener(TREE_EVENTS.action, handleCustomEvents);
         }
         itemRef.current = node;
         if (node) {
             node.addEventListener(TREE_EVENTS.expand, handleCustomEvents);
             node.addEventListener(TREE_EVENTS.collapse, handleCustomEvents);
-            node.addEventListener(TREE_EVENTS.select, handleCustomEvents);
             node.addEventListener(TREE_EVENTS.action, handleCustomEvents);
         }
     }, [handleCustomEvents]);
     const mergedRef = (0, react_1.useMergeRefs)([callbackRef, ref]);
-    const isFocused = focusedId === itemId;
     const selectionAriaProps = (() => {
         if (!isSelectable) {
             return {};
         }
         if (isMultiple) {
             return {
-                'aria-checked': isIndeterminate
-                    ? 'mixed'
-                    : (isSelected !== null && isSelected !== void 0 ? isSelected : false),
+                'aria-checked': isIndeterminate ? 'mixed' : isSelected,
             };
         }
-        return { 'aria-selected': isSelected !== null && isSelected !== void 0 ? isSelected : false };
+        return { 'aria-selected': isSelected };
     })();
+    const edgeClass = edge === undefined ? undefined : `ndl-tree-view-new-item--selected-${edge}`;
+    const childContextValue = (0, react_2.useMemo)(() => (Object.assign(Object.assign({}, treeViewContext), { level: treeViewContext.level + 1, parentId: itemId })), [itemId, treeViewContext]);
+    // Same caching as in Root: keeps child element identity stable across
+    // renders of this item (selection, focus, expansion) so unchanged
+    // descendants bail out of re-rendering.
+    const annotatedChildren = (0, react_2.useMemo)(() => annotateTreeItems(children), [children]);
     const itemElement = (
     // eslint-disable-next-line jsx-a11y/click-events-have-key-events -- keyboard handled on tree root; aria-selected/aria-checked applied via spread
-    (0, jsx_runtime_1.jsx)("div", Object.assign({ ref: mergedRef, id: itemId, 
+    (0, jsx_runtime_1.jsx)("div", Object.assign({ ref: mergedRef, 
         // eslint-disable-next-line jsx-a11y/role-has-required-aria-props -- aria-selected/aria-checked applied conditionally via spread
-        role: "treeitem" }, selectionAriaProps, { "aria-expanded": hasChildren ? isExpanded : undefined, "aria-owns": hasChildren ? groupId : undefined, "aria-disabled": isDisabled || undefined, "aria-busy": isLoading || undefined, "aria-keyshortcuts": actionMenuItems ? 'Shift+F10' : undefined, "aria-labelledby": titleId, "aria-level": level, tabIndex: isFocused ? 0 : -1, className: (0, classnames_1.default)('ndl-tree-view-new-item', className, {
+        role: "treeitem" }, selectionAriaProps, { "aria-expanded": hasChildren ? isExpanded : undefined, "aria-owns": hasChildren ? groupId : undefined, "aria-disabled": isDisabled || undefined, "aria-busy": isLoading || undefined, "aria-keyshortcuts": actionMenuItems ? 'Shift+F10' : undefined, "aria-labelledby": titleId, "aria-level": level, tabIndex: isFocused ? 0 : -1, className: (0, classnames_1.default)('ndl-tree-view-new-item', className, edgeClass, {
             'ndl-tree-view-new-item--disabled': isDisabled,
             'ndl-tree-view-new-item--parent': hasChildren,
             'ndl-tree-view-new-item--selected': isSelected && isSelectable,
         }), style: Object.assign({ '--tree-level': level - 1 }, style), onClick: (event) => {
             event.stopPropagation();
-            handleClick();
-        } }, htmlAttributes, restProps, { children: (0, jsx_runtime_1.jsxs)("div", { className: (0, classnames_1.default)('ndl-tree-view-new-item-content', {
+            handleClick(event);
+        } }, htmlAttributes, restProps, { id: itemId, children: (0, jsx_runtime_1.jsxs)("div", { className: (0, classnames_1.default)('ndl-tree-view-new-item-content', {
                 'ndl-tree-view-new-item-content--parent': hasChildren,
             }), children: [hasChildren && (
                 // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-static-element-interactions -- keyboard handled on tree root
@@ -434,7 +738,7 @@ const Item = (_a) => {
                                 },
                                 tabIndex: -1,
                             }, children: (0, jsx_runtime_1.jsx)(EllipsisHorizontalIconOutline_1.EllipsisHorizontalIconOutline, {}) }), (0, jsx_runtime_1.jsx)(menu_1.Menu, Object.assign({ isOpen: isMenuOpen, anchorRef: actionButtonRef, onClose: handleMenuClose }, actionMenuProps, { children: actionMenuItems }))] }))] }) })));
-    return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(conditional_wrap_1.ConditionalWrap, { shouldWrap: tooltipContent !== undefined && tooltipContent !== null, wrap: (children) => ((0, jsx_runtime_1.jsxs)(tooltip_1.Tooltip, Object.assign({ type: "simple", hoverDelay: { close: 0, open: 500 }, isDisabled: isMenuOpen, followCursor: "initial" }, tooltipProps === null || tooltipProps === void 0 ? void 0 : tooltipProps.root, { children: [(0, jsx_runtime_1.jsx)(tooltip_1.Tooltip.Trigger, Object.assign({ hasButtonWrapper: true }, tooltipProps === null || tooltipProps === void 0 ? void 0 : tooltipProps.trigger, { children: children })), (0, jsx_runtime_1.jsx)(tooltip_1.Tooltip.Content, Object.assign({}, tooltipProps === null || tooltipProps === void 0 ? void 0 : tooltipProps.content, { children: tooltipContent }))] }))), children: itemElement }), hasChildren && ((0, jsx_runtime_1.jsx)(TreeViewContext.Provider, { value: { focusedId, level: level + 1, selectionMode, setFocusedId }, children: (0, jsx_runtime_1.jsx)("div", { role: "group", id: groupId, hidden: !isExpanded, style: { '--tree-level': level - 1 }, children: annotateTreeItems(children) }) }))] }));
+    return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(conditional_wrap_1.ConditionalWrap, { shouldWrap: tooltipContent !== undefined && tooltipContent !== null, wrap: (children) => ((0, jsx_runtime_1.jsxs)(tooltip_1.Tooltip, Object.assign({ type: "simple", hoverDelay: { close: 0, open: 500 }, isDisabled: isMenuOpen, followCursor: "initial" }, tooltipProps === null || tooltipProps === void 0 ? void 0 : tooltipProps.root, { children: [(0, jsx_runtime_1.jsx)(tooltip_1.Tooltip.Trigger, Object.assign({ hasButtonWrapper: true }, tooltipProps === null || tooltipProps === void 0 ? void 0 : tooltipProps.trigger, { children: children })), (0, jsx_runtime_1.jsx)(tooltip_1.Tooltip.Content, Object.assign({}, tooltipProps === null || tooltipProps === void 0 ? void 0 : tooltipProps.content, { children: tooltipContent }))] }))), children: itemElement }), hasChildren && ((0, jsx_runtime_1.jsx)(TreeViewContext.Provider, { value: childContextValue, children: (0, jsx_runtime_1.jsx)("div", { role: "group", id: groupId, hidden: !isExpanded, style: { '--tree-level': level - 1 }, children: annotatedChildren }) }))] }));
 };
 /**
  * A skeleton placeholder for tree items that are being loaded. Renders one or
@@ -446,7 +750,7 @@ const Item = (_a) => {
  *
  * @example
  * ```tsx
- * <TreeView.Item title="Lazy folder" hasChildren isLoading={isLoading} isExpanded>
+ * <TreeView.Item title="Lazy folder" hasChildren isLoading isExpanded>
  *   {isLoading && <TreeView.SkeletonItem rows={3} />}
  * </TreeView.Item>
  * ```
@@ -456,6 +760,20 @@ const SkeletonItem = (_a) => {
     const { level } = (0, react_2.useContext)(TreeViewContext);
     return ((0, jsx_runtime_1.jsx)("div", Object.assign({ ref: ref, "aria-hidden": "true", className: (0, classnames_1.default)('ndl-tree-view-new-skeleton', className), style: Object.assign({ '--tree-level': level - 1 }, style) }, htmlAttributes, restProps, { children: Array.from({ length: rows }, (_unused, index) => ((0, jsx_runtime_1.jsx)(skeleton_1.Skeleton, { height: "18px", width: "100%" }, index))) })));
 };
+/**
+ * @remarks
+ * 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.
+ */
 const TreeView = Object.assign(Root, { Item, SkeletonItem });
 exports.TreeView = TreeView;
 //# sourceMappingURL=TreeView.js.map