@wordpress/components 23.3.5 → 23.5.0

package/src/combobox-control/test/{index.js → index.tsx}

@@ -12,7 +12,8 @@ import { useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import ComboboxControl from '../';
+import ComboboxControl from '..';
+import type { ComboboxControlOption, ComboboxControlProps } from '../types';
 
 const timezones = [
 	{ label: 'Greenwich Mean Time', value: 'GMT' },
@@ -49,20 +50,21 @@ const timezones = [
 ];
 
 const defaultLabelText = 'Select a timezone';
-const getLabel = ( labelText ) => screen.getByText( labelText );
-const getInput = ( name ) => screen.getByRole( 'combobox', { name } );
-const getOption = ( name ) => screen.getByRole( 'option', { name } );
+const getLabel = ( labelText: string ) => screen.getByText( labelText );
+const getInput = ( name: string ) => screen.getByRole( 'combobox', { name } );
+const getOption = ( name: string ) => screen.getByRole( 'option', { name } );
 const getAllOptions = () => screen.getAllByRole( 'option' );
-const getOptionSearchString = ( option ) => option.label.substring( 0, 11 );
+const getOptionSearchString = ( option: ComboboxControlOption ) =>
+	option.label.substring( 0, 11 );
 const setupUser = () => userEvent.setup();
 
 const ControlledComboboxControl = ( {
 	value: valueProp,
 	onChange,
 	...props
-} ) => {
+}: ComboboxControlProps ) => {
 	const [ value, setValue ] = useState( valueProp );
-	const handleOnChange = ( newValue ) => {
+	const handleOnChange: ComboboxControlProps[ 'onChange' ] = ( newValue ) => {
 		setValue( newValue );
 		onChange?.( newValue );
 	};

package/src/combobox-control/types.ts

@@ -0,0 +1,69 @@
+/**
+ * Internal dependencies
+ */
+import type { BaseControlProps } from '../base-control/types';
+
+export type ComboboxControlOption = {
+	label: string;
+	value: string;
+	[ key: string ]: any;
+};
+
+export type ComboboxControlProps = Pick<
+	BaseControlProps,
+	| '__nextHasNoMarginBottom'
+	| 'className'
+	| 'label'
+	| 'hideLabelFromVision'
+	| 'help'
+> & {
+	/**
+	 * Custom renderer invoked for each option in the suggestion list.
+	 * The render prop receives as its argument an object containing, under the `item` key,
+	 * the single option's data (directly from the array of data passed to the `options` prop).
+	 */
+	__experimentalRenderItem?: ( args: {
+		item: ComboboxControlOption;
+	} ) => React.ReactNode;
+	/**
+	 * Start opting into the larger default height that will become the default size in a future version.
+	 *
+	 * @default false
+	 */
+	__next36pxDefaultSize?: boolean;
+	/**
+	 * Show a reset button to clear the input.
+	 *
+	 * @default true
+	 */
+	allowReset?: boolean;
+	/**
+	 * Customizable UI messages.
+	 */
+	messages?: {
+		/**
+		 * The message to announce to screen readers when a suggestion is selected.
+		 *
+		 * @default `__( 'Item selected.' )`
+		 */
+		selected: string;
+	};
+	/**
+	 * Function called with the selected value changes.
+	 */
+	onChange?: ( value: ComboboxControlProps[ 'value' ] ) => void;
+	/**
+	 * Function called when the control's search input value changes. The argument contains the next input value.
+	 *
+	 * @default noop
+	 */
+	onFilterValueChange?: ( value: string ) => void;
+	/**
+	 * The options that can be chosen from.
+	 */
+	options: ComboboxControlOption[];
+	/**
+	 * The current value of the control.
+	 */
+	value?: string | null;
+};

package/src/custom-gradient-picker/index.js

@@ -53,7 +53,6 @@ const GradientAnglePicker = ( { gradientAST, hasGradient, onChange } ) => {
 		<AnglePickerControl
 			__nextHasNoMarginBottom
 			onChange={ onAngleChange }
-			labelPosition="top"
 			value={ hasGradient ? angle : '' }
 		/>
 	);

package/src/custom-select-control/stories/index.js

@@ -10,9 +10,9 @@ export default {
 		__next36pxDefaultSize: { control: { type: 'boolean' } },
 		__experimentalShowSelectedHint: { control: { type: 'boolean' } },
 		size: {
+			options: [ 'small', 'default', '__unstable-large' ],
 			control: {
 				type: 'radio',
-				options: [ 'small', 'default', '__unstable-large' ],
 			},
 		},
 	},

package/src/date-time/time/index.tsx

@@ -51,7 +51,7 @@ function from12hTo24h( hours: number, isPm: boolean ) {
  * given width. For example, the hours and minutes inputs are padded to 2 so
  * that '4' appears as '04'.
  *
- * @param  pad How many digits the value should be.
+ * @param pad How many digits the value should be.
  */
 function buildPadInputStateReducer( pad: number ) {
 	return ( state: InputState, action: InputAction ) => {

package/src/date-time/utils.ts

@@ -7,7 +7,7 @@ import { toDate } from 'date-fns';
  * Like date-fn's toDate, but tries to guess the format when a string is
  * given.
  *
- * @param  input Value to turn into a date.
+ * @param input Value to turn into a date.
  */
 export function inputToDate( input: Date | string | number ): Date {
 	if ( typeof input === 'string' ) {

package/src/draggable/index.tsx

@@ -75,7 +75,7 @@ export function Draggable( {
 	/**
 	 * Removes the element clone, resets cursor, and removes drag listener.
 	 *
-	 * @param  event The non-custom DragEvent.
+	 * @param event The non-custom DragEvent.
 	 */
 	function end( event: DragEvent ) {
 		event.preventDefault();
@@ -94,7 +94,7 @@ export function Draggable( {
 	 * - Sets transfer data.
 	 * - Adds dragover listener.
 	 *
-	 * @param  event The non-custom DragEvent.
+	 * @param event The non-custom DragEvent.
 	 */
 	function start( event: DragEvent ) {
 		const { ownerDocument } = event.target as HTMLElement;

package/src/dropdown-menu/test/index.js

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { act, render, screen, waitFor, within } from '@testing-library/react';
+import { render, screen, waitFor, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 
 /**
@@ -63,10 +63,6 @@ describe( 'DropdownMenu', () => {
 
 		await user.keyboard( '[ArrowDown]' );
 
-		// Wait for the `floating-ui` effects in `Dropdown`/`Popover` to finish running
-		// See also: https://floating-ui.com/docs/react-dom#testing
-		await act( () => Promise.resolve() );
-
 		const menu = screen.getByRole( 'menu' );
 
 		// we need to wait because showing the dropdown is animated
@@ -86,15 +82,11 @@ describe( 'DropdownMenu', () => {
 			/>
 		);
 
-		const button = screen.getByRole( 'button' );
-		act( () => button.focus() );
+		// Move focus on the toggle button
+		await user.tab();
 
 		await user.keyboard( '[ArrowDown]' );
 
-		// Wait for the `floating-ui` effects in `Dropdown`/`Popover` to finish running
-		// See also: https://floating-ui.com/docs/react-dom#testing
-		await act( () => Promise.resolve() );
-
 		const menu = screen.getByRole( 'menu' );
 
 		// we need to wait because showing the dropdown is animated

package/src/focal-point-picker/utils.ts

@@ -19,7 +19,7 @@ const VIDEO_EXTENSIONS = [
 /**
  * Gets the extension of a file name.
  *
- * @param  filename The file name.
+ * @param filename The file name.
  * @return  The extension of the file name.
  */
 export function getExtension( filename = '' ): string {
@@ -30,7 +30,7 @@ export function getExtension( filename = '' ): string {
 /**
  * Checks if a file is a video.
  *
- * @param  filename The file name.
+ * @param filename The file name.
  * @return Whether the file is a video.
  */
 export function isVideoType( filename: string = '' ): boolean {
@@ -44,7 +44,7 @@ export function isVideoType( filename: string = '' ): boolean {
 /**
  * Transforms a fraction value to a percentage value.
  *
- * @param  fraction The fraction value.
+ * @param fraction The fraction value.
  * @return A percentage value.
  */
 export function fractionToPercentage( fraction: number ): number {

package/src/font-size-picker/utils.ts

@@ -13,7 +13,7 @@ import { parseQuantityAndUnitFromRawValue } from '../unit-control';
  * Some themes use css vars for their font sizes, so until we
  * have the way of calculating them don't display them.
  *
- * @param  value The value that is checked.
+ * @param value The value that is checked.
  * @return Whether the value is a simple css value.
  */
 export function isSimpleCssValue(
@@ -27,7 +27,7 @@ export function isSimpleCssValue(
  * If all of the given font sizes have the same unit (e.g. 'px'), return that
  * unit. Otherwise return null.
  *
- * @param  fontSizes List of font sizes.
+ * @param fontSizes List of font sizes.
  * @return The common unit, or null.
  */
 export function getCommonSizeUnit( fontSizes: FontSize[] ) {

package/src/gradient-picker/README.md

@@ -101,3 +101,11 @@ Start opting into the new margin-free styles that will become the default in a f
 -   Type: `Boolean`
 -   Required: No
 -   Default: `false`
+
+### headingLevel
+
+The heading level.
+
+-   Type: `1 | 2 | 3 | 4 | 5 | 6 | '1' | '2' | '3' | '4' | '5' | '6'`
+-   Required: No
+-   Default: `2`

package/src/gradient-picker/index.js

@@ -77,13 +77,16 @@ function MultipleOrigin( {
 	onChange,
 	value,
 	actions,
+	headingLevel,
 } ) {
 	return (
 		<VStack spacing={ 3 } className={ className }>
 			{ gradients.map( ( { name, gradients: gradientSet }, index ) => {
 				return (
 					<VStack spacing={ 2 } key={ index }>
-						<ColorHeading>{ name }</ColorHeading>
+						<ColorHeading level={ headingLevel }>
+							{ name }
+						</ColorHeading>
 						<SingleOrigin
 							clearGradient={ clearGradient }
 							gradients={ gradientSet }
@@ -112,6 +115,7 @@ export default function GradientPicker( {
 	clearable = true,
 	disableCustomGradients = false,
 	__experimentalIsRenderedInSidebar,
+	headingLevel = 2,
 } ) {
 	const clearGradient = useCallback(
 		() => onChange( undefined ),
@@ -168,6 +172,7 @@ export default function GradientPicker( {
 								</CircularOptionPicker.ButtonAction>
 							)
 						}
+						headingLevel={ headingLevel }
 					/>
 				) }
 			</VStack>

package/src/h-stack/stories/e2e/index.tsx

@@ -0,0 +1,36 @@
+/**
+ * External dependencies
+ */
+import type { ComponentStory, ComponentMeta } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { View } from '../../../view';
+import { HStack } from '../..';
+
+const meta: ComponentMeta< typeof HStack > = {
+	component: HStack,
+	title: 'Components (Experimental)/HStack',
+};
+export default meta;
+
+const Template: ComponentStory< typeof HStack > = ( props ) => {
+	return (
+		<HStack
+			style={ { background: '#eee', minHeight: '3rem' } }
+			{ ...props }
+		>
+			{ [ 'One', 'Two', 'Three', 'Four', 'Five' ].map( ( text ) => (
+				<View key={ text } style={ { background: '#b9f9ff' } }>
+					{ text }
+				</View>
+			) ) }
+		</HStack>
+	);
+};
+
+export const Default: ComponentStory< typeof HStack > = Template.bind( {} );
+Default.args = {
+	spacing: 3,
+};

package/src/higher-order/with-constrained-tabbing/index.tsx

@@ -0,0 +1,30 @@
+/**
+ * WordPress dependencies
+ */
+import {
+	createHigherOrderComponent,
+	useConstrainedTabbing,
+} from '@wordpress/compose';
+
+/**
+ * `withConstrainedTabbing` is a React [higher-order component](https://facebook.github.io/react/docs/higher-order-components.html)
+ * adding the ability to constrain keyboard navigation with the Tab key within a component.
+ * For accessibility reasons, some UI components need to constrain Tab navigation, for example
+ * modal dialogs or similar UI. Use of this component is recommended only in cases where a way to
+ * navigate away from the wrapped component is implemented by other means, usually by pressing
+ * the Escape key or using a specific UI control, e.g. a "Close" button.
+ */
+const withConstrainedTabbing = createHigherOrderComponent(
+	( WrappedComponent ) =>
+		function ComponentWithConstrainedTabbing( props ) {
+			const ref = useConstrainedTabbing();
+			return (
+				<div ref={ ref } tabIndex={ -1 }>
+					<WrappedComponent { ...props } />
+				</div>
+			);
+		},
+	'withConstrainedTabbing'
+);
+
+export default withConstrainedTabbing;

package/src/input-control/reducer/reducer.ts

@@ -23,7 +23,7 @@ import type { InputChangeCallback } from '../types';
 /**
  * Prepares initialState for the reducer.
  *
- * @param  initialState The initial state.
+ * @param initialState The initial state.
  * @return Prepared initialState for the reducer
  */
 function mergeInitialState(
@@ -45,7 +45,7 @@ function mergeInitialState(
  * exception for CONTROL actions is because they represent controlled updates
  * from props and no case has yet presented for their specialization.
  *
- * @param  composedStateReducers A reducer to specialize state changes.
+ * @param composedStateReducers A reducer to specialize state changes.
  * @return The reducer.
  */
 function inputControlStateReducer(
@@ -140,9 +140,9 @@ function inputControlStateReducer(
  * This technique uses the "stateReducer" design pattern:
  * https://kentcdodds.com/blog/the-state-reducer-pattern/
  *
- * @param  stateReducer    An external state reducer.
- * @param  initialState    The initial state for the reducer.
- * @param  onChangeHandler A handler for the onChange event.
+ * @param stateReducer    An external state reducer.
+ * @param initialState    The initial state for the reducer.
+ * @param onChangeHandler A handler for the onChange event.
  * @return State, dispatch, and a collection of actions.
  */
 export function useInputControlStateReducer(

package/src/input-control/utils.ts

@@ -21,7 +21,7 @@ import type { InputChangeCallback } from './types';
 /**
  * Gets a CSS cursor value based on a drag direction.
  *
- * @param  dragDirection The drag direction.
+ * @param dragDirection The drag direction.
  * @return  The CSS cursor value.
  */
 export function getDragCursor( dragDirection: string ): string {

package/src/menu-items-choice/index.tsx

@@ -0,0 +1,83 @@
+/**
+ * WordPress dependencies
+ */
+import { check } from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import MenuItem from '../menu-item';
+import type { MenuItemsChoiceProps } from './types';
+
+const noop = () => {};
+
+/**
+ * `MenuItemsChoice` functions similarly to a set of `MenuItem`s, but allows the user to select one option from a set of multiple choices.
+ *
+ *
+ * ```jsx
+ * import { MenuGroup, MenuItemsChoice } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const MyMenuItemsChoice = () => {
+ * 	const [ mode, setMode ] = useState( 'visual' );
+ * 	const choices = [
+ * 		{
+ * 			value: 'visual',
+ * 			label: 'Visual editor',
+ * 		},
+ * 		{
+ * 			value: 'text',
+ * 			label: 'Code editor',
+ * 		},
+ * 	];
+ *
+ * 	return (
+ * 		<MenuGroup label="Editor">
+ * 			<MenuItemsChoice
+ * 				choices={ choices }
+ * 				value={ mode }
+ * 				onSelect={ ( newMode ) => setMode( newMode ) }
+ * 			/>
+ * 		</MenuGroup>
+ * 	);
+ * };
+ * ```
+ */
+function MenuItemsChoice( {
+	choices = [],
+	onHover = noop,
+	onSelect,
+	value,
+}: MenuItemsChoiceProps ) {
+	return (
+		<>
+			{ choices.map( ( item ) => {
+				const isSelected = value === item.value;
+				return (
+					<MenuItem
+						key={ item.value }
+						role="menuitemradio"
+						icon={ isSelected && check }
+						info={ item.info }
+						isSelected={ isSelected }
+						shortcut={ item.shortcut }
+						className="components-menu-items-choice"
+						onClick={ () => {
+							if ( ! isSelected ) {
+								onSelect( item.value );
+							}
+						} }
+						onMouseEnter={ () => onHover( item.value ) }
+						onMouseLeave={ () => onHover( null ) }
+						aria-label={ item[ 'aria-label' ] }
+					>
+						{ item.label }
+					</MenuItem>
+				);
+			} ) }
+		</>
+	);
+}
+
+export default MenuItemsChoice;

package/src/menu-items-choice/stories/index.tsx

@@ -0,0 +1,79 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import MenuItemsChoice from '..';
+import MenuGroup from '../../menu-group';
+
+const meta: ComponentMeta< typeof MenuItemsChoice > = {
+	component: MenuItemsChoice,
+	title: 'Components/MenuItemsChoice',
+	argTypes: {
+		onHover: { action: 'onHover' },
+		onSelect: { action: 'onSelect' },
+		value: { control: { type: null } },
+	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof MenuItemsChoice > = ( {
+	onHover,
+	onSelect,
+	choices,
+} ) => {
+	const [ choice, setChoice ] = useState( choices[ 0 ]?.value ?? '' );
+
+	return (
+		<MenuGroup label="Editor">
+			<MenuItemsChoice
+				choices={ choices }
+				value={ choice }
+				onSelect={ ( ...selectArgs ) => {
+					onSelect( ...selectArgs );
+					setChoice( ...selectArgs );
+				} }
+				onHover={ onHover }
+			/>
+		</MenuGroup>
+	);
+};
+
+export const Default: ComponentStory< typeof MenuItemsChoice > = Template.bind(
+	{}
+);
+
+Default.args = {
+	choices: [
+		{
+			value: 'arbitrary-choice-1',
+			label: 'Arbitrary Label #1',
+			info: 'Arbitrary Explanatory 1',
+		},
+		{
+			value: 'arbitrary-choice-2',
+			label: 'Arbitrary Label #2',
+			info: 'Arbitrary Explanatory 2',
+		},
+		{
+			value: 'arbitrary-choice-3',
+			label: 'Arbitrary Label #3',
+			info: 'Arbitrary Explanatory 3',
+		},
+	],
+	value: 'arbitrary-choice-1',
+};

package/src/menu-items-choice/types.ts

@@ -0,0 +1,54 @@
+/**
+ * Internal dependencies
+ */
+import type { ShortcutProps } from '../shortcut/types';
+
+export type MenuItemsChoiceProps = {
+	/**
+	 * Array of choices.
+	 *
+	 * @default []
+	 */
+	choices: readonly MenuItemChoice[];
+	/**
+	 * Value of currently selected choice (should match a `value` property
+	 * from a choice in `choices`).
+	 */
+	value: string;
+	/**
+	 * Callback function to be called with the selected choice when user
+	 * selects a new choice.
+	 */
+	onSelect( value: string ): void;
+	/**
+	 * Callback function to be called with a choice when user
+	 * hovers over a new choice (will be empty on mouse leave).
+	 *
+	 * @default noop
+	 */
+	onHover: ( value: string | null ) => void;
+};
+
+export type MenuItemChoice = {
+	/**
+	 * Human-readable label for choice.
+	 */
+	label: string;
+	/**
+	 * Unique value for choice.
+	 */
+	value: string;
+	/**
+	 * Additional information which will be rendered below the given label.
+	 */
+	info?: string;
+	/**
+	 * Optional keyboard sequence to trigger choice with keyboard shortcut
+	 * (e.g. `ctrl+s`).
+	 */
+	shortcut?: ShortcutProps[ 'shortcut' ];
+	/**
+	 * Aria compliant label.
+	 */
+	[ 'aria-label' ]?: string;
+};

package/src/mobile/global-styles-context/utils.native.js

@@ -416,6 +416,7 @@ export function getGlobalStyles( rawStyles, rawFeatures ) {
 				fontSizes,
 				customLineHeight: features?.custom?.[ 'line-height' ],
 			},
+			spacing: features?.spacing,
 		},
 		__experimentalGlobalStylesBaseStyles: globalStyles,
 	};