@skdx/react 0.26.0 → 0.28.0

package/dist/menubar/MenubarTrigger.d.ts

@@ -1,13 +1,11 @@
 import * as React from 'react';
 import type { MenubarTriggerProps } from './types.js';
 /**
- * The menubar item that opens its {@link MenubarMenu}'s content: renders a
- * `<button type="button" role="menuitem">` marked `data-skdx-menubar-trigger`
- * (its own id, for roving focus — the menubar keeps exactly one trigger at
- * `tabIndex` 0), with `aria-haspopup="menu"`, `aria-expanded`,
- * `aria-controls`, and `data-state` of `"open"` or `"closed"`. Click toggles
- * its menu; hover or focus switches to it while a sibling menu is already
- * open (matching native app menu bars); Arrow Down/Up, Enter, or Space open it.
+ * The menubar item that opens its {@link MenubarMenu}'s content. Click
+ * toggles its menu; hover or focus switches to it while a sibling menu is
+ * already open, matching native app menu bars. Enter/Space/ArrowDown open on
+ * the first item, ArrowUp on the last — except in a vertical bar, where those
+ * two arrows rove along the bar instead and ArrowRight opens.
  *
  * @example
  * ```tsx

package/dist/menubar/index.d.cts

@@ -1,15 +1,2 @@
-export * from './Menubar.cjs';
-export { MenubarMenu } from './MenubarMenu.cjs';
-export { MenubarTrigger } from './MenubarTrigger.cjs';
-export { MenubarPortal } from './MenubarPortal.cjs';
-export { MenubarContent } from './MenubarContent.cjs';
-export { MenubarItem } from './MenubarItem.cjs';
-export { MenubarCheckboxItem } from './MenubarCheckboxItem.cjs';
-export { MenubarRadioGroup } from './MenubarRadioGroup.cjs';
-export { MenubarRadioItem } from './MenubarRadioItem.cjs';
-export { MenubarItemIndicator } from './MenubarItemIndicator.cjs';
-export { MenubarGroup } from './MenubarGroup.cjs';
-export { MenubarLabel } from './MenubarLabel.cjs';
-export { MenubarSeparator } from './MenubarSeparator.cjs';
-export { MenubarSub, MenubarSubContent, MenubarSubTrigger } from './MenubarSub.cjs';
-export type { MenubarProps, MenubarMenuProps, MenubarTriggerProps, MenubarPortalProps, MenubarContentProps, MenubarItemProps, MenubarCheckboxItemProps, MenubarRadioGroupProps, MenubarRadioItemProps, MenubarItemIndicatorProps, MenubarGroupProps, MenubarLabelProps, MenubarSeparatorProps, MenubarSubProps, MenubarSubTriggerProps, MenubarSubContentProps, } from './types.cjs';
+export { Menubar } from './Menubar.cjs';
+export type { MenubarProps, MenubarMenu, MenuItem as MenubarItem } from './types.cjs';

package/dist/menubar/index.d.ts

@@ -1,15 +1,2 @@
-export * from './Menubar.js';
-export { MenubarMenu } from './MenubarMenu.js';
-export { MenubarTrigger } from './MenubarTrigger.js';
-export { MenubarPortal } from './MenubarPortal.js';
-export { MenubarContent } from './MenubarContent.js';
-export { MenubarItem } from './MenubarItem.js';
-export { MenubarCheckboxItem } from './MenubarCheckboxItem.js';
-export { MenubarRadioGroup } from './MenubarRadioGroup.js';
-export { MenubarRadioItem } from './MenubarRadioItem.js';
-export { MenubarItemIndicator } from './MenubarItemIndicator.js';
-export { MenubarGroup } from './MenubarGroup.js';
-export { MenubarLabel } from './MenubarLabel.js';
-export { MenubarSeparator } from './MenubarSeparator.js';
-export { MenubarSub, MenubarSubContent, MenubarSubTrigger } from './MenubarSub.js';
-export type { MenubarProps, MenubarMenuProps, MenubarTriggerProps, MenubarPortalProps, MenubarContentProps, MenubarItemProps, MenubarCheckboxItemProps, MenubarRadioGroupProps, MenubarRadioItemProps, MenubarItemIndicatorProps, MenubarGroupProps, MenubarLabelProps, MenubarSeparatorProps, MenubarSubProps, MenubarSubTriggerProps, MenubarSubContentProps, } from './types.js';
+export { Menubar } from './Menubar.js';
+export type { MenubarProps, MenubarMenu, MenuItem as MenubarItem } from './types.js';

package/dist/menubar/primitives.d.cts

@@ -0,0 +1,39 @@
+/**
+ * Advanced primitives for `Menubar` — the parts the recipe composes.
+ *
+ * @example
+ * ```tsx
+ * import { MenubarContent, MenubarItem, MenubarMenu, MenubarPortal, MenubarRoot, MenubarShortcut, MenubarTrigger } from '@skdx/react/primitives/menubar';
+ *
+ * <MenubarRoot aria-label="Application">
+ *   <MenubarMenu value="file">
+ *     <MenubarTrigger>File</MenubarTrigger>
+ *     <MenubarPortal>
+ *       <MenubarContent>
+ *         <MenubarItem>
+ *           Save
+ *           <MenubarShortcut>⌘S</MenubarShortcut>
+ *         </MenubarItem>
+ *       </MenubarContent>
+ *     </MenubarPortal>
+ *   </MenubarMenu>
+ * </MenubarRoot>
+ * ```
+ */
+export { MenubarRoot, MenubarArrow } from './Menubar.cjs';
+export { MenubarMenu } from './MenubarMenu.cjs';
+export { MenubarTrigger } from './MenubarTrigger.cjs';
+export { MenubarPortal } from './MenubarPortal.cjs';
+export { MenubarContent } from './MenubarContent.cjs';
+export { MenubarItem } from './MenubarItem.cjs';
+export { MenubarCheckboxItem } from './MenubarCheckboxItem.cjs';
+export { MenubarRadioGroup } from './MenubarRadioGroup.cjs';
+export { MenubarRadioItem } from './MenubarRadioItem.cjs';
+export { MenubarItemIndicator } from './MenubarItemIndicator.cjs';
+export { MenubarGroup } from './MenubarGroup.cjs';
+export { MenubarLabel } from './MenubarLabel.cjs';
+export { MenubarSeparator } from './MenubarSeparator.cjs';
+export { MenubarShortcut } from './MenubarShortcut.cjs';
+export { MenubarSub, MenubarSubTrigger, MenubarSubContent } from './MenubarSub.cjs';
+export type { MenubarRootProps } from './Menubar.cjs';
+export type { MenubarMenuProps, MenubarTriggerProps, MenubarPortalProps, MenubarContentProps, MenubarItemProps, MenubarCheckboxItemProps, MenubarRadioGroupProps, MenubarRadioItemProps, MenubarItemIndicatorProps, MenubarGroupProps, MenubarLabelProps, MenubarSeparatorProps, MenubarShortcutProps, MenubarSubProps, MenubarSubTriggerProps, MenubarSubContentProps, } from './types.cjs';

