@uniflowed/ui 0.0.0-alpha.4 → 0.0.0-alpha.41

package/menu.js

@@ -15,10 +15,36 @@
 //   * `Escape` closes *this* menu — the submenu if one is open, not the whole
 //     tree — and gives focus back to what opened it.
 //   * `ArrowRight` opens a submenu and lands on its first item; `ArrowLeft`
-//     closes it and comes back to the item that opened it.
+//     closes it and comes back to the item that opened it — and the two swap in
+//     a right-to-left page, because a submenu opens onto the *inline end*.
 //   * `Tab` closes the menu and carries on through the page, rather than
 //     walking the reader through thirty items they have already dismissed.
 //
+// # This is shadcn's Dropdown Menu
+//
+// Under that name it is a fourth component; here it is this one. A dropdown
+// menu is a menu whose trigger is a button, which is what `Menu.Trigger` is, so
+// there is no second module and no alias export — a second spelling of a
+// component is a second surface to keep in step, and `index.js` argues against
+// one at greater length. `context-menu.js` and `menubar.js` are the two that
+// genuinely differ, and each of their headers says in what.
+//
+// # Choosing an item, and the item that should not close the menu
+//
+// `onSelect` receives the click and may answer it. `preventDefault()` means "I
+// handled this and the menu stays open", which is the contract
+// `internal/merge-props.js` already uses between a caller's handler and a
+// component's, and the one Radix settled on for this exact question. A
+// `closeOnSelect` prop is the same answer given once for a part rather than per
+// press.
+//
+// The defaults differ between the item kinds because the platform's do. A
+// command closes the menu — running it and leaving the menu open is a state no
+// native menu has been in. A *checkable* item does not: "show hidden files"
+// toggled three times is one visit to the menu everywhere except in a component
+// library, and a checkbox that closed the menu would make checking three boxes
+// mean opening the menu three times.
+//
 // # Focus moves; `aria-activedescendant` does not appear here
 //
 // A menu moves *real* DOM focus onto its items. That is what WAI-ARIA
@@ -38,6 +64,27 @@
 // were aiming at. Keyboard and click open a submenu; a deliberate hover
 // implementation is tracked work, not a line to be added carelessly.
 //
+// # Where the menu goes
+//
+// `internal/anchor.js`, the same module `Popover.Body` uses, and adopting it
+// here rather than writing a second one is most of ubugeeei-prod/uf#256. Two
+// things about a menu were wrong before it and are worth naming, because
+// neither looks like a positioning bug:
+//
+//   * A menu in a table row, a card, or anything else with `overflow: hidden`
+//     was cut off at that box's edge. It is `position: fixed` now, so the
+//     clipping ancestor is not its business.
+//   * A menu whose trigger sat near the bottom of the page opened downwards,
+//     off the screen, and the reader saw nothing at all.
+//
+// A submenu asks for `side="inline-end"` rather than `right`, which is the same
+// answer `submenuKeys` gives about the *keys*: the submenu opens the way the
+// page reads, and the arrow that opens it points at where it went.
+//
+// A context menu opens at a point instead, which is the one thing the
+// positioner did not do; `internal/menu-tree.js` carries that rectangle and
+// `internal/anchor.js` says what it replaces.
+//
 // # Items are found in the document, not in a registry
 //
 // `internal/roving-focus.js` explains why. The short version is that mount
