@trackunit/react-components 2.5.4 → 2.6.2-alpha-770d9994af7.0

package/migrations/v3-0-0/menulist-rename-to-menucontent.js

@@ -0,0 +1,105 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.menuListRenameToMenuContent = void 0;
+const tslib_1 = require("tslib");
+const ts = tslib_1.__importStar(require("typescript"));
+const jsx_utils_1 = require("../utils/jsx-utils");
+const PACKAGE_NAME = "@trackunit/react-components";
+const RENAMES = [
+    { from: "MenuList", to: "MenuContent" },
+    { from: "MenuListProps", to: "MenuContentProps" },
+];
+/**
+ * Every `Identifier` node in the file matching `name`. Safe to use as a
+ * blanket rename once we've confirmed (via `getImportedAliases`) that `name`
+ * is genuinely imported from the target package with no local alias — in
+ * that case the import specifier, JSX tag references, and type references
+ * all share the same identifier text, so one pass covers every site.
+ */
+const collectIdentifierEdits = (sourceFile, name, replacement) => {
+    const edits = [];
+    const visit = (node) => {
+        if (ts.isIdentifier(node) && node.text === name) {
+            edits.push({ start: node.getStart(sourceFile), end: node.getEnd(), text: replacement });
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return edits;
+};
+/**
+ * Locates the `propertyName` of an aliased named import specifier
+ * (`{ MenuList as Foo }`) for `importedName`. Only that part needs
+ * rewriting — the local binding `Foo` (and therefore every usage site in
+ * the file) stays exactly as the author wrote it.
+ */
+const findAliasedImportSpecifierEdit = (sourceFile, packageName, importedName, replacement) => {
+    for (const stmt of sourceFile.statements) {
+        if (!ts.isImportDeclaration(stmt))
+            continue;
+        const moduleSpecifier = stmt.moduleSpecifier;
+        if (!ts.isStringLiteral(moduleSpecifier) || moduleSpecifier.text !== packageName)
+            continue;
+        const namedBindings = stmt.importClause?.namedBindings;
+        if (namedBindings === undefined || !ts.isNamedImports(namedBindings))
+            continue;
+        for (const element of namedBindings.elements) {
+            if (element.propertyName === undefined)
+                continue;
+            if (element.propertyName.text !== importedName)
+                continue;
+            return {
+                start: element.propertyName.getStart(sourceFile),
+                end: element.propertyName.getEnd(),
+                text: replacement,
+            };
+        }
+    }
+    return null;
+};
+const transformMenuListUsage = (filePath, content) => {
+    const sourceFile = (0, jsx_utils_1.parseTsx)(content, filePath);
+    const aliases = (0, jsx_utils_1.getImportedAliases)(sourceFile, PACKAGE_NAME);
+    if (aliases === null)
+        return null;
+    const edits = [];
+    for (const { from, to } of RENAMES) {
+        const localAlias = Object.entries(aliases).find(([, original]) => original === from)?.[0];
+        if (localAlias === undefined)
+            continue;
+        if (localAlias === from) {
+            edits.push(...collectIdentifierEdits(sourceFile, from, to));
+        }
+        else {
+            const edit = findAliasedImportSpecifierEdit(sourceFile, PACKAGE_NAME, from, to);
+            if (edit !== null)
+                edits.push(edit);
+        }
+    }
+    if (edits.length === 0)
+        return null;
+    edits.sort((a, b) => b.start - a.start);
+    let updated = content;
+    for (const { start, end, text } of edits) {
+        updated = updated.slice(0, start) + text + updated.slice(end);
+    }
+    return updated;
+};
+/**
+ * Renames `MenuList`/`MenuListProps` to `MenuContent`/`MenuContentProps`
+ * everywhere they're imported from `@trackunit/react-components` — the
+ * import specifier, every JSX tag usage, and every type reference (e.g.
+ * `Omit<MenuListProps, "children">`).
+ *
+ * Aliased imports (`{ MenuList as Foo }`) only need the imported name
+ * rewritten; the local alias and its usage sites are left untouched.
+ * Unrelated same-prefix exports like `cvaMenuList`/`cvaMenuListItem` are
+ * never matched since identifier comparisons are exact, not substring.
+ */
+const menuListRenameToMenuContent = (tree) => {
+    const touched = (0, jsx_utils_1.visitTsxFiles)(tree, "MenuList", transformMenuListUsage);
+    (0, jsx_utils_1.logSummary)("menulist-rename-to-menucontent", touched);
+};
+exports.menuListRenameToMenuContent = menuListRenameToMenuContent;
+exports.default = exports.menuListRenameToMenuContent;
+//# sourceMappingURL=menulist-rename-to-menucontent.js.map

package/migrations.json

@@ -39,6 +39,11 @@
       "version": "2.0.0",
       "description": "Remove the no-longer-supported style property from inline ToggleGroup list items.",
       "implementation": "./migrations/v2-0-0/togglegroup-remove-item-style"
+    },
+    "v3-0-0-menulist-rename-to-menucontent": {
+      "version": "3.0.0",
+      "description": "Rename MenuList/MenuListProps to MenuContent/MenuContentProps (import specifiers, JSX tags, and type references).",
+      "implementation": "./migrations/v3-0-0/menulist-rename-to-menucontent"
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trackunit/react-components",
-  "version": "2.5.4",
+  "version": "2.6.2-alpha-770d9994af7.0",
   "repository": "https://github.com/Trackunit/manager",
   "license": "SEE LICENSE IN LICENSE.txt",
   "migrations": "./migrations.json",
@@ -14,17 +14,17 @@
     "@floating-ui/react": "^0.26.25",
     "string-ts": "^2.0.0",
     "tailwind-merge": "^2.0.0",
-    "@trackunit/ui-design-tokens": "1.14.1",
-    "@trackunit/css-class-variance-utilities": "1.14.1",
-    "@trackunit/shared-utils": "1.16.1",
-    "@trackunit/ui-icons": "1.14.1",
+    "@trackunit/ui-design-tokens": "1.14.3-alpha-770d9994af7.0",
+    "@trackunit/css-class-variance-utilities": "1.14.3-alpha-770d9994af7.0",
+    "@trackunit/shared-utils": "1.16.3-alpha-770d9994af7.0",
+    "@trackunit/ui-icons": "1.14.3-alpha-770d9994af7.0",
     "es-toolkit": "^1.39.10",
     "@tanstack/react-virtual": "^3.14.3",
     "dequal": "^2.0.3",
     "fflate": "^0.8.2",
     "superjson": "^2.2.6",
     "zod": "^3.25.76",
-    "@trackunit/i18n-library-translation": "2.3.1"
+    "@trackunit/i18n-library-translation": "2.3.4-alpha-770d9994af7.0"
   },
   "peerDependencies": {
     "react": "^19.0.0",

package/src/components/Menu/MenuContent/MenuContent.d.ts

@@ -0,0 +1,96 @@
+import { MouseEventHandler, ReactElement, ReactNode } from "react";
+import { CommonProps } from "../../../common/CommonProps";
+import { Refable } from "../../../common/Refable";
+import type { Styleable } from "../../../common/Styleable";
+export interface MenuContentProps extends CommonProps, Styleable, Refable<HTMLDivElement> {
+    /**
+     * List of menu items to be rendered.
+     */
+    children: ReactNode;
+    /**
+     * Optional class names for the inner scrollable list container (`cvaMenuList`).
+     * Use this when the outer menu shell and inner list need different layout constraints
+     * (for example, filter submenus with a sticky header/body/footer grid).
+     */
+    listClassName?: string;
+    /** Click handler - typically used to trigger close action. when propagation is NOT prevented on menuItem */
+    onClick?: MouseEventHandler<HTMLDivElement>;
+    /**
+     * Enable multi-selection in the menu content.
+     *
+     * @default false
+     */
+    isMulti?: boolean;
+    /**
+     * Array of IDs representing the currently selected items.
+     */
+    selectedItems?: Array<string>;
+    /**
+     * Callback triggered when selected items change.
+     */
+    onSelectionChange?: (selected: Array<string>) => void;
+}
+/**
+ * MenuContent (formerly MenuList) is a popover menu that appears above all other content on the page. It offers a
+ * list of actions or functions that a user can access by clicking on a trigger, with full keyboard support:
+ * roving-tabindex Up/Down navigation (wrapping), Home/End, typeahead, and — via `MenuItem`'s `submenu` prop —
+ * nested submenu entry/exit.
+ *
+ * Typically rendered inside a `Popover` (directly, or as `PopoverContent`'s children), in which case it reads
+ * the popover's floating context to power its keyboard navigation. Also works standalone (e.g. inside a
+ * `Collapse`, with no ambient `Popover`), falling back to its own local, always-open floating context.
+ *
+ * **When to use**
+ * - Use the MenuContent if you have limited space and need to display overflow actions in a list.
+ * - Use the MenuContent for actions that are not essential to completing workflows.
+ * - Don't use the MenuContent to display single or multi-select items within form components. For dropdowns within select components, use SelectDropdown (component not available yet).
+ *
+ * @example MenuContent with action items
+ * ```tsx
+ * import { MenuContent, MenuItem, MoreMenu, Icon } from "@trackunit/react-components";
+ *
+ * const ActionsMenu = () => (
+ *   <MoreMenu>
+ *     {(close) => (
+ *       <MenuContent onClick={close}>
+ *         <MenuItem id="edit" prefix={<Icon name="PencilSquare" size="small" />}>
+ *           Edit
+ *         </MenuItem>
+ *         <MenuItem id="duplicate" prefix={<Icon name="DocumentDuplicate" size="small" />}>
+ *           Duplicate
+ *         </MenuItem>
+ *         <MenuItem id="delete" prefix={<Icon name="Trash" size="small" />} destructive>
+ *           Delete
+ *         </MenuItem>
+ *       </MenuContent>
+ *     )}
+ *   </MoreMenu>
+ * );
+ * ```
+ * @example Multi-select MenuContent
+ * ```tsx
+ * import { MenuContent, MenuItem, MoreMenu } from "@trackunit/react-components";
+ * import { useState } from "react";
+ *
+ * const FilterMenu = () => {
+ *   const [selected, setSelected] = useState<string[]>(["active"]);
+ *
+ *   return (
+ *     <MoreMenu label="Filter by status">
+ *       <MenuContent
+ *         isMulti
+ *         selectedItems={selected}
+ *         onSelectionChange={setSelected}
+ *       >
+ *         <MenuItem id="active">Active</MenuItem>
+ *         <MenuItem id="idle">Idle</MenuItem>
+ *         <MenuItem id="offline">Offline</MenuItem>
+ *       </MenuContent>
+ *     </MoreMenu>
+ *   );
+ * };
+ * ```
+ * @param {MenuContentProps} props - The props for the MenuContent component
+ * @returns {ReactElement} MenuContent component
+ */
+export declare const MenuContent: ({ "data-testid": dataTestId, className, listClassName, children, isMulti, selectedItems: controlledSelectedItems, onSelectionChange, style, ref, ...args }: MenuContentProps) => ReactElement;

package/src/components/Menu/MenuDivider/MenuDivider.d.ts

@@ -4,25 +4,25 @@ import { Refable } from "../../../common/Refable";
 import type { Styleable } from "../../../common/Styleable";
 export type MenuDividerProps = CommonProps & Styleable & Refable<HTMLDivElement>;
 /**
- * MenuDivider renders a horizontal line to visually separate groups of items within a MenuList.
+ * MenuDivider renders a horizontal line to visually separate groups of items within a MenuContent.
  *
  * ### When to use
  * Use MenuDivider between groups of related `MenuItem` elements to create logical sections within a menu.
  *
  * ### When not to use
- * Do not use MenuDivider outside of a `MenuList`. For general-purpose dividers, use `Spacer` with `border`.
+ * Do not use MenuDivider outside of a `MenuContent`. For general-purpose dividers, use `Spacer` with `border`.
  *
  * @example Menu with grouped sections
  * ```tsx
- * import { MenuList, MenuItem, MenuDivider, Icon } from "@trackunit/react-components";
+ * import { MenuContent, MenuItem, MenuDivider, Icon } from "@trackunit/react-components";
  *
  * const GroupedMenu = () => (
- *   <MenuList>
+ *   <MenuContent>
  *     <MenuItem id="edit" label="Edit" prefix={<Icon name="PencilSquare" size="small" />} />
  *     <MenuItem id="duplicate" label="Duplicate" prefix={<Icon name="DocumentDuplicate" size="small" />} />
  *     <MenuDivider />
  *     <MenuItem id="delete" label="Delete" variant="danger" prefix={<Icon name="Trash" size="small" />} />
- *   </MenuList>
+ *   </MenuContent>
  * );
  * ```
  * @returns {ReactElement} MenuDivider component

package/src/components/Menu/MenuItem/MenuItem.d.ts

@@ -1,8 +1,9 @@
 import { VariantProps } from "@trackunit/css-class-variance-utilities";
-import { MouseEventHandler, ReactElement, ReactNode } from "react";
+import { FocusEventHandler, MouseEventHandler, PointerEventHandler, ReactElement, ReactNode } from "react";
 import { CommonProps } from "../../../common/CommonProps";
-import type { Styleable } from "../../../common/Styleable";
 import { Refable } from "../../../common/Refable";
+import type { Styleable } from "../../../common/Styleable";
+import { PopoverSizing } from "../../Popover/PopoverTypes";
 import { cvaMenuItemStyle } from "./MenuItem.variants";
 export type MenuItemVariant = "primary" | "danger";
 export interface MenuItemProps extends CommonProps, Styleable, Refable<HTMLDivElement> {
@@ -85,23 +86,51 @@ export interface MenuItemProps extends CommonProps, Styleable, Refable<HTMLDivEl
      * @memberof MenuItemProps
      */
     fieldSize?: VariantProps<typeof cvaMenuItemStyle>["fieldSize"];
+    /**
+     * Renders a nested menu that opens when this item is activated (click, `Enter`/`Space`, or
+     * `ArrowRight`). When present, `MenuItem` internally wraps itself in a `Popover` joined to the
+     * nearest `MenuTree`, and auto-renders a chevron affordance as `suffix` unless one is explicitly
+     * provided. `ArrowLeft` inside the submenu closes it and returns focus to this item.
+     */
+    submenu?: ReactNode;
+    /**
+     * Size constraints forwarded to the internal `Popover` that renders `submenu`. See `PopoverSizing`.
+     * Has no effect when `submenu` is not provided.
+     */
+    submenuSizing?: PopoverSizing | ((defaultSizing: PopoverSizing) => PopoverSizing);
+    /**
+     * Forwarded to the root element. Wired in by `MenuContent` to keep real DOM focus in sync with
+     * roving-tabindex keyboard navigation -- not typically set directly by consumers.
+     */
+    onFocus?: FocusEventHandler<HTMLDivElement>;
+    /**
+     * Forwarded to the root element. Wired in by `MenuContent` so hovering an item synchronizes
+     * keyboard-navigation focus -- not typically set directly by consumers.
+     */
+    onMouseMove?: MouseEventHandler<HTMLDivElement>;
+    /**
+     * Forwarded to the root element. Wired in by `MenuContent` to clear keyboard-navigation focus
+     * when the pointer leaves the list -- not typically set directly by consumers.
+     */
+    onPointerLeave?: PointerEventHandler<HTMLDivElement>;
 }
 /**
- * MenuItem represents a single actionable item within a MenuList.
- * It supports labels, icons (prefix/suffix), selected and focused states, and danger variants.
+ * MenuItem represents a single actionable item within a MenuContent.
+ * It supports labels, icons (prefix/suffix), selected and focused states, danger variants, and — via the
+ * `submenu` prop — nested submenus.
  *
  * ### When to use
- * Use MenuItem inside a `MenuList` for individual actions (edit, delete, duplicate) or selectable options.
+ * Use MenuItem inside a `MenuContent` for individual actions (edit, delete, duplicate) or selectable options.
  *
  * ### When not to use
- * Do not use MenuItem outside of a `MenuList` context. For standalone clickable items, use `Button` or `ListItem`.
+ * Do not use MenuItem outside of a `MenuContent` context. For standalone clickable items, use `Button` or `ListItem`.
  *
  * @example MenuItem with icon prefix
  * ```tsx
- * import { MenuList, MenuItem, Icon } from "@trackunit/react-components";
+ * import { MenuContent, MenuItem, Icon } from "@trackunit/react-components";
  *
  * const ActionMenu = () => (
- *   <MenuList>
+ *   <MenuContent>
  *     <MenuItem
  *       id="edit"
  *       label="Edit asset"
@@ -115,10 +144,28 @@ export interface MenuItemProps extends CommonProps, Styleable, Refable<HTMLDivEl
  *       variant="danger"
  *       onClick={() => console.log("Delete clicked")}
  *     />
- *   </MenuList>
+ *   </MenuContent>
+ * );
+ * ```
+ * @example MenuItem with a submenu
+ * ```tsx
+ * import { MenuContent, MenuItem } from "@trackunit/react-components";
+ *
+ * const StatusMenu = () => (
+ *   <MenuContent>
+ *     <MenuItem
+ *       label="Status"
+ *       submenu={
+ *         <MenuContent>
+ *           <MenuItem id="active" label="Active" />
+ *           <MenuItem id="idle" label="Idle" />
+ *         </MenuContent>
+ *       }
+ *     />
+ *   </MenuContent>
  * );
  * ```
  * @param {MenuItemProps} props - The props for the MenuItem component
  * @returns {ReactElement} MenuItem component
  */
-export declare const MenuItem: ({ className, "data-testid": dataTestId, label, children, selected, focused, prefix, suffix, disabled, onClick, stopPropagation, id, tabIndex, optionLabelDescription, optionPrefix, fieldSize, variant, style, ref, }: MenuItemProps) => ReactElement;
+export declare const MenuItem: ({ className, "data-testid": dataTestId, label, children, selected, focused, prefix, suffix, disabled, onClick, stopPropagation, id, tabIndex, optionLabelDescription, optionPrefix, fieldSize, variant, style, ref, submenu, submenuSizing, onFocus, onMouseMove, onPointerLeave, }: MenuItemProps) => ReactElement;

package/src/components/Menu/MoreMenu/MoreMenu.d.ts

@@ -43,7 +43,7 @@ export interface MoreMenuProps extends CommonProps, Styleable, Refable<HTMLDivEl
 }
 /**
  * MoreMenu (kebab menu) renders a three-dot button that opens a popover with a list of actions.
- * It is typically filled with a MenuList containing MenuItem elements.
+ * It is typically filled with a MenuContent containing MenuItem elements.
  *
  * ### When to use
  * Use MoreMenu when you have overflow actions that don't fit in the main UI. Common for row-level actions in tables, card headers, or list items.
@@ -53,30 +53,30 @@ export interface MoreMenuProps extends CommonProps, Styleable, Refable<HTMLDivEl
  *
  * @example Action items with render prop — Pass a function as `children` to receive the `close` callback and dismiss the menu after an action.
  * ```tsx
- * import { MoreMenu, MenuList, MenuItem, Icon } from "@trackunit/react-components";
+ * import { MoreMenu, MenuContent, MenuItem, Icon } from "@trackunit/react-components";
  *
  * const AssetActions = () => (
  *   <MoreMenu>
  *     {(close) => (
- *       <MenuList onClick={close}>
+ *       <MenuContent onClick={close}>
  *         <MenuItem id="edit" label="Edit" prefix={<Icon name="PencilSquare" size="small" />} />
  *         <MenuItem id="delete" label="Delete" variant="danger" prefix={<Icon name="Trash" size="small" />} />
- *       </MenuList>
+ *       </MenuContent>
  *     )}
  *   </MoreMenu>
  * );
  * ```
  * @example Custom trigger button — Use `customButton` to replace the default kebab icon with any element, like a labeled Button.
  * ```tsx
- * import { MoreMenu, MenuList, MenuItem, Button } from "@trackunit/react-components";
+ * import { MoreMenu, MenuContent, MenuItem, Button } from "@trackunit/react-components";
  *
  * const CustomTriggerMenu = () => (
  *   <MoreMenu customButton={<Button variant="secondary" size="small">Actions</Button>}>
  *     {(close) => (
- *       <MenuList onClick={close}>
+ *       <MenuContent onClick={close}>
  *         <MenuItem id="export" label="Export" />
  *         <MenuItem id="archive" label="Archive" />
- *       </MenuList>
+ *       </MenuContent>
  *     )}
  *   </MoreMenu>
  * );

package/src/components/Popover/MenuTree.d.ts

@@ -0,0 +1,130 @@
+import { FloatingTreeType, OpenChangeReason } from "@floating-ui/react";
+import { ReactElement, ReactNode } from "react";
+/**
+ * Emitted on the tree's event emitter whenever a node transitions to open, so `MenuTree` can close
+ * that node's siblings. See `usePopover`'s emit side and `MenuTree`'s listener below.
+ */
+export declare const MENU_TREE_OPEN_EVENT = "menuopen";
+/**
+ * Emitted whenever a node transitions to closed, so siblings can tell when a `reason: "click"` open
+ * (see `MenuTreeOpenEvent`) has been dismissed and stop treating that branch as click-pinned. See
+ * `usePopover`'s emit side and its `openSiblingPinned` listener.
+ */
+export declare const MENU_TREE_CLOSE_EVENT = "menuclose";
+export type MenuTreeOpenEvent = {
+    nodeId: string;
+    parentId: string | null;
+    /**
+     * How this node came to open, from Floating UI's `onOpenChange` (`undefined` for a
+     * non-interaction-driven open, e.g. the `ArrowRight` keyboard shortcut setting state directly).
+     * Siblings use this to tell a deliberate `"click"` open (or any other explicit reason) -- which
+     * should not be casually overridden by hovering past it -- apart from a `"hover"` open, which
+     * already only happened because the user was passing through the row anyway.
+     */
+    reason?: OpenChangeReason;
+    /**
+     * Whether the opening node is itself a delayed-hover submenu row (`MenuItem`'s
+     * `hover: { delayed: true }` pattern) -- as opposed to some unrelated `Popover` that merely
+     * happens to share a parent in the tree, e.g. a `Tooltip` on the same row or on the tree's own
+     * root trigger. `hasOpenSibling`/`openSiblingPinned` tracking (see `usePopover`) only cares about
+     * other menu rows, since a stray tooltip opening or closing elsewhere isn't a signal about
+     * whether hovering should switch between rows.
+     */
+    isMenuRow: boolean;
+};
+export type MenuTreeCloseEvent = {
+    nodeId: string;
+    parentId: string | null;
+    /** See `MenuTreeOpenEvent.isMenuRow`. */
+    isMenuRow: boolean;
+};
+export type UseMenuTreeType = {
+    /**
+     * This node's id within the tree. Stable for the lifetime of the component that called the hook.
+     */
+    nodeId: string;
+    /**
+     * The nearest ancestor node's id, or `null` at the root of a `MenuTree` (or outside any `MenuTree`).
+     */
+    parentId: string | null;
+    /**
+     * Whether this node has an ancestor node, i.e. it is not the root of its `MenuTree`.
+     */
+    isNested: boolean;
+    /**
+     * The underlying Floating UI tree, or `null` when called outside a `<MenuTree>`.
+     */
+    tree: FloatingTreeType | null;
+};
+/**
+ * Returns whether a pointer event landed on any `MenuTree` member's trigger or floating surface.
+ * Used by nested `Popover`s to avoid treating a click on a sibling row (or the parent panel) as an
+ * outside press that dismisses the whole branch.
+ */
+export declare const isPressInsideMenuTree: (event: Event, tree: FloatingTreeType) => boolean;
+/**
+ * Reads (and joins) the nearest `MenuTree` boundary, if any.
+ *
+ * Returns explicit tree state so fully custom nested-menu UI can be built without going through
+ * `Popover`/`PopoverTrigger`/`PopoverContent`'s implicit prop-cloning. `Popover` is one consumer of
+ * this hook, not the only way to participate in a `MenuTree`.
+ *
+ * Safe to call outside a `<MenuTree>`: `parentId`/`tree` are `null` and `isNested` is `false`.
+ *
+ * @returns {UseMenuTreeType} Explicit tree state for the calling node
+ */
+export declare const useMenuTree: () => UseMenuTreeType;
+/**
+ * Opt-in tree-coordination boundary for a family of `Popover`s: sibling-close-on-open, dismiss
+ * bubbling (Escape closes one level at a time; outside-press is scoped per node so sibling rows
+ * don't collapse the root), and hover safe-polygon between nested rows. Every `Popover` rendered
+ * automatically joins it — there is no per-instance flag to set. A `Popover` outside any `MenuTree`
+ * is unaffected and behaves exactly as it does today.
+ *
+ * Only the immediate siblings of a newly-opened node (nodes sharing the same parent) are closed.
+ * Closing a node cascades to close its own open subtree as a structural consequence of
+ * `PopoverContent` unmounting when its `Popover` closes, not extra logic here.
+ *
+ * ### When to use
+ * Wrap a family of nested `Popover`s (e.g. a menu bar or a filter bar's flyouts) that should
+ * coordinate open/close state with each other.
+ *
+ * ### When not to use
+ * Do not wrap unrelated `Popover`s that merely happen to render inside each other's React tree —
+ * they will incorrectly join tree coordination and can be closed by sibling opens.
+ *
+ * ### Click-opened rows vs. sibling hovers
+ * `hover: { delayed: true }` on a nested `Popover` (used below, instead of a plain `hover: true`)
+ * keeps a row opened by a click open while the cursor passes over its siblings, matching what
+ * `MenuItem`'s `submenu` prop already does internally. See the "Advanced" section of the
+ * `Components/Menu/Nested Menu` docs page for the full explanation.
+ *
+ * @example
+ * ```tsx
+ * import { MenuTree, Popover, PopoverContent, PopoverTrigger } from "@trackunit/react-components";
+ *
+ * const NestedMenu = () => (
+ *   <MenuTree>
+ *     <Popover placement="bottom-start">
+ *       <PopoverTrigger>Open</PopoverTrigger>
+ *       <PopoverContent>
+ *         <Popover activation={{ click: true, hover: { delayed: true } }} placement="right-start">
+ *           <PopoverTrigger>Row A</PopoverTrigger>
+ *           <PopoverContent>Row A's flyout</PopoverContent>
+ *         </Popover>
+ *         <Popover activation={{ click: true, hover: { delayed: true } }} placement="right-start">
+ *           <PopoverTrigger>Row B</PopoverTrigger>
+ *           <PopoverContent>Row B's flyout</PopoverContent>
+ *         </Popover>
+ *       </PopoverContent>
+ *     </Popover>
+ *   </MenuTree>
+ * );
+ * ```
+ * @param {object} props The props for MenuTree
+ * @param {ReactNode} props.children The `Popover`s (and anything else) to coordinate
+ * @returns {ReactElement} A `FloatingTree` provider wired up for sibling-close coordination
+ */
+export declare const MenuTree: ({ children }: {
+    children: ReactNode;
+}) => ReactElement;