package/dist/menubar/primitives.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Advanced primitives for `Menubar` — the parts the recipe composes.
+ *
+ * @example
+ * ```tsx
+ * import { MenubarContent, MenubarItem, MenubarMenu, MenubarPortal, MenubarRoot, MenubarShortcut, MenubarTrigger } from '@skdx/react/primitives/menubar';
+ *
+ * <MenubarRoot aria-label="Application">
+ *   <MenubarMenu value="file">
+ *     <MenubarTrigger>File</MenubarTrigger>
+ *     <MenubarPortal>
+ *       <MenubarContent>
+ *         <MenubarItem>
+ *           Save
+ *           <MenubarShortcut>⌘S</MenubarShortcut>
+ *         </MenubarItem>
+ *       </MenubarContent>
+ *     </MenubarPortal>
+ *   </MenubarMenu>
+ * </MenubarRoot>
+ * ```
+ */
+export { MenubarRoot, MenubarArrow } from './Menubar.js';
+export { MenubarMenu } from './MenubarMenu.js';
+export { MenubarTrigger } from './MenubarTrigger.js';
+export { MenubarPortal } from './MenubarPortal.js';
+export { MenubarContent } from './MenubarContent.js';
+export { MenubarItem } from './MenubarItem.js';
+export { MenubarCheckboxItem } from './MenubarCheckboxItem.js';
+export { MenubarRadioGroup } from './MenubarRadioGroup.js';
+export { MenubarRadioItem } from './MenubarRadioItem.js';
+export { MenubarItemIndicator } from './MenubarItemIndicator.js';
+export { MenubarGroup } from './MenubarGroup.js';
+export { MenubarLabel } from './MenubarLabel.js';
+export { MenubarSeparator } from './MenubarSeparator.js';
+export { MenubarShortcut } from './MenubarShortcut.js';
+export { MenubarSub, MenubarSubTrigger, MenubarSubContent } from './MenubarSub.js';
+export type { MenubarRootProps } from './Menubar.js';
+export type { MenubarMenuProps, MenubarTriggerProps, MenubarPortalProps, MenubarContentProps, MenubarItemProps, MenubarCheckboxItemProps, MenubarRadioGroupProps, MenubarRadioItemProps, MenubarItemIndicatorProps, MenubarGroupProps, MenubarLabelProps, MenubarSeparatorProps, MenubarShortcutProps, MenubarSubProps, MenubarSubTriggerProps, MenubarSubContentProps, } from './types.js';

