@astryxdesign/core 0.1.9 → 0.2.0-canary.136a00f

package/dist/DropdownMenu/DropdownMenuSubMenu.js

@@ -0,0 +1,427 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file DropdownMenuSubMenu.tsx
+ * @input React, stylex, useLayer (context mode), useListFocus, useMenuHover,
+ *   useTypeahead, Item, Icon, Spinner, DropdownMenu context + item roles.
+ * @output Exports DropdownMenuSubMenu — a single menu row that reveals a nested
+ *   flyout menu of its own children/items.
+ * @position Sub-component; place inside a DropdownMenu (or ContextMenu)
+ *   alongside plain items.
+ *
+ * One component, not three. The row itself adopts DropdownMenuItem semantics
+ * (label / icon / description / isDisabled) and its children become the
+ * flyout's content. This mirrors how SideNavItem / TreeListItem promote a
+ * normal row into a nested surface when given children, rather than the Radix
+ * Sub / SubTrigger / SubContent split. Data-driven menus never touch this
+ * component directly — renderDropdownItems renders it from a nested `items`
+ * array and passes the rendered children in.
+ *
+ * Built on existing primitives — no bespoke floating code:
+ * - Positioning: useLayer context mode opens the flyout inline-end with
+ *   viewport auto-flip via CSS anchor positioning (RTL-correct by default).
+ * - Pointer: useMenuHover for open/close intent.
+ * - Keyboard: a per-level useListFocus + useTypeahead. Right (Left in RTL) /
+ *   Enter / Space opens the flyout and focuses its first item; Left (Right in
+ *   RTL) / Escape closes it and returns focus to the trigger row.
+ *
+ * Prior art: legacy internal XDS `XDSDropdownSubMenuItem` (APG menubar-
+ * navigation submenu). This re-expresses the same contract on Astryx primitives.
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/DropdownMenu/DropdownMenuSubMenu.doc.mjs
+ * - /packages/core/src/DropdownMenu/DropdownMenuSubMenu.test.tsx
+ * - /packages/core/src/DropdownMenu/index.ts
+ * - /apps/storybook/stories/DropdownMenu.stories.tsx
+ * - /packages/cli/templates/blocks/components/DropdownMenu/ (showcase blocks)
+ */
+import React, { useCallback, useId, useMemo, useRef, useState } from 'react';
+import * as stylex from '@stylexjs/stylex';
+import { Icon, renderIconSlot } from "../Icon/index.js";
+import { Spinner } from "../Spinner/index.js";
+import { Item } from "../Item/index.js";
+import { useLayer } from "../Layer/useLayer.js";
+import { layerAnimations } from "../Layer/layerAnimations.stylex.js";
+import { useListFocus } from "../hooks/useListFocus.js";
+import { useMenuHover } from "../hooks/useMenuHover.js";
+import { useTypeahead } from "../hooks/useTypeahead.js";
+import "../theme/tokens.stylex.js";
+import { colorVars, spacingVars, radiusVars, durationVars, easeVars, shadowVars, typographyVars, typeScaleVars } from "../theme/tokens.stylex.js";
+import { mergeProps } from "../utils/index.js";
+import { themeProps } from "../utils/themeProps.js";
+import { MENU_ITEM_ROLES, MENU_ITEM_SELECTOR, MENU_BOUNDARY_SELECTOR } from "./menuItemRoles.js";
+import { DropdownMenuContext, useDropdownMenuContext } from "./DropdownMenuContext.js";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+const triggerStyles = {
+  root: {
+    kB7OPa: "x9f619",
+    kzqmXN: "xh8yej3",
+    k8WAf4: "xce4md1",
+    kg3NbH: "xf314gf",
+    kaIpWk: "x1ws5lxm",
+    kMv6JI: "x9ynric",
+    kGuDYH: "xcr08ib",
+    kMwMTN: "x1tgivj0",
+    kWkggS: "xjbqb8w x1c52tdz",
+    kHE3J0: "xe9uy6x",
+    kkrTdU: "x1ypdohk",
+    k9WMMc: "x1yc453h",
+    kI3sdo: "x1a2a7pz",
+    $$css: true
+  },
+  open: {
+    kWkggS: "x1lmrjuc",
+    $$css: true
+  },
+  disabled: {
+    kSiTet: "xbyyjgo",
+    kkrTdU: "x1h6gzvc",
+    $$css: true
+  }
+};
+const triggerSizeStyles = {
+  sm: {
+    k8WAf4: "xu0wf1k",
+    kg3NbH: "xf314gf",
+    $$css: true
+  },
+  md: {
+    k8WAf4: "x1vofgu7",
+    $$css: true
+  },
+  lg: {
+    $$css: true
+  }
+};
+const _temp = {
+  keTefX: "x11g1kdw",
+  k71WvV: "xnur1sd",
+  "$$css": true
+};
+const flyoutStyles = {
+  popover: {
+    k7Eaqz: "x5w4yej",
+    keTefX: "x11g1kdw",
+    k71WvV: "xnur1sd",
+    $$css: true
+  },
+  popoverCustomWidth: width => [_temp, {
+    k7Eaqz: (typeof width === 'number' ? `${width}px` : width) != null ? "xkj4a21" : typeof width === 'number' ? `${width}px` : width,
+    $$css: true
+  }, {
+    "--x-minWidth": (val => typeof val === "number" ? val + "px" : val != null ? val : undefined)(typeof width === 'number' ? `${width}px` : width)
+  }]
+};
+/**
+ * A single menu row that reveals a nested flyout of its own items. The row
+ * adopts DropdownMenuItem semantics (label / icon / description / isDisabled);
+ * its `children` become the flyout content. Place inside a DropdownMenu (or
+ * ContextMenu) alongside plain items.
+ *
+ * For data-driven menus, don't use this directly — give a menu item a nested
+ * `items` array and DropdownMenu/ContextMenu renders the submenu for you.
+ *
+ * @example
+ * ```
+ * <DropdownMenu button={{label: 'Actions'}}>
+ *   <DropdownMenuItem label="Rename" onClick={rename} />
+ *   <DropdownMenuSubMenu label="Move to" icon="folder">
+ *     <DropdownMenuItem label="Folder A" onClick={() => move('a')} />
+ *     <DropdownMenuItem label="Folder B" onClick={() => move('b')} />
+ *   </DropdownMenuSubMenu>
+ * </DropdownMenu>
+ * ```
+ */
+export function DropdownMenuSubMenu(props) {
+  const {
+    icon,
+    label,
+    description,
+    isDisabled = false,
+    hasSpinner = false,
+    menuWidth,
+    onOpenChange,
+    children,
+    xstyle,
+    className,
+    style,
+    'data-testid': testId,
+    menuDataTestId
+  } = props;
+  const menuCtx = useDropdownMenuContext();
+  const menuSize = menuCtx?.menuSize ?? 'md';
+  const canOpen = !isDisabled;
+  const contentId = useId();
+  const triggerId = useId();
+  const triggerRef = useRef(null);
+  const [isOpen, setIsOpen] = useState(false);
+  const layer = useLayer({
+    mode: 'context',
+    lightDismiss: false,
+    onShow: useCallback(() => {
+      setIsOpen(true);
+      onOpenChange?.(true);
+    }, [onOpenChange]),
+    onHide: useCallback(() => {
+      setIsOpen(false);
+      onOpenChange?.(false);
+    }, [onOpenChange])
+  });
+  const showLayer = useCallback(() => {
+    if (canOpen) {
+      layer.show();
+    }
+  }, [canOpen, layer]);
+  const hideLayer = useCallback(() => {
+    layer.hide();
+  }, [layer]);
+
+  // Dedicated roving-focus + typeahead for this flyout level. The boundary
+  // selector scopes item collection and key handling to this flyout's own
+  // `role="menu"` — so a submenu nested inside this one (also inline, also
+  // `role="menu"`) doesn't pollute this level's items or double-handle keys.
+  const {
+    listRef: menuRef,
+    handleKeyDown: listNavKeyDown,
+    focusFirst,
+    focusItem,
+    ownsEvent,
+    getItems
+  } = useListFocus({
+    itemSelector: MENU_ITEM_SELECTOR,
+    boundarySelector: MENU_BOUNDARY_SELECTOR,
+    wrap: false,
+    onEscape: () => close({
+      focusTrigger: true
+    })
+  });
+  const typeahead = useTypeahead({
+    getItemLabels: () => getItems().map(el => el.textContent),
+    onMatch: focusItem,
+    getCurrentIndex: () => getItems().findIndex(el => el === document.activeElement || el.contains(document.activeElement))
+  });
+
+  // Hover-intent: entering the trigger opens after a short delay; leaving
+  // either surface closes after a delay. Hover-open does not steal focus.
+  const {
+    triggerProps,
+    contentProps
+  } = useMenuHover({
+    show: showLayer,
+    hide: hideLayer,
+    isOpen,
+    isEnabled: canOpen
+  });
+  const open = useCallback(options => {
+    if (!canOpen) {
+      return;
+    }
+    layer.show();
+    if (options?.focusFirst) {
+      requestAnimationFrame(() => {
+        // Move focus into the flyout. When it has no focusable items yet
+        // (e.g. an async submenu showing only a disabled "Loading…" row via
+        // hasSpinner), focusFirst() finds nothing — fall back to focusing the
+        // flyout container itself so keyboard ownership still transfers off
+        // the parent list. Otherwise the parent would keep focus, letting
+        // arrow keys rove the parent while the empty flyout stays open.
+        const focusedItem = focusFirst();
+        if (!focusedItem) {
+          menuRef.current?.focus();
+        }
+      });
+    }
+  }, [canOpen, layer, focusFirst, menuRef]);
+  const close = useCallback(options => {
+    layer.hide();
+    if (options?.focusTrigger !== false) {
+      triggerRef.current?.focus();
+    }
+  }, [layer]);
+
+  // Single ref for the trigger row: store it for focus management AND wire it
+  // as the flyout's positioning anchor (CSS anchor positioning).
+  const setTriggerEl = useCallback(el => {
+    triggerRef.current = el;
+    layer.ref(el);
+  }, [layer]);
+  const handleTriggerClick = useCallback(() => {
+    if (isDisabled) {
+      return;
+    }
+    // Click toggles the flyout, moving focus into it on open.
+    if (isOpen) {
+      close({
+        focusTrigger: true
+      });
+    } else {
+      open({
+        focusFirst: true
+      });
+    }
+  }, [isDisabled, isOpen, open, close]);
+  const handleTriggerKeyDown = useCallback(e => {
+    if (isDisabled) {
+      return;
+    }
+    const isRtl = typeof window !== 'undefined' && triggerRef.current ? window.getComputedStyle(triggerRef.current).direction === 'rtl' : false;
+    const openKey = isRtl ? 'ArrowLeft' : 'ArrowRight';
+    if (e.key === openKey || e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      // The trigger row is a direct child of the parent menu (not a nested
+      // role="menu"), so the parent's key handler would otherwise also act on
+      // this event (e.g. Enter clicking the focused row). Stop it here — this
+      // level fully handles opening the flyout.
+      e.stopPropagation();
+      open({
+        focusFirst: true
+      });
+    }
+  }, [isDisabled, open]);
+
+  // Enter/Space activate the focused row; typeahead jumps by first character;
+  // the close key (Left, or Right in RTL) returns focus to the trigger;
+  // arrows/Home/End defer to useListFocus (RTL-aware).
+  //
+  // The flyout renders inline (useLayer context mode is a native popover, not a
+  // portal), so a submenu nested inside this one bubbles its key events up to
+  // this handler. `ownsEvent` (from useListFocus, scoped by boundarySelector)
+  // tells us whether the event originated in THIS flyout or a deeper one; we
+  // only act on our own, letting the deeper level keep ownership. No manual
+  // stopPropagation needed — each level self-filters.
+  const handleContentKeyDown = useCallback(e => {
+    if (!ownsEvent(e)) {
+      return;
+    }
+    // Escape closes just this submenu and returns focus to its trigger (APG:
+    // Escape collapses the current level, not the whole stack). The root
+    // popover's focus-trap listens for Escape at the document level and bails
+    // when the event is already handled, so we mark it handled here (stop
+    // propagation + preventDefault) to keep the parent menu open.
+    if (e.key === 'Escape') {
+      e.preventDefault();
+      e.stopPropagation();
+      close({
+        focusTrigger: true
+      });
+      return;
+    }
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      const focused = document.activeElement;
+      if (focused && MENU_ITEM_ROLES.has(focused.getAttribute('role') ?? '')) {
+        focused.click();
+      }
+      return;
+    }
+    const isRtl = typeof window !== 'undefined' && menuRef.current ? window.getComputedStyle(menuRef.current).direction === 'rtl' : false;
+    const closeKey = isRtl ? 'ArrowRight' : 'ArrowLeft';
+    if (e.key === closeKey) {
+      e.preventDefault();
+      close({
+        focusTrigger: true
+      });
+      return;
+    }
+    if (typeahead.onKeyDown(e)) {
+      e.preventDefault();
+      return;
+    }
+    listNavKeyDown(e);
+  }, [ownsEvent, close, listNavKeyDown, typeahead, menuRef]);
+
+  // Re-provide the menu context so nested items behave exactly like top-level
+  // ones. Selecting a leaf item must dismiss the WHOLE stack, not just this
+  // flyout: close this level (without stealing focus back to the trigger) and
+  // propagate up via the parent menu's closeMenu. Because every level
+  // re-provides the context, this chains from the deepest flyout all the way to
+  // the root DropdownMenu (whose closeMenu hides the popover).
+  const nestedMenuContext = useMemo(() => ({
+    menuSize,
+    closeMenu: () => {
+      close({
+        focusTrigger: false
+      });
+      menuCtx?.closeMenu();
+    }
+  }), [menuSize, close, menuCtx]);
+  const endAffordance = hasSpinner ? /*#__PURE__*/_jsx("span", {
+    ...{
+      className: "x78zum5 x6s0dn4"
+    },
+    children: /*#__PURE__*/_jsx(Spinner, {
+      size: "sm"
+    })
+  }) : /*#__PURE__*/_jsx("span", {
+    ...{
+      className: "x78zum5 x6s0dn4"
+    },
+    children: /*#__PURE__*/_jsx(Icon, {
+      icon: "chevronRight",
+      size: "sm",
+      color: "secondary"
+    })
+  });
+  const popoverXstyle = menuWidth ? flyoutStyles.popoverCustomWidth(menuWidth) : flyoutStyles.popover;
+  return /*#__PURE__*/_jsxs(_Fragment, {
+    children: [/*#__PURE__*/_jsx(Item, {
+      ref: el => setTriggerEl(el),
+      id: triggerId,
+      role: "menuitem",
+      tabIndex: isDisabled ? undefined : -1,
+      "aria-haspopup": "menu",
+      "aria-expanded": isOpen,
+      "aria-controls": isOpen ? contentId : undefined,
+      "aria-disabled": isDisabled || undefined,
+      "data-testid": testId,
+      onMouseEnter: triggerProps.onMouseEnter,
+      onMouseLeave: triggerProps.onMouseLeave,
+      startContent: icon ? renderIconSlot(icon, {
+        size: 'sm',
+        color: 'secondary'
+      }) : undefined,
+      label: label,
+      description: description,
+      endContent: endAffordance,
+      onClick: handleTriggerClick,
+      onKeyDown: handleTriggerKeyDown,
+      isDisabled: isDisabled,
+      xstyle: [triggerStyles.root, triggerSizeStyles[menuSize], isOpen && triggerStyles.open, isDisabled && triggerStyles.disabled, xstyle],
+      ...mergeProps(themeProps('dropdown-menu-item', {
+        size: menuSize
+      }), {
+        className,
+        style
+      })
+    }), layer.render(/*#__PURE__*/_jsx("div", {
+      ref: menuRef,
+      id: contentId,
+      role: "menu"
+      // Focusable as a fallback target so an empty/loading flyout (e.g.
+      // hasSpinner with only a disabled row) can still receive keyboard
+      // focus and own arrow/Escape keys instead of leaving focus on the
+      // parent list.
+      ,
+      tabIndex: -1,
+      "aria-labelledby": triggerId,
+      onKeyDown: handleContentKeyDown,
+      onMouseEnter: contentProps.onMouseEnter,
+      onMouseLeave: contentProps.onMouseLeave,
+      "data-testid": menuDataTestId,
+      ...mergeProps(themeProps('dropdown-menu'), {
+        className: "x9f619 x78zum5 xdt5ytf x1lsbc85 xuyqlj2 x1odjw0f x1fcsqxe xgory14 x9epnlk x1n97fys x1prclbq x1i5ehqx x1hc1fzr x19991ni xuedmi6 xlr8y92"
+      }),
+      children: /*#__PURE__*/_jsx(DropdownMenuContext, {
+        value: nestedMenuContext,
+        children: children
+      })
+    }), {
+      placement: 'end',
+      alignment: 'start',
+      xstyle: [popoverXstyle, layerAnimations.end]
+    })]
+  });
+}
+DropdownMenuSubMenu.displayName = 'DropdownMenuSubMenu';

