@wordpress/components 23.3.1 → 23.4.0

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/index.js

@@ -59,7 +59,7 @@ export {
 	useCompositeState as __unstableUseCompositeState,
 } from './composite';
 export { ConfirmDialog as __experimentalConfirmDialog } from './confirm-dialog';
-export { default as CustomSelectControl } from './custom-select-control';
+export { StableCustomSelectControl as CustomSelectControl } from './custom-select-control';
 export { default as Dashicon } from './dashicon';
 export { default as DateTimePicker, DatePicker, TimePicker } from './date-time';
 export { default as __experimentalDimensionControl } from './dimension-control';
@@ -115,6 +115,7 @@ export {
 	NavigatorScreen as __experimentalNavigatorScreen,
 	NavigatorButton as __experimentalNavigatorButton,
 	NavigatorBackButton as __experimentalNavigatorBackButton,
+	NavigatorToParentButton as __experimentalNavigatorToParentButton,
 	useNavigator as __experimentalUseNavigator,
 } from './navigator';
 export { default as Notice } from './notice';
@@ -126,7 +127,6 @@ export { default as PanelHeader } from './panel/header';
 export { default as PanelRow } from './panel/row';
 export { default as Placeholder } from './placeholder';
 export { default as Popover } from './popover';
-export { positionToPlacement as __experimentalPopoverPositionToPlacement } from './popover/utils';
 export { default as QueryControls } from './query-controls';
 export { default as __experimentalRadio } from './radio-group/radio';
 export { default as __experimentalRadioGroup } from './radio-group';
@@ -212,3 +212,6 @@ export {
 } from './higher-order/with-focus-return';
 export { default as withNotices } from './higher-order/with-notices';
 export { default as withSpokenMessages } from './higher-order/with-spoken-messages';
+
+// Private APIs.
+export { privateApis } from './private-apis';

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/modal/index.tsx

@@ -14,6 +14,7 @@ import {
 	useRef,
 	useState,
 	forwardRef,
+	useLayoutEffect,
 } from '@wordpress/element';
 import {
 	useInstanceId,
@@ -25,6 +26,7 @@ import {
 } from '@wordpress/compose';
 import { __ } from '@wordpress/i18n';
 import { close } from '@wordpress/icons';
+import { getScrollContainer } from '@wordpress/dom';
 
 /**
  * Internal dependencies
@@ -76,8 +78,26 @@ function UnforwardedModal(
 	const constrainedTabbingRef = useConstrainedTabbing();
 	const focusReturnRef = useFocusReturn();
 	const focusOutsideProps = useFocusOutside( onRequestClose );
+	const contentRef = useRef< HTMLDivElement >( null );
+	const childrenContainerRef = useRef< HTMLDivElement >( null );
 
 	const [ hasScrolledContent, setHasScrolledContent ] = useState( false );
+	const [ hasScrollableContent, setHasScrollableContent ] = useState( false );
+
+	// Determines whether the Modal content is scrollable and updates the state.
+	const isContentScrollable = useCallback( () => {
+		if ( ! contentRef.current ) {
+			return;
+		}
+
+		const closestScrollContainer = getScrollContainer( contentRef.current );
+
+		if ( contentRef.current === closestScrollContainer ) {
+			setHasScrollableContent( true );
+		} else {
+			setHasScrollableContent( false );
+		}
+	}, [ contentRef ] );
 
 	useEffect( () => {
 		openModalCount++;
@@ -97,6 +117,22 @@ function UnforwardedModal(
 		};
 	}, [ bodyOpenClassName ] );
 
+	// Calls the isContentScrollable callback when the Modal children container resizes.
+	useLayoutEffect( () => {
+		if ( ! window.ResizeObserver || ! childrenContainerRef.current ) {
+			return;
+		}
+
+		const resizeObserver = new ResizeObserver( isContentScrollable );
+		resizeObserver.observe( childrenContainerRef.current );
+
+		isContentScrollable();
+
+		return () => {
+			resizeObserver.disconnect();
+		};
+	}, [ isContentScrollable, childrenContainerRef ] );
+
 	function handleEscapeKeyDown( event: KeyboardEvent< HTMLDivElement > ) {
 		if (
 			// Ignore keydowns from IMEs
@@ -172,10 +208,18 @@ function UnforwardedModal(
 					<div
 						className={ classnames( 'components-modal__content', {
 							'hide-header': __experimentalHideHeader,
+							'is-scrollable': hasScrollableContent,
 							'has-scrolled-content': hasScrolledContent,
 						} ) }
 						role="document"
 						onScroll={ onContentContainerScroll }
+						ref={ contentRef }
+						aria-label={
+							hasScrollableContent
+								? __( 'Scrollable section' )
+								: undefined
+						}
+						tabIndex={ hasScrollableContent ? 0 : undefined }
 					>
 						{ ! __experimentalHideHeader && (
 							<div className="components-modal__header">
@@ -208,7 +252,7 @@ function UnforwardedModal(
 								) }
 							</div>
 						) }
-						{ children }
+						<div ref={ childrenContainerRef }>{ children }</div>
 					</div>
 				</div>
 			</StyleProvider>

package/src/modal/style.scss

@@ -129,4 +129,12 @@
 		margin-top: 0;
 		padding-top: $grid-unit-30;
 	}
+
+	&.is-scrollable:focus-visible {
+		box-shadow: inset 0 0 0 var(--wp-admin-border-width-focus) var(--wp-admin-theme-color);
+
+		// Windows High Contrast mode will show this outline, but not the box-shadow.
+		outline: 2px solid transparent;
+		outline-offset: -2px;
+	}
 }

package/src/modal/types.ts

@@ -50,6 +50,8 @@ export type ModalProps = {
 	className?: string;
 	/**
 	 * Label on the close button.
+	 *
+	 * @default `__( 'Close' )`
 	 */
 	closeButtonLabel?: string;
 	/**

package/src/navigator/context.ts

@@ -12,5 +12,9 @@ const initialContextValue: NavigatorContextType = {
 	location: {},
 	goTo: () => {},
 	goBack: () => {},
+	goToParent: () => {},
+	addScreen: () => {},
+	removeScreen: () => {},
+	params: {},
 };
 export const NavigatorContext = createContext( initialContextValue );

package/src/navigator/index.ts

@@ -2,4 +2,5 @@ export { NavigatorProvider } from './navigator-provider';
 export { NavigatorScreen } from './navigator-screen';
 export { NavigatorButton } from './navigator-button';
 export { NavigatorBackButton } from './navigator-back-button';
+export { NavigatorToParentButton } from './navigator-to-parent-button';
 export { default as useNavigator } from './use-navigator';

package/src/navigator/navigator-back-button/README.md

@@ -10,22 +10,6 @@ The `NavigatorBackButton` component can be used to navigate to a screen and shou
 
 Refer to [the `NavigatorProvider` component](/packages/components/src/navigator/navigator-provider/README.md#usage) for a usage example.
 
-## Props
-
-The component accepts the following props:
-
-### `onClick`: `React.MouseEventHandler< HTMLElement >`
-
-The callback called in response to a `click` event.
-
--   Required: No
-
-### `path`: `string`
-
-The path of the screen to navigate to.
-
--   Required: Yes
-
 ### Inherited props
 
-`NavigatorBackButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href`.
+`NavigatorBackButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`.

package/src/navigator/navigator-back-button/hook.ts

@@ -9,26 +9,31 @@ import { useCallback } from '@wordpress/element';
 import { useContextSystem, WordPressComponentProps } from '../../ui/context';
 import Button from '../../button';
 import useNavigator from '../use-navigator';
-import type { NavigatorBackButtonProps } from '../types';
+import type { NavigatorBackButtonHookProps } from '../types';
 
 export function useNavigatorBackButton(
-	props: WordPressComponentProps< NavigatorBackButtonProps, 'button' >
+	props: WordPressComponentProps< NavigatorBackButtonHookProps, 'button' >
 ) {
 	const {
 		onClick,
 		as = Button,
+		goToParent: goToParentProp = false,
 		...otherProps
 	} = useContextSystem( props, 'NavigatorBackButton' );
 
-	const { goBack } = useNavigator();
+	const { goBack, goToParent } = useNavigator();
 	const handleClick: React.MouseEventHandler< HTMLButtonElement > =
 		useCallback(
 			( e ) => {
 				e.preventDefault();
-				goBack();
+				if ( goToParentProp ) {
+					goToParent();
+				} else {
+					goBack();
+				}
 				onClick?.( e );
 			},
-			[ goBack, onClick ]
+			[ goToParentProp, goToParent, goBack, onClick ]
 		);
 
 	return {

package/src/navigator/navigator-button/README.md

@@ -35,4 +35,4 @@ The path of the screen to navigate to. The value of this prop needs to be [a val
 
 ### Inherited props
 
-`NavigatorButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href`.
+`NavigatorButton` also inherits all of the [`Button` props](/packages/components/src/button/README.md#props), except for `href` and `target`.

package/src/navigator/navigator-provider/README.md

@@ -4,7 +4,7 @@
 This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
 </div>
 
-The `NavigatorProvider` component allows rendering nested views/panels/menus (via the [`NavigatorScreen` component](/packages/components/src/navigator/navigator-screen/README.md)) and navigate between these different states (via the [`NavigatorButton`](/packages/components/src/navigator/navigator-button/README.md) and [`NavigatorBackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components or the `useNavigator` hook). The Global Styles sidebar is an example of this.
+The `NavigatorProvider` component allows rendering nested views/panels/menus (via the [`NavigatorScreen` component](/packages/components/src/navigator/navigator-screen/README.md)) and navigate between these different states (via the [`NavigatorButton`](/packages/components/src/navigator/navigator-button/README.md), [`NavigatorToParentButton`](/packages/components/src/navigator/navigator-to-parent-button/README.md) and [`NavigatorBackButton`](/packages/components/src/navigator/navigator-back-button/README.md) components or the `useNavigator` hook). The Global Styles sidebar is an example of this.
 
 ## Usage
 
@@ -13,7 +13,7 @@ import {
   __experimentalNavigatorProvider as NavigatorProvider,
   __experimentalNavigatorScreen as NavigatorScreen,
   __experimentalNavigatorButton as NavigatorButton,
-  __experimentalNavigatorBackButton as NavigatorBackButton,
+  __experimentalNavigatorToParentButton as NavigatorToParentButton,
 } from '@wordpress/components';
 
 const MyNavigation = () => (
@@ -27,13 +27,21 @@ const MyNavigation = () => (
 
     <NavigatorScreen path="/child">
       <p>This is the child screen.</p>
-      <NavigatorBackButton>
+      <NavigatorToParentButton>
         Go back
-      </NavigatorBackButton>
+      </NavigatorToParentButton>
     </NavigatorScreen>
   </NavigatorProvider>
 );
 ```
+**Important note**
+
+Parent/child navigation only works if the path you define are hierarchical, following a URL-like scheme where each path segment is separated by the `/` character.
+For example:
+- `/` is the root of all paths. There should always be a screen with `path="/"`.
+- `/parent/child` is a child of `/parent`.
+- `/parent/child/grand-child` is a child of `/parent/child`.
+- `/parent/:param` is a child of `/parent` as well.
 
 ## Props
 
@@ -58,6 +66,15 @@ The `goTo` function allows navigating to a given path. The second argument can a
 The available options are:
 
 - `focusTargetSelector`: `string`. An optional property used to specify the CSS selector used to restore focus on the matching element when navigating back.
+- `isBack`: `boolean`. An optional property used to specify whether the navigation should be considered as backwards (thus enabling focus restoration when possible, and causing the animation to be backwards too)
+
+### `goToParent`: `() => void;`
+
+The `goToParent` function allows navigating to the parent screen.
+
+Parent/child navigation only works if the path you define are hierarchical (see note above).
+
+When a match is not found, the function will try to recursively navigate the path hierarchy until a matching screen (or the root `/`) are found.
 
 ### `goBack`: `() => void`
 
@@ -70,3 +87,7 @@ The `location` object represent the current location, and has a few properties:
 - `path`: `string`. The path associated to the location.
 - `isBack`: `boolean`. A flag that is `true` when the current location was reached by navigating backwards in the location stack.
 - `isInitial`: `boolean`. A flag that is `true` only for the first (root) location in the location stack.
+
+### `params`: `Record< string, string | string[] >`
+
+The parsed record of parameters from the current location. For example if the current screen path is `/product/:productId` and the location is `/product/123`, then `params` will be `{ productId: '123' }`.