@skdx/react 0.26.0 → 0.28.0

package/dist/context-menu/types.d.cts

@@ -1,11 +1,134 @@
 import type * as React from 'react';
 import type { MenuSubContentProps, MenuSubProps, MenuSubTriggerProps } from '../utils/menuSub.cjs';
+import type { PassThroughProps } from '../utils/passThrough.cjs';
 import type { PortalProps } from '../utils/portal.cjs';
 import type { PrimitivePropsWithRef } from '../utils/primitive.cjs';
 import type { FocusOutsideEvent, InteractOutsideEvent } from '../utils/useDismiss.cjs';
-/** @internal Viewport coordinates of the triggering `contextmenu` event. Not part of the public API. */
+import type { AutoFocusEvent } from '../utils/useFocusTrap.cjs';
+/**
+ * Menu item entry (re-exported as `ContextMenuItem`). Discriminated union where
+ * plain action items have no `type` field; narrow with `'type' in item`. Submenus
+ * recurse through this type.
+ */
+export type MenuItem = {
+    /** Text rendered inside the derived `ContextMenuItem`, and the fallback typeahead text. */
+    label: string;
+    /**
+     * Called when this item is activated, before the recipe's own `onSelect`; both fire, and neither cancels the other.
+     * @default undefined — no-op if omitted.
+     */
+    onSelect?: () => void;
+    /**
+     * Keyboard hint rendered as a `ContextMenuShortcut` at the item's trailing edge; `aria-hidden`, so it never joins the accessible name.
+     * @default undefined — no shortcut is rendered.
+     */
+    shortcut?: string;
+    /**
+     * Marks the item `aria-disabled` and blocks selection, staying focusable so it remains discoverable.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Text typeahead matches this item by, instead of its rendered text. Reflected to `data-text-value`.
+     * @default undefined — the item's rendered text is used.
+     */
+    textValue?: string;
+} | {
+    /** Renders a `ContextMenuSeparator` — a horizontal rule between groups of items. */
+    type: 'separator';
+} | {
+    /** Renders a `ContextMenuCheckboxItem` (`role="menuitemcheckbox"`) with an `ContextMenuItemIndicator` shown only while checked. */
+    type: 'checkbox';
+    /** Text rendered inside the derived `ContextMenuCheckboxItem`. */
+    label: string;
+    /**
+     * The checked state, always externally controlled: the item reports the state it wants via `onCheckedChange` and never flips itself.
+     * @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 `ContextMenuShortcut` at the item's trailing edge.
+     * @default undefined — no shortcut is rendered.
+     */
+    shortcut?: string;
+    /**
+     * Marks the item `aria-disabled` and blocks selection, leaving it focusable.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Text typeahead matches this item by, instead of its rendered text.
+     * @default undefined — the item's rendered text is used.
+     */
+    textValue?: string;
+} | {
+    /** Renders a `ContextMenuRadioGroup` of mutually-exclusive `ContextMenuRadioItem`s. */
+    type: 'radio-group';
+    /**
+     * The selected option's `value`, always externally controlled.
+     * @default undefined — no option is selected.
+     */
+    value?: string;
+    /**
+     * Fires with the newly selected option's `value`.
+     * @default undefined — no-op if omitted.
+     */
+    onValueChange?: (value: string) => void;
+    /** The mutually-exclusive options, one derived `ContextMenuRadioItem` each. */
+    items: {
+        /** Text rendered inside the derived `ContextMenuRadioItem`. */
+        label: string;
+        /** Compared against the group's `value` to decide checked state, and reported through `onValueChange`. */
+        value: string;
+        /**
+         * Marks the option `aria-disabled` and blocks selection, leaving it focusable.
+         * @default false
+         */
+        disabled?: boolean;
+        /**
+         * Text typeahead matches this option by, instead of its rendered text.
+         * @default undefined — the option's rendered text is used.
+         */
+        textValue?: string;
+    }[];
+} | {
+    /** Renders a `ContextMenuSub`/`ContextMenuSubTrigger`/`ContextMenuSubContent` trio — a nested submenu. */
+    type: 'submenu';
+    /** Text rendered inside the derived `ContextMenuSubTrigger`. */
+    label: string;
+    /** The submenu's own entries, recursing through this same union. */
+    items: MenuItem[];
+    /**
+     * Marks the `ContextMenuSubTrigger` `aria-disabled` and blocks it from opening the submenu, leaving it focusable.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Text typeahead matches the `ContextMenuSubTrigger` by, instead of its rendered text.
+     * @default undefined — the trigger's rendered text is used.
+     */
+    textValue?: string;
+} | {
+    /** Renders a `ContextMenuGroup` (`role="group"`), captioned and named by a `ContextMenuLabel` when `label` is set. */
+    type: 'group';
+    /**
+     * Heading rendered as a `ContextMenuLabel` inside the group, the only accessible name a `role="group"` can have.
+     * @default undefined — the group is rendered unnamed.
+     */
+    label?: string;
+    /** The group's entries, recursing through this same union. */
+    items: MenuItem[];
+};
+/** Viewport coordinates the menu is placed at — the triggering `contextmenu` event's, or {@link ContextMenuProps.point}'s. */
 export interface Point {
+    /** Distance in CSS pixels from the left edge of the viewport. */
     x: number;
+    /** Distance in CSS pixels from the top edge of the viewport. */
     y: number;
 }
 /** @internal Shared state distributed from {@link ContextMenu} to its parts via context. Not part of the public API. */
