feat(ui): add multi-select, type navigation, paging, and sticky scroll

Multi-selection with `selectedItemIds`, ranges anchored the way the native
list anchors them, Ctrl/Cmd toggling under either `multiSelectModifier`,
and Ctrl/Cmd+A scoped to the active sibling group before widening to its
parent, which is what `list.selectAll` does for a tree.

Buffered prefix and fuzzy type navigation, PageUp and PageDown measured
against the scroller's viewport, and sticky scroll: ancestors pin against
the nearest scrolling ancestor with VS Code's pinned-count and 40% viewport
caps, the deepest row sliding out as its subtree ends, and its own tab stop
for keyboard reveal.

Author: EhabY

packages/ui/README.md

@@ -54,7 +54,7 @@ that override live.
 ## Tree
 
 `Tree` is controlled: `nodes` describe the hierarchy, `expandedIds` controls
-branches, and `selectedItemId` controls selection. Each
+branches, and the single- or multi-selection props control selection. Each
 visible node renders as a flat `treeitem`, while normal keyboard navigation
 keeps DOM focus on the `tree` container and identifies the active row with
 `aria-activedescendant`. Focus and selection are independent.
@@ -88,20 +88,46 @@ whose children are still loading. `icon`, `action`, and `className` customize
 the row. Actions stay live on plain hover, as in the native list, and are
 isolated from row selection and expansion.
 
-Arrow Up/Down, Home, and End move the active row through visible rows. Arrow Right
+Arrow Up/Down, Home, End, PageUp/PageDown, and buffered prefix/fuzzy typing
+move the active row through visible rows. Arrow Right
 expands a branch or enters it; Arrow Left collapses it or moves to its parent.
 
 `expandMode="singleClick"` is the default: clicking a branch selects
 and toggles it, and Enter does the same. With `expandMode="doubleClick"`, a
 single click or Enter only selects and a double click toggles expansion. Space
 toggles a branch without selecting it, or selects a leaf. A normal-row twistie
 toggles without changing selection. Alt-click recursively toggles descendant
-branches.
+branches unless Alt is configured as the multi-selection modifier.
 
-Escape clears selection, then the active focus mark. Once neither remains,
-Escape is left to the host. The root `onKeyDown` runs first, so a host
+Escape clears selection. It also clears the active focus mark when the tree has
+at most one selected row; after a larger multi-selection, a second Escape
+clears the remaining focus mark. Once neither selection nor a focus mark
+remains, Escape is left to the host. The root `onKeyDown` runs first, so a host
 can intercept shortcuts with `preventDefault()`.
 
+`multiSelect` uses `selectedItemIds` and `onSelectedItemsChange` and sets
+`aria-multiselectable`. `multiSelectModifier` chooses the toggle modifier:
+`"ctrlCmd"` (the default) uses Ctrl/Cmd and `"alt"` uses Alt. Shift-click and
+Shift+Arrow extend from the selection anchor; modifier clicks take precedence
+over expansion. Ctrl/Cmd+A selects the visible rows in the active sibling
+scope.
+
+`stickyScroll` pins ancestors against the nearest scrolling ancestor. `true`
+uses a maximum of seven pinned rows; a number supplies the maximum, and the
+widget is also capped at 40% of the viewport. The pinned region is a separate
+tab stop: Arrow Up/Down move among pinned ancestors, Arrow Down/Right from the
+deepest row enters its first visible child, Enter reveals, focuses, and selects
+the real row, Arrow Left reveals and focuses it and collapses an expanded
+branch, and Space only reveals and focuses it. A plain pointer click reveals,
+focuses, and selects; a pinned twistie additionally toggles the branch.
+Selection-modifier clicks update selection without revealing the real row.
+
+Webviews do not receive `workbench.tree.*` settings automatically. Consumers
+that mirror native sticky-scroll preferences must read
+`workbench.tree.enableStickyScroll` and
+`workbench.tree.stickyScrollMaxItemCount` in the extension host and send the
+values to the webview.
+
 ```mermaid
 flowchart LR
   accTitle: Tree architecture
@@ -114,6 +140,7 @@ flowchart LR
   Commands --> Transition
   Transition --> Adapter[useTreeAdapter.ts]
   Adapter --> Rows[Tree.tsx and TreeRow.tsx]
+  Adapter --> Sticky[StickyScroll.tsx]
 ```
 
 The model, policy, and transitions stay pure. The adapter owns React and DOM

