From f334028366879f95768b1a587225cc3ae5b580bf Mon Sep 17 00:00:00 2001
From: Marco Ciampini <marco.ciampo@gmail.com>
Date: Mon, 23 Dec 2024 11:43:54 +0100
Subject: [PATCH] Generate README

---
 packages/components/src/menu/README.md        | 535 ++++++++++++------
 .../components/src/menu/docs-manifest.json    |  62 ++
 2 files changed, 422 insertions(+), 175 deletions(-)
 create mode 100644 packages/components/src/menu/docs-manifest.json

diff --git a/packages/components/src/menu/README.md b/packages/components/src/menu/README.md
index 6732610c0c6cae..575037db2b1abe 100644
--- a/packages/components/src/menu/README.md
+++ b/packages/components/src/menu/README.md
@@ -1,344 +1,529 @@
-# `Menu`
+# Menu
 
-<div class="callout callout-alert">
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-</div>
+<!-- This file is generated automatically and cannot be edited directly. Make edits via TypeScript types and TSDocs. -->
 
-`Menu` displays a menu to the user (such as a set of actions or functions). The menu is rendered in a popover (this pattern is also known as a "Dropdown menu"), which is triggered by a button.
+<p class="callout callout-info">See the <a href="https://wordpress.github.io/gutenberg/?path=/docs/components-menu--docs">WordPress Storybook</a> for more detailed, interactive documentation.</p>
 
-## Design guidelines
+## Props
 
-### Usage
+### `as`
 
-#### When to use a `Menu`
+The HTML element or React component to render the component as.
 
-Use a `Menu` when you want users to:
+ - 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
 
--   Choose an action or change a setting from a list, AND
--   Only see the available choices contextually.
+### `children`
 
-`Menu` is a React component to render an expandable menu of buttons. It is similar in purpose to a `<select>` element, with the distinction that it does not maintain a value. Instead, each option behaves as an action button.
+The elements, which should include one instance of the `Menu.TriggerButton`
+component and one instance of the `Menu.Popover` component.
 
-If you need to display all the available options at all times, consider using a Toolbar instead. Use a `Menu` to display a list of actions after the user interacts with a button.
+ - Type: `ReactNode`
+ - Required: No
 
-**Do**
-Use a `Menu` to display a list of actions after the user interacts with an icon.
+### `defaultOpen`
 
-**Don’t** use a `Menu` for important actions that should always be visible. Use a `Toolbar` instead.
+Whether the menu popover and its contents should be visible by default.
 
-**Don’t**
-Don’t use a `Menu` for frequently used actions. Use a `Toolbar` instead.
+Note: this prop will be overridden by the `open` prop if it is
+provided (meaning the component will be used in "controlled" mode).
 
-#### Behavior
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
 
-Generally, the parent button should indicate that interacting with it will show a `Menu`.
+### `open`
 
-The parent button should retain the same visual styling regardless of whether the `Menu` is displayed or not.
+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.
 
-#### Placement
+Note: this prop will set the component in "controlled" mode, and it will
+override the `defaultOpen` prop.
 
-The `Menu` should typically appear directly below, or below and to the left of, the parent button. If there isn’t enough space below to display the full `Menu`, it can be displayed instead above the parent button.
+ - Type: `boolean`
+ - Required: No
 
-## Development guidelines
+### `onOpenChange`
 
-This component is still highly experimental, and it's not normally accessible to consumers of the `@wordpress/components` package.
+A callback that gets called when the `open` state changes.
 
-The component exposes a set of components that are meant to be used in combination with each other in order to implement a `Menu` correctly.
+ - Type: `(open: boolean) => void`
+ - Required: No
 
-### `Menu`
+### `placement`
 