package/dist/DropdownMenu/index.d.ts

@@ -2,11 +2,21 @@
  * @file index.ts
  * @output Exports DropdownMenu, DropdownMenuItem and related types
  * @position Public API entry point
+ *
+ * SYNC: The item components below are re-exported (aliased) by the other menu
+ * surfaces that reuse the DropdownMenu item pipeline. When you add or remove an
+ * item component here, mirror it in:
+ * - /packages/core/src/ContextMenu/index.ts        (ContextMenu* aliases)
+ * - /packages/core/src/Breadcrumbs/index.ts        (BreadcrumbMenu* aliases)
+ * Those surfaces render menu items through the same renderDropdownItems +
+ * DropdownMenuContext + useListFocus path, so a new item type (e.g. a submenu)
+ * only shows up in their public API once it's aliased there too.
  */
 export { DropdownMenu, type DropdownMenuProps, type DropdownMenuButtonProps, type DropdownMenuItemData, type DropdownMenuDivider, type DropdownMenuSection, type DropdownMenuOption, } from './DropdownMenu';
 export { DropdownMenuItem, type DropdownMenuItemProps } from './DropdownMenuItem';
 export { DropdownMenuCheckboxItem, type DropdownMenuCheckboxItemProps, } from './DropdownMenuCheckboxItem';
 export { DropdownMenuRadioGroup, type DropdownMenuRadioGroupProps, } from './DropdownMenuRadioGroup';
 export { DropdownMenuRadioItem, type DropdownMenuRadioItemProps, } from './DropdownMenuRadioItem';