package/src/components/Popover/Popover.d.ts

@@ -1,6 +1,14 @@
 import { ReactElement, ReactNode } from "react";
 import { PopoverPlacement, PopoverProps, UsePopoverType } from "./PopoverTypes";
 export type ContextType = UsePopoverType | null;
+/**
+ * Like `usePopoverContext`, but returns `null` instead of throwing when called outside a `<Popover />`.
+ * Used by components (e.g. `MenuContent`) that support being rendered either inside a `Popover` or fully
+ * standalone.
+ *
+ * @returns {ContextType} The popover context, or `null` if there is no ancestor `Popover`
+ */
+export declare const useOptionalPopoverContext: () => ContextType;
 /**
  * A hook to get the popover context.
  * It should only be used by the Popover components.

package/src/components/Popover/PopoverContent.d.ts

@@ -44,18 +44,23 @@ export interface PopoverContentProps extends Omit<HTMLProps<HTMLDivElement>, "ch
      */
     initialFocus?: number | MutableRefObject<HTMLElement | null>;
     /**
-     * Controls whether focus is returned to the previously focused element when the popover closes.
+     * Controls whether -- and where -- focus is returned when the popover closes.
      *
-     * Floating UI tracks the most recently focused tabbable element **across the whole app** (not
-     * just this popover instance) as the return target, so disabling this is the only reliable way
-     * to guarantee a popover never affects focus on close.
-     *
-     * Set to `false` for non-modal, non-interactive overlays (like `Tooltip`) that should never
-     * manage focus in either direction.
+     * - **boolean** (default `true`): Floating UI tracks the most recently focused tabbable element
+     *   **across the whole app** (not just this popover instance) as the return target. `false` is
+     *   the only reliable way to guarantee a popover never affects focus on close -- use it for
+     *   non-modal, non-interactive overlays (like `Tooltip`) that should never manage focus in
+     *   either direction.
+     * - **ref**: returns focus to this specific element instead of Floating UI's own app-wide
+     *   tracking, checked for visibility right at close time -- if the target has scrolled out of
+     *   its own scrollable ancestor (or is otherwise clipped/off-viewport), focus automatically
+     *   falls back to Floating UI's own hidden, off-screen element instead (which has no scroll
+     *   side effect) rather than focusing something the user can't see. No need to null the ref out
+     *   by hand for a scrolled-out close -- just keep it pointed at the normal target.
      *
      * @default true
      */