packages/ui/src/components/Tree/Tree.css

@@ -21,6 +21,42 @@
 	user-select: none;
 }
 
+/* A zero-height sticky anchor; the browser pins it, the scroll listener
+   only decides which rows it shows. */
+.ui-tree-sticky {
+	position: sticky;
+	top: 0;
+	z-index: 100;
+	height: 0;
+	outline: 0;
+}
+
+.ui-tree-sticky__rows {
+	position: absolute;
+	inset-inline: 0;
+	overflow: hidden;
+}
+
+.ui-tree-sticky__shadow {
+	position: absolute;
+	inset-inline: 0;
+	height: 3px;
+	box-shadow: var(--ui-tree-sticky-shadow) 0 6px 6px -6px inset;
+	pointer-events: none;
+}
+
+.ui-tree-sticky__rows > .ui-tree-item {
+	position: absolute;
+	inset-inline: 0;
+	background: var(--ui-tree-sticky-background);
+}
+
+/* Pinned copies show indentation, never guide rails, like the native
+   widget; without this the tree-wide hover rule lights them up. */
+.ui-tree-sticky .ui-tree-item__indent {
+	display: none;
+}
+
 /* Native skips hover on selected and focused rows, keeping their outlines. */
 .ui-tree-item:not([aria-selected="true"]):not(.ui-tree-item--focused)
 	> .ui-tree-item__row:hover {

packages/ui/src/components/Tree/Tree.stories.tsx

@@ -132,6 +132,75 @@ const NESTED_FILES = [
 	]),
 	node("README.md", { icon: "markdown" }),
 ];