+export { DropdownMenuSubMenu, type DropdownMenuSubMenuProps, } from './DropdownMenuSubMenu';
 export { DropdownMenuContext, useDropdownMenuContext, type DropdownMenuContextValue, type DropdownMenuSize, } from './DropdownMenuContext';
 //# sourceMappingURL=index.d.ts.map

package/dist/DropdownMenu/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/index.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AAEH,OAAO,EACL,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAC,gBAAgB,EAAE,KAAK,qBAAqB,EAAC,MAAM,oBAAoB,CAAC;AAGhF,OAAO,EACL,wBAAwB,EACxB,KAAK,6BAA6B,GACnC,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,sBAAsB,EACtB,KAAK,2BAA2B,GACjC,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,qBAAqB,EACrB,KAAK,0BAA0B,GAChC,MAAM,yBAAyB,CAAC;AAIjC,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,GACtB,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/index.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,YAAY,EACZ,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAC,gBAAgB,EAAE,KAAK,qBAAqB,EAAC,MAAM,oBAAoB,CAAC;AAGhF,OAAO,EACL,wBAAwB,EACxB,KAAK,6BAA6B,GACnC,MAAM,4BAA4B,CAAC;AACpC,OAAO,EACL,sBAAsB,EACtB,KAAK,2BAA2B,GACjC,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,qBAAqB,EACrB,KAAK,0BAA0B,GAChC,MAAM,yBAAyB,CAAC;AAIjC,OAAO,EACL,mBAAmB,EACnB,KAAK,wBAAwB,GAC9B,MAAM,uBAAuB,CAAC;AAI/B,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,KAAK,wBAAwB,EAC7B,KAAK,gBAAgB,GACtB,MAAM,uBAAuB,CAAC"}

