@cdx-ui/primitives 0.0.1-beta.159 → 0.0.1-beta.160

package/src/menu/MenuRoot.tsx

@@ -0,0 +1,190 @@
+import {
+  forwardRef,
+  useCallback,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentRef,
+} from 'react';
+import { Platform, View } from 'react-native';
+import { composeEventHandlers, mergeRefs } from '@cdx-ui/utils';
+import { Slot } from '../slot';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import { MenuProvider } from './context';
+import { useOptionalMenuOverlayContext } from './overlayContext';
+import type { IMenuProps, RegisteredMenuItem } from './types';
+import { useMenuNavigation } from './useMenuNavigation';
+import { useMenuOverlayOpenFocus } from './useMenuOverlayLifecycle';
+
+function getItemsInRenderedOrder(
+  items: Map<string, RegisteredMenuItem>,
+): [string, RegisteredMenuItem][] {
+  const entries = Array.from(items.entries());
+  if (Platform.OS !== 'web' || typeof Node === 'undefined') {
+    return entries;
+  }
+
+  return entries.sort(([, first], [, second]) => {
+    const firstNode = first.node as Node | null;
+    const secondNode = second.node as Node | null;
+    if (!firstNode?.compareDocumentPosition || !secondNode) {
+      return 0;
+    }
+
+    const position = firstNode.compareDocumentPosition(secondNode);
+    if (position & Node.DOCUMENT_POSITION_FOLLOWING) {
+      return -1;
+    }
+    if (position & Node.DOCUMENT_POSITION_PRECEDING) {
+      return 1;
+    }
+    return 0;
+  });
+}
+
+export interface MenuRootProps extends IMenuProps {
+  asChild?: boolean;
+  className?: string;
+}
+
+export const MenuRoot = forwardRef<ComponentRef<typeof View>, MenuRootProps>(
+  ({ asChild, children, scrollable, asSurface = false, onEscape, ...props }, ref) => {
+    const overlay = useOptionalMenuOverlayContext();
+
+    const itemsRef = useRef<Map<string, RegisteredMenuItem>>(new Map());
+    const [focusedItemId, setFocusedItemId] = useState<string | undefined>(undefined);
+
+    const registerItem = useCallback(
+      (itemId: string, entry: RegisteredMenuItem) => {
+        itemsRef.current.set(itemId, entry);
+        if (!overlay && !entry.disabled) {
+          setFocusedItemId((previous) => previous ?? itemId);
+        }
+      },
+      [overlay],
+    );
+
+    const unregisterItem = useCallback(
+      (itemId: string) => {
+        itemsRef.current.delete(itemId);
+        setFocusedItemId((previous) => {
+          if (previous !== itemId) {
+            return previous;
+          }
+          if (overlay) {
+            return undefined;
+          }
+          return getItemsInRenderedOrder(itemsRef.current).find(
+            ([, entry]) => !entry.disabled,
+          )?.[0];
+        });
+      },
+      [overlay],
+    );
+
+    const getItems = useCallback(() => getItemsInRenderedOrder(itemsRef.current), []);
+
+    const reactId = useId();
+    const localMenuId = `menu-${reactId}`;
+    const menuId = overlay?.menuId ?? localMenuId;
+
+    const dismissOverlay = useCallback(() => {
+      overlay?.closeMenu('programmatic');
+    }, [overlay]);
+
+    const handleEscape = useCallback(() => {
+      if (overlay) {
+        overlay.closeMenu('escape');
+      }
+      onEscape?.();
+    }, [overlay, onEscape]);
+
+    const handleTab = useCallback(() => {
+      if (!overlay) {
+        return;
+      }
+      if (Platform.OS === 'web') {
+        (overlay.triggerRef.current as { focus?: () => void } | null)?.focus?.();
+      }
+      overlay.closeMenu('tab');
+    }, [overlay]);
+
+    const { handleKeyDown } = useMenuNavigation({
+      getItems,
+      focusedItemId,
+      setFocusedItemId,
+      onEscape: handleEscape,
+      onTab: handleTab,
+    });
+
+    useMenuOverlayOpenFocus({
+      overlay,
+      getItems,
+      setFocusedItemId,
+    });
+
+    const contextValue = useMemo(
+      () => ({
+        menuId,
+        registerItem,
+        unregisterItem,
+        getItems,
+        focusedItemId,
+        setFocusedItemId,
+        onEscape: handleEscape,
+        closeOnSelect: !!overlay,
+        dismissOverlay: overlay?.closeMenu ?? dismissOverlay,
+      }),
+      [
+        menuId,
+        registerItem,
+        unregisterItem,
+        getItems,
+        focusedItemId,
+        setFocusedItemId,
+        handleEscape,
+        overlay,
+        dismissOverlay,
+      ],
+    );
+
+    const webProps =
+      Platform.OS === 'web' && !asSurface
+        ? {
+            onKeyDown: composeEventHandlers(
+              (props as { onKeyDown?: (e: KeyboardEvent) => void }).onKeyDown,
+              handleKeyDown,
+            ),
+            ...(overlay ? { tabIndex: -1 } : {}),
+          }
+        : {};
+
+    const mergedRef = overlay ? mergeRefs(ref, overlay.contentRef) : ref;
+
+    const Comp = asChild ? Slot : View;
+
+    return (
+      <MenuProvider value={contextValue}>
+        <Comp
+          ref={mergedRef}
+          id={overlay && !asSurface ? menuId : undefined}
+          role={asSurface ? undefined : 'menu'}
+          aria-labelledby={overlay && !asSurface ? overlay.triggerId : undefined}
+          {...props}
+          {...webProps}
+          {...mergeDataAttributes(
+            props,
+            dataAttributes({
+              scrollable: scrollable ? true : undefined,
+            }),
+          )}
+        >
+          {children}
+        </Comp>
+      </MenuProvider>
+    );
+  },
+);
+
+MenuRoot.displayName = 'MenuRoot';

