@ariakit/react-components 0.1.0

package/src/menu/menu-button.tsx

@@ -0,0 +1,338 @@
+import { useStoreState } from "@ariakit/react-store";
+import {
+  useEvent,
+  useId,
+  useMergeRefs,
+  useWrapElement,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import {
+  getPopupItemRole,
+  getPopupRole,
+  disabledFromElement,
+  disabledFromProps,
+  invariant,
+} from "@ariakit/utils";
+import type { ElementType, FocusEvent, KeyboardEvent, MouseEvent } from "react";
+import { useRef } from "react";
+import type { CompositeTypeaheadOptions } from "../composite/composite-typeahead.tsx";
+import { useCompositeTypeahead } from "../composite/composite-typeahead.tsx";
+import type { HovercardAnchorOptions } from "../hovercard/hovercard-anchor.tsx";
+import { useHovercardAnchor } from "../hovercard/hovercard-anchor.tsx";
+import type { PopoverDisclosureOptions } from "../popover/popover-disclosure.tsx";
+import { usePopoverDisclosure } from "../popover/popover-disclosure.tsx";
+import { Role } from "../role/role.tsx";
+import {
+  MenuContextProvider,
+  useMenuProviderContext,
+} from "./menu-context.tsx";
+import type { MenuStore, MenuStoreState } from "./menu-store.ts";
+
+const TagName = "button" satisfies ElementType;
+type TagName = typeof TagName | "div";
+type HTMLType = HTMLElementTagNameMap[TagName];
+type BasePlacement = "top" | "bottom" | "left" | "right";
+
+function getInitialFocus(event: KeyboardEvent, dir: BasePlacement) {
+  const keyMap = {
+    ArrowDown: dir === "bottom" || dir === "top" ? "first" : false,
+    ArrowUp: dir === "bottom" || dir === "top" ? "last" : false,
+    ArrowRight: dir === "right" ? "first" : false,
+    ArrowLeft: dir === "left" ? "first" : false,
+  } as const;
+  return keyMap[event.key as keyof typeof keyMap];
+}
+
+function hasActiveItem(
+  items?: MenuStoreState["items"],
+  excludeElement?: Element | null,
+) {
+  return !!items?.some((item) => {
+    if (!item.element) return false;
+    if (item.element === excludeElement) return false;
+    return item.element.getAttribute("aria-expanded") === "true";
+  });
+}
+
+/**
+ * Returns props to create a `MenuButton` component.
+ * @see https://ariakit.com/components/menu
+ * @example
+ * ```jsx
+ * const store = useMenuStore();
+ * const props = useMenuButton({ store });
+ * <Role {...props}>Edit</Role>
+ * <Menu store={store}>
+ *   <MenuItem>Undo</MenuItem>
+ *   <MenuItem>Redo</MenuItem>
+ * </Menu>
+ * ```
+ */
+export const useMenuButton = createHook<TagName, MenuButtonOptions>(
+  function useMenuButton({
+    store,
+    focusable,
+    accessibleWhenDisabled,
+    showOnHover,
+    ...props
+  }) {
+    const context = useMenuProviderContext();
+    store = store || context;
+
+    invariant(
+      store,
+      process.env.NODE_ENV !== "production" &&
+        "MenuButton must receive a `store` prop or be wrapped in a MenuProvider component.",
+    );
+
+    const ref = useRef<HTMLElement>(null);
+    const parentMenu = store.parent;
+    const parentMenubar = store.menubar;
+    const hasParentMenu = !!parentMenu;
+    const parentIsMenubar = !!parentMenubar && !hasParentMenu;
+    const disabled = disabledFromProps(props);
+    const isDisabled = (element: Element) =>
+      disabled || disabledFromElement(element);
+
+    const showMenu = () => {
+      const trigger = ref.current;
+      if (!trigger) return;
+      store?.setDisclosureElement(trigger);
+      store?.setAnchorElement(trigger);
+      store?.show();
+    };
+
+    const onFocusProp = props.onFocus;
+
+    const onFocus = useEvent((event: FocusEvent<HTMLType>) => {
+      onFocusProp?.(event as any);
+      if (isDisabled(event.currentTarget)) return;
+      if (event.defaultPrevented) return;
+      // Reset the autoFocusOnShow state so we can focus the menu button while
+      // the menu is open and press arrow keys to move focus to the menu items.
+      store?.setAutoFocusOnShow(false);
+      // We need to unset the active menu item so no menu item appears active
+      // while the menu button is focused.
+      store?.setActiveId(null);
+      // When the menu button is focused, we'll only show its menu if it's in a
+      // menu bar
+      if (!parentMenubar) return;
+      if (!parentIsMenubar) return;
+      const { items } = parentMenubar.getState();
+      // and there's already another expanded menu button or the previously
+      // focused element is another menu item.
+      if (hasActiveItem(items, event.currentTarget)) {
+        showMenu();
+      }
+    });
+
+    const dir = useStoreState(
+      store,
+      (state) => state.placement.split("-")[0] as BasePlacement,
+    );
+
+    const onKeyDownProp = props.onKeyDown;
+
+    const onKeyDown = useEvent((event: KeyboardEvent<HTMLType>) => {
+      onKeyDownProp?.(event as any);
+      if (isDisabled(event.currentTarget)) return;
+      if (event.defaultPrevented) return;
+      const initialFocus = getInitialFocus(event, dir);
+      if (initialFocus) {
+        event.preventDefault();
+        const { open } = store.getState();
+        if (open) {
+          const id = initialFocus === "last" ? store.last() : store.first();
+          store.move(id);
+          return;
+        }
+        showMenu();
+        store?.setAutoFocusOnShow(true);
+        store?.setInitialFocus(initialFocus);
+      }
+    });
+
+    const onClickProp = props.onClick;
+
+    const onClick = useEvent((event: MouseEvent<HTMLType>) => {
+      onClickProp?.(event as any);
+      if (event.defaultPrevented) return;
+      if (!store) return;
+      const isKeyboardClick = !event.detail;
+      const { open } = store.getState();
+      // When the menu button is clicked, if the menu is hidden or if it's a
+      // keyboard click (enter or space),
+      if (!open || isKeyboardClick) {
+        // we'll only automatically focus on the menu if it's not a submenu
+        // button, or if it's a keyboard click.
+        if (!hasParentMenu || isKeyboardClick) {
+          store.setAutoFocusOnShow(true);
+        }
+        store.setInitialFocus(isKeyboardClick ? "first" : "container");
+      }
+      // On submenu buttons, we can't hide the submenu by clicking on the menu
+      // button again.
+      if (hasParentMenu) {
+        showMenu();
+      }
+    });
+
+    props = useWrapElement(
+      props,
+      (element) => (
+        <MenuContextProvider value={store}>{element}</MenuContextProvider>
+      ),
+      [store],
+    );
+
+    if (hasParentMenu) {
+      // On Safari, VO+Space triggers a click twice on native button elements
+      // with role menuitem (https://bugs.webkit.org/show_bug.cgi?id=228318).
+      // So, if the menu button is rendered within a menu, we need to render it
+      // as another element.
+      props = {
+        ...props,
+        render: <Role.div render={props.render} />,
+      };
+    }
+
+    // We'll use this id to render the aria-labelledby attribute on the menu.
+    const id = useId(props.id);
+
+    const parentContentElement = useStoreState(
+      parentMenu?.combobox || parentMenu,
+      "contentElement",
+    );
+
+    // When the menu button is rendered inside another menu, we set the role
+    // attribute here so it doesn't get overridden by the button component with
+    // role="button".
+    const role =
+      hasParentMenu || parentIsMenubar
+        ? getPopupItemRole(parentContentElement, "menuitem")
+        : undefined;
+
+    const contentElement = useStoreState(store, "contentElement");
+
+    // Use the combobox presence to pick the correct fallback so
+    // aria-haspopup stays stable before the content element mounts.
+    // See https://github.com/ariakit/ariakit/issues/4443
+    const hasCombobox = !!store.combobox;
+    const popupRole = getPopupRole(
+      contentElement,
+      hasCombobox ? "dialog" : "menu",
+    );
+
+    props = {
+      role,
+      "aria-haspopup": popupRole,
+      ...props,
+      id,
+      ref: useMergeRefs(ref, props.ref),
+      onFocus,
+      onKeyDown,
+      onClick,
+    };
+
+    props = useHovercardAnchor<TagName>({
+      store,
+      focusable,
+      accessibleWhenDisabled,
+      ...props,
+      showOnHover: (event) => {
+        const getShowOnHover = () => {
+          if (typeof showOnHover === "function") return showOnHover(event);
+          if (showOnHover != null) return showOnHover;
+          if (hasParentMenu) return true;
+          if (!parentMenubar) return false;
+          const { items } = parentMenubar.getState();
+          return parentIsMenubar && hasActiveItem(items);
+        };
+        const canShowOnHover = getShowOnHover();
+        if (!canShowOnHover) return false;
+        const parent = parentIsMenubar ? parentMenubar : parentMenu;
+        if (!parent) return true;
+        // When hovering over a menu button shows a menu and the menu button is
+        // part of another menu or menubar, it's not guaranteed that the button
+        // will get focused. That's why we make sure the active item is updated
+        // on the parent menu store. See "moving between menus with arrow keys
+        // after hovering over subitems" test.
+        parent.setActiveId(event.currentTarget.id);
+        return true;
+      },
+    });
+
+    props = usePopoverDisclosure<TagName>({
+      store,
+      toggleOnClick: !hasParentMenu,
+      focusable,
+      accessibleWhenDisabled,
+      ...props,
+    });
+
+    props = useCompositeTypeahead<TagName>({
+      store,
+      typeahead: parentIsMenubar,
+      ...props,
+    });
+
+    return props;
+  },
+);
+
+/**
+ * Renders a menu button that toggles the visibility of a
+ * [`Menu`](https://ariakit.com/reference/menu) component when clicked or when
+ * using arrow keys.
+ * @see https://ariakit.com/components/menu
+ * @example
+ * ```jsx {2}
+ * <MenuProvider>
+ *   <MenuButton>Edit</MenuButton>
+ *   <Menu>
+ *     <MenuItem>Undo</MenuItem>
+ *     <MenuItem>Redo</MenuItem>
+ *   </Menu>
+ * </MenuProvider>
+ * ```
+ */
+export const MenuButton = forwardRef(function MenuButton(
+  props: MenuButtonProps,
+) {
+  const htmlProps = useMenuButton(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface MenuButtonOptions<T extends ElementType = TagName>
+  extends
+    HovercardAnchorOptions<T>,
+    PopoverDisclosureOptions<T>,
+    CompositeTypeaheadOptions<T> {
+  /**
+   * Object returned by the
+   * [`useMenuStore`](https://ariakit.com/reference/use-menu-store) hook. If not
+   * provided, the closest
+   * [`MenuProvider`](https://ariakit.com/reference/menu-provider) component's
+   * context will be used.
+   */
+  store?: MenuStore;
+  /**
+   * Determines whether pressing a character key while focusing on the
+   * [`MenuButton`](https://ariakit.com/reference/menu-button) should move focus
+   * to the [`MenuItem`](https://ariakit.com/reference/menu-item) starting with
+   * that character.
+   *
+   * By default, it's `true` for menu buttons in a
+   * [`Menubar`](https://ariakit.com/reference/menubar), but `false` for other
+   * menu buttons.
+   */
+  typeahead?: boolean;
+}
+
+export type MenuButtonProps<T extends ElementType = TagName> = Props<
+  T,
+  MenuButtonOptions<T>
+>;

package/src/menu/menu-context.tsx

@@ -0,0 +1,76 @@
+import { createStoreContext } from "@ariakit/react-utils";
+import { createContext } from "react";
+import {
+  CompositeContextProvider,
+  CompositeScopedContextProvider,
+} from "../composite/composite-context.tsx";
+import {
+  HovercardContextProvider,
+  HovercardScopedContextProvider,
+} from "../hovercard/hovercard-context.tsx";
+import {
+  MenubarContextProvider,
+  MenubarScopedContextProvider,
+  useMenubarContext,
+  useMenubarProviderContext,
+  useMenubarScopedContext,
+} from "../menubar/menubar-context.tsx";
+import type { MenuStore } from "./menu-store.ts";
+
+const menu = createStoreContext<MenuStore>(
+  [CompositeContextProvider, HovercardContextProvider],
+  [CompositeScopedContextProvider, HovercardScopedContextProvider],
+);
+
+/**
+ * Returns the menu store from the nearest menu container.
+ * @example
+ * function Menu() {
+ *   const store = useMenuContext();
+ *
+ *   if (!store) {
+ *     throw new Error("Menu must be wrapped in MenuProvider");
+ *   }
+ *
+ *   // Use the store...
+ * }
+ */
+export const useMenuContext = menu.useContext;
+
+export const useMenuScopedContext = menu.useScopedContext;
+
+export const useMenuProviderContext = menu.useProviderContext;
+
+export const MenuContextProvider = menu.ContextProvider;
+
+export const MenuScopedContextProvider = menu.ScopedContextProvider;
+
+/**
+ * Returns the menuBar store from the nearest menuBar container.
+ * @deprecated
+ * Use [`useMenubarContext`](https://ariakit.com/reference/use-menubar-context)
+ * instead.
+ * @example
+ * function MenuBar() {
+ *   const store = useMenuBarContext();
+ *
+ *   if (!store) {
+ *     throw new Error("MenuBar must be wrapped in MenuBarProvider");
+ *   }
+ *
+ *   // Use the store...
+ * }
+ */
+export const useMenuBarContext = useMenubarContext;
+
+export const useMenuBarScopedContext = useMenubarScopedContext;
+
+export const useMenuBarProviderContext = useMenubarProviderContext;
+
+export const MenuBarContextProvider = MenubarContextProvider;
+
+export const MenuBarScopedContextProvider = MenubarScopedContextProvider;
+
+export const MenuItemCheckedContext = createContext<boolean | undefined>(
+  undefined,
+);

package/src/menu/menu-description.tsx

@@ -0,0 +1,67 @@
+import { createElement, createHook, forwardRef } from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import type { ElementType } from "react";
+import type { HovercardDescriptionOptions } from "../hovercard/hovercard-description.tsx";
+import { useHovercardDescription } from "../hovercard/hovercard-description.tsx";
+import type { MenuStore } from "./menu-store.ts";
+
+const TagName = "p" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `MenuDescription` component. This hook must be used
+ * in a component that's wrapped with `Menu` so the `aria-describedby` prop is
+ * properly set on the menu element.
+ * @see https://ariakit.com/components/menu
+ * @example
+ * ```jsx
+ * // This component must be wrapped with Menu
+ * const props = useMenuDescription();
+ * <Role {...props}>Description</Role>
+ * ```
+ */
+export const useMenuDescription = createHook<TagName, MenuDescriptionOptions>(
+  function useMenuDescription(props) {
+    props = useHovercardDescription(props);
+    return props;
+  },
+);
+
+/**
+ * Renders a description in a menu. This component must be wrapped with a
+ * [`Menu`](https://ariakit.com/reference/menu) component so the
+ * `aria-describedby` prop is properly set on the menu element.
+ * @see https://ariakit.com/components/menu
+ * @example
+ * ```jsx {3}
+ * <MenuProvider>
+ *   <Menu>
+ *     <MenuDescription>Description</MenuDescription>
+ *   </Menu>
+ * </MenuProvider>
+ * ```
+ */
+export const MenuDescription = forwardRef(function MenuDescription(
+  props: MenuDescriptionProps,
+) {
+  const htmlProps = useMenuDescription(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface MenuDescriptionOptions<
+  T extends ElementType = TagName,
+> extends HovercardDescriptionOptions<T> {
+  /**
+   * Object returned by the
+   * [`useMenuStore`](https://ariakit.com/reference/use-menu-store) hook. If not
+   * provided, the closest [`Menu`](https://ariakit.com/reference/menu) or
+   * [`MenuProvider`](https://ariakit.com/reference/menu-provider) components'
+   * context will be used.
+   */
+  store?: MenuStore;
+}
+
+export type MenuDescriptionProps<T extends ElementType = TagName> = Props<
+  T,
+  MenuDescriptionOptions<T>
+>;

package/src/menu/menu-dismiss.tsx

@@ -0,0 +1,69 @@
+import { createElement, createHook, forwardRef } from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import type { ElementType } from "react";
+import type { HovercardDismissOptions } from "../hovercard/hovercard-dismiss.tsx";
+import { useHovercardDismiss } from "../hovercard/hovercard-dismiss.tsx";
+import { useMenuScopedContext } from "./menu-context.tsx";
+import type { MenuStore } from "./menu-store.ts";
+
+const TagName = "button" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `MenuDismiss` component.
+ * @see https://ariakit.com/components/menu
+ * @example
+ * ```jsx
+ * const store = useMenuStore();
+ * const props = useMenuDismiss({ store });
+ * <Menu store={store}>
+ *   <Role {...props} />
+ * </Menu>
+ * ```
+ */
+export const useMenuDismiss = createHook<TagName, MenuDismissOptions>(
+  function useMenuDismiss({ store, ...props }) {
+    const context = useMenuScopedContext();
+    store = store || context;
+    props = useHovercardDismiss({ store, ...props });
+    return props;
+  },
+);
+
+/**
+ * Renders a button that hides a [`Menu`](https://ariakit.com/reference/menu)
+ * when clicked.
+ * @see https://ariakit.com/components/menu
+ * @example
+ * ```jsx {3}
+ * <MenuProvider>
+ *   <Menu>
+ *     <MenuDismiss />
+ *   </Menu>
+ * </MenuProvider>
+ * ```
+ */
+export const MenuDismiss = forwardRef(function MenuDismiss(
+  props: MenuDismissProps,
+) {
+  const htmlProps = useMenuDismiss(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface MenuDismissOptions<
+  T extends ElementType = TagName,
+> extends HovercardDismissOptions<T> {
+  /**
+   * Object returned by the
+   * [`useMenuStore`](https://ariakit.com/reference/use-menu-store) hook. If not
+   * provided, the closest [`Menu`](https://ariakit.com/reference/menu) or
+   * [`MenuProvider`](https://ariakit.com/reference/menu-provider) components'
+   * context will be used.
+   */
+  store?: MenuStore;
+}
+
+export type MenuDismissProps<T extends ElementType = TagName> = Props<
+  T,
+  MenuDismissOptions<T>
+>;

package/src/menu/menu-group-label.tsx

@@ -0,0 +1,72 @@
+import { createElement, createHook, forwardRef } from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import type { ElementType } from "react";
+import type { CompositeGroupLabelOptions } from "../composite/composite-group-label.tsx";
+import { useCompositeGroupLabel } from "../composite/composite-group-label.tsx";
+import type { MenuStore } from "./menu-store.ts";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `MenuGroupLabel` component. This hook must be used
+ * in a component that's wrapped with `MenuGroup` so the `aria-labelledby` prop
+ * is properly set on the menu group element.
+ * @see https://ariakit.com/components/menu
+ * @example
+ * ```jsx
+ * // This component must be wrapped with MenuGroup
+ * const props = useMenuGroupLabel();
+ * <Role {...props}>Label</Role>
+ * ```
+ */
+export const useMenuGroupLabel = createHook<TagName, MenuGroupLabelOptions>(
+  function useMenuGroupLabel(props) {
+    props = useCompositeGroupLabel(props);
+    return props;
+  },
+);
+
+/**
+ * Renders a label in a menu group. This component should be wrapped with
+ * [`MenuGroup`](https://ariakit.com/reference/menu-group) so the
+ * `aria-labelledby` is correctly set on the group element.
+ * @see https://ariakit.com/components/menu
+ * @example
+ * ```jsx {5}
+ * <MenuProvider>
+ *   <MenuButton>Recent Items</MenuButton>
+ *   <Menu>
+ *     <MenuGroup>
+ *       <MenuGroupLabel>Applications</MenuGroupLabel>
+ *       <MenuItem>Google Chrome.app</MenuItem>
+ *       <MenuItem>Safari.app</MenuItem>
+ *     </MenuGroup>
+ *   </Menu>
+ * </MenuProvider>
+ * ```
+ */
+export const MenuGroupLabel = forwardRef(function MenuGroupLabel(
+  props: MenuGroupLabelProps,
+) {
+  const htmlProps = useMenuGroupLabel(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface MenuGroupLabelOptions<
+  T extends ElementType = TagName,
+> extends CompositeGroupLabelOptions<T> {
+  /**
+   * Object returned by the
+   * [`useMenuStore`](https://ariakit.com/reference/use-menu-store) hook. If not
+   * provided, the closest [`Menu`](https://ariakit.com/reference/menu) or
+   * [`MenuProvider`](https://ariakit.com/reference/menu-provider) components'
+   * context will be used.
+   */
+  store?: MenuStore;
+}
+
+export type MenuGroupLabelProps<T extends ElementType = TagName> = Props<
+  T,
+  MenuGroupLabelOptions<T>
+>;

package/src/menu/menu-group.tsx

@@ -0,0 +1,76 @@
+import { createElement, createHook, forwardRef } from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import type { ElementType } from "react";
+import type { CompositeGroupOptions } from "../composite/composite-group.tsx";
+import { useCompositeGroup } from "../composite/composite-group.tsx";
+import type { MenuStore } from "./menu-store.ts";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+
+/**
+ * Returns props to create a `MenuGroup` component.
+ * @see https://ariakit.com/components/menu
+ * @example
+ * ```jsx
+ * const store = useMenuStore();
+ * const props = useMenuGroup({ store });
+ * <MenuButton store={store}>Recent Items</MenuButton>
+ * <Menu store={store}>
+ *   <Role {...props}>
+ *     <MenuGroupLabel>Applications</MenuGroupLabel>
+ *     <MenuItem>Google Chrome.app</MenuItem>
+ *     <MenuItem>Safari.app</MenuItem>
+ *   </Role>
+ * </Menu>
+ * ```
+ */
+export const useMenuGroup = createHook<TagName, MenuGroupOptions>(
+  function useMenuGroup(props) {
+    props = useCompositeGroup(props);
+    return props;
+  },
+);
+
+/**
+ * Renders a group for [`MenuItem`](https://ariakit.com/reference/menu-item)
+ * elements. Optionally, a
+ * [`MenuGroupLabel`](https://ariakit.com/reference/menu-group-label) can be
+ * rendered as a child to provide a label for the group.
+ * @see https://ariakit.com/components/menu
+ * @example
+ * ```jsx {4-8}
+ * <MenuProvider>
+ *   <MenuButton>Recent Items</MenuButton>
+ *   <Menu>
+ *     <MenuGroup>
+ *       <MenuGroupLabel>Applications</MenuGroupLabel>
+ *       <MenuItem>Google Chrome.app</MenuItem>
+ *       <MenuItem>Safari.app</MenuItem>
+ *     </MenuGroup>
+ *   </Menu>
+ * </MenuProvider>
+ * ```
+ */
+export const MenuGroup = forwardRef(function MenuGroup(props: MenuGroupProps) {
+  const htmlProps = useMenuGroup(props);
+  return createElement(TagName, htmlProps);
+});
+
+export interface MenuGroupOptions<
+  T extends ElementType = TagName,
+> extends CompositeGroupOptions<T> {
+  /**
+   * Object returned by the
+   * [`useMenuStore`](https://ariakit.com/reference/use-menu-store) hook. If not
+   * provided, the closest [`Menu`](https://ariakit.com/reference/menu) or
+   * [`MenuProvider`](https://ariakit.com/reference/menu-provider) components'
+   * context will be used.
+   */
+  store?: MenuStore;
+}
+
+export type MenuGroupProps<T extends ElementType = TagName> = Props<
+  T,
+  MenuGroupOptions<T>
+>;