package/dist/DropdownMenu/index.js

@@ -6,6 +6,15 @@
  * @file index.ts
  * @output Exports DropdownMenu, DropdownMenuItem and related types
  * @position Public API entry point
+ *
+ * SYNC: The item components below are re-exported (aliased) by the other menu
+ * surfaces that reuse the DropdownMenu item pipeline. When you add or remove an
+ * item component here, mirror it in:
+ * - /packages/core/src/ContextMenu/index.ts        (ContextMenu* aliases)
+ * - /packages/core/src/Breadcrumbs/index.ts        (BreadcrumbMenu* aliases)
+ * Those surfaces render menu items through the same renderDropdownItems +
+ * DropdownMenuContext + useListFocus path, so a new item type (e.g. a submenu)
+ * only shows up in their public API once it's aliased there too.
  */
 export { DropdownMenu } from "./DropdownMenu.js";
 export { DropdownMenuItem } from "./DropdownMenuItem.js";
@@ -15,6 +24,10 @@ export { DropdownMenuCheckboxItem } from "./DropdownMenuCheckboxItem.js";
 export { DropdownMenuRadioGroup } from "./DropdownMenuRadioGroup.js";
 export { DropdownMenuRadioItem } from "./DropdownMenuRadioItem.js";
 
+// Submenu — a single menu row that reveals a nested flyout of its own
+// children/items. Data mode via DropdownMenuItemData.items.
+export { DropdownMenuSubMenu } from "./DropdownMenuSubMenu.js";
+
 // Menu-coordination context — public so consumers can build custom menu items
 // that read the menu size / close the menu.
 export { DropdownMenuContext, useDropdownMenuContext } from "./DropdownMenuContext.js";