package/src/menu/MenuTrigger.tsx

@@ -0,0 +1,57 @@
+import { forwardRef, type ComponentRef, type ForwardedRef, type ReactNode } from 'react';
+import { Pressable } from 'react-native';
+import { Slot } from '../slot';
+import { dataAttributes, mergeDataAttributes } from '../utils/dataAttributes';
+import type { IMenuTriggerProps } from './types';
+import { useMenuTrigger } from './useMenuTrigger';
+
+export interface MenuTriggerProps extends Omit<IMenuTriggerProps, 'children'> {
+  children?: ReactNode;
+}
+
+export const MenuTrigger = forwardRef<ComponentRef<typeof Pressable>, MenuTriggerProps>(
+  ({ asChild, children, onPress, onHoverIn, onHoverOut, onFocus, onBlur, ...rest }, ref) => {
+    const { ariaProps, interactionState, mergedRef, handlers } = useMenuTrigger(
+      ref as ForwardedRef<unknown>,
+      {
+        asChild,
+        onPress,
+        onHoverIn,
+        onHoverOut,
+        onFocus: onFocus as (...args: unknown[]) => unknown,
+        onBlur: onBlur as (...args: unknown[]) => unknown,
+        onKeyDown: (rest as { onKeyDown?: (e: KeyboardEvent) => void }).onKeyDown,
+      },
+    );
+
+    const Comp = asChild ? Slot : Pressable;
+
+    return (
+      <Comp
+        ref={mergedRef}
+        {...ariaProps}
+        {...rest}
+        {...mergeDataAttributes(
+          rest,
+          dataAttributes({
+            slot: 'menu-trigger',
+            hover: interactionState.hover,
+            focus: interactionState.focus,
+            disabled: interactionState.disabled,
+            state: ariaProps['aria-expanded'] ? 'open' : 'closed',
+          }),
+        )}
+        onPress={handlers.onPress}
+        onHoverIn={handlers.onHoverIn}
+        onHoverOut={handlers.onHoverOut}
+        onFocus={handlers.onFocus}
+        onBlur={handlers.onBlur}
+        onKeyDown={handlers.onKeyDown}
+      >
+        {children}
+      </Comp>
+    );
+  },
+);
+
+MenuTrigger.displayName = 'MenuTrigger';

package/src/menu/context.tsx

@@ -0,0 +1,38 @@
+import { createContext as createReactContext, useContext } from 'react';
+import { createContext } from '@cdx-ui/utils';
+import type { MenuContextValue, MenuItemInteractionState } from './types';
+
+export const [MenuProvider, useMenuContext] = createContext<MenuContextValue>('MenuContext');
+
+const MenuItemContext = createReactContext<MenuItemInteractionState | null>(null);
+
+export const MenuItemProvider = MenuItemContext.Provider;
+
+export function useMenuItemContext(): MenuItemInteractionState {
+  const ctx = useContext(MenuItemContext);
+  if (!ctx) {
+    throw new Error('Menu item slot must be used within Menu.Item');
+  }
+  return ctx;
+}
+
+export function useOptionalMenuItemContext(): MenuItemInteractionState | null {
+  return useContext(MenuItemContext);
+}
+
+export interface MenuRadioGroupContextValue {
+  value: string | undefined;
+  setValue: (value: string) => void;
+}
+
+const MenuRadioGroupContext = createReactContext<MenuRadioGroupContextValue | null>(null);
+
+export const MenuRadioGroupProvider = MenuRadioGroupContext.Provider;
+
+export function useMenuRadioGroupContext(): MenuRadioGroupContextValue {
+  const ctx = useContext(MenuRadioGroupContext);
+  if (!ctx) {
+    throw new Error('Menu.RadioItem must be used within Menu.RadioGroup');
+  }
+  return ctx;
+}