-The root component, used to specify the menu's trigger and its contents.
+The placement of the menu popover.
+
+ - 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`
+
+## Subcomponents
+
+### Menu.TriggerButton
 
 #### Props
 
-The component accepts the following props:
+##### `accessibleWhenDisabled`
 
-##### `trigger`: `React.ReactNode`
+Indicates whether the element should be focusable even when it is
+`disabled`.
 
-The button triggering the menu popover.
+This is important when discoverability is a concern. For example:
 
--   Required: yes
+> A toolbar in an editor contains a set of special smart paste functions
+that are disabled when the clipboard is empty or when the function is not
+applicable to the current content of the clipboard. It could be helpful to
+keep the disabled buttons focusable if the ability to discover their
+functionality is primarily via their presence on the toolbar.
 
-##### `children`: `React.ReactNode`
+Learn more on [Focusability of disabled
+controls](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#focusabilityofdisabledcontrols).
 
-The contents of the menu (ie. one or more menu items).
+ - Type: `boolean`
+ - Required: No
 
--   Required: yes
+##### `children`
 
-##### `defaultOpen`: `boolean`
+The contents of the menu trigger button.
 
-The open state of the menu popover when it is initially rendered. Use when not wanting to control its open state.
+ - Type: `ReactNode`
+ - Required: No
 
--   Required: no
--   Default: `false`
+##### `disabled`
 
-##### `open`: `boolean`
+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.
 
-The controlled open state of the menu popover. Must be used in conjunction with `onOpenChange`.
+This feature can be combined with the `accessibleWhenDisabled` prop to
+make disabled elements still accessible via keyboard.
 
--   Required: no
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
 
-##### `onOpenChange`: `(open: boolean) => void`
+##### `render`
 
-Event handler called when the open state of the menu popover changes.
+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.
 
--   Required: no
+ - Type: `ReactElement<any, string | JSXElementConstructor<any>> | RenderProp<HTMLAttributes<any> & { ref?: Ref<any>; }>`
+ - Required: No
 
-##### `modal`: `boolean`
+### Menu.Popover
 
-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.
+#### Props
 
--   Required: no
--   Default: `true`
+##### `children`
 
-##### `placement`: ``'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end'`
+The contents of the menu popover, which should include instances of the
+`Menu.Item`, `Menu.CheckboxItem`, `Menu.RadioItem`, `Menu.Group`, and
+`Menu.Separator` components.
 
-The placement of the menu popover.
+ - 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`
+
+##### `hideOnEscape`
+
+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.
 
--   Required: no
--   Default: `'bottom-start'` for root-level menus, `'right-start'` for nested menus
+ - Type: `BooleanOrCallback<KeyboardEvent | React.KeyboardEvent<Element>>`
+ - Required: No
+ - Default: ``( event ) => { event.preventDefault(); return true; }``
 
-##### `gutter`: `number`
+##### `modal`
 
-The distance in pixels from the trigger.
+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.
 
--   Required: no
--   Default: `8` for root-level menus, `16` for nested menus
+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.
 
-##### `shift`: `number`
+ - Type: `boolean`
+ - Required: No
+ - Default: `true`
 
-The skidding of the popover along the anchor element. Can be set to negative values to make the popover shift to the opposite side.
+##### `shift`
 
--   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`
+ - Type: `number`
+ - Required: No
+ - Default: `0 for root-level menus, -8 for nested menus`
 
-Used to render a menu item.
+### Menu.Item
 
 #### Props
 
-The component accepts the following props:
+##### `children`
 
-##### `children`: `React.ReactNode`
+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.
 
-The contents of the item
+ - Type: `ReactNode`
+ - Required: Yes
 
--   Required: yes
+##### `disabled`
 
-##### `prefix`: `React.ReactNode`
+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.
 
-The contents of the item's prefix.
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
 
--   Required: no
+##### `hideOnClick`
 
-##### `suffix`: `React.ReactNode`
+Determines if the menu should hide when this item is clicked.
 
-The contents of the item's suffix.
+**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.
 