package/dist/menubar/types.d.cts

@@ -4,31 +4,210 @@ import type { PopperContentProps } from '../utils/popper.cjs';
 import type { PortalProps } from '../utils/portal.cjs';
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
 import type { FocusOutsideEvent, InteractOutsideEvent } from '../utils/useDismiss.cjs';
+import type { AutoFocusEvent } from '../utils/useFocusTrap.cjs';
+/**
+ * One menu entry: a discriminated union where the plain action variant carries no `type` field,
+ * so `{ label: 'Cut', onSelect: cut }` needs no annotation. Narrow with `'type' in item`, never with a cast.
+ * Submenus recurse through this same type, so nesting is unrestricted.
+ */
+export type MenuItem = {
+    /** Text rendered inside the item, and fallback typeahead. */
+    label: string;
+    /**
+     * Called when this item is activated, before the recipe's own `onSelect`. Both fire.
+     * @default undefined — no-op if omitted.
+     */
+    onSelect?: () => void;
+    /**
+     * Keyboard hint rendered as a `MenubarShortcut` at the item's trailing edge, `aria-hidden`.
+     * @default undefined — no shortcut.
+     */
+    shortcut?: string;
+    /**
+     * Marks item `aria-disabled` and blocks selection, staying in roving order and focusable for discoverability.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Text typeahead matches this item by, reflected to `data-text-value`.
+     * @default undefined — the item's rendered text is used.
+     */
+    textValue?: string;
+} | {
+    /** Renders a `MenubarSeparator`: a horizontal rule between item groups. */
+    type: 'separator';
+} | {
+    /** Renders a `MenubarCheckboxItem` (`role="menuitemcheckbox"`) with a `MenubarItemIndicator` shown while checked. */
+    type: 'checkbox';
+    /** Text rendered inside the checkbox item. */
+    label: string;
+    /**
+     * Checked state, externally controlled: reports state via `onCheckedChange`.
+     * @default false
+     */
+    checked?: boolean;
+    /**
+     * Fires with the new checked state when the item is selected.
+     * @default undefined — no-op if omitted.
+     */
+    onCheckedChange?: (checked: boolean) => void;
+    /**
+     * Keyboard hint rendered as a `MenubarShortcut` at the item's trailing edge.
+     * @default undefined — no shortcut.
+     */
+    shortcut?: string;
+    /**
+     * Marks item `aria-disabled` and blocks selection, staying focusable.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Text typeahead matches this item by, reflected to `data-text-value`.
+     * @default undefined — the item's rendered text is used.
+     */
+    textValue?: string;
+} | {
+    /** Renders a `MenubarRadioGroup` of mutually-exclusive options. */
+    type: 'radio-group';
+    /**
+     * Selected radio option's value, externally controlled.
+     * @default undefined — no option selected.
+     */
+    value?: string;
+    /**
+     * Fires with the newly selected option's `value`.
+     * @default undefined — no-op if omitted.
+     */
+    onValueChange?: (value: string) => void;
+    /** The radio options, one `MenubarRadioItem` each. */
+    items: {
+        /** Text rendered inside the radio item. */
+        label: string;
+        /** Compared against group `value` to decide checked state. */
+        value: string;
+        /**
+         * Marks option `aria-disabled` and blocks selection, staying focusable.
+         * @default false
+         */
+        disabled?: boolean;
+        /**
+         * Text typeahead matches this option by, reflected to `data-text-value`.
+         * @default undefined — the option's rendered text is used.
+         */
+        textValue?: string;
+    }[];
+} | {
+    /** Renders a nested submenu trio: `MenubarSubTrigger` and `MenubarSubContent`. */
+    type: 'submenu';
+    /** Text rendered inside the submenu trigger. */
+    label: string;
+    /** Submenu entries, recursing through the `MenuItem` union. */
+    items: MenuItem[];
+    /**
+     * Marks submenu trigger `aria-disabled` and blocks opening, staying focusable.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Text typeahead matches the trigger by, reflected to `data-text-value`.
+     * @default undefined — the trigger's rendered text is used.
+     */
+    textValue?: string;
+} | {
+    /** Renders a `MenubarGroup` (`role="group"`) with optional `MenubarLabel` caption. */
+    type: 'group';
+    /**
+     * Group heading rendered as `MenubarLabel`, the group's accessible name.
+     * @default undefined — the group is unnamed.
+     */
+    label?: string;
+    /** Group entries, recursing through the `MenuItem` union. */
+    items: MenuItem[];
+};
+/**
+ * One menu on the bar: a trigger label and its panel's entries.
+ */
+export interface MenubarMenu {
+    /** Text rendered inside the menu's trigger. */
+    label: string;
+    /** The menu panel's entries. */
+    items: MenuItem[];
+    /**
+     * Identifier matched against the bar's open `menu` to open/report by name.
+     * @default undefined — the menu's index, as a string.
+     */
+    value?: string;
+    /**
+     * Marks trigger disabled and skips it in the bar's roving focus.
+     * @default false
+     */
+    disabled?: boolean;
+}
+/**
+ * Which menu end focus lands on when opened: `'first'` (Enter/Space/ArrowDown)
+ * or `'last'` (ArrowUp), following WAI-ARIA menubar semantics.
+ */
+export type MenubarOpenIntent = 'first' | 'last';
+/** Axis the bar lays triggers on, reflected as `data-orientation`. */
+export type MenubarOrientation = 'horizontal' | 'vertical';
 /** @internal Shared state distributed from {@link Menubar} to its parts via context. Not part of the public API. */
 export interface MenubarContextValue {
-    value: string;
-    onValueChange: (value: string) => void;
+    menu: string;
+    onMenuChange: (menu: string) => void;
+    /** The bar's axis, read by Trigger to know which arrows open a menu and which rove along the bar. */
+    orientation: MenubarOrientation;
     /** Id of the trigger holding the menubar's single tab stop; every other trigger is `tabIndex` -1. */
     currentTabStopId: string | null;
     setCurrentTabStopId: (id: string) => void;
 }
-/** Props for the {@link Menubar} root. */
-export interface MenubarProps extends PrimitivePropsWithRef<'div'> {
+/**
+ * Props for the {@link Menubar} recipe. Standard attributes pass to the `<div role="menubar">`.
+ * For full manual composition use `MenubarRoot` from `@skdx/react/primitives/menubar`.
+ */
+export interface MenubarProps extends Omit<PrimitivePropsWithRef<'div'>, 'onSelect' | 'children'> {
     /**
-     * Value of the currently open menu, for controlled usage. Pair with `onValueChange`.
-     * @default undefined — uncontrolled, tracks its own open menu internally.
+     * The bar's menus, one trigger and panel each.
+     * @default undefined — an empty bar.
      */
-    value?: string;
+    menus?: MenubarMenu[];
+    /**
+     * Fires with the activated entry (plain, checkbox, submenu item, or radio option)
+     * after that entry's own `onSelect`/`onCheckedChange`/`onValueChange`.
+     * @default undefined — no-op if omitted.
+     */
+    onSelect?: (item: MenuItem) => void;
+    /**
+     * Renders an entry's content in place of its `label`; the item element's role, id, wiring
+     * and disabled state stay the library's. Not called for separators or groups.
+     * @default undefined — renders the entry's `label`.
+     */
+    renderItem?: (item: MenuItem) => React.ReactNode;
+    /**
+     * Currently open menu, for controlled usage; pair with `onMenuChange`.
+     * @default undefined — uncontrolled.
+     */
+    menu?: string;
     /**
      * Initially open menu's value, for uncontrolled usage.
      * @default ''
      */
-    defaultValue?: string;
+    defaultMenu?: string;
     /**
-     * Fires with the new value whenever the open menu changes, controlled or not.
+     * Fires with the newly open menu's value, controlled or uncontrolled.
      * @default undefined — no-op if omitted.
      */
-    onValueChange?: (value: string) => void;
+    onMenuChange?: (menu: string) => void;
+    /**
+     * Layout axis for the bar, reflected as `aria-orientation`; sets which arrows rove
+     * along the bar. An open menu is always vertical.
+     * @default 'horizontal'
+     */
+    orientation?: MenubarOrientation;
+    /**
+     * Whether roving focus across the bar wraps from the last trigger to the first.
+     * @default true
+     */
+    loop?: boolean;
 }
 /** @internal Per-menu state distributed from {@link MenubarMenu} to its descendants via context. Not part of the public API. */
 export interface MenubarMenuContextValue {
@@ -36,40 +215,66 @@ export interface MenubarMenuContextValue {
     triggerRef: React.RefObject<HTMLButtonElement | null>;
     contentRef: React.RefObject<HTMLDivElement | null>;
     contentId: string;
+    /**
+     * This menu's Trigger id, which Content points `aria-labelledby` at.
+     * Owned by `MenubarMenu` so `MenubarContent` can reach it.
+     */
+    triggerId: string;
     open: boolean;
-    /** True once this menu was opened by an explicit click (vs. a hover/focus switch), so a repeat click knows to close it. */
+    /** True once opened by explicit click vs. hover/focus. */
     openedExplicitlyRef: React.RefObject<boolean>;
     onOpen: () => void;
     onClose: () => void;
+    /**
+     * Returns focus to this menu's Trigger, firing `close-auto-focus`
+     * from Escape, Tab, and item selection.
+     */
+    focusTrigger: () => void;
+    /**
+     * Content's `onCloseAutoFocus` handler, parked here so focusTrigger can reach it.
+     * A ref: Content declares the event but MenubarMenu owns the focus move.
+     */
+    closeAutoFocusRef: React.RefObject<((event: AutoFocusEvent) => void) | undefined>;
+    /**
+     * Which menu end the last open request asked for: `'first'` or `'last'`.
+     * Read once on open, never rendered.
+     */
+    openIntentRef: React.RefObject<MenubarOpenIntent>;
+    /**
+     * Bumped on every `onOpen()` call, including one that re-requests an
+     * already-open menu (e.g. `defaultMenu` pre-opened it, then its trigger is
+     * clicked). Content's auto-focus effect keys off this alongside `open` so a
+     * request that doesn't flip the boolean still moves focus into the panel.
+     */
+    openRequestId: number;
 }
 /** Props for a single {@link MenubarMenu}. */
 export interface MenubarMenuProps {
-    /** Unique identifier matched against the root's open `value`. */
+    /** Unique identifier matched against the bar's open `menu`. */
     value: string;
     /**
-     * The menu's trigger and content, typically a `MenubarTrigger` paired with
-     * a `MenubarPortal`/`MenubarContent`.
+     * The menu's trigger and content, typically `MenubarTrigger` with `MenubarPortal`/`MenubarContent`.
      * @default undefined — renders nothing.
      */
     children?: React.ReactNode;
     /**
-     * Fires with the new open state once the change has finished on screen —
-     * after `MenubarContent`'s enter or exit animation ends, or as soon as it has
-     * settled when the panel declares no animation. Use it for work that must not race
-     * the transition; use `onOpenChange` for work that must not wait for it.
+     * Fires once the menu's open state change has finished on screen, after animation ends.
      * @default undefined — no-op if omitted.
      */
     onOpenChangeComplete?: (open: boolean) => void;
 }
 /** Props for {@link MenubarTrigger}, the menubar item that opens its menu's content. */
 export interface MenubarTriggerProps extends PrimitivePropsWithRef<'button'> {
+    /**
+     * Disables trigger and excludes it from roving-focus navigation.
+     * @default false
+     */
+    disabled?: boolean;
 }
-/** Props for {@link MenubarPortal}, which teleports a menu's content elsewhere in the DOM while open. */
+/** Props for {@link MenubarPortal}, which teleports menu content elsewhere in the DOM. */
 export interface MenubarPortalProps extends PortalProps {
     /**
-     * Keep the portal mounted even while its menu is closed, instead of
-     * unmounting it. Useful for animation libraries that need the outgoing
-     * content present in the DOM during an exit transition.
+     * Keep portal mounted while closed, for animation libraries needing outgoing content during exit.
      * @default false
      */
     forceMount?: boolean;
@@ -77,61 +282,72 @@ export interface MenubarPortalProps extends PortalProps {
 /** Props for {@link MenubarContent}, the popover panel of menu items. */
 export interface MenubarContentProps extends PopperContentProps {
     /**
-     * Keep this panel mounted even while its menu is closed, instead of
-     * unmounting it. Useful for animation libraries that need the outgoing
-     * panel present in the DOM during an exit transition.
+     * Keep panel mounted while closed, for animation libraries needing outgoing content during exit.
      * @default false
      */
     forceMount?: boolean;
     /**
-     * Whether arrow-key navigation wraps from the last item back to the first
-     * (and vice versa).
+     * Whether arrow-key navigation wraps from last item to first.
      * @default true
      */
     loop?: boolean;
     /**
-     * Called when Escape is pressed while the content is open. Call `event.preventDefault()` to stop the default close-and-refocus behavior.
+     * Fires on Escape press while open; call `preventDefault()` to keep open.
      * @default undefined — no-op if omitted.
      */
     onEscapeKeyDown?: (event: KeyboardEvent) => void;
     /**
-     * Called on pointerdown outside the content. Call `event.preventDefault()` to stop the default close behavior.
+     * Fires on pointerdown outside content; call `preventDefault()` to keep open.
      * @default undefined — no-op if omitted.
      */
     onPointerDownOutside?: (event: PointerEvent) => void;
     /**
-     * Called when focus moves to an element outside the content and outside the menu bar itself. Call `event.preventDefault()` to stop the default close behavior. Receives a cancelable stand-in carrying the original `focusin` as its `detail`, since `focusin` itself cannot be canceled.
+     * Fires when focus moves outside content and menubar; call `preventDefault()` to keep open.
+     * Receives a cancelable stand-in for `focusin` (not itself cancelable) carrying the original.
      * @default undefined — no-op if omitted.
      */
     onFocusOutside?: (event: FocusOutsideEvent) => void;
     /**
-     * Called for either kind of outside interaction — pointerdown or focus — immediately before the specific handler above and with the same event, so one `event.preventDefault()` here stops the close whichever way it was triggered.
+     * Fires for either outside interaction (pointerdown or focus) before specific handlers,
+     * so one `preventDefault()` vetoes both paths.
      * @default undefined — no-op if omitted.
      */
     onInteractOutside?: (event: InteractOutsideEvent) => void;
+    /**
+     * Fires just before focus returns to trigger on Escape, Tab, or item selection;
+     * call `preventDefault()` to place focus yourself.
+     * @default undefined — no-op if omitted.
+     */
+    onCloseAutoFocus?: (event: AutoFocusEvent) => void;
 }
 /** Props for a single {@link MenubarItem} entry. */
 export interface MenubarItemProps extends Omit<PrimitivePropsWithRef<'div'>, 'onSelect'> {
     /**
-     * Disables selection and excludes the item from arrow-key/typeahead navigation.
+     * Marks item `aria-disabled` and blocks selection, staying in roving order and focusable for discoverability.
      * @default false
      */
     disabled?: boolean;
     /**
-     * Called when the item is activated. `event.preventDefault()` keeps the menu open.
+     * Text typeahead matches this item by, reflected to `data-text-value`.
+     * Important for items rendering more than their label or icon-only items.
+     * @default undefined — the item's rendered text is used.
+     */
+    textValue?: string;
+    /**
+     * Called when the item is activated; call `preventDefault()` to keep menu open.
      * @default undefined — no-op if omitted, menu closes on select.
      */
     onSelect?: (event: Event) => void;
 }
-/** Props for {@link MenubarCheckboxItem}, a togglable menu item. */
+/** Props for {@link MenubarCheckboxItem}, a toggleable menu item. */
 export interface MenubarCheckboxItemProps extends MenubarItemProps {
     /**
-     * Whether the item currently renders as checked.
+     * Whether the item renders as checked.
      * @default false
      */
     checked?: boolean;
     /**
-     * Fires with the next checked state when the item is selected.
+     * Fires with the new checked state when the item is selected.
      * @default undefined — no-op if omitted.
      */
     onCheckedChange?: (checked: boolean) => void;
@@ -141,15 +357,15 @@ export interface MenuRadioGroupContextValue {
     value?: string;
     onValueChange?: (value: string) => void;
 }
-/** Props for the {@link MenubarRadioGroup} wrapping a set of `MenubarRadioItem`s. */
+/** Props for {@link MenubarRadioGroup}, wrapping mutually-exclusive radio items. */
 export interface MenubarRadioGroupProps extends PrimitivePropsWithRef<'div'> {
     /**
-     * Value of the currently checked radio item.
+     * Selected item's value; compared against each radio item's own `value`.
      * @default undefined — no item checked.
      */
     value?: string;
     /**
-     * Fires with the new value when a `MenubarRadioItem` in this group is selected.
+     * Fires with the new value when a radio item in this group is selected.
      * @default undefined — no-op if omitted.
      */
     onValueChange?: (value: string) => void;
@@ -159,11 +375,10 @@ export interface MenubarRadioItemProps extends MenubarItemProps {
     /** Unique identifier matched against the group's checked `value`. */
     value: string;
 }
-/** Props for {@link MenubarItemIndicator}, shown inside a checked `MenubarCheckboxItem` or `MenubarRadioItem`. */
+/** Props for {@link MenubarItemIndicator}, shown while checkbox or radio item is checked. */
 export interface MenubarItemIndicatorProps extends PrimitivePropsWithRef<'span'> {
     /**
-     * Keep this indicator mounted even while unchecked, instead of unmounting
-     * it.
+     * Keep indicator mounted while unchecked, for animation libraries needing outgoing content.
      * @default false
      */
     forceMount?: boolean;
@@ -177,6 +392,9 @@ export interface MenubarLabelProps extends PrimitivePropsWithRef<'div'> {
 /** Props for {@link MenubarSeparator}, a visual divider between menu items. */
 export interface MenubarSeparatorProps extends PrimitivePropsWithRef<'div'> {
 }
+/** Props for {@link MenubarShortcut}, the keyboard hint at an item's trailing edge. */
+export interface MenubarShortcutProps extends PrimitivePropsWithRef<'span'> {
+}
 /** Props for {@link MenubarSub}, the root of a nested submenu. */
 export interface MenubarSubProps extends MenuSubProps {
 }