package/src/menu/index.ts

@@ -0,0 +1,36 @@
+export type {
+  IMenuCheckboxItemProps,
+  IMenuItemProps,
+  IMenuOverlayRootProps,
+  IMenuPopupProps,
+  IMenuProps,
+  IMenuRadioGroupProps,
+  IMenuRadioItemProps,
+  IMenuTriggerProps,
+  MenuCloseReason,
+  MenuContextValue,
+  MenuItemInteractionState,
+  RegisteredMenuItem,
+} from './types';
+
+export {
+  useMenuContext,
+  useMenuItemContext,
+  useMenuRadioGroupContext,
+  useOptionalMenuItemContext,
+} from './context';
+export {
+  MenuPopupProvider,
+  useMenuOverlayContext,
+  useOptionalMenuPopupContext,
+  useOptionalMenuOverlayContext,
+  MenuOverlayProvider,
+} from './overlayContext';
+export { MenuOverlayRoot, type MenuOverlayRootProps } from './MenuOverlayRoot';
+export { MenuTrigger, type MenuTriggerProps } from './MenuTrigger';
+export { MenuPopup, type MenuPopupProps } from './MenuPopup';
+export { MenuRoot, type MenuRootProps } from './MenuRoot';
+export { MenuItem, type MenuItemProps } from './MenuItem';
+export { MenuCheckboxItem, type MenuCheckboxItemProps } from './MenuCheckboxItem';
+export { MenuRadioGroup, type MenuRadioGroupProps } from './MenuRadioGroup';
+export { MenuRadioItem, type MenuRadioItemProps } from './MenuRadioItem';

package/src/menu/overlayContext.tsx

@@ -0,0 +1,61 @@
+import {
+  createContext as createReactContext,
+  useContext,
+  type MutableRefObject,
+  type RefObject,
+} from 'react';
+import type { View } from 'react-native';
+import type { OverlayPlacement } from '../overlay';
+import type { MenuCloseReason } from './types';
+
+/** Where to place focus when an overlay menu opens. */
+export type MenuFocusOnOpen = 'first' | 'last' | 'menu';
+
+export interface MenuOverlayContextValue {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  closeMenu: (reason?: MenuCloseReason) => void;
+  disabled: boolean;
+  placement: OverlayPlacement;
+  offset: number;
+  crossOffset: number;
+  triggerRef: RefObject<View | null>;
+  triggerId: string;
+  menuId: string;
+  contentRef: RefObject<View | null>;
+  /**
+   * Set by the trigger immediately before `setOpen(true)`.
+   * `'menu'` keeps pointer-opened menus from highlighting the first item.
+   */
+  focusOnOpenRef: MutableRefObject<MenuFocusOnOpen>;
+  closeReasonRef: MutableRefObject<MenuCloseReason>;
+}
+
+const MenuOverlayContext = createReactContext<MenuOverlayContextValue | null>(null);
+
+export const MenuOverlayProvider = MenuOverlayContext.Provider;
+
+export function useMenuOverlayContext(): MenuOverlayContextValue {
+  const ctx = useContext(MenuOverlayContext);
+  if (!ctx) {
+    throw new Error('Menu overlay slot must be used within Menu');
+  }
+  return ctx;
+}
+
+export function useOptionalMenuOverlayContext(): MenuOverlayContextValue | null {
+  return useContext(MenuOverlayContext);
+}
+
+export interface MenuPopupContextValue {
+  availableHeight: number | undefined;
+  availableWidth: number | undefined;
+}
+
+const MenuPopupContext = createReactContext<MenuPopupContextValue | null>(null);
+
+export const MenuPopupProvider = MenuPopupContext.Provider;
+
+export function useOptionalMenuPopupContext(): MenuPopupContextValue | null {
+  return useContext(MenuPopupContext);
+}

package/src/menu/types.ts

