@react-aria/menu 3.0.0-alpha.1 → 3.0.0-nightly-4980928d3-240906

package/package.json

@@ -1,37 +1,47 @@
 {
   "name": "@react-aria/menu",
-  "version": "3.0.0-alpha.1",
+  "version": "3.0.0-nightly-4980928d3-240906",
   "description": "Spectrum UI components in React",
   "license": "Apache-2.0",
   "main": "dist/main.js",
   "module": "dist/module.js",
+  "exports": {
+    "types": "./dist/types.d.ts",
+    "import": "./dist/import.mjs",
+    "require": "./dist/main.js"
+  },
   "types": "dist/types.d.ts",
   "source": "src/index.ts",
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "sideEffects": false,
   "repository": {
     "type": "git",
-    "url": "https://github.com/adobe-private/react-spectrum-v3"
+    "url": "https://github.com/adobe/react-spectrum"
   },
   "dependencies": {
-    "@babel/runtime": "^7.6.2",
-    "@react-aria/interactions": "^3.0.0-rc.2",
-    "@react-aria/overlays": "^3.0.0-alpha.1",
-    "@react-aria/selection": "^3.0.0-alpha.1",
-    "@react-aria/utils": "^3.0.0-rc.2",
-    "@react-stately/collections": "^3.0.0-alpha.1",
-    "@react-stately/menu": "^3.0.0-alpha.1",
-    "@react-stately/tree": "^3.0.0-alpha.1",
-    "@react-types/menu": "^3.0.0-alpha.1",
-    "@react-types/shared": "^3.0.0-rc.2"
+    "@react-aria/focus": "^3.0.0-nightly-4980928d3-240906",
+    "@react-aria/i18n": "^3.0.0-nightly-4980928d3-240906",
+    "@react-aria/interactions": "^3.0.0-nightly-4980928d3-240906",
+    "@react-aria/overlays": "^3.0.0-nightly-4980928d3-240906",
+    "@react-aria/selection": "^3.0.0-nightly-4980928d3-240906",
+    "@react-aria/utils": "^3.0.0-nightly-4980928d3-240906",
+    "@react-stately/collections": "^3.0.0-nightly-4980928d3-240906",
+    "@react-stately/menu": "^3.0.0-nightly-4980928d3-240906",
+    "@react-stately/tree": "^3.0.0-nightly-4980928d3-240906",
+    "@react-types/button": "^3.0.0-nightly-4980928d3-240906",
+    "@react-types/menu": "^3.0.0-nightly-4980928d3-240906",
+    "@react-types/shared": "^3.0.0-nightly-4980928d3-240906",
+    "@swc/helpers": "^0.5.0"
   },
   "peerDependencies": {
-    "react": "^16.8.0"
+    "react": "^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0",
+    "react-dom": "^16.8.0 || ^17.0.0-rc.1 || ^18.0.0 || ^19.0.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "207e6ee9076905c96638a7f81a367758872e1410"
-}
+  "stableVersion": "3.15.3"
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+/*
+ * Copyright 2020 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+export {useMenuTrigger} from './useMenuTrigger';
+export {useMenu} from './useMenu';
+export {useMenuItem} from './useMenuItem';
+export {useMenuSection} from './useMenuSection';
+export {useSubmenuTrigger} from './useSubmenuTrigger';
+
+export type {AriaMenuProps} from '@react-types/menu';
+export type {AriaMenuTriggerProps, MenuTriggerAria} from './useMenuTrigger';
+export type {AriaMenuOptions, MenuAria} from './useMenu';
+export type {AriaMenuItemProps, MenuItemAria} from './useMenuItem';
+export type {AriaMenuSectionProps, MenuSectionAria} from './useMenuSection';
+export type {AriaSubmenuTriggerProps, SubmenuTriggerAria} from './useSubmenuTrigger';

package/src/useMenu.ts

@@ -0,0 +1,88 @@
+/*
+ * Copyright 2020 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import {AriaMenuProps} from '@react-types/menu';
+import {DOMAttributes, Key, KeyboardDelegate, KeyboardEvents, RefObject} from '@react-types/shared';
+import {filterDOMProps, mergeProps} from '@react-aria/utils';
+import {TreeState} from '@react-stately/tree';
+import {useSelectableList} from '@react-aria/selection';
+
+export interface MenuAria {
+  /** Props for the menu element. */
+  menuProps: DOMAttributes
+}
+
+export interface AriaMenuOptions<T> extends Omit<AriaMenuProps<T>, 'children'>, KeyboardEvents {
+  /** Whether the menu uses virtual scrolling. */
+  isVirtualized?: boolean,
+
+  /**
+   * An optional keyboard delegate implementation for type to select,
+   * to override the default.
+   */
+  keyboardDelegate?: KeyboardDelegate
+}
+
+interface MenuData {
+  onClose?: () => void,
+  onAction?: (key: Key) => void
+}
+
+export const menuData = new WeakMap<TreeState<unknown>, MenuData>();
+
+/**
+ * Provides the behavior and accessibility implementation for a menu component.
+ * A menu displays a list of actions or options that a user can choose.
+ * @param props - Props for the menu.
+ * @param state - State for the menu, as returned by `useListState`.
+ */
+export function useMenu<T>(props: AriaMenuOptions<T>, state: TreeState<T>, ref: RefObject<HTMLElement | null>): MenuAria {
+  let {
+    shouldFocusWrap = true,
+    onKeyDown,
+    onKeyUp,
+    ...otherProps
+  } = props;
+
+  if (!props['aria-label'] && !props['aria-labelledby']) {
+    console.warn('An aria-label or aria-labelledby prop is required for accessibility.');
+  }
+
+  let domProps = filterDOMProps(props, {labelable: true});
+  let {listProps} = useSelectableList({
+    ...otherProps,
+    ref,
+    selectionManager: state.selectionManager,
+    collection: state.collection,
+    disabledKeys: state.disabledKeys,
+    shouldFocusWrap,
+    linkBehavior: 'override'
+  });
+
+  menuData.set(state, {
+    onClose: props.onClose,
+    onAction: props.onAction
+  });
+
+  return {
+    menuProps: mergeProps(domProps, {onKeyDown, onKeyUp}, {
+      role: 'menu',
+      ...listProps,
+      onKeyDown: (e) => {
+        // don't clear the menu selected keys if the user is presses escape since escape closes the menu
+        if (e.key !== 'Escape') {
+          listProps.onKeyDown(e);
+        }
+      }
+    })
+  };
+}

