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

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]);
+}

package/src/menu/useMenuTrigger.ts

@@ -0,0 +1,161 @@
+import { useCallback, useMemo, useRef, type ForwardedRef, type RefCallback } from 'react';
+import { type GestureResponderEvent, type PressableProps } from 'react-native';
+import { composeEventHandlers, mergeRefs } from '@cdx-ui/utils';
+import { useFocus } from '@react-native-aria/focus';
+import { useHover } from '@react-native-aria/interactions';
+import type { InteractionState } from '../types';
+import { useMenuOverlayContext } from './overlayContext';
+
+export interface UseMenuTriggerOptions {
+  asChild?: boolean;
+  onPress?: PressableProps['onPress'];
+  onHoverIn?: PressableProps['onHoverIn'];
+  onHoverOut?: PressableProps['onHoverOut'];
+  onFocus?: (...args: unknown[]) => unknown;
+  onBlur?: (...args: unknown[]) => unknown;
+  onKeyDown?: (e: KeyboardEvent) => void;
+}
+
+export interface MenuTriggerAriaProps {
+  role: 'button';
+  id: string;
+  'aria-haspopup': 'menu';
+  'aria-expanded': boolean;
+  'aria-controls': string;
+  disabled: boolean;
+}
+
+export interface UseMenuTriggerReturn {
+  ariaProps: MenuTriggerAriaProps;
+  interactionState: Pick<InteractionState, 'hover' | 'focus' | 'disabled'>;
+  mergedRef: RefCallback<unknown>;
+  handlers: {
+    onPress: (e: GestureResponderEvent) => void;
+    onHoverIn: NonNullable<PressableProps['onHoverIn']>;
+    onHoverOut: NonNullable<PressableProps['onHoverOut']>;
+    onFocus: (...args: unknown[]) => unknown;
+    onBlur: (...args: unknown[]) => unknown;
+    onKeyDown: (e: KeyboardEvent) => void;
+  };
+}
+
+export function useMenuTrigger(
+  forwardedRef: ForwardedRef<unknown>,
+  options: UseMenuTriggerOptions,
+): UseMenuTriggerReturn {
+  const {
+    onPress: consumerOnPress,
+    onHoverIn: consumerOnHoverIn,
+    onHoverOut: consumerOnHoverOut,
+    onFocus: consumerOnFocus,
+    onBlur: consumerOnBlur,
+    onKeyDown: consumerOnKeyDown,
+  } = options;
+
+  const { open, setOpen, closeMenu, disabled, triggerRef, triggerId, menuId, focusOnOpenRef } =
+    useMenuOverlayContext();
+  const pendingKeyboardOpenRef = useRef<'first' | 'last' | null>(null);
+
+  const { isFocused, focusProps } = useFocus();
+  const { isHovered, hoverProps } = useHover();
+  const clearPendingKeyboardOpen = useCallback(() => {
+    pendingKeyboardOpenRef.current = null;
+  }, []);
+
+  const handlePress = useCallback(
+    (_e: GestureResponderEvent) => {
+      if (disabled) {
+        return;
+      }
+
+      if (open) {
+        pendingKeyboardOpenRef.current = null;
+        closeMenu('trigger');
+        return;
+      }
+
+      focusOnOpenRef.current = pendingKeyboardOpenRef.current ?? 'menu';
+      pendingKeyboardOpenRef.current = null;
+      setOpen(true);
+    },
+    [closeMenu, disabled, focusOnOpenRef, open, setOpen],
+  );
+
+  const handleKeyDown = useCallback(
+    (e: KeyboardEvent) => {
+      if (disabled) {
+        return;
+      }
+
+      switch (e.key) {
+        case 'Enter':
+        case ' ': {
+          e.preventDefault();
+          pendingKeyboardOpenRef.current = 'first';
+          break;
+        }
+        case 'ArrowDown': {
+          e.preventDefault();
+          pendingKeyboardOpenRef.current = null;
+          focusOnOpenRef.current = 'first';
+          setOpen(true);
+          break;
+        }
+        case 'ArrowUp': {
+          e.preventDefault();
+          pendingKeyboardOpenRef.current = null;
+          focusOnOpenRef.current = 'last';
+          setOpen(true);
+          break;
+        }
+      }
+    },
+    [disabled, focusOnOpenRef, setOpen],
+  );
+
+  const interactionState = useMemo(
+    () => ({
+      hover: !!isHovered,
+      focus: !!isFocused,
+      disabled: !!disabled,
+    }),
+    [isHovered, isFocused, disabled],
+  );
+
+  const mergedRef = mergeRefs(forwardedRef, triggerRef);
+
+  const ariaProps: MenuTriggerAriaProps = {
+    role: 'button',
+    id: triggerId,
+    'aria-haspopup': 'menu',
+    'aria-expanded': open,
+    'aria-controls': menuId,
+    disabled,
+  };
+
+  const handlers = {
+    onPress: composeEventHandlers(
+      consumerOnPress,
+      handlePress,
+    ) as UseMenuTriggerReturn['handlers']['onPress'],
+    onHoverIn: composeEventHandlers(
+      consumerOnHoverIn,
+      hoverProps.onHoverIn,
+    ) as UseMenuTriggerReturn['handlers']['onHoverIn'],
+    onHoverOut: composeEventHandlers(
+      consumerOnHoverOut,
+      hoverProps.onHoverOut,
+    ) as UseMenuTriggerReturn['handlers']['onHoverOut'],
+    onFocus: composeEventHandlers(consumerOnFocus, focusProps.onFocus),
+    onBlur: composeEventHandlers(
+      composeEventHandlers(consumerOnBlur, focusProps.onBlur),
+      clearPendingKeyboardOpen,
+    ),
+    onKeyDown: composeEventHandlers(
+      consumerOnKeyDown,
+      handleKeyDown,
+    ) as UseMenuTriggerReturn['handlers']['onKeyDown'],
+  };
+
+  return { ariaProps, interactionState, mergedRef, handlers };
+}