@wordpress/components 25.9.1 → 25.11.0

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

@@ -0,0 +1,324 @@
+# `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 not wanting to control its open state.
+
+- Required: no
+- Default: `false`
+
+##### `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`
+
+##### `placement`: ``'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end'`
+
+The placement of the dropdown menu popover.
+
+- Required: no
+- Default: `'bottom-start'` for root-level menus, `'right-start'` for nested menus
+
+##### `gutter`: `number`
+
+The distance in pixels from the trigger.
+
+- Required: no
+- Default: `8` for root-level menus, `16` for nested menus
+
+##### `shift`: `number`
+
+The skidding of the popover along the anchor element. Can be set to negative values to make the popover shift to the opposite side.
+
+- Required: no
+- Default: `0` for root-level menus, `-8` for nested menus
+
+##### `hideOnEscape`: `boolean | ( ( event: KeyboardEvent | React.KeyboardEvent< Element > ) => boolean )`
+
+Determines whether the menu popover will be hidden when the user presses the Escape key.
+
+- Required: no
+- Default: `true`
+
+### `DropdownMenuItem`
+
+Used to render a menu item.
+
+#### 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.
+
+- Required: no
+
+##### `hideOnClick`: `boolean`
+
+Whether to hide the dropdown menu when the menu item is clicked.
+
+- Required: no
+- Default: `true`
+
+##### `disabled`: `boolean`
+
+Determines if the element is disabled.
+
+- Required: no
+- Default: `false`
+
+### `DropdownMenuCheckboxItem`
+
+Used to render a checkbox item.
+
+#### Props
+
+The component accepts the following props:
+
+##### `children`: `React.ReactNode`
+
+The contents of the item
+
+- Required: yes
+
+##### `suffix`: `React.ReactNode`
+
+The contents of the item's suffix.
+
+- Required: no
+
+##### `hideOnClick`: `boolean`
+
+Whether to hide the dropdown menu when the menu item is clicked.
+
+- Required: no
+- Default: `false`
+
+##### `disabled`: `boolean`
+
+Determines if the element is disabled.
+
+- Required: no
+- Default: `false`
+
+##### `name`: `string`
+
+The checkbox item's name.
+
+- Required: yes
+
+##### `value`: `string`
+
+The checkbox item's value, useful when using multiple checkbox items
+ associated to the same `name`.
+
+- Required: no
+
+##### `checked`: `boolean`
+
+The checkbox item's value, useful when using multiple checkbox items
+ associated to the same `name`.
+
+- Required: no
+
+##### `defaultChecked`: `boolean`
+
+The checked state of the checkbox menu item when it is initially rendered. Use when not wanting to control its checked state.
+
+- Required: no
+
+##### `onChange`: `( event: React.ChangeEvent< HTMLInputElement > ) => void;`
+
+Event handler called when the checked state of the checkbox menu item 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
+
+##### `suffix`: `React.ReactNode`
+
+The contents of the item's suffix.
+
+- Required: no
+
+##### `hideOnClick`: `boolean`
+
+Whether to hide the dropdown menu when the menu item is clicked.
+
+- Required: no
+- Default: `false`
+
+##### `disabled`: `boolean`
+
+Determines if the element is disabled.
+
+- Required: no
+- Default: `false`
+
+##### `name`: `string`
+
+The radio item's name.
+
+- Required: yes
+
+##### `value`: `string | number`
+
+The radio item's value.
+
+- Required: yes
+
+##### `checked`: `boolean`
+
+The checkbox item's value, useful when using multiple checkbox items
+ associated to the same `name`.
+
+- Required: no
+
+##### `defaultChecked`: `boolean`
+
+The checked state of the radio menu item when it is initially rendered. Use when not wanting to control its checked state.
+
+- Required: no
+
+##### `onChange`: `( event: React.ChangeEvent< HTMLInputElement > ) => void;`
+
+Event handler called when the checked radio menu item changes.
+
+- Required: no
+
+### `DropdownMenuGroup`
+
+Used to group menu items.
+
+#### Props
+
+The component accepts the following props:
+
+##### `children`: `React.ReactNode`
+
+The contents of the group.
+
+- Required: yes
+
+### `DropdownMenuGroupLabel`
+
+Used to render a group label.
+
+#### Props
+
+The component accepts the following props:
+
+##### `children`: `React.ReactNode`
+
+The contents of the group.
+
+- Required: yes
+
+### `DropdownMenuSeparatorProps`
+
+Used to render a visual separator.

package/src/dropdown-menu-v2-ariakit/index.tsx

