entasis 0.11.0 → 0.13.0

package/dist/components/Popover/popover.theme.d.ts

@@ -36,14 +36,14 @@ export declare const popoverTheme: {
             };
         };
     }>;
-    root: (props?: (import("../../utils/cva/types.js").CVAVariantSchema<{
+    root: (props?: (import("../../utils/cva/types.ts").CVAVariantSchema<{
         mode: {
             floating: string;
             inline: string;
             mobileSheet: string;
         };
-    }> & import("../../utils/cva/types.js").CVAClassProp) | undefined) => string;
-    popover: (props?: (import("../../utils/cva/types.js").CVAVariantSchema<{
+    }> & import("../../utils/cva/types.ts").CVAClassProp) | undefined) => string;
+    popover: (props?: (import("../../utils/cva/types.ts").CVAVariantSchema<{
         size: {
             small: string;
             normal: string;
@@ -54,7 +54,12 @@ export declare const popoverTheme: {
             inline: string;
             mobileSheet: string;
         };
-    }> & import("../../utils/cva/types.js").CVAClassProp) | undefined) => string;
+        arrow: {
+            true: string;
+            false: string;
+        };
+    }> & import("../../utils/cva/types.ts").CVAClassProp) | undefined) => string;
+    arrow: (props?: import("../../utils/cva/types.ts").CVAClassProp | undefined) => string;
 };
 export type PopoverTheme = typeof popoverTheme;
 export type PopoverThemeProps = InferComponentTheme<PopoverTheme>;
@@ -77,14 +82,14 @@ export declare const setPopoverTheme: (theme: InferComponentTheme<{
             };
         };
     }>;
-    root: (props?: (import("../../utils/cva/types.js").CVAVariantSchema<{
+    root: (props?: (import("../../utils/cva/types.ts").CVAVariantSchema<{
         mode: {
             floating: string;
             inline: string;
             mobileSheet: string;
         };
-    }> & import("../../utils/cva/types.js").CVAClassProp) | undefined) => string;
-    popover: (props?: (import("../../utils/cva/types.js").CVAVariantSchema<{
+    }> & import("../../utils/cva/types.ts").CVAClassProp) | undefined) => string;
+    popover: (props?: (import("../../utils/cva/types.ts").CVAVariantSchema<{
         size: {
             small: string;
             normal: string;
@@ -95,9 +100,14 @@ export declare const setPopoverTheme: (theme: InferComponentTheme<{
             inline: string;
             mobileSheet: string;
         };
-    }> & import("../../utils/cva/types.js").CVAClassProp) | undefined) => string;
+        arrow: {
+            true: string;
+            false: string;
+        };
+    }> & import("../../utils/cva/types.ts").CVAClassProp) | undefined) => string;
+    arrow: (props?: import("../../utils/cva/types.ts").CVAClassProp | undefined) => string;
 }>) => void;
-export declare const usePopoverTheme: import("../../utils/cva/theme.js").UseComponentTheme<{
+export declare const usePopoverTheme: import("../../utils/cva/theme.ts").UseComponentTheme<{
     motion: import("../../utils/motion/index.js").MotionResolver<{
         readonly mode: {
             readonly floating: {};
@@ -116,14 +126,14 @@ export declare const usePopoverTheme: import("../../utils/cva/theme.js").UseComp
             };
         };
     }>;
-    root: (props?: (import("../../utils/cva/types.js").CVAVariantSchema<{
+    root: (props?: (import("../../utils/cva/types.ts").CVAVariantSchema<{
         mode: {
             floating: string;
             inline: string;
             mobileSheet: string;
         };
-    }> & import("../../utils/cva/types.js").CVAClassProp) | undefined) => string;
-    popover: (props?: (import("../../utils/cva/types.js").CVAVariantSchema<{
+    }> & import("../../utils/cva/types.ts").CVAClassProp) | undefined) => string;
+    popover: (props?: (import("../../utils/cva/types.ts").CVAVariantSchema<{
         size: {
             small: string;
             normal: string;
@@ -134,7 +144,12 @@ export declare const usePopoverTheme: import("../../utils/cva/theme.js").UseComp
             inline: string;
             mobileSheet: string;
         };
-    }> & import("../../utils/cva/types.js").CVAClassProp) | undefined) => string;
+        arrow: {
+            true: string;
+            false: string;
+        };
+    }> & import("../../utils/cva/types.ts").CVAClassProp) | undefined) => string;
+    arrow: (props?: import("../../utils/cva/types.ts").CVAClassProp | undefined) => string;
 }>;
 export declare const usePopoverMotion: () => import("../../utils/motion/index.js").ComponentMotion<{
     readonly mode: {

package/dist/components/Popover/popover.theme.js

@@ -37,12 +37,36 @@ const defaultPopover = cva({
             // Same visuals as `floating` — only the positioning of the wrapper differs.
             inline: '',
             mobileSheet: 'max-h-[85dvh] w-full max-w-none overflow-auto rounded-b-none rounded-t-xl pb-[calc(env(safe-area-inset-bottom)+1rem)]'
+        },
+        // The arrow is placed against the panel's box.
+        arrow: {
+            true: 'relative',
+            false: ''
         }
     },
     defaultVariants: {
-        mode: 'floating'
+        mode: 'floating',
+        arrow: false
     }
 });
