@ariakit/react-components 0.1.0

package/src/menu/menu-store.ts

@@ -0,0 +1,155 @@
+import * as Core from "@ariakit/components/menu/menu-store";
+import { useStore, useStoreProps } from "@ariakit/react-store";
+import type { Store } from "@ariakit/react-store";
+import { useUpdateEffect } from "@ariakit/react-utils";
+import type { BivariantCallback, PickRequired } from "@ariakit/utils";
+import { useComboboxProviderContext } from "../combobox/combobox-context.tsx";
+import type { ComboboxStore } from "../combobox/combobox-store.ts";
+import type {
+  CompositeStoreFunctions,
+  CompositeStoreOptions,
+  CompositeStoreState,
+} from "../composite/composite-store.ts";
+import { useCompositeStoreProps } from "../composite/composite-store.ts";
+import type {
+  HovercardStoreFunctions,
+  HovercardStoreOptions,
+  HovercardStoreState,
+} from "../hovercard/hovercard-store.ts";
+import { useHovercardStoreProps } from "../hovercard/hovercard-store.ts";
+import { useMenubarContext } from "../menubar/menubar-context.tsx";
+import type { MenubarStore } from "../menubar/menubar-store.ts";
+import { useMenuContext } from "./menu-context.tsx";
+
+export function useMenuStoreProps<T extends Core.MenuStore>(
+  store: T,
+  update: () => void,
+  props: MenuStoreProps,
+) {
+  useUpdateEffect(update, [props.combobox, props.parent, props.menubar]);
+  useStoreProps(store, props, "values", "setValues");
+  return Object.assign(
+    useHovercardStoreProps(
+      useCompositeStoreProps(store, update, props),
+      update,
+      props,
+    ),
+    {
+      combobox: props.combobox,
+      parent: props.parent,
+      menubar: props.menubar,
+    },
+  );
+}
+
+/**
+ * Creates a menu store to control the state of
+ * [Menu](https://ariakit.com/components/menu) components.
+ * @see https://ariakit.com/components/menu
+ * @example
+ * ```jsx
+ * const menu = useMenuStore({ placement: "top" });
+ *
+ * <MenuButton store={menu}>Edit</MenuButton>
+ * <Menu store={menu}>
+ *   <MenuItem>Undo</MenuItem>
+ *   <MenuItem>Redo</MenuItem>
+ * </Menu>
+ * ```
+ */
+export function useMenuStore<T extends MenuStoreValues = MenuStoreValues>(
+  props: PickRequired<MenuStoreProps<T>, "values" | "defaultValues">,
+): MenuStore<T>;
+
+export function useMenuStore(props?: MenuStoreProps): MenuStore;
+
+export function useMenuStore(props: MenuStoreProps = {}): MenuStore {
+  const parent = useMenuContext();
+  const menubar = useMenubarContext();
+  const combobox = useComboboxProviderContext();
+  props = {
+    ...props,
+    parent: props.parent !== undefined ? props.parent : parent,
+    menubar: props.menubar !== undefined ? props.menubar : menubar,
+    combobox: props.combobox !== undefined ? props.combobox : combobox,
+  };
+  const [store, update] = useStore(Core.createMenuStore, props);
+  return useMenuStoreProps(store, update, props);
+}
+
+export type MenuStoreValues = Core.MenuStoreValues;
+
+export interface MenuStoreState<T extends MenuStoreValues = MenuStoreValues>
+  extends Core.MenuStoreState<T>, CompositeStoreState, HovercardStoreState {}
+
+export interface MenuStoreFunctions<T extends MenuStoreValues = MenuStoreValues>
+  extends
+    Pick<MenuStoreOptions, "combobox" | "parent" | "menubar" | "disclosure">,
+    Omit<
+      Core.MenuStoreFunctions<T>,
+      "combobox" | "parent" | "menubar" | "disclosure"
+    >,
+    CompositeStoreFunctions,
+    HovercardStoreFunctions {}
+
+export interface MenuStoreOptions<T extends MenuStoreValues = MenuStoreValues>
+  extends
+    Omit<Core.MenuStoreOptions<T>, "disclosure">,
+    CompositeStoreOptions,
+    HovercardStoreOptions {
+  /**
+   * A callback that gets called when the
+   * [`values`](https://ariakit.com/reference/menu-provider#values) state
+   * changes.
+   *
+   * Live examples:
+   * - [MenuItemCheckbox](https://ariakit.com/examples/menu-item-checkbox)
+   * - [Submenu with
+   *   Combobox](https://ariakit.com/examples/menu-nested-combobox)
+   */
+  setValues?: BivariantCallback<(values: MenuStoreState<T>["values"]) => void>;
+  /**
+   * A reference to a [combobox
+   * store](https://ariakit.com/reference/use-combobox-store). It's
+   * automatically set when composing [Menu with
+   * Combobox](https://ariakit.com/examples/menu-combobox).
+   */
+  combobox?: ComboboxStore | null;
+  /**
+   * A reference to a parent menu store. It's automatically set when nesting
+   * menus in the React tree. You should manually set this if menus aren't
+   * nested in the React tree.
+   *
+   * Live examples:
+   * - [Menubar](https://ariakit.com/components/menubar)
+   * - [Submenu](https://ariakit.com/examples/menu-nested)
+   * - [Navigation Menubar](https://ariakit.com/examples/menubar-navigation)
+   */
+  parent?: MenuStore | null;
+  /**
+   * A reference to a [menubar
+   * store](https://ariakit.com/reference/use-menubar-store). It's automatically
+   * set when rendering menus inside a
+   * [`Menubar`](https://ariakit.com/reference/menubar) in the React tree.
+   *
+   * Live examples:
+   * - [Navigation Menubar](https://ariakit.com/examples/menubar-navigation)
+   */
+  menubar?: MenubarStore | null;
+}
+
+export interface MenuStoreProps<T extends MenuStoreValues = MenuStoreValues>
+  extends
+    MenuStoreOptions<T>,
+    Omit<
+      Core.MenuStoreProps<T>,
+      "combobox" | "parent" | "menubar" | "disclosure"
+    > {}
+
+export interface MenuStore<T extends MenuStoreValues = MenuStoreValues>
+  extends
+    MenuStoreFunctions<T>,
+    Omit<
+      Store<Core.MenuStore<T>>,
+      "combobox" | "parent" | "menubar" | "disclosure"
+    > {}

