diff --git a/packages/components/src/menu/checkbox-item.tsx b/packages/components/src/menu/checkbox-item.tsx index ddb700b43324a6..69339387c3add5 100644 --- a/packages/components/src/menu/checkbox-item.tsx +++ b/packages/components/src/menu/checkbox-item.tsx @@ -21,7 +21,7 @@ export const MenuCheckboxItem = forwardRef< HTMLDivElement, WordPressComponentProps< MenuCheckboxItemProps, 'div', false > >( function MenuCheckboxItem( - { suffix, children, hideOnClick = false, ...props }, + { suffix, children, disabled = false, hideOnClick = false, ...props }, ref ) { const menuContext = useContext( MenuContext ); @@ -37,6 +37,7 @@ export const MenuCheckboxItem = forwardRef< ref={ ref } { ...props } accessibleWhenDisabled + disabled={ disabled } hideOnClick={ hideOnClick } store={ menuContext.store } > diff --git a/packages/components/src/menu/item.tsx b/packages/components/src/menu/item.tsx index 84ff050bcc2236..a716cbcc89654c 100644 --- a/packages/components/src/menu/item.tsx +++ b/packages/components/src/menu/item.tsx @@ -15,7 +15,15 @@ export const MenuItem = forwardRef< HTMLDivElement, WordPressComponentProps< MenuItemProps, 'div', false > >( function MenuItem( - { prefix, suffix, children, hideOnClick = true, store, ...props }, + { + prefix, + suffix, + children, + disabled = false, + hideOnClick = true, + store, + ...props + }, ref ) { const menuContext = useContext( MenuContext ); @@ -37,6 +45,7 @@ export const MenuItem = forwardRef< ref={ ref } { ...props } accessibleWhenDisabled + disabled={ disabled } hideOnClick={ hideOnClick } store={ computedStore } > diff --git a/packages/components/src/menu/radio-item.tsx b/packages/components/src/menu/radio-item.tsx index 5534a6b7f3e10c..28b3199d7d36b8 100644 --- a/packages/components/src/menu/radio-item.tsx +++ b/packages/components/src/menu/radio-item.tsx @@ -28,7 +28,7 @@ export const MenuRadioItem = forwardRef< HTMLDivElement, WordPressComponentProps< MenuRadioItemProps, 'div', false > >( function MenuRadioItem( - { suffix, children, hideOnClick = false, ...props }, + { suffix, children, disabled = false, hideOnClick = false, ...props }, ref ) { const menuContext = useContext( MenuContext ); @@ -44,6 +44,7 @@ export const MenuRadioItem = forwardRef< ref={ ref } { ...props } accessibleWhenDisabled + disabled={ disabled } hideOnClick={ hideOnClick } store={ menuContext.store } > diff --git a/packages/components/src/menu/types.ts b/packages/components/src/menu/types.ts index f58b5bcc89b953..f9bb0782529d1f 100644 --- a/packages/components/src/menu/types.ts +++ b/packages/components/src/menu/types.ts @@ -2,7 +2,6 @@ * External dependencies */ import type * as Ariakit from '@ariakit/react'; -import type { Placement } from '@floating-ui/react-dom'; export interface MenuContext { /** @@ -17,77 +16,93 @@ export interface MenuContext { export interface MenuProps { /** - * The contents of the menu (ie. one or more menu items). + * The elements, which should include one instance of the `Menu.TriggerButton` + * component and one instance of the `Menu.Popover` component. */ - children?: React.ReactNode; + children?: Ariakit.MenuProviderProps[ 'children' ]; /** - * The open state of the menu popover when it is initially rendered. Use when - * not wanting to control its open state. + * Whether the menu popover and its contents should be visible by default. + * + * Note: this prop will be overridden by the `open` prop if it is + * provided (meaning the component will be used in "controlled" mode). * * @default false */ - defaultOpen?: boolean; + defaultOpen?: Ariakit.MenuProviderProps[ 'defaultOpen' ]; /** - * The controlled open state of the menu popover. Must be used in conjunction - * with `onOpenChange`. + * Whether the menu popover and its contents should be visible. + * Should be used in conjunction with `onOpenChange` in order to control + * the open state of the menu popover. + * + * Note: this prop will set the component in "controlled" mode, and it will + * override the `defaultOpen` prop. */ - open?: boolean; + open?: Ariakit.MenuProviderProps[ 'open' ]; /** - * Event handler called when the open state of the menu popover changes. + * A callback that gets called when the `open` state changes. */ - onOpenChange?: ( open: boolean ) => void; + onOpenChange?: Ariakit.MenuProviderProps[ 'setOpen' ]; /** * The placement of the menu popover. * - * @default 'bottom-start' for root-level menus, 'right-start' for nested menus + * @default 'bottom-start' for root-level menus, 'right-start' for submenus */ - placement?: Placement; + placement?: Ariakit.MenuProviderProps[ 'placement' ]; } export interface MenuPopoverProps { /** - * The contents of the dropdown. + * The contents of the menu popover, which should include instances of the + * `Menu.Item`, `Menu.CheckboxItem`, `Menu.RadioItem`, `Menu.Group`, and + * `Menu.Separator` components. */ - children?: React.ReactNode; + children?: Ariakit.MenuProps[ 'children' ]; /** * The modality of the menu popover. When set to true, interaction with * outside elements will be disabled and only menu content will be visible to * screen readers. * + * Determines whether the menu popover is modal. Modal dialogs have distinct + * states and behaviors: + * - The `portal` and `preventBodyScroll` props are set to `true`. They can + * still be manually set to `false`. + * - When the dialog is open, element tree outside it will be inert. + * * @default true */ - modal?: boolean; + modal?: Ariakit.MenuProps[ 'modal' ]; /** * The distance between the popover and the anchor element. * * @default 8 for root-level menus, 16 for nested menus */ - gutter?: number; + gutter?: Ariakit.MenuProps[ 'gutter' ]; /** * The skidding of the popover along the anchor element. Can be set to * negative values to make the popover shift to the opposite side. * * @default 0 for root-level menus, -8 for nested menus */ - shift?: number; + shift?: Ariakit.MenuProps[ 'shift' ]; /** - * Determines whether the menu popover will be hidden when the user presses - * the Escape key. + * Determines if the menu popover will hide when the user presses the + * Escape key. + * + * This prop can be either a boolean or a function that accepts an event as an + * argument and returns a boolean. The event object represents the keydown + * event that initiated the hide action, which could be either a native + * keyboard event or a React synthetic event. * * @default `( event ) => { event.preventDefault(); return true; }` */ - hideOnEscape?: - | boolean - | ( ( - event: KeyboardEvent | React.KeyboardEvent< Element > - ) => boolean ); + hideOnEscape?: Ariakit.MenuProps[ 'hideOnEscape' ]; } export interface MenuTriggerButtonProps { /** * The contents of the menu trigger button. */ - children?: React.ReactNode; + children?: Ariakit.MenuButtonProps[ 'children' ]; /** * Allows the component to be rendered as a different HTML element or React * component. The value can be a React element or a function that takes in the @@ -103,9 +118,6 @@ export interface MenuTriggerButtonProps { * This feature can be combined with the `accessibleWhenDisabled` prop to * make disabled elements still accessible via keyboard. * - * **Note**: For this prop to work, the `focusable` prop must be set to - * `true`, if it's not set by default. - * * @default false */ disabled?: Ariakit.MenuButtonProps[ 'disabled' ]; @@ -129,42 +141,54 @@ export interface MenuTriggerButtonProps { export interface MenuGroupProps { /** - * The contents of the menu group (ie. an optional menu group label and one - * or more menu items). + * The contents of the menu group, which should include one instance of the + * `Menu.GroupLabel` component and one or more instances of `Menu.Item`, + * `Menu.CheckboxItem`, and `Menu.RadioItem`. */ - children: React.ReactNode; + children: Ariakit.MenuGroupProps[ 'children' ]; } export interface MenuGroupLabelProps { /** - * The contents of the menu group label. + * The contents of the menu group label, which should provide an accessible + * label for the menu group. */ - children: React.ReactNode; + children: Ariakit.MenuGroupLabelProps[ 'children' ]; } export interface MenuItemProps { /** - * The contents of the menu item. + * The contents of the menu item, which could include one instance of the + * `Menu.ItemLabel` component and/or one instance of the `Menu.ItemHelpText` + * component. */ - children: React.ReactNode; + children: Ariakit.MenuItemProps[ 'children' ]; /** - * The contents of the menu item's prefix. + * The contents of the menu item's prefix, such as an icon. */ prefix?: React.ReactNode; /** - * The contents of the menu item's suffix. + * The contents of the menu item's suffix, such as a keyboard shortcut. */ suffix?: React.ReactNode; /** - * Whether to hide the menu popover when the menu item is clicked. + * Determines if the menu should hide when this item is clicked. + * + * **Note**: This behavior isn't triggered if this menu item is rendered as a + * link and modifier keys are used to either open the link in a new tab or + * download it. * * @default true */ - hideOnClick?: boolean; + hideOnClick?: Ariakit.MenuItemProps[ 'hideOnClick' ]; /** - * Determines if the element is disabled. + * Determines if the element is disabled. This sets the `aria-disabled` + * attribute accordingly, enabling support for all elements, including those + * that don't support the native `disabled` attribute. + * + * @default false */ - disabled?: boolean; + disabled?: Ariakit.MenuItemProps[ 'disabled' ]; /** * Allows the component to be rendered as a different HTML element or React * component. The value can be a React element or a function that takes in the @@ -173,73 +197,137 @@ export interface MenuItemProps { */ render?: Ariakit.MenuItemProps[ 'render' ]; /** - * The ariakit store. This prop is only meant for internal use. + * The ariakit menu store. This prop is only meant for internal use. * @ignore */ store?: Ariakit.MenuItemProps[ 'store' ]; } -export interface MenuCheckboxItemProps - extends Omit< MenuItemProps, 'prefix' | 'hideOnClick' > { +export interface MenuCheckboxItemProps { /** - * Whether to hide the menu popover when the menu item is clicked. + * The contents of the menu item, which could include one instance of the + * `Menu.ItemLabel` component and/or one instance of the `Menu.ItemHelpText` + * component. + */ + children: Ariakit.MenuItemCheckboxProps[ 'children' ]; + /** + * The contents of the menu item's suffix, such as a keyboard shortcut. + */ + suffix?: React.ReactNode; + /** + * Determines if the menu should hide when this item is clicked. + * + * **Note**: This behavior isn't triggered if this menu item is rendered as a + * link and modifier keys are used to either open the link in a new tab or + * download it. * * @default false */ - hideOnClick?: boolean; + hideOnClick?: Ariakit.MenuItemCheckboxProps[ 'hideOnClick' ]; + /** + * Determines if the element is disabled. This sets the `aria-disabled` + * attribute accordingly, enabling support for all elements, including those + * that don't support the native `disabled` attribute. + * + * @default false + */ + disabled?: Ariakit.MenuItemCheckboxProps[ 'disabled' ]; + /** + * Allows the component to be rendered as a different HTML element or React + * component. The value can be a React element or a function that takes in the + * original component props and gives back a React element with the props + * merged. + */ + render?: Ariakit.MenuItemCheckboxProps[ 'render' ]; /** * The checkbox menu item's name. */ - name: string; + name: Ariakit.MenuItemCheckboxProps[ 'name' ]; /** * The checkbox item's value, useful when using multiple checkbox menu items * associated to the same `name`. */ - value?: string; + value?: Ariakit.MenuItemCheckboxProps[ 'value' ]; /** * The controlled checked state of the checkbox menu item. + * + * Note: this prop will override the `defaultChecked` prop. */ - checked?: boolean; + checked?: Ariakit.MenuItemCheckboxProps[ 'checked' ]; /** * The checked state of the checkbox menu item when it is initially rendered. * Use when not wanting to control its checked state. + * + * Note: this prop will be overriden by the `checked` prop, if it is defined. */ - defaultChecked?: boolean; + defaultChecked?: Ariakit.MenuItemCheckboxProps[ 'defaultChecked' ]; /** - * Event handler called when the checked state of the checkbox menu item changes. + * A function that is called when the checkbox's checked state changes. */ - onChange?: ( event: React.ChangeEvent< HTMLInputElement > ) => void; + onChange?: Ariakit.MenuItemCheckboxProps[ 'onChange' ]; } -export interface MenuRadioItemProps - extends Omit< MenuItemProps, 'prefix' | 'hideOnClick' > { +export interface MenuRadioItemProps { + /** + * The contents of the menu item, which could include one instance of the + * `Menu.ItemLabel` component and/or one instance of the `Menu.ItemHelpText` + * component. + */ + children: Ariakit.MenuItemRadioProps[ 'children' ]; + /** + * The contents of the menu item's suffix, such as a keyboard shortcut. + */ + suffix?: React.ReactNode; + /** + * Determines if the menu should hide when this item is clicked. + * + * **Note**: This behavior isn't triggered if this menu item is rendered as a + * link and modifier keys are used to either open the link in a new tab or + * download it. + * + * @default false + */ + hideOnClick?: Ariakit.MenuItemRadioProps[ 'hideOnClick' ]; /** - * Whether to hide the menu popover when the menu item is clicked. + * Determines if the element is disabled. This sets the `aria-disabled` + * attribute accordingly, enabling support for all elements, including those + * that don't support the native `disabled` attribute. * * @default false */ - hideOnClick?: boolean; + disabled?: Ariakit.MenuItemRadioProps[ 'disabled' ]; + /** + * Allows the component to be rendered as a different HTML element or React + * component. The value can be a React element or a function that takes in the + * original component props and gives back a React element with the props + * merged. + */ + render?: Ariakit.MenuItemRadioProps[ 'render' ]; /** * The radio item's name. */ - name: string; + name: Ariakit.MenuItemRadioProps[ 'name' ]; /** * The radio item's value. */ - value: string | number; + value: Ariakit.MenuItemRadioProps[ 'value' ]; /** * The controlled checked state of the radio menu item. + * + * Note: this prop will override the `defaultChecked` prop. */ - checked?: boolean; + checked?: Ariakit.MenuItemRadioProps[ 'checked' ]; /** * The checked state of the radio menu item when it is initially rendered. * Use when not wanting to control its checked state. + * + * Note: this prop will be overriden by the `checked` prop, if it is defined. */ - defaultChecked?: boolean; + defaultChecked?: Ariakit.MenuItemRadioProps[ 'defaultChecked' ]; /** - * Event handler called when the checked radio menu item changes. + * A function that is called when the checkbox's checked state changes. */ - onChange?: ( event: React.ChangeEvent< HTMLInputElement > ) => void; + onChange?: Ariakit.MenuItemRadioProps[ 'onChange' ]; } export interface MenuSeparatorProps {}