feat(ui): give tree rows and icon buttons native hovers

Rows hover with their text value, as VS Code's tree falls back to the
label when an item has no tooltip; `tooltip` overrides it and null opts
out. Ctrl+K Ctrl+I opens the focused row's hover, the chord bound to
list.showHover, and IconButton hints with its label like an action bar
item.

One bubble serves a whole tree rather than one per trigger, the way a
list hands a single hover delegate to its rows and their action bars.
Rows report the element under the pointer through `HoverDelegateScope`
and an invisible anchor moves to it. That single widget is also the only
place a delay rule can live, and native's rule needs one: each new target
waits out `workbench.hover.delay`, except inside a row's action bar, the
dense cluster native grants an instant handoff.

A managed hover always uses hoverPosition 2, whatever the widget's own
default, so the bubble sits 2px into the bottom edge of its target rather
than above it. Placement then splits on the delegate: an element-placed
hover, which is what an action bar button gets, centers under it, while a
mouse-placed one, which is what a row gets, follows the cursor.

Measured in Chrome: label to a button 513ms, button to button 19ms, and
mounting 2,000 rows 189ms against 515ms for a Radix root per row. Also
pins the sticky container at native's z-index 13, below the hover's 40,
so pinned rows no longer paint over a bubble, and drops the menu parity
story's trigger button so both menus line up.

Author: EhabY

packages/ui/README.md

@@ -141,6 +141,7 @@ flowchart LR
   Transition --> Adapter[useTreeAdapter.ts]
   Adapter --> Rows[Tree.tsx and TreeRow.tsx]
   Adapter --> Sticky[StickyScroll.tsx]