package/dist/DropdownMenu/menuItemHover.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @file menuItemHover.ts
+ * @output Exports focusMenuItemOnHover
+ * @position Shared helper for DropdownMenu/ContextMenu item components
+ *
+ * Menus keep a single highlighted item by using DOM focus as the sole
+ * highlight source. Mouse hover moves focus onto the pointed-at item so the
+ * one focus highlight follows the pointer — instead of a separate `:hover`
+ * background leaving the keyboard-focused item highlighted at the same time.
+ *
+ * SYNC: When modified, update the item components that use it:
+ * - /packages/core/src/DropdownMenu/DropdownMenuItem.tsx
+ * - /packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.tsx
+ * - /packages/core/src/DropdownMenu/DropdownMenuRadioItem.tsx
+ */
+import type { PointerEvent } from 'react';
+/**
+ * Move focus to a menu item as the pointer moves over it, so hover and
+ * keyboard navigation share a single focus-driven highlight. Only reacts to a
+ * real mouse (not touch/pen, which have no hover), and skips disabled items.
+ */
+export declare function focusMenuItemOnHover(e: PointerEvent<HTMLElement>, isDisabled?: boolean): void;
+//# sourceMappingURL=menuItemHover.d.ts.map

package/dist/DropdownMenu/menuItemHover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"menuItemHover.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/menuItemHover.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAC,YAAY,EAAC,MAAM,OAAO,CAAC;AAExC;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,CAAC,EAAE,YAAY,CAAC,WAAW,CAAC,EAC5B,UAAU,CAAC,EAAE,OAAO,GACnB,IAAI,CAQN"}

