aeon-ui-engine 1.4.0 → 1.5.1

package/packages/primitives/dist/index.js

@@ -30,7 +30,7 @@ import {
   clamp,
   sliderMachine,
   snap
-} from "./chunk-PB3LFHXU.js";
+} from "./chunk-VUPWYBGU.js";
 import {
   STICKY_BAR_STATES,
   stickyBarMachine

package/packages/primitives/dist/machines/range-slider.d.ts

@@ -83,14 +83,14 @@ declare const rangeSliderMachine: xstate.StateMachine<RangeSliderContext, {
     type: "END";
     thumb: 0 | 1;
 }, {}, never, {
-    type: "setValues";
-    params: xstate.NonReducibleUnknown;
-} | {
     type: "setBounds";
     params: xstate.NonReducibleUnknown;
 } | {
     type: "setDisabled";
     params: xstate.NonReducibleUnknown;
+} | {
+    type: "setValues";
+    params: xstate.NonReducibleUnknown;
 } | {
     type: "pointerDown";
     params: xstate.NonReducibleUnknown;

package/packages/primitives/dist/machines/slider.d.ts

@@ -21,6 +21,14 @@ type SliderEvent = {
     type: 'HOME';
 } | {
     type: 'END';
+} | {
+    type: 'SET_BOUNDS';
+    min: number;
+    max: number;
+    step: number;
+} | {
+    type: 'SET_DISABLED';
+    disabled: boolean;
 };
 declare function clamp(value: number, min: number, max: number): number;
 declare function snap(value: number, min: number, max: number, step: number): number;
@@ -39,6 +47,14 @@ declare const sliderMachine: xstate.StateMachine<SliderContext, {
     type: "HOME";
 } | {
     type: "END";
+} | {
+    type: "SET_BOUNDS";
+    min: number;
+    max: number;
+    step: number;
+} | {
+    type: "SET_DISABLED";
+    disabled: boolean;
 }, {}, never, {
     type: "setValue";
     params: xstate.NonReducibleUnknown;
@@ -51,6 +67,12 @@ declare const sliderMachine: xstate.StateMachine<SliderContext, {
 } | {
     type: "end";
     params: xstate.NonReducibleUnknown;
+} | {
+    type: "setBounds";
+    params: xstate.NonReducibleUnknown;
+} | {
+    type: "setDisabled";
+    params: xstate.NonReducibleUnknown;
 }, {
     type: "notDisabled";
     params: unknown;

package/packages/primitives/dist/machines/slider.js

@@ -2,7 +2,7 @@ import {
   clamp,
   sliderMachine,
   snap
-} from "../chunk-PB3LFHXU.js";
+} from "../chunk-VUPWYBGU.js";
 export {
   clamp as clampSliderValue,
   sliderMachine,

package/packages/primitives/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -1 +1 @@
-{"version":"3.2.4","results":[[":src/machines/dialog.test.ts",{"duration":5.771292000000017,"failed":false}],[":src/machines/select.test.ts",{"duration":6.394416000000035,"failed":false}],[":src/__tests__/dialog.test.ts",{"duration":3.686000000000007,"failed":false}],[":src/__tests__/select.test.ts",{"duration":2.8540000000000134,"failed":false}],[":src/__tests__/floating-surface.test.ts",{"duration":5.357416999999998,"failed":false}],[":src/__tests__/app-nav.test.ts",{"duration":7.012541999999996,"failed":false}],[":src/__tests__/file-upload.test.ts",{"duration":5.016666000000015,"failed":false}],[":src/__tests__/range-slider.test.ts",{"duration":6.245291999999978,"failed":false}]]}
+{"version":"3.2.4","results":[[":src/machines/dialog.test.ts",{"duration":5.771292000000017,"failed":false}],[":src/machines/select.test.ts",{"duration":6.394416000000035,"failed":false}],[":src/__tests__/dialog.test.ts",{"duration":3.686000000000007,"failed":false}],[":src/__tests__/select.test.ts",{"duration":2.8540000000000134,"failed":false}],[":src/__tests__/floating-surface.test.ts",{"duration":13.601374999999962,"failed":false}],[":src/__tests__/app-nav.test.ts",{"duration":9.962167000000022,"failed":false}],[":src/__tests__/file-upload.test.ts",{"duration":13.053917000000013,"failed":false}],[":src/__tests__/range-slider.test.ts",{"duration":13.141374999999982,"failed":false}]]}

package/packages/primitives/src/machines/slider.ts

@@ -15,6 +15,8 @@ export type SliderEvent =
   | { type: 'POINTER_UP' }
   | { type: 'HOME' }
   | { type: 'END' }
+  | { type: 'SET_BOUNDS'; min: number; max: number; step: number }
+  | { type: 'SET_DISABLED'; disabled: boolean }
 
 function clamp(value: number, min: number, max: number) {
   return Math.min(max, Math.max(min, value))
@@ -55,6 +57,15 @@ export const sliderMachine = setup({
     end: assign({
       value: ({ context }) => context.max,
     }),
+    setBounds: assign(({ context, event }) => {
+      if (event.type !== 'SET_BOUNDS') return context
+      const { min, max, step } = event
+      return { ...context, min, max, step, value: snap(context.value, min, max, step) }
+    }),
+    setDisabled: assign({
+      disabled: ({ context, event }) =>
+        event.type === 'SET_DISABLED' ? event.disabled : context.disabled,
+    }),
   },
 }).createMachine({
   id: 'slider',
@@ -66,6 +77,12 @@ export const sliderMachine = setup({
     disabled: input.disabled ?? false,
   }),
   initial: 'interaction',
+  // Bounds and disabled follow the host regardless of interaction state, so a
+  // range that widens (audio duration arriving) stops clamping to stale limits.
+  on: {
+    SET_BOUNDS: { actions: 'setBounds' },
+    SET_DISABLED: { actions: 'setDisabled' },
+  },
   states: {
     interaction: {
       initial: 'idle',

package/packages/react/dist/index.d.ts

@@ -519,7 +519,9 @@ declare const Combobox: {
     Empty: react.ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & react.RefAttributes<HTMLDivElement>>;
 };
 
-type AnchorPlacement = 'bottom-start' | 'top-start';
+type AnchorSide = 'top' | 'bottom';
+type AnchorAlign = 'start' | 'end' | 'center';
+type AnchorPlacement = `${AnchorSide}-${AnchorAlign}`;
 
 interface PopoverRootProps {
     open?: boolean;
@@ -532,6 +534,10 @@ interface PopoverPositionerProps extends HTMLAttributes<HTMLDivElement> {
     /** Mount panel in document.body (default true). */
     portalled?: boolean;
     placement?: AnchorPlacement;
+    /** Gap between trigger and panel (default 4). */
+    gutter?: number;
+    /** Stack level for the portalled surface (default 50). */
+    zIndex?: number;
     children?: ReactNode;
 }
 declare const Popover: {
@@ -554,6 +560,10 @@ interface MenuPositionerProps extends HTMLAttributes<HTMLDivElement> {
     /** Mount menu in document.body (default true). */
     portalled?: boolean;
     placement?: AnchorPlacement;
+    /** Gap between trigger and menu (default 4). */
+    gutter?: number;
+    /** Stack level for the portalled surface (default 50). */
+    zIndex?: number;
     children?: ReactNode;
 }
 interface MenuItemProps extends ButtonHTMLAttributes<HTMLButtonElement> {
@@ -588,6 +598,10 @@ interface TooltipPositionerProps extends HTMLAttributes<HTMLDivElement> {
     /** Mount tooltip in document.body (default true). */
     portalled?: boolean;
     placement?: AnchorPlacement;
+    /** Gap between trigger and tip (default 4). */
+    gutter?: number;
+    /** Stack level for the portalled surface (default 50). */
+    zIndex?: number;
     children?: ReactNode;
 }
 declare const Tooltip: {

package/packages/react/dist/index.js

@@ -2628,20 +2628,35 @@ import { forwardRef as forwardRef23 } from "react";
 
 // src/hooks/use-anchor-position.ts
 import { useEffect as useEffect13 } from "react";
+var DEFAULT_GUTTER = 4;
+var DEFAULT_Z_INDEX = 50;
+var DEFAULT_PADDING = 8;
+function splitPlacement(placement) {
+  const [side, align] = placement.split("-");
+  return [side, align];
+}
 function useAnchorPosition(anchorRef, floatingRef, active, placement = "bottom-start", options = {}) {
-  const { matchWidth = false } = options;
+  const {
+    matchWidth = false,
+    gutter = DEFAULT_GUTTER,
+    zIndex = DEFAULT_Z_INDEX,
+    padding = DEFAULT_PADDING
+  } = options;
   useEffect13(() => {
     if (!active || !anchorRef.current || !floatingRef.current) return;
+    let frame = 0;
     const update = () => {
       const anchor = anchorRef.current;
       const floating = floatingRef.current;
       if (!anchor || !floating) return;
+      const [preferredSide, align] = splitPlacement(placement);
       const rect = anchor.getBoundingClientRect();
+      const viewportWidth = window.innerWidth;
+      const viewportHeight = window.innerHeight;
       floating.style.position = "fixed";
-      floating.style.left = `${rect.left}px`;
       floating.style.bottom = "";
       floating.style.right = "";
-      floating.style.zIndex = "50";
+      floating.style.zIndex = String(zIndex);
       if (matchWidth) {
         floating.style.width = `${rect.width}px`;
         floating.style.minWidth = `${rect.width}px`;
@@ -2649,22 +2664,43 @@ function useAnchorPosition(anchorRef, floatingRef, active, placement = "bottom-s
         floating.style.width = "";
         floating.style.minWidth = "";
       }
-      if (placement === "top-start") {
-        const height = floating.offsetHeight || floating.getBoundingClientRect().height;
-        floating.style.top = `${rect.top - height - 4}px`;
-      } else {
-        floating.style.top = `${rect.bottom + 4}px`;
-      }
+      const width = floating.offsetWidth || floating.getBoundingClientRect().width;
+      const height = floating.offsetHeight || floating.getBoundingClientRect().height;
+      const roomBelow = viewportHeight - rect.bottom - gutter - padding;
+      const roomAbove = rect.top - gutter - padding;
+      const room = preferredSide === "top" ? roomAbove : roomBelow;
+      const side = room >= height ? preferredSide : roomAbove > roomBelow ? "top" : "bottom";
+      const available = side === "top" ? roomAbove : roomBelow;
+      let left = rect.left;
+      if (align === "end") left = rect.right - width;
+      else if (align === "center") left = rect.left + rect.width / 2 - width / 2;
+      const maxLeft = Math.max(padding, viewportWidth - width - padding);
+      left = Math.min(Math.max(padding, left), maxLeft);
+      const top = side === "top" ? Math.max(padding, rect.top - gutter - Math.min(height, Math.max(available, 0))) : Math.min(
+        rect.bottom + gutter,
+        Math.max(padding, viewportHeight - height - padding)
+      );
+      floating.style.left = `${Math.round(left)}px`;
+      floating.style.top = `${Math.round(top)}px`;
+      floating.style.setProperty("--aeon-available-height", `${Math.round(Math.max(available, 0))}px`);
+      floating.style.setProperty("--aeon-anchor-width", `${Math.round(rect.width)}px`);
+      floating.dataset.side = side;
+      floating.dataset.align = align;
+    };
+    const schedule = () => {
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(update);
     };
     update();
-    requestAnimationFrame(update);
-    window.addEventListener("resize", update);
-    window.addEventListener("scroll", update, true);
+    schedule();
+    window.addEventListener("resize", schedule);
+    window.addEventListener("scroll", schedule, true);
     return () => {
-      window.removeEventListener("resize", update);
-      window.removeEventListener("scroll", update, true);
+      cancelAnimationFrame(frame);
+      window.removeEventListener("resize", schedule);
+      window.removeEventListener("scroll", schedule, true);
     };
-  }, [active, anchorRef, floatingRef, placement, matchWidth]);
+  }, [active, anchorRef, floatingRef, placement, matchWidth, gutter, zIndex, padding]);
 }
 
 // src/floating/FloatingPositioner.tsx
@@ -2679,13 +2715,17 @@ var FloatingPositioner = forwardRef23(
     portalled = true,
     placement = "bottom-start",
     matchAnchorWidth = false,
+    gutter,
+    zIndex,
     children,
     className,
     ...rest
   }, ref) {
     const mounted = usePortalledMount();
     useAnchorPosition(triggerRef, positionerRef, open && portalled, placement, {
-      matchWidth: matchAnchorWidth
+      matchWidth: matchAnchorWidth,
+      gutter,
+      zIndex
     });
     if (!open) return null;
     const node = /* @__PURE__ */ jsx23(
@@ -3425,7 +3465,7 @@ var Trigger4 = forwardRef26(function PopoverTrigger({ onClick, ...rest }, ref) {
     }
   );
 });
-var Positioner3 = forwardRef26(function PopoverPositioner({ portalled = true, placement = "bottom-start", children, className, ...rest }, ref) {
+var Positioner3 = forwardRef26(function PopoverPositioner({ portalled = true, placement = "bottom-start", gutter, zIndex, children, className, ...rest }, ref) {
   const { open, triggerRef, positionerRef } = usePopoverCtx();
   return /* @__PURE__ */ jsx26(
     FloatingPositioner,
@@ -3438,6 +3478,8 @@ var Positioner3 = forwardRef26(function PopoverPositioner({ portalled = true, pl
       positionerRef,
       portalled,
       placement,
+      gutter,
+      zIndex,
       className,
       ...rest,
       children
@@ -3583,7 +3625,7 @@ var Trigger5 = forwardRef27(function MenuTrigger({ onClick, ...rest }, ref) {
     }
   );
 });
-var Positioner4 = forwardRef27(function MenuPositioner({ portalled = true, placement = "bottom-start", children, className, ...rest }, ref) {
+var Positioner4 = forwardRef27(function MenuPositioner({ portalled = true, placement = "bottom-start", gutter, zIndex, children, className, ...rest }, ref) {
   const { open, triggerRef, positionerRef } = useMenuCtx();
   return /* @__PURE__ */ jsx27(
     FloatingPositioner,
@@ -3596,6 +3638,8 @@ var Positioner4 = forwardRef27(function MenuPositioner({ portalled = true, place
       positionerRef,
       portalled,
       placement,
+      gutter,
+      zIndex,
       className,
       ...rest,
       children
@@ -3603,14 +3647,36 @@ var Positioner4 = forwardRef27(function MenuPositioner({ portalled = true, place
   );
 });
 var Content7 = forwardRef27(function MenuContent({ onKeyDown, ...rest }, ref) {
-  const { open, send, menuId } = useMenuCtx();
+  const { open, send, menuId, triggerRef } = useMenuCtx();
+  const contentRef = useRef10(null);
+  useEffect17(() => {
+    if (!open) return;
+    const trigger = triggerRef.current;
+    contentRef.current?.focus({ preventScroll: true });
+    return () => {
+      if (trigger?.isConnected) trigger.focus({ preventScroll: true });
+    };
+  }, [open, triggerRef]);
+  useEffect17(() => {
+    if (!open) return;
+    const onDocumentKeyDown = (event) => {
+      if (event.key === "Escape") send({ type: "ESCAPE" });
+    };
+    document.addEventListener("keydown", onDocumentKeyDown);
+    return () => document.removeEventListener("keydown", onDocumentKeyDown);
+  }, [open, send]);
   if (!open) return null;
   return /* @__PURE__ */ jsx27(
     "div",
     {
-      ref,
+      ref: (node) => {
+        contentRef.current = node;
+        if (typeof ref === "function") ref(node);
+        else if (ref) ref.current = node;
+      },
       id: menuId,
       role: "menu",
+      tabIndex: -1,
       ...mergeProps(
         partAttrs23(menuAnatomy.scope, menuAnatomy.content, { state: "open" }),
         {
@@ -3870,7 +3936,7 @@ var Trigger6 = forwardRef28(function TooltipTrigger({ onClick, onMouseEnter, onM
     }
   );
 });
-var Positioner5 = forwardRef28(function TooltipPositioner({ portalled = true, placement = "top-start", children, className, ...rest }, ref) {
+var Positioner5 = forwardRef28(function TooltipPositioner({ portalled = true, placement = "top-start", gutter, zIndex, children, className, ...rest }, ref) {
   const { open, triggerRef, positionerRef } = useTooltipCtx();
   return /* @__PURE__ */ jsx28(
     FloatingPositioner,
@@ -3883,6 +3949,8 @@ var Positioner5 = forwardRef28(function TooltipPositioner({ portalled = true, pl
       positionerRef,
       portalled,
       placement,
+      gutter,
+      zIndex,
       className,
       ...rest,
       children

package/packages/react/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -1 +1 @@
-{"version":"3.2.4","results":[[":src/select/select.test.tsx",{"duration":233.12287500000002,"failed":false}],[":src/dialog/dialog.test.tsx",{"duration":197.85458300000005,"failed":false}],[":src/avatar/avatar.test.tsx",{"duration":175.06837500000006,"failed":false}],[":src/tooltip/tooltip.test.tsx",{"duration":236.69991700000014,"failed":false}],[":src/toast/toast.test.tsx",{"duration":174.01087499999994,"failed":false}]]}
+{"version":"3.2.4","results":[[":src/select/select.test.tsx",{"duration":374.59737499999983,"failed":false}],[":src/dialog/dialog.test.tsx",{"duration":302.22662500000024,"failed":false}],[":src/avatar/avatar.test.tsx",{"duration":222.467666,"failed":false}],[":src/tooltip/tooltip.test.tsx",{"duration":394.93274999999994,"failed":false}],[":src/toast/toast.test.tsx",{"duration":290.9687079999999,"failed":false}]]}

package/packages/react/src/floating/FloatingPositioner.tsx

@@ -13,6 +13,10 @@ export interface FloatingPositionerProps extends HTMLAttributes<HTMLDivElement>
   portalled?: boolean
   placement?: AnchorPlacement
   matchAnchorWidth?: boolean
+  /** Gap between trigger and surface. */
+  gutter?: number
+  /** Stack level for the portalled surface. */
+  zIndex?: number
   children?: ReactNode
 }
 
@@ -27,6 +31,8 @@ export const FloatingPositioner = forwardRef<HTMLDivElement, FloatingPositionerP
       portalled = true,
       placement = 'bottom-start',
       matchAnchorWidth = false,
+      gutter,
+      zIndex,
       children,
       className,
       ...rest
@@ -36,6 +42,8 @@ export const FloatingPositioner = forwardRef<HTMLDivElement, FloatingPositionerP
     const mounted = usePortalledMount()
     useAnchorPosition(triggerRef, positionerRef, open && portalled, placement, {
       matchWidth: matchAnchorWidth,
+      gutter,
+      zIndex,
     })
 
     if (!open) return null

package/packages/react/src/hooks/use-anchor-position.ts

@@ -1,13 +1,38 @@
 import { useEffect, type RefObject } from 'react'
 
-export type AnchorPlacement = 'bottom-start' | 'top-start'
+export type AnchorSide = 'top' | 'bottom'
+export type AnchorAlign = 'start' | 'end' | 'center'
+export type AnchorPlacement = `${AnchorSide}-${AnchorAlign}`
 
 export interface AnchorPositionOptions {
   /** Match floating width to anchor (select listboxes). */
   matchWidth?: boolean
+  /** Gap between anchor and floating surface. */
+  gutter?: number
+  /** Stack level written to the floating surface. */
+  zIndex?: number
+  /** Viewport padding kept clear when flipping and clamping. */
+  padding?: number
 }
 
-/** Pin floating surface to trigger rect (for portalled overlays). */
+const DEFAULT_GUTTER = 4
+const DEFAULT_Z_INDEX = 50
+const DEFAULT_PADDING = 8
+
+function splitPlacement(placement: AnchorPlacement): [AnchorSide, AnchorAlign] {
+  const [side, align] = placement.split('-') as [AnchorSide, AnchorAlign]
+  return [side, align]
+}
+
+/**
+ * Pin floating surface to trigger rect (for portalled overlays).
+ *
+ * Collision aware: the preferred side flips when it has no room, and the
+ * surface is clamped inside the viewport so an end-aligned trigger near an edge
+ * never renders offscreen. The resolved geometry is published as
+ * `data-side` / `data-align` plus `--aeon-available-height` and
+ * `--aeon-anchor-width` so recipes can cap their own scroll area.
+ */
 export function useAnchorPosition(
   anchorRef: RefObject<HTMLElement | null>,
   floatingRef: RefObject<HTMLElement | null>,
@@ -15,22 +40,32 @@ export function useAnchorPosition(
   placement: AnchorPlacement = 'bottom-start',
   options: AnchorPositionOptions = {},
 ) {
-  const { matchWidth = false } = options
+  const {
+    matchWidth = false,
+    gutter = DEFAULT_GUTTER,
+    zIndex = DEFAULT_Z_INDEX,
+    padding = DEFAULT_PADDING,
+  } = options
 
   useEffect(() => {
     if (!active || !anchorRef.current || !floatingRef.current) return
 
+    let frame = 0
+
     const update = () => {
       const anchor = anchorRef.current
       const floating = floatingRef.current
       if (!anchor || !floating) return
 
+      const [preferredSide, align] = splitPlacement(placement)
       const rect = anchor.getBoundingClientRect()
+      const viewportWidth = window.innerWidth
+      const viewportHeight = window.innerHeight
+
       floating.style.position = 'fixed'
-      floating.style.left = `${rect.left}px`
       floating.style.bottom = ''
       floating.style.right = ''
-      floating.style.zIndex = '50'
+      floating.style.zIndex = String(zIndex)
 
       if (matchWidth) {
         floating.style.width = `${rect.width}px`
@@ -40,22 +75,58 @@ export function useAnchorPosition(
         floating.style.minWidth = ''
       }
 
-      if (placement === 'top-start') {
-        const height = floating.offsetHeight || floating.getBoundingClientRect().height
-        floating.style.top = `${rect.top - height - 4}px`
-      } else {
-        floating.style.top = `${rect.bottom + 4}px`
-      }
+      const width = floating.offsetWidth || floating.getBoundingClientRect().width
+      const height = floating.offsetHeight || floating.getBoundingClientRect().height
+
+      const roomBelow = viewportHeight - rect.bottom - gutter - padding
+      const roomAbove = rect.top - gutter - padding
+      const room = preferredSide === 'top' ? roomAbove : roomBelow
+      const side =
+        room >= height
+          ? preferredSide
+          : roomAbove > roomBelow
+            ? 'top'
+            : 'bottom'
+      const available = side === 'top' ? roomAbove : roomBelow
+
+      let left = rect.left
+      if (align === 'end') left = rect.right - width
+      else if (align === 'center') left = rect.left + rect.width / 2 - width / 2
+
+      const maxLeft = Math.max(padding, viewportWidth - width - padding)
+      left = Math.min(Math.max(padding, left), maxLeft)
+
+      const top =
+        side === 'top'
+          ? Math.max(padding, rect.top - gutter - Math.min(height, Math.max(available, 0)))
+          : Math.min(
+              rect.bottom + gutter,
+              Math.max(padding, viewportHeight - height - padding),
+            )
+
+      floating.style.left = `${Math.round(left)}px`
+      floating.style.top = `${Math.round(top)}px`
+      floating.style.setProperty('--aeon-available-height', `${Math.round(Math.max(available, 0))}px`)
+      floating.style.setProperty('--aeon-anchor-width', `${Math.round(rect.width)}px`)
+      floating.dataset.side = side
+      floating.dataset.align = align
+    }
+
+    const schedule = () => {
+      cancelAnimationFrame(frame)
+      frame = requestAnimationFrame(update)
     }
 
     update()
-    requestAnimationFrame(update)
+    // Measure again once the surface has laid out (flip/clamp need real height).
+    schedule()
 
-    window.addEventListener('resize', update)
-    window.addEventListener('scroll', update, true)
+    window.addEventListener('resize', schedule)
+    window.addEventListener('scroll', schedule, true)
     return () => {
-      window.removeEventListener('resize', update)
-      window.removeEventListener('scroll', update, true)
+      cancelAnimationFrame(frame)
+      window.removeEventListener('resize', schedule)
+      window.removeEventListener('scroll', schedule, true)
     }
-  }, [active, anchorRef, floatingRef, placement, matchWidth])
+  }, [active, anchorRef, floatingRef, placement, matchWidth, gutter, zIndex, padding])
 }

package/packages/react/src/menu/index.tsx

@@ -129,11 +129,15 @@ export interface MenuPositionerProps extends HTMLAttributes<HTMLDivElement> {
   /** Mount menu in document.body (default true). */
   portalled?: boolean
   placement?: AnchorPlacement
+  /** Gap between trigger and menu (default 4). */
+  gutter?: number
+  /** Stack level for the portalled surface (default 50). */
+  zIndex?: number
   children?: ReactNode
 }
 
 const Positioner = forwardRef<HTMLDivElement, MenuPositionerProps>(function MenuPositioner(
-  { portalled = true, placement = 'bottom-start', children, className, ...rest },
+  { portalled = true, placement = 'bottom-start', gutter, zIndex, children, className, ...rest },
   ref,
 ) {
   const { open, triggerRef, positionerRef } = useMenuCtx()
@@ -148,6 +152,8 @@ const Positioner = forwardRef<HTMLDivElement, MenuPositionerProps>(function Menu
       positionerRef={positionerRef}
       portalled={portalled}
       placement={placement}
+      gutter={gutter}
+      zIndex={zIndex}
       className={className}
       {...rest}
     >
@@ -160,13 +166,41 @@ const Content = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(funct
   { onKeyDown, ...rest },
   ref,
 ) {
-  const { open, send, menuId } = useMenuCtx()
+  const { open, send, menuId, triggerRef } = useMenuCtx()
+  const contentRef = useRef<HTMLDivElement | null>(null)
+
+  // Focus enters the surface while it is open and returns to the trigger on
+  // dismiss, so keyboard users stay inside the menu they opened.
+  useEffect(() => {
+    if (!open) return
+    const trigger = triggerRef.current
+    contentRef.current?.focus({ preventScroll: true })
+    return () => {
+      if (trigger?.isConnected) trigger.focus({ preventScroll: true })
+    }
+  }, [open, triggerRef])
+
+  // Escape closes wherever focus sits — trigger, item or elsewhere on the page.
+  useEffect(() => {
+    if (!open) return
+    const onDocumentKeyDown = (event: globalThis.KeyboardEvent) => {
+      if (event.key === 'Escape') send({ type: 'ESCAPE' })
+    }
+    document.addEventListener('keydown', onDocumentKeyDown)
+    return () => document.removeEventListener('keydown', onDocumentKeyDown)
+  }, [open, send])
+
   if (!open) return null
   return (
     <div
-      ref={ref}
+      ref={(node) => {
+        contentRef.current = node
+        if (typeof ref === 'function') ref(node)
+        else if (ref) ref.current = node
+      }}
       id={menuId}
       role="menu"
+      tabIndex={-1}
       {...mergeProps(
         partAttrs(menuAnatomy.scope, menuAnatomy.content, { state: 'open' }),
         {

package/packages/react/src/popover/index.tsx

@@ -132,11 +132,15 @@ export interface PopoverPositionerProps extends HTMLAttributes<HTMLDivElement> {
   /** Mount panel in document.body (default true). */
   portalled?: boolean
   placement?: AnchorPlacement
+  /** Gap between trigger and panel (default 4). */
+  gutter?: number
+  /** Stack level for the portalled surface (default 50). */
+  zIndex?: number
   children?: ReactNode
 }
 
 const Positioner = forwardRef<HTMLDivElement, PopoverPositionerProps>(function PopoverPositioner(
-  { portalled = true, placement = 'bottom-start', children, className, ...rest },
+  { portalled = true, placement = 'bottom-start', gutter, zIndex, children, className, ...rest },
   ref,
 ) {
   const { open, triggerRef, positionerRef } = usePopoverCtx()
@@ -151,6 +155,8 @@ const Positioner = forwardRef<HTMLDivElement, PopoverPositionerProps>(function P
       positionerRef={positionerRef}
       portalled={portalled}
       placement={placement}
+      gutter={gutter}
+      zIndex={zIndex}
       className={className}
       {...rest}
     >