+// The arrow is a rotated square the panel's colour, half of it poking out of the edge that faces
+// the trigger. It sits behind the panel's content (`-z-10` inside the panel's own stacking
+// context) but above the panel's own border, so the half inside the panel hides the border
+// beneath it and the half outside carries the edge on its two outer sides: the corner that
+// points at the trigger is the top-left one before the 45° turn when the panel is below it, the
+// bottom-right one when above, and so on. Its position along the edge and its edge offset are
+// written by the placement, with the side as `data-side`.
+const defaultPopoverArrow = cva({
+    base: [
+        // The panel's elevation lightens its surface in dark mode with an inset tint (`raised-3`); the
+        // arrow paints the same tint, without the drop shadow, or it reads darker than the panel.
+        'bg-surface-floating pointer-events-none absolute -z-10 size-2.5 rotate-45 rounded-xs border border-transparent bg-clip-padding shadow-[inset_0_0_0_9999px_var(--elevation-tint-3)]',
+        'data-[side=bottom]:border-t-neutral-muted data-[side=bottom]:border-l-neutral-muted',
+        'data-[side=top]:border-r-neutral-muted data-[side=top]:border-b-neutral-muted',
+        'data-[side=right]:border-b-neutral-muted data-[side=right]:border-l-neutral-muted',
+        'data-[side=left]:border-t-neutral-muted data-[side=left]:border-r-neutral-muted'
+    ].join(' ')
+});
 // A floating panel scales in place; the mobile sheet slides up from the bottom edge.
 // `duration` / `easing` stay tokens, so `<Theme motion>` and reduced motion reach both.
 export const defaultPopoverMotion = motion({
@@ -68,7 +92,8 @@ export const defaultPopoverMotion = motion({
 export const popoverTheme = {
     motion: defaultPopoverMotion,
     root: defaultPopoverContainer,
-    popover: defaultPopover
+    popover: defaultPopover,
+    arrow: defaultPopoverArrow
 };
 export const setPopoverTheme = setComponentTheme('popover');
 export const usePopoverTheme = useComponentTheme('popover', popoverTheme);

package/dist/components/PopupMenu/PopupMenu.svelte

@@ -1,13 +1,26 @@
 <script lang="ts">
-	import { providePopupMenuPanelSize } from './popupMenu.context.js';
+	import {
+		closeMenuTree,
+		providePopupMenuLevel,
+		providePopupMenuPanelSize,
+		providePopupMenuRoot,
+		type PopupMenuRoot
+	} from './popupMenu.context.js';
 	import { createBindableValue } from '../../utils/state.svelte.js';
 	import Popover from '../Popover/Popover.svelte';
 	import Menu from '../Menu/Menu.svelte';
-	import type { PopupMenuProps } from './popupMenu.props.js';
+	import type { PopupMenuInternalProps } from './popupMenu.props.js';
 	import { usePopupMenuTheme } from './popupMenu.theme.js';
+	import { untrack, type Snippet } from 'svelte';
+	import { createAttachmentKey } from 'svelte/attachments';
 	import { on } from 'svelte/events';
-	import type { PopoverState } from '../Popover/popover.state.svelte.js';
+	import { popoverInternals, type PopoverState } from '../Popover/popover.state.svelte.js';
+	import type { PopoverApi } from '../Popover/popover.api.js';
 	import { hasSubmenuItems } from '../Menu/menuTree.js';
+	import { createOpenChangeDetails, type OpenChangeDetails } from '../../utils/openChange.js';
+	import { getTabbableElements } from '../../utils/focus.js';
+	import { hasShortcutModifier } from '../../utils/useKeyDown.svelte.js';
+	import { triggerFocusTarget } from '../../utils/trigger.js';
 
 	let {
 		menu,
@@ -21,8 +34,12 @@
 		class: className,
 		theme,
 		size = 'small',
+		submenuOf,
+		isSubmenu = false,
+		nativeMenu = true,
+		trigger,
 		...popoverProps
-	}: PopupMenuProps = $props();
+	}: PopupMenuInternalProps = $props();
 	const classes = $derived(usePopupMenuTheme(theme));
 	// Submenus rendered by the Menu below open in a panel of this same size.
 	providePopupMenuPanelSize(() => size);
@@ -47,32 +64,183 @@
 		usesStackedSubmenus ? false : mobileSheetSizeTransition
 	);
 
-	const setOpen = (nextOpen: boolean) => {
+	// The Popover's `onOpenChange`: the details (reason, event, `cancel()`) pass through, so a
+	// consumer that cancels keeps the menu as it is.
+	const setOpen = (nextOpen: boolean, details: OpenChangeDetails) => {
 		if (openState.value === nextOpen) return;
+		onOpenChange?.(nextOpen, details);
+		if (details.isCanceled) return;
+		if (!nextOpen) arrowOpen = null;
 		openState.value = nextOpen;
-		onOpenChange?.(nextOpen);
 	};
 
-	const closeOnClick = (popover: PopoverState) => (node: HTMLElement) => {
-		if (closeOnItemClick) {
-			return on(node, 'click', (e) => {
-				const path = e.composedPath();
-				const buttonOrLink = path.find(
-					(node) => node instanceof HTMLButtonElement || node instanceof HTMLAnchorElement
-				);
-				const shouldKeepOpen = path.some(
-					(node) =>
-						node instanceof HTMLElement && node.getAttribute('data-menu-keep-open') === 'true'
-				);
+	// The popover this PopupMenu renders and its Menu element, known once the menu mounts.
+	let popoverState: PopoverState | null = null;
+	let menuElement: HTMLElement | null = null;
+	// Where focus goes when the tree closes, chosen as the root panel's focus scope chooses: the
+	// trigger, else the element that had focus when the menu opened (a context menu's target).
+	let opener: HTMLElement | null = null;
+	// A submenu MenuFloating renders joins the tree it opens from: that root's `closeOnItemClick`
+	// decides for every level, and an item press anywhere closes the whole tree once. Every other
+	// PopupMenu, one nested in a menu's header, footer or trigger included, roots its own tree.
+	// Membership is settled when the menu mounts.
+	const tree = untrack(() => submenuOf);
+	providePopupMenuLevel(untrack(() => !!submenuOf || isSubmenu));
 
-				if (buttonOrLink && !shouldKeepOpen) {
-					popover?.close();
-				}
-			});
+	/** Where focus goes when the tree is left by keyboard: the root trigger, else the opener. */
+	const leaveTarget = (): HTMLElement | null => {
+		const anchor = popoverState?.triggerReference;
+		const trigger = anchor?.isConnected ? triggerFocusTarget(anchor) : null;
+		return trigger ?? (opener?.isConnected ? opener : null);
+	};
+
+	const root: PopupMenuRoot = tree ?? {
+		closeOnItemClick: () => closeOnItemClick,
+		nativeMenu: () => nativeMenu,
+		close: (event) => {
+			const details = { reason: 'item-press', event } as const;
+			if (popoverState) {
+				closeMenuTree(popoverState, popoverState.triggerReference ?? opener, menuElement, details);
+			} else setOpen(false, createOpenChangeDetails(details));
+		},
+		leave: (event) => {
+			const details = { reason: 'focus-out', event, interaction: 'keyboard' } as const;
+			if (!popoverState) return;
+			// Focus lands on the trigger before the keydown's default action runs: Tab then carries
+			// on from the trigger, to the control after it. Shift+Tab stays on the trigger.
+			const closed = closeMenuTree(popoverState, leaveTarget(), menuElement, details);
+			if (!closed || event.shiftKey) event.preventDefault();
 		}
 	};
+	if (!tree) providePopupMenuRoot(root);
+
+	// Tab or Shift+Tab in a panel leaves the whole tree, unless another tabbable control of the same
+	// panel (a field or a link in its header or footer) comes next in that direction. Focus on
+	// the menu itself has no row to move on from, so it always leaves.
+	const leavesOnTab = (node: HTMLElement, event: KeyboardEvent) => {
+		const target = event.target;
+		if (!(target instanceof HTMLElement) || target.matches('[role="menu"]')) return true;
+		const tabbable = getTabbableElements(node);
+		const index = tabbable.indexOf(target);
+		if (index === -1) return true;
+		return event.shiftKey ? index === 0 : index === tabbable.length - 1;
+	};
+
+	const attachTree = (popover: PopoverState) => (node: HTMLElement) => {
+		popoverState = popover;
+		menuElement = node;
+		const active = document.activeElement;
+		opener =
+			active instanceof HTMLElement && active !== document.body && !node.contains(active)
+				? active
+				: null;
+		const off = on(node, 'click', (e) => {
+			if (!root.closeOnItemClick()) return;
+			const path = e.composedPath();
+			const buttonOrLink = path.find(
+				(node) => node instanceof HTMLButtonElement || node instanceof HTMLAnchorElement
+			);
+			const shouldKeepOpen = path.some(
+				(node) => node instanceof HTMLElement && node.getAttribute('data-menu-keep-open') === 'true'
+			);
+
+			if (buttonOrLink && !shouldKeepOpen) root.close(e);
+		});
+		// The browser's own menu over a panel hides the one the user is looking at, padding included.
+		const offNativeMenu = on(popover.dialogElement ?? node, 'contextmenu', (event) => {
+			if (root.nativeMenu?.() === false) event.preventDefault();
+		});
+		const offKeys = on(node, 'keydown', (event) => {
+			// Ctrl+Tab and Cmd+Tab switch the browser's tabs; Alt+Tab is how Safari reaches every control.
+			if (event.key !== 'Tab' || event.defaultPrevented || event.ctrlKey || event.metaKey) return;
+			if (!leavesOnTab(node, event)) return;
+			root.leave?.(event);
+		});
+		return () => {
+			off();
+			offKeys();
+			offNativeMenu();
+			if (popoverState === popover) popoverState = null;
+			if (menuElement === node) menuElement = null;
+		};
+	};
+
+	// A keyboard open (Enter, Space, ArrowDown, ArrowUp, Shift+F10) puts focus on the first row,
+	// ArrowUp on the last; a pointer open focuses the menu itself; a hover open leaves focus alone.
+	// A menu opened from code keeps `'container'`.
+	const initialFocus = (popover: PopoverState) => {
+		if (menu.focusOnMount !== undefined) return menu.focusOnMount;
+		const reason = popover.openReason;
+		if (reason === 'keyboard') {
+			const event = popover.lastOpenChange?.event ?? arrowOpen?.event;
+			return event instanceof KeyboardEvent && event.key === 'ArrowUp' ? 'last' : true;
+		}
+		if (reason === 'hover') return false;
+		return arrowOpen ? (arrowOpen.event.key === 'ArrowUp' ? 'last' : true) : 'container';
+	};
+
+	// The ArrowDown or ArrowUp that opened the menu from its button: the Popover sees that open as
+	// one made from code, so the key is kept here until the menu has taken focus. A menu closed any
+	// other way (code setting `open`, a cancelled change) must not leave it for the next open.
+	let arrowOpen: { event: KeyboardEvent } | null = null;
+	$effect(() => {
+		if (!openState.value) arrowOpen = null;
+	});
+	const openFromArrow = (node: HTMLElement, event: KeyboardEvent) => {
+		if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return;
+		if (event.defaultPrevented || hasShortcutModifier(event)) return;
+		if (node.matches(':disabled') || node.getAttribute('aria-disabled') === 'true') return;
+		event.preventDefault();
+		if (openState.value) {
+			// Already open: ArrowDown or ArrowUp moves into it, like Tab does.
+			menuElement?.querySelector<HTMLElement>('[role="menu"]')?.focus();
+			return;
+		}
+		const details = createOpenChangeDetails({
+			reason: 'list-navigation',
+			event,
+			trigger: node,
+			interaction: 'keyboard'
+		});
+		arrowOpen = { event };
+		setOpen(true, details);
+		if (details.isCanceled) arrowOpen = null;
+	};
+	const arrowKey = createAttachmentKey();
+	const openFromArrowKey = (node: HTMLElement) =>
+		on(node, 'keydown', (e) => openFromArrow(node, e));
+
+	// A trigger made with a snippet is the consumer's own element, so there is no attachment to
+	// put the key handler on: the snippet's Popover is remembered as it renders, and a keydown
+	// that bubbles up from the element it anchors to is handled the same way.
+	let snippetPopover: PopoverState | null = null;
+	const rememberSnippetPopover = (popover: PopoverApi) => {
+		snippetPopover = popoverInternals(popover);
+		return popover;
+	};
+	const usesSnippetTrigger = $derived(typeof trigger === 'function');
+	$effect(() => {
+		if (!usesSnippetTrigger) return;
+		return on(document, 'keydown', (event) => {
+			const target = event.target;
+			const anchor = snippetPopover?.triggerReference ?? snippetPopover?.referenceElement;
+			if (!(target instanceof HTMLElement) || !anchor || target !== anchor) return;
+			openFromArrow(target, event);
+		});
+	});
+
+	const resolvedTrigger = $derived(
+		trigger !== undefined && trigger !== false && typeof trigger === 'object'
+			? { ...trigger, [arrowKey]: openFromArrowKey }
+			: trigger
+	);
 </script>
 
+{#snippet snippetTrigger(popover: PopoverApi)}
+	{@const remembered = rememberSnippetPopover(popover)}
+	{@render (trigger as Snippet<[PopoverApi]>)(remembered)}
+{/snippet}
+
 <Popover
 	open={openState.value}
 	onOpenChange={setOpen}
@@ -83,9 +251,12 @@
 	mobileSheetSizeTransition={resolvedMobileSheetSizeTransition}
 	class={panelClass}
 	{theme}
+	trigger={typeof resolvedTrigger === 'function' ? snippetTrigger : resolvedTrigger}
 	{...popoverProps}
 >
 	{#snippet children(popover)}
-		<Menu focusOnMount="container" {...menu} {@attach closeOnClick(popover)} />
+		{@const internals = popoverInternals(popover)}
+		{@const focusOnMount = untrack(() => initialFocus(internals))}
+		<Menu {...menu} {focusOnMount} {@attach attachTree(internals)} />
 	{/snippet}
 </Popover>

package/dist/components/PopupMenu/PopupMenu.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { PopupMenuProps } from './popupMenu.props.js';
-declare const PopupMenu: import("svelte").Component<PopupMenuProps, {}, "open">;
+import type { PopupMenuInternalProps } from './popupMenu.props.js';
+declare const PopupMenu: import("svelte").Component<PopupMenuInternalProps, {}, "open">;
 type PopupMenu = ReturnType<typeof PopupMenu>;
 export default PopupMenu;

package/dist/components/PopupMenu/popupMenu.context.d.ts

@@ -1,4 +1,46 @@
 import type { PopoverProps } from '../Popover/popover.props.js';
+import type { PopoverState } from '../Popover/popover.state.svelte.js';
+import type { OpenChangeInit } from '../../utils/openChange.js';
 export type PopupMenuPanelSize = NonNullable<PopoverProps['size']>;
 export declare const providePopupMenuPanelSize: (read: () => PopupMenuPanelSize) => () => PopupMenuPanelSize;
 export declare const usePopupMenuPanelSize: () => (() => PopupMenuPanelSize) | undefined;
+export interface PopupMenuRoot {
+    /** The root's `closeOnItemClick`: whether an item press anywhere in the tree closes it. */
+    closeOnItemClick: () => boolean;
+    /**
+     * Closes every open level of the tree once, focus going back to where the root returns it.
+     * `event` is the item press, reported to each level's `onOpenChange` as `reason: 'item-press'`.
+     */
+    close: (event?: Event) => void;
+    /**
+     * Tab or Shift+Tab pressed in a panel of the tree: closes every level and hands focus to the
+     * root trigger (Shift+Tab stays there; Tab lets the browser carry on from it, so focus lands on
+     * the control after the trigger). Optional: a host that does not provide it leaves Tab alone.
+     */
+    leave?: (event: KeyboardEvent) => void;
+    /** Whether the browser's own context menu may open over a panel of the tree. Default `true`. */
+    nativeMenu?: () => boolean;
+}
+export declare const providePopupMenuLevel: (submenu: boolean) => boolean;
+/** Whether the Menu being rendered is a submenu level; `false` for a root or a standalone Menu. */
+export declare const usePopupMenuSubmenu: () => boolean;
+/** Makes `root` the tree that the submenus of every Menu rendered below it join. */
+export declare const providePopupMenuRoot: (root: PopupMenuRoot) => PopupMenuRoot;
+/** The tree a Menu's submenus join, read by MenuFloating; `undefined` outside any tree. */
+export declare const usePopupMenuRoot: () => PopupMenuRoot | undefined;
+/**
+ * Closes a menu tree: the root first, through its own `close(details)`, then every open submenu
+ * below it, deepest first. Each level reports its open change exactly once, with the reason in
+ * `details` (`item-press` for a chosen item).
+ *
+ * The root asks first because it is the level the consumer's `onOpenChange` can cancel: when it
+ * does, the whole tree stays as it was, submenus and focus included. Submenus are still mounted
+ * while the root panel's outro runs, so they close right after it in the same task.
+ *
+ * Focus left inside the tree goes straight to `returnTo`, the element the root hands focus back
+ * to. No row of a closing panel keeps focus through the close transition, and every panel's focus
+ * scope then finds focus already outside and leaves it alone. `rootMenu`, the root's Menu element,
+ * covers a root panel the popover does not own, such as a mobile sheet. Returns `false` when the
+ * consumer's `onOpenChange` cancelled the close and the tree stayed as it was.
+ */
+export declare const closeMenuTree: (root: PopoverState, returnTo: HTMLElement | null, rootMenu?: HTMLElement | null, details?: OpenChangeInit) => boolean;

package/dist/components/PopupMenu/popupMenu.context.js

@@ -6,3 +6,55 @@ import { getContext, setContext } from 'svelte';
 const POPUP_MENU_PANEL_SIZE = Symbol('entasis:popup-menu-panel-size');
 export const providePopupMenuPanelSize = (read) => setContext(POPUP_MENU_PANEL_SIZE, read);
 export const usePopupMenuPanelSize = () => getContext(POPUP_MENU_PANEL_SIZE);
+// A menu and the submenus it opens are one tree, owned by its root: the PopupMenu the consumer
+// rendered, or another host that renders a Menu inline (Tree's context-menu surface). Submenu
+// panels are portaled out of the root panel, so a press inside one never reaches the root's own
+// click listener; each submenu reports item presses to the root instead, and the root closes every
+// level at once. MenuFloating hands the root to the submenus it renders through `submenuOf`, so a
+// PopupMenu the consumer nests in a header, a footer or a trigger stays a root of its own.
+const POPUP_MENU_ROOT = Symbol('entasis:popup-menu-root');
+// Whether the Menu rendering below is a submenu level (a PopupMenu that joined its parent's tree)
+// rather than a root menu. Set by every PopupMenu for the Menu it renders, read by MenuFloating
+// to decide whether ArrowLeft leaves a level and whether the row set has a back control.
+const POPUP_MENU_LEVEL = Symbol('entasis:popup-menu-level');
+export const providePopupMenuLevel = (submenu) => setContext(POPUP_MENU_LEVEL, submenu);
+/** Whether the Menu being rendered is a submenu level; `false` for a root or a standalone Menu. */
+export const usePopupMenuSubmenu = () => getContext(POPUP_MENU_LEVEL) ?? false;
+/** Makes `root` the tree that the submenus of every Menu rendered below it join. */
+export const providePopupMenuRoot = (root) => setContext(POPUP_MENU_ROOT, root);
+/** The tree a Menu's submenus join, read by MenuFloating; `undefined` outside any tree. */
+export const usePopupMenuRoot = () => getContext(POPUP_MENU_ROOT);
+const containsInTree = (popover, node) => !!popover.dialogElement?.contains(node) ||
+    popover.children.some((child) => containsInTree(child, node));
+/**
+ * Closes a menu tree: the root first, through its own `close(details)`, then every open submenu
+ * below it, deepest first. Each level reports its open change exactly once, with the reason in
+ * `details` (`item-press` for a chosen item).
+ *
+ * The root asks first because it is the level the consumer's `onOpenChange` can cancel: when it
+ * does, the whole tree stays as it was, submenus and focus included. Submenus are still mounted
+ * while the root panel's outro runs, so they close right after it in the same task.
+ *
+ * Focus left inside the tree goes straight to `returnTo`, the element the root hands focus back
+ * to. No row of a closing panel keeps focus through the close transition, and every panel's focus
+ * scope then finds focus already outside and leaves it alone. `rootMenu`, the root's Menu element,
+ * covers a root panel the popover does not own, such as a mobile sheet. Returns `false` when the
+ * consumer's `onOpenChange` cancelled the close and the tree stayed as it was.
+ */
+export const closeMenuTree = (root, returnTo, rootMenu, details) => {
+    const active = document.activeElement;
+    const focusInTree = !!active && (!!rootMenu?.contains(active) || containsInTree(root, active));
+    if (root.isOpen && root.close(details) === false)
+        return false;
+    const closeBelow = (popover) => {
+        for (const child of popover.children) {
+            closeBelow(child);
+            if (child.isOpen)
+                child.close(details);
+        }
+    };
+    closeBelow(root);
+    if (focusInTree && returnTo?.isConnected)
+        returnTo.focus({ preventScroll: true });
+    return true;
+};

package/dist/components/PopupMenu/popupMenu.mcp.d.ts

@@ -1 +1 @@
-export declare const popupMenuDescription = "\n# PopupMenu Component\n\nThe PopupMenu component is a wrapper around Popover that renders a Menu inside. It provides all Popover functionality (positioning, transitions, triggers) with integrated Menu rendering for quick menu implementations.\n\n## Basic Usage\n\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\timport { PopupMenu } from 'entasis/popup-menu';\n\timport { userIcon } from 'entasis/icons/user';\n\timport { gearIcon } from 'entasis/icons/gear';\n\timport { signOutIcon } from 'entasis/icons/signOut';\n\t\n\tconst menuItems = [\n\t\t{ type: 'option', prefix: userIcon, title: 'Profile' },\n\t\t{ type: 'option', prefix: gearIcon, title: 'Settings' },\n\t\t{ type: 'separator' },\n\t\t{ type: 'option', prefix: signOutIcon, title: 'Logout', color: 'danger' }\n\t] satisfies MenuItem[];\n</script>\n\n<PopupMenu\n\ttrigger={{ content: 'Open Menu' }}\n\tposition=\"bottom-start\"\n\tmenu={{ items: menuItems }}\n/>\n```\n\n## Props\n\n### Menu Props\n- **menu**: MenuProps (required)\n  - items: MenuItem[] - Array of menu items (buttons, options, separators)\n  - class: string - Custom class for the menu container\n  - theme: MenuThemeProps - Theme overrides for menu and its items\n  - submenuMode: 'auto' | 'popover' | 'stack' - defaults to auto; mobileSheet menus stack submenus automatically\n\n- **closeOnItemClick**: boolean (default: true)\n  - Whether to close the menu when a menu item (button or link) is clicked\n  - Set to false for menus that should stay open for multiple selections\n\n### Popover Props (All Available)\n\n#### Positioning & Layout\n- **position**: ResponsiveProps<Placement> - Popover position relative to trigger\n  - Values: 'top', 'bottom', 'left', 'right', 'top-start', 'bottom-start', etc.\n  \n- **offset**: number - Distance from trigger in pixels\n\n- **size**: ResponsiveProps<'small' | 'normal' | 'large'> - Popover size\n\n- **fitTrigger**: boolean - Make popover width match trigger width\n\n#### Trigger Configuration\n- **trigger**: Snippet | ButtonProps | false\n  - Snippet: Custom trigger rendering with popover state\n  - ButtonProps: Render a button with these props\n  - false: No trigger (control externally via open)\n\n#### Interaction Behavior\n- **open**: boolean (bindable) - Control open state externally\n\n- **openOnClick**: boolean (default: true) - Open on trigger click\n\n- **openOnHover**: boolean (default: false) - Open on trigger hover\n\n- **delay**: number (default: 100) - Delay before opening on hover (ms)\n\n- **closeOnClickOutside**: boolean (default: true) - Close when clicking outside\n\n- **closeOnEscape**: boolean (default: true) - Close on Escape key\n\n- **closeOnMouseLeave**: boolean (default: false) - Close when the pointer leaves the hover safe area. The safe area is the trigger, the panel, and a prediction cone toward the submenu, so a diagonal move into the submenu keeps it open while sibling rows stay hoverable.\n\n- **debugSafeArea**: boolean (default: false) - Show hover safe-area overlays. Trigger/panel rectangles render in blue; the prediction cone toward the submenu renders in orange.\n\n#### Visual & Animation\n- **transition**: ResponsiveProps<FSOProps> - Custom transition configuration\n\n- **directedTransition**: boolean (default: true) - Transition direction based on position\n\n- **lockScroll**: boolean (default: true) - Lock body scroll when open\n\n- **class**: string - Custom class for popover dialog\n\n- **mobileSheet**: boolean (default: false) - Render as a bottom sheet on mobile viewports. With menu.submenuMode='auto', nested submenus become stacked views.\n\n#### Advanced\n- **id**: string - Custom ID for popover element\n\n- **ref**: HTMLElement | null - External reference element (instead of trigger)\n\n- **onOpenChange**: (open: boolean) => void - Called for component-owned state changes\n\n- **onAfterOpen**: (popover: PopoverState) => void - Called after the popover opens\n\n- **onAfterClose**: (popover: PopoverState) => void - Called after the popover closes\n\n- **theme**: PopoverThemeProps - Theme overrides for popover\n\n## Structure\n\nPopupMenu renders as:\n```\n<Popover {...popoverProps}>\n  <Menu {...menuProps} />\n</Popover>\n```\n\nThe Menu inherits the Popover's dialog styling (background, border, shadow, etc.)\n\n## Examples\n\n### Basic Dropdown Menu\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\tconst items = [\n\t\t{ type: 'option', title: 'New File' },\n\t\t{ type: 'option', title: 'Open...' },\n\t\t{ type: 'option', title: 'Save' },\n\t\t{ type: 'separator' },\n\t\t{ type: 'option', title: 'Exit' }\n\t] satisfies MenuItem[];\n</script>\n\n<PopupMenu\n\ttrigger={{ content: 'File', variant: 'ghost' }}\n\tposition=\"bottom-start\"\n\tmenu={{ items }}\n/>\n```\n\n### User Profile Menu\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\timport { userIcon } from 'entasis/icons/user';\n\timport { gearIcon } from 'entasis/icons/gear';\n\timport { questionIcon } from 'entasis/icons/question';\n\timport { signOutIcon } from 'entasis/icons/signOut';\n\t\n\tconst items = [\n\t\t{ type: 'option', prefix: userIcon, title: 'Profile', href: '/profile' },\n\t\t{ type: 'option', prefix: gearIcon, title: 'Settings', href: '/settings' },\n\t\t{ type: 'option', prefix: questionIcon, title: 'Help' },\n\t\t{ type: 'separator' },\n\t\t{ type: 'option', prefix: signOutIcon, title: 'Log Out', color: 'danger' }\n\t] satisfies MenuItem[];\n</script>\n\n<PopupMenu\n\ttrigger={{ content: 'John Doe', variant: 'outline' }}\n\tposition=\"bottom-end\"\n\tmenu={{ items }}\n/>\n```\n\n### Context Menu (Right Click)\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\timport { trashIcon } from 'entasis/icons/trash';\n\timport { copyIcon } from 'entasis/icons/copy';\n\timport { shareIcon } from 'entasis/icons/share';\n\t\n\tlet open = $state(false);\n\tlet contextMenuRef = $state<HTMLElement | null>(null);\n\t\n\tfunction handleContextMenu(e: MouseEvent) {\n\t\te.preventDefault();\n\t\tcontextMenuRef = e.currentTarget as HTMLElement;\n\t\topen = true;\n\t}\n\t\n\tconst items = [\n\t\t{ type: 'option', title: 'Open' },\n\t\t{ type: 'option', prefix: copyIcon, title: 'Copy' },\n\t\t{ type: 'option', prefix: shareIcon, title: 'Share' },\n\t\t{ type: 'separator' },\n\t\t{ type: 'option', prefix: trashIcon, title: 'Delete', color: 'danger' }\n\t] satisfies MenuItem[];\n</script>\n\n<div oncontextmenu={handleContextMenu}>\n\tRight-click me\n</div>\n\n<PopupMenu\n\ttrigger={false}\n\tbind:open\n\tref={contextMenuRef}\n\tposition=\"bottom-start\"\n\tmenu={{ items }}\n/>\n```\n\n### With Custom Trigger Snippet\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\tlet open = $state(false);\n\n\tconst items = [\n\t\t{ type: 'option', title: 'Option 1' },\n\t\t{ type: 'option', title: 'Option 2' }\n\t] satisfies MenuItem[];\n</script>\n\n<PopupMenu bind:open position=\"bottom\" menu={{ items }}>\n\t{#snippet trigger(popover)}\n\t\t<button onclick={() => popover.toggle()}>\n\t\t\tCustom Trigger {open ? '\u25B2' : '\u25BC'}\n\t\t</button>\n\t{/snippet}\n</PopupMenu>\n```\n\n### Hover Menu\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\tconst items = [\n\t\t{ type: 'option', title: 'Quick Action 1' },\n\t\t{ type: 'option', title: 'Quick Action 2' }\n\t] satisfies MenuItem[];\n</script>\n\n<PopupMenu\n\ttrigger={{ content: 'Hover Me', variant: 'ghost' }}\n\topenOnHover={true}\n\topenOnClick={false}\n\tdelay={200}\n\tcloseOnMouseLeave={true}\n\tmenu={{ items }}\n/>\n```\n\n### Actions Menu with Buttons\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\tconst items = [\n\t\t{ type: 'button', children: 'Save Draft', variant: 'ghost', fullWidth: true },\n\t\t{ type: 'button', children: 'Publish', variant: 'solid', color: 'primary', fullWidth: true },\n\t\t{ type: 'separator' },\n\t\t{ type: 'button', children: 'Delete', variant: 'soft', color: 'danger', fullWidth: true }\n\t] satisfies MenuItem[];\n</script>\n\n<PopupMenu\n\ttrigger={{ content: 'Actions' }}\n\tposition=\"bottom-end\"\n\tmenu={{ items }}\n/>\n```\n\n### External Control with Bindable State\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\tlet menuOpen = $state(false);\n\t\n\tconst items = [\n\t\t{ type: 'option', title: 'Item 1' },\n\t\t{ type: 'option', title: 'Item 2' }\n\t] satisfies MenuItem[];\n\t\n\tfunction openMenu() {\n\t\tmenuOpen = true;\n\t}\n</script>\n\n<button onclick={openMenu}>Open Menu Externally</button>\n\n<PopupMenu\n\ttrigger={{ content: 'Menu' }}\n\tbind:open={menuOpen}\n\tmenu={{ items }}\n/>\n```\n\n### Positioned Menu\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\tconst items = [\n\t\t{ type: 'option', title: 'Top Start' },\n\t\t{ type: 'option', title: 'Example' }\n\t] satisfies MenuItem[];\n</script>\n\n<div class=\"flex gap-2\">\n\t<PopupMenu trigger={{ content: 'Top Start' }} position=\"top-start\" menu={{ items }} />\n\t<PopupMenu trigger={{ content: 'Bottom' }} position=\"bottom\" menu={{ items }} />\n\t<PopupMenu trigger={{ content: 'Right' }} position=\"right\" menu={{ items }} />\n</div>\n```\n\n### With Custom Theme\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\tconst items = [\n\t\t{ type: 'option', title: 'Themed Option 1' },\n\t\t{ type: 'option', title: 'Themed Option 2' }\n\t] satisfies MenuItem[];\n\t\n\tconst menuTheme = {\n\t\troot: { base: 'gap-3' },\n\t\toption: {\n\t\t\troot: { base: 'px-4 py-3' }\n\t\t}\n\t};\n</script>\n\n<PopupMenu\n\ttrigger={{ content: 'Themed Menu' }}\n\tmenu={{ items, theme: menuTheme }}\n/>\n```\n\n### Keep Menu Open for Multiple Interactions\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\tlet selections = $state<string[]>([]);\n\t\n\tconst items = [\n\t\t{ \n\t\t\ttype: 'option', \n\t\t\ttitle: 'Option 1',\n\t\t\tonclick: () => selections.push('Option 1')\n\t\t},\n\t\t{ \n\t\t\ttype: 'option', \n\t\t\ttitle: 'Option 2',\n\t\t\tonclick: () => selections.push('Option 2')\n\t\t},\n\t\t{ type: 'separator' },\n\t\t{ \n\t\t\ttype: 'button', \n\t\t\tchildren: 'Done',\n\t\t\tvariant: 'solid',\n\t\t\tfullWidth: true\n\t\t}\n\t] satisfies MenuItem[];\n</script>\n\n<PopupMenu\n\ttrigger={{ content: 'Select Multiple' }}\n\tcloseOnItemClick={false}\n\tmenu={{ items }}\n/>\n```\n\n### Nested Submenus\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\n\tconst items = [\n\t\t{ type: 'option', title: 'New File' },\n\t\t{\n\t\t\ttype: 'submenu',\n\t\t\ttitle: 'More Options',\n\t\t\tmenu: [\n\t\t\t\t{ type: 'option', title: 'Sub Option 1' },\n\t\t\t\t{ type: 'option', title: 'Sub Option 2' }\n\t\t\t]\n\t\t}\n\t] satisfies MenuItem[];\n</script>\n\n<PopupMenu trigger={{ content: 'Main Menu' }} position=\"bottom-start\" menu={{ items }} />\n```\n\n## Accessibility\n\n- Inherits all Popover accessibility features: the trigger carries `aria-haspopup=\"menu\"`, `aria-expanded`, and `aria-controls`, and focus returns to it on close\n- Menu items have appropriate roles (`menuitem`, or `menuitemradio` with `aria-checked` for options that set `selected`) and keyboard navigation\n- Type-ahead: typing letters moves the highlight to the next matching item\n- Escape closes only the topmost open layer, so a submenu closes before its parent (configurable)\n- An outside press closes every layer above the one pressed (configurable)\n\n## Notes\n\n- PopupMenu is a lightweight wrapper - all Popover props work as expected\n- Menu styling inherits from Popover's dialog theme\n- Use `closeOnClickOutside={true}` (default) for typical dropdown menus\n- Use `closeOnMouseLeave={true}` for hover-triggered quick menus; a prediction cone toward the submenu keeps it open during the diagonal move while sibling rows stay hoverable.\n- The `menu` prop accepts full MenuProps including theme forwarding to child components\n";
+export declare const popupMenuDescription = "\n# PopupMenu Component\n\nThe PopupMenu component is a wrapper around Popover that renders a Menu inside. It provides all Popover functionality (positioning, transitions, triggers) with integrated Menu rendering for quick menu implementations.\n\n## Basic Usage\n\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\timport { PopupMenu } from 'entasis/popup-menu';\n\timport { userIcon } from 'entasis/icons/user';\n\timport { gearIcon } from 'entasis/icons/gear';\n\timport { signOutIcon } from 'entasis/icons/signOut';\n\t\n\tconst menuItems = [\n\t\t{ type: 'option', prefix: userIcon, title: 'Profile' },\n\t\t{ type: 'option', prefix: gearIcon, title: 'Settings' },\n\t\t{ type: 'separator' },\n\t\t{ type: 'option', prefix: signOutIcon, title: 'Logout', color: 'danger' }\n\t] satisfies MenuItem[];\n</script>\n\n<PopupMenu\n\ttrigger={{ content: 'Open Menu' }}\n\tposition=\"bottom-start\"\n\tmenu={{ items: menuItems }}\n/>\n```\n\n## Props\n\n### Menu Props\n- **menu**: MenuProps (required)\n  - items: MenuItem[] - Array of menu items (buttons, options, separators, submenus, checkbox items, radio groups, groups)\n  - filter / search / defaultSearch / onSearchChange / onHighlightChange / empty: a search field above the rows (see the Menu docs)\n  - focusOnMount: boolean | 'container' | 'last' - leave it out and the menu decides from how it opened (see Accessibility)\n  - class: string - Custom class for the menu container\n  - theme: MenuThemeProps - Theme overrides for menu and its items\n  - submenuMode: 'auto' | 'popover' | 'stack' - defaults to auto; mobileSheet menus stack submenus automatically\n\n- **closeOnItemClick**: boolean (default: true)\n  - Whether to close the menu when a menu item (button or link) is clicked\n  - Choosing an item inside a submenu closes every open submenu and the menu together, once each; a floating menu then returns focus to its trigger (a mobile sheet hands focus back through its Dialog)\n  - Submenus follow this setting; an item (or an ancestor) with data-menu-keep-open=\"true\" never closes the menu\n  - A PopupMenu placed in another menu's header, footer or trigger is a menu of its own: it keeps its own closeOnItemClick and closes only itself\n  - Set to false for menus that should stay open for multiple selections\n\n### Popover Props (All Available)\n\n#### Positioning & Layout\n- **position**: ResponsiveProps<Placement> - Popover position relative to trigger\n  - Values: 'top', 'bottom', 'left', 'right', 'top-start', 'bottom-start', etc.\n  \n- **offset**: number - Distance from trigger in pixels\n\n- **size**: ResponsiveProps<'small' | 'normal' | 'large'> - Popover size\n\n- **fitTrigger**: boolean - Make popover width match trigger width\n\n#### Trigger Configuration\n- **trigger**: Snippet | ButtonProps | false\n  - Snippet: Custom trigger rendering with popover state\n  - ButtonProps: Render a button with these props\n  - false: No trigger (control externally via open)\n\n#### Interaction Behavior\n- **open**: boolean (bindable) - Control open state externally\n\n- **openOnClick**: boolean (default: true) - Open on trigger click\n\n- **openOnHover**: boolean (default: false) - Open on trigger hover. Touch taps and disabled triggers never hover-open it, and a submenu row that lands under a resting pointer (a menu reopened from the keyboard) opens only once the pointer moves\n\n- **delay**: number (default: 100) - Delay before opening on hover (ms)\n\n- **closeOnClickOutside**: boolean (default: true) - Close when clicking outside\n\n- **closeOnEscape**: boolean (default: true) - Close on Escape key\n\n- **closeOnMouseLeave**: boolean (default: false) - Close when the pointer leaves the hover safe area. The safe area is the trigger, the panel, and a prediction cone toward the submenu, so a diagonal move into the submenu keeps it open while sibling rows stay hoverable.\n- **closeDelay**: number (default: 120) - Milliseconds the pointer may spend outside the hover safe area before `closeOnMouseLeave` closes the menu\n\n- **debugSafeArea**: boolean (default: false) - Show hover safe-area overlays. Trigger/panel rectangles render in blue; the prediction cone toward the submenu renders in orange.\n\n#### Visual & Animation\n- **transition**: ResponsiveProps<FSOProps> - Custom transition configuration\n\n- **directedTransition**: boolean (default: true) - Transition direction based on position\n\n- **lockScroll**: boolean (default: true) - Lock body scroll when open\n\n- **class**: string - Custom class for popover dialog\n\n- **mobileSheet**: boolean (default: false) - Render as a bottom sheet on mobile viewports. With menu.submenuMode='auto', nested submenus become stacked views.\n\n#### Advanced\n- **id**: string - Custom ID for popover element\n\n- **ref**: HTMLElement | null - External reference element (instead of trigger)\n\n- **onOpenChange**: (open: boolean, details: OpenChangeDetails) => void - Called before component-owned state changes, with `details.reason` (`'trigger-press'`, `'trigger-hover'`, `'item-press'` when a chosen item closes the menu, `'escape-key'`, `'outside-press'`\u2026), `details.event` and `details.cancel()`, which keeps the menu as it is (cancelling an `'item-press'` close also keeps its open submenus and focus where they were)\n\n- **onAfterOpen**: (popover: PopoverApi) => void - Called after the popover opens\n\n- **onAfterClose**: (popover: PopoverApi) => void - Called after the popover closes\n\n- **theme**: PopoverThemeProps - Theme overrides for popover\n\n## Structure\n\nPopupMenu renders as:\n```\n<Popover {...popoverProps}>\n  <Menu {...menuProps} />\n</Popover>\n```\n\nThe Menu inherits the Popover's dialog styling (background, border, shadow, etc.)\n\n## Examples\n\n### Basic Dropdown Menu\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\tconst items = [\n\t\t{ type: 'option', title: 'New File' },\n\t\t{ type: 'option', title: 'Open...' },\n\t\t{ type: 'option', title: 'Save' },\n\t\t{ type: 'separator' },\n\t\t{ type: 'option', title: 'Exit' }\n\t] satisfies MenuItem[];\n</script>\n\n<PopupMenu\n\ttrigger={{ content: 'File', variant: 'ghost' }}\n\tposition=\"bottom-start\"\n\tmenu={{ items }}\n/>\n```\n\n### User Profile Menu\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\timport { userIcon } from 'entasis/icons/user';\n\timport { gearIcon } from 'entasis/icons/gear';\n\timport { questionIcon } from 'entasis/icons/question';\n\timport { signOutIcon } from 'entasis/icons/signOut';\n\t\n\tconst items = [\n\t\t{ type: 'option', prefix: userIcon, title: 'Profile', href: '/profile' },\n\t\t{ type: 'option', prefix: gearIcon, title: 'Settings', href: '/settings' },\n\t\t{ type: 'option', prefix: questionIcon, title: 'Help' },\n\t\t{ type: 'separator' },\n\t\t{ type: 'option', prefix: signOutIcon, title: 'Log Out', color: 'danger' }\n\t] satisfies MenuItem[];\n</script>\n\n<PopupMenu\n\ttrigger={{ content: 'John Doe', variant: 'outline' }}\n\tposition=\"bottom-end\"\n\tmenu={{ items }}\n/>\n```\n\n### Context Menu (Right Click)\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\timport { trashIcon } from 'entasis/icons/trash';\n\timport { copyIcon } from 'entasis/icons/copy';\n\timport { shareIcon } from 'entasis/icons/share';\n\t\n\tlet open = $state(false);\n\tlet contextMenuRef = $state<HTMLElement | null>(null);\n\t\n\tfunction handleContextMenu(e: MouseEvent) {\n\t\te.preventDefault();\n\t\tcontextMenuRef = e.currentTarget as HTMLElement;\n\t\topen = true;\n\t}\n\t\n\tconst items = [\n\t\t{ type: 'option', title: 'Open' },\n\t\t{ type: 'option', prefix: copyIcon, title: 'Copy' },\n\t\t{ type: 'option', prefix: shareIcon, title: 'Share' },\n\t\t{ type: 'separator' },\n\t\t{ type: 'option', prefix: trashIcon, title: 'Delete', color: 'danger' }\n\t] satisfies MenuItem[];\n</script>\n\n<div oncontextmenu={handleContextMenu}>\n\tRight-click me\n</div>\n\n<PopupMenu\n\ttrigger={false}\n\tbind:open\n\tref={contextMenuRef}\n\tposition=\"bottom-start\"\n\tmenu={{ items }}\n/>\n```\n\n### With Custom Trigger Snippet\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\tlet open = $state(false);\n\n\tconst items = [\n\t\t{ type: 'option', title: 'Option 1' },\n\t\t{ type: 'option', title: 'Option 2' }\n\t] satisfies MenuItem[];\n</script>\n\n<PopupMenu bind:open position=\"bottom\" menu={{ items }}>\n\t{#snippet trigger(popover)}\n\t\t<button onclick={() => popover.toggle()}>\n\t\t\tCustom Trigger {open ? '\u25B2' : '\u25BC'}\n\t\t</button>\n\t{/snippet}\n</PopupMenu>\n```\n\n### Hover Menu\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\tconst items = [\n\t\t{ type: 'option', title: 'Quick Action 1' },\n\t\t{ type: 'option', title: 'Quick Action 2' }\n\t] satisfies MenuItem[];\n</script>\n\n<PopupMenu\n\ttrigger={{ content: 'Hover Me', variant: 'ghost' }}\n\topenOnHover={true}\n\topenOnClick={false}\n\tdelay={200}\n\tcloseOnMouseLeave={true}\n\tmenu={{ items }}\n/>\n```\n\n### Actions Menu with Buttons\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\tconst items = [\n\t\t{ type: 'button', children: 'Save Draft', variant: 'ghost', fullWidth: true },\n\t\t{ type: 'button', children: 'Publish', variant: 'solid', color: 'primary', fullWidth: true },\n\t\t{ type: 'separator' },\n\t\t{ type: 'button', children: 'Delete', variant: 'soft', color: 'danger', fullWidth: true }\n\t] satisfies MenuItem[];\n</script>\n\n<PopupMenu\n\ttrigger={{ content: 'Actions' }}\n\tposition=\"bottom-end\"\n\tmenu={{ items }}\n/>\n```\n\n### External Control with Bindable State\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\tlet menuOpen = $state(false);\n\t\n\tconst items = [\n\t\t{ type: 'option', title: 'Item 1' },\n\t\t{ type: 'option', title: 'Item 2' }\n\t] satisfies MenuItem[];\n\t\n\tfunction openMenu() {\n\t\tmenuOpen = true;\n\t}\n</script>\n\n<button onclick={openMenu}>Open Menu Externally</button>\n\n<PopupMenu\n\ttrigger={{ content: 'Menu' }}\n\tbind:open={menuOpen}\n\tmenu={{ items }}\n/>\n```\n\n### Positioned Menu\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\tconst items = [\n\t\t{ type: 'option', title: 'Top Start' },\n\t\t{ type: 'option', title: 'Example' }\n\t] satisfies MenuItem[];\n</script>\n\n<div class=\"flex gap-2\">\n\t<PopupMenu trigger={{ content: 'Top Start' }} position=\"top-start\" menu={{ items }} />\n\t<PopupMenu trigger={{ content: 'Bottom' }} position=\"bottom\" menu={{ items }} />\n\t<PopupMenu trigger={{ content: 'Right' }} position=\"right\" menu={{ items }} />\n</div>\n```\n\n### With Custom Theme\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\tconst items = [\n\t\t{ type: 'option', title: 'Themed Option 1' },\n\t\t{ type: 'option', title: 'Themed Option 2' }\n\t] satisfies MenuItem[];\n\t\n\tconst menuTheme = {\n\t\troot: { base: 'gap-3' },\n\t\toption: {\n\t\t\troot: { base: 'px-4 py-3' }\n\t\t}\n\t};\n</script>\n\n<PopupMenu\n\ttrigger={{ content: 'Themed Menu' }}\n\tmenu={{ items, theme: menuTheme }}\n/>\n```\n\n### Keep Menu Open for Multiple Interactions\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\tlet selections = $state<string[]>([]);\n\t\n\tconst items = [\n\t\t{ \n\t\t\ttype: 'option', \n\t\t\ttitle: 'Option 1',\n\t\t\tonclick: () => selections.push('Option 1')\n\t\t},\n\t\t{ \n\t\t\ttype: 'option', \n\t\t\ttitle: 'Option 2',\n\t\t\tonclick: () => selections.push('Option 2')\n\t\t},\n\t\t{ type: 'separator' },\n\t\t{ \n\t\t\ttype: 'button', \n\t\t\tchildren: 'Done',\n\t\t\tvariant: 'solid',\n\t\t\tfullWidth: true\n\t\t}\n\t] satisfies MenuItem[];\n</script>\n\n<PopupMenu\n\ttrigger={{ content: 'Select Multiple' }}\n\tcloseOnItemClick={false}\n\tmenu={{ items }}\n/>\n```\n\n### Checkbox Items and Radio Groups\nCheckbox and radio rows keep the menu open on their own, so a menu of settings needs no `closeOnItemClick={false}`:\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\n\tconst items = [\n\t\t{ type: 'checkbox', title: 'Show hidden files', defaultValue: false },\n\t\t{\n\t\t\ttype: 'radio-group',\n\t\t\tlabel: 'Sort by',\n\t\t\tdefaultValue: 'name',\n\t\t\titems: [\n\t\t\t\t{ value: 'name', title: 'Name' },\n\t\t\t\t{ value: 'date', title: 'Date modified' }\n\t\t\t]\n\t\t},\n\t\t{ type: 'separator' },\n\t\t{ type: 'option', title: 'Done' }\n\t] satisfies MenuItem[];\n</script>\n\n<PopupMenu trigger={{ content: 'View' }} menu={{ items }} />\n```\n\n### Nested Submenus\n```svelte\n<script lang=\"ts\">\n\timport type { MenuItem } from 'entasis/menu';\n\n\tconst items = [\n\t\t{ type: 'option', title: 'New File' },\n\t\t{\n\t\t\ttype: 'submenu',\n\t\t\ttitle: 'More Options',\n\t\t\tmenu: [\n\t\t\t\t{ type: 'option', title: 'Sub Option 1' },\n\t\t\t\t{ type: 'option', title: 'Sub Option 2' }\n\t\t\t]\n\t\t}\n\t] satisfies MenuItem[];\n</script>\n\n<PopupMenu trigger={{ content: 'Main Menu' }} position=\"bottom-start\" menu={{ items }} />\n```\n\n## Styling hooks\n\nThe popup is a Popover panel: it carries `data-open`, `data-closed`, `data-entering`, `data-exiting`, `data-side` and `data-align`, and the `--available-height`, `--anchor-width` and `--transform-origin` variables (`popoverDataAttributes` and `popoverCssVariables` from `entasis/popover`). The trigger carries `data-popup-open` while the menu is open. Rows and submenu rows carry `data-highlighted`, `data-disabled`, `data-selected` and `data-popup-open` (`menuDataAttributes` from `entasis/menu`).\n\n## Accessibility\n\n- Inherits all Popover accessibility features: the trigger carries `aria-haspopup=\"menu\"`, `aria-expanded`, and `aria-controls`, and focus returns to it on close\n- Menu items have appropriate roles (`menuitem`, `menuitemcheckbox` and `menuitemradio` with `aria-checked`, or `menuitemradio` for options that set `selected`) and keyboard navigation\n- Where focus goes when the menu opens depends on how it opened. Enter, Space or a screen reader's press on the button, and ArrowDown, put focus on the first row; ArrowUp on the last; a mouse or touch press focuses the menu itself with no row highlighted; hovering it open leaves focus where it was. ArrowDown and ArrowUp on the button open the menu (Alt, Ctrl and Meta with them are left to the browser); on an already open menu they move into it\n- Tab closes the whole menu tree and moves on to the control after the trigger, Shift+Tab closes it and stays on the trigger; `onOpenChange` reports `reason: 'focus-out'`. Focus left where Tab put it is not taken back when the close finishes. A field or link in the menu's header or footer keeps Tab until the last one\n- A submenu closes when focus returns to a row of the menu that opened it\n- The panel carries the reading direction of its trigger: in right-to-left text submenus open to the left, carets and back arrows mirror, and ArrowLeft opens a submenu while ArrowRight leaves it\n- Type-ahead: typing letters moves the highlight to the next matching item\n- Escape closes only the topmost open layer, so a submenu closes before its parent (configurable)\n- An outside press closes every layer above the one pressed (configurable)\n- Choosing an item at any depth closes the whole menu tree at once; a floating menu returns focus straight to the trigger, without stopping on a submenu row\n\n## Notes\n\n- PopupMenu is a lightweight wrapper - all Popover props work as expected\n- Menu styling inherits from Popover's dialog theme\n- Use `closeOnClickOutside={true}` (default) for typical dropdown menus\n- Use `closeOnMouseLeave={true}` for hover-triggered quick menus; a prediction cone toward the submenu keeps it open during the diagonal move while sibling rows stay hoverable.\n- The `menu` prop accepts full MenuProps including theme forwarding to child components\n";