package/src/menu/menu.tsx

@@ -0,0 +1,274 @@
+import { useStoreState } from "@ariakit/react-store";
+import {
+  useMergeRefs,
+  createElement,
+  createHook,
+  forwardRef,
+} from "@ariakit/react-utils";
+import type { Props } from "@ariakit/react-utils";
+import {
+  fireEvent,
+  hasFocusWithin,
+  invariant,
+  isFalsyBooleanCallback,
+} from "@ariakit/utils";
+import type { ElementType, MutableRefObject } from "react";
+import { createRef, useEffect, useMemo, useRef, useState } from "react";
+import { createDialogComponent } from "../dialog/dialog.tsx";
+import type { HovercardOptions } from "../hovercard/hovercard.tsx";
+import { useHovercard } from "../hovercard/hovercard.tsx";
+import { useMenuProviderContext } from "./menu-context.tsx";
+import type { MenuListOptions } from "./menu-list.tsx";
+import { useMenuList } from "./menu-list.tsx";
+
+const TagName = "div" satisfies ElementType;
+type TagName = typeof TagName;
+type HTMLType = HTMLElementTagNameMap[TagName];
+
+/**
+ * Returns props to create a `Menu` component.
+ * @see https://ariakit.com/components/menu
+ * @example
+ * ```jsx
+ * const store = useMenuStore();
+ * const props = useMenu({ store });
+ * <MenuButton store={store}>Edit</MenuButton>
+ * <Role {...props}>
+ *   <MenuItem>Undo</MenuItem>
+ *   <MenuItem>Redo</MenuItem>
+ * </Role>
+ * ```
+ */
+export const useMenu = createHook<TagName, MenuOptions>(function useMenu({
+  store,
+  modal: modalProp = false,
+  portal = modalProp,
+  hideOnEscape = true,
+  autoFocusOnShow = true,
+  hideOnHoverOutside,
+  alwaysVisible,
+  ...props
+}) {
+  const context = useMenuProviderContext();
+  store = store || context;
+
+  invariant(
+    store,
+    process.env.NODE_ENV !== "production" &&
+      "Menu must receive a `store` prop or be wrapped in a MenuProvider component.",
+  );
+
+  const ref = useRef<HTMLType>(null);
+
+  const parentMenu = store.parent;
+  const parentMenubar = store.menubar;
+  const hasParentMenu = !!parentMenu;
+  const parentIsMenubar = !!parentMenubar && !hasParentMenu;
+  // If it's a submenu, it shouldn't behave like a modal dialog.
+  const modal = hasParentMenu ? false : modalProp;
+
+  props = {
+    ...props,
+    ref: useMergeRefs(ref, props.ref),
+  };
+
+  // The aria-labelledby prop on MenuList defaults to the MenuButton's id. On
+  // Dialog/Popover/Hovercard/Menu, we need to consider MenuHeading as well
+  // and it should take precedence. That's why we need to destructure this
+  // prop here and check if aria-labelledby is set later.
+  const { "aria-labelledby": ariaLabelledBy, ...menuListProps } = useMenuList({
+    store,
+    alwaysVisible,
+    ...props,
+  });
+
+  props = menuListProps;
+
+  const [initialFocusRef, setInitialFocusRef] =
+    useState<MutableRefObject<HTMLElement | null>>();
+
+  const autoFocusOnShowState = useStoreState(store, "autoFocusOnShow");
+  const initialFocus = useStoreState(store, "initialFocus");
+  const baseElement = useStoreState(store, "baseElement");
+  const items = useStoreState(store, "renderedItems");
+
+  // Sets the initial focus ref.
+  useEffect(() => {
+    let cleaning = false;
+    setInitialFocusRef((prevInitialFocusRef) => {
+      if (cleaning) return;
+      if (modal && prevInitialFocusRef?.current?.isConnected) {
+        return prevInitialFocusRef;
+      }
+      if (!autoFocusOnShowState) return;
+      let element: HTMLElement | null;
+      switch (initialFocus) {
+        // TODO: Refactor
+        case "first":
+          element =
+            items.find((item) => !item.disabled && item.element)?.element ||
+            null;
+          break;
+        case "last":
+          element =
+            [...items].reverse().find((item) => !item.disabled && item.element)
+              ?.element || null;
+          break;
+        default:
+          element = baseElement;
+      }
+      if (element && element === prevInitialFocusRef?.current) {
+        return prevInitialFocusRef;
+      }
+      const ref = createRef() as MutableRefObject<HTMLElement | null>;
+      ref.current = element;
+      return ref;
+    });
+    return () => {
+      cleaning = true;
+    };
+  }, [store, modal, autoFocusOnShowState, initialFocus, items, baseElement]);
+
+  // When the `autoFocusOnShow` prop is set to `true` (default), we'll only
+  // move focus to the menu when there's an initialFocusRef set or the menu is
+  // modal. Otherwise, users would have to manually call
+  // store.setAutoFocusOnShow(true) every time they want to open the menu.
+  // This differs from the usual dialog behavior that would automatically
+  // focus on the dialog container when no initialFocusRef is set.
+  const canAutoFocusOnShow = !!initialFocusRef || !!props.initialFocus || modal;
+  const autoFocusOnShowProp =
+    autoFocusOnShow === false ? false : canAutoFocusOnShow && autoFocusOnShow;
+
+  const contentElement = useStoreState(
+    store.combobox || store,
+    "contentElement",
+  );
+  const parentContentElement = useStoreState(
+    parentMenu?.combobox || parentMenu,
+    "contentElement",
+  );
+
+  // This ensures that, when the menu is nested in a non-menu wrapper, the tab
+  // order will be preserved from the parent content element rather than from
+  // the anchor element. This is because the preserveTabOrderAnchor feature
+  // will use aria-owns to fix the tab order on screen readers. The parent
+  // content element may have a role that does not allow this menu's role as a
+  // child. By passing the parent content element as the tab order anchor, the
+  // aria-owns element will be added as a sibling instead. TODO: Test this.
+  const preserveTabOrderAnchor = useMemo(() => {
+    if (!parentContentElement) return;
+    if (!contentElement) return;
+    const role = contentElement.getAttribute("role");
+    const parentRole = parentContentElement.getAttribute("role");
+    const parentIsMenuOrMenubar =
+      parentRole === "menu" || parentRole === "menubar";
+    if (parentIsMenuOrMenubar && role === "menu") return;
+    return parentContentElement;
+  }, [contentElement, parentContentElement]);
+
+  if (preserveTabOrderAnchor !== undefined) {
+    props = {
+      preserveTabOrderAnchor,
+      ...props,
+    };
+  }
+
+  props = useHovercard({
+    store,
+    alwaysVisible,
+    initialFocus: initialFocusRef,
+    autoFocusOnShow: autoFocusOnShowProp,
+    ...props,
+    hideOnEscape(event) {
+      if (isFalsyBooleanCallback(hideOnEscape, event)) return false;
+      store?.hideAll();
+      return true;
+    },
+    hideOnHoverOutside(event) {
+      const disclosureElement = store?.getState().disclosureElement;
+      const getHideOnHoverOutside = () => {
+        if (typeof hideOnHoverOutside === "function") {
+          return hideOnHoverOutside(event);
+        }
+        if (hideOnHoverOutside != null) return hideOnHoverOutside;
+        // Hide the menu when hovering outside if it's a submenu in a dropdown
+        // menu or if it's a menu in a menubar and the menu button doesn't
+        // have focus.
+        if (hasParentMenu) return true;
+        if (!parentIsMenubar) return false;
+        if (!disclosureElement) return true;
+        if (hasFocusWithin(disclosureElement)) return false;
+        return true;
+      };
+      if (!getHideOnHoverOutside()) return false;
+      if (event.defaultPrevented) return true;
+      if (!hasParentMenu) return true;
+      if (!disclosureElement) return true;
+      // This can be tested by hovering over a menu item (that's also a menu
+      // button), waiting for the menu to open, and then moving towards the
+      // menu, but stopping before reaching it. Then, move the mouse to the
+      // other direction. The menu should close, but since we've already left
+      // the menu button, the mouseout and therefore the blurOnHoverEnd
+      // behavior won't be fired. That's why we need to manually re-fire it
+      // here when the menu is closed by hovering away.
+      fireEvent(disclosureElement, "mouseout", event);
+      if (!hasFocusWithin(disclosureElement)) return true;
+      // When the focus is determined by the aria-activedescendant attribute
+      // (virtual focus), the mouseout event above won't update the state
+      // synchronously. That is, the hasFocusWithin function above (which also
+      // takes into account aria-activedescendant) will be true even though
+      // the mouseout event has blurred the menu button.
+      requestAnimationFrame(() => {
+        if (hasFocusWithin(disclosureElement)) return;
+        store?.hide();
+      });
+      return false;
+    },
+    modal,
+    portal,
+    backdrop: hasParentMenu ? false : props.backdrop,
+  });
+
+  props = {
+    "aria-labelledby": ariaLabelledBy,
+    ...props,
+  };
+
+  return props;
+});
+
+/**
+ * Renders a dropdown menu element that's controlled by a
+ * [`MenuButton`](https://ariakit.com/reference/menu-button) component.
+ *
+ * This component uses the primitive
+ * [`MenuList`](https://ariakit.com/reference/menu-list) component under the
+ * hood. It renders a popover and automatically focuses on items when the menu
+ * is shown.
+ * @see https://ariakit.com/components/menu
+ * @example
+ * ```jsx {3-6}
+ * <MenuProvider>
+ *   <MenuButton>Edit</MenuButton>
+ *   <Menu>
+ *     <MenuItem>Undo</MenuItem>
+ *     <MenuItem>Redo</MenuItem>
+ *   </Menu>
+ * </MenuProvider>
+ * ```
+ */
+export const Menu = createDialogComponent(
+  forwardRef(function Menu(props: MenuProps) {
+    const htmlProps = useMenu(props);
+    return createElement(TagName, htmlProps);
+  }),
+  useMenuProviderContext,
+);
+
+export interface MenuOptions<T extends ElementType = TagName>
+  extends MenuListOptions<T>, Omit<HovercardOptions<T>, "store"> {}
+
+export type MenuProps<T extends ElementType = TagName> = Props<
+  T,
+  MenuOptions<T>
+>;