package/dist/DropdownMenu/menuItemHover.js

@@ -0,0 +1,33 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file menuItemHover.ts
+ * @output Exports focusMenuItemOnHover
+ * @position Shared helper for DropdownMenu/ContextMenu item components
+ *
+ * Menus keep a single highlighted item by using DOM focus as the sole
+ * highlight source. Mouse hover moves focus onto the pointed-at item so the
+ * one focus highlight follows the pointer — instead of a separate `:hover`
+ * background leaving the keyboard-focused item highlighted at the same time.
+ *
+ * SYNC: When modified, update the item components that use it:
+ * - /packages/core/src/DropdownMenu/DropdownMenuItem.tsx
+ * - /packages/core/src/DropdownMenu/DropdownMenuCheckboxItem.tsx
+ * - /packages/core/src/DropdownMenu/DropdownMenuRadioItem.tsx
+ */
+/**
+ * Move focus to a menu item as the pointer moves over it, so hover and
+ * keyboard navigation share a single focus-driven highlight. Only reacts to a
+ * real mouse (not touch/pen, which have no hover), and skips disabled items.
+ */
+export function focusMenuItemOnHover(e, isDisabled) {
+  if (isDisabled || e.pointerType !== 'mouse') {
+    return;
+  }
+  const el = e.currentTarget;
+  if (el !== el.ownerDocument.activeElement) {
+    el.focus();
+  }
+}

package/dist/DropdownMenu/menuItemRoles.d.ts