@@ -13,46 +136,82 @@ export interface ContextMenuContextValue {
     triggerRef: React.RefObject<HTMLDivElement | null>;
     contentRef: React.RefObject<HTMLDivElement | null>;
     contentId: string;
+    /** Id of the Trigger region, which Content points `aria-labelledby` at. */
+    triggerId: string;
     open: boolean;
     onOpenChange: (open: boolean) => void;
+    /** Whether the page behind the open menu is inert and scroll-locked. */
+    modal: boolean;
+    /** The point Content places itself at: the root's `point` prop when set, the recorded pointer position otherwise. */
     point: Point;
     setPoint: (point: Point) => void;
 }
 /** Props for the {@link ContextMenu} root. */
-export interface ContextMenuProps {
+export interface ContextMenuProps extends PassThroughProps {
+    /**
+     * The right-clickable region, wrapped in the derived `ContextMenuTrigger`; required, since a context menu needs something to right-click on.
+     */
+    children: React.ReactNode;
+    /**
+     * The menu's entries, rendered into the derived `ContextMenuContent` panel.
+     * @default undefined — an empty menu.
+     */
+    items?: MenuItem[];
+    /**
+     * Fires with the entry that was activated — a plain item, checkbox item,
+     * submenu item, or radio option; the entry's own handler fires first, and neither cancels the other.
+     * @default undefined — no-op if omitted.
+     */
+    onSelect?: (item: MenuItem) => void;
+    /**
+     * Renders the contents of a derived item, in place of its label; not called for separators, groups or radio groups.
+     * @default undefined — the entry's `label` is rendered.
+     */
+    renderItem?: (item: MenuItem) => React.ReactNode;
     /**
-     * The trigger region and portal — the menu's own DOM (content, items) is
-     * rendered by {@link ContextMenuPortal} elsewhere.
-     * @default undefined — renders nothing if omitted.
+     * Disables the derived trigger region, letting the native browser context menu through.
+     * @default false
      */
-    children?: React.ReactNode;
+    disabled?: boolean;
     /**
      * Whether the menu is open, for controlled usage. Pair with `onOpenChange`.
      * @default undefined — uncontrolled, tracks its own open state internally.
      */
     open?: boolean;
     /**
-     * Whether the menu is initially open, for uncontrolled usage. There is no
-     * pointer event to position it at, so it opens at the viewport's top-left
-     * corner — mainly useful for tests, docs demos, and exit-animation work.
+     * Whether the menu is initially open, for uncontrolled usage; opens at the viewport's top-left corner, with no pointer event to position it at.
      * @default false
      */
     defaultOpen?: boolean;
+    /**
+     * Takes the page behind an open menu out of reach — `inert` outside the
+     * portal and scroll-locked — without trapping focus, since the WAI-ARIA
+     * menu pattern needs Tab to leave the menu.
+     * @default false — unlike `DropdownMenu`'s `true`, since modality here is still an open question.
+     */
+    modal?: boolean;
+    /**
+     * Viewport coordinates `ContextMenuContent` is placed at, overriding the
+     * position recorded from the pointer; still clamped by Content's `collisionPadding`.
+     * @default undefined — the position of the pointer that opened the menu.
+     */
+    point?: Point;
     /**
      * Fires with the new open state whenever the menu opens or closes, controlled or not.
      * @default undefined — no-op if omitted.
      */
     onOpenChange?: (open: boolean) => void;
     /**
-     * Fires with the new open state once the change has finished on screen —
-     * after `ContextMenuContent`'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 with the new open state once the change has finished on screen,
+     * after animation or as soon as the panel settles.
      * @default undefined — no-op if omitted.
      */
     onOpenChangeComplete?: (open: boolean) => void;
 }
-/** Props for {@link ContextMenuTrigger}, the region that opens the menu on right-click/long-press. */
+/**
+ * Props for {@link ContextMenuTrigger}, the region that opens the menu on
+ * right-click, a touch long press, or Shift+F10 / the Menu key.
+ */
 export interface ContextMenuTriggerProps extends PrimitivePropsWithRef<'div'> {
     /**
      * Disables the context menu for this region, letting the native browser context menu through.
@@ -63,9 +222,7 @@ export interface ContextMenuTriggerProps extends PrimitivePropsWithRef<'div'> {
 /** Props for {@link ContextMenuPortal}, which teleports its children to `document.body`. */
 export interface ContextMenuPortalProps extends PortalProps {
     /**
-     * Render the portal even while the menu is closed, instead of unmounting
-     * it. Useful for animation libraries that need the outgoing content
-     * present in the DOM during an exit transition.
+     * Render the portal even while the menu is closed, instead of unmounting it.
      * @default false
      */
     forceMount?: boolean;
@@ -73,21 +230,17 @@ export interface ContextMenuPortalProps extends PortalProps {
 /** Props for {@link ContextMenuContent}, the menu panel positioned at the pointer. */
 export interface ContextMenuContentProps extends PrimitivePropsWithRef<'div'> {
     /**
-     * Keep this panel mounted even while the menu is closed. Useful for
-     * animation libraries that need the outgoing panel present in the DOM
-     * during an exit transition.
+     * Keep this panel mounted even while the menu is closed.
      * @default false
      */
     forceMount?: boolean;
     /**
-     * Whether Up/Down arrow-key navigation wraps from the last item back to
-     * the first (and vice versa).
+     * Whether Up/Down arrow-key navigation wraps from the last item back to the first.
      * @default true
      */
     loop?: boolean;
     /**
-     * Minimum distance (px) kept between the menu and the viewport edge when
-     * clamping its position so it never overflows the screen.
+     * Minimum distance (px) kept between the menu and the viewport edge when clamping its position.
      * @default 8
      */
     collisionPadding?: number;
@@ -102,23 +255,34 @@ export interface ContextMenuContentProps extends PrimitivePropsWithRef<'div'> {
      */
     onPointerDownOutside?: (event: PointerEvent) => void;
     /**
-     * Fires when focus moves to an element outside the content. Call `event.preventDefault()` to stop the menu from closing. Receives a cancelable stand-in carrying the original `focusin` as its `detail`, since `focusin` itself cannot be canceled.
+     * Fires when focus moves outside the content. Receives a cancelable stand-in carrying the original `focusin` as its `detail`.
      * @default undefined — no-op if omitted.
      */
     onFocusOutside?: (event: FocusOutsideEvent) => void;
     /**
-     * Fires for either kind of outside interaction — pointer-down or focus — immediately before the specific handler above and with the same event, so one `event.preventDefault()` here vetoes the dismissal whichever way it was triggered.
+     * Fires for either kind of outside interaction, immediately before the specific handler above and with the same event.
      * @default undefined — no-op if omitted.
      */
     onInteractOutside?: (event: InteractOutsideEvent) => void;
+    /**
+     * Fires just before focus returns to the Trigger region as the menu closes; call `event.preventDefault()` to place focus yourself.
+     * @default undefined — no-op if omitted.
+     */
+    onCloseAutoFocus?: (event: AutoFocusEvent) => void;
 }
 /** Props for a single {@link ContextMenuItem}. */
 export interface ContextMenuItemProps extends Omit<PrimitivePropsWithRef<'div'>, 'onSelect'> {
     /**
-     * Excludes the item from roving-focus navigation and blocks selection.
+     * Marks the item aria-disabled and blocks selection, staying focusable so a keyboard user still discovers the command.
      * @default false
      */
     disabled?: boolean;
+    /**
+     * Text typeahead matches this item by, instead of its rendered text; reflected to `data-text-value`. Set explicitly
+     * for an item whose rendered content is more than its label, such as one with an `ContextMenuItemIndicator` or an icon only.
+     * @default undefined — the item's rendered text is used.
+     */
+    textValue?: string;
     /**
      * Called when the item is activated. `event.preventDefault()` keeps the menu open.
      * @default undefined — no-op if omitted.
@@ -164,9 +328,7 @@ export interface ContextMenuRadioItemProps extends ContextMenuItemProps {
 /** Props for {@link ContextMenuItemIndicator}, the checked-state glyph inside a checkbox/radio item. */
 export interface ContextMenuItemIndicatorProps extends PrimitivePropsWithRef<'span'> {
     /**
-     * Render even while unchecked, instead of unmounting. Useful for
-     * animation libraries that need the outgoing indicator present in the DOM
-     * during an exit transition.
+     * Render even while unchecked, instead of unmounting.
      * @default false
      */
     forceMount?: boolean;
@@ -180,6 +342,9 @@ export interface ContextMenuLabelProps extends PrimitivePropsWithRef<'div'> {
 /** Props for {@link ContextMenuSeparator}, a visual divider between items or groups. */
 export interface ContextMenuSeparatorProps extends PrimitivePropsWithRef<'div'> {
 }
+/** Props for {@link ContextMenuShortcut}, the keyboard hint at an item's trailing edge. */
+export interface ContextMenuShortcutProps extends PrimitivePropsWithRef<'span'> {
+}
 /** Props for {@link ContextMenuSub}, the root of a nested submenu. */
 export interface ContextMenuSubProps extends MenuSubProps {
 }

package/dist/context-menu/types.d.ts

@@ -1,11 +1,134 @@
 import type * as React from 'react';
 import type { MenuSubContentProps, MenuSubProps, MenuSubTriggerProps } from '../utils/menuSub.js';
+import type { PassThroughProps } from '../utils/passThrough.js';
 import type { PortalProps } from '../utils/portal.js';
 import type { PrimitivePropsWithRef } from '../utils/primitive.js';
 import type { FocusOutsideEvent, InteractOutsideEvent } from '../utils/useDismiss.js';
-/** @internal Viewport coordinates of the triggering `contextmenu` event. Not part of the public API. */
+import type { AutoFocusEvent } from '../utils/useFocusTrap.js';
+/**
+ * Menu item entry (re-exported as `ContextMenuItem`). Discriminated union where
+ * plain action items have no `type` field; narrow with `'type' in item`. Submenus
+ * recurse through this type.
+ */
+export type MenuItem = {
+    /** Text rendered inside the derived `ContextMenuItem`, and the fallback typeahead text. */
+    label: string;
+    /**
+     * Called when this item is activated, before the recipe's own `onSelect`; both fire, and neither cancels the other.
+     * @default undefined — no-op if omitted.
+     */
+    onSelect?: () => void;
+    /**
+     * Keyboard hint rendered as a `ContextMenuShortcut` at the item's trailing edge; `aria-hidden`, so it never joins the accessible name.
+     * @default undefined — no shortcut is rendered.
+     */
+    shortcut?: string;
+    /**
+     * Marks the item `aria-disabled` and blocks selection, staying focusable so it remains discoverable.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Text typeahead matches this item by, instead of its rendered text. Reflected to `data-text-value`.
+     * @default undefined — the item's rendered text is used.
+     */
+    textValue?: string;
+} | {
+    /** Renders a `ContextMenuSeparator` — a horizontal rule between groups of items. */
+    type: 'separator';
+} | {
+    /** Renders a `ContextMenuCheckboxItem` (`role="menuitemcheckbox"`) with an `ContextMenuItemIndicator` shown only while checked. */
+    type: 'checkbox';
+    /** Text rendered inside the derived `ContextMenuCheckboxItem`. */
+    label: string;
+    /**
+     * The checked state, always externally controlled: the item reports the state it wants via `onCheckedChange` and never flips itself.
+     * @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 `ContextMenuShortcut` at the item's trailing edge.
+     * @default undefined — no shortcut is rendered.
+     */
+    shortcut?: string;
+    /**
+     * Marks the item `aria-disabled` and blocks selection, leaving it focusable.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Text typeahead matches this item by, instead of its rendered text.
+     * @default undefined — the item's rendered text is used.
+     */
+    textValue?: string;
+} | {
+    /** Renders a `ContextMenuRadioGroup` of mutually-exclusive `ContextMenuRadioItem`s. */
+    type: 'radio-group';
+    /**
+     * The selected option's `value`, always externally controlled.
+     * @default undefined — no option is selected.
+     */
+    value?: string;
+    /**
+     * Fires with the newly selected option's `value`.
+     * @default undefined — no-op if omitted.
+     */
+    onValueChange?: (value: string) => void;
+    /** The mutually-exclusive options, one derived `ContextMenuRadioItem` each. */
+    items: {
+        /** Text rendered inside the derived `ContextMenuRadioItem`. */
+        label: string;
+        /** Compared against the group's `value` to decide checked state, and reported through `onValueChange`. */
+        value: string;
+        /**
+         * Marks the option `aria-disabled` and blocks selection, leaving it focusable.
+         * @default false
+         */
+        disabled?: boolean;
+        /**
+         * Text typeahead matches this option by, instead of its rendered text.
+         * @default undefined — the option's rendered text is used.
+         */
+        textValue?: string;
+    }[];
+} | {
+    /** Renders a `ContextMenuSub`/`ContextMenuSubTrigger`/`ContextMenuSubContent` trio — a nested submenu. */
+    type: 'submenu';
+    /** Text rendered inside the derived `ContextMenuSubTrigger`. */
+    label: string;
+    /** The submenu's own entries, recursing through this same union. */
+    items: MenuItem[];
+    /**
+     * Marks the `ContextMenuSubTrigger` `aria-disabled` and blocks it from opening the submenu, leaving it focusable.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Text typeahead matches the `ContextMenuSubTrigger` by, instead of its rendered text.
+     * @default undefined — the trigger's rendered text is used.
+     */
+    textValue?: string;
+} | {
+    /** Renders a `ContextMenuGroup` (`role="group"`), captioned and named by a `ContextMenuLabel` when `label` is set. */
+    type: 'group';
+    /**
+     * Heading rendered as a `ContextMenuLabel` inside the group, the only accessible name a `role="group"` can have.
+     * @default undefined — the group is rendered unnamed.
+     */
+    label?: string;
+    /** The group's entries, recursing through this same union. */
+    items: MenuItem[];
+};
+/** Viewport coordinates the menu is placed at — the triggering `contextmenu` event's, or {@link ContextMenuProps.point}'s. */
 export interface Point {
+    /** Distance in CSS pixels from the left edge of the viewport. */
     x: number;
+    /** Distance in CSS pixels from the top edge of the viewport. */
     y: number;
 }
 /** @internal Shared state distributed from {@link ContextMenu} to its parts via context. Not part of the public API. */
@@ -13,46 +136,82 @@ export interface ContextMenuContextValue {
     triggerRef: React.RefObject<HTMLDivElement | null>;
     contentRef: React.RefObject<HTMLDivElement | null>;
     contentId: string;
+    /** Id of the Trigger region, which Content points `aria-labelledby` at. */
+    triggerId: string;
     open: boolean;
     onOpenChange: (open: boolean) => void;
+    /** Whether the page behind the open menu is inert and scroll-locked. */
+    modal: boolean;
+    /** The point Content places itself at: the root's `point` prop when set, the recorded pointer position otherwise. */
     point: Point;
     setPoint: (point: Point) => void;
 }
 /** Props for the {@link ContextMenu} root. */
-export interface ContextMenuProps {
+export interface ContextMenuProps extends PassThroughProps {
+    /**
+     * The right-clickable region, wrapped in the derived `ContextMenuTrigger`; required, since a context menu needs something to right-click on.
+     */
+    children: React.ReactNode;
+    /**
+     * The menu's entries, rendered into the derived `ContextMenuContent` panel.
+     * @default undefined — an empty menu.
+     */
+    items?: MenuItem[];
+    /**
+     * Fires with the entry that was activated — a plain item, checkbox item,
+     * submenu item, or radio option; the entry's own handler fires first, and neither cancels the other.
+     * @default undefined — no-op if omitted.
+     */
+    onSelect?: (item: MenuItem) => void;
+    /**
+     * Renders the contents of a derived item, in place of its label; not called for separators, groups or radio groups.
+     * @default undefined — the entry's `label` is rendered.
+     */
+    renderItem?: (item: MenuItem) => React.ReactNode;
     /**
-     * The trigger region and portal — the menu's own DOM (content, items) is
-     * rendered by {@link ContextMenuPortal} elsewhere.
-     * @default undefined — renders nothing if omitted.
+     * Disables the derived trigger region, letting the native browser context menu through.
+     * @default false
      */
-    children?: React.ReactNode;
+    disabled?: boolean;
     /**
      * Whether the menu is open, for controlled usage. Pair with `onOpenChange`.
      * @default undefined — uncontrolled, tracks its own open state internally.
      */
     open?: boolean;
     /**
-     * Whether the menu is initially open, for uncontrolled usage. There is no
-     * pointer event to position it at, so it opens at the viewport's top-left
-     * corner — mainly useful for tests, docs demos, and exit-animation work.
+     * Whether the menu is initially open, for uncontrolled usage; opens at the viewport's top-left corner, with no pointer event to position it at.
      * @default false
      */
     defaultOpen?: boolean;
+    /**
+     * Takes the page behind an open menu out of reach — `inert` outside the
+     * portal and scroll-locked — without trapping focus, since the WAI-ARIA
+     * menu pattern needs Tab to leave the menu.
+     * @default false — unlike `DropdownMenu`'s `true`, since modality here is still an open question.
+     */
+    modal?: boolean;
+    /**
+     * Viewport coordinates `ContextMenuContent` is placed at, overriding the
+     * position recorded from the pointer; still clamped by Content's `collisionPadding`.
+     * @default undefined — the position of the pointer that opened the menu.
+     */
+    point?: Point;
     /**
      * Fires with the new open state whenever the menu opens or closes, controlled or not.
      * @default undefined — no-op if omitted.
      */
     onOpenChange?: (open: boolean) => void;
     /**
-     * Fires with the new open state once the change has finished on screen —
-     * after `ContextMenuContent`'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 with the new open state once the change has finished on screen,
+     * after animation or as soon as the panel settles.
      * @default undefined — no-op if omitted.
      */
     onOpenChangeComplete?: (open: boolean) => void;
 }
-/** Props for {@link ContextMenuTrigger}, the region that opens the menu on right-click/long-press. */
+/**
+ * Props for {@link ContextMenuTrigger}, the region that opens the menu on
+ * right-click, a touch long press, or Shift+F10 / the Menu key.
+ */
 export interface ContextMenuTriggerProps extends PrimitivePropsWithRef<'div'> {
     /**
      * Disables the context menu for this region, letting the native browser context menu through.
@@ -63,9 +222,7 @@ export interface ContextMenuTriggerProps extends PrimitivePropsWithRef<'div'> {
 /** Props for {@link ContextMenuPortal}, which teleports its children to `document.body`. */
 export interface ContextMenuPortalProps extends PortalProps {
     /**
-     * Render the portal even while the menu is closed, instead of unmounting
-     * it. Useful for animation libraries that need the outgoing content
-     * present in the DOM during an exit transition.
+     * Render the portal even while the menu is closed, instead of unmounting it.
      * @default false
      */
     forceMount?: boolean;
@@ -73,21 +230,17 @@ export interface ContextMenuPortalProps extends PortalProps {
 /** Props for {@link ContextMenuContent}, the menu panel positioned at the pointer. */
 export interface ContextMenuContentProps extends PrimitivePropsWithRef<'div'> {
     /**
-     * Keep this panel mounted even while the menu is closed. Useful for
-     * animation libraries that need the outgoing panel present in the DOM
-     * during an exit transition.
+     * Keep this panel mounted even while the menu is closed.
      * @default false
      */
     forceMount?: boolean;
     /**
-     * Whether Up/Down arrow-key navigation wraps from the last item back to
-     * the first (and vice versa).
+     * Whether Up/Down arrow-key navigation wraps from the last item back to the first.
      * @default true
      */
     loop?: boolean;
     /**
-     * Minimum distance (px) kept between the menu and the viewport edge when
-     * clamping its position so it never overflows the screen.
+     * Minimum distance (px) kept between the menu and the viewport edge when clamping its position.
      * @default 8
      */
     collisionPadding?: number;
@@ -102,23 +255,34 @@ export interface ContextMenuContentProps extends PrimitivePropsWithRef<'div'> {
      */
     onPointerDownOutside?: (event: PointerEvent) => void;
     /**
-     * Fires when focus moves to an element outside the content. Call `event.preventDefault()` to stop the menu from closing. Receives a cancelable stand-in carrying the original `focusin` as its `detail`, since `focusin` itself cannot be canceled.
+     * Fires when focus moves outside the content. Receives a cancelable stand-in carrying the original `focusin` as its `detail`.
      * @default undefined — no-op if omitted.
      */
     onFocusOutside?: (event: FocusOutsideEvent) => void;
     /**
-     * Fires for either kind of outside interaction — pointer-down or focus — immediately before the specific handler above and with the same event, so one `event.preventDefault()` here vetoes the dismissal whichever way it was triggered.
+     * Fires for either kind of outside interaction, immediately before the specific handler above and with the same event.
      * @default undefined — no-op if omitted.
      */
     onInteractOutside?: (event: InteractOutsideEvent) => void;
+    /**
+     * Fires just before focus returns to the Trigger region as the menu closes; call `event.preventDefault()` to place focus yourself.
+     * @default undefined — no-op if omitted.
+     */
+    onCloseAutoFocus?: (event: AutoFocusEvent) => void;
 }
 /** Props for a single {@link ContextMenuItem}. */
 export interface ContextMenuItemProps extends Omit<PrimitivePropsWithRef<'div'>, 'onSelect'> {
     /**
-     * Excludes the item from roving-focus navigation and blocks selection.
+     * Marks the item aria-disabled and blocks selection, staying focusable so a keyboard user still discovers the command.
      * @default false
      */
     disabled?: boolean;
+    /**
+     * Text typeahead matches this item by, instead of its rendered text; reflected to `data-text-value`. Set explicitly
+     * for an item whose rendered content is more than its label, such as one with an `ContextMenuItemIndicator` or an icon only.
+     * @default undefined — the item's rendered text is used.
+     */
+    textValue?: string;
     /**
      * Called when the item is activated. `event.preventDefault()` keeps the menu open.
      * @default undefined — no-op if omitted.
@@ -164,9 +328,7 @@ export interface ContextMenuRadioItemProps extends ContextMenuItemProps {
 /** Props for {@link ContextMenuItemIndicator}, the checked-state glyph inside a checkbox/radio item. */
 export interface ContextMenuItemIndicatorProps extends PrimitivePropsWithRef<'span'> {
     /**
-     * Render even while unchecked, instead of unmounting. Useful for
-     * animation libraries that need the outgoing indicator present in the DOM
-     * during an exit transition.
+     * Render even while unchecked, instead of unmounting.
      * @default false
      */
     forceMount?: boolean;
@@ -180,6 +342,9 @@ export interface ContextMenuLabelProps extends PrimitivePropsWithRef<'div'> {
 /** Props for {@link ContextMenuSeparator}, a visual divider between items or groups. */
 export interface ContextMenuSeparatorProps extends PrimitivePropsWithRef<'div'> {
 }
+/** Props for {@link ContextMenuShortcut}, the keyboard hint at an item's trailing edge. */
+export interface ContextMenuShortcutProps extends PrimitivePropsWithRef<'span'> {
+}
 /** Props for {@link ContextMenuSub}, the root of a nested submenu. */
 export interface ContextMenuSubProps extends MenuSubProps {
 }

package/dist/data-list/DataList.cjs

@@ -1 +1 @@
-"use strict";var k=Object.create;var s=Object.defineProperty;var v=Object.getOwnPropertyDescriptor;var w=Object.getOwnPropertyNames;var H=Object.getPrototypeOf,M=Object.prototype.hasOwnProperty;var S=(t,a)=>{for(var e in a)s(t,e,{get:a[e],enumerable:!0})},L=(t,a,e,o)=>{if(a&&typeof a=="object"||typeof a=="function")for(let r of w(a))!M.call(t,r)&&r!==e&&s(t,r,{get:()=>a[r],enumerable:!(o=v(a,r))||o.enumerable});return t};var m=(t,a,e)=>(e=t!=null?k(H(t)):{},L(a||!t||!t.__esModule?s(e,"default",{value:t,enumerable:!0}):e,t)),h=t=>L(s({},"__esModule",{value:!0}),t);var z={};S(z,{DataList:()=>c,DataListItem:()=>i,DataListLabel:()=>p,DataListValue:()=>l});module.exports=h(z);var f=m(require("react"),1),D=require("../utils/part.cjs"),d=require("../utils/slot.cjs"),n=require("react/jsx-runtime"),c=f.forwardRef(({asChild:t,orientation:a="horizontal",...e},o)=>(0,n.jsx)(t?d.Slot:"dl",{"data-orientation":a,...e,...(0,D.skdxPart)("data-list","root",e.className),ref:o}));c.displayName="DataList";var y=m(require("react"),1),P=require("../utils/part.cjs"),R=require("../utils/primitive.cjs"),x=require("react/jsx-runtime"),i=y.forwardRef((t,a)=>(0,x.jsx)(R.Primitive.div,{...t,...(0,P.skdxPart)("data-list","item",t.className),ref:a}));i.displayName="DataListItem";var N=m(require("react"),1),b=require("../utils/part.cjs"),E=require("../utils/slot.cjs"),T=require("react/jsx-runtime"),p=N.forwardRef(({asChild:t,...a},e)=>(0,T.jsx)(t?E.Slot:"dt",{...a,...(0,b.skdxPart)("data-list","label",a.className),ref:e}));p.displayName="DataListLabel";var u=m(require("react"),1),C=require("../utils/part.cjs"),I=require("../utils/slot.cjs"),V=require("react/jsx-runtime"),l=u.forwardRef(({asChild:t,...a},e)=>(0,V.jsx)(t?I.Slot:"dd",{...a,...(0,C.skdxPart)("data-list","value",a.className),ref:e}));l.displayName="DataListValue";0&&(module.exports={DataList,DataListItem,DataListLabel,DataListValue});
+"use strict";var H=Object.create;var s=Object.defineProperty;var M=Object.getOwnPropertyDescriptor;var S=Object.getOwnPropertyNames;var A=Object.getPrototypeOf,h=Object.prototype.hasOwnProperty;var z=(t,a)=>{for(var o in a)s(t,o,{get:a[o],enumerable:!0})},y=(t,a,o,m)=>{if(a&&typeof a=="object"||typeof a=="function")for(let e of S(a))!h.call(t,e)&&e!==o&&s(t,e,{get:()=>a[e],enumerable:!(m=M(a,e))||m.enumerable});return t};var i=(t,a,o)=>(o=t!=null?H(A(t)):{},y(a||!t||!t.__esModule?s(o,"default",{value:t,enumerable:!0}):o,t)),O=t=>y(s({},"__esModule",{value:!0}),t);var g={};z(g,{DataList:()=>D,DataListItem:()=>p,DataListLabel:()=>l,DataListValue:()=>L});module.exports=O(g);var V=i(require("react"),1),k=require("../utils/part.cjs"),v=require("../utils/slot.cjs");var n=i(require("react"),1),d=require("../utils/part.cjs"),c=require("../utils/primitive.cjs"),R=require("react/jsx-runtime"),p=n.forwardRef((t,a)=>(0,R.jsx)(c.Primitive.div,{...t,...(0,d.skdxPart)("data-list","item",t.className),ref:a}));p.displayName="DataListItem";var P=i(require("react"),1),x=require("../utils/part.cjs"),E=require("../utils/slot.cjs"),b=require("react/jsx-runtime"),l=P.forwardRef(({asChild:t,...a},o)=>(0,b.jsx)(t?E.Slot:"dt",{...a,...(0,x.skdxPart)("data-list","label",a.className),ref:o}));l.displayName="DataListLabel";var N=i(require("react"),1),C=require("../utils/part.cjs"),T=require("../utils/slot.cjs"),u=require("react/jsx-runtime"),L=N.forwardRef(({asChild:t,...a},o)=>(0,u.jsx)(t?T.Slot:"dd",{...a,...(0,C.skdxPart)("data-list","value",a.className),ref:o}));L.displayName="DataListValue";var r=require("react/jsx-runtime"),I=({items:t=[]})=>(0,r.jsx)(r.Fragment,{children:t.map((a,o)=>(0,r.jsxs)(p,{children:[(0,r.jsx)(l,{children:a.label}),(0,r.jsx)(L,{children:a.value})]},o))});var f=require("react/jsx-runtime"),D=V.forwardRef(({asChild:t,orientation:a="horizontal",items:o,children:m,...e},w)=>(0,f.jsx)(t?v.Slot:"dl",{"data-orientation":a,...e,...(0,k.skdxPart)("data-list","root",e.className),ref:w,children:m??(0,f.jsx)(I,{items:o})}));D.displayName="DataList";0&&(module.exports={DataList,DataListItem,DataListLabel,DataListValue});