diff --git a/packages/components/src/menu/README.md b/packages/components/src/menu/README.md index b34e21696459d5..12f120b871f85d 100644 --- a/packages/components/src/menu/README.md +++ b/packages/components/src/menu/README.md @@ -2,6 +2,8 @@ +🔒 This component is locked as a [private API](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-private-apis/). We do not yet recommend using this outside of the Gutenberg project. +

See the WordPress Storybook for more detailed, interactive documentation.

Menu is a collection of React components that combine to render @@ -17,31 +19,34 @@ component, and the `Menu.Popover` component. ### `as` -The HTML element or React component to render the component as. - - Type: `"symbol" | "object" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | "canvas" | ... 516 more ... | ("view" & FunctionComponent<...>)` - Required: No -### `children` +The HTML element or React component to render the component as. -The elements, which should include one instance of the `Menu.TriggerButton` -component and one instance of the `Menu.Popover` component. +### `children` - Type: `ReactNode` - Required: No +The elements, which should include one instance of the `Menu.TriggerButton` +component and one instance of the `Menu.Popover` component. + ### `defaultOpen` + - Type: `boolean` + - Required: No + - Default: `false` + 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). +### `open` + - Type: `boolean` - Required: No - - Default: `false` - -### `open` Whether the menu popover and its contents should be visible. Should be used in conjunction with `onOpenChange` in order to control @@ -50,24 +55,21 @@ the open state of the menu popover. Note: this prop will set the component in "controlled" mode, and it will override the `defaultOpen` prop. - - Type: `boolean` - - Required: No - ### `onOpenChange` -A callback that gets called when the `open` state changes. - - Type: `(open: boolean) => void` - Required: No -### `placement` +A callback that gets called when the `open` state changes. -The placement of the menu popover. +### `placement` - Type: `"top" | "bottom" | "left" | "right" | "top-start" | "bottom-start" | "left-start" | "right-start" | "top-end" | "bottom-end" | ...` - Required: No - Default: `'bottom-start' for root-level menus, 'right-start' for submenus` +The placement of the menu popover. + ## Subcomponents ### Menu.TriggerButton @@ -79,6 +81,9 @@ Renders a menu button that toggles the visibility of a sibling ##### `accessibleWhenDisabled` + - Type: `boolean` + - Required: No + Indicates whether the element should be focusable even when it is `disabled`. @@ -93,18 +98,19 @@ functionality is primarily via their presence on the toolbar. Learn more on [Focusability of disabled controls](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#focusabilityofdisabledcontrols). - - Type: `boolean` - - Required: No - ##### `children` -The contents of the menu trigger button. - - Type: `ReactNode` - Required: No +The contents of the menu trigger button. + ##### `disabled` + - Type: `boolean` + - Required: No + - Default: `false` + 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. @@ -112,20 +118,16 @@ that don't support the native `disabled` attribute. This feature can be combined with the `accessibleWhenDisabled` prop to make disabled elements still accessible via keyboard. - - Type: `boolean` - - Required: No - - Default: `false` - ##### `render` + - Type: `ReactElement> | RenderProp & { ref?: Ref; }>` + - Required: No + 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. - - Type: `ReactElement> | RenderProp & { ref?: Ref; }>` - - Required: No - ### Menu.Popover Renders a dropdown menu element that's controlled by a sibling @@ -140,23 +142,27 @@ and `Menu` (for nested dropdown menus). ##### `children` + - Type: `ReactNode` + - Required: No + The contents of the menu popover, which should include instances of the `Menu.Item`, `Menu.CheckboxItem`, `Menu.RadioItem`, `Menu.Group`, and `Menu.Separator` components. - - Type: `ReactNode` - - Required: No - ##### `gutter` -The distance between the popover and the anchor element. - - Type: `number` - Required: No - Default: `8 for root-level menus, 16 for nested menus` +The distance between the popover and the anchor element. + ##### `hideOnEscape` + - Type: `BooleanOrCallback>` + - Required: No + - Default: ``( event ) => { event.preventDefault(); return true; }`` + Determines if the menu popover will hide when the user presses the Escape key. @@ -165,12 +171,12 @@ 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. - - Type: `BooleanOrCallback>` - - Required: No - - Default: ``( event ) => { event.preventDefault(); return true; }`` - ##### `modal` + - Type: `boolean` + - Required: No + - Default: `true` + 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. @@ -181,19 +187,15 @@ states and behaviors: still be manually set to `false`. - When the dialog is open, element tree outside it will be inert. - - Type: `boolean` - - Required: No - - Default: `true` - ##### `shift` -The skidding of the popover along the anchor element. Can be set to -negative values to make the popover shift to the opposite side. - - Type: `number` - Required: No - Default: `0 for root-level menus, -8 for nested menus` +The skidding of the popover along the anchor element. Can be set to +negative values to make the popover shift to the opposite side. + ### Menu.Item Renders a menu item inside the `Menu.Popover` or `Menu.Group` components. @@ -205,59 +207,59 @@ and one instance of the `Menu.ItemHelpText` component. ##### `children` + - Type: `ReactNode` + - Required: Yes + 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. - - Type: `ReactNode` - - Required: Yes - ##### `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. - - Type: `boolean` - Required: No - Default: `false` +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. + ##### `hideOnClick` + - Type: `BooleanOrCallback>` + - Required: No + - Default: `true` + 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. - - Type: `BooleanOrCallback>` - - Required: No - - Default: `true` - ##### `prefix` -The contents of the menu item's prefix, such as an icon. - - Type: `ReactNode` - Required: No +The contents of the menu item's prefix, such as an icon. + ##### `render` + - Type: `ReactElement> | RenderProp & { ref?: Ref; }>` + - Required: No + 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. - - Type: `ReactElement> | RenderProp & { ref?: Ref; }>` - - Required: No - ##### `suffix` -The contents of the menu item's suffix, such as a keyboard shortcut. - - Type: `ReactNode` - Required: No +The contents of the menu item's suffix, such as a keyboard shortcut. + ### Menu.RadioItem Renders a radio menu item inside the `Menu.Popover` or `Menu.Group` @@ -270,92 +272,92 @@ and one instance of the `Menu.ItemHelpText` component. ##### `children` + - Type: `ReactNode` + - Required: Yes + 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. - - Type: `ReactNode` - - Required: Yes - ##### `checked` + - Type: `boolean` + - Required: No + The controlled checked state of the radio menu item. Note: this prop will override the `defaultChecked` prop. +##### `disabled` + - Type: `boolean` - Required: No - -##### `disabled` + - Default: `false` 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. +##### `defaultChecked` + - Type: `boolean` - Required: No - - Default: `false` - -##### `defaultChecked` 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. - - Type: `boolean` - - Required: No - ##### `hideOnClick` + - Type: `BooleanOrCallback>` + - Required: No + - Default: `false` + 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. - - Type: `BooleanOrCallback>` - - Required: No - - Default: `false` - ##### `name` -The radio item's name. - - Type: `string` - Required: Yes -##### `onChange` +The radio item's name. -A function that is called when the checkbox's checked state changes. +##### `onChange` - Type: `BivariantCallback<(event: ChangeEvent) => void>` - Required: No +A function that is called when the checkbox's checked state changes. + ##### `render` + - Type: `ReactElement> | RenderProp & { ref?: Ref; }>` + - Required: No + 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. - - Type: `ReactElement> | RenderProp & { ref?: Ref; }>` - - Required: No - ##### `suffix` -The contents of the menu item's suffix, such as a keyboard shortcut. - - Type: `ReactNode` - Required: No -##### `value` +The contents of the menu item's suffix, such as a keyboard shortcut. -The radio item's value. +##### `value` - Type: `string | number` - Required: Yes +The radio item's value. + ### Menu.CheckboxItem Renders a checkbox menu item inside the `Menu.Popover` or `Menu.Group` @@ -368,93 +370,93 @@ and one instance of the `Menu.ItemHelpText` component. ##### `children` + - Type: `ReactNode` + - Required: Yes + 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. - - Type: `ReactNode` - - Required: Yes - ##### `checked` + - Type: `boolean` + - Required: No + The controlled checked state of the checkbox menu item. Note: this prop will override the `defaultChecked` prop. +##### `disabled` + - Type: `boolean` - Required: No - -##### `disabled` + - Default: `false` 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. +##### `defaultChecked` + - Type: `boolean` - Required: No - - Default: `false` - -##### `defaultChecked` 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. - - Type: `boolean` - - Required: No - ##### `hideOnClick` + - Type: `BooleanOrCallback>` + - Required: No + - Default: `false` + 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. - - Type: `BooleanOrCallback>` - - Required: No - - Default: `false` - ##### `name` -The checkbox menu item's name. - - Type: `string` - Required: Yes -##### `onChange` +The checkbox menu item's name. -A function that is called when the checkbox's checked state changes. +##### `onChange` - Type: `ChangeEventHandler` - Required: No +A function that is called when the checkbox's checked state changes. + ##### `render` + - Type: `ReactElement> | RenderProp & { ref?: Ref; }>` + - Required: No + 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. - - Type: `ReactElement> | RenderProp & { ref?: Ref; }>` - - Required: No - ##### `suffix` -The contents of the menu item's suffix, such as a keyboard shortcut. - - Type: `ReactNode` - Required: No -##### `value` +The contents of the menu item's suffix, such as a keyboard shortcut. -The checkbox item's value, useful when using multiple checkbox menu items -associated to the same `name`. +##### `value` - Type: `string | number | readonly string[]` - Required: No +The checkbox item's value, useful when using multiple checkbox menu items +associated to the same `name`. + ### Menu.ItemLabel Renders a menu item's label text. It should be wrapped with `Menu.Item`, @@ -464,11 +466,11 @@ Renders a menu item's label text. It should be wrapped with `Menu.Item`, ##### `as` -The HTML element or React component to render the component as. - - Type: `"symbol" | "object" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | ...` - Required: No +The HTML element or React component to render the component as. + ### Menu.ItemHelpText Renders a menu item's help text. It should be wrapped with `Menu.Item`, @@ -478,11 +480,11 @@ Renders a menu item's help text. It should be wrapped with `Menu.Item`, ##### `as` -The HTML element or React component to render the component as. - - Type: `"symbol" | "object" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | ...` - Required: No +The HTML element or React component to render the component as. + ### Menu.Group Renders a group for menu items. @@ -494,13 +496,13 @@ instances of `Menu.Item`, `Menu.RadioItem`, or `Menu.CheckboxItem`. ##### `children` + - Type: `ReactNode` + - Required: Yes + 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`. - - Type: `ReactNode` - - Required: Yes - ### Menu.GroupLabel Renders a label in a menu group. @@ -512,12 +514,12 @@ This component should be wrapped with `Menu.Group` so the ##### `children` -The contents of the menu group label, which should provide an accessible -label for the menu group. - - Type: `ReactNode` - Required: Yes +The contents of the menu group label, which should provide an accessible +label for the menu group. + ### Menu.Separator Renders a divider between menu items or menu groups. @@ -535,55 +537,55 @@ This component is used to create a nested dropdown menu. ##### `children` + - Type: `ReactNode` + - Required: Yes + 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. - - Type: `ReactNode` - - Required: Yes - ##### `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. - - Type: `boolean` - Required: No - Default: `false` +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. + ##### `hideOnClick` + - Type: `BooleanOrCallback>` + - Required: No + - Default: `true` + 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. - - Type: `BooleanOrCallback>` - - Required: No - - Default: `true` - ##### `prefix` -The contents of the menu item's prefix, such as an icon. - - Type: `ReactNode` - Required: No +The contents of the menu item's prefix, such as an icon. + ##### `render` + - Type: `ReactElement> | RenderProp & { ref?: Ref; }>` + - Required: No + 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. - - Type: `ReactElement> | RenderProp & { ref?: Ref; }>` - - Required: No - ##### `suffix` -The contents of the menu item's suffix, such as a keyboard shortcut. - - Type: `ReactNode` - Required: No + +The contents of the menu item's suffix, such as a keyboard shortcut.