@arun-dev/headless 4.15.0 → 4.17.0

package/dist/index.d.cts

@@ -50,9 +50,7 @@ declare function mergeProps(...objects: (UnknownProps | undefined)[]): UnknownPr
  * default element and the props it wants; the consumer can replace the element
  * entirely via `render` without losing any of it.
  *
- * Currently uses no hooks. The `use` prefix matches the API it will grow into
- * (memoised merging, so parts stop re-rendering their children needlessly) and keeps
- * call sites stable when that lands.
+ * Uses no hooks; the `use` prefix keeps its call sites those of a hook.
  */
 interface UseRenderParams {
     /**

package/dist/index.d.ts

@@ -50,9 +50,7 @@ declare function mergeProps(...objects: (UnknownProps | undefined)[]): UnknownPr
  * default element and the props it wants; the consumer can replace the element
  * entirely via `render` without losing any of it.
  *
- * Currently uses no hooks. The `use` prefix matches the API it will grow into
- * (memoised merging, so parts stop re-rendering their children needlessly) and keeps
- * call sites stable when that lands.
+ * Uses no hooks; the `use` prefix keeps its call sites those of a hook.
  */
 interface UseRenderParams {
     /**

package/dist/menu/index.cjs

@@ -36,6 +36,8 @@ __export(index_parts_exports, {
   RadioGroup: () => MenuRadioGroup,
   RadioItem: () => MenuRadioItem,
   Root: () => MenuRoot,
+  SubmenuRoot: () => MenuSubmenuRoot,
+  SubmenuTrigger: () => MenuSubmenuTrigger,
   Trigger: () => MenuTrigger
 });
 
@@ -139,17 +141,20 @@ function useMenuRootContext(part) {
 
 // src/menu/MenuRoot.tsx
 var import_jsx_runtime = require("react/jsx-runtime");
-function MenuRoot({
+function MenuRoot({ children, ...props }) {
+  const context = useMenuRootValue("Menu.Root", props, null);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(MenuRootContext.Provider, { value: context, children });
+}
+function useMenuRootValue(name, {
   open: openProp,
   defaultOpen,
   onOpenChange,
-  focusableWhenDisabled = false,
-  children
-}) {
+  focusableWhenDisabled = false
+}, parent) {
   const [open, setOpenState] = useControlled({
     controlled: openProp,
     default: defaultOpen ?? false,
-    name: "Menu.Root",
+    name,
     state: "open"
   });
   const setOpen = (0, import_react3.useCallback)(
@@ -160,6 +165,10 @@ function MenuRoot({
     },
     [open, setOpenState, onOpenChange]
   );
+  const closeAll = (0, import_react3.useCallback)(() => {
+    setOpen(false);
+    parent?.closeAll();
+  }, [setOpen, parent]);
   const [items, setItems] = (0, import_react3.useState)([]);
   const register = (0, import_react3.useCallback)((entry) => {
     setItems((current) => [...current, entry].sort(byDocumentOrder));
@@ -172,10 +181,14 @@ function MenuRoot({
   const id = (0, import_react3.useId)();
   const triggerRef = (0, import_react3.useRef)(null);
   const focusOnOpenRef = (0, import_react3.useRef)("first");
-  const context = (0, import_react3.useMemo)(
+  const popupRef = (0, import_react3.useRef)(null);
+  const openSubmenuRef = (0, import_react3.useRef)(null);
+  const graceRef = (0, import_react3.useRef)(null);
+  return (0, import_react3.useMemo)(
     () => ({
       open,
       setOpen,
+      closeAll,
       navigableItems,
       focusableWhenDisabled,
       register,
@@ -183,11 +196,14 @@ function MenuRoot({
       triggerId: `${id}-trigger`,
       popupId: `${id}-popup`,
       anchorName: anchorNameFor(id),
-      triggerRef
+      triggerRef,
+      parent,
+      popupRef,
+      openSubmenuRef,
+      graceRef
     }),
-    [open, setOpen, navigableItems, focusableWhenDisabled, register, id]
+    [open, setOpen, closeAll, navigableItems, focusableWhenDisabled, register, id, parent]
   );
-  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(MenuRootContext.Provider, { value: context, children });
 }
 
 // src/core/useRender.ts
@@ -373,7 +389,7 @@ function useTypeahead() {
 
 // src/menu/MenuPopup.tsx
 function MenuPopup({
-  side = "bottom",
+  side: sideProp,
   align = "start",
   className,
   children,
@@ -388,9 +404,12 @@ function MenuPopup({
     triggerId,
     popupId,
     anchorName,
-    triggerRef
+    triggerRef,
+    parent,
+    popupRef: elementRef,
+    openSubmenuRef
   } = useMenuRootContext("Popup");
-  const elementRef = (0, import_react6.useRef)(null);
+  const side = sideProp ?? (parent ? "right" : "bottom");
   const focusPendingRef = (0, import_react6.useRef)(false);
   const [, resync] = (0, import_react6.useReducer)((n) => n + 1, 0);
   const typeahead = useTypeahead();
@@ -408,7 +427,8 @@ function MenuPopup({
     }
     if (focusPendingRef.current && navigableItems.length > 0) {
       focusPendingRef.current = false;
-      const target = focusOnOpenRef.current === "last" ? navigableItems.at(-1) : navigableItems[0];
+      const focus = focusOnOpenRef.current;
+      const target = focus === "last" ? navigableItems.at(-1) : focus === "first" ? navigableItems[0] : null;
       target?.ref.current?.focus();
     }
   });
@@ -433,6 +453,12 @@ function MenuPopup({
         }
         const current = navigableItems.findIndex((i) => i.ref.current === event.target);
         if (current < 0 && event.target !== event.currentTarget) return;
+        const rtl = getComputedStyle(event.currentTarget).direction === "rtl";
+        if (parent && event.key === (rtl ? "ArrowRight" : "ArrowLeft")) {
+          event.preventDefault();
+          setOpen(false);
+          return;
+        }
         const search = typeahead(event);
         const next = search === null ? rovingIndex(event.key, {
           count: navigableItems.length,
@@ -447,7 +473,15 @@ function MenuPopup({
         if (search !== null) event.preventDefault();
         if (next === null) return;
         event.preventDefault();
-        navigableItems[next]?.ref.current?.focus();
+        const target = navigableItems[next]?.ref.current;
+        const submenu = openSubmenuRef.current;
+        if (submenu && submenu.triggerRef.current !== target) submenu.close();
+        target?.focus();
+      },
+      onBeforeToggle(event) {
+        if (event.target !== event.currentTarget || !parent) return;
+        if (event.nativeEvent.newState !== "closed") return;
+        if (event.currentTarget.contains(document.activeElement)) triggerRef.current?.focus();
       },
       onToggle(event) {
         if (event.target !== event.currentTarget) return;
@@ -462,23 +496,60 @@ function MenuPopup({
 
 // src/menu/useMenuItem.ts
 var import_react7 = require("react");
-function useMenuItem(part, { disabled, textValue, children }) {
-  const { setOpen, focusableWhenDisabled, register } = useMenuRootContext(part);
+
+// src/core/pointerIntent.ts
+function graceArea(exit, popup) {
+  const toRight = popup.left >= exit.x;
+  const edge = toRight ? popup.left : popup.right;
+  const back = toRight ? -5 : 5;
+  return [
+    { x: exit.x + back, y: exit.y - 5 },
+    { x: edge, y: popup.top },
+    { x: edge, y: popup.bottom },
+    { x: exit.x + back, y: exit.y + 5 }
+  ];
+}
+function isPointInPolygon({ x, y }, polygon) {
+  let inside = false;
+  for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i, i += 1) {
+    const a = polygon[i];
+    const b = polygon[j];
+    if (!a || !b) continue;
+    if (a.y > y !== b.y > y && x < (b.x - a.x) * (y - a.y) / (b.y - a.y) + a.x) {
+      inside = !inside;
+    }
+  }
+  return inside;
+}
+
+// src/menu/useMenuItem.ts
+function useMenuItem(part, { disabled, textValue, children }, menu) {
+  const own = useMenuRootContext(part);
+  const { closeAll, focusableWhenDisabled, register, openSubmenuRef, graceRef } = menu ?? own;
   const ref = (0, import_react7.useRef)(null);
   const text = textValue ?? textOf(children);
   (0, import_react7.useLayoutEffect)(() => register({ disabled, textValue: text, ref }), [register, disabled, text]);
   return {
-    setOpen,
+    closeAll,
     itemProps: {
       type: "button",
       tabIndex: -1,
       disabled: disabled && !focusableWhenDisabled || void 0,
       "aria-disabled": disabled && focusableWhenDisabled || void 0,
       "data-disabled": disabled ? "" : void 0,
-      ref
+      ref,
+      onPointerMove(event) {
+        if (event.pointerType !== "mouse" || !openSubmenuRef.current) return;
+        if (isInGrace(graceRef.current, event)) return;
+        openSubmenuRef.current.close();
+      }
     }
   };
 }
+function isInGrace(grace, event) {
+  if (!grace || performance.now() > grace.until) return false;
+  return isPointInPolygon({ x: event.clientX, y: event.clientY }, grace.area);
+}
 var MenuItemIndicatorContext = (0, import_react7.createContext)(null);
 function useMenuItemIndicatorContext() {
   const context = (0, import_react7.useContext)(MenuItemIndicatorContext);
@@ -507,7 +578,7 @@ function MenuItem({
   render,
   ...rest
 }) {
-  const { setOpen, itemProps } = useMenuItem("Item", { disabled, textValue, children });
+  const { closeAll, itemProps } = useMenuItem("Item", { disabled, textValue, children });
   return useRender({
     render,
     defaultTagName: "button",
@@ -517,7 +588,7 @@ function MenuItem({
       className,
       children,
       onClick() {
-        if (!disabled) setOpen(false);
+        if (!disabled) closeAll();
       }
     },
     consumerProps: disabled ? rest : { ...rest, onClick }
@@ -540,7 +611,7 @@ function MenuCheckboxItem({
   render,
   ...rest
 }) {
-  const { setOpen, itemProps } = useMenuItem("CheckboxItem", { disabled, textValue, children });
+  const { closeAll, itemProps } = useMenuItem("CheckboxItem", { disabled, textValue, children });
   const [checked, setChecked] = useControlled({
     controlled: checkedProp,
     default: defaultChecked ?? false,
@@ -562,7 +633,7 @@ function MenuCheckboxItem({
         if (disabled) return;
         setChecked(!checked);
         onCheckedChange?.(!checked);
-        if (closeOnClick) setOpen(false);
+        if (closeOnClick) closeAll();
       }
     },
     consumerProps: disabled ? rest : { ...rest, onClick }
@@ -668,7 +739,7 @@ function MenuRadioItem({
 }) {
   const group = useMenuRadioGroupContext();
   const disabled = disabledProp || group.disabled;
-  const { setOpen, itemProps } = useMenuItem("RadioItem", { disabled, textValue, children });
+  const { closeAll, itemProps } = useMenuItem("RadioItem", { disabled, textValue, children });
   const checked = group.value === value;
   const state = (0, import_react11.useMemo)(() => ({ checked, disabled }), [checked, disabled]);
   const element = useRender({
@@ -684,7 +755,7 @@ function MenuRadioItem({
       onClick() {
         if (disabled) return;
         group.select(value);
-        if (closeOnClick) setOpen(false);
+        if (closeOnClick) closeAll();
       }
     },
     consumerProps: disabled ? rest : { ...rest, onClick }
@@ -724,6 +795,119 @@ function MenuGroupLabel({ className, children, render, ...rest }) {
     consumerProps: rest
   });
 }
+
+// src/menu/MenuSubmenuRoot.tsx
+var import_react13 = require("react");
+var import_jsx_runtime6 = require("react/jsx-runtime");
+function MenuSubmenuRoot({
+  focusableWhenDisabled,
+  children,
+  ...props
+}) {
+  const parent = useMenuRootContext("SubmenuRoot");
+  const context = useMenuRootValue(
+    "Menu.SubmenuRoot",
+    { ...props, focusableWhenDisabled: focusableWhenDisabled ?? parent.focusableWhenDisabled },
+    parent
+  );
+  const { open, setOpen, triggerRef } = context;
+  (0, import_react13.useEffect)(() => {
+    if (!open) return;
+    const entry = { close: () => setOpen(false), triggerRef };
+    parent.openSubmenuRef.current = entry;
+    return () => {
+      if (parent.openSubmenuRef.current === entry) parent.openSubmenuRef.current = null;
+    };
+  }, [open, setOpen, triggerRef, parent]);
+  return /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(MenuRootContext.Provider, { value: context, children });
+}
+
+// src/menu/MenuSubmenuTrigger.tsx
+var import_react14 = require("react");
+var SUBMENU_OPEN_DELAY = 100;
+var SUBMENU_GRACE_PERIOD = 300;
+function MenuSubmenuTrigger({
+  disabled = false,
+  textValue,
+  onClick,
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const submenu = useMenuRootContext("SubmenuTrigger");
+  const { parent } = submenu;
+  if (parent === null) {
+    throw new Error("<Menu.SubmenuTrigger> must be rendered inside <Menu.SubmenuRoot>.");
+  }
+  const { itemProps } = useMenuItem("SubmenuTrigger", { disabled, textValue, children }, parent);
+  const { open, setOpen, focusOnOpenRef, navigableItems, triggerRef, popupRef } = submenu;
+  const timerRef = (0, import_react14.useRef)(void 0);
+  (0, import_react14.useEffect)(() => () => clearTimeout(timerRef.current), []);
+  const openAt = (focus) => {
+    if (disabled) return;
+    focusOnOpenRef.current = focus;
+    if (!open) setOpen(true);
+    else if (focus === "first") navigableItems[0]?.ref.current?.focus();
+  };
+  const openAtRef = (0, import_react14.useRef)(openAt);
+  openAtRef.current = openAt;
+  const itemRef = itemProps.ref;
+  const ref = (0, import_react14.useCallback)(
+    (element) => {
+      itemRef.current = element;
+      triggerRef.current = element;
+    },
+    [itemRef, triggerRef]
+  );
+  return useRender({
+    render,
+    defaultTagName: "button",
+    props: {
+      ...itemProps,
+      id: submenu.triggerId,
+      role: "menuitem",
+      "aria-haspopup": "menu",
+      "aria-expanded": open,
+      "aria-controls": submenu.popupId,
+      ...menuDataAttributes({ open }),
+      style: { anchorName: submenu.anchorName },
+      className,
+      children,
+      ref,
+      onClick(event) {
+        openAt(event.detail === 0 ? "first" : "none");
+      },
+      onKeyDown(event) {
+        const rtl = getComputedStyle(event.currentTarget).direction === "rtl";
+        if (event.key !== (rtl ? "ArrowLeft" : "ArrowRight")) return;
+        event.preventDefault();
+        openAt("first");
+      },
+      onPointerMove(event) {
+        if (event.pointerType !== "mouse" || disabled) return;
+        const sibling = parent.openSubmenuRef.current;
+        if (sibling && sibling.triggerRef !== triggerRef) sibling.close();
+        if (open || timerRef.current !== void 0) return;
+        timerRef.current = setTimeout(() => {
+          timerRef.current = void 0;
+          openAtRef.current("none");
+        }, SUBMENU_OPEN_DELAY);
+      },
+      onPointerLeave(event) {
+        clearTimeout(timerRef.current);
+        timerRef.current = void 0;
+        const popup = popupRef.current;
+        if (!open || !popup) return;
+        parent.graceRef.current = {
+          area: graceArea({ x: event.clientX, y: event.clientY }, popup.getBoundingClientRect()),
+          until: performance.now() + SUBMENU_GRACE_PERIOD
+        };
+      }
+    },
+    consumerProps: disabled ? rest : { ...rest, onClick }
+  });
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Menu

package/dist/menu/index.d.cts

@@ -2,6 +2,11 @@ import * as react from 'react';
 import { ReactNode, ReactElement, Ref, ComponentPropsWithRef } from 'react';
 import { A as AnchorSide, a as AnchorAlign } from '../anchoring-Btxi0QwC.cjs';
 
+/** The state Menu.Root shares with its parts, and projects as `data-*` attributes. */
+type MenuState = {
+    open: boolean;
+};
+
 type MenuRootProps = {
     /**
      * Controlled state. Provide `onOpenChange` alongside it.
@@ -34,7 +39,7 @@ type MenuRootProps = {
  * Each Item registers its own `disabled` from its props; the Root never reads it back from
  * the DOM (decision 10). Elements are kept only to move focus to.
  */
-declare function MenuRoot({ open: openProp, defaultOpen, onOpenChange, focusableWhenDisabled, children, }: MenuRootProps): react.JSX.Element;
+declare function MenuRoot({ children, ...props }: MenuRootProps): react.JSX.Element;
 
 type MenuTriggerOwnProps = {
     /** Element to render instead of the default `<button>`. Props and ref are merged onto it. */
@@ -53,7 +58,10 @@ declare function MenuTrigger({ className, children, render, ...rest }: MenuTrigg
 type MenuSide = AnchorSide;
 type MenuAlign = AnchorAlign;
 type MenuPopupOwnProps = {
-    /** Which side of the trigger to open on. Flips to the opposite side when there is no room. */
+    /**
+     * Which side of the trigger to open on. Flips to the opposite side when there is no room.
+     * Defaults to `'bottom'`, and to `'right'` in a submenu.
+     */
     side?: MenuSide;
     /** Where along that side: flush with the trigger's start or end edge, or centred on it. */
     align?: MenuAlign;
@@ -72,11 +80,15 @@ type MenuPopupProps = MenuPopupOwnProps & Omit<ComponentPropsWithRef<'div'>, key
  * whose text starts with what was typed. Disabled items are skipped by both, unless the Root
  * sets `focusableWhenDisabled`. Tab closes the menu and lets focus move on.
  *
+ * Inside a SubmenuRoot it is that submenu's popup: it opens beside its SubmenuTrigger, ← (→ in
+ * a right-to-left menu) closes it, and Tab closes every level. Closing with focus inside returns
+ * it to the SubmenuTrigger.
+ *
  * Light dismiss and Esc close the element before anyone is asked; the `toggle` event
  * reports it through the Root, and the element reopens if the state stays open. Focus
  * returns to the Trigger, the invoker, whenever the menu hides with focus inside it.
  */
-declare function MenuPopup({ side, align, className, children, render, ...rest }: MenuPopupProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+declare function MenuPopup({ side: sideProp, align, className, children, render, ...rest }: MenuPopupProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 
 type MenuItemOwnProps = {
     /**
@@ -97,8 +109,8 @@ type MenuItemOwnProps = {
 type MenuItemProps = MenuItemOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof MenuItemOwnProps>;
 /**
  * One action. A native `<button>`, so Enter, Space and a click activate it with no key
- * handling here: put the action in `onClick`. Activating it closes the menu — call
- * `event.preventComponentHandler()` in your `onClick` to keep it open.
+ * handling here: put the action in `onClick`. Activating it closes the menu, and every menu
+ * it is nested in — call `event.preventComponentHandler()` in your `onClick` to keep it open.
  *
  * Disabled, your `onClick` is not attached, so an `aria-disabled` item under the Root's
  * `focusableWhenDisabled` cannot run it either.
@@ -237,13 +249,63 @@ type MenuGroupLabelProps = MenuGroupLabelOwnProps & Omit<ComponentPropsWithRef<'
  */
 declare function MenuGroupLabel({ className, children, render, ...rest }: MenuGroupLabelProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 
-declare namespace index_parts {
-  export { MenuCheckboxItem as CheckboxItem, MenuGroup as Group, MenuGroupLabel as GroupLabel, MenuItem as Item, MenuItemIndicator as ItemIndicator, MenuPopup as Popup, MenuRadioGroup as RadioGroup, MenuRadioItem as RadioItem, MenuRoot as Root, MenuTrigger as Trigger };
-}
+type MenuSubmenuRootProps = {
+    /**
+     * Controlled state. Provide `onOpenChange` alongside it.
+     *
+     * Never `undefined` once mounted: the mode is latched at mount, as for Menu.Root.
+     */
+    open?: boolean;
+    /** Initial state when uncontrolled. Read once, at mount. */
+    defaultOpen?: boolean;
+    /**
+     * Called on every request to open or close — its SubmenuTrigger, the arrow keys, an Item,
+     * Esc, a click elsewhere, or the pointer moving to another item of the parent menu.
+     */
+    onOpenChange?: (open: boolean) => void;
+    /** As on Menu.Root. Defaults to the parent menu's setting. */
+    focusableWhenDisabled?: boolean;
+    children?: ReactNode;
+};
+/**
+ * A menu inside a menu: holds the submenu's state, as Root does, and renders no element. Put a
+ * SubmenuTrigger and a Popup inside it; the Popup opens beside the trigger, on the right by
+ * default.
+ *
+ * The popup is a native `popover="auto"` shown with the trigger as its `source`, which nests it
+ * in the parent's popover: the parent stays open while it is, Esc closes one level at a time,
+ * a click in the parent closes only the submenu, and focus returns to the trigger — all the
+ * platform's. Activating an item closes every level.
+ */
+declare function MenuSubmenuRoot({ focusableWhenDisabled, children, ...props }: MenuSubmenuRootProps): react.JSX.Element;
 
-/** The state Menu.Root shares with its parts, and projects as `data-*` attributes. */
-type MenuState = {
-    open: boolean;
+type MenuSubmenuTriggerOwnProps = {
+    /**
+     * Cannot open its submenu. Skipped by the arrow keys, unless the Root sets
+     * `focusableWhenDisabled`.
+     */
+    disabled?: boolean;
+    /** The text typeahead matches in the parent menu. Defaults to the text in `children`. */
+    textValue?: string;
+    /** Element to render instead of the default `<button>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
 };
+type MenuSubmenuTriggerProps = MenuSubmenuTriggerOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof MenuSubmenuTriggerOwnProps>;
+/**
+ * The item that opens a submenu: a `menuitem` of the parent menu with `aria-haspopup="menu"`,
+ * which the submenu is anchored to and named by. It registers with the parent, so the parent's
+ * arrow keys and typeahead reach it.
+ *
+ * Enter, Space and → (← in a right-to-left menu) open the submenu at its first item. Resting the
+ * pointer on it opens it without moving focus; moving to another item of the parent closes it,
+ * unless the pointer is crossing toward the submenu.
+ */
+declare function MenuSubmenuTrigger({ disabled, textValue, onClick, className, children, render, ...rest }: MenuSubmenuTriggerProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+declare namespace index_parts {
+  export { MenuCheckboxItem as CheckboxItem, MenuGroup as Group, MenuGroupLabel as GroupLabel, MenuItem as Item, MenuItemIndicator as ItemIndicator, MenuPopup as Popup, MenuRadioGroup as RadioGroup, MenuRadioItem as RadioItem, MenuRoot as Root, MenuSubmenuRoot as SubmenuRoot, MenuSubmenuTrigger as SubmenuTrigger, MenuTrigger as Trigger };
+}
 
-export { index_parts as Menu, type MenuAlign, type MenuCheckboxItemProps, type MenuGroupLabelProps, type MenuGroupProps, type MenuItemIndicatorProps, type MenuItemProps, type MenuPopupProps, type MenuRadioGroupProps, type MenuRadioItemProps, type MenuRootProps, type MenuSide, type MenuState, type MenuTriggerProps };
+export { index_parts as Menu, type MenuAlign, type MenuCheckboxItemProps, type MenuGroupLabelProps, type MenuGroupProps, type MenuItemIndicatorProps, type MenuItemProps, type MenuPopupProps, type MenuRadioGroupProps, type MenuRadioItemProps, type MenuRootProps, type MenuSide, type MenuState, type MenuSubmenuRootProps, type MenuSubmenuTriggerProps, type MenuTriggerProps };

package/dist/menu/index.d.ts

@@ -2,6 +2,11 @@ import * as react from 'react';
 import { ReactNode, ReactElement, Ref, ComponentPropsWithRef } from 'react';
 import { A as AnchorSide, a as AnchorAlign } from '../anchoring-Btxi0QwC.js';
 
+/** The state Menu.Root shares with its parts, and projects as `data-*` attributes. */
+type MenuState = {
+    open: boolean;
+};
+
 type MenuRootProps = {
     /**
      * Controlled state. Provide `onOpenChange` alongside it.
@@ -34,7 +39,7 @@ type MenuRootProps = {
  * Each Item registers its own `disabled` from its props; the Root never reads it back from
  * the DOM (decision 10). Elements are kept only to move focus to.
  */
-declare function MenuRoot({ open: openProp, defaultOpen, onOpenChange, focusableWhenDisabled, children, }: MenuRootProps): react.JSX.Element;
+declare function MenuRoot({ children, ...props }: MenuRootProps): react.JSX.Element;
 
 type MenuTriggerOwnProps = {
     /** Element to render instead of the default `<button>`. Props and ref are merged onto it. */
@@ -53,7 +58,10 @@ declare function MenuTrigger({ className, children, render, ...rest }: MenuTrigg
 type MenuSide = AnchorSide;
 type MenuAlign = AnchorAlign;
 type MenuPopupOwnProps = {
-    /** Which side of the trigger to open on. Flips to the opposite side when there is no room. */
+    /**
+     * Which side of the trigger to open on. Flips to the opposite side when there is no room.
+     * Defaults to `'bottom'`, and to `'right'` in a submenu.
+     */
     side?: MenuSide;
     /** Where along that side: flush with the trigger's start or end edge, or centred on it. */
     align?: MenuAlign;
@@ -72,11 +80,15 @@ type MenuPopupProps = MenuPopupOwnProps & Omit<ComponentPropsWithRef<'div'>, key
  * whose text starts with what was typed. Disabled items are skipped by both, unless the Root
  * sets `focusableWhenDisabled`. Tab closes the menu and lets focus move on.
  *
+ * Inside a SubmenuRoot it is that submenu's popup: it opens beside its SubmenuTrigger, ← (→ in
+ * a right-to-left menu) closes it, and Tab closes every level. Closing with focus inside returns
+ * it to the SubmenuTrigger.
+ *
  * Light dismiss and Esc close the element before anyone is asked; the `toggle` event
  * reports it through the Root, and the element reopens if the state stays open. Focus
  * returns to the Trigger, the invoker, whenever the menu hides with focus inside it.
  */
-declare function MenuPopup({ side, align, className, children, render, ...rest }: MenuPopupProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+declare function MenuPopup({ side: sideProp, align, className, children, render, ...rest }: MenuPopupProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 
 type MenuItemOwnProps = {
     /**
@@ -97,8 +109,8 @@ type MenuItemOwnProps = {
 type MenuItemProps = MenuItemOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof MenuItemOwnProps>;
 /**
  * One action. A native `<button>`, so Enter, Space and a click activate it with no key
- * handling here: put the action in `onClick`. Activating it closes the menu — call
- * `event.preventComponentHandler()` in your `onClick` to keep it open.
+ * handling here: put the action in `onClick`. Activating it closes the menu, and every menu
+ * it is nested in — call `event.preventComponentHandler()` in your `onClick` to keep it open.
  *
  * Disabled, your `onClick` is not attached, so an `aria-disabled` item under the Root's
  * `focusableWhenDisabled` cannot run it either.
@@ -237,13 +249,63 @@ type MenuGroupLabelProps = MenuGroupLabelOwnProps & Omit<ComponentPropsWithRef<'
  */
 declare function MenuGroupLabel({ className, children, render, ...rest }: MenuGroupLabelProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
 
-declare namespace index_parts {
-  export { MenuCheckboxItem as CheckboxItem, MenuGroup as Group, MenuGroupLabel as GroupLabel, MenuItem as Item, MenuItemIndicator as ItemIndicator, MenuPopup as Popup, MenuRadioGroup as RadioGroup, MenuRadioItem as RadioItem, MenuRoot as Root, MenuTrigger as Trigger };
-}
+type MenuSubmenuRootProps = {
+    /**
+     * Controlled state. Provide `onOpenChange` alongside it.
+     *
+     * Never `undefined` once mounted: the mode is latched at mount, as for Menu.Root.
+     */
+    open?: boolean;
+    /** Initial state when uncontrolled. Read once, at mount. */
+    defaultOpen?: boolean;
+    /**
+     * Called on every request to open or close — its SubmenuTrigger, the arrow keys, an Item,
+     * Esc, a click elsewhere, or the pointer moving to another item of the parent menu.
+     */
+    onOpenChange?: (open: boolean) => void;
+    /** As on Menu.Root. Defaults to the parent menu's setting. */
+    focusableWhenDisabled?: boolean;
+    children?: ReactNode;
+};
+/**
+ * A menu inside a menu: holds the submenu's state, as Root does, and renders no element. Put a
+ * SubmenuTrigger and a Popup inside it; the Popup opens beside the trigger, on the right by
+ * default.
+ *
+ * The popup is a native `popover="auto"` shown with the trigger as its `source`, which nests it
+ * in the parent's popover: the parent stays open while it is, Esc closes one level at a time,
+ * a click in the parent closes only the submenu, and focus returns to the trigger — all the
+ * platform's. Activating an item closes every level.
+ */
+declare function MenuSubmenuRoot({ focusableWhenDisabled, children, ...props }: MenuSubmenuRootProps): react.JSX.Element;
 
-/** The state Menu.Root shares with its parts, and projects as `data-*` attributes. */
-type MenuState = {
-    open: boolean;
+type MenuSubmenuTriggerOwnProps = {
+    /**
+     * Cannot open its submenu. Skipped by the arrow keys, unless the Root sets
+     * `focusableWhenDisabled`.
+     */
+    disabled?: boolean;
+    /** The text typeahead matches in the parent menu. Defaults to the text in `children`. */
+    textValue?: string;
+    /** Element to render instead of the default `<button>`. Props and ref are merged onto it. */
+    render?: ReactElement;
+    /** Ref to the rendered element. Merged with any ref on the `render` element. */
+    ref?: Ref<HTMLElement>;
 };
+type MenuSubmenuTriggerProps = MenuSubmenuTriggerOwnProps & Omit<ComponentPropsWithRef<'button'>, keyof MenuSubmenuTriggerOwnProps>;
+/**
+ * The item that opens a submenu: a `menuitem` of the parent menu with `aria-haspopup="menu"`,
+ * which the submenu is anchored to and named by. It registers with the parent, so the parent's
+ * arrow keys and typeahead reach it.
+ *
+ * Enter, Space and → (← in a right-to-left menu) open the submenu at its first item. Resting the
+ * pointer on it opens it without moving focus; moving to another item of the parent closes it,
+ * unless the pointer is crossing toward the submenu.
+ */
+declare function MenuSubmenuTrigger({ disabled, textValue, onClick, className, children, render, ...rest }: MenuSubmenuTriggerProps): ReactElement<unknown, string | react.JSXElementConstructor<any>>;
+
+declare namespace index_parts {
+  export { MenuCheckboxItem as CheckboxItem, MenuGroup as Group, MenuGroupLabel as GroupLabel, MenuItem as Item, MenuItemIndicator as ItemIndicator, MenuPopup as Popup, MenuRadioGroup as RadioGroup, MenuRadioItem as RadioItem, MenuRoot as Root, MenuSubmenuRoot as SubmenuRoot, MenuSubmenuTrigger as SubmenuTrigger, MenuTrigger as Trigger };
+}
 
-export { index_parts as Menu, type MenuAlign, type MenuCheckboxItemProps, type MenuGroupLabelProps, type MenuGroupProps, type MenuItemIndicatorProps, type MenuItemProps, type MenuPopupProps, type MenuRadioGroupProps, type MenuRadioItemProps, type MenuRootProps, type MenuSide, type MenuState, type MenuTriggerProps };
+export { index_parts as Menu, type MenuAlign, type MenuCheckboxItemProps, type MenuGroupLabelProps, type MenuGroupProps, type MenuItemIndicatorProps, type MenuItemProps, type MenuPopupProps, type MenuRadioGroupProps, type MenuRadioItemProps, type MenuRootProps, type MenuSide, type MenuState, type MenuSubmenuRootProps, type MenuSubmenuTriggerProps, type MenuTriggerProps };

package/dist/menu/index.js

@@ -30,6 +30,8 @@ __export(index_parts_exports, {
   RadioGroup: () => MenuRadioGroup,
   RadioItem: () => MenuRadioItem,
   Root: () => MenuRoot,
+  SubmenuRoot: () => MenuSubmenuRoot,
+  SubmenuTrigger: () => MenuSubmenuTrigger,
   Trigger: () => MenuTrigger
 });
 
@@ -49,17 +51,20 @@ function useMenuRootContext(part) {
 
 // src/menu/MenuRoot.tsx
 import { jsx } from "react/jsx-runtime";
-function MenuRoot({
+function MenuRoot({ children, ...props }) {
+  const context = useMenuRootValue("Menu.Root", props, null);
+  return /* @__PURE__ */ jsx(MenuRootContext.Provider, { value: context, children });
+}
+function useMenuRootValue(name, {
   open: openProp,
   defaultOpen,
   onOpenChange,
-  focusableWhenDisabled = false,
-  children
-}) {
+  focusableWhenDisabled = false
+}, parent) {
   const [open, setOpenState] = useControlled({
     controlled: openProp,
     default: defaultOpen ?? false,
-    name: "Menu.Root",
+    name,
     state: "open"
   });
   const setOpen = useCallback(
@@ -70,6 +75,10 @@ function MenuRoot({
     },
     [open, setOpenState, onOpenChange]
   );
+  const closeAll = useCallback(() => {
+    setOpen(false);
+    parent?.closeAll();
+  }, [setOpen, parent]);
   const [items, setItems] = useState([]);
   const register = useCallback((entry) => {
     setItems((current) => [...current, entry].sort(byDocumentOrder));
@@ -82,10 +91,14 @@ function MenuRoot({
   const id = useId();
   const triggerRef = useRef(null);
   const focusOnOpenRef = useRef("first");
-  const context = useMemo(
+  const popupRef = useRef(null);
+  const openSubmenuRef = useRef(null);
+  const graceRef = useRef(null);
+  return useMemo(
     () => ({
       open,
       setOpen,
+      closeAll,
       navigableItems,
       focusableWhenDisabled,
       register,
@@ -93,11 +106,14 @@ function MenuRoot({
       triggerId: `${id}-trigger`,
       popupId: `${id}-popup`,
       anchorName: anchorNameFor(id),
-      triggerRef
+      triggerRef,
+      parent,
+      popupRef,
+      openSubmenuRef,
+      graceRef
     }),
-    [open, setOpen, navigableItems, focusableWhenDisabled, register, id]
+    [open, setOpen, closeAll, navigableItems, focusableWhenDisabled, register, id, parent]
   );
-  return /* @__PURE__ */ jsx(MenuRootContext.Provider, { value: context, children });
 }
 
 // src/menu/menuDataAttributes.ts
@@ -187,7 +203,7 @@ function useTypeahead() {
 
 // src/menu/MenuPopup.tsx
 function MenuPopup({
-  side = "bottom",
+  side: sideProp,
   align = "start",
   className,
   children,
@@ -202,9 +218,12 @@ function MenuPopup({
     triggerId,
     popupId,
     anchorName,
-    triggerRef
+    triggerRef,
+    parent,
+    popupRef: elementRef,
+    openSubmenuRef
   } = useMenuRootContext("Popup");
-  const elementRef = useRef3(null);
+  const side = sideProp ?? (parent ? "right" : "bottom");
   const focusPendingRef = useRef3(false);
   const [, resync] = useReducer((n) => n + 1, 0);
   const typeahead = useTypeahead();
@@ -222,7 +241,8 @@ function MenuPopup({
     }
     if (focusPendingRef.current && navigableItems.length > 0) {
       focusPendingRef.current = false;
-      const target = focusOnOpenRef.current === "last" ? navigableItems.at(-1) : navigableItems[0];
+      const focus = focusOnOpenRef.current;
+      const target = focus === "last" ? navigableItems.at(-1) : focus === "first" ? navigableItems[0] : null;
       target?.ref.current?.focus();
     }
   });
@@ -247,6 +267,12 @@ function MenuPopup({
         }
         const current = navigableItems.findIndex((i) => i.ref.current === event.target);
         if (current < 0 && event.target !== event.currentTarget) return;
+        const rtl = getComputedStyle(event.currentTarget).direction === "rtl";
+        if (parent && event.key === (rtl ? "ArrowRight" : "ArrowLeft")) {
+          event.preventDefault();
+          setOpen(false);
+          return;
+        }
         const search = typeahead(event);
         const next = search === null ? rovingIndex(event.key, {
           count: navigableItems.length,
@@ -261,7 +287,15 @@ function MenuPopup({
         if (search !== null) event.preventDefault();
         if (next === null) return;
         event.preventDefault();
-        navigableItems[next]?.ref.current?.focus();
+        const target = navigableItems[next]?.ref.current;
+        const submenu = openSubmenuRef.current;
+        if (submenu && submenu.triggerRef.current !== target) submenu.close();
+        target?.focus();
+      },
+      onBeforeToggle(event) {
+        if (event.target !== event.currentTarget || !parent) return;
+        if (event.nativeEvent.newState !== "closed") return;
+        if (event.currentTarget.contains(document.activeElement)) triggerRef.current?.focus();
       },
       onToggle(event) {
         if (event.target !== event.currentTarget) return;
@@ -276,23 +310,60 @@ function MenuPopup({
 
 // src/menu/useMenuItem.ts
 import { createContext as createContext2, useContext as useContext2, useLayoutEffect, useRef as useRef4 } from "react";
-function useMenuItem(part, { disabled, textValue, children }) {
-  const { setOpen, focusableWhenDisabled, register } = useMenuRootContext(part);
+
+// src/core/pointerIntent.ts
+function graceArea(exit, popup) {
+  const toRight = popup.left >= exit.x;
+  const edge = toRight ? popup.left : popup.right;
+  const back = toRight ? -5 : 5;
+  return [
+    { x: exit.x + back, y: exit.y - 5 },
+    { x: edge, y: popup.top },
+    { x: edge, y: popup.bottom },
+    { x: exit.x + back, y: exit.y + 5 }
+  ];
+}
+function isPointInPolygon({ x, y }, polygon) {
+  let inside = false;
+  for (let i = 0, j = polygon.length - 1; i < polygon.length; j = i, i += 1) {
+    const a = polygon[i];
+    const b = polygon[j];
+    if (!a || !b) continue;
+    if (a.y > y !== b.y > y && x < (b.x - a.x) * (y - a.y) / (b.y - a.y) + a.x) {
+      inside = !inside;
+    }
+  }
+  return inside;
+}
+
+// src/menu/useMenuItem.ts
+function useMenuItem(part, { disabled, textValue, children }, menu) {
+  const own = useMenuRootContext(part);
+  const { closeAll, focusableWhenDisabled, register, openSubmenuRef, graceRef } = menu ?? own;
   const ref = useRef4(null);
   const text = textValue ?? textOf(children);
   useLayoutEffect(() => register({ disabled, textValue: text, ref }), [register, disabled, text]);
   return {
-    setOpen,
+    closeAll,
     itemProps: {
       type: "button",
       tabIndex: -1,
       disabled: disabled && !focusableWhenDisabled || void 0,
       "aria-disabled": disabled && focusableWhenDisabled || void 0,
       "data-disabled": disabled ? "" : void 0,
-      ref
+      ref,
+      onPointerMove(event) {
+        if (event.pointerType !== "mouse" || !openSubmenuRef.current) return;
+        if (isInGrace(graceRef.current, event)) return;
+        openSubmenuRef.current.close();
+      }
     }
   };
 }
+function isInGrace(grace, event) {
+  if (!grace || performance.now() > grace.until) return false;
+  return isPointInPolygon({ x: event.clientX, y: event.clientY }, grace.area);
+}
 var MenuItemIndicatorContext = createContext2(null);
 function useMenuItemIndicatorContext() {
   const context = useContext2(MenuItemIndicatorContext);
@@ -321,7 +392,7 @@ function MenuItem({
   render,
   ...rest
 }) {
-  const { setOpen, itemProps } = useMenuItem("Item", { disabled, textValue, children });
+  const { closeAll, itemProps } = useMenuItem("Item", { disabled, textValue, children });
   return useRender({
     render,
     defaultTagName: "button",
@@ -331,7 +402,7 @@ function MenuItem({
       className,
       children,
       onClick() {
-        if (!disabled) setOpen(false);
+        if (!disabled) closeAll();
       }
     },
     consumerProps: disabled ? rest : { ...rest, onClick }
@@ -354,7 +425,7 @@ function MenuCheckboxItem({
   render,
   ...rest
 }) {
-  const { setOpen, itemProps } = useMenuItem("CheckboxItem", { disabled, textValue, children });
+  const { closeAll, itemProps } = useMenuItem("CheckboxItem", { disabled, textValue, children });
   const [checked, setChecked] = useControlled({
     controlled: checkedProp,
     default: defaultChecked ?? false,
@@ -376,7 +447,7 @@ function MenuCheckboxItem({
         if (disabled) return;
         setChecked(!checked);
         onCheckedChange?.(!checked);
-        if (closeOnClick) setOpen(false);
+        if (closeOnClick) closeAll();
       }
     },
     consumerProps: disabled ? rest : { ...rest, onClick }
@@ -482,7 +553,7 @@ function MenuRadioItem({
 }) {
   const group = useMenuRadioGroupContext();
   const disabled = disabledProp || group.disabled;
-  const { setOpen, itemProps } = useMenuItem("RadioItem", { disabled, textValue, children });
+  const { closeAll, itemProps } = useMenuItem("RadioItem", { disabled, textValue, children });
   const checked = group.value === value;
   const state = useMemo5(() => ({ checked, disabled }), [checked, disabled]);
   const element = useRender({
@@ -498,7 +569,7 @@ function MenuRadioItem({
       onClick() {
         if (disabled) return;
         group.select(value);
-        if (closeOnClick) setOpen(false);
+        if (closeOnClick) closeAll();
       }
     },
     consumerProps: disabled ? rest : { ...rest, onClick }
@@ -538,6 +609,119 @@ function MenuGroupLabel({ className, children, render, ...rest }) {
     consumerProps: rest
   });
 }
+
+// src/menu/MenuSubmenuRoot.tsx
+import { useEffect as useEffect3 } from "react";
+import { jsx as jsx6 } from "react/jsx-runtime";
+function MenuSubmenuRoot({
+  focusableWhenDisabled,
+  children,
+  ...props
+}) {
+  const parent = useMenuRootContext("SubmenuRoot");
+  const context = useMenuRootValue(
+    "Menu.SubmenuRoot",
+    { ...props, focusableWhenDisabled: focusableWhenDisabled ?? parent.focusableWhenDisabled },
+    parent
+  );
+  const { open, setOpen, triggerRef } = context;
+  useEffect3(() => {
+    if (!open) return;
+    const entry = { close: () => setOpen(false), triggerRef };
+    parent.openSubmenuRef.current = entry;
+    return () => {
+      if (parent.openSubmenuRef.current === entry) parent.openSubmenuRef.current = null;
+    };
+  }, [open, setOpen, triggerRef, parent]);
+  return /* @__PURE__ */ jsx6(MenuRootContext.Provider, { value: context, children });
+}
+
+// src/menu/MenuSubmenuTrigger.tsx
+import { useCallback as useCallback5, useEffect as useEffect4, useRef as useRef5 } from "react";
+var SUBMENU_OPEN_DELAY = 100;
+var SUBMENU_GRACE_PERIOD = 300;
+function MenuSubmenuTrigger({
+  disabled = false,
+  textValue,
+  onClick,
+  className,
+  children,
+  render,
+  ...rest
+}) {
+  const submenu = useMenuRootContext("SubmenuTrigger");
+  const { parent } = submenu;
+  if (parent === null) {
+    throw new Error("<Menu.SubmenuTrigger> must be rendered inside <Menu.SubmenuRoot>.");
+  }
+  const { itemProps } = useMenuItem("SubmenuTrigger", { disabled, textValue, children }, parent);
+  const { open, setOpen, focusOnOpenRef, navigableItems, triggerRef, popupRef } = submenu;
+  const timerRef = useRef5(void 0);
+  useEffect4(() => () => clearTimeout(timerRef.current), []);
+  const openAt = (focus) => {
+    if (disabled) return;
+    focusOnOpenRef.current = focus;
+    if (!open) setOpen(true);
+    else if (focus === "first") navigableItems[0]?.ref.current?.focus();
+  };
+  const openAtRef = useRef5(openAt);
+  openAtRef.current = openAt;
+  const itemRef = itemProps.ref;
+  const ref = useCallback5(
+    (element) => {
+      itemRef.current = element;
+      triggerRef.current = element;
+    },
+    [itemRef, triggerRef]
+  );
+  return useRender({
+    render,
+    defaultTagName: "button",
+    props: {
+      ...itemProps,
+      id: submenu.triggerId,
+      role: "menuitem",
+      "aria-haspopup": "menu",
+      "aria-expanded": open,
+      "aria-controls": submenu.popupId,
+      ...menuDataAttributes({ open }),
+      style: { anchorName: submenu.anchorName },
+      className,
+      children,
+      ref,
+      onClick(event) {
+        openAt(event.detail === 0 ? "first" : "none");
+      },
+      onKeyDown(event) {
+        const rtl = getComputedStyle(event.currentTarget).direction === "rtl";
+        if (event.key !== (rtl ? "ArrowLeft" : "ArrowRight")) return;
+        event.preventDefault();
+        openAt("first");
+      },
+      onPointerMove(event) {
+        if (event.pointerType !== "mouse" || disabled) return;
+        const sibling = parent.openSubmenuRef.current;
+        if (sibling && sibling.triggerRef !== triggerRef) sibling.close();
+        if (open || timerRef.current !== void 0) return;
+        timerRef.current = setTimeout(() => {
+          timerRef.current = void 0;
+          openAtRef.current("none");
+        }, SUBMENU_OPEN_DELAY);
+      },
+      onPointerLeave(event) {
+        clearTimeout(timerRef.current);
+        timerRef.current = void 0;
+        const popup = popupRef.current;
+        if (!open || !popup) return;
+        parent.graceRef.current = {
+          area: graceArea({ x: event.clientX, y: event.clientY }, popup.getBoundingClientRect()),
+          until: performance.now() + SUBMENU_GRACE_PERIOD
+        };
+      }
+    },
+    consumerProps: disabled ? rest : { ...rest, onClick }
+  });
+}
 export {
   index_parts_exports as Menu
 };

package/dist/toast/index.d.cts

@@ -27,6 +27,11 @@ type ToastOptions<Data = unknown> = {
     /** Milliseconds before it closes on its own. `0` keeps it until closed. Defaults to the Provider's. */
     timeout?: number;
     priority?: ToastPriority;
+    /**
+     * Where this toast shows, for the ui's default rendering, overriding its Viewport's
+     * `position`. Headless keeps it and does nothing with it: your own layout places toasts.
+     */
+    position?: string;
     /** A button on the toast, for the ui's default rendering. The headless `Action` part is yours to place. */
     action?: {
         label: ReactNode;

package/dist/toast/index.d.ts

@@ -27,6 +27,11 @@ type ToastOptions<Data = unknown> = {
     /** Milliseconds before it closes on its own. `0` keeps it until closed. Defaults to the Provider's. */
     timeout?: number;
     priority?: ToastPriority;
+    /**
+     * Where this toast shows, for the ui's default rendering, overriding its Viewport's
+     * `position`. Headless keeps it and does nothing with it: your own layout places toasts.
+     */
+    position?: string;
     /** A button on the toast, for the ui's default rendering. The headless `Action` part is yours to place. */
     action?: {
         label: ReactNode;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arun-dev/headless",
-  "version": "4.15.0",
+  "version": "4.17.0",
   "description": "Unstyled React behaviour primitives — render engine, controlled/uncontrolled state, and data-* state projection. Ships no CSS and no class names.",
   "license": "MIT",
   "type": "module",