--   Required: no
+ - Type: `BooleanOrCallback<MouseEvent<HTMLElement, MouseEvent>>`
+ - Required: No
+ - Default: `true`
 
-##### `hideOnClick`: `boolean`
+##### `prefix`
 
-Whether to hide the menu popover when the menu item is clicked.
+The contents of the menu item's prefix, such as an icon.
 
--   Required: no
--   Default: `true`
+ - Type: `ReactNode`
+ - Required: No
 
-##### `disabled`: `boolean`
+##### `render`
 
-Determines if the element is 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.
 
--   Required: no
--   Default: `false`
+ - Type: `ReactElement<any, string | JSXElementConstructor<any>> | RenderProp<HTMLAttributes<any> & { ref?: Ref<any>; }>`
+ - Required: No
 
-### `Menu.CheckboxItem`
+##### `suffix`
 
-Used to render a checkbox item.
+The contents of the menu item's suffix, such as a keyboard shortcut.
+
+ - Type: `ReactNode`
+ - Required: No
+
+### Menu.RadioItem
 
 #### Props
 
-The component accepts the following props:
+##### `children`
 
-##### `children`: `React.ReactNode`
+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.
 
-The contents of the item
+ - Type: `ReactNode`
+ - Required: Yes
 
--   Required: yes
+##### `checked`
 
-##### `suffix`: `React.ReactNode`
+The controlled checked state of the radio menu item.
 
-The contents of the item's suffix.
+Note: this prop will override the `defaultChecked` prop.
 
--   Required: no
+ - Type: `boolean`
+ - Required: No
 
-##### `hideOnClick`: `boolean`
+##### `disabled`
 
-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.
 
--   Required: no
--   Default: `false`
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
 
-##### `disabled`: `boolean`
+##### `defaultChecked`
 
-Determines if the element is disabled.
+The checked state of the radio menu item when it is initially rendered.
+Use when not wanting to control its checked state.
 
--   Required: no
--   Default: `false`
+Note: this prop will be overriden by the `checked` prop, if it is defined.
 
-##### `name`: `string`
+ - Type: `boolean`
+ - Required: No
 
-The checkbox item's name.
+##### `hideOnClick`
 
--   Required: yes
+Determines if the menu should hide when this item is clicked.
 
-##### `value`: `string`
+**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.
 
-The checkbox item's value, useful when using multiple checkbox items
-associated to the same `name`.
+ - Type: `BooleanOrCallback<MouseEvent<HTMLElement, MouseEvent>>`
+ - Required: No
+ - Default: `false`
 
--   Required: no
+##### `name`
 
-##### `checked`: `boolean`
+The radio item's name.
 
-The checkbox item's value, useful when using multiple checkbox items
-associated to the same `name`.
+ - Type: `string`
+ - Required: Yes
+
+##### `onChange`
 
--   Required: no
+A function that is called when the checkbox's checked state changes.
 
-##### `defaultChecked`: `boolean`
+ - Type: `BivariantCallback<(event: ChangeEvent<HTMLInputElement>) => void>`
+ - Required: No
 
-The checked state of the checkbox menu item when it is initially rendered. Use when not wanting to control its checked state.
+##### `render`
 
--   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.
 
-##### `onChange`: `( event: React.ChangeEvent< HTMLInputElement > ) => void;`
+ - Type: `ReactElement<any, string | JSXElementConstructor<any>> | RenderProp<HTMLAttributes<any> & { ref?: Ref<any>; }>`
+ - Required: No
 
-Event handler called when the checked state of the checkbox menu item changes.
+##### `suffix`
 
--   Required: no
+The contents of the menu item's suffix, such as a keyboard shortcut.
 
-### `Menu.RadioItem`
+ - Type: `ReactNode`
+ - Required: No
 
-Used to render a radio item.
+##### `value`
+
+The radio item's value.
+
+ - Type: `string | number`
+ - Required: Yes
+
+### Menu.CheckboxItem
 
 #### Props
 