package/src/useMenuItem.ts

@@ -0,0 +1,299 @@
+/*
+ * Copyright 2020 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import {DOMAttributes, DOMProps, FocusableElement, FocusEvents, HoverEvents, Key, KeyboardEvents, PressEvent, PressEvents, RefObject, RouterOptions} from '@react-types/shared';
+import {filterDOMProps, mergeProps, useLinkProps, useRouter, useSlotId} from '@react-aria/utils';
+import {getItemCount} from '@react-stately/collections';
+import {isFocusVisible, useFocus, useHover, useKeyboard, usePress} from '@react-aria/interactions';
+import {menuData} from './useMenu';
+import {TreeState} from '@react-stately/tree';
+import {useSelectableItem} from '@react-aria/selection';
+
+export interface MenuItemAria {
+  /** Props for the menu item element. */
+  menuItemProps: DOMAttributes,
+
+  /** Props for the main text element inside the menu item. */
+  labelProps: DOMAttributes,
+
+  /** Props for the description text element inside the menu item, if any. */
+  descriptionProps: DOMAttributes,
+
+  /** Props for the keyboard shortcut text element inside the item, if any. */
+  keyboardShortcutProps: DOMAttributes,
+
+  /** Whether the item is currently focused. */
+  isFocused: boolean,
+  /** Whether the item is currently selected. */
+  isSelected: boolean,
+  /** Whether the item is currently in a pressed state. */
+  isPressed: boolean,
+  /** Whether the item is disabled. */
+  isDisabled: boolean
+}
+
+export interface AriaMenuItemProps extends DOMProps, PressEvents, HoverEvents, KeyboardEvents, FocusEvents  {
+  /**
+   * Whether the menu item is disabled.
+   * @deprecated - pass disabledKeys to useTreeState instead.
+   */
+  isDisabled?: boolean,
+
+  /**
+   * Whether the menu item is selected.
+   * @deprecated - pass selectedKeys to useTreeState instead.
+   */
+  isSelected?: boolean,
+
+  /** A screen reader only label for the menu item. */
+  'aria-label'?: string,
+
+  /** The unique key for the menu item. */
+  key?: Key,
+
+  /**
+   * Handler that is called when the menu should close after selecting an item.
+   * @deprecated - pass to the menu instead.
+   */
+  onClose?: () => void,
+
+  /**
+   * Whether the menu should close when the menu item is selected.
+   * @default true
+   */
+  closeOnSelect?: boolean,
+
+  /** Whether the menu item is contained in a virtual scrolling menu. */
+  isVirtualized?: boolean,
+
+  /**
+   * Handler that is called when the user activates the item.
+   * @deprecated - pass to the menu instead.
+   */
+  onAction?: (key: Key) => void,
+
+  /** What kind of popup the item opens. */
+  'aria-haspopup'?: 'menu' | 'dialog',
+
+  /** Indicates whether the menu item's popup element is expanded or collapsed. */
+  'aria-expanded'?: boolean | 'true' | 'false',
+
+  /** Identifies the menu item's popup element whose contents or presence is controlled by the menu item. */
+  'aria-controls'?: string
+}
+
+/**
+ * Provides the behavior and accessibility implementation for an item in a menu.
+ * See `useMenu` for more details about menus.
+ * @param props - Props for the item.
+ * @param state - State for the menu, as returned by `useTreeState`.
+ */
+export function useMenuItem<T>(props: AriaMenuItemProps, state: TreeState<T>, ref: RefObject<FocusableElement | null>): MenuItemAria {
+  let {
+    id,
+    key,
+    closeOnSelect,
+    isVirtualized,
+    'aria-haspopup': hasPopup,
+    onPressStart: pressStartProp,
+    onPressUp: pressUpProp,
+    onPress,
+    onPressChange,
+    onPressEnd,
+    onHoverStart: hoverStartProp,
+    onHoverChange,
+    onHoverEnd,
+    onKeyDown,
+    onKeyUp,
+    onFocus,
+    onFocusChange,
+    onBlur
+  } = props;
+
+  let isTrigger = !!hasPopup;
+  let isDisabled = props.isDisabled ?? state.selectionManager.isDisabled(key);
+  let isSelected = props.isSelected ?? state.selectionManager.isSelected(key);
+  let data = menuData.get(state);
+  let item = state.collection.getItem(key);
+  let onClose = props.onClose || data.onClose;
+  let router = useRouter();
+  let performAction = (e: PressEvent) => {
+    if (isTrigger) {
+      return;
+    }
+
+    if (item?.props?.onAction) {
+      item.props.onAction();
+    } else if (props.onAction) {
+      props.onAction(key);
+    }
+
+    if (data.onAction) {
+      // Must reassign to variable otherwise `this` binding gets messed up. Something to do with WeakMap.
+      let onAction = data.onAction;
+      onAction(key);
+    }
+
+    if (e.target instanceof HTMLAnchorElement) {
+      router.open(e.target, e, item.props.href, item.props.routerOptions as RouterOptions);
+    }
+  };
+
+  let role = 'menuitem';
+  if (!isTrigger) {
+    if (state.selectionManager.selectionMode === 'single') {
+      role = 'menuitemradio';
+    } else if (state.selectionManager.selectionMode === 'multiple') {
+      role = 'menuitemcheckbox';
+    }
+  }
+
+  let labelId = useSlotId();
+  let descriptionId = useSlotId();
+  let keyboardId = useSlotId();
+
+  let ariaProps = {
+    id,
+    'aria-disabled': isDisabled || undefined,
+    role,
+    'aria-label': props['aria-label'],
+    'aria-labelledby': labelId,
+    'aria-describedby': [descriptionId, keyboardId].filter(Boolean).join(' ') || undefined,
+    'aria-controls': props['aria-controls'],
+    'aria-haspopup': hasPopup,
+    'aria-expanded': props['aria-expanded']
+  };
+
+  if (state.selectionManager.selectionMode !== 'none' && !isTrigger) {
+    ariaProps['aria-checked'] = isSelected;
+  }
+
+  if (isVirtualized) {
+    ariaProps['aria-posinset'] = item?.index;
+    ariaProps['aria-setsize'] = getItemCount(state.collection);
+  }
+
+  let onPressStart = (e: PressEvent) => {
+    if (e.pointerType === 'keyboard') {
+      performAction(e);
+    }
+
+    pressStartProp?.(e);
+  };
+
+  let onPressUp = (e: PressEvent) => {
+    if (e.pointerType !== 'keyboard') {
+      performAction(e);
+
+      // Pressing a menu item should close by default in single selection mode but not multiple
+      // selection mode, except if overridden by the closeOnSelect prop.
+      if (!isTrigger && onClose && (closeOnSelect ?? (state.selectionManager.selectionMode !== 'multiple' || state.selectionManager.isLink(key)))) {
+        onClose();
+      }
+    }
+
+    pressUpProp?.(e);
+  };
+
+  let {itemProps, isFocused} = useSelectableItem({
+    selectionManager: state.selectionManager,
+    key,
+    ref,
+    shouldSelectOnPressUp: true,
+    allowsDifferentPressOrigin: true,
+    // Disable all handling of links in useSelectable item
+    // because we handle it ourselves. The behavior of menus
+    // is slightly different from other collections because
+    // actions are performed on key down rather than key up.
+    linkBehavior: 'none'
+  });
+
+  let {pressProps, isPressed} = usePress({
+    onPressStart,
+    onPress,
+    onPressUp,
+    onPressChange,
+    onPressEnd,
+    isDisabled
+  });
+  let {hoverProps} = useHover({
+    isDisabled,
+    onHoverStart(e) {
+      if (!isFocusVisible()) {
+        state.selectionManager.setFocused(true);
+        state.selectionManager.setFocusedKey(key);
+      }
+      hoverStartProp?.(e);
+    },
+    onHoverChange,
+    onHoverEnd
+  });
+
+  let {keyboardProps} = useKeyboard({
+    onKeyDown: (e) => {
+      // Ignore repeating events, which may have started on the menu trigger before moving
+      // focus to the menu item. We want to wait for a second complete key press sequence.
+      if (e.repeat) {
+        e.continuePropagation();
+        return;
+      }
+
+      switch (e.key) {
+        case ' ':
+          if (!isDisabled && state.selectionManager.selectionMode === 'none' && !isTrigger && closeOnSelect !== false && onClose) {
+            onClose();
+          }
+          break;
+        case 'Enter':
+          // The Enter key should always close on select, except if overridden.
+          if (!isDisabled && closeOnSelect !== false && !isTrigger && onClose) {
+            onClose();
+          }
+          break;
+        default:
+          if (!isTrigger) {
+            e.continuePropagation();
+          }
+
+          onKeyDown?.(e);
+          break;
+      }
+    },
+    onKeyUp
+  });
+
+  let {focusProps} = useFocus({onBlur, onFocus, onFocusChange});
+  let domProps = filterDOMProps(item.props);
+  delete domProps.id;
+  let linkProps = useLinkProps(item.props);
+
+  return {
+    menuItemProps: {
+      ...ariaProps,
+      ...mergeProps(domProps, linkProps, isTrigger ? {onFocus: itemProps.onFocus, 'data-key': itemProps['data-key']} : itemProps, pressProps, hoverProps, keyboardProps, focusProps),
+      tabIndex: itemProps.tabIndex != null ? -1 : undefined
+    },
+    labelProps: {
+      id: labelId
+    },
+    descriptionProps: {
+      id: descriptionId
+    },
+    keyboardShortcutProps: {
+      id: keyboardId
+    },
+    isFocused,
+    isSelected,
+    isPressed,
+    isDisabled
+  };
+}