@@ -49,6 +96,7 @@
 import * as React from "@uniflowed/react";
 import {
   createContext,
+  useCallback,
   useContext,
   useEffect,
   useId,
@@ -58,8 +106,19 @@ import {
 } from "@uniflowed/react";
 import { useStableCallback } from "@uniflowed/hooks/lifecycle";
 
-import { composeHandlers, composeRefs, withoutComposed } from "./internal/merge-props.js";
+import { useInteractOutside } from "./interactions.js";
+
+import type { Align, LogicalSide } from "./internal/anchor.js";
+import { useAnchor } from "./internal/anchor.js";
+import type { PartEvent, RenderProp, Rest } from "./internal/merge-props.js";
 import {
+  composeHandlers,
+  composeRefs,
+  withProps,
+  withoutComposed,
+} from "./internal/merge-props.js";
+import {
+  directionOf,
   indexOfActive,
   isTypeaheadKey,
   itemsOf,
@@ -68,61 +127,35 @@ import {
   useTypeahead,
 } from "./internal/roving-focus.js";
 import { useControlled } from "./internal/controlled-state.js";
+import {
+  ITEM_SELECTOR,
+  MENU_SELECTOR,
+  MenuAnchorContext,
+  MenuContext,
+  MenuLevel,
+  MenuListContext,
+  closeTree,
+  submenuKeys,
+  useMenu,
+  useTriggerRegistration,
+} from "./internal/menu-tree.js";
+
+export type { Align, LogicalSide, Side } from "./internal/anchor.js";
 
 /**
- * Anything that plays the part of a menu item, including the two checkable
- * kinds a caller may write themselves. The keyboard has to move between all of
- * them, so the selector names all of them rather than only what this package
- * ships.
- */
-const ITEM_SELECTOR = '[role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"]';
-
-/** What owns an item: the nearest menu, so a submenu keeps its own. */
-const MENU_SELECTOR = '[role="menu"]';
-
-type MenuState = {|
-  readonly base: string,
-  readonly open: boolean,
-  readonly setOpen: (open: boolean) => void,
-  /** What opened this menu, and what focus goes back to when it closes. */
-  readonly triggerRef: { current: HTMLElement | null },
-  /**
-   * Which end the menu should open onto, written by whatever opened it.
-   *
-   * A ref rather than state because it is an instruction for the next commit,
-   * not a value anything renders: `ArrowUp` on a closed menu opens it *and*
-   * lands on the last item, and re-rendering the trigger to say so would be a
-   * render whose only purpose is to carry a message to an effect.
-   */
-  readonly pendingFocus: { current: "first" | "last" | null },
-  /** The menu this one hangs off, or null for the outermost. */
-  readonly parent: MenuState | null,
-  /**
-   * Whether a trigger is rendered, so the body only names one that exists.
-   *
-   * A menu opened by `defaultOpen` in a page that never renders a trigger is a
-   * real arrangement, and an `aria-labelledby` pointing at the id that trigger
-   * *would* have had makes a screen reader announce nothing at all.
-   */
-  readonly triggered: boolean,
-  readonly registerTrigger: (present: boolean) => void,
-|};
-
-const MenuContext: React.Context<MenuState | null> = createContext(null);
-
-/**
- * The roving tab stop of one open menu.
+ * The part of a click a menu item's `onSelect` may read and answer.
  *
- * Provided by `Menu.Body` rather than by the root, because a submenu is a
- * second list with a tab stop of its own: nesting the provider is what stops
- * the parent menu and the submenu from fighting over which item is `tabindex=0`.
+ * Inexact, because what arrives is React's synthetic event and this names only
+ * the two members the contract is about: calling `preventDefault()` keeps the
+ * menu open, and the component reads `defaultPrevented` afterwards to find out.
+ * A caller who wants the rest of the event has it — this is the promise, not
+ * the object.
  */
-type MenuListState = {|
-  readonly activeId: string | null,
-  readonly setActiveId: (id: string | null) => void,
-|};
-
-const MenuListContext: React.Context<MenuListState | null> = createContext(null);
+export type MenuSelect = {
+  readonly defaultPrevented: boolean,
+  readonly preventDefault: () => mixed,
+  ...
+};
 
 /** The id of a group's label, so `Menu.Group` only claims one that exists. */
 type MenuGroupState = {|
@@ -132,54 +165,13 @@ type MenuGroupState = {|
 
 const MenuGroupContext: React.Context<MenuGroupState | null> = createContext(null);
 
-hook useMenu(part: string): MenuState {
-  const state = useContext(MenuContext);
-  if (state == null) {
-    throw new Error(`${part} must be rendered inside a Menu.Root`);
-  }
-  return state;
-}
-
-/**
- * Tell the menu that a trigger for it is in the document.
- *
- * `Menu.Body` names its trigger with `aria-labelledby`, and it may only do that
- * while there is one to name — a menu opened by `defaultOpen` in a page with no
- * trigger would otherwise point at an id nothing has, and a screen reader given
- * a dangling `aria-labelledby` announces nothing at all rather than falling back
- * to the element's own content.
- */
-hook useTriggerRegistration(menu: MenuState): void {
-  const register = menu.registerTrigger;
-  useEffect(() => {
-    register(true);
-    return () => register(false);
-  }, [register]);
-}
-
-/** Every menu from `menu` outwards, innermost first. */
-function ancestry(menu: MenuState): Array<MenuState> {
-  const chain = [];
-  let at: MenuState | null = menu;
-  while (at != null) {
-    chain.push(at);
-    at = at.parent;
-  }
-  return chain;
-}
+/** What a `Menu.RadioGroup` tells the items inside it. */
+type MenuRadioState = {|
+  readonly value: string | null,
+  readonly choose: (value: string) => void,
+|};
 
-/**
- * Close this menu and every menu it hangs off.
- *
- * Choosing an item in a submenu dismisses the whole thing — leaving the parent
- * menu open after a command has run is a state no native menu has ever been in,
- * and it leaves the reader looking at a menu whose action already happened.
- */
-function closeTree(menu: MenuState): void {
-  for (const each of ancestry(menu)) {
-    each.setOpen(false);
-  }
-}
+const MenuRadioContext: React.Context<MenuRadioState | null> = createContext(null);
 
 /**
  * A menu and its trigger.
@@ -225,77 +217,48 @@ export component MenuSub(
   );
 }
 
-/** One level of the menu tree. Shared by `Menu.Root` and `Menu.Sub`. */
-component MenuLevel(
-  children: React.Node,
-  parent: MenuState | null,
-  defaultOpen: boolean,
-  open?: boolean,
-  onOpenChange?: (open: boolean) => void,
-) {
-  const base = useId();
-  const [isOpen, setOpen] = useControlled(open, defaultOpen, onOpenChange);
-  const triggerRef = useRef<HTMLElement | null>(null);
-  const pendingFocus = useRef<"first" | "last" | null>(null);
-  const [triggered, setTriggered] = useState(false);
-
-  const state = useMemo(
-    () => ({
-      base,
-      open: isOpen,
-      setOpen,
-      triggerRef,
-      pendingFocus,
-      parent,
-      triggered,
-      registerTrigger: setTriggered,
-    }),
-    [base, isOpen, setOpen, parent, triggered],
-  );
-
-  return <MenuContext.Provider value={state}>{children}</MenuContext.Provider>;
-}
-
 /** The button that opens the menu. */
-export component MenuTrigger(children: React.Node, ...rest: { readonly [string]: mixed }) {
+export component MenuTrigger(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const menu = useMenu("Menu.Trigger");
-  const passed = withoutComposed(rest, ["onClick", "onKeyDown", "ref"]);
   useTriggerRegistration(menu);
+  const props = withProps(withoutComposed(rest, ["onClick", "onKeyDown", "ref"]), {
+    // Named only while the menu is in the document, so a reader is never told
+    // to go somewhere that is not there.
+    "aria-controls": menu.open ? `${menu.base}-body` : undefined,
+    "aria-expanded": menu.open ? "true" : "false",
+    "aria-haspopup": "menu",
+    children,
+    id: `${menu.base}-trigger`,
+    onClick: composeHandlers(rest.onClick, () => menu.setOpen(!menu.open)),
+    onKeyDown: composeHandlers(rest.onKeyDown, (event: PartEvent) => {
+      // `ArrowUp` opening onto the *last* item is the behaviour that makes a
+      // long menu usable: the last entry is usually the destructive one, and
+      // reaching it should not mean arrowing past everything else.
+      const end = match (event.key) {
+        "ArrowDown" => "first",
+        "ArrowUp" => "last",
+        _ => null,
+      };
+      if (end == null) {
+        return;
+      }
+      event.preventDefault();
+      // This is an instruction for the menu body after the opening commit.
+      // uf-lint-disable-next-line react-compiler/immutability
+      menu.pendingFocusRef.current = end;
+      menu.setOpen(true);
+    }),
+    ref: composeRefs(rest.ref, (element: HTMLElement | null) => {
+      // React calls callback refs during commit; the menu body reads the trigger later.
+      // uf-lint-disable-next-line react-compiler/immutability
+      menu.triggerRef.current = element;
+    }),
+  });
 
-  return (
-    <button
-      {...passed}
-      // Named only while the menu is in the document, so a reader is never told
-      // to go somewhere that is not there.
-      aria-controls={menu.open ? `${menu.base}-body` : undefined}
-      aria-expanded={menu.open ? "true" : "false"}
-      aria-haspopup="menu"
-      id={`${menu.base}-trigger`}
-      onClick={composeHandlers(rest.onClick, () => menu.setOpen(!menu.open))}
-      onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
-        // `ArrowUp` opening onto the *last* item is the behaviour that makes a
-        // long menu usable: the last entry is usually the destructive one, and
-        // reaching it should not mean arrowing past everything else.
-        const end = match (event.key) {
-          "ArrowDown" => "first",
-          "ArrowUp" => "last",
-          _ => null,
-        };
-        if (end == null) {
-          return;
-        }
-        event.preventDefault();
-        menu.pendingFocus.current = end;
-        menu.setOpen(true);
-      })}
-      ref={composeRefs(rest.ref, (element) => {
-        menu.triggerRef.current = element;
-      })}
-      type="button"
-    >
-      {children}
-    </button>
-  );
+  if (render != null) {
+    return render(props);
+  }
+  return <button {...props} type="button" />;
 }
 
 /**
@@ -307,22 +270,64 @@ export component MenuTrigger(children: React.Node, ...rest: { readonly [string]:
  * `Space` from being buttons.
  */
 export component MenuBody(
-  children: renders* (MenuItem | MenuSeparator | MenuGroup | MenuSub),
-  ...rest: { readonly [string]: mixed }
+  children: renders* (
+    | MenuItem
+    | MenuCheckboxItem
+    | MenuRadioGroup
+    | MenuSeparator
+    | MenuGroup
+    | MenuSub
+  ),
+  align?: Align = "start",
+  alignOffset?: number = 0,
+  avoidCollisions?: boolean = true,
+  collisionPadding?: number = 0,
+  side?: LogicalSide,
+  sideOffset?: number = 0,
+  render?: RenderProp,
+  ...rest: Rest
 ) {
   const menu = useMenu("Menu.Body");
   const bodyRef = useRef<HTMLElement | null>(null);
   const [activeId, setActiveId] = useState<string | null>(null);
   const typeahead = useTypeahead();
+  // A point to open at, when whatever opened this menu was a pointer rather
+  // than a button. Null for every menu that hangs off a trigger.
+  const point = useContext(MenuAnchorContext);
 
   // Pulled out because they are stable for the life of the menu, which is what
   // lets the effect below depend on `open` alone. Keyed on the context object
   // it re-ran on every parent render and re-took focus each time, dragging the
   // reader back to the first item while they were arrowing.
   const triggerRef = menu.triggerRef;
-  const pendingFocus = menu.pendingFocus;
+  const pendingFocusRef = menu.pendingFocusRef;
+  // `parent` is menu-tree metadata; no ref value is read during render.
+  // uf-lint-disable-next-line react-compiler/refs
   const isRoot = menu.parent == null;
   const closeAll = useStableCallback(() => closeTree(menu));
+  // A root menu drops from its button; a submenu comes out of the side of the
+  // item that opened it, on the side the page reads towards. The default cannot
+  // be a parameter default because it is not a constant: it is the answer to
+  // "is this the outermost menu", which only this component knows.
+  const placement = side ?? (isRoot ? "bottom" : "inline-end");
+  // useAnchor accepts ref objects and reads them from layout/effects.
+  // uf-lint-disable-next-line react-compiler/refs
+  const anchored = useAnchor({
+    align,
+    alignOffset,
+    anchorRect: point,
+    // uf-lint-disable-next-line react-compiler/refs
+    anchorRef: triggerRef,
+    avoidCollisions,
+    collisionPadding,
+    // `open` is menu-tree metadata; no ref value is read during render.
+    // uf-lint-disable-next-line react-compiler/refs
+    open: menu.open,
+    // uf-lint-disable-next-line react-compiler/refs
+    overlayRef: bodyRef,
+    side: placement,
+    sideOffset,
+  });
   // Set when the menu was dismissed by a press somewhere else, so the cleanup
   // knows not to drag focus back to the trigger the reader just left.
   const dismissed = useRef(false);
@@ -335,8 +340,8 @@ export component MenuBody(
     const document = body.ownerDocument;
     const trigger = triggerRef.current;
 
-    const wanted = pendingFocus.current;
-    pendingFocus.current = null;
+    const wanted = pendingFocusRef.current;
+    pendingFocusRef.current = null;
     const items = itemsOf(body, ITEM_SELECTOR, MENU_SELECTOR);
     const landing = moveTo(items, -1, wanted === "last" ? "last" : "first", false);
     // The menu itself when it holds nothing focusable, so focus is inside it
@@ -346,30 +351,7 @@ export component MenuBody(
       setActiveId(landing.id);
     }
 
-    const onOutsidePress = (event: Event) => {
-      const target: $FlowFixMe = event.target;
-      if (target == null || body.contains(target)) {
-        return;
-      }
-      // The trigger is outside the menu and is not "outside" for this purpose:
-      // closing here and letting the trigger's own click reopen made a press on
-      // the trigger a no-op that flickered.
-      if (trigger != null && trigger.contains(target)) {
-        return;
-      }
-      dismissed.current = true;
-      closeAll();
-    };
-    // Only the outermost menu listens. A submenu closes with the tree, and two
-    // listeners would each answer the same press.
-    if (isRoot) {
-      document.addEventListener("pointerdown", onOutsidePress, true);
-    }
-
     return () => {
-      if (isRoot) {
-        document.removeEventListener("pointerdown", onOutsidePress, true);
-      }
       if (dismissed.current) {
         dismissed.current = false;
         return;
@@ -382,92 +364,171 @@ export component MenuBody(
         trigger?.focus?.();
       }
     };
-  }, [menu.open, isRoot, triggerRef, pendingFocus, closeAll]);
+    // The ref objects are stable; this effect reads them after the opening commit.
+    // uf-lint-disable-next-line react-compiler/refs
+  }, [menu.open, triggerRef, pendingFocusRef]);
+
+  // Only the outermost menu listens. A submenu closes with the tree, and two
+  // of these would each answer the same press.
+  // The outside-interaction hook accepts refs; it reads them from event handlers.
+  // uf-lint-disable-next-line react-compiler/refs
+  useInteractOutside({
+    // `open` is menu-tree metadata; the hook reads refs from event handlers.
+    // uf-lint-disable-next-line react-compiler/refs
+    isDisabled: !menu.open || !isRoot,
+    onInteractOutside: () => {
+      dismissed.current = true;
+      closeAll();
+    },
+    // uf-lint-disable-next-line react-compiler/refs
+    refs: [bodyRef, triggerRef],
+  });
 
   const list = useMemo(() => ({ activeId, setActiveId }), [activeId]);
 
+  // `open` is menu-tree metadata; no ref value is read during render.
+  // uf-lint-disable-next-line react-compiler/refs
   if (!menu.open) {
     return null;
   }
 
-  const passed = withoutComposed(rest, ["onKeyDown", "ref"]);
+  const props = withProps(withoutComposed(rest, ["onKeyDown", "ref"]), {
+    // `triggered` and `base` are menu-tree metadata, not ref values.
+    // uf-lint-disable-next-line react-compiler/refs
+    "aria-labelledby": menu.triggered ? `${menu.base}-trigger` : undefined,
+    "aria-orientation": "vertical",
+    children,
+    "data-align": anchored.align,
+    "data-side": anchored.side,
+    // `base` is menu-tree metadata, not a ref value.
+    // uf-lint-disable-next-line react-compiler/refs
+    id: `${menu.base}-body`,
+    // Key handling moves real DOM focus and records the active item after events.
+    // uf-lint-disable-next-line react-compiler/refs
+    onKeyDown: composeHandlers(rest.onKeyDown, (event: PartEvent) => {
+      const body: $FlowFixMe = event.currentTarget;
+      const items = itemsOf(body, ITEM_SELECTOR, MENU_SELECTOR);
+      const at = indexOfActive(items, body.ownerDocument?.activeElement);
+
+      if (event.key === "Escape") {
+        event.preventDefault();
+        // This menu, not the one behind it and not the dialog around it.
+        // A submenu is a DOM descendant of its parent menu, so without this
+        // one Escape closed the whole tree at once.
+        event.stopPropagation();
+        menu.setOpen(false);
+        return;
+      }
+
+      if (event.key === "Tab") {
+        // Not prevented: the browser should carry on to the next control,
+        // which is what makes Tab a way *past* a menu rather than a way
+        // through its thirty items.
+        event.stopPropagation();
+        closeAll();
+        return;
+      }
+
+      // Asked once, here, and used for both questions below: which key
+      // closes this submenu, and — for a menu a caller has laid out
+      // horizontally one day — which way the arrows run.
+      const direction = directionOf(body);
+
+      if (!isRoot && event.key === submenuKeys(direction).close) {
+        event.preventDefault();
+        event.stopPropagation();
+        menu.setOpen(false);
+        return;
+      }
+
+      const movement = movementFor(event.key, "vertical", direction);
+      if (movement != null) {
+        // Before moving, or the arrow also scrolls the page under the item
+        // that just took focus.
+        event.preventDefault();
+        event.stopPropagation();
+        const next = moveTo(items, at, movement, true);
+        if (next != null) {
+          next.focus();
+          setActiveId(next.id);
+        }
+        return;
+      }
+
+      if (isTypeaheadKey(event)) {
+        const next = typeahead(items, at, event.key);
+        if (next != null) {
+          event.preventDefault();
+          event.stopPropagation();
+          next.focus();
+          setActiveId(next.id);
+        }
+      }
+    }),
+    // React calls callback refs during commit; placement and keyboard effects read it later.
+    // uf-lint-disable-next-line react-compiler/refs
+    ref: composeRefs(rest.ref, (element: HTMLElement | null) => {
+      bodyRef.current = element;
+    }),
+    role: "menu",
+    // So the menu can hold focus itself when it is empty, and so a press on
+    // its padding does not send focus to `<body>`.
+    tabIndex: -1,
+  });
 
   return (
     <MenuListContext.Provider value={list}>
-      <div
-        {...passed}
-        aria-labelledby={menu.triggered ? `${menu.base}-trigger` : undefined}
-        aria-orientation="vertical"
-        id={`${menu.base}-body`}
-        onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
-          const body: $FlowFixMe = event.currentTarget;
-          const items = itemsOf(body, ITEM_SELECTOR, MENU_SELECTOR);
-          const at = indexOfActive(items, body.ownerDocument?.activeElement);
-
-          if (event.key === "Escape") {
-            event.preventDefault();
-            // This menu, not the one behind it and not the dialog around it.
-            // A submenu is a DOM descendant of its parent menu, so without this
-            // one Escape closed the whole tree at once.
-            event.stopPropagation();
-            menu.setOpen(false);
-            return;
-          }
-
-          if (event.key === "Tab") {
-            // Not prevented: the browser should carry on to the next control,
-            // which is what makes Tab a way *past* a menu rather than a way
-            // through its thirty items.
-            event.stopPropagation();
-            closeAll();
-            return;
-          }
-
-          if (!isRoot && event.key === "ArrowLeft") {
-            event.preventDefault();
-            event.stopPropagation();
-            menu.setOpen(false);
-            return;
-          }
-
-          const movement = movementFor(event.key, "vertical");
-          if (movement != null) {
-            // Before moving, or the arrow also scrolls the page under the item
-            // that just took focus.
-            event.preventDefault();
-            event.stopPropagation();
-            const next = moveTo(items, at, movement, true);
-            if (next != null) {
-              next.focus();
-              setActiveId(next.id);
-            }
-            return;
-          }
-
-          if (isTypeaheadKey(event)) {
-            const next = typeahead(items, at, event.key);
-            if (next != null) {
-              event.preventDefault();
-              event.stopPropagation();
-              next.focus();
-              setActiveId(next.id);
-            }
-          }
-        })}
-        ref={composeRefs(rest.ref, (element) => {
-          bodyRef.current = element;
-        })}
-        role="menu"
-        // So the menu can hold focus itself when it is empty, and so a press on
-        // its padding does not send focus to `<body>`.
-        tabIndex={-1}
-      >
-        {children}
-      </div>
+      {render == null ? <div {...props} /> : render(props)}
     </MenuListContext.Provider>
   );
 }
 