@@ -0,0 +1,119 @@
+import type { ReactNode } from 'react';
+import type { PressableProps, ViewProps } from 'react-native';
+import type { OverlayPlacement } from '../overlay';
+import type { InteractionState } from '../types';
+
+export interface IMenuOverlayRootProps extends ViewProps {
+  isOpen?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  disabled?: boolean;
+  /** Preferred popup placement relative to the trigger. */
+  placement?: OverlayPlacement;
+  /** Distance between the trigger and popup in pixels. */
+  offset?: number;
+  /** Cross-axis adjustment from the aligned popup position in pixels. */
+  crossOffset?: number;
+  children?: ReactNode;
+}
+
+export interface IMenuTriggerProps extends PressableProps {
+  asChild?: boolean;
+  children?: ReactNode;
+}
+
+export interface IMenuPopupProps extends ViewProps {
+  children?: ReactNode;
+}
+
+export interface IMenuProps extends ViewProps {
+  /** When true, children are wrapped in a scroll container (styled layer applies max-height). */
+  scrollable?: boolean;
+  /** Called when Escape is pressed on web keyboard navigation. */
+  onEscape?: () => void;
+  /**
+   * Visual-only surface without `role="menu"` or menu keyboard navigation.
+   * Use when embedding inside another collection (e.g. `Select.Content` listbox).
+   */
+  asSurface?: boolean;
+  children?: ReactNode;
+}
+
+export interface IMenuItemProps extends PressableProps {
+  disabled?: boolean;
+  /** Whether activation closes an overlay Menu. Defaults to true for overlay items. */
+  closeOnSelect?: boolean;
+  /** @internal */
+  itemRole?: 'menuitem' | 'menuitemcheckbox' | 'menuitemradio';
+  /** @internal */
+  isChecked?: boolean;
+  /**
+   * @internal
+   */
+  isHovered?: boolean;
+  /**
+   * @internal
+   */
+  isActive?: boolean;
+  /**
+   * @internal
+   */
+  isFocused?: boolean;
+  /**
+   * @internal
+   */
+  isFocusVisible?: boolean;
+  /**
+   * @internal
+   */
+  isDisabled?: boolean;
+}
+
+export interface MenuItemInteractionState extends InteractionState {
+  highlighted: boolean;
+  checked: boolean;
+}
+
+export interface IMenuCheckboxItemProps extends Omit<
+  IMenuItemProps,
+  'children' | 'isChecked' | 'itemRole'
+> {
+  children?: ReactNode;
+  isChecked?: boolean;
+  defaultIsChecked?: boolean;
+  onChange?: (isChecked: boolean) => void;
+}
+
+export interface IMenuRadioGroupProps extends ViewProps {
+  value?: string;
+  defaultValue?: string;
+  onChange?: (value: string) => void;
+}
+
+export interface IMenuRadioItemProps extends Omit<
+  IMenuItemProps,
+  'children' | 'isChecked' | 'itemRole'
+> {
+  children?: ReactNode;
+  value: string;
+}
+
+export interface RegisteredMenuItem {
+  disabled: boolean;
+  node: { focus?: () => void } | null;
+}
+
+export type MenuCloseReason = 'escape' | 'outside' | 'programmatic' | 'select' | 'tab' | 'trigger';
+
+export interface MenuContextValue {
+  menuId: string;
+  registerItem: (itemId: string, entry: RegisteredMenuItem) => void;
+  unregisterItem: (itemId: string) => void;
+  getItems: () => [string, RegisteredMenuItem][];
+  focusedItemId: string | undefined;
+  setFocusedItemId: (itemId: string | undefined) => void;
+  onEscape?: () => void;
+  /** When true, item activation dismisses the overlay menu. */
+  closeOnSelect?: boolean;
+  dismissOverlay?: (reason?: MenuCloseReason) => void;
+}

package/src/menu/useMenuNavigation.ts

