@wordpress/components 23.3.2 → 23.4.0

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

@@ -313,6 +313,7 @@ export default function PaletteEdit( {
 	colors = EMPTY_ARRAY,
 	onChange,
 	paletteLabel,
+	paletteLabelHeadingLevel = 2,
 	emptyMessage,
 	canOnlyChangeValues,
 	canReset,
@@ -347,7 +348,9 @@ export default function PaletteEdit( {
 	return (
 		<PaletteEditStyles>
 			<PaletteHStackHeader>
-				<PaletteHeading>{ paletteLabel }</PaletteHeading>
+				<PaletteHeading level={ paletteLabelHeadingLevel }>
+					{ paletteLabel }
+				</PaletteHeading>
 				<PaletteActionsContainer>
 					{ hasElements && isEditing && (
 						<DoneButton

package/src/panel/README.md

@@ -161,7 +161,7 @@ Props that are passed to the `Button` component in the `PanelBodyTitle` within t
 
 #### PanelRow
 
-The `PanelRow` is a generic container for panel content. Default styles add a top margin and arrange items in a flex row.
+`PanelRow` is a generic container for rows within a `PanelBody`. It is a flex container with a top margin for spacing.
 
 ##### Props
 
@@ -182,7 +182,7 @@ PanelRow accepts a forwarded ref that will be added to the wrapper div. Usage:
 
 #### PanelHeader
 
-This is a simple container for a header component. This is used by the `Panel` component under the hood, so it does not typically need to be used.
+`PanelHeader` renders the header for the `Panel`. This is used by the `Panel` component under the hood, so it does not typically need to be used.
 
 ##### Props
 

package/src/panel/header.tsx

@@ -0,0 +1,20 @@
+/**
+ * Internal dependencies
+ */
+import type { PanelHeaderProps } from './types';
+
+/**
+ * `PanelHeader` renders the header for the `Panel`.
+ * This is used by the `Panel` component under the hood,
+ * so it does not typically need to be used.
+ */
+function PanelHeader( { label, children }: PanelHeaderProps ) {
+	return (
+		<div className="components-panel__header">
+			{ label && <h2>{ label }</h2> }
+			{ children }
+		</div>
+	);
+}
+
+export default PanelHeader;

package/src/panel/index.tsx

@@ -0,0 +1,48 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+
+/**
+ * WordPress dependencies
+ */
+import { forwardRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import PanelHeader from './header';
+import type { PanelProps } from './types';
+
+function UnforwardedPanel(
+	{ header, className, children }: PanelProps,
+	ref: React.ForwardedRef< HTMLDivElement >
+) {
+	const classNames = classnames( className, 'components-panel' );
+	return (
+		<div className={ classNames } ref={ ref }>
+			{ header && <PanelHeader label={ header } /> }
+			{ children }
+		</div>
+	);
+}
+
+/**
+ * `Panel` expands and collapses multiple sections of content.
+ *
+ * ```jsx
+ * import { Panel, PanelBody, PanelRow } from '@wordpress/components';
+ * import { more } from '@wordpress/icons';
+ *
+ * const MyPanel = () => (
+ * 	<Panel header="My Panel">
+ * 		<PanelBody title="My Block Settings" icon={ more } initialOpen={ true }>
+ * 			<PanelRow>My Panel Inputs and Labels</PanelRow>
+ * 		</PanelBody>
+ * 	</Panel>
+ * );
+ * ```
+ */
+export const Panel = forwardRef( UnforwardedPanel );
+
+export default Panel;

package/src/panel/row.tsx

@@ -0,0 +1,37 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+
+/**
+ * WordPress dependencies
+ */
+import { forwardRef } from '@wordpress/element';
+import type { ForwardedRef } from 'react';
+
+/**
+ * Internal dependencies
+ */
+import type { PanelRowProps } from './types';
+
+function UnforwardedPanelRow(
+	{ className, children }: PanelRowProps,
+	ref: ForwardedRef< HTMLDivElement >
+) {
+	return (
+		<div
+			className={ classnames( 'components-panel__row', className ) }
+			ref={ ref }
+		>
+			{ children }
+		</div>
+	);
+}
+
+/**
+ * `PanelRow` is a generic container for rows within a `PanelBody`.
+ * It is a flex container with a top margin for spacing.
+ */
+export const PanelRow = forwardRef( UnforwardedPanelRow );
+
+export default PanelRow;

package/src/panel/stories/index.js

@@ -4,6 +4,7 @@
 import Panel from '../';
 import PanelRow from '../row';
 import PanelBody from '../body';
+import InputControl from '../../input-control';
 
 /**
  * WordPress dependencies
@@ -56,6 +57,27 @@ Default.args = {
 	),
 };
 
+/**
+ * `PanelRow` is a generic container for rows within a `PanelBody`.
+ * It is a flex container with a top margin for spacing.
+ */
+export const _PanelRow = Template.bind( {} );
+_PanelRow.args = {
+	children: (
+		<PanelBody title="My Profile">
+			<PanelRow>
+				<InputControl label="First name" />
+				<InputControl label="Last name" />
+			</PanelRow>
+			<PanelRow>
+				<div style={ { flex: 1 } }>
+					<InputControl label="Email" />
+				</div>
+			</PanelRow>
+		</PanelBody>
+	),
+};
+
 export const DisabledSection = Template.bind( {} );
 DisabledSection.args = {
 	...Default.args,

package/src/panel/test/{header.js → header.tsx}

@@ -6,7 +6,7 @@ import { render, screen } from '@testing-library/react';
 /**
  * Internal dependencies
  */
-import PanelHeader from '../header.js';
+import PanelHeader from '../header';
 
 describe( 'PanelHeader', () => {
 	describe( 'basic rendering', () => {

package/src/panel/test/{index.js → index.tsx}

@@ -6,18 +6,18 @@ import { render, screen } from '@testing-library/react';
 /**
  * Internal dependencies
  */
-import Panel from '../';
+import Panel from '..';
 
 describe( 'Panel', () => {
 	describe( 'basic rendering', () => {
 		it( 'should render an empty div without any provided props', () => {
-			const { container } = render( <Panel /> );
+			const { container } = render( <Panel children={ null } /> );
 
 			expect( container ).toMatchSnapshot();
 		} );
 
 		it( 'should render a heading when provided text in the header prop', () => {
-			render( <Panel header="Header Label" /> );
+			render( <Panel header="Header Label" children={ null } /> );
 
 			const heading = screen.getByRole( 'heading' );
 			expect( heading ).toBeVisible();
@@ -25,7 +25,9 @@ describe( 'Panel', () => {
 		} );
 
 		it( 'should render an additional className', () => {
-			const { container } = render( <Panel className="the-panel" /> );
+			const { container } = render(
+				<Panel className="the-panel" children={ null } />
+			);
 
 			expect( container ).toMatchSnapshot();
 		} );

package/src/panel/test/{row.js → row.tsx}

@@ -10,13 +10,15 @@ import PanelRow from '../row';
 
 describe( 'PanelRow', () => {
 	it( 'should render with the default class name', () => {
-		const { container } = render( <PanelRow /> );
+		const { container } = render( <PanelRow children={ null } /> );
 
 		expect( container ).toMatchSnapshot();
 	} );
 
 	it( 'should render with the custom class name', () => {
-		const { container } = render( <PanelRow className="custom" /> );
+		const { container } = render(
+			<PanelRow className="custom" children={ null } />
+		);
 
 		expect( container ).toMatchSnapshot();
 	} );

package/src/panel/types.ts

@@ -0,0 +1,38 @@
+export type PanelProps = {
+	/**
+	 * The text that will be rendered as the title of the panel.
+	 * Text will be rendered inside an `<h2>` tag.
+	 */
+	header?: PanelHeaderProps[ 'label' ];
+	/**
+	 * The CSS class to apply to the wrapper element.
+	 */
+	className?: string;
+	/**
+	 * The content to display within the panel.
+	 */
+	children: React.ReactNode;
+};
+
+export type PanelHeaderProps = {
+	/**
+	 * The text that will be rendered as the title of the panel.
+	 * Will be rendered in an `<h2>` tag.
+	 */
+	label?: string;
+	/**
+	 * The content to display within the panel header.
+	 */
+	children?: React.ReactNode;
+};
+
+export type PanelRowProps = {
+	/**
+	 * The CSS class to apply to the wrapper element.
+	 */
+	className?: string;
+	/**
+	 * The content to display within the panel row.
+	 */
+	children: React.ReactNode;
+};

package/src/popover/README.md

@@ -196,10 +196,13 @@ A callback invoked when the popover should be closed.
 
 -   Required: No
 
-### `placement`: `'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end'`
+### `placement`: `'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'overlay'`
 
 Used to specify the popover's position with respect to its anchor.
 
+`overlay` is a special case that places the popover over the reference element.
+Please note that other placement related props may not behave as excepted.
+
 -   Required: No
 -   Default: `"bottom-start"`