@wordpress/components 25.14.0 → 25.15.1-next.79a6196f.0

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

@@ -1,331 +0,0 @@
-# `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
-
-### `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
-
-### `DropdownMenuItemLabel`
-
-Used to render the menu item's label.
-
-#### Props
-
-The component accepts the following props:
-
-##### `children`: `React.ReactNode`
-
-The label contents.
-
-- Required: yes
-
-### `DropdownMenuItemHelpText`
-
-Used to render the menu item's help text.
-
-#### Props
-
-The component accepts the following props:
-
-##### `children`: `React.ReactNode`
-
-The help text contents.
-
-- 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-ariakit/index.tsx

@@ -1,383 +0,0 @@
-/**
- * External dependencies
- */
-// eslint-disable-next-line no-restricted-imports
-import * as Ariakit from '@ariakit/react';
-
-/**
- * WordPress dependencies
- */
-import {
-	forwardRef,
-	createContext,
-	useContext,
-	useMemo,
-	cloneElement,
-	isValidElement,
-	useCallback,
-} 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,
-	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 }
-			accessibleWhenDisabled
-			hideOnClick={ hideOnClick }
-			store={ dropdownMenuContext?.store }
-		>
-			<Styled.ItemPrefixWrapper>{ prefix }</Styled.ItemPrefixWrapper>
-
-			<Styled.DropdownMenuItemContentWrapper>
-				<Styled.DropdownMenuItemChildrenWrapper>
-					{ children }
-				</Styled.DropdownMenuItemChildrenWrapper>
-
-				{ suffix && (
-					<Styled.ItemSuffixWrapper>
-						{ suffix }
-					</Styled.ItemSuffixWrapper>
-				) }
-			</Styled.DropdownMenuItemContentWrapper>
-		</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 }
-			accessibleWhenDisabled
-			hideOnClick={ hideOnClick }
-			store={ dropdownMenuContext?.store }
-		>
-			<Ariakit.MenuItemCheck
-				store={ dropdownMenuContext?.store }
-				render={ <Styled.ItemPrefixWrapper /> }
-				// Override some ariakit inline styles
-				style={ { width: 'auto', height: 'auto' } }
-			>
-				<Icon icon={ check } size={ 24 } />
-			</Ariakit.MenuItemCheck>
-
-			<Styled.DropdownMenuItemContentWrapper>
-				<Styled.DropdownMenuItemChildrenWrapper>
-					{ children }
-				</Styled.DropdownMenuItemChildrenWrapper>
-
-				{ suffix && (
-					<Styled.ItemSuffixWrapper>
-						{ suffix }
-					</Styled.ItemSuffixWrapper>
-				) }
-			</Styled.DropdownMenuItemContentWrapper>
-		</Styled.DropdownMenuCheckboxItem>
-	);
-} );
-
-const radioCheck = (
-	<SVG xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
-		<Circle cx={ 12 } cy={ 12 } r={ 3 }></Circle>
-	</SVG>
-);
-
-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 }
-			accessibleWhenDisabled
-			hideOnClick={ hideOnClick }
-			store={ dropdownMenuContext?.store }
-		>
-			<Ariakit.MenuItemCheck
-				store={ dropdownMenuContext?.store }
-				render={ <Styled.ItemPrefixWrapper /> }
-				// Override some ariakit inline styles
-				style={ { width: 'auto', height: 'auto' } }
-			>
-				<Icon icon={ radioCheck } size={ 24 } />
-			</Ariakit.MenuItemCheck>
-
-			<Styled.DropdownMenuItemContentWrapper>
-				<Styled.DropdownMenuItemChildrenWrapper>
-					{ children }
-				</Styled.DropdownMenuItemChildrenWrapper>
-
-				{ suffix && (
-					<Styled.ItemSuffixWrapper>
-						{ suffix }
-					</Styled.ItemSuffixWrapper>
-				) }
-			</Styled.DropdownMenuItemContentWrapper>
-		</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 }
-		/>
-	);
-} );
-
-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,
-
-		// 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`.'
-		);
-	}
-
-	const hideOnEscape = useCallback(
-		( event: React.KeyboardEvent< Element > ) => {
-			// Pressing Escape can cause unexpected consequences (ie. exiting
-			// full screen mode on MacOs, close parent modals...).
-			event.preventDefault();
-			// Returning `true` causes the menu to hide.
-			return true;
-		},
-		[]
-	);
-
-	const wrapperProps = useMemo(
-		() => ( {
-			dir: computedDirection,
-			style: {
-				direction:
-					computedDirection as React.CSSProperties[ 'direction' ],
-			},
-		} ),
-		[ computedDirection ]
-	);
-
-	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 }
-											preserveAspectRatio="xMidYMid slice"
-										/>
-									</>
-								),
-						  } )
-						: trigger
-				}
-			/>
-
-			{ /* Menu popover */ }
-			<Styled.DropdownMenu
-				{ ...otherProps }
-				modal={ modal }
-				store={ dropdownMenuStore }
-				// Root menu has an 8px distance from its trigger,
-				// otherwise 0 (which causes the submenu to slightly overlap)
-				gutter={ gutter ?? ( dropdownMenuStore.parent ? 0 : 8 ) }
-				// Align nested menu by the same (but opposite) amount
-				// as the menu container's padding.
-				shift={ shift ?? ( dropdownMenuStore.parent ? -4 : 0 ) }
-				hideOnHoverOutside={ false }
-				data-side={ appliedPlacementSide }
-				variant={ variant }
-				wrapperProps={ wrapperProps }
-				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 }
-		/>
-	);
-} );
-
-export const DropdownMenuItemLabel = forwardRef<
-	HTMLSpanElement,
-	WordPressComponentProps< { children: React.ReactNode }, 'span', true >
->( function DropdownMenuItemLabel( props, ref ) {
-	return (
-		<Styled.DropdownMenuItemLabel
-			numberOfLines={ 1 }
-			ref={ ref }
-			{ ...props }
-		/>
-	);
-} );
-
-export const DropdownMenuItemHelpText = forwardRef<
-	HTMLSpanElement,
-	WordPressComponentProps< { children: React.ReactNode }, 'span', true >
->( function DropdownMenuItemHelpText( props, ref ) {
-	return (
-		<Styled.DropdownMenuItemHelpText
-			numberOfLines={ 2 }
-			ref={ ref }
-			{ ...props }
-		/>
-	);
-} );