+  Rows --> Hover[TreeHover.tsx]
 ```
 
 The model, policy, and transitions stay pure. The adapter owns React and DOM
@@ -155,6 +156,15 @@ while the tree has focus. The package default uses inset Modern UI rows;
 `data-ui-style="stable"` restores edge-to-edge square rows and stable focus
 styling.
 
+Labels hover with the node's text value, so truncated rows stay readable.
+Set `tooltip` for richer content or `null` to opt out. One bubble serves the
+whole tree, as in the native list: an invisible anchor moves to whatever the
+pointer reaches, taking its x from the cursor and its y from the target's box,
+the way a native hover placed at the mouse does. Each new target waits out the
+show delay, except within a row's action bar, where crossing between buttons is
+instant, the exception native grants a dense cluster of targets. Ctrl+K Ctrl+I opens the focused
+row's hover with no delay at all, and moving the focus closes it.
+
 ## Overlays
 
 `Tooltip`, `ContextMenu`, and `DropdownMenu` wrap the Radix primitives,
@@ -172,7 +182,18 @@ tooltips.
 `TooltipProvider` ancestor. Mount one provider per app so that a pointer
 moving between nearby triggers skips the show delay, like native hovers.
 The delay defaults to 500ms, matching VS Code's `workbench.hover.delay`,
-and tooltips stop growing at half the window height.
+and tooltips stop growing at half the window height. Components that own
+their hovers fall back to a private provider when the app has none, so
+`Tree` rows and `IconButton` work unwrapped. A private provider keeps its own
+skip-delay, though, so an app with several of them makes every hover wait out
+the full delay; mount one provider and they share it. `IconButton` hints with
+its label like a native action bar item; pass `tooltip` to say something else,
+or `null` for a button that stays quiet.
+
+`HoverDelegateScope` hands every `Tooltip` inside it to one shared bubble
+instead of a bubble each, the way a VS Code list serves its rows and their
+action bars from a single hover widget. `Tree` uses it, which is also what
+lets one place decide when a hover is instant rather than delayed.
 
 Overlay content is portalled to `body`, inherits webview typography from
 there, and shares the `.ui-overlay` base for stacking, border, shadow,

packages/ui/package.json

@@ -27,6 +27,7 @@
 	"dependencies": {
 		"@radix-ui/react-context-menu": "^2.3.7",
 		"@radix-ui/react-dropdown-menu": "^2.1.24",
+		"@radix-ui/react-slot": "^1.3.3",
 		"@radix-ui/react-tooltip": "^1.2.16",
 		"@vscode/codicons": "catalog:"
 	},

packages/ui/src/components/IconButton/IconButton.tsx

@@ -1,9 +1,10 @@
-import { type ComponentProps } from "react";
+import { type ComponentProps, type ReactNode } from "react";
 
 import { cx } from "#cx";
 
 import "../control.css";
 import { Icon } from "../Icon/Icon";
+import { Tooltip, TooltipScope } from "../Tooltip/Tooltip";
 
 import "./IconButton.css";
 
@@ -15,18 +16,20 @@ export interface IconButtonProps extends Omit<
 > {
 	icon: CodiconName;
 	label: string;
+	/** Hover content; defaults to the label, `null` opts out. */
+	tooltip?: ReactNode;
 }
 
-/* No default title: native toolbar buttons hint with the styled hover
-   widget, not the browser box. Wrap in Tooltip for that. */
+/* Hints through the hover widget, never the browser title box. */
 export function IconButton({
 	icon,
 	label,
+	tooltip = label,
 	className,
 	type = "button",
 	...props
 }: IconButtonProps): React.JSX.Element {
-	return (
+	const button = (
 		<button
 			{...props}
 			type={type}
@@ -36,4 +39,10 @@ export function IconButton({
 			<Icon name={icon} />
 		</button>
 	);
+	if (!tooltip) return button;
+	return (
+		<TooltipScope>
+			<Tooltip content={tooltip}>{button}</Tooltip>
+		</TooltipScope>
+	);
 }

packages/ui/src/components/Tooltip/Tooltip.tsx

@@ -1,26 +1,89 @@
+import { Slot } from "@radix-ui/react-slot";
 import * as TooltipPrimitive from "@radix-ui/react-tooltip";
+import {
+	createContext,
+	use,
+	type ComponentProps,
+	type ComponentPropsWithRef,
+	type PointerEvent,
+	type ReactNode,
+} from "react";
 
 import { cx } from "#cx";
 
 import "../overlay.css";
 
 import "./Tooltip.css";
 
-import type { ComponentProps, ComponentPropsWithRef, ReactNode } from "react";
-
 export type TooltipProviderProps = ComponentProps<
 	typeof TooltipPrimitive.Provider
 >;
 
+/** VS Code's `workbench.hover.delay`. */
+const DEFAULT_DELAY_MS = 500;
+
 /**
  * App-level tooltip context; `Tooltip` throws without one. Sharing a single
  * provider lets a pointer moving between nearby triggers skip the show delay,
- * like native hovers. The default delay is VS Code's `workbench.hover.delay`.
+ * like native hovers.
  */
-export function TooltipProvider(
-	props: TooltipProviderProps,
-): React.JSX.Element {
-	return <TooltipPrimitive.Provider delayDuration={500} {...props} />;
+export function TooltipProvider({
+	delayDuration = DEFAULT_DELAY_MS,
+	...props
+}: TooltipProviderProps): React.JSX.Element {
+	return (
+		<TooltipContext value={delayDuration}>
+			<TooltipPrimitive.Provider delayDuration={delayDuration} {...props} />
+		</TooltipContext>
+	);
+}
+
+const TooltipContext = createContext<number | null>(null);
+
+/** Owns tooltips without forcing a provider on consumers; defers to any app-level one. */
+export function TooltipScope({ children }: { children: ReactNode }): ReactNode {
+	return use(TooltipContext) === null ? (
+		<TooltipProvider>{children}</TooltipProvider>
+	) : (
+		children
+	);
+}
+
+/** The surrounding provider's show delay, for surfaces that time their own. */
+export function useTooltipDelay(): number {
+	return use(TooltipContext) ?? DEFAULT_DELAY_MS;
+}
+
+export interface HoverTarget {
+	readonly content: ReactNode;
+	readonly element: HTMLElement;
+}
+
+/** `immediate` skips the show delay. */
+export type HoverDelegate = (
+	target: HoverTarget | undefined,
+	immediate?: boolean,
+) => void;
+
+const HoverDelegateContext = createContext<HoverDelegate | undefined>(
+	undefined,
+);
+
+/**
+ * Hands every `Tooltip` inside to one shared bubble, the way a VS Code list
+ * serves its rows and their action bars from a single hover widget. Pass
+ * `undefined` to hand them back.
+ */
+export function HoverDelegateScope({
+	delegate,
+	children,
+}: {
+	delegate: HoverDelegate | undefined;
+	children: ReactNode;
+}): React.JSX.Element {
+	return (
+		<HoverDelegateContext value={delegate}>{children}</HoverDelegateContext>
+	);
 }
 
 export interface TooltipProps extends Omit<
@@ -30,22 +93,41 @@ export interface TooltipProps extends Omit<
 	content: ReactNode;
 	/** The trigger element; must accept a forwarded ref (asChild). */
 	children: ReactNode;
+	open?: boolean;
+	onOpenChange?: (open: boolean) => void;
 }
 
 /** Hover bubble matching the native hover widget; requires a `TooltipProvider` ancestor. */
 export function Tooltip({
 	content,
 	children,
 	className,
+	open,
+	onOpenChange,
 	...props
 }: TooltipProps): React.JSX.Element {
+	const delegate = use(HoverDelegateContext);
+	if (delegate) {
+		return (
+			<Slot
+				onPointerEnter={(event: PointerEvent<HTMLElement>) =>
+					delegate({ content, element: event.currentTarget })
+				}
+				onPointerLeave={() => delegate(undefined)}
+			>
+				{children}
+			</Slot>
+		);
+	}
 	return (
-		<TooltipPrimitive.Root>
+		<TooltipPrimitive.Root open={open} onOpenChange={onOpenChange}>
 			<TooltipPrimitive.Trigger asChild>{children}</TooltipPrimitive.Trigger>
 			<TooltipPrimitive.Portal>
 				<TooltipPrimitive.Content
-					// Native hovers sit flush with the target, left-aligned
-					align="start"
+					// Native sits a hover 2px into the bottom edge of its target.
+					side="bottom"
+					sideOffset={-2}
+					align="center"
 					collisionPadding={8}
 					{...props}
 					className={cx("ui-overlay ui-tooltip", className)}

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

@@ -1,6 +1,7 @@
 .ui-tree {
 	--ui-tree-indent-size: 8px;
 	--ui-tree-row-height: 22px;
+	position: relative;
 	width: 100%;
 	min-width: 0;
 	outline: 0;
@@ -26,7 +27,8 @@
 .ui-tree-sticky {
 	position: sticky;
 	top: 0;
-	z-index: 100;
+	/* Native pins the sticky container below the hover widget's stacking */
+	z-index: 13;
 	height: 0;
 	outline: 0;
 }
@@ -205,3 +207,10 @@
 	> .ui-tree-item__row {
 	outline-color: var(--ui-list-focus-and-selection-outline);
 }
+
+/* The shared hover anchors here instead of to each row's label. */
+.ui-tree-hover-anchor {
+	position: absolute;
+	pointer-events: none;
+	opacity: 0;
+}