-    returnFocus?: boolean;
+    returnFocus?: boolean | MutableRefObject<HTMLElement | null>;
     /**
      * A ref for the component
      */

package/src/components/Popover/PopoverNestedClearance.d.ts

@@ -0,0 +1,56 @@
+import { FloatingTreeType } from "@floating-ui/react";
+/**
+ * The parent Popover's own floating panel element, found via the `MenuTree`'s Floating UI tree
+ * bookkeeping rather than by walking the DOM -- this is the exact element `PopoverContent` set as
+ * `context.refs.floating.current` when it rendered, so its rect is the parent panel's true visual
+ * boundary (border, shadow, and any internal scrollbar all already baked in), regardless of how
+ * deeply the current node's own trigger row is nested inside it.
+ *
+ * @param tree The `MenuTree`'s Floating UI tree, or `null` outside a `MenuTree`
+ * @param parentId The nearest ancestor node's id from `useMenuTree`, or `null` at the tree's root
+ * @returns {HTMLElement | null} The parent's floating panel element, or `null` if there isn't one
+ */
+export declare const getParentPanelElement: (tree: FloatingTreeType | null, parentId: string | null) => HTMLElement | null;
+/**
+ * Extra horizontal offset (in pixels) a `right`/`left`-placed submenu needs so it clears its parent
+ * Popover panel's true edge, rather than sitting flush with (or overlapping) whatever is at the edge
+ * of the specific row that triggered it.
+ *
+ * A submenu's `elements.reference` is the trigger row it opened from, not the parent panel itself --
+ * and that row's own edge is inset from the panel's true visual boundary by the panel's padding and,
+ * when the panel's list happens to be scrolling, by its scrollbar too. Measuring against the parent
+ * panel's actual rendered edge (via `getParentPanelElement` above) gets both of those for free and
+ * keeps the visual gap identical whether or not the parent list happens to be scrolling -- rather
+ * than re-deriving "how much padding/scrollbar is in the way" and landing on a different visual gap
+ * depending on the parent's internal layout.
+ *
+ * @param parentPanelElement The parent Popover's own floating panel element
+ * @param referenceElement The trigger element the submenu is anchored to
+ * @param resolvedPlacement Floating UI's resolved placement (e.g. `"right-start"`)
+ * @returns {number} Additional pixels to add to the base `offset()` `mainAxis` value
+ */
+export declare const getNestedSubmenuClearance: (parentPanelElement: HTMLElement, referenceElement: HTMLElement, resolvedPlacement: string) => number;
+type Rect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+type YToClearReferenceParams = {
+    floatingX: number;
+    floatingY: number;
+    floatingWidth: number;
+    floatingHeight: number;
+    reference: Rect;
+    gap: number;
+    viewportHeight: number;
+    padding: number;
+};
+/**
+ * When a nested submenu has shifted horizontally over its parent (cascade-with-overlap), it must
+ * not cover the trigger row that opened it. Returns a new `y` that places the floating panel
+ * entirely below or above the reference -- whichever side has more room -- or `null` when the
+ * panels do not overlap and no adjustment is needed.
+ */
+export declare const getYToClearReference: ({ floatingX, floatingY, floatingWidth, floatingHeight, reference, gap, viewportHeight, padding, }: YToClearReferenceParams) => number | null;
+export {};