@edgeandnode/eds-react 1.0.1 → 1.1.0

package/src/components/Menu.parts.tsx

@@ -9,7 +9,6 @@ import {
   useMemo,
   useRef,
   useState,
-  type ChangeEvent,
   type ComponentProps,
   type KeyboardEvent,
   type PointerEvent,
@@ -41,13 +40,7 @@ import {
   useCSSState,
   useEDS,
 } from '../hooks/index.ts'
-import {
-  cn,
-  getCSSPropsAttributes,
-  setInputValue,
-  splitProps,
-  type OptionValue,
-} from '../utils/index.ts'
+import { cn, getCSSPropsAttributes, splitProps, type OptionValue } from '../utils/index.ts'
 import { renderAddon, type AddonValue } from './base/Addon.tsx'
 import { ButtonOrLink, type ButtonOrLinkProps } from './base/ButtonOrLink.tsx'
 import { Portal } from './base/Portal.tsx'
@@ -62,6 +55,8 @@ import { Checkbox } from './Checkbox.tsx'
 import { MenuMeta, type MenuItemMeta } from './Menu.meta.ts'
 
 const MenuTriggerContext = createContext<boolean>(false)
+const MenuSearchableContext = createContext<boolean>(false)
+const MenuSearchLoadingContext = createContext<boolean>(false)
 
 type MenuItemType = 'plain' | 'checkbox' | 'radio'
 
@@ -131,6 +126,39 @@ export declare namespace MenuProps {
      * @default false
      */
     highlightCheckedOnOpen?: boolean | undefined
+    /**
+     * Adds `Menu.Search` to the header and filters items by their text (or `label`) as the user
+     * types. A custom `header` must include `Menu.Search`, which handles the keyboard navigation.
+     * Pass a function to customize matching, or `'manual'` to filter the items yourself (e.g.
+     * results from an API). Defaults to `true` if `searchValue` or `onSearchValueChange` is set.
+     */
+    searchable?:
+      | boolean
+      | ((item: { label: string; searchValue: string }) => boolean)
+      | 'manual'
+      | undefined
+    /** The search query, to control it along with `onSearchValueChange`. */
+    searchValue?: string | undefined
+    /**
+     * Called when the search query changes, including when it's reset after the menu closes (then
+     * `eventDetails.reason` is `'popup-close'`).
+     */
+    onSearchValueChange?:
+      | ((searchValue: string, eventDetails: Menu.FilterProvider.ChangeEventDetails) => void)
+      | undefined
+    /**
+     * Shown in a searchable menu when no item matches. A string is rendered in a `Menu.Empty`, and
+     * `null` renders nothing.
+     *
+     * @default <Menu.Empty />
+     */
+    empty?: ReactNode | undefined
+    /**
+     * Marks the items as loading (e.g. search results from an API). In a searchable menu, a
+     * `LoadingIcon` also shows in the search input, or in place of the empty state until a search
+     * finishes.
+     */
+    loading?: boolean | undefined
   }
   interface CommonProps extends HTMLProps, OwnProps, EDSComponentProps<typeof MenuMeta> {}
   interface NonRadioProps extends CommonProps, GroupProps.NonRadioProps {}
@@ -155,9 +183,14 @@ export function MenuRoot<T extends OptionValue>({
   open: controlledOpen,
   defaultOpen,
   onOpenChange,
-  header,
+  header: passedHeader,
   footer,
   highlightCheckedOnOpen,
+  searchable: passedSearchable,
+  searchValue,
+  onSearchValueChange,
+  empty,
+  loading,
   label,
   type,
   value,
@@ -166,7 +199,7 @@ export function MenuRoot<T extends OptionValue>({
   children,
   ...props
 }: MenuProps<T>) {
-  const { dirProps } = useEDS()
+  const { dirProps, localThemeClass } = useEDS()
 
   const isSubmenu = useContext(MenuGroupContext) !== null
   const isContextMenu = triggerMode === 'right-click' && !isSubmenu
@@ -247,6 +280,12 @@ export function MenuRoot<T extends OptionValue>({
 
   useHighlightCheckedOnOpen(popupRef, open, highlightCheckedOnOpen)
 
+  const searchable =
+    passedSearchable ?? (searchValue !== undefined || onSearchValueChange !== undefined)
+  const [onSearchValueChangeAfterClose, reportPendingSearchReset] =
+    useSearchResetAfterClose(onSearchValueChange)
+  const header = passedHeader !== undefined ? passedHeader : searchable ? <MenuSearch /> : undefined
+
   return (
     /**
      * This wrapper element ensures a `Menu` always renders a single element, unlike Base UI's which
@@ -264,76 +303,87 @@ export function MenuRoot<T extends OptionValue>({
         i:safari:not-data-is-submenu:size-max`,
       )}
     >
-      <MenuRoot
-        key={`${hasTrigger}-${triggerMode}`}
-        actionsRef={actionsRef}
-        open={open}
-        onOpenChange={(newOpen) => {
-          // A menu with no trigger can still be opened/closed by the consumer, but it should not send events
-          if (hasTrigger) setOpen(newOpen)
-        }}
-        {...(!isSubmenu && !isContextMenu && { modal: hasTrigger })}
-        closeParentOnEsc
+      <MenuFilter
+        searchable={searchable}
+        searchValue={searchValue}
+        onSearchValueChange={onSearchValueChangeAfterClose}
       >
-        <MenuTriggerContext.Provider value={true}>
-          {renderedTriggerElement ?? (
-            <MenuInlineFallback label={label} portalRef={portalRef} rootProps={props} />
-          )}
-        </MenuTriggerContext.Provider>
-        {/* Ensure changes to CSS props are detected even when the menu is not mounted */}
-        <Portal>
-          <span
-            ref={cssPropsPolyfillRef}
-            {...mergeProps(
-              { className: cn('eds-menu invisible! block!', cssPropsClassName) },
-              cssPropsAttributes,
-              cssPropsPolyfillAttributes,
-              dirProps,
-              props,
-            )}
-            hidden={undefined}
-          />
-        </Portal>
-        <Menu.Portal
-          container={
-            !hasTrigger
-              ? portalRef
-              : /**
-                 * Specifying `document.body` because while it is the default for top-level menus, a submenu
-                 * defaults to using the same portal as its parent, which is not desirable when the parent is
-                 * rendered inline (it can cause the submenu to appear behind other elements).
-                 */
-                typeof document !== 'undefined'
-                ? document.body
-                : undefined
-          }
+        <MenuRoot
+          key={`${hasTrigger}-${triggerMode}`}
+          actionsRef={actionsRef}
+          open={open}
+          onOpenChange={(newOpen) => {
+            if (newOpen) reportPendingSearchReset()
+            // A menu with no trigger can still be opened/closed by the consumer, but it should not send events
+            if (hasTrigger) setOpen(newOpen)
+          }}
+          onOpenChangeComplete={(newOpen) => {
+            if (!newOpen) reportPendingSearchReset()
+          }}
+          {...(!isSubmenu && !isContextMenu && { modal: hasTrigger })}
+          closeParentOnEsc
         >
-          <Menu.Positioner
-            ref={passedRef}
-            anchor={anchor}
-            side={
-              cssProps.side === 'start'
-                ? 'inline-start'
-                : cssProps.side === 'end'
-                  ? 'inline-end'
-                  : cssProps.side
+          <MenuTriggerContext.Provider value={true}>
+            {renderedTriggerElement ?? (
+              <MenuInlineFallback label={label} portalRef={portalRef} rootProps={props} />
+            )}
+          </MenuTriggerContext.Provider>
+          {/* Ensure changes to CSS props are detected even when the menu is not mounted */}
+          <Portal>
+            <span
+              ref={cssPropsPolyfillRef}
+              {...mergeProps(
+                { className: cn('eds-menu invisible! block!', cssPropsClassName) },
+                cssPropsAttributes,
+                cssPropsPolyfillAttributes,
+                dirProps,
+                props,
+              )}
+              hidden={undefined}
+            />
+          </Portal>
+          <Menu.Portal
+            container={
+              !hasTrigger
+                ? portalRef
+                : /**
+                   * Specifying `document.body` because while it is the default for top-level menus, a submenu
+                   * defaults to using the same portal as its parent, which is not desirable when the parent is
+                   * rendered inline (it can cause the submenu to appear behind other elements).
+                   */
+                  typeof document !== 'undefined'
+                  ? document.body
+                  : undefined
             }
-            sideOffset={twToPx(cssProps.gap)}
-            align={cssProps.align}
-            alignOffset={twToPx(cssProps.alignOffset)}
-            collisionPadding={8}
-            collisionAvoidance={{
-              side: 'flip',
-              align: 'flip',
-              fallbackAxisSide:
-                cssProps.side === 'start' || cssProps.side === 'end' ? 'end' : 'none',
-            }}
-            data-has-trigger={hasTrigger || undefined}
-            data-match-trigger-width={cssProps.matchTriggerWidth || undefined}
-            data-match-trigger-height={cssProps.matchTriggerHeight || undefined}
-            {...mergeProps(
-              {
-                className: cn(`
+            // Inline menus are portalled in place, so they already inherit the local theme
+            className={hasTrigger ? localThemeClass : undefined}
+          >
+            <Menu.Positioner
+              ref={passedRef}
+              anchor={anchor}
+              side={
+                cssProps.side === 'start'
+                  ? 'inline-start'
+                  : cssProps.side === 'end'
+                    ? 'inline-end'
+                    : cssProps.side
+              }
+              sideOffset={twToPx(cssProps.gap)}
+              align={cssProps.align}
+              alignOffset={twToPx(cssProps.alignOffset)}
+              collisionPadding={8}
+              collisionAvoidance={{
+                side: 'flip',
+                align: 'flip',
+                fallbackAxisSide:
+                  cssProps.side === 'start' || cssProps.side === 'end' ? 'end' : 'none',
+              }}
+              data-has-trigger={hasTrigger || undefined}
+              data-match-trigger-width={cssProps.matchTriggerWidth || undefined}
+              data-match-trigger-height={cssProps.matchTriggerHeight || undefined}
+              {...mergeProps(
+                {
+                  className: cn(`
                   eds-menu root-flex
                   [--available-height-but-not-too-small:max(var(--available-height),--spacing(16))]
                   [anchor-name:--eds-menu]
@@ -352,83 +402,153 @@ export function MenuRoot<T extends OptionValue>({
                   u:i:data-[match-trigger-width=at-most]:max-w-[min(var(--anchor-width),var(--available-width))]
                   u:i:data-[match-trigger-width=true]:w-(--anchor-width)
                 `, cssPropsClassName),
-              },
-              cssPropsAttributes,
-              cssPropsPolyfillAttributes,
-              dirProps,
-              props,
-            )}
-            render={(renderProps, state) => (
-              <>
-                <div {...renderProps} style={hasTrigger ? renderProps.style : undefined} />
-                {/**
-                 * The `data-anchor-hidden:hidden` class above hides the menu if it's open when the trigger gets
-                 * hidden, but this actually closes it to restore pointer interactions outside the menu (though the
-                 * class is still necessary to prevent a flash of incorrect menu position). We're doing it in an
-                 * effect to prevent a "Cannot update a component while rendering a different component" error.
-                 */}
-                {hasTrigger && state.open && state.anchorHidden && actionsRef.current ? (
-                  <LayoutEffect effect={actionsRef.current.close} />
-                ) : null}
-              </>
-            )}
-          >
-            <Menu.Popup
-              ref={popupRef}
-              data-initial-open={initialOpen.current || undefined}
-              className="
+                },
+                cssPropsAttributes,
+                cssPropsPolyfillAttributes,
+                dirProps,
+                props,
+              )}
+              render={(renderProps, state) => (
+                <>
+                  <div {...renderProps} style={hasTrigger ? renderProps.style : undefined} />
+                  {/**
+                   * The `data-anchor-hidden:hidden` class above hides the menu if it's open when the trigger gets
+                   * hidden, but this actually closes it to restore pointer interactions outside the menu (though the
+                   * class is still necessary to prevent a flash of incorrect menu position). We're doing it in an
+                   * effect to prevent a "Cannot update a component while rendering a different component" error.
+                   */}
+                  {hasTrigger && state.open && state.anchorHidden && actionsRef.current ? (
+                    <LayoutEffect effect={actionsRef.current.close} />
+                  ) : null}
+                </>
+              )}
+            >
+              <Menu.Popup
+                ref={popupRef}
+                data-initial-open={initialOpen.current || undefined}
+                className="
                 flex grow origin-(--transform-origin) flex-col overflow-clip rounded-inherit bg-muted outline-0 transition
                 data-ending-style:scale-95
                 data-ending-style:opacity-0
                 data-starting-style:not-data-initial-open:scale-95
                 data-starting-style:not-data-initial-open:opacity-0
               "
-              onKeyDown={handleMenuPopupKeyDown}
-            >
-              <MenuPopupContent header={header} footer={footer}>
-                {/* When `label` or `type` is provided at the root level, automatically wrap `children` in a group */}
-                {label !== undefined || type !== undefined ? (
-                  type === 'radio' ? (
-                    <MenuGroup
-                      label={label}
-                      type={type}
-                      value={value}
-                      defaultValue={defaultValue}
-                      onValueChange={onValueChange}
-                    >
-                      {children}
-                    </MenuGroup>
+                onKeyDown={handleMenuPopupKeyDown}
+              >
+                <MenuPopupContent header={header} footer={footer} empty={empty} loading={loading}>
+                  {/* When `label` or `type` is provided at the root level, automatically wrap `children` in a group */}
+                  {label !== undefined || type !== undefined ? (
+                    type === 'radio' ? (
+                      <MenuGroup
+                        label={label}
+                        type={type}
+                        value={value}
+                        defaultValue={defaultValue}
+                        onValueChange={onValueChange}
+                      >
+                        {children}
+                      </MenuGroup>
+                    ) : (
+                      <MenuGroup label={label} type={type}>
+                        {children}
+                      </MenuGroup>
+                    )
                   ) : (
-                    <MenuGroup label={label} type={type}>
-                      {children}
-                    </MenuGroup>
-                  )
-                ) : (
-                  children
-                )}
-              </MenuPopupContent>
-            </Menu.Popup>
-          </Menu.Positioner>
-        </Menu.Portal>
-      </MenuRoot>
+                    children
+                  )}
+                </MenuPopupContent>
+              </Menu.Popup>
+            </Menu.Positioner>
+          </Menu.Portal>
+        </MenuRoot>
+      </MenuFilter>
     </span>
   )
 }
 MenuRoot.displayName = 'Menu'
 
+/** Makes the menu filterable when it's `searchable` (see `MenuProps.OwnProps['searchable']`). */
+function MenuFilter({
+  searchable,
+  searchValue,
+  onSearchValueChange,
+  children,
+}: Pick<MenuProps.OwnProps, 'searchable' | 'searchValue' | 'onSearchValueChange'> & {
+  children: ReactNode
+}) {
+  const filter = useMemo(
+    () =>
+      searchable === 'manual'
+        ? null
+        : typeof searchable === 'function'
+          ? (label: string, query: string) => searchable({ label, searchValue: query })
+          : undefined,
+    [searchable],
+  )
+
+  return (
+    <MenuSearchableContext.Provider value={Boolean(searchable)}>
+      {searchable ? (
+        <Menu.FilterProvider
+          filter={filter}
+          autoHighlight
+          value={searchValue}
+          onValueChange={onSearchValueChange}
+        >
+          {children}
+        </Menu.FilterProvider>
+      ) : (
+        children
+      )}
+    </MenuSearchableContext.Provider>
+  )
+}
+
 /**
- * Popup chrome: minimum-width spacer, optional header, scrollable items area, optional footer,
- * border overlay.
+ * Holds back the search reset that Base UI reports as the menu starts closing until it has finished
+ * closing (or reopens), so items filtered outside of Base UI (e.g. with `searchable="manual"`)
+ * don't change while it animates out. Base UI keeps filtering its own items with the previous query
+ * until then too.
+ */
+function useSearchResetAfterClose(onSearchValueChange: MenuProps.OwnProps['onSearchValueChange']) {
+  const pendingResetRef = useRef<(() => void) | null>(null)
+  const onSearchValueChangeAfterClose: MenuProps.OwnProps['onSearchValueChange'] =
+    onSearchValueChange &&
+    ((searchValue, eventDetails) => {
+      if (eventDetails.reason === 'popup-close') {
+        pendingResetRef.current = () => onSearchValueChange(searchValue, eventDetails)
+      } else {
+        onSearchValueChange(searchValue, eventDetails)
+      }
+    })
+  const reportPendingReset = () => {
+    pendingResetRef.current?.()
+    pendingResetRef.current = null
+  }
+  return [onSearchValueChangeAfterClose, reportPendingReset] as const
+}
+
+/**
+ * Popup chrome: minimum-width spacer, optional header, scrollable items area (with a searchable
+ * menu's empty state), optional footer, border overlay.
  */
 function MenuPopupContent({
   header,
   footer,
+  empty,
+  loading = false,
   children,
 }: {
   header?: ReactNode | undefined
   footer?: ReactNode | undefined
+  /** Only for searchable menus, where Base UI shows it when no item matches. */
+  empty?: ReactNode | undefined
+  loading?: boolean | undefined
   children?: ReactNode | undefined
 }) {
+  const searchable = useContext(MenuSearchableContext)
+  const [emptyShowsLoading, setEmptyShowsLoading] = useState(false)
+
   return (
     <>
       {/**
@@ -440,15 +560,25 @@ function MenuPopupContent({
       <div className="w-58" />
       {header ? (
         <div className="nested/menu-header u:shrink-0 u:border-b u:border-muted u:p-4">
-          {header}
+          <MenuSearchLoadingContext.Provider value={loading && !emptyShowsLoading}>
+            {header}
+          </MenuSearchLoadingContext.Provider>
         </div>
       ) : null}
       <div className="grow scroll-p-8 scrollbar-thin overflow-x-clip overflow-y-auto gradient-mask-y">
         <div className="overflow-clip p-2">
-          <MenuGroupContext.Provider value="root">
-            {children}
-            <div className="mt-[calc(-2*(--spacing(2))-1px)] not-preceded-by-peer/menu-group:hidden" />
-          </MenuGroupContext.Provider>
+          {searchable ? (
+            <Menu.Empty>
+              <MenuEmptyContent
+                empty={empty}
+                loading={loading}
+                onLoadingShownChange={setEmptyShowsLoading}
+              />
+            </Menu.Empty>
+          ) : null}
+          <Menu.List aria-busy={loading || undefined} className="outline-0">
+            <MenuGroupContext.Provider value="root">{children}</MenuGroupContext.Provider>
+          </Menu.List>
         </div>
       </div>
       {footer ? (
@@ -535,8 +665,8 @@ function MenuInlineFallback({
         {...mergeProps(
           {
             className: cn(`
-              pointer-events-none absolute inset-[anchor(inside)] size-auto! [position-anchor:--eds-menu]
-              not-open:hidden
+              pointer-events-none! absolute! inset-[anchor(inside)]! z-auto! m-0! size-auto! [position-anchor:--eds-menu]!
+              not-open:hidden!
               u:rounded-12
             `),
           },
@@ -622,9 +752,44 @@ function renderMenuTriggerElement({
   }
 }
 
+/**
+ * The content of a searchable menu's `Menu.Empty`, which Base UI only renders while no item
+ * matches. Until a search finishes, `empty` would be premature, so `loading` shows a `LoadingIcon`
+ * instead (rather than in the search input).
+ */
+function MenuEmptyContent({
+  empty,
+  loading,
+  onLoadingShownChange,
+}: {
+  empty: ReactNode
+  loading: boolean
+  onLoadingShownChange: (loadingShown: boolean) => void
+}) {
+  const [searchFinished, setSearchFinished] = useState(!loading)
+  if (!loading && !searchFinished) setSearchFinished(true)
+
+  useLayoutEffect(() => {
+    onLoadingShownChange(!searchFinished)
+    return () => onLoadingShownChange(false)
+  }, [searchFinished, onLoadingShownChange])
+
+  if (!searchFinished) {
+    return (
+      <MenuEmpty>
+        <span className="flex h-lh items-center justify-center">
+          <LoadingIcon />
+        </span>
+      </MenuEmpty>
+    )
+  }
+  return empty === undefined || typeof empty === 'string' ? <MenuEmpty>{empty}</MenuEmpty> : empty
+}
+
 /**
  * Focus the `[data-checked]` item on open so Base UI's composite syncs its active index to it (Base
- * UI has no `initialActiveIndex` API).
+ * UI has no `initialActiveIndex` API). In a searchable menu, typing then moves focus back to the
+ * search input.
  */
 function useHighlightCheckedOnOpen(
   popupRef: RefObject<HTMLDivElement | null>,
@@ -646,19 +811,13 @@ function useHighlightCheckedOnOpen(
       ) {
         return
       }
-      const searchInput = popup.querySelector<HTMLInputElement>('input[type="search"]')
-      const searchWasFocused = searchInput !== null && document.activeElement === searchInput
       checkedItem.focus({ preventScroll: false })
-      if (searchWasFocused) searchInput.focus({ preventScroll: true })
     })
     return () => cancelAnimationFrame(frameId)
   }, [popupRef, open, enabled])
 }
 
-/**
- * Keydown handler for `Menu.Popup`. Handles Shift + Tab escaping the popup and inline-search-input
- * / composite-item coordination.
- */
+/** Keydown handler for `Menu.Popup`. Handles Shift + Tab escaping the popup. */
 function handleMenuPopupKeyDown(event: BaseUIEvent<KeyboardEvent<HTMLDivElement>>) {
   /**
    * Ensure Shift + Tab doesn't close the menu if there is a previous focusable element that is not
@@ -690,59 +849,6 @@ function handleMenuPopupKeyDown(event: BaseUIEvent<KeyboardEvent<HTMLDivElement>
       (!activeElementIsMenuItem && previousElementIsMenuItem)
     ) {
       event.preventBaseUIHandler()
-      return
-    }
-  }
-  // If there is a search input in the menu...
-  const searchInput = event.currentTarget.querySelector('input[type="search"]')
-  if (searchInput instanceof HTMLInputElement) {
-    // If the user typed some text, ensure it goes in the input instead of Base UI focusing the item that matches
-    if (
-      (event.key.length === 1 && event.key !== ' ') ||
-      event.key === 'Backspace' ||
-      event.key === 'ArrowLeft' ||
-      event.key === 'ArrowRight'
-    ) {
-      event.preventBaseUIHandler()
-      searchInput.focus()
-    } else {
-      const searchInputIsFocused = document.activeElement === searchInput
-      const menuItems = [...event.currentTarget.querySelectorAll<HTMLElement>('.eds-menu-item')]
-      const highlightedMenuItem = menuItems.find((item) => item.matches('[data-highlighted]'))
-      /**
-       * If the user pressed the down arrow while the search input is focused and there is a single
-       * menu item in the results, move the focus to it because it may already be highlighted, which
-       * would prevent Base UI from focusing it.
-       */
-      if (event.key === 'ArrowDown' && searchInputIsFocused && menuItems.length === 1) {
-        event.preventBaseUIHandler()
-        menuItems[0]!.focus()
-      }
-      // Inversely, if the user pressed the up arrow and the focus is on the only menu item, move it back to the search input
-      else if (
-        event.key === 'ArrowUp' &&
-        menuItems.length === 1 &&
-        document.activeElement === menuItems[0]
-      ) {
-        event.preventDefault()
-        searchInput.focus()
-      }
-      // If the user pressed Enter while the search input is focused and a menu item is highlighted, select it
-      else if (event.key === 'Enter' && searchInputIsFocused && highlightedMenuItem) {
-        highlightedMenuItem.focus()
-        window.setTimeout(() => {
-          highlightedMenuItem.dispatchEvent(
-            new KeyboardEvent('keydown', {
-              key: 'Enter',
-              code: 'Enter',
-              keyCode: 13,
-              which: 13,
-              bubbles: true,
-              cancelable: true,
-            }),
-          )
-        }, 0)
-      }
     }
   }
 }
@@ -794,7 +900,11 @@ export function MenuGroup<T extends OptionValue>({
     <MenuGroupContext.Provider value={menuGroupContextValue}>
       <Menu.Group
         {...mergeProps(
-          { className: cn('peer/menu-group u:-m-2 u:mb-2 u:border-b u:border-muted u:p-2') },
+          {
+            className: cn(
+              'u:-m-2 u:border-muted u:p-2 u:has-[~:not([hidden]):not(:empty)]:mb-2 u:has-[~:not([hidden]):not(:empty)]:border-b',
+            ),
+          },
           props,
         )}
         render={
@@ -825,6 +935,11 @@ export declare namespace MenuItemProps {
     'defaultChecked' | 'defaultValue' | 'onChange' | 'type' | 'value'
   > {}
   interface OwnProps {
+    /**
+     * Text that search and typeahead match against. Defaults to the item's rendered text, addons
+     * included.
+     */
+    label?: string | undefined
     addonBefore?: AddonValue | undefined
     addonAfter?: AddonValue | undefined
     disabled?: boolean | undefined
@@ -873,6 +988,7 @@ export type MenuItemProps<T extends OptionValue = OptionValue> =
 export function MenuItem<T extends OptionValue>({
   ref: passedRef,
   type: passedType,
+  label,
   addonBefore: passedAddonBefore,
   addonAfter: passedAddonAfter,
   variant,
@@ -1021,7 +1137,14 @@ export function MenuItem<T extends OptionValue>({
   }
 
   if (type === 'submenu-trigger') {
-    return <Menu.SubmenuTrigger nativeButton disabled={disabled} render={renderItem(baseProps)} />
+    return (
+      <Menu.SubmenuTrigger
+        nativeButton
+        label={label}
+        disabled={disabled}
+        render={renderItem(baseProps)}
+      />
+    )
   }
 
   if (type === 'checkbox') {
@@ -1029,6 +1152,7 @@ export function MenuItem<T extends OptionValue>({
       <CheckboxItem
         {...baseProps}
         nativeButton
+        label={label}
         checked={checked}
         defaultChecked={defaultChecked}
         onCheckedChange={onCheckedChange}
@@ -1044,6 +1168,7 @@ export function MenuItem<T extends OptionValue>({
         {...baseProps}
         nativeButton
         closeOnClick
+        label={label}
         value={passedValue !== undefined ? passedValue : autoValue}
         disabled={disabled}
         render={renderItem}
@@ -1053,13 +1178,22 @@ export function MenuItem<T extends OptionValue>({
 
   if (href !== undefined) {
     return (
-      <Menu.LinkItem {...baseProps} closeOnClick href={href} target={target} render={renderItem}>
+      <Menu.LinkItem
+        {...baseProps}
+        closeOnClick
+        label={label}
+        href={href}
+        target={target}
+        render={renderItem}
+      >
         {children}
       </Menu.LinkItem>
     )
   }
 
-  return <Menu.Item {...baseProps} nativeButton disabled={disabled} render={renderItem} />
+  return (
+    <Menu.Item {...baseProps} nativeButton label={label} disabled={disabled} render={renderItem} />
+  )
 }
 MenuItem.displayName = 'Menu.Item'
 
@@ -1080,29 +1214,21 @@ function MenuItemAddon({ children, ...props }: ComponentProps<'span'>) {
   )
 }
 
-export interface MenuSearchProps extends Omit<ComponentProps<'input'>, 'children'> {
+export interface MenuSearchProps extends Omit<
+  ComponentProps<'input'>,
+  'children' | 'value' | 'defaultValue'
+> {
   /** @default 'Search' */
   placeholder?: string | undefined
-  value?: string | undefined
-  defaultValue?: string | undefined
-  onValueChange?: ((value: string) => void) | undefined
 }
 
-export function MenuSearch({
-  ref: passedRef,
-  placeholder: passedPlaceholder,
-  value: controlledValue,
-  defaultValue,
-  onValueChange,
-  ...props
-}: MenuSearchProps) {
-  const inputRef = useRef<HTMLInputElement>(null)
-  const inputPassedRef = useMergedRefs(inputRef, passedRef)
-
-  const placeholder = passedPlaceholder ?? 'Search'
-
-  const [value, setValue] = useControlled(controlledValue, defaultValue ?? '', onValueChange)
+/** Search input for the `header` of a `searchable` menu, which filters its items. */
+export function MenuSearch({ placeholder = 'Search', ...props }: MenuSearchProps) {
+  if (!useContext(MenuSearchableContext)) {
+    throw new Error('[Menu] `Menu.Search` must be used in a `searchable` menu')
+  }
 
+  const loading = useContext(MenuSearchLoadingContext)
   const { rootProps, nestedProps } = splitProps(props)
 
   return (
@@ -1112,36 +1238,27 @@ export function MenuSearch({
         rootProps,
       )}
     >
-      <MagnifyingGlassIcon alt="" className="absolute inset-y-0 inset-s-3.5 my-auto size-3.5" />
-      <input
-        ref={inputPassedRef}
-        type="search"
+      {loading ? (
+        <LoadingIcon className="absolute inset-y-0 inset-s-3.5 my-auto size-3.5" />
+      ) : (
+        <MagnifyingGlassIcon alt="" className="absolute inset-y-0 inset-s-3.5 my-auto size-3.5" />
+      )}
+      <Menu.Input
         placeholder={placeholder}
         aria-label={placeholder}
-        value={value}
         {...mergeProps(
-          {
-            className: cn('peer -mb-px h-10 w-0 grow ps-8.5 outline-0'),
-            onChange: (event: ChangeEvent<HTMLInputElement>) => setValue(event.target.value),
-          },
+          { className: cn('peer -mb-px h-10 w-0 grow ps-8.5 outline-0') },
           nestedProps,
         )}
       />
       <div className="me-1.5 flex size-7 shrink-0 items-center justify-center peer-placeholder-shown:hidden">
-        <Button
-          variant="naked"
-          size="xsmall"
-          tabIndex={-1}
-          onClick={() => {
-            const input = inputRef.current
-            if (!input) return
-            setInputValue(input, '')
-            input.focus()
-          }}
-          className="h-full"
+        {/* Exposed to assistive tech, unlike Base UI's default */}
+        <Menu.Clear
+          aria-hidden={false}
+          render={<Button variant="naked" size="xsmall" className="h-full" />}
         >
           <XIcon alt="Clear" />
-        </Button>
+        </Menu.Clear>
       </div>
     </div>
   )
@@ -1151,12 +1268,18 @@ MenuSearch.displayName = 'Menu.Search'
 export interface MenuEmptyProps extends ComponentProps<'div'> {}
 
 /**
- * Renders the standard empty-state treatment for a `Menu` (typically shown when search filters
- * yield no results, or when a `Menu` has no items at all). Defaults to `"No results"`.
+ * Renders the standard empty-state treatment for a `Menu`, e.g. when it has no items. Searchable
+ * menus render it when no item matches (see `empty`). Its text wraps instead of widening the menu.
+ * Defaults to `"No results"`.
  */
 export function MenuEmpty({ children = 'No results', ...props }: MenuEmptyProps) {
+  // `contain-inline-size` keeps the text from widening a menu that sizes to fit its content
   return (
-    <div {...mergeProps({ className: cn('p-2 u:text-16 u:text-muted') }, props)}>{children}</div>
+    <div
+      {...mergeProps({ className: cn('p-2 contain-inline-size u:text-16 u:text-muted') }, props)}
+    >
+      {children}
+    </div>
   )
 }
 MenuEmpty.displayName = 'Menu.Empty'