@@ -0,0 +1,318 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import * as Ariakit from '@ariakit/react';
+
+/**
+ * WordPress dependencies
+ */
+import {
+	forwardRef,
+	createContext,
+	useContext,
+	useMemo,
+	cloneElement,
+	isValidElement,
+} from '@wordpress/element';
+import { isRTL } from '@wordpress/i18n';
+import { check, chevronRightSmall } from '@wordpress/icons';
+import { SVG, Circle } from '@wordpress/primitives';
+
+/**
+ * Internal dependencies
+ */
+import { useContextSystem, contextConnect } from '../context';
+import type { WordPressComponentProps } from '../context';
+import Icon from '../icon';
+import type {
+	DropdownMenuContext as DropdownMenuContextType,
+	DropdownMenuProps,
+	DropdownMenuGroupProps,
+	DropdownMenuGroupLabelProps,
+	DropdownMenuItemProps,
+	DropdownMenuCheckboxItemProps,
+	DropdownMenuRadioItemProps,
+	DropdownMenuSeparatorProps,
+} from './types';
+import * as Styled from './styles';
+
+export const DropdownMenuContext = createContext<
+	DropdownMenuContextType | undefined
+>( undefined );
+
+export const DropdownMenuItem = forwardRef<
+	HTMLDivElement,
+	WordPressComponentProps< DropdownMenuItemProps, 'div', false >
+>( function DropdownMenuItem(
+	{ prefix, suffix, children, hideOnClick = true, ...props },
+	ref
+) {
+	const dropdownMenuContext = useContext( DropdownMenuContext );
+
+	return (
+		<Styled.DropdownMenuItem
+			ref={ ref }
+			{ ...props }
+			hideOnClick={ hideOnClick }
+			store={ dropdownMenuContext?.store }
+		>
+			{ prefix && (
+				<Styled.ItemPrefixWrapper>{ prefix }</Styled.ItemPrefixWrapper>
+			) }
+			{ children }
+			{ suffix && (
+				<Styled.ItemSuffixWrapper>{ suffix }</Styled.ItemSuffixWrapper>
+			) }
+		</Styled.DropdownMenuItem>
+	);
+} );
+
+export const DropdownMenuCheckboxItem = forwardRef<
+	HTMLDivElement,
+	WordPressComponentProps< DropdownMenuCheckboxItemProps, 'div', false >
+>( function DropdownMenuCheckboxItem(
+	{ suffix, children, hideOnClick = false, ...props },
+	ref
+) {
+	const dropdownMenuContext = useContext( DropdownMenuContext );
+
+	return (
+		<Styled.DropdownMenuCheckboxItem
+			ref={ ref }
+			{ ...props }
+			hideOnClick={ hideOnClick }
+			store={ dropdownMenuContext?.store }
+		>
+			<Ariakit.MenuItemCheck
+				store={ dropdownMenuContext?.store }
+				render={ <Styled.ItemPrefixWrapper /> }
+			>
+				<Icon icon={ check } size={ 24 } />
+			</Ariakit.MenuItemCheck>
+
+			{ children }
+			{ suffix && (
+				<Styled.ItemSuffixWrapper>{ suffix }</Styled.ItemSuffixWrapper>
+			) }
+		</Styled.DropdownMenuCheckboxItem>
+	);
+} );
+
+export const DropdownMenuRadioItem = forwardRef<
+	HTMLDivElement,
+	WordPressComponentProps< DropdownMenuRadioItemProps, 'div', false >
+>( function DropdownMenuRadioItem(
+	{ suffix, children, hideOnClick = false, ...props },
+	ref
+) {
+	const dropdownMenuContext = useContext( DropdownMenuContext );
+
+	return (
+		<Styled.DropdownMenuRadioItem
+			ref={ ref }
+			{ ...props }
+			hideOnClick={ hideOnClick }
+			store={ dropdownMenuContext?.store }
+		>
+			<Ariakit.MenuItemCheck
+				store={ dropdownMenuContext?.store }
+				render={ <Styled.ItemPrefixWrapper /> }
+			>
+				<SVG viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+					<Circle
+						cx={ 12 }
+						cy={ 12 }
+						r={ 3 }
+						fill="currentColor"
+					></Circle>
+				</SVG>
+			</Ariakit.MenuItemCheck>
+			{ children }
+			{ suffix }
+		</Styled.DropdownMenuRadioItem>
+	);
+} );
+
+export const DropdownMenuGroup = forwardRef<
+	HTMLDivElement,
+	WordPressComponentProps< DropdownMenuGroupProps, 'div', false >
+>( function DropdownMenuGroup( props, ref ) {
+	const dropdownMenuContext = useContext( DropdownMenuContext );
+	return (
+		<Styled.DropdownMenuGroup
+			ref={ ref }
+			{ ...props }
+			store={ dropdownMenuContext?.store }
+		/>
+	);
+} );
+
+export const DropdownMenuGroupLabel = forwardRef<
+	HTMLDivElement,
+	WordPressComponentProps< DropdownMenuGroupLabelProps, 'div', false >
+>( function DropdownMenuGroupLabel( props, ref ) {
+	const dropdownMenuContext = useContext( DropdownMenuContext );
+	return (
+		<Styled.DropdownMenuGroupLabel
+			ref={ ref }
+			{ ...props }
+			store={ dropdownMenuContext?.store }
+		/>
+	);
+} );
+
+const UnconnectedDropdownMenu = (
+	props: WordPressComponentProps< DropdownMenuProps, 'div', false >,
+	ref: React.ForwardedRef< HTMLDivElement >
+) => {
+	const {
+		// Store props
+		open,
+		defaultOpen = false,
+		onOpenChange,
+		placement,
+
+		// Menu trigger props
+		trigger,
+
+		// Menu props
+		gutter,
+		children,
+		shift,
+		modal = true,
+		hideOnEscape = true,
+
+		// From internal components context
+		variant,
+
+		// Rest
+		...otherProps
+	} = useContextSystem<
+		typeof props & Pick< DropdownMenuContextType, 'variant' >
+	>( props, 'DropdownMenu' );
+
+	const parentContext = useContext( DropdownMenuContext );
+
+	const computedDirection = isRTL() ? 'rtl' : 'ltr';
+
+	// If an explicit value for the `placement` prop is not passed,
+	// apply a default placement of `bottom-start` for the root dropdown,
+	// and of `right-start` for nested dropdowns.
+	let computedPlacement =
+		props.placement ??
+		( parentContext?.store ? 'right-start' : 'bottom-start' );
+	// Swap left/right in case of RTL direction
+	if ( computedDirection === 'rtl' ) {
+		if ( /right/.test( computedPlacement ) ) {
+			computedPlacement = computedPlacement.replace(
+				'right',
+				'left'
+			) as typeof computedPlacement;
+		} else if ( /left/.test( computedPlacement ) ) {
+			computedPlacement = computedPlacement.replace(
+				'left',
+				'right'
+			) as typeof computedPlacement;
+		}
+	}
+
+	const dropdownMenuStore = Ariakit.useMenuStore( {
+		parent: parentContext?.store,
+		open,
+		defaultOpen,
+		placement: computedPlacement,
+		focusLoop: true,
+		setOpen( willBeOpen ) {
+			onOpenChange?.( willBeOpen );
+		},
+		rtl: computedDirection === 'rtl',
+	} );
+
+	const contextValue = useMemo(
+		() => ( { store: dropdownMenuStore, variant } ),
+		[ dropdownMenuStore, variant ]
+	);
+
+	// Extract the side from the applied placement — useful for animations.
+	const appliedPlacementSide = dropdownMenuStore
+		.useState( 'placement' )
+		.split( '-' )[ 0 ];
+
+	if (
+		dropdownMenuStore.parent &&
+		! ( isValidElement( trigger ) && DropdownMenuItem === trigger.type )
+	) {
+		// eslint-disable-next-line no-console
+		console.warn(
+			'For nested DropdownMenus, the `trigger` should always be a `DropdownMenuItem`.'
+		);
+	}
+
+	return (
+		<>
+			{ /* Menu trigger */ }
+			<Ariakit.MenuButton
+				ref={ ref }
+				store={ dropdownMenuStore }
+				render={
+					dropdownMenuStore.parent
+						? cloneElement( trigger, {
+								// Add submenu arrow, unless a `suffix` is explicitly specified
+								suffix: trigger.props.suffix ?? (
+									<Styled.SubmenuChevronIcon
+										aria-hidden="true"
+										icon={ chevronRightSmall }
+										size={ 24 }
+									/>
+								),
+						  } )
+						: trigger
+				}
+			/>
+
+			{ /* Menu popover */ }
+			<Styled.DropdownMenu
+				{ ...otherProps }
+				modal={ modal }
+				store={ dropdownMenuStore }
+				gutter={ gutter ?? ( dropdownMenuStore.parent ? 16 : 8 ) }
+				shift={ shift ?? ( dropdownMenuStore.parent ? -8 : 0 ) }
+				hideOnHoverOutside={ false }
+				data-side={ appliedPlacementSide }
+				variant={ variant }
+				wrapperProps={ {
+					dir: computedDirection,
+					style: {
+						direction: computedDirection,
+					},
+				} }
+				hideOnEscape={ hideOnEscape }
+				unmountOnHide
+			>
+				<DropdownMenuContext.Provider value={ contextValue }>
+					{ children }
+				</DropdownMenuContext.Provider>
+			</Styled.DropdownMenu>
+		</>
+	);
+};
+export const DropdownMenu = contextConnect(
+	UnconnectedDropdownMenu,
+	'DropdownMenu'
+);
+
+export const DropdownMenuSeparator = forwardRef<
+	HTMLHRElement,
+	WordPressComponentProps< DropdownMenuSeparatorProps, 'hr', false >
+>( function DropdownMenuSeparator( props, ref ) {
+	const dropdownMenuContext = useContext( DropdownMenuContext );
+	return (
+		<Styled.DropdownMenuSeparator
+			ref={ ref }
+			{ ...props }
+			store={ dropdownMenuContext?.store }
+			variant={ dropdownMenuContext?.variant }
+		/>
+	);
+} );