@seed-design/react-menu 0.0.0-alpha-20260414104312

package/src/Menu.tsx

@@ -0,0 +1,221 @@
+"use client";
+
+import {
+  FloatingFocusManager,
+  FloatingList,
+  FloatingPortal,
+  useListItem,
+} from "@floating-ui/react";
+import { composeRefs } from "@radix-ui/react-compose-refs";
+import { FocusScope } from "@radix-ui/react-focus-scope";
+import { DismissibleLayer } from "@seed-design/react-dismissible-layer";
+import { mergeProps } from "@seed-design/dom-utils";
+import { Primitive, type PrimitiveProps } from "@seed-design/react-primitive";
+import React, { forwardRef, createContext } from "react";
+import { useMenu, type UseMenuItemProps, type UseMenuProps } from "./useMenu";
+import { MenuProvider, useMenuContext } from "./useMenuContext";
+import { MenuItemProvider } from "./useMenuItemContext";
+
+const MenuGroupLabelIdContext = createContext<string | null>(null);
+
+export interface MenuRootProps extends UseMenuProps {
+  children?: React.ReactNode;
+}
+
+export const MenuRoot = ({
+  open,
+  defaultOpen,
+  onOpenChange,
+  disabled,
+  placement,
+  gutter,
+  overflowPadding,
+  strategy,
+  matchReferenceWidth,
+  children,
+}: MenuRootProps) => {
+  const api = useMenu({
+    open,
+    defaultOpen,
+    onOpenChange,
+    disabled,
+    placement,
+    gutter,
+    overflowPadding,
+    strategy,
+    matchReferenceWidth,
+  });
+
+  return <MenuProvider value={api}>{children}</MenuProvider>;
+};
+
+export interface MenuAnchorProps extends PrimitiveProps, React.HTMLAttributes<HTMLDivElement> {}
+
+export const MenuAnchor = forwardRef<HTMLDivElement, MenuAnchorProps>((props, ref) => {
+  const api = useMenuContext();
+
+  return (
+    <Primitive.div
+      ref={composeRefs(api.refs.anchor, ref)}
+      {...mergeProps(api.anchorProps, props)}
+    />
+  );
+});
+MenuAnchor.displayName = "MenuAnchor";
+
+export interface MenuTriggerProps
+  extends PrimitiveProps,
+    React.ButtonHTMLAttributes<HTMLButtonElement> {}
+
+export const MenuTrigger = forwardRef<HTMLButtonElement, MenuTriggerProps>((props, ref) => {
+  const api = useMenuContext();
+
+  return (
+    <Primitive.button
+      ref={composeRefs(api.refs.trigger, ref)}
+      {...mergeProps(api.triggerProps, props)}
+    />
+  );
+});
+MenuTrigger.displayName = "MenuTrigger";
+
+export interface MenuPositionerProps extends PrimitiveProps, React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * The container element to render the portal into.
+   * @default document.body
+   */
+  container?: React.RefObject<HTMLElement | null>;
+}
+
+export const MenuPositioner = forwardRef<HTMLDivElement, MenuPositionerProps>(
+  ({ container, ...props }, ref) => {
+    const api = useMenuContext();
+
+    // FloatingPortal (not a generic portal) so that FloatingFocusManager
+    // detects the portal context and renders focus-guard sentinels.
+    return (
+      <FloatingPortal root={container ?? undefined}>
+        <Primitive.div
+          ref={composeRefs(api.refs.positioner, ref)}
+          {...mergeProps(api.positionerProps, props)}
+        />
+      </FloatingPortal>
+    );
+  },
+);
+MenuPositioner.displayName = "MenuPositioner";
+
+export interface MenuContentProps extends PrimitiveProps, React.HTMLAttributes<HTMLDivElement> {}
+
+export const MenuContent = forwardRef<HTMLDivElement, MenuContentProps>((props, ref) => {
+  const { floatingContext, contentProps, open, setOpen, elementsRef, labelsRef } = useMenuContext();
+
+  const content = <Primitive.div ref={ref} {...mergeProps(contentProps, props)} />;
+
+  // FloatingFocusManager: handles position-aware initial focus, return focus,
+  // closeOnFocusOut, tab order guards, and useListNavigation coordination.
+  //
+  // FocusScope: participates in Radix's focusScopesStack so that parent
+  // FocusScopes (e.g. Dialog, Drawer) are automatically paused while this
+  // Menu is open. Without this, focus cannot leave a trapped parent scope
+  // to reach Menu content rendered in a Portal.
+  //
+  // FocusScope is conditionally rendered (only when open) because Menu
+  // content is always in the DOM (hidden via data-hidden). If FocusScope
+  // were always mounted, it would register in the stack at page load —
+  // before any Dialog — and could never re-register above a Dialog that
+  // mounts later. Mounting only when open ensures it lands at the top of
+  // the stack, pausing the parent scope.
+  return (
+    <FloatingFocusManager context={floatingContext} disabled={!open} modal={false}>
+      <FloatingList elementsRef={elementsRef} labelsRef={labelsRef}>
+        {/* DismissibleLayer must wrap FocusScope, not the other way around.
+            FocusScope asChild uses Slot to forward tabIndex/onKeyDown/ref to the
+            DOM element; if DismissibleLayer sits between them, those props are
+            swallowed by DismissibleLayer's own destructuring and never reach the DOM. */}
+        <DismissibleLayer
+          enabled={open}
+          pressBehavior="drag"
+          onEscapeKeyDown={(event) => {
+            setOpen(false, { reason: "escapeKeyDown", event });
+          }}
+          onPressOutside={(event) => {
+            setOpen(false, { reason: "interactOutside", event });
+          }}
+          onCascadeDismiss={({ dismissedParent }) => {
+            setOpen(false, { reason: "cascadeDismiss", dismissedParent });
+          }}
+          onFocusOutside={() => {
+            // focus trapping is handled by FloatingFocusManager — nothing to do here
+          }}
+          exclude={(target) => {
+            const reference = floatingContext.refs.reference.current;
+            if (!(reference instanceof HTMLElement)) return false;
+
+            return reference.contains(target);
+          }}
+        >
+          {open ? (
+            <FocusScope
+              asChild
+              trapped={false}
+              loop={false}
+              onMountAutoFocus={(e) => e.preventDefault()}
+              onUnmountAutoFocus={(e) => e.preventDefault()}
+            >
+              {content}
+            </FocusScope>
+          ) : (
+            content
+          )}
+        </DismissibleLayer>
+      </FloatingList>
+    </FloatingFocusManager>
+  );
+});
+MenuContent.displayName = "MenuContent";
+
+export interface MenuItemProps
+  extends UseMenuItemProps,
+    PrimitiveProps,
+    Omit<React.HTMLAttributes<HTMLDivElement>, "onClick"> {}
+
+export const MenuItem = forwardRef<HTMLDivElement, MenuItemProps>(
+  ({ disabled, typeaheadLabel, onClick, ...restProps }, ref) => {
+    const { getItemProps } = useMenuContext();
+    const { ref: listRef, index } = useListItem({ label: typeaheadLabel });
+    const api = getItemProps({ disabled, onClick }, index);
+
+    return (
+      <MenuItemProvider value={api}>
+        <Primitive.div ref={composeRefs(listRef, ref)} {...mergeProps(api.rootProps, restProps)} />
+      </MenuItemProvider>
+    );
+  },
+);
+MenuItem.displayName = "MenuItem";
+
+export interface MenuGroupProps extends PrimitiveProps, React.HTMLAttributes<HTMLDivElement> {}
+
+export const MenuGroup = forwardRef<HTMLDivElement, MenuGroupProps>((props, ref) => {
+  const { getGroupProps } = useMenuContext();
+  const { labelId, rootProps } = getGroupProps();
+
+  return (
+    <MenuGroupLabelIdContext.Provider value={labelId}>
+      <Primitive.div ref={ref} {...mergeProps(rootProps, props)} />
+    </MenuGroupLabelIdContext.Provider>
+  );
+});
+MenuGroup.displayName = "MenuGroup";
+
+export interface MenuGroupLabelProps extends PrimitiveProps, React.HTMLAttributes<HTMLDivElement> {}
+
+export const MenuGroupLabel = forwardRef<HTMLDivElement, MenuGroupLabelProps>((props, ref) => {
+  const { getGroupLabelProps } = useMenuContext();
+  const labelId = React.useContext(MenuGroupLabelIdContext);
+  if (!labelId) throw new Error("MenuGroupLabel must be used within a MenuGroup");
+
+  return <Primitive.div ref={ref} {...mergeProps(getGroupLabelProps(labelId), props)} />;
+});
+MenuGroupLabel.displayName = "MenuGroupLabel";