@@ -0,0 +1,102 @@
+import { useCallback, useRef } from 'react';
+import type { RegisteredMenuItem } from './types';
+
+// Web-only — native platforms rely on OS-managed sequential focus.
+
+export interface UseMenuNavigationOptions {
+  getItems: () => [string, RegisteredMenuItem][];
+  focusedItemId: string | undefined;
+  setFocusedItemId: (itemId: string | undefined) => void;
+  onEscape?: () => void;
+  onTab?: () => void;
+}
+
+export function useMenuNavigation({
+  getItems,
+  focusedItemId,
+  setFocusedItemId,
+  onEscape,
+  onTab,
+}: UseMenuNavigationOptions) {
+  const onEscapeRef = useRef(onEscape);
+  onEscapeRef.current = onEscape;
+  const onTabRef = useRef(onTab);
+  onTabRef.current = onTab;
+
+  const getEnabledItems = useCallback(
+    () => getItems().filter(([, entry]) => !entry.disabled),
+    [getItems],
+  );
+
+  const moveFocus = useCallback(
+    ([targetId, targetEntry]: [string, RegisteredMenuItem]) => {
+      setFocusedItemId(targetId);
+      targetEntry.node?.focus?.();
+    },
+    [setFocusedItemId],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: { key: string; preventDefault: () => void; stopPropagation?: () => void }) => {
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        e.stopPropagation?.();
+        onEscapeRef.current?.();
+        return;
+      }
+      if (e.key === 'Tab') {
+        onTabRef.current?.();
+        return;
+      }
+
+      const enabledItems = getEnabledItems();
+      if (enabledItems.length === 0) {
+        return;
+      }
+
+      const idx = focusedItemId
+        ? enabledItems.findIndex(([itemId]) => itemId === focusedItemId)
+        : -1;
+
+      switch (e.key) {
+        case 'ArrowDown': {
+          e.preventDefault();
+          if (idx === -1) {
+            moveFocus(enabledItems[0]);
+            break;
+          }
+          moveFocus(enabledItems[idx < enabledItems.length - 1 ? idx + 1 : 0]);
+          break;
+        }
+        case 'ArrowUp': {
+          e.preventDefault();
+          if (idx === -1) {
+            const last = enabledItems.at(-1);
+            if (last) {
+              moveFocus(last);
+            }
+            break;
+          }
+          moveFocus(enabledItems[idx > 0 ? idx - 1 : enabledItems.length - 1]);
+          break;
+        }
+        case 'Home': {
+          e.preventDefault();
+          moveFocus(enabledItems[0]);
+          break;
+        }
+        case 'End': {
+          e.preventDefault();
+          const last = enabledItems.at(-1);
+          if (last) {
+            moveFocus(last);
+          }
+          break;
+        }
+      }
+    },
+    [focusedItemId, getEnabledItems, moveFocus],
+  );
+
+  return { handleKeyDown };
+}

package/src/menu/useMenuOverlayLifecycle.ts

@@ -0,0 +1,77 @@
+import { useEffect, useRef } from 'react';
+import { Platform } from 'react-native';
+import type { MenuOverlayContextValue } from './overlayContext';
+import type { RegisteredMenuItem } from './types';
+
+export interface UseMenuOverlayOpenFocusOptions {
+  overlay: MenuOverlayContextValue | null;
+  getItems: () => [string, RegisteredMenuItem][];
+  setFocusedItemId: (itemId: string | undefined) => void;
+}
+
+function focusDomNode(node: { focus?: () => void } | null | undefined) {
+  if (Platform.OS !== 'web') {
+    return;
+  }
+  requestAnimationFrame(() => {
+    node?.focus?.();
+  });
+}
+
+/**
+ * On open, keyboard-opened menus focus the first or last enabled item;
+ * pointer-opened menus focus the menu container so the first item is not
+ * highlighted until hover or arrow keys.
+ */
+export function useMenuOverlayOpenFocus({
+  overlay,
+  getItems,
+  setFocusedItemId,
+}: UseMenuOverlayOpenFocusOptions) {
+  const open = overlay?.open ?? false;
+
+  useEffect(() => {
+    if (!overlay || !open) {
+      return;
+    }
+
+    const intent = overlay.focusOnOpenRef.current;
+    const enabled = getItems().filter(([, entry]) => !entry.disabled);
+
+    if (intent === 'menu' || enabled.length === 0) {
+      setFocusedItemId(undefined);
+      focusDomNode(overlay.contentRef.current as { focus?: () => void } | null);
+      return;
+    }
+
+    const target = intent === 'last' ? enabled.at(-1) : enabled[0];
+    if (!target) {
+      return;
+    }
+
+    setFocusedItemId(target[0]);
+    focusDomNode(target[1].node);
+  }, [open, getItems, overlay, setFocusedItemId]);
+}
+
+export function useMenuOverlayCloseFocus(overlay: MenuOverlayContextValue) {
+  const { closeReasonRef, open, triggerRef } = overlay;
+  const prevOpenRef = useRef(open);
+
+  useEffect(() => {
+    if (open) {
+      closeReasonRef.current = 'programmatic';
+    } else if (prevOpenRef.current && Platform.OS === 'web') {
+      const shouldRestoreFocus =
+        closeReasonRef.current === 'escape' ||
+        closeReasonRef.current === 'programmatic' ||
+        closeReasonRef.current === 'select';
+
+      if (shouldRestoreFocus) {
+        (triggerRef.current as { focus?: () => void } | null)?.focus?.();
+      }
+    }
+
+    prevOpenRef.current = open;
+  }, [closeReasonRef, open, triggerRef]);
+}