package/src/useMenuSection.ts

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2020 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import {DOMAttributes} from '@react-types/shared';
+import {ReactNode} from 'react';
+import {useId} from '@react-aria/utils';
+
+export interface AriaMenuSectionProps {
+  /** The heading for the section. */
+  heading?: ReactNode,
+  /** An accessibility label for the section. Required if `heading` is not present. */
+  'aria-label'?: string
+}
+
+export interface MenuSectionAria {
+  /** Props for the wrapper list item. */
+  itemProps: DOMAttributes,
+
+  /** Props for the heading element, if any. */
+  headingProps: DOMAttributes,
+
+  /** Props for the group element. */
+  groupProps: DOMAttributes
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a section in a menu.
+ * See `useMenu` for more details about menus.
+ * @param props - Props for the section.
+ */
+export function useMenuSection(props: AriaMenuSectionProps): MenuSectionAria {
+  let {heading, 'aria-label': ariaLabel} = props;
+  let headingId = useId();
+
+  return {
+    itemProps: {
+      role: 'presentation'
+    },
+    headingProps: heading ? {
+      // Techincally, menus cannot contain headings according to ARIA.
+      // We hide the heading from assistive technology, using role="presentation",
+      // and only use it as a label for the nested group.
+      id: headingId,
+      role: 'presentation'
+    } : {},
+    groupProps: {
+      role: 'group',
+      'aria-label': ariaLabel,
+      'aria-labelledby': heading ? headingId : undefined
+    }
+  };
+}

package/src/useMenuTrigger.ts

@@ -0,0 +1,144 @@
+/*
+ * Copyright 2020 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import {AriaButtonProps} from '@react-types/button';
+import {AriaMenuOptions} from './useMenu';
+// @ts-ignore
+import intlMessages from '../intl/*.json';
+import {MenuTriggerState} from '@react-stately/menu';
+import {MenuTriggerType} from '@react-types/menu';
+import {RefObject} from '@react-types/shared';
+import {useId} from '@react-aria/utils';
+import {useLocalizedStringFormatter} from '@react-aria/i18n';
+import {useLongPress} from '@react-aria/interactions';
+import {useOverlayTrigger} from '@react-aria/overlays';
+
+export interface AriaMenuTriggerProps {
+  /** The type of menu that the menu trigger opens. */
+  type?: 'menu' | 'listbox',
+  /** Whether menu trigger is disabled. */
+  isDisabled?: boolean,
+  /** How menu is triggered. */
+  trigger?: MenuTriggerType
+}
+
+export interface MenuTriggerAria<T> {
+  /** Props for the menu trigger element. */
+  menuTriggerProps: AriaButtonProps,
+
+  /** Props for the menu. */
+  menuProps: AriaMenuOptions<T>
+}
+
+/**
+ * Provides the behavior and accessibility implementation for a menu trigger.
+ * @param props - Props for the menu trigger.
+ * @param state - State for the menu trigger.
+ * @param ref - Ref to the HTML element trigger for the menu.
+ */
+export function useMenuTrigger<T>(props: AriaMenuTriggerProps, state: MenuTriggerState, ref: RefObject<Element | null>): MenuTriggerAria<T> {
+  let {
+    type = 'menu' as AriaMenuTriggerProps['type'],
+    isDisabled,
+    trigger = 'press'
+  } = props;
+
+  let menuTriggerId = useId();
+  let {triggerProps, overlayProps} = useOverlayTrigger({type}, state, ref);
+
+  let onKeyDown = (e) => {
+    if (isDisabled) {
+      return;
+    }
+
+    if (trigger === 'longPress' && !e.altKey) {
+      return;
+    }
+
+    if (ref && ref.current) {
+      switch (e.key) {
+        case 'Enter':
+        case ' ':
+          if (trigger === 'longPress') {
+            return;
+          }
+          // fallthrough
+        case 'ArrowDown':
+          // Stop propagation, unless it would already be handled by useKeyboard.
+          if (!('continuePropagation' in e)) {
+            e.stopPropagation();
+          }
+          e.preventDefault();
+          state.toggle('first');
+          break;
+        case 'ArrowUp':
+          if (!('continuePropagation' in e)) {
+            e.stopPropagation();
+          }
+          e.preventDefault();
+          state.toggle('last');
+          break;
+        default:
+          // Allow other keys.
+          if ('continuePropagation' in e) {
+            e.continuePropagation();
+          }
+      }
+    }
+  };
+
+  let stringFormatter = useLocalizedStringFormatter(intlMessages, '@react-aria/menu');
+  let {longPressProps} = useLongPress({
+    isDisabled: isDisabled || trigger !== 'longPress',
+    accessibilityDescription: stringFormatter.format('longPressMessage'),
+    onLongPressStart() {
+      state.close();
+    },
+    onLongPress() {
+      state.open('first');
+    }
+  });
+
+  let pressProps =  {
+    onPressStart(e) {
+      // For consistency with native, open the menu on mouse/key down, but touch up.
+      if (e.pointerType !== 'touch' && e.pointerType !== 'keyboard' && !isDisabled) {
+        // If opened with a screen reader, auto focus the first item.
+        // Otherwise, the menu itself will be focused.
+        state.open(e.pointerType === 'virtual' ? 'first' : null);
+      }
+    },
+    onPress(e) {
+      if (e.pointerType === 'touch' && !isDisabled) {
+        state.toggle();
+      }
+    }
+  };
+
+  // omit onPress from triggerProps since we override it above.
+  delete triggerProps.onPress;
+
+  return {
+    menuTriggerProps: {
+      ...triggerProps,
+      ...(trigger === 'press' ? pressProps : longPressProps),
+      id: menuTriggerId,
+      onKeyDown
+    },
+    menuProps: {
+      ...overlayProps,
+      'aria-labelledby': menuTriggerId,
+      autoFocus: state.focusStrategy || true,
+      onClose: state.close
+    }
+  };
+}