+/**
+ * Everything an item of any of the three kinds needs from the menu around it.
+ *
+ * One hook rather than three copies, because the three differ in their role and
+ * their state and in nothing else: the same id, the same roving tab stop, the
+ * same "a disabled item is announced and stepped over", and the same rule about
+ * when a press closes the tree.
+ */
+hook useMenuItem(
+  part: string,
+  disabled: boolean,
+  closeOnSelect: boolean,
+  onSelect: ((event: MenuSelect) => mixed) | void,
+  act: (() => void) | void,
+): {|
+  readonly id: string,
+  readonly onClick: (event: MenuSelect) => void,
+  readonly onFocus: () => void,
+  readonly tabIndex: number,
+|} {
+  const menu = useMenu(part);
+  const list = useContext(MenuListContext);
+  const id = useId();
+  const setActiveId = list?.setActiveId;
+
+  return {
+    id,
+    onClick: (event: MenuSelect) => {
+      if (disabled) {
+        return;
+      }
+      act?.();
+      onSelect?.(event);
+      // The caller's answer, read after they have had the event: a
+      // `preventDefault()` in `onSelect` is "I handled this, leave the menu
+      // open", which is the same sentence `composeHandlers` reads between a
+      // caller's handler and this package's.
+      if (closeOnSelect && !event.defaultPrevented) {
+        closeTree(menu);
+      }
+    },
+    onFocus: () => setActiveId?.(id),
+    tabIndex: list?.activeId === id ? 0 : -1,
+  };
+}
+
 /**
  * One command in the menu.
  *
@@ -476,44 +537,190 @@ export component MenuBody(
  * that the command exists and is unavailable, where a native `disabled` leaves
  * a silent gap they cannot ask about. The arrow keys and typeahead step over it
  * either way.
+ *
+ * `render` is what makes a menu of links possible, and a menu of links is the
+ * most ordinary menu there is:
+ *
+ *     <Menu.Item render={(props) => <a href="/settings" {...props} />}>
+ *       Settings
+ *     </Menu.Item>
+ *
+ * The `<a>` keeps everything a link is for — the middle click, the context
+ * menu, "open in new tab", the status bar showing where it goes — and the item
+ * keeps the id, the roving tab stop, the role and the press that closes the
+ * tree. That combination is what shadcn's copy step is usually reached for, and
+ * what this package offers instead of it.
  */
 export component MenuItem(
   children: React.Node,
   disabled?: boolean = false,
-  onSelect?: () => mixed,
-  ...rest: { readonly [string]: mixed }
+  closeOnSelect?: boolean = true,
+  onSelect?: (event: MenuSelect) => mixed,
+  render?: RenderProp,
+  ...rest: Rest
 ) {
-  const menu = useMenu("Menu.Item");
-  const list = useContext(MenuListContext);
-  const id = useId();
-  const passed = withoutComposed(rest, ["onClick", "onFocus"]);
-  const setActiveId = list?.setActiveId;
+  const item = useMenuItem("Menu.Item", disabled, closeOnSelect, onSelect, undefined);
+  const props = withProps(withoutComposed(rest, ["onClick", "onFocus"]), {
+    "aria-disabled": disabled ? "true" : undefined,
+    children,
+    id: item.id,
+    onClick: composeHandlers(rest.onClick, item.onClick),
+    // The roving tab stop follows real focus rather than leading it, so a
+    // pointer that moves focus and a key that moves focus agree without the
+    // two of them having to be kept in step by hand.
+    onFocus: composeHandlers(rest.onFocus, item.onFocus),
+    role: "menuitem",
+    tabIndex: item.tabIndex,
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+  return <button {...props} type="button" />;
+}
+
+/**
+ * An item that carries a state of its own: "show hidden files".
+ *
+ * `role="menuitemcheckbox"` with `aria-checked`, which is the role the arrow
+ * keys and the typeahead have always stepped across — `ITEM_SELECTOR` named it
+ * before there was a component that rendered it. What a caller could not
+ * hand-roll on `Menu.Item` is the rest: the controlled-and-uncontrolled
+ * contract `internal/controlled-state.js` states for everything here, and a
+ * press that does *not* dismiss the menu.
+ *
+ * There is no third state. `aria-checked="mixed"` belongs to a checkbox that
+ * summarises other checkboxes — `checkbox.js` has it, and a menu item is a
+ * command rather than a summary of a table's rows.
+ */
+export component MenuCheckboxItem(
+  children: React.Node,
+  checked?: boolean,
+  defaultChecked?: boolean = false,
+  onCheckedChange?: (checked: boolean) => void,
+  disabled?: boolean = false,
+  // A menu the reader is still ticking boxes in stays open; see the module
+  // header for why this default is the opposite of `Menu.Item`'s.
+  closeOnSelect?: boolean = false,
+  onSelect?: (event: MenuSelect) => mixed,
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const [on, setOn] = useControlled(checked, defaultChecked, onCheckedChange);
+  const toggle = useCallback(() => setOn(!on), [on, setOn]);
+  const item = useMenuItem("Menu.CheckboxItem", disabled, closeOnSelect, onSelect, toggle);
+  const props = withProps(withoutComposed(rest, ["onClick", "onFocus"]), {
+    "aria-checked": on ? "true" : "false",
+    "aria-disabled": disabled ? "true" : undefined,
+    children,
+    id: item.id,
+    onClick: composeHandlers(rest.onClick, item.onClick),
+    onFocus: composeHandlers(rest.onFocus, item.onFocus),
+    role: "menuitemcheckbox",
+    tabIndex: item.tabIndex,
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+  return <button {...props} type="button" />;
+}
+
+/**
+ * A set of items of which exactly one is chosen.
+ *
+ * The *group* owns the value, which is what makes this a component rather than
+ * a convention: `aria-checked="true"` has to be on one item and `"false"` on
+ * the others, and a caller holding a value per item gets two checked ones the
+ * first time a render is skipped. `role="group"` is what ties them together for
+ * a reader — the items are `menuitemradio`, and a reader is told "2 of 3".
+ *
+ * `onValueChange` promises a `string` while the state is `string | null`, for
+ * the reason `radio-group.js` gives at greater length: "nothing chosen yet" is
+ * a state the group starts in and never an event it reports, because no gesture
+ * inside it unchooses an answer.
+ */
+export component MenuRadioGroup(
+  children: renders* (MenuRadioItem | MenuLabel | MenuSeparator),
+  defaultValue?: string | null = null,
+  value?: string | null,
+  onValueChange?: (value: string) => void,
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const base = useId();
+  const [labelled, setLabelled] = useState(false);
+  const report = useCallback(
+    (next: string | null) => {
+      if (next != null) {
+        onValueChange?.(next);
+      }
+    },
+    [onValueChange],
+  );
+  const [selected, select] = useControlled<string | null>(value, defaultValue, report);
+
+  const group = useMemo(() => ({ labelId: `${base}-label`, registerLabel: setLabelled }), [base]);
+  const radio = useMemo(
+    () => ({ value: selected, choose: (next: string) => select(next) }),
+    [selected, select],
+  );
+
+  const props = withProps(rest, {
+    "aria-labelledby": labelled ? group.labelId : undefined,
+    children,
+    role: "group",
+  });
 
   return (
-    <button
-      {...passed}
-      aria-disabled={disabled ? "true" : undefined}
-      id={id}
-      onClick={composeHandlers(rest.onClick, () => {
-        if (disabled) {
-          return;
-        }
-        onSelect?.();
-        closeTree(menu);
-      })}
-      // The roving tab stop follows real focus rather than leading it, so a
-      // pointer that moves focus and a key that moves focus agree without the
-      // two of them having to be kept in step by hand.
-      onFocus={composeHandlers(rest.onFocus, () => setActiveId?.(id))}
-      role="menuitem"
-      tabIndex={list?.activeId === id ? 0 : -1}
-      type="button"
-    >
-      {children}
-    </button>
+    <MenuGroupContext.Provider value={group}>
+      <MenuRadioContext.Provider value={radio}>
+        {render == null ? <div {...props} /> : render(props)}
+      </MenuRadioContext.Provider>
+    </MenuGroupContext.Provider>
   );
 }
 
+/**
+ * One answer in a `Menu.RadioGroup`.
+ *
+ * Choosing it reports the group's new value and leaves the menu open, which is
+ * what a sort order or a zoom level in a native menu does; `closeOnSelect` is
+ * the way to say otherwise for a choice that ends the visit.
+ */
+export component MenuRadioItem(
+  children: React.Node,
+  value: string,
+  disabled?: boolean = false,
+  closeOnSelect?: boolean = false,
+  onSelect?: (event: MenuSelect) => mixed,
+  render?: RenderProp,
+  ...rest: Rest
+) {
+  const group = useContext(MenuRadioContext);
+  if (group == null) {
+    throw new Error("Menu.RadioItem must be rendered inside a Menu.RadioGroup");
+  }
+  const choose = group.choose;
+  const pick = useCallback(() => choose(value), [choose, value]);
+  const item = useMenuItem("Menu.RadioItem", disabled, closeOnSelect, onSelect, pick);
+  const props = withProps(withoutComposed(rest, ["onClick", "onFocus"]), {
+    "aria-checked": group.value === value ? "true" : "false",
+    "aria-disabled": disabled ? "true" : undefined,
+    children,
+    id: item.id,
+    onClick: composeHandlers(rest.onClick, item.onClick),
+    onFocus: composeHandlers(rest.onFocus, item.onFocus),
+    role: "menuitemradio",
+    tabIndex: item.tabIndex,
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+  return <button {...props} type="button" />;
+}
+
 /**
  * The item that opens a submenu.
  *
@@ -521,10 +728,9 @@ export component MenuItem(
  * is why it reads the list context of the menu around it and the menu context
  * of the one below it.
  */
-export component MenuSubTrigger(children: React.Node, ...rest: { readonly [string]: mixed }) {
+export component MenuSubTrigger(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const menu = useMenu("Menu.SubTrigger");
   const list = useContext(MenuListContext);
-  const passed = withoutComposed(rest, ["onClick", "onFocus", "onKeyDown", "ref"]);
   const setActiveId = list?.setActiveId;
   useTriggerRegistration(menu);
   // The submenu's own trigger id, not a fresh one: the submenu names itself
@@ -532,39 +738,44 @@ export component MenuSubTrigger(children: React.Node, ...rest: { readonly [strin
   const id = `${menu.base}-trigger`;
 
   const open = () => {
-    menu.pendingFocus.current = "first";
+    // This is an instruction for the submenu body after the opening commit.
+    // uf-lint-disable-next-line react-compiler/immutability
+    menu.pendingFocusRef.current = "first";
     menu.setOpen(true);
   };
 
-  return (
-    <button
-      {...passed}
-      aria-controls={menu.open ? `${menu.base}-body` : undefined}
-      aria-expanded={menu.open ? "true" : "false"}
-      aria-haspopup="menu"
-      id={id}
-      onClick={composeHandlers(rest.onClick, open)}
-      onFocus={composeHandlers(rest.onFocus, () => setActiveId?.(id))}
-      onKeyDown={composeHandlers(rest.onKeyDown, (event) => {
-        if (event.key !== "ArrowRight") {
-          return;
-        }
-        event.preventDefault();
-        // The parent menu's own `ArrowRight` does nothing, but a menu three
-        // levels deep would otherwise see this key at every level.
-        event.stopPropagation();
-        open();
-      })}
-      ref={composeRefs(rest.ref, (element) => {
-        menu.triggerRef.current = element;
-      })}
-      role="menuitem"
-      tabIndex={list?.activeId === id ? 0 : -1}
-      type="button"
-    >
-      {children}
-    </button>
-  );
+  const props = withProps(withoutComposed(rest, ["onClick", "onFocus", "onKeyDown", "ref"]), {
+    "aria-controls": menu.open ? `${menu.base}-body` : undefined,
+    "aria-expanded": menu.open ? "true" : "false",
+    "aria-haspopup": "menu",
+    children,
+    id,
+    onClick: composeHandlers(rest.onClick, open),
+    onFocus: composeHandlers(rest.onFocus, () => setActiveId?.(id)),
+    onKeyDown: composeHandlers(rest.onKeyDown, (event: PartEvent) => {
+      const trigger: $FlowFixMe = event.currentTarget;
+      if (event.key !== submenuKeys(directionOf(trigger)).open) {
+        return;
+      }
+      event.preventDefault();
+      // The parent menu's own `ArrowRight` does nothing, but a menu three
+      // levels deep would otherwise see this key at every level.
+      event.stopPropagation();
+      open();
+    }),
+    ref: composeRefs(rest.ref, (element: HTMLElement | null) => {
+      // React calls callback refs during commit; the submenu body reads the trigger later.
+      // uf-lint-disable-next-line react-compiler/immutability
+      menu.triggerRef.current = element;
+    }),
+    role: "menuitem",
+    tabIndex: list?.activeId === id ? 0 : -1,
+  });
+
+  if (render != null) {
+    return render(props);
+  }
+  return <button {...props} type="button" />;
 }
 
 /**
@@ -574,8 +785,12 @@ export component MenuSubTrigger(children: React.Node, ...rest: { readonly [strin
  * moving through the menu is told the group changed. It is not focusable and
  * the arrow keys pass straight over it.
  */
-export component MenuSeparator(...rest: { readonly [string]: mixed }) {
-  return <div {...rest} aria-orientation="horizontal" role="separator" />;
+export component MenuSeparator(render?: RenderProp, ...rest: Rest) {
+  const props = withProps(rest, { "aria-orientation": "horizontal", role: "separator" });
+  if (render != null) {
+    return render(props);
+  }
+  return <div {...props} />;
 }
 
 /**
@@ -586,29 +801,32 @@ export component MenuSeparator(...rest: { readonly [string]: mixed }) {
  * that is not in the document makes a screen reader announce *nothing*, which
  * is worse than an unnamed group.
  */
-export component MenuGroup(children: React.Node, ...rest: { readonly [string]: mixed }) {
+export component MenuGroup(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const base = useId();
   const [labelled, setLabelled] = useState(false);
 
   const group = useMemo(() => ({ labelId: `${base}-label`, registerLabel: setLabelled }), [base]);
+  const props = withProps(rest, {
+    "aria-labelledby": labelled ? group.labelId : undefined,
+    children,
+    role: "group",
+  });
 
   return (
     <MenuGroupContext.Provider value={group}>
-      <div {...rest} aria-labelledby={labelled ? group.labelId : undefined} role="group">
-        {children}
-      </div>
+      {render == null ? <div {...props} /> : render(props)}
     </MenuGroupContext.Provider>
   );
 }
 
 /**
- * The heading of a `Menu.Group`.
+ * The heading of a `Menu.Group` or a `Menu.RadioGroup`.
  *
  * `role="presentation"` because the group already carries the name: leaving it
  * as ordinary content would have a reader hear the heading once as the group's
  * name and again as a stray line of text between the items.
  */
-export component MenuLabel(children: React.Node, ...rest: { readonly [string]: mixed }) {
+export component MenuLabel(children: React.Node, render?: RenderProp, ...rest: Rest) {
   const group = useContext(MenuGroupContext);
   const register = group?.registerLabel;
 
@@ -620,9 +838,9 @@ export component MenuLabel(children: React.Node, ...rest: { readonly [string]: m
     return () => register(false);
   }, [register]);
 
-  return (
-    <div {...rest} id={group?.labelId} role="presentation">
-      {children}
-    </div>
-  );
+  const props = withProps(rest, { children, id: group?.labelId, role: "presentation" });
+  if (render != null) {
+    return render(props);
+  }
+  return <div {...props} />;
 }