package/src/index.ts

@@ -0,0 +1,31 @@
+export {
+  MenuRoot,
+  MenuAnchor,
+  MenuTrigger,
+  MenuPositioner,
+  MenuContent,
+  MenuItem,
+  MenuGroup,
+  MenuGroupLabel,
+  type MenuRootProps,
+  type MenuAnchorProps,
+  type MenuTriggerProps,
+  type MenuPositionerProps,
+  type MenuContentProps,
+  type MenuItemProps,
+  type MenuGroupProps,
+  type MenuGroupLabelProps,
+} from "./Menu";
+
+export { useMenuContext, type UseMenuContext } from "./useMenuContext";
+export { useMenuItemContext, type UseMenuItemContext } from "./useMenuItemContext";
+
+export * as Menu from "./Menu.namespace";
+
+export type {
+  UseMenuProps,
+  UseMenuItemProps,
+  // implement when submenu is needed
+  // UseMenuSubmenuTriggerProps,
+  UseMenuReturn,
+} from "./useMenu";

package/src/useMenu.ts

@@ -0,0 +1,411 @@
+"use client";
+
+import {
+  useFloating,
+  autoUpdate,
+  offset,
+  flip,
+  shift,
+  size,
+  useClick,
+  useRole,
+  useListNavigation,
+  useTypeahead,
+  useInteractions,
+  useTransitionStatus,
+  type Placement,
+} from "@floating-ui/react";
+import { useControllableState } from "@seed-design/react-use-controllable-state";
+import { buttonProps, dataAttr, elementProps } from "@seed-design/dom-utils";
+import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+
+const MIN_HEIGHT = 200;
+
+function getTransformOrigin(placement: string) {
+  const [side, align] = placement.split("-");
+  const y = { top: "bottom", bottom: "top", left: "center", right: "center" }[side] ?? "top";
+  const x = { start: "left", end: "right" }[align] ?? "center";
+  return `${x} ${y}`;
+}
+
+interface MenuReasonToDetailMap {
+  trigger: { event: MouseEvent | KeyboardEvent };
+  escapeKeyDown: { event: KeyboardEvent };
+  interactOutside: { event: PointerEvent | TouchEvent };
+  cascadeDismiss: { dismissedParent: HTMLElement };
+  itemClick: { event: MouseEvent };
+}
+
+type MenuChangeDetails = {
+  [R in keyof MenuReasonToDetailMap]: {
+    reason?: R;
+  } & MenuReasonToDetailMap[R];
+}[keyof MenuReasonToDetailMap];
+
+interface UseMenuStateProps {
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean, details?: MenuChangeDetails) => void;
+}
+
+export interface UseMenuProps extends UseMenuStateProps {
+  disabled?: boolean;
+
+  /**
+   * Floating UI placement. @default "bottom"
+   */
+  placement?: Placement;
+
+  /**
+   * Distance between trigger and floating element.
+   * @default 0
+   */
+  gutter?: number;
+
+  /**
+   * Virtual padding around viewport edges.
+   * @default 8
+   */
+  overflowPadding?: number;
+
+  /**
+   * Positioning strategy.
+   * @default "absolute"
+   */
+  strategy?: "absolute" | "fixed";
+
+  /**
+   * Whether the floating element's width should match the reference(trigger/anchor)'s width.
+   * @default false
+   */
+  matchReferenceWidth?: boolean;
+}
+
+export interface UseMenuItemProps {
+  disabled?: boolean;
+  /**
+   * Overrides the text label to use when the item is matched during keyboard text navigation.
+   * Falls back to the element's text content if not provided.
+   */
+  typeaheadLabel?: string;
+
+  // intentionally defined here; onClick is omitted in MenuItemProps since it shouldn't be merged as restProps
+  /**
+   * Called when the item is activated (click or keyboard).
+   * Not called when the item is disabled.
+   */
+  onClick?: React.MouseEventHandler;
+}
+
+// implement when submenu is needed
+// export interface UseMenuSubmenuTriggerProps {
+//   disabled?: boolean;
+//   /**
+//    * Overrides the text label to use when the item is matched during keyboard text navigation.
+//    * Falls back to the element's text content if not provided.
+//    */
+//   typeaheadLabel?: string;
+// }
+
+export type UseMenuReturn = ReturnType<typeof useMenu>;
+
+export type GetItemPropsReturn = ReturnType<UseMenuReturn["getItemProps"]>;
+
+function useMenuState(props: UseMenuStateProps) {
+  const [open = false, setOpenState] = useControllableState<
+    boolean,
+    Parameters<NonNullable<UseMenuStateProps["onOpenChange"]>>[1]
+  >({
+    prop: props.open,
+    defaultProp: props.defaultOpen ?? false,
+    onChange: props.onOpenChange,
+  });
+
+  const [activeIndex, setActiveIndex] = useState<number | null>(null);
+
+  const elementsRef = useRef<(HTMLElement | null)[]>([]);
+  const labelsRef = useRef<(string | null)[]>([]);
+  const triggerRef = useRef<Element | null>(null);
+
+  const groupIndexCounter = useRef(0);
+  groupIndexCounter.current = 0;
+
+  const menuId = useId();
+
+  return {
+    open,
+    setOpenState,
+    activeIndex,
+    setActiveIndex,
+    elementsRef,
+    labelsRef,
+    triggerRef,
+    groupIndexCounter,
+    menuId,
+  };
+}
+
+export function useMenu(props: UseMenuProps) {
+  const {
+    open,
+    setOpenState,
+    activeIndex,
+    setActiveIndex,
+    elementsRef,
+    labelsRef,
+    triggerRef,
+    groupIndexCounter,
+    menuId,
+  } = useMenuState(props);
+
+  const {
+    disabled = false,
+    placement = "bottom",
+    gutter = 8,
+    overflowPadding = 8,
+    strategy = "absolute",
+    matchReferenceWidth = false,
+  } = props;
+
+  const setOpen = useCallback(
+    (nextOpen: boolean, details?: MenuChangeDetails) => {
+      if (disabled && nextOpen) return;
+      setOpenState(nextOpen, details);
+    },
+    [disabled, setOpenState],
+  );
+
+  const handleFloatingOpenChange = useCallback(
+    (nextOpen: boolean, event?: Event, reason?: string) => {
+      if (reason === "click" && event) {
+        // NOTE: floating-ui passes click/mousedown/keydown on "click" reason
+        setOpen(nextOpen, { reason: "trigger", event: event as MouseEvent | KeyboardEvent });
+
+        return;
+      }
+
+      setOpen(nextOpen);
+    },
+    [setOpen],
+  );
+
+  const {
+    refs: floatingRefs,
+    context,
+    floatingStyles,
+  } = useFloating({
+    open,
+    onOpenChange: handleFloatingOpenChange,
+    strategy,
+    placement,
+    middleware: [
+      offset(gutter),
+      size({
+        padding: overflowPadding,
+        apply({ availableHeight, rects, elements }) {
+          elements.floating.style.setProperty(
+            "--seed-menu-available-height",
+            `${Math.max(MIN_HEIGHT, availableHeight)}px`,
+          );
+          if (matchReferenceWidth) {
+            elements.floating.style.setProperty(
+              "--seed-menu-reference-width",
+              `${rects.reference.width}px`,
+            );
+          }
+        },
+      }),
+      flip({ padding: overflowPadding, fallbackStrategy: "initialPlacement" }),
+      shift({ padding: overflowPadding }),
+    ],
+  });
+
+  const { status } = useTransitionStatus(context);
+
+  // Keep autoUpdate alive during exit animation so the positioner
+  // follows the trigger even while the menu is animating out.
+  const mounted = status !== "unmounted";
+
+  useEffect(() => {
+    if (!mounted) return;
+    if (!floatingRefs.reference.current || !floatingRefs.floating.current) return;
+
+    return autoUpdate(
+      floatingRefs.reference.current,
+      floatingRefs.floating.current,
+      context.update,
+    );
+  }, [mounted, floatingRefs.reference, floatingRefs.floating, context]);
+
+  const click = useClick(context, {
+    enabled: !disabled,
+  });
+
+  const role = useRole(context, {
+    role: "menu",
+  });
+
+  const listNavigation = useListNavigation(context, {
+    listRef: elementsRef,
+    activeIndex,
+    onNavigate: setActiveIndex,
+    loop: true,
+    // Hover and focus states should be differentiated; disable focus-on-hover
+    // so that hover styling can be handled separately via CSS :hover.
+    focusItemOnHover: false,
+    // focusItemOnOpen: false,
+  });
+
+  const typeahead = useTypeahead(context, {
+    listRef: labelsRef,
+    activeIndex,
+    onMatch: setActiveIndex,
+  });
+
+  const triggerInteractions = useInteractions([click, role, listNavigation, typeahead]);
+  const anchorInteractions = useInteractions([role, listNavigation, typeahead]);
+
+  const stateProps = useMemo(
+    () =>
+      elementProps({
+        "data-hidden": dataAttr(status === "unmounted"),
+        "data-open": dataAttr(status === "open" || status === "initial"),
+      }),
+    [status],
+  );
+
+  return {
+    open,
+    setOpen,
+    activeIndex,
+    stateProps,
+
+    floatingContext: context,
+    elementsRef,
+    labelsRef,
+
+    refs: {
+      anchor: (node: HTMLElement | null) => {
+        floatingRefs.setReference(node);
+      },
+      trigger: (node: HTMLElement | null) => {
+        floatingRefs.setReference(node);
+        triggerRef.current = node;
+      },
+      positioner: floatingRefs.setFloating,
+    },
+
+    anchorProps: elementProps({
+      "data-open": dataAttr(open),
+      ...anchorInteractions.getReferenceProps(),
+    }),
+
+    triggerProps: buttonProps({
+      "aria-haspopup": "menu",
+      "aria-expanded": open,
+      "data-open": dataAttr(open),
+      ...triggerInteractions.getReferenceProps(),
+    }),
+
+    positionerProps: elementProps({
+      ...stateProps,
+      style: floatingStyles,
+    }),
+
+    contentProps: elementProps({
+      ...stateProps,
+      role: "menu",
+      style: {
+        "--seed-menu-transform-origin": getTransformOrigin(context.placement),
+      } as React.CSSProperties,
+      ...triggerInteractions.getFloatingProps(),
+    }),
+
+    getItemProps: (itemProps: UseMenuItemProps, index: number) => {
+      const isActive = activeIndex === index;
+
+      const itemStateProps = elementProps({
+        // implement when submenu is needed
+        // "data-highlighted": dataAttr(isActive),
+        "data-disabled": dataAttr(itemProps.disabled),
+      });
+
+      return {
+        // implement when submenu is needed
+        // isHighlighted: isActive,
+        isDisabled: itemProps.disabled,
+
+        stateProps: itemStateProps,
+
+        rootProps: elementProps({
+          ...itemStateProps,
+          ...triggerInteractions.getItemProps({
+            onClick(event) {
+              if (itemProps.disabled) return;
+              if (event.defaultPrevented) return;
+              itemProps.onClick?.(event);
+              setOpen(false, { reason: "itemClick", event: event.nativeEvent });
+            },
+            onKeyDown(event) {
+              if (itemProps.disabled) return;
+              if (event.key === "Enter" || event.key === " ") {
+                event.preventDefault();
+
+                if (!(event.currentTarget instanceof HTMLElement)) return;
+
+                event.currentTarget.click();
+              }
+            },
+          }),
+          role: "menuitem",
+          tabIndex: isActive ? 0 : -1,
+          "aria-disabled": itemProps.disabled ? "true" : undefined,
+        }),
+      };
+    },
+
+    // implement when submenu is needed
+    // getSubmenuTriggerProps: (itemProps: UseMenuSubmenuTriggerProps, index: number) => {
+    //   const isActive = activeIndex === index;
+    //
+    //   const itemStateProps = elementProps({
+    //     "data-highlighted": dataAttr(isActive),
+    //     "data-disabled": dataAttr(itemProps.disabled),
+    //   });
+    //
+    //   return {
+    //     isHighlighted: isActive,
+    //     isDisabled: itemProps.disabled,
+    //
+    //     stateProps: itemStateProps,
+    //
+    //     rootProps: elementProps({
+    //       ...itemStateProps,
+    //       ...triggerInteractions.getItemProps(),
+    //       role: "menuitem",
+    //       tabIndex: isActive ? 0 : -1,
+    //       "aria-disabled": itemProps.disabled ? "true" : undefined,
+    //     }),
+    //   };
+    // },
+
+    getGroupProps: () => {
+      const groupIndex = groupIndexCounter.current++;
+      const labelId = `menu:${menuId}:group-${groupIndex}:label`;
+      return {
+        labelId,
+        rootProps: elementProps({
+          role: "group",
+          "aria-labelledby": labelId,
+        }),
+      };
+    },
+
+    getGroupLabelProps: (labelId: string) => {
+      return elementProps({
+        role: "presentation",
+        id: labelId,
+      });
+    },
+  };
+}