@wordpress/components 24.0.0 → 25.0.0

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.

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

@@ -0,0 +1,241 @@
+/**
+ * External dependencies
+ */
+import * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu';
+
+/**
+ * WordPress dependencies
+ */
+import { forwardRef } from '@wordpress/element';
+import { isRTL } from '@wordpress/i18n';
+import { check, chevronRightSmall, lineSolid } from '@wordpress/icons';
+import { SVG, Circle } from '@wordpress/primitives';
+
+/**
+ * Internal dependencies
+ */
+import Icon from '../icon';
+import * as DropdownMenuStyled from './styles';
+import type {
+	DropdownMenuProps,
+	DropdownSubMenuProps,
+	DropdownMenuItemProps,
+	DropdownMenuLabelProps,
+	DropdownMenuGroupProps,
+	DropdownMenuCheckboxItemProps,
+	DropdownMenuRadioGroupProps,
+	DropdownMenuRadioItemProps,
+	DropdownMenuSeparatorProps,
+	DropdownSubMenuTriggerProps,
+} from './types';
+
+// Menu content's side padding + 4px
+const SUB_MENU_OFFSET_SIDE = 12;
+// Opposite amount of the top padding of the menu item
+const SUB_MENU_OFFSET_ALIGN = -8;
+
+/**
+ * `DropdownMenu` displays a menu to the user (such as a set of actions
+ * or functions) triggered by a button.
+ */
+export const DropdownMenu = ( {
+	// Root props
+	defaultOpen,
+	open,
+	onOpenChange,
+	modal = true,
+	// Content positioning props
+	side = 'bottom',
+	sideOffset = 0,
+	align = 'center',
+	alignOffset = 0,
+	// Render props
+	children,
+	trigger,
+}: DropdownMenuProps ) => {
+	return (
+		<DropdownMenuPrimitive.Root
+			defaultOpen={ defaultOpen }
+			open={ open }
+			onOpenChange={ onOpenChange }
+			modal={ modal }
+			dir={ isRTL() ? 'rtl' : 'ltr' }
+		>
+			<DropdownMenuPrimitive.Trigger asChild>
+				{ trigger }
+			</DropdownMenuPrimitive.Trigger>
+			<DropdownMenuPrimitive.Portal>
+				<DropdownMenuStyled.Content
+					side={ side }
+					align={ align }
+					sideOffset={ sideOffset }
+					alignOffset={ alignOffset }
+					loop={ true }
+				>
+					{ children }
+				</DropdownMenuStyled.Content>
+			</DropdownMenuPrimitive.Portal>
+		</DropdownMenuPrimitive.Root>
+	);
+};
+
+export const DropdownSubMenuTrigger = ( {
+	prefix,
+	suffix = (
+		<DropdownMenuStyled.SubmenuRtlChevronIcon
+			icon={ chevronRightSmall }
+			size={ 24 }
+		/>
+	),
+	children,
+}: DropdownSubMenuTriggerProps ) => {
+	return (
+		<>
+			{ prefix && (
+				<DropdownMenuStyled.ItemPrefixWrapper>
+					{ prefix }
+				</DropdownMenuStyled.ItemPrefixWrapper>
+			) }
+			{ children }
+			{ suffix && (
+				<DropdownMenuStyled.ItemSuffixWrapper>
+					{ suffix }
+				</DropdownMenuStyled.ItemSuffixWrapper>
+			) }
+		</>
+	);
+};
+
+export const DropdownSubMenu = ( {
+	// Sub props
+	defaultOpen,
+	open,
+	onOpenChange,
+	// Sub trigger props
+	disabled,
+	textValue,
+	// Render props
+	children,
+	trigger,
+}: DropdownSubMenuProps ) => {
+	return (
+		<DropdownMenuPrimitive.Sub
+			defaultOpen={ defaultOpen }
+			open={ open }
+			onOpenChange={ onOpenChange }
+		>
+			<DropdownMenuStyled.SubTrigger
+				disabled={ disabled }
+				textValue={ textValue }
+			>
+				{ trigger }
+			</DropdownMenuStyled.SubTrigger>
+			<DropdownMenuPrimitive.Portal>
+				<DropdownMenuStyled.SubContent
+					loop
+					sideOffset={ SUB_MENU_OFFSET_SIDE }
+					alignOffset={ SUB_MENU_OFFSET_ALIGN }
+				>
+					{ children }
+				</DropdownMenuStyled.SubContent>
+			</DropdownMenuPrimitive.Portal>
+		</DropdownMenuPrimitive.Sub>
+	);
+};
+
+export const DropdownMenuLabel = ( props: DropdownMenuLabelProps ) => (
+	<DropdownMenuStyled.Label { ...props } />
+);
+
+export const DropdownMenuGroup = ( props: DropdownMenuGroupProps ) => (
+	<DropdownMenuPrimitive.Group { ...props } />
+);
+
+export const DropdownMenuItem = forwardRef(
+	(
+		{ children, prefix, suffix, ...props }: DropdownMenuItemProps,
+		forwardedRef: React.ForwardedRef< any >
+	) => {
+		return (
+			<DropdownMenuStyled.Item { ...props } ref={ forwardedRef }>
+				{ prefix && (
+					<DropdownMenuStyled.ItemPrefixWrapper>
+						{ prefix }
+					</DropdownMenuStyled.ItemPrefixWrapper>
+				) }
+				{ children }
+				{ suffix && (
+					<DropdownMenuStyled.ItemSuffixWrapper>
+						{ suffix }
+					</DropdownMenuStyled.ItemSuffixWrapper>
+				) }
+			</DropdownMenuStyled.Item>
+		);
+	}
+);
+
+export const DropdownMenuCheckboxItem = ( {
+	children,
+	checked = false,
+	suffix,
+	...props
+}: DropdownMenuCheckboxItemProps ) => {
+	return (
+		<DropdownMenuStyled.CheckboxItem { ...props } checked={ checked }>
+			<DropdownMenuStyled.ItemPrefixWrapper>
+				<DropdownMenuStyled.ItemIndicator>
+					{ ( checked === 'indeterminate' || checked === true ) && (
+						<Icon
+							icon={
+								checked === 'indeterminate' ? lineSolid : check
+							}
+							size={ 24 }
+						/>
+					) }
+				</DropdownMenuStyled.ItemIndicator>
+			</DropdownMenuStyled.ItemPrefixWrapper>
+			{ children }
+			{ suffix && (
+				<DropdownMenuStyled.ItemSuffixWrapper>
+					{ suffix }
+				</DropdownMenuStyled.ItemSuffixWrapper>
+			) }
+		</DropdownMenuStyled.CheckboxItem>
+	);
+};
+
+export const DropdownMenuRadioGroup = (
+	props: DropdownMenuRadioGroupProps
+) => <DropdownMenuPrimitive.RadioGroup { ...props } />;
+
+const radioDot = (
+	<SVG viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+		<Circle cx={ 12 } cy={ 12 } r={ 3 } fill="currentColor"></Circle>
+	</SVG>
+);
+
+export const DropdownMenuRadioItem = ( {
+	children,
+	suffix,
+	...props
+}: DropdownMenuRadioItemProps ) => {
+	return (
+		<DropdownMenuStyled.RadioItem { ...props }>
+			<DropdownMenuStyled.ItemPrefixWrapper>
+				<DropdownMenuStyled.ItemIndicator>
+					<Icon icon={ radioDot } size={ 22 } />
+				</DropdownMenuStyled.ItemIndicator>
+			</DropdownMenuStyled.ItemPrefixWrapper>
+			{ children }
+			{ suffix && (
+				<DropdownMenuStyled.ItemSuffixWrapper>
+					{ suffix }
+				</DropdownMenuStyled.ItemSuffixWrapper>
+			) }
+		</DropdownMenuStyled.RadioItem>
+	);
+};
+
+export const DropdownMenuSeparator = ( props: DropdownMenuSeparatorProps ) => (
+	<DropdownMenuStyled.Separator { ...props } />
+);