+const DEEP_FILES = ["alpha", "beta"].map((name) =>
+	branch(name, [
+		branch(
+			`${name}/src`,
+			Array.from({ length: 12 }, (_, index) =>
+				node(`${name}/src/file-${index}`, {
+					label: `file-${index}.ts`,
+					icon: "symbol-class",
+				}),
+			),
+			{ label: "src" },
+		),
+	]),
+);
+
+export const StickyScroll: Story = {
+	render: () => (
+		<div
+			data-testid="scroller"
+			style={{ height: "140px", overflow: "auto", ...treeStyle }}
+			ref={(scroller) => {
+				if (scroller) scroller.scrollTop = 143;
+			}}
+		>
+			<TreeDemo
+				aria-label="Sticky explorer"
+				variant="explorer"
+				stickyScroll
+				nodes={DEEP_FILES}
+			/>
+		</div>
+	),
+	play: async ({ canvasElement }) => {
+		await waitFor(() =>
+			expect(
+				canvasElement.querySelector(".ui-tree-sticky__rows"),
+			).not.toBeNull(),
+		);
+		await expect(
+			within(canvasElement).getByTestId("scroller").scrollTop,
+		).toBeGreaterThan(0);
+	},
+};
+
+export const MultiSelect: Story = {
+	render: () => (
+		<TreeDemo
+			aria-label="Multi-select explorer"
+			variant="explorer"
+			multiSelect
+			selectedItemIds={["tree", "styles"]}
+			nodes={FILES}
+			style={treeStyle}
+		/>
+	),
+	play: async ({ canvasElement }) => {
+		const canvas = within(canvasElement);
+		const tree = canvas.getByRole("tree");
+		const readme = canvas.getByRole("treeitem", { name: "README.md" });
+		await fireEvent.click(readme, { ctrlKey: true });
+		await expect(readme).toHaveAttribute("aria-selected", "true");
+		await expect(
+			canvas.getByRole("treeitem", { name: "Tree.tsx" }),
+		).toHaveAttribute("aria-selected", "true");
+		await expect(canvasElement.ownerDocument.activeElement).toBe(tree);
+		await expect(tree).toHaveAttribute("aria-activedescendant", readme.id);
+	},
+};
+
 export const Focused: Story = {
 	render: () => singleTree("Focused explorer", "tree", FILES, "explorer"),
 	play: async ({ canvasElement }) => {

packages/ui/src/components/Tree/Tree.tsx

@@ -2,12 +2,14 @@ import { type ComponentPropsWithRef, type Ref, useId, useRef } from "react";
 
 import { cx } from "#cx";
 
+import { StickyScroll } from "./sticky/StickyScroll";
 import "./Tree.css";
 import { TreeRow } from "./TreeRow";
 import { type SelectionProps, useTreeAdapter } from "./useTreeAdapter";
 
 import type { TreeNode } from "./treeModel";
 
+const DEFAULT_STICKY_COUNT = 7;
 const NO_IDS: readonly string[] = [];
 
 interface TreeBaseProps extends Omit<
@@ -19,6 +21,8 @@ interface TreeBaseProps extends Omit<
 	onExpandedIdsChange?: (expandedIds: readonly string[]) => void;
 	variant?: "default" | "explorer";
 	expandMode?: "singleClick" | "doubleClick";
+	multiSelectModifier?: "ctrlCmd" | "alt";
+	stickyScroll?: boolean | number;
 }
 
 export type TreeProps = TreeBaseProps & SelectionProps;
@@ -46,8 +50,13 @@ export function Tree(props: TreeProps): React.JSX.Element {
 		onExpandedIdsChange: _onExpandedIdsChange,
 		variant = "default",
 		expandMode = "singleClick",
+		multiSelectModifier = "ctrlCmd",
+		stickyScroll = false,
+		multiSelect = false,
 		selectedItemId: _selectedItemId,
 		onSelectedItemChange: _onSelectedItemChange,
+		selectedItemIds: _selectedItemIds,
+		onSelectedItemsChange: _onSelectedItemsChange,
 		className,
 		onBlur,
 		onFocus,
@@ -61,6 +70,7 @@ export function Tree(props: TreeProps): React.JSX.Element {
 		...props,
 		expandedIds,
 		expandMode,
+		multiSelectModifier,
 		treeRef,
 	});
 
@@ -76,6 +86,7 @@ export function Tree(props: TreeProps): React.JSX.Element {
 			aria-activedescendant={
 				adapter.focusedId ? `${treeDomId}-${adapter.focusedId}` : undefined
 			}
+			aria-multiselectable={multiSelect || undefined}
 			className={cx(
 				"ui-tree",
 				variant === "explorer" && "ui-tree--explorer",
@@ -107,6 +118,13 @@ export function Tree(props: TreeProps): React.JSX.Element {
 			}}
 			onKeyDown={(event) => adapter.onKeyDown(event)}
 		>
+			{stickyScroll ? (
+				<StickyScroll
+					maxCount={stickyScroll === true ? DEFAULT_STICKY_COUNT : stickyScroll}
+					adapter={adapter}
+					treeRef={treeRef}
+				/>
+			) : null}
 			{adapter.model.rows.map((row) => (
 				<TreeRow
 					key={row.node.id}

packages/ui/src/components/Tree/TreeRow.tsx

@@ -111,7 +111,7 @@ export function TreeRow(props: TreeRowProps): React.JSX.Element {
 					event.target instanceof Element &&
 					event.target.closest(".ui-tree-item__chevron") !== null;
 				if (onClick) onClick(event, twistie);
-				else adapter?.onPointer(row, event, twistie);
+				else adapter?.onPointer(row, event, twistie, "row");
 			}}
 		>
 			<TreeRowSurface row={row} activeGuideIds={activeGuideIds} />

packages/ui/src/components/Tree/rowDom.ts

@@ -42,3 +42,19 @@ export function closestRow(target: EventTarget | null): HTMLElement | null {
 		? target.closest<HTMLElement>('[role="treeitem"]')
 		: null;
 }
+
+export function scrollableAncestor(
+	element: HTMLElement,
+): HTMLElement | undefined {
+	for (
+		let parent = element.parentElement;
+		parent !== null;
+		parent = parent.parentElement
+	) {
+		const { overflowY } = getComputedStyle(parent);
+		if (overflowY === "auto" || overflowY === "scroll") {
+			return parent;
+		}
+	}
+	return undefined;
+}