@@ -10,4 +10,12 @@
  */
 export declare const MENU_ITEM_ROLES: ReadonlySet<string>;
 export declare const MENU_ITEM_SELECTOR: string;
+/**
+ * Boundary selector for a single menu level. A menu and its submenu flyouts
+ * both use `role="menu"`, and flyouts render inline (native popover, not a
+ * portal), so a nested menu's items and key events would otherwise be picked
+ * up by the parent. Pass this as `useListFocus`'s `boundarySelector` so each
+ * level scopes item collection and key handling to its own container.
+ */
+export declare const MENU_BOUNDARY_SELECTOR = "[role=\"menu\"]";
 //# sourceMappingURL=menuItemRoles.d.ts.map

package/dist/DropdownMenu/menuItemRoles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"menuItemRoles.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/menuItemRoles.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAI9C,CAAC;AAEH,eAAO,MAAM,kBAAkB,EAAE,MAErB,CAAC"}
+{"version":3,"file":"menuItemRoles.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/menuItemRoles.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAI9C,CAAC;AAEH,eAAO,MAAM,kBAAkB,EAAE,MAErB,CAAC;AAEb;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,oBAAkB,CAAC"}

package/dist/DropdownMenu/menuItemRoles.js

@@ -12,4 +12,13 @@
  */
 
 export const MENU_ITEM_ROLES = new Set(['menuitem', 'menuitemradio', 'menuitemcheckbox']);
-export const MENU_ITEM_SELECTOR = [...MENU_ITEM_ROLES].map(role => `[role="${role}"]:not([aria-disabled="true"])`).join(',');
+export const MENU_ITEM_SELECTOR = [...MENU_ITEM_ROLES].map(role => `[role="${role}"]:not([aria-disabled="true"])`).join(',');
+
+/**
+ * Boundary selector for a single menu level. A menu and its submenu flyouts
+ * both use `role="menu"`, and flyouts render inline (native popover, not a
+ * portal), so a nested menu's items and key events would otherwise be picked
+ * up by the parent. Pass this as `useListFocus`'s `boundarySelector` so each
+ * level scopes item collection and key handling to its own container.
+ */
+export const MENU_BOUNDARY_SELECTOR = '[role="menu"]';

package/dist/DropdownMenu/renderDropdownItems.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"renderDropdownItems.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/renderDropdownItems.tsx"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAUrC,OAAO,KAAK,EAEV,kBAAkB,EAEnB,MAAM,gBAAgB,CAAC;AAyBxB;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,kBAAkB,EAAE,GAC1B,SAAS,CA8CX"}
+{"version":3,"file":"renderDropdownItems.d.ts","sourceRoot":"","sources":["../../src/DropdownMenu/renderDropdownItems.tsx"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAWrC,OAAO,KAAK,EAEV,kBAAkB,EAEnB,MAAM,gBAAgB,CAAC;AAyBxB;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,kBAAkB,EAAE,GAAG,SAAS,CA6D1E"}

package/dist/DropdownMenu/renderDropdownItems.js

@@ -9,6 +9,7 @@
 import * as stylex from '@stylexjs/stylex';
 import { Divider } from "../Divider/index.js";
 import { DropdownMenuItem } from "./DropdownMenuItem.js";
+import { DropdownMenuSubMenu } from "./DropdownMenuSubMenu.js";
 import "../theme/tokens.stylex.js";
 import { spacingVars, typographyVars, typeScaleVars, colorVars } from "../theme/tokens.stylex.js";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
@@ -55,12 +56,26 @@ export function renderDropdownItems(items) {
         }, getItemKey(item)))]
       }, getSectionKey(option, i)));
     } else if (!('type' in option)) {
-      elements.push(/*#__PURE__*/_jsx(DropdownMenuItem, {
-        icon: option.icon,
-        label: option.label,
-        onClick: option.onClick,
-        isDisabled: option.isDisabled
-      }, getItemKey(option)));
+      // A plain item that declares nested `items` becomes a submenu (data-mode
+      // parity with the compound DropdownMenuSubMenu API); otherwise it's a
+      // leaf. renderDropdownItems owns the recursion and hands the rendered
+      // children to DropdownMenuSubMenu — so DropdownMenuSubMenu never imports
+      // this module back (no import cycle).
+      if (option.items && option.items.length > 0) {
+        elements.push(/*#__PURE__*/_jsx(DropdownMenuSubMenu, {
+          icon: option.icon,
+          label: option.label,
+          isDisabled: option.isDisabled,
+          children: renderDropdownItems(option.items)
+        }, getItemKey(option)));
+      } else {
+        elements.push(/*#__PURE__*/_jsx(DropdownMenuItem, {
+          icon: option.icon,
+          label: option.label,
+          onClick: option.onClick,
+          isDisabled: option.isDisabled
+        }, getItemKey(option)));
+      }
     }
   }
   return elements;