package/src/menubar/menubar-context.tsx

@@ -0,0 +1,39 @@
+import { createStoreContext } from "@ariakit/react-utils";
+import { createContext } from "react";
+import {
+  CompositeContextProvider,
+  CompositeScopedContextProvider,
+} from "../composite/composite-context.tsx";
+import type { MenubarStore } from "./menubar-store.ts";
+
+const menubar = createStoreContext<MenubarStore>(
+  [CompositeContextProvider],
+  [CompositeScopedContextProvider],
+);
+
+/**
+ * Returns the menubar store from the nearest menubar container.
+ * @example
+ * function Menubar() {
+ *   const store = useMenubarContext();
+ *
+ *   if (!store) {
+ *     throw new Error("Menubar must be wrapped in MenubarProvider");
+ *   }
+ *
+ *   // Use the store...
+ * }
+ */
+export const useMenubarContext = menubar.useContext;
+
+export const useMenubarScopedContext = menubar.useScopedContext;
+
+export const useMenubarProviderContext = menubar.useProviderContext;
+
+export const MenubarContextProvider = menubar.ContextProvider;
+
+export const MenubarScopedContextProvider = menubar.ScopedContextProvider;
+
+export const MenuItemCheckedContext = createContext<boolean | undefined>(
+  undefined,
+);

