@mks2508/mks-ui 0.2.0 → 0.3.1

package/src/react-ui/ui/Menu/index.tsx

@@ -0,0 +1,900 @@
+'use client';
+
+/**
+ * Menu component -- animated dropdown/context menu built on base-ui Menu
+ * with motion transitions, highlight tracking, and the v0.2.0 slot system.
+ *
+ * Provides sub-components for triggers, items, checkbox items, radio groups,
+ * submenus, keyboard shortcut hints, separators, and animated highlights.
+ *
+ * @module @mks2508/mks-ui/react/ui/Menu
+ *
+ * @example
+ * ```tsx
+ * <Menu>
+ *   <MenuTrigger>Open Menu</MenuTrigger>
+ *   <MenuPortal>
+ *     <MenuPositioner sideOffset={8}>
+ *       <MenuPopup className="rounded-lg border bg-zinc-900 p-1 shadow-xl">
+ *         <MenuHighlight className="rounded-md bg-white/10" />
+ *         <MenuHighlightItem>
+ *           <MenuItem id="edit">Edit</MenuItem>
+ *         </MenuHighlightItem>
+ *         <MenuSeparator className="my-1 border-white/10" />
+ *         <MenuHighlightItem>
+ *           <MenuItem id="delete">Delete</MenuItem>
+ *         </MenuHighlightItem>
+ *       </MenuPopup>
+ *     </MenuPositioner>
+ *   </MenuPortal>
+ * </Menu>
+ * ```
+ */
+
+import * as React from 'react';
+import { Menu as MenuPrimitive } from '@base-ui/react/menu';
+import { AnimatePresence, motion } from 'motion/react';
+
+import {
+  Highlight,
+  HighlightItem,
+} from '@/react-ui/primitives/Highlight';
+import { getStrictContext } from '@/react-ui/lib/get-strict-context';
+import { useControlledState } from '@/react-ui/hooks/State/UseControlledState';
+import { useDataState } from '@/react-ui/hooks/State/UseDataState';
+import { cn } from '@/react-ui/lib/utils';
+import { menuStyles } from './Menu.styles';
+
+import type {
+  MenuActiveValueContextType,
+  MenuContextType,
+  IMenuProps,
+  IMenuTriggerProps,
+  IMenuPortalProps,
+  IMenuGroupProps,
+  IMenuGroupLabelProps,
+  IMenuSubmenuProps,
+  IMenuSubmenuTriggerProps,
+  IMenuHighlightProps,
+  IMenuHighlightItemProps,
+  IMenuPositionerProps,
+  IMenuPopupProps,
+  IMenuItemProps,
+  IMenuCheckboxItemProps,
+  IMenuCheckboxItemIndicatorProps,
+  IMenuRadioGroupProps,
+  IMenuRadioItemProps,
+  IMenuRadioItemIndicatorProps,
+  IMenuShortcutProps,
+  IMenuArrowProps,
+  IMenuSeparatorProps,
+} from './Menu.types';
+
+// ---------------------------------------------------------------------------
+// Context
+// ---------------------------------------------------------------------------
+
+const [MenuActiveValueProvider, useMenuActiveValue] =
+  getStrictContext<MenuActiveValueContextType>('MenuActiveValueContext');
+
+const [MenuProvider, useMenu] =
+  getStrictContext<MenuContextType>('MenuContext');
+
+// ---------------------------------------------------------------------------
+// Menu (Root)
+// ---------------------------------------------------------------------------
+
+/**
+ * Root Menu component -- provides open/close state and highlighted-value context.
+ * Wraps base-ui Menu.Root with controlled state management.
+ *
+ * @param open - Controlled open state
+ * @param defaultOpen - Uncontrolled initial open state
+ * @param onOpenChange - Callback when open state changes
+ * @param slots - Partial class overrides per slot
+ * @param config - Menu behavior / animation configuration
+ *
+ * @example
+ * ```tsx
+ * <Menu slots={{ popup: 'bg-zinc-900' }}>
+ *   <MenuTrigger>Actions</MenuTrigger>
+ *   <MenuPortal>...</MenuPortal>
+ * </Menu>
+ * ```
+ */
+function Menu({ slots, config, ...props }: IMenuProps) {
+  const [isOpen, setIsOpen] = useControlledState({
+    value: props?.open,
+    defaultValue: props?.defaultOpen,
+    onChange: props?.onOpenChange,
+  });
+  const [highlightedValue, setHighlightedValue] = React.useState<string | null>(
+    null,
+  );
+
+  return (
+    <MenuActiveValueProvider value={{ highlightedValue, setHighlightedValue }}>
+      <MenuProvider value={{ isOpen, setIsOpen }}>
+        <MenuPrimitive.Root
+          data-slot="menu"
+          {...props}
+          onOpenChange={setIsOpen}
+        />
+      </MenuProvider>
+    </MenuActiveValueProvider>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// MenuTrigger
+// ---------------------------------------------------------------------------
+
+/**
+ * MenuTrigger -- the interactive element that toggles the menu open/closed.
+ * Renders a base-ui Menu.Trigger with the `trigger` slot classes.
+ *
+ * @param slots - Partial class overrides per slot
+ * @param className - Additional class names
+ *
+ * @example
+ * ```tsx
+ * <MenuTrigger className="rounded-md px-3 py-1.5">
+ *   Open Menu
+ * </MenuTrigger>
+ * ```
+ */
+function MenuTrigger({ slots, className, ...props }: IMenuTriggerProps) {
+  return (
+    <MenuPrimitive.Trigger
+      data-slot="menu-trigger"
+      className={cn(menuStyles.trigger, slots?.trigger, className)}
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// MenuPortal
+// ---------------------------------------------------------------------------
+
+/**
+ * MenuPortal -- wraps menu content in a portal with AnimatePresence.
+ * Internally keeps the portal mounted and uses AnimatePresence for
+ * smooth enter/exit transitions of children.
+ *
+ * @example
+ * ```tsx
+ * <MenuPortal>
+ *   <MenuPositioner>
+ *     <MenuPopup>...</MenuPopup>
+ *   </MenuPositioner>
+ * </MenuPortal>
+ * ```
+ */
+function MenuPortal(props: IMenuPortalProps) {
+  const { isOpen } = useMenu();
+
+  return (
+    <AnimatePresence>
+      {isOpen && (
+        <MenuPrimitive.Portal keepMounted data-slot="menu-portal" {...props} />
+      )}
+    </AnimatePresence>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// MenuGroup
+// ---------------------------------------------------------------------------
+
+/**
+ * MenuGroup -- logical grouping of related menu items.
+ * Renders a base-ui Menu.Group with the `group` slot classes.
+ *
+ * @param slots - Partial class overrides per slot
+ * @param className - Additional class names
+ *
+ * @example
+ * ```tsx
+ * <MenuGroup>
+ *   <MenuGroupLabel>Editing</MenuGroupLabel>
+ *   <MenuItem id="cut">Cut</MenuItem>
+ *   <MenuItem id="copy">Copy</MenuItem>
+ * </MenuGroup>
+ * ```
+ */
+function MenuGroup({ slots, className, ...props }: IMenuGroupProps) {
+  return (
+    <MenuPrimitive.Group
+      data-slot="menu-group"
+      className={cn(menuStyles.group, slots?.group, className)}
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// MenuGroupLabel
+// ---------------------------------------------------------------------------
+
+/**
+ * MenuGroupLabel -- heading text for a MenuGroup.
+ * Renders a base-ui Menu.GroupLabel with the `groupLabel` slot classes.
+ *
+ * @param slots - Partial class overrides per slot
+ * @param className - Additional class names
+ *
+ * @example
+ * ```tsx
+ * <MenuGroupLabel className="text-xs font-medium uppercase tracking-wider">
+ *   Navigation
+ * </MenuGroupLabel>
+ * ```
+ */
+function MenuGroupLabel({ slots, className, ...props }: IMenuGroupLabelProps) {
+  return (
+    <MenuPrimitive.GroupLabel
+      data-slot="menu-group-label"
+      className={cn(menuStyles.groupLabel, slots?.groupLabel, className)}
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// MenuSubmenu
+// ---------------------------------------------------------------------------
+
+/**
+ * MenuSubmenu -- a nested sub-menu with its own open/close state.
+ * Wraps base-ui Menu.SubmenuRoot and provides a scoped MenuProvider.
+ *
+ * @param open - Controlled open state
+ * @param defaultOpen - Uncontrolled initial open state
+ * @param onOpenChange - Callback when open state changes
+ *
+ * @example
+ * ```tsx
+ * <MenuSubmenu>
+ *   <MenuSubmenuTrigger>More Actions</MenuSubmenuTrigger>
+ *   <MenuPortal>
+ *     <MenuPositioner>
+ *       <MenuPopup>
+ *         <MenuItem id="archive">Archive</MenuItem>
+ *       </MenuPopup>
+ *     </MenuPositioner>
+ *   </MenuPortal>
+ * </MenuSubmenu>
+ * ```
+ */
+function MenuSubmenu(props: IMenuSubmenuProps) {
+  const [isOpen, setIsOpen] = useControlledState({
+    value: props?.open,
+    defaultValue: props?.defaultOpen,
+    onChange: props?.onOpenChange,
+  });
+
+  return (
+    <MenuProvider value={{ isOpen, setIsOpen }}>
+      <MenuPrimitive.SubmenuRoot
+        data-slot="menu-submenu"
+        {...props}
+        onOpenChange={setIsOpen}
+      />
+    </MenuProvider>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// MenuSubmenuTrigger
+// ---------------------------------------------------------------------------
+
+/**
+ * MenuSubmenuTrigger -- the item that opens a submenu on hover/focus.
+ * Tracks its own highlighted state via useDataState for highlight integration.
+ *
+ * @param label - Accessible label for the trigger
+ * @param id - Unique identifier used for highlight tracking
+ * @param disabled - Whether the trigger is disabled
+ * @param slots - Partial class overrides per slot
+ * @param className - Additional class names
+ *
+ * @example
+ * ```tsx
+ * <MenuSubmenuTrigger id="more" label="More actions">
+ *   More...
+ * </MenuSubmenuTrigger>
+ * ```
+ */
+function MenuSubmenuTrigger({
+  label,
+  id,
+  nativeButton,
+  slots,
+  className,
+  ...props
+}: IMenuSubmenuTriggerProps) {
+  const { setHighlightedValue } = useMenuActiveValue();
+  const [, highlightedRef] = useDataState<HTMLDivElement>(
+    'highlighted',
+    undefined,
+    (value) => {
+      if (value === true) {
+        const el = highlightedRef.current;
+        const v = el?.dataset.value || el?.id || null;
+        if (v) setHighlightedValue(v);
+      }
+    },
+  );
+
+  return (
+    <MenuPrimitive.SubmenuTrigger
+      ref={highlightedRef}
+      label={label}
+      id={id}
+      nativeButton={nativeButton}
+      data-slot="menu-submenu-trigger"
+      className={cn(menuStyles.submenuTrigger, slots?.submenuTrigger, className)}
+      {...(props as any)}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// MenuHighlight
+// ---------------------------------------------------------------------------
+
+/**
+ * MenuHighlight -- animated background that follows the currently
+ * focused/highlighted menu item. Wraps the Highlight primitive with
+ * menu-specific defaults (spring transition, no click activation).
+ *
+ * @param transition - Motion transition config (default: spring 350/35)
+ * @param animateOnHover - Whether to activate on hover
+ * @param slots - Partial class overrides per slot
+ * @param className - Additional class names
+ *
+ * @example
+ * ```tsx
+ * <MenuHighlight className="rounded-md bg-white/10" />
+ * ```
+ */
+function MenuHighlight({
+  transition = { type: 'spring', stiffness: 350, damping: 35 },
+  slots,
+  className,
+  ...props
+}: IMenuHighlightProps) {
+  const { highlightedValue } = useMenuActiveValue();
+
+  return (
+    <Highlight
+      data-slot="menu-highlight"
+      click={false}
+      controlledItems
+      transition={transition}
+      value={highlightedValue}
+      className={cn(menuStyles.highlight, slots?.highlight, className)}
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// MenuHighlightItem
+// ---------------------------------------------------------------------------
+
+/**
+ * MenuHighlightItem -- wraps a MenuItem for highlight position tracking.
+ * Must be placed inside a MenuHighlight context.
+ *
+ * @param slots - Partial class overrides per slot
+ *
+ * @example
+ * ```tsx
+ * <MenuHighlight className="rounded bg-white/10">
+ *   <MenuHighlightItem>
+ *     <MenuItem id="edit">Edit</MenuItem>
+ *   </MenuHighlightItem>
+ * </MenuHighlight>
+ * ```
+ */
+function MenuHighlightItem({ slots, ...props }: IMenuHighlightItemProps) {
+  return <HighlightItem data-slot="menu-highlight-item" {...props} />;
+}
+
+// ---------------------------------------------------------------------------
+// MenuPositioner
+// ---------------------------------------------------------------------------
+
+/**
+ * MenuPositioner -- positions the popup relative to the trigger element.
+ * Thin wrapper over base-ui Menu.Positioner.
+ *
+ * @param sideOffset - Gap between trigger and popup
+ * @param align - Alignment along the trigger edge
+ *
+ * @example
+ * ```tsx
+ * <MenuPositioner sideOffset={8} align="start">
+ *   <MenuPopup>...</MenuPopup>
+ * </MenuPositioner>
+ * ```
+ */
+function MenuPositioner(props: IMenuPositionerProps) {
+  return <MenuPrimitive.Positioner data-slot="menu-positioner" {...props} />;
+}
+
+// ---------------------------------------------------------------------------
+// MenuPopup
+// ---------------------------------------------------------------------------
+
+/**
+ * MenuPopup -- the visible flyout surface containing menu items.
+ * Uses Motion for animated entrance (scale + opacity) and exit.
+ *
+ * @param transition - Motion transition config (default: 0.2s duration)
+ * @param slots - Partial class overrides per slot
+ * @param className - Additional class names
+ * @param style - Inline styles merged with will-change hint
+ *
+ * @example
+ * ```tsx
+ * <MenuPopup className="min-w-[180px] rounded-lg border bg-zinc-900 p-1 shadow-xl">
+ *   <MenuItem id="edit">Edit</MenuItem>
+ *   <MenuItem id="delete">Delete</MenuItem>
+ * </MenuPopup>
+ * ```
+ */
+function MenuPopup({
+  finalFocus,
+  id,
+  transition = { duration: 0.2 },
+  style,
+  slots,
+  className,
+  ...props
+}: IMenuPopupProps) {
+  return (
+    <MenuPrimitive.Popup
+      finalFocus={finalFocus}
+      id={id}
+      render={
+        <motion.div
+          key="menu-popup"
+          data-slot="menu-popup"
+          initial={{ opacity: 0, scale: 0.95 }}
+          animate={{ opacity: 1, scale: 1 }}
+          exit={{ opacity: 0, scale: 0.95 }}
+          transition={transition}
+          style={{ willChange: 'opacity, transform', ...style }}
+          className={cn(menuStyles.popup, slots?.popup, className)}
+          {...(props as any)}
+        />
+      }
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// MenuItem
+// ---------------------------------------------------------------------------
+
+/**
+ * MenuItem -- a single actionable row within the menu.
+ * Tracks highlight state via useDataState for animated highlight integration.
+ *
+ * @param id - Unique identifier, also used as highlight tracking value
+ * @param label - Accessible label
+ * @param disabled - Whether the item is disabled
+ * @param closeOnClick - Close menu when this item is clicked
+ * @param slots - Partial class overrides per slot
+ * @param className - Additional class names
+ *
+ * @example
+ * ```tsx
+ * <MenuItem id="edit" label="Edit document">
+ *   <PencilIcon className="mr-2 size-4" />
+ *   Edit
+ *   <MenuShortcut>Ctrl+E</MenuShortcut>
+ * </MenuItem>
+ * ```
+ */
+function MenuItem({
+  disabled,
+  label,
+  closeOnClick,
+  nativeButton,
+  id,
+  slots,
+  className,
+  ...props
+}: IMenuItemProps) {
+  const { setHighlightedValue } = useMenuActiveValue();
+  const [, highlightedRef] = useDataState<HTMLDivElement>(
+    'highlighted',
+    undefined,
+    (value) => {
+      if (value === true) {
+        const el = highlightedRef.current;
+        const v = el?.dataset.value || el?.id || null;
+        if (v) setHighlightedValue(v);
+      }
+    },
+  );
+
+  return (
+    <MenuPrimitive.Item
+      ref={highlightedRef}
+      label={label}
+      closeOnClick={closeOnClick}
+      nativeButton={nativeButton}
+      disabled={disabled}
+      id={id}
+      data-slot="menu-item"
+      className={cn(menuStyles.item, slots?.item, className)}
+      {...(props as any)}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// MenuCheckboxItem
+// ---------------------------------------------------------------------------
+
+/**
+ * MenuCheckboxItem -- a toggleable checkbox item within the menu.
+ * Tracks highlight state for animated highlight integration.
+ *
+ * @param checked - Controlled checked state
+ * @param defaultChecked - Uncontrolled initial checked state
+ * @param onCheckedChange - Callback when checked state changes
+ * @param disabled - Whether the item is disabled
+ * @param slots - Partial class overrides per slot
+ * @param className - Additional class names
+ *
+ * @example
+ * ```tsx
+ * <MenuCheckboxItem checked={showGrid} onCheckedChange={setShowGrid}>
+ *   <MenuCheckboxItemIndicator>
+ *     <CheckIcon />
+ *   </MenuCheckboxItemIndicator>
+ *   Show Grid
+ * </MenuCheckboxItem>
+ * ```
+ */
+function MenuCheckboxItem({
+  label,
+  defaultChecked,
+  checked,
+  onCheckedChange,
+  disabled,
+  closeOnClick,
+  nativeButton,
+  id,
+  slots,
+  className,
+  ...props
+}: IMenuCheckboxItemProps) {
+  const { setHighlightedValue } = useMenuActiveValue();
+  const [, highlightedRef] = useDataState<HTMLDivElement>(
+    'highlighted',
+    undefined,
+    (value) => {
+      if (value === true) {
+        const el = highlightedRef.current;
+        const v = el?.dataset.value || el?.id || null;
+        if (v) setHighlightedValue(v);
+      }
+    },
+  );
+
+  return (
+    <MenuPrimitive.CheckboxItem
+      ref={highlightedRef}
+      label={label}
+      checked={checked}
+      defaultChecked={defaultChecked}
+      onCheckedChange={onCheckedChange}
+      disabled={disabled}
+      closeOnClick={closeOnClick}
+      nativeButton={nativeButton}
+      id={id}
+      data-slot="menu-checkbox-item"
+      className={cn(menuStyles.checkboxItem, slots?.checkboxItem, className)}
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// MenuCheckboxItemIndicator
+// ---------------------------------------------------------------------------
+
+/**
+ * MenuCheckboxItemIndicator -- the visual check/indeterminate icon.
+ * Renders via a motion.div for animated enter/exit transitions.
+ *
+ * @param keepMounted - Keep in DOM when unchecked (for exit animations)
+ *
+ * @example
+ * ```tsx
+ * <MenuCheckboxItemIndicator
+ *   initial={{ opacity: 0, scale: 0.8 }}
+ *   animate={{ opacity: 1, scale: 1 }}
+ * >
+ *   <CheckIcon className="size-4" />
+ * </MenuCheckboxItemIndicator>
+ * ```
+ */
+function MenuCheckboxItemIndicator({
+  keepMounted,
+  ...props
+}: IMenuCheckboxItemIndicatorProps) {
+  return (
+    <MenuPrimitive.CheckboxItemIndicator
+      data-slot="menu-checkbox-item-indicator"
+      keepMounted={keepMounted}
+      render={
+        <motion.div data-slot="menu-checkbox-item-indicator" {...(props as any)} />
+      }
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// MenuRadioGroup
+// ---------------------------------------------------------------------------
+
+/**
+ * MenuRadioGroup -- groups radio items for single-selection within a menu.
+ * Wraps base-ui Menu.RadioGroup.
+ *
+ * @param value - Controlled selected value
+ * @param defaultValue - Uncontrolled initial selected value
+ * @param onValueChange - Callback when selection changes
+ *
+ * @example
+ * ```tsx
+ * <MenuRadioGroup value={sortBy} onValueChange={setSortBy}>
+ *   <MenuRadioItem value="name">Name</MenuRadioItem>
+ *   <MenuRadioItem value="date">Date</MenuRadioItem>
+ *   <MenuRadioItem value="size">Size</MenuRadioItem>
+ * </MenuRadioGroup>
+ * ```
+ */
+function MenuRadioGroup(props: IMenuRadioGroupProps) {
+  return <MenuPrimitive.RadioGroup data-slot="menu-radio-group" {...props} />;
+}
+
+// ---------------------------------------------------------------------------
+// MenuRadioItem
+// ---------------------------------------------------------------------------
+
+/**
+ * MenuRadioItem -- a single option within a MenuRadioGroup.
+ * Tracks highlight state for animated highlight integration.
+ *
+ * @param value - The value this item represents
+ * @param disabled - Whether the item is disabled
+ * @param label - Accessible label
+ * @param slots - Partial class overrides per slot
+ * @param className - Additional class names
+ *
+ * @example
+ * ```tsx
+ * <MenuRadioItem value="name">
+ *   <MenuRadioItemIndicator>
+ *     <DotIcon />
+ *   </MenuRadioItemIndicator>
+ *   Sort by Name
+ * </MenuRadioItem>
+ * ```
+ */
+function MenuRadioItem({
+  value,
+  disabled,
+  label,
+  closeOnClick,
+  nativeButton,
+  id,
+  slots,
+  className,
+  ...props
+}: IMenuRadioItemProps) {
+  const { setHighlightedValue } = useMenuActiveValue();
+  const [, highlightedRef] = useDataState<HTMLDivElement>(
+    'highlighted',
+    undefined,
+    (value) => {
+      if (value === true) {
+        const el = highlightedRef.current;
+        const v = el?.dataset.value || el?.id || null;
+        if (v) setHighlightedValue(v);
+      }
+    },
+  );
+
+  return (
+    <MenuPrimitive.RadioItem
+      ref={highlightedRef}
+      value={value}
+      disabled={disabled}
+      label={label}
+      closeOnClick={closeOnClick}
+      nativeButton={nativeButton}
+      id={id}
+      data-slot="menu-radio-item"
+      className={cn(menuStyles.radioItem, slots?.radioItem, className)}
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// MenuRadioItemIndicator
+// ---------------------------------------------------------------------------
+
+/**
+ * MenuRadioItemIndicator -- the selection dot/icon for a radio item.
+ * Renders via a motion.div for animated enter/exit transitions.
+ *
+ * @param keepMounted - Keep in DOM when unselected (for exit animations)
+ *
+ * @example
+ * ```tsx
+ * <MenuRadioItemIndicator
+ *   initial={{ opacity: 0 }}
+ *   animate={{ opacity: 1 }}
+ * >
+ *   <DotFilledIcon className="size-4" />
+ * </MenuRadioItemIndicator>
+ * ```
+ */
+function MenuRadioItemIndicator({
+  keepMounted,
+  ...props
+}: IMenuRadioItemIndicatorProps) {
+  return (
+    <MenuPrimitive.RadioItemIndicator
+      data-slot="menu-radio-item-indicator"
+      keepMounted={keepMounted}
+      render={<motion.div data-slot="menu-radio-item-indicator" {...(props as any)} />}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// MenuShortcut
+// ---------------------------------------------------------------------------
+
+/**
+ * MenuShortcut -- displays a keyboard shortcut hint aligned to the right.
+ * Renders a plain `<span>` with the `shortcut` slot classes.
+ *
+ * @param slots - Partial class overrides per slot
+ * @param className - Additional class names
+ *
+ * @example
+ * ```tsx
+ * <MenuItem id="copy">
+ *   Copy
+ *   <MenuShortcut>Ctrl+C</MenuShortcut>
+ * </MenuItem>
+ * ```
+ */
+function MenuShortcut({ slots, className, ...props }: IMenuShortcutProps) {
+  return (
+    <span
+      data-slot="menu-shortcut"
+      className={cn(menuStyles.shortcut, slots?.shortcut, className)}
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// MenuArrow
+// ---------------------------------------------------------------------------
+
+/**
+ * MenuArrow -- the directional caret/arrow on the popup edge.
+ * Wraps base-ui Menu.Arrow.
+ *
+ * @example
+ * ```tsx
+ * <MenuPopup>
+ *   <MenuArrow className="fill-zinc-800" />
+ *   <MenuItem id="edit">Edit</MenuItem>
+ * </MenuPopup>
+ * ```
+ */
+function MenuArrow(props: IMenuArrowProps) {
+  return <MenuPrimitive.Arrow data-slot="menu-arrow" {...props} />;
+}
+
+// ---------------------------------------------------------------------------
+// MenuSeparator
+// ---------------------------------------------------------------------------
+
+/**
+ * MenuSeparator -- a horizontal divider between menu items or groups.
+ * Renders a base-ui Menu.Separator with the `separator` slot classes.
+ *
+ * @param slots - Partial class overrides per slot
+ * @param className - Additional class names
+ *
+ * @example
+ * ```tsx
+ * <MenuItem id="edit">Edit</MenuItem>
+ * <MenuSeparator className="my-1 h-px bg-white/10" />
+ * <MenuItem id="delete">Delete</MenuItem>
+ * ```
+ */
+function MenuSeparator({ slots, className, ...props }: IMenuSeparatorProps) {
+  return (
+    <MenuPrimitive.Separator
+      data-slot="menu-separator"
+      className={cn(menuStyles.separator, slots?.separator, className)}
+      {...props}
+    />
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+export {
+  Menu,
+  MenuTrigger,
+  MenuPortal,
+  MenuPositioner,
+  MenuPopup,
+  MenuArrow,
+  MenuItem,
+  MenuCheckboxItem,
+  MenuCheckboxItemIndicator,
+  MenuRadioGroup,
+  MenuRadioItem,
+  MenuRadioItemIndicator,
+  MenuGroup,
+  MenuGroupLabel,
+  MenuSeparator,
+  MenuShortcut,
+  MenuHighlight,
+  MenuHighlightItem,
+  MenuSubmenu,
+  MenuSubmenuTrigger,
+  useMenuActiveValue,
+  useMenu,
+};
+
+// Re-export all types
+export type {
+  IMenuProps,
+  IMenuTriggerProps,
+  IMenuPortalProps,
+  IMenuPositionerProps,
+  IMenuPopupProps,
+  IMenuArrowProps,
+  IMenuItemProps,
+  IMenuCheckboxItemProps,
+  IMenuCheckboxItemIndicatorProps,
+  IMenuRadioItemProps,
+  IMenuRadioItemIndicatorProps,
+  IMenuRadioGroupProps,
+  IMenuGroupProps,
+  IMenuGroupLabelProps,
+  IMenuSeparatorProps,
+  IMenuShortcutProps,
+  IMenuHighlightProps,
+  IMenuHighlightItemProps,
+  IMenuSubmenuProps,
+  IMenuSubmenuTriggerProps,
+  IMenuConfig,
+  MenuActiveValueContextType,
+  MenuContextType,
+} from './Menu.types';
+
+export type { MenuSlot } from './Menu.styles';