package/dist/Field/Field.d.ts

@@ -14,6 +14,7 @@
 import { type ReactNode } from 'react';
 import type { BaseProps } from '../BaseProps';
 import type { SizeValue } from '../utils/types';
+import type { FieldStatusVariant } from '../FieldStatus/FieldStatus';
 import type { IconType } from '../Icon';
 export type { SizeValue } from '../utils/types';
 export type FieldStatusType = 'warning' | 'error' | 'success';
@@ -105,9 +106,10 @@ export interface FieldProps extends Omit<BaseProps<HTMLDivElement>, 'children'>
      * How the status message is rendered relative to the input.
      * - 'attached': Status sits directly below the input (default, for bordered inputs)
      * - 'detached': Status is a separate element below the field (for checkboxes, switches, sliders)
+     * - 'tooltip': No message box; the input surfaces status through a tooltip on its on-field icon
      * @default 'attached'
      */
-    statusVariant?: 'attached' | 'detached';
+    statusVariant?: FieldStatusVariant;
     /**
      * Width of the field. Numbers are treated as pixels, strings are used as-is
      * (e.g. `'100%'`). Sizes the whole field — label, control, and status — so

package/dist/Field/Field.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Field.d.ts","sourceRoot":"","sources":["../../src/Field/Field.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAC,KAAK,SAAS,EAAM,MAAM,OAAO,CAAC;AAE1C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAI9C,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,SAAS,CAAC;AAqCtC,YAAY,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAE9C,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAE9D,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,IAAI,EAAE,eAAe,CAAC;IACtB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAW,SAAQ,IAAI,CACtC,SAAS,CAAC,cAAc,CAAC,EACzB,UAAU,CACX;IACC,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,SAAS,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACjC;;;OAGG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACxC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,EACpB,KAAK,EACL,aAAqB,EACrB,WAAW,EACX,OAAO,EACP,OAAO,EACP,YAAoB,EACpB,aAAa,EACb,UAAkB,EAClB,UAAkB,EAClB,UAAkB,EAClB,SAAS,EACT,MAAM,EACN,YAAY,EACZ,aAA0B,EAC1B,KAAK,EACL,MAAM,EACN,QAAQ,EACR,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,UAAU,+BAqGZ;yBA3He,KAAK"}
+{"version":3,"file":"Field.d.ts","sourceRoot":"","sources":["../../src/Field/Field.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAC,KAAK,SAAS,EAAM,MAAM,OAAO,CAAC;AAE1C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAG9C,OAAO,KAAK,EAAC,kBAAkB,EAAC,MAAM,4BAA4B,CAAC;AAEnE,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,SAAS,CAAC;AAqCtC,YAAY,EAAC,SAAS,EAAC,MAAM,gBAAgB,CAAC;AAE9C,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAE9D,MAAM,WAAW,gBAAgB;IAC/B;;OAEG;IACH,IAAI,EAAE,eAAe,CAAC;IACtB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAW,SAAQ,IAAI,CACtC,SAAS,CAAC,cAAc,CAAC,EACzB,UAAU,CACX;IACC,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,SAAS,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IACjC;;;OAGG;IACH,MAAM,CAAC,EAAE,gBAAgB,CAAC;IAC1B;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,EACpB,KAAK,EACL,aAAqB,EACrB,WAAW,EACX,OAAO,EACP,OAAO,EACP,YAAoB,EACpB,aAAa,EACb,UAAkB,EAClB,UAAkB,EAClB,UAAkB,EAClB,SAAS,EACT,MAAM,EACN,YAAY,EACZ,aAA0B,EAC1B,KAAK,EACL,MAAM,EACN,QAAQ,EACR,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,UAAU,+BAwGZ;yBA9He,KAAK"}