package/src/menubar/menubar-provider.tsx

@@ -0,0 +1,43 @@
+import type { ReactNode } from "react";
+import { MenubarContextProvider } from "./menubar-context.tsx";
+import type { MenubarStoreProps } from "./menubar-store.ts";
+import { useMenubarStore } from "./menubar-store.ts";
+
+/**
+ * Provides a menubar store to [Menubar](https://ariakit.com/components/menubar)
+ * components.
+ * @see https://ariakit.com/components/menubar
+ * @example
+ * ```jsx
+ * <MenubarProvider>
+ *   <Menubar>
+ *     <MenuProvider>
+ *       <MenuItem render={<MenuButton />}>File</MenuItem>
+ *       <Menu>
+ *         <MenuItem>New File</MenuItem>
+ *         <MenuItem>New Window</MenuItem>
+ *       </Menu>
+ *     </MenuProvider>
+ *     <MenuProvider>
+ *       <MenuItem render={<MenuButton />}>Edit</MenuItem>
+ *       <Menu>
+ *         <MenuItem>Undo</MenuItem>
+ *         <MenuItem>Redo</MenuItem>
+ *       </Menu>
+ *     </MenuProvider>
+ *   </Menubar>
+ * </MenubarProvider>
+ * ```
+ */
+export function MenubarProvider(props: MenubarProviderProps = {}) {
+  const store = useMenubarStore(props);
+  return (
+    <MenubarContextProvider value={store}>
+      {props.children}
+    </MenubarContextProvider>
+  );
+}
+
+export interface MenubarProviderProps extends MenubarStoreProps {
+  children?: ReactNode;
+}

package/src/menubar/menubar-store.ts

@@ -0,0 +1,48 @@
+import * as Core from "@ariakit/components/menubar/menubar-store";
+import { useStore } from "@ariakit/react-store";
+import type { Store } from "@ariakit/react-store";
+import type {
+  CompositeStoreFunctions,
+  CompositeStoreOptions,
+  CompositeStoreState,
+} from "../composite/composite-store.ts";
+import { useCompositeStoreProps } from "../composite/composite-store.ts";
+
+export function useMenubarStoreProps<T extends Core.MenubarStore>(
+  store: T,
+  update: () => void,
+  props: MenubarStoreProps,
+) {
+  return useCompositeStoreProps(store, update, props);
+}
+
+/**
+ * Creates a menubar store to control the state of
+ * [Menubar](https://ariakit.com/components/menubar) components.
+ * @see https://ariakit.com/components/menubar
+ * @example
+ * ```jsx
+ * const menu = useMenubarStore();
+ *
+ * <Menubar store={menu} />
+ * ```
+ */
+export function useMenubarStore(props: MenubarStoreProps = {}): MenubarStore {
+  const [store, update] = useStore(Core.createMenubarStore, props);
+  return useMenubarStoreProps(store, update, props);
+}
+
+export interface MenubarStoreState
+  extends Core.MenubarStoreState, CompositeStoreState {}
+
+export interface MenubarStoreFunctions
+  extends Core.MenubarStoreFunctions, CompositeStoreFunctions {}
+
+export interface MenubarStoreOptions
+  extends Core.MenubarStoreOptions, CompositeStoreOptions {}
+
+export interface MenubarStoreProps
+  extends MenubarStoreOptions, Core.MenubarStoreProps {}
+
+export interface MenubarStore
+  extends MenubarStoreFunctions, Store<Core.MenubarStore> {}