-The component accepts the following props:
+##### `children`
 
-##### `children`: `React.ReactNode`
+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.
 
-The contents of the item
+ - Type: `ReactNode`
+ - Required: Yes
 
--   Required: yes
+##### `checked`
 
-##### `suffix`: `React.ReactNode`
+The controlled checked state of the checkbox menu item.
 
-The contents of the item's suffix.
+Note: this prop will override the `defaultChecked` prop.
 
--   Required: no
+ - Type: `boolean`
+ - Required: No
 
-##### `hideOnClick`: `boolean`
+##### `disabled`
 
-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.
 
--   Required: no
--   Default: `false`
+ - Type: `boolean`
+ - Required: No
+ - Default: `false`
 
-##### `disabled`: `boolean`
+##### `defaultChecked`
 
-Determines if the element is disabled.
+The checked state of the checkbox menu item when it is initially rendered.
+Use when not wanting to control its checked state.
 
--   Required: no
--   Default: `false`
+Note: this prop will be overriden by the `checked` prop, if it is defined.
 
-##### `name`: `string`
+ - Type: `boolean`
+ - Required: No
 
-The radio item's name.
+##### `hideOnClick`
 
--   Required: yes
+Determines if the menu should hide when this item is clicked.
 
-##### `value`: `string | number`
+**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.
 
-The radio item's value.
+ - Type: `BooleanOrCallback<MouseEvent<HTMLElement, MouseEvent>>`
+ - Required: No
+ - Default: `false`
 
--   Required: yes
+##### `name`
 
-##### `checked`: `boolean`
+The checkbox menu item's name.
 
-The checkbox item's value, useful when using multiple checkbox items
-associated to the same `name`.
+ - Type: `string`
+ - Required: Yes
 
--   Required: no
+##### `onChange`
 
-##### `defaultChecked`: `boolean`
+A function that is called when the checkbox's checked state changes.
 
-The checked state of the radio menu item when it is initially rendered. Use when not wanting to control its checked state.
+ - Type: `ChangeEventHandler<HTMLInputElement>`
+ - Required: No
 
--   Required: no
+##### `render`
 
-##### `onChange`: `( event: React.ChangeEvent< HTMLInputElement > ) => void;`
+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.
 
-Event handler called when the checked radio menu item changes.
+ - Type: `ReactElement<any, string | JSXElementConstructor<any>> | RenderProp<HTMLAttributes<any> & { ref?: Ref<any>; }>`
+ - Required: No
 
--   Required: no
+##### `suffix`
 
-### `Menu.ItemLabel`
+The contents of the menu item's suffix, such as a keyboard shortcut.
 
-Used to render the menu item's label.
+ - Type: `ReactNode`
+ - Required: No
 
-#### Props
+##### `value`
+
+The checkbox item's value, useful when using multiple checkbox menu items
+associated to the same `name`.
+
+ - Type: `string | number | readonly string[]`
+ - Required: No
 
-The component accepts the following props:
+### Menu.ItemLabel
 
-##### `children`: `React.ReactNode`
+#### Props
 
-The label contents.
+##### `as`
 
--   Required: yes
+The HTML element or React component to render the component as.
 
-### `Menu.ItemHelpText`
+ - Type: `"symbol" | "object" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | ...`
+ - Required: No
 
-Used to render the menu item's help text.
+### Menu.ItemHelpText
 
 #### Props
 
-The component accepts the following props:
+##### `as`
 
-##### `children`: `React.ReactNode`
+The HTML element or React component to render the component as.
 
-The help text contents.
+ - Type: `"symbol" | "object" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | ...`
+ - Required: No
 
--   Required: yes
+### Menu.Group
 
-### `Menu.Group`
+#### Props
+
+##### `children`
+
+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`.
 
-Used to group menu items.
+ - Type: `ReactNode`
+ - Required: Yes
+
+### Menu.GroupLabel
 
 #### Props
 
-The component accepts the following props:
+##### `children`
 
-##### `children`: `React.ReactNode`
+The contents of the menu group label, which should provide an accessible
+label for the menu group.
 
-The contents of the menu group (ie. an optional menu group label and one or more menu items).
+ - Type: `ReactNode`
+ - Required: Yes
 
--   Required: yes
+### Menu.Separator
 
-### `Menu.GroupLabel`
+#### Props
 
-Used to render a group label. The label text should be kept as short as possible.
+### Menu.SubmenuTriggerItem
 
 #### Props
 
-The component accepts the following props:
+##### `children`
+
+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`
+
+##### `hideOnClick`
+
+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<MouseEvent<HTMLElement, MouseEvent>>`
+ - Required: No
+ - Default: `true`
+
+##### `prefix`
+
+The contents of the menu item's prefix, such as an icon.
+
+ - Type: `ReactNode`
+ - Required: No
+
+##### `render`
 
-##### `children`: `React.ReactNode`
+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.
 
-The contents of the menu group label.
+ - Type: `ReactElement<any, string | JSXElementConstructor<any>> | RenderProp<HTMLAttributes<any> & { ref?: Ref<any>; }>`
+ - Required: No
 
--   Required: yes
+##### `suffix`
 
-### `Menu.Separator`
+The contents of the menu item's suffix, such as a keyboard shortcut.
 
-Used to render a visual separator.
+ - Type: `ReactNode`
+ - Required: No
diff --git a/packages/components/src/menu/docs-manifest.json b/packages/components/src/menu/docs-manifest.json
new file mode 100644
index 00000000000000..50e92189a39990
--- /dev/null
+++ b/packages/components/src/menu/docs-manifest.json
@@ -0,0 +1,62 @@
+{
+	"$schema": "../../schemas/docs-manifest.json",
+	"displayName": "Menu",
+	"filePath": "./index.tsx",
+	"subcomponents": [
+		{
+			"displayName": "MenuTriggerButton",
+			"preferredDisplayName": "Menu.TriggerButton",
+			"filePath": "./trigger-button.tsx"
+		},
+		{
+			"displayName": "MenuPopover",
+			"preferredDisplayName": "Menu.Popover",
+			"filePath": "./popover.tsx"
+		},
+		{
+			"displayName": "MenuItem",
+			"preferredDisplayName": "Menu.Item",
+			"filePath": "./item.tsx"
+		},
+		{
+			"displayName": "MenuRadioItem",
+			"preferredDisplayName": "Menu.RadioItem",
+			"filePath": "./radio-item.tsx"
+		},
+		{
+			"displayName": "MenuCheckboxItem",
+			"preferredDisplayName": "Menu.CheckboxItem",
+			"filePath": "./checkbox-item.tsx"
+		},
+		{
+			"displayName": "MenuItemLabel",
+			"preferredDisplayName": "Menu.ItemLabel",
+			"filePath": "./item-label.tsx"
+		},
+		{
+			"displayName": "MenuItemHelpText",
+			"preferredDisplayName": "Menu.ItemHelpText",
+			"filePath": "./item-help-text.tsx"
+		},
+		{
+			"displayName": "MenuGroup",
+			"preferredDisplayName": "Menu.Group",
+			"filePath": "./group.tsx"
+		},
+		{
+			"displayName": "MenuGroupLabel",
+			"preferredDisplayName": "Menu.GroupLabel",
+			"filePath": "./group-label.tsx"
+		},
+		{
+			"displayName": "MenuSeparator",
+			"preferredDisplayName": "Menu.Separator",
+			"filePath": "./separator.tsx"
+		},
+		{
+			"displayName": "MenuSubmenuTriggerItem",
+			"preferredDisplayName": "Menu.SubmenuTriggerItem",
+			"filePath": "./submenu-trigger-item.tsx"
+		}
+	]
+}