@wordpress/components 23.9.0 → 25.0.0

package/src/dropdown-menu/types.ts

@@ -0,0 +1,143 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+/**
+ * Internal dependencies
+ */
+import type { ButtonAsButtonProps } from '../button/types';
+import type { WordPressComponentProps } from '../ui/context';
+import type { DropdownProps } from '../dropdown/types';
+import type { Props as IconProps } from '../icon';
+import type { NavigableMenuProps } from '../navigable-container/types';
+
+export type DropdownOption = {
+	/**
+	 * The Dashicon icon slug to be shown for the option.
+	 */
+	icon?: IconProps[ 'icon' ];
+	/**
+	 * A human-readable title to display for the option.
+	 */
+	title: string;
+	/**
+	 * Whether or not the option is disabled.
+	 *
+	 * @default false
+	 */
+	isDisabled?: boolean;
+	/**
+	 * A callback function to invoke when the option is selected.
+	 */
+	onClick?: () => void;
+	/**
+	 * Whether or not the control is currently active.
+	 */
+	isActive?: boolean;
+	/**
+	 * Text to use for the internal `Button` component's tooltip.
+	 */
+	label?: string;
+	/**
+	 * The role to apply to the option's HTML element
+	 */
+	role?: HTMLElement[ 'role' ];
+};
+
+type DropdownCallbackProps = {
+	isOpen: boolean;
+	onToggle: () => void;
+	onClose: () => void;
+};
+
+// Manually including `as` prop because `WordPressComponentProps` polymorhpism
+// creates a union that is too large for TypeScript to handle.
+type ToggleProps = Partial<
+	Omit<
+		WordPressComponentProps< ButtonAsButtonProps, 'button', false >,
+		'label' | 'text'
+	>
+> & {
+	as?: React.ElementType | keyof JSX.IntrinsicElements;
+};
+
+export type DropdownMenuProps = {
+	/**
+	 * The Dashicon icon slug to be shown in the collapsed menu button.
+	 *
+	 * @default "menu"
+	 */
+	icon?: IconProps[ 'icon' ] | null;
+	/**
+	 * A human-readable label to present as accessibility text on the focused
+	 * collapsed menu button.
+	 */
+	label: string;
+	/**
+	 * A class name to apply to the dropdown menu's toggle element wrapper.
+	 */
+	className?: string;
+	/**
+	 * Properties of `popoverProps` object will be passed as props to the nested
+	 * `Popover` component.
+	 * Use this object to modify props available for the `Popover` component that
+	 * are not already exposed in the `DropdownMenu` component, e.g.: the
+	 * direction in which the popover should open relative to its parent node
+	 * set with `position` prop.
+	 */
+	popoverProps?: DropdownProps[ 'popoverProps' ];
+	/**
+	 * Properties of `toggleProps` object will be passed as props to the nested
+	 * `Button` component in the `renderToggle` implementation of the `Dropdown`
+	 * component used internally.
+	 * Use this object to modify props available for the `Button` component that
+	 * are not already exposed in the `DropdownMenu` component, e.g.: the tooltip
+	 * text displayed on hover set with `tooltip` prop.
+	 */
+	toggleProps?: ToggleProps;
+	/**
+	 * Properties of `menuProps` object will be passed as props to the nested
+	 * `NavigableMenu` component in the `renderContent` implementation of the
+	 * `Dropdown` component used internally.
+	 * Use this object to modify props available for the `NavigableMenu`
+	 * component that are not already exposed in the `DropdownMenu` component,
+	 * e.g.: the orientation of the menu set with `orientation` prop.
+	 */
+	menuProps?: Omit< Partial< NavigableMenuProps >, 'children' >;
+	/**
+	 * In some contexts, the arrow down key used to open the dropdown menu might
+	 * need to be disabled—for example when that key is used to perform another
+	 * action.
+	 *
+	 * @default false
+	 */
+	disableOpenOnArrowDown?: boolean;
+	/**
+	 * Text to display on the nested `Button` component in the `renderToggle`
+	 * implementation of the `Dropdown` component used internally.
+	 */
+	text?: string;
+	/**
+	 * Whether or not `no-icons` should be added to the menu's `className`.
+	 */
+	noIcons?: boolean;
+	/**
+	 * A [function render prop](https://reactjs.org/docs/render-props.html#using-props-other-than-render)
+	 * which should return an element or elements valid for use in a DropdownMenu:
+	 * `MenuItem`, `MenuItemsChoice`, or `MenuGroup`. Its first argument is a
+	 * props object including the same values as given to a `Dropdown`'s
+	 * `renderContent` (`isOpen`, `onToggle`, `onClose`).
+	 *
+	 * A valid DropdownMenu must specify a `controls` or `children` prop, or both.
+	 */
+	children?: ( callbackProps: DropdownCallbackProps ) => ReactNode;
+	/**
+	 * An array or nested array of objects describing the options to be shown in
+	 * the expanded menu. Each object should include an `icon` Dashicon slug
+	 * string, a human-readable `title` string, `isDisabled` boolean flag, and
+	 * an `onClick` function callback to invoke when the option is selected.
+	 *
+	 * A valid DropdownMenu must specify a `controls` or `children` prop, or both.
+	 */
+	controls?: DropdownOption[] | DropdownOption[][];
+};

package/src/dropdown-menu-v2/README.md

@@ -0,0 +1,392 @@
+# `DropdownMenu` (v2)
+
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
+`DropdownMenu` displays a menu to the user (such as a set of actions or functions) triggered by a button.
+
+
+## Design guidelines
+
+### Usage
+
+#### When to use a DropdownMenu
+
+Use a DropdownMenu when you want users to:
+
+-   Choose an action or change a setting from a list, AND
+-   Only see the available choices contextually.
+
+`DropdownMenu` 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.
+
+If you need to display all the available options at all times, consider using a Toolbar instead. Use a `DropdownMenu` to display a list of actions after the user interacts with a button.
+
+**Do**
+Use a `DropdownMenu` to display a list of actions after the user interacts with an icon.
+
+**Don’t** use a `DropdownMenu` for important actions that should always be visible. Use a `Toolbar` instead.
+
+**Don’t**
+Don’t use a `DropdownMenu` for frequently used actions. Use a `Toolbar` instead.
+
+#### Behavior
+
+Generally, the parent button should indicate that interacting with it will show a `DropdownMenu`.
+
+The parent button should retain the same visual styling regardless of whether the `DropdownMenu` is displayed or not.
+
+#### Placement
+
+The `DropdownMenu` 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 `DropdownMenu`, it can be displayed instead above the parent button.
+
+## Development guidelines
+
+This component is still highly experimental, and it's not normally accessible to consumers of the `@wordpress/components` package.
+
+The component exposes a set of components that are meant to be used in combination with each other in order to implement a `DropdownMenu` correctly.
+
+### `DropdownMenu`
+
+The root component, used to specify the menu's trigger and its contents.
+
+#### Props
+
+The component accepts the following props:
+
+##### `trigger`: `React.ReactNode`
+
+The trigger button
+
+- Required: yes
+
+##### `children`: `React.ReactNode`
+
+The contents of the dropdown
+
+- Required: yes
+
+##### `defaultOpen`: `boolean`
+
+The open state of the dropdown menu when it is initially rendered. Use when you do not need to control its open state.
+
+- Required: no
+
+##### `open`: `boolean`
+
+The controlled open state of the dropdown menu. Must be used in conjunction with `onOpenChange`
+
+- Required: no
+
+##### `onOpenChange`: `(open: boolean) => void`
+
+Event handler called when the open state of the dropdown menu changes.
+
+- Required: no
+
+##### `modal`: `boolean`
+
+The modality of the dropdown menu. When set to true, interaction with outside elements will be disabled and only menu content will be visible to screen readers.
+
+- Required: no
+- Default: `true`
+
+##### `side`: `"bottom" | "left" | "right" | "top"`
+
+The preferred side of the trigger to render against when open. Will be reversed when collisions occur and avoidCollisions is enabled.
+
+- Required: no
+- Default: `"bottom"`
+
+##### `sideOffset`: `number`
+
+The distance in pixels from the trigger.
+
+- Required: no
+- Default: `0`
+
+##### `align`: `"end" | "start" | "center"`
+
+The preferred alignment against the trigger. May change when collisions occur.
+
+- Required: no
+- Default: `"center"`
+
+##### `alignOffset`: `number`
+
+An offset in pixels from the "start" or "end" alignment options.
+
+- Required: no
+- Default: `0`
+
+### `DropdownMenuItem`
+
+Used to render a menu item.
+
+#### Props
+
+The component accepts the following props:
+
+##### `children`: `React.ReactNode`
+
+The contents of the item
+
+- Required: yes
+
+##### `disabled`: `boolean`
+
+- Required: no
+- Default: `false`
+
+##### `onSelect`: `(event: Event) => void`
+
+Event handler called when the user selects an item (via mouse or keyboard). Calling `event.preventDefault` in this handler will prevent the dropdown menu from closing when selecting that item.
+
+- Required: no
+
+##### `textValue`: `string`
+
+Optional text used for typeahead purposes. By default the typeahead behavior will use the `.textContent` of the item. Use this when the content is complex, or you have non-textual content inside.
+
+- Required: no
+
+##### `prefix`: `React.ReactNode`
+
+The contents of the item's prefix.
+
+- Required: no
+
+##### `suffix`: `React.ReactNode`
+
+The contents of the item's suffix.
+
+- Required: no
+
+### `DropdownSubMenu`
+
+Used to render a nested submenu.
+
+#### Props
+
+The component accepts the following props:
+##### `trigger`: `React.ReactNode`
+
+The contents rendered inside the trigger. The trigger should be an instance of the `DropdownSubMenuTrigger` component.
+
+- Required: yes
+
+##### `children`: `React.ReactNode`
+
+The contents of the dropdown
+
+- Required: yes
+
+##### `defaultOpen`: `boolean`
+
+The open state of the dropdown menu when it is initially rendered. Use when you do not need to control its open state.
+
+- Required: no
+
+##### `open`: `boolean`
+
+The controlled open state of the dropdown menu. Must be used in conjunction with `onOpenChange`
+
+- Required: no
+
+##### `onOpenChange`: `(open: boolean) => void`
+
+Event handler called when the open state of the dropdown menu changes.
+
+- Required: no
+
+##### `disabled`: `boolean`
+
+When `true`, prevents the user from interacting with the item.
+
+- Required: no
+
+##### `textValue`: `string`
+
+Optional text used for typeahead purposes for the trigger. By default the typeahead behavior will use the `.textContent` of the trigger. Use this when the content is complex, or you have non-textual content inside.
+
+- Required: no
+
+### `DropdownSubMenuTrigger`
+
+Used to render a submenu trigger.
+
+#### Props
+
+The component accepts the following props:
+
+##### `children`: `React.ReactNode`
+
+The contents of the item
+
+- Required: yes
+
+##### `prefix`: `React.ReactNode`
+
+The contents of the item's prefix.
+
+- Required: no
+
+##### `suffix`: `React.ReactNode`
+
+The contents of the item's suffix.
+
+- Default: a chevron icon
+- Required: The standard chevron icon for a submenu trigger
+
+### `DropdownMenuCheckboxItem`
+
+Used to render a checkbox item.
+
+#### Props
+
+The component accepts the following props:
+
+##### `children`: `React.ReactNode`
+
+The contents of the checkbox item
+
+- Required: yes
+
+##### `checked`: `boolean`
+
+The controlled checked state of the item. Must be used in conjunction with `onCheckedChange`.
+
+- Required: no
+- Default: `false`
+
+##### `onCheckedChange`: `(checked: boolean) => void)`
+
+Event handler called when the checked state changes.
+
+- Required: no
+
+##### `disabled`: `boolean`
+
+When `true`, prevents the user from interacting with the item.
+
+- Required: no
+
+##### `onSelect`: `(event: Event) => void`
+
+Event handler called when the user selects an item (via mouse or keyboard). Calling `event.preventDefault` in this handler will prevent the dropdown menu from closing when selecting that item.
+
+- Required: no
+
+##### `textValue`: `string`
+
+Optional text used for typeahead purposes. By default the typeahead behavior will use the `.textContent` of the item. Use this when the content is complex, or you have non-textual content inside.
+
+- Required: no
+
+##### `suffix`: `React.ReactNode`
+
+The contents of the checkbox item's suffix.
+
+- Required: no
+
+### `DropdownMenuRadioGroup`
+
+Used to render a radio group.
+
+#### Props
+
+The component accepts the following props:
+
+##### `children`: `React.ReactNode`
+
+The contents of the radio group
+
+- Required: yes
+
+##### `value`: `string`
+
+The value of the selected item in the group.
+
+- Required: no
+
+##### `onValueChange`: `(value: string) => void`
+
+Event handler called when the value changes.
+
+- Required: no
+
+### `DropdownMenuRadioItem`
+
+Used to render a radio item.
+
+#### Props
+
+The component accepts the following props:
+
+##### `children`: `React.ReactNode`
+
+The contents of the item.
+
+- Required: yes
+
+##### `value`: `string`
+
+The unique value of the item.
+
+- Required: yes
+
+##### `disabled`: `boolean`
+
+When `true`, prevents the user from interacting with the item.
+
+- Required: no
+
+##### `onSelect`: `(event: Event) => void`
+
+Event handler called when the user selects an item (via mouse or keyboard). Calling `event.preventDefault` in this handler will prevent the dropdown menu from closing when selecting that item.
+
+- Required: no
+
+##### `textValue`: `string`
+
+Optional text used for typeahead purposes. By default the typeahead behavior will use the `.textContent` of the item. Use this when the content is complex, or you have non-textual content inside.
+
+- Required: no
+
+##### `suffix`: `React.ReactNode
+
+The contents of the radio item's suffix.
+
+- Required: no
+
+### `DropdownMenuLabel`
+
+Used to render a group label.
+
+#### Props
+
+The component accepts the following props:
+
+##### `children`: `React.ReactNode`
+
+The contents of the group.
+
+- Required: yes
+
+### `DropdownMenuGroup`
+
+Used to group menu items.
+
+#### Props
+
+The component accepts the following props:
+
+##### `children`: `React.ReactNode`
+
+The contents of the group.
+
+- Required: yes
+
+### `DropdownMenuSeparatorProps`
+
+Used to render a visual separator.