@wordpress/components 23.3.5 → 23.5.0

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"`
 

package/src/popover/index.tsx

@@ -43,6 +43,7 @@ import {
 import { close } from '@wordpress/icons';
 import deprecated from '@wordpress/deprecated';
 import { Path, SVG } from '@wordpress/primitives';
+import { getScrollContainer } from '@wordpress/dom';
 
 /**
  * Internal dependencies
@@ -52,6 +53,7 @@ import ScrollLock from '../scroll-lock';
 import { Slot, Fill, useSlot } from '../slot-fill';
 import {
 	getFrameOffset,
+	getFrameScale,
 	positionToPlacement,
 	placementToMotionAnimationProps,
 	getReferenceOwnerDocument,
@@ -65,6 +67,7 @@ import type {
 	PopoverAnchorRefTopBottom,
 } from './types';
 import { limitShift as customLimitShift } from './limit-shift';
+import { overlayMiddlewares } from './overlay-middlewares';
 
 /**
  * Name of slot in which popover should fill.
@@ -268,6 +271,7 @@ const UnforwardedPopover = (
 	const frameOffsetRef = useRef( getFrameOffset( referenceOwnerDocument ) );
 
 	const middleware = [
+		...( placementProp === 'overlay' ? overlayMiddlewares() : [] ),
 		// Custom middleware which adjusts the popover's position by taking into
 		// account the offset of the anchor's iframe (if any) compared to the page.
 		{
@@ -361,7 +365,10 @@ const UnforwardedPopover = (
 		placement: computedPlacement,
 		middlewareData: { arrow: arrowData },
 	} = useFloating( {
-		placement: normalizedPlacementFromProps,
+		placement:
+			normalizedPlacementFromProps === 'overlay'
+				? undefined
+				: normalizedPlacementFromProps,
 		middleware,
 		whileElementsMounted: ( referenceParam, floatingParam, updateParam ) =>
 			autoUpdate( referenceParam, floatingParam, updateParam, {
@@ -399,12 +406,14 @@ const UnforwardedPopover = (
 			fallbackReferenceElement,
 			fallbackDocument: document,
 		} );
+		const scale = getFrameScale( resultingReferenceOwnerDoc );
 		const resultingReferenceElement = getReferenceElement( {
 			anchor,
 			anchorRef,
 			anchorRect,
 			getAnchorRect,
 			fallbackReferenceElement,
+			scale,
 		} );
 
 		referenceCallbackRef( resultingReferenceElement );
@@ -441,17 +450,24 @@ const UnforwardedPopover = (
 		}
 
 		const { defaultView } = referenceOwnerDocument;
+		const { frameElement } = defaultView;
+
+		const scrollContainer = frameElement
+			? getScrollContainer( frameElement )
+			: null;
 
 		const updateFrameOffset = () => {
 			frameOffsetRef.current = getFrameOffset( referenceOwnerDocument );
 			update();
 		};
 		defaultView.addEventListener( 'resize', updateFrameOffset );
+		scrollContainer?.addEventListener( 'scroll', updateFrameOffset );
 
 		updateFrameOffset();
 
 		return () => {
 			defaultView.removeEventListener( 'resize', updateFrameOffset );
+			scrollContainer?.removeEventListener( 'scroll', updateFrameOffset );
 		};
 	}, [ referenceOwnerDocument, update, refs.floating ] );
 

package/src/popover/overlay-middlewares.tsx

@@ -0,0 +1,29 @@
+/**
+ * External dependencies
+ */
+import { size, MiddlewareArguments } from '@floating-ui/react-dom';
+
+export function overlayMiddlewares() {
+	return [
+		{
+			name: 'overlay',
+			fn( { rects }: MiddlewareArguments ) {
+				return rects.reference;
+			},
+		},
+		size( {
+			apply( { rects, elements } ) {
+				const { firstElementChild } = elements.floating ?? {};
+
+				// Only HTMLElement instances have the `style` property.
+				if ( ! ( firstElementChild instanceof HTMLElement ) ) return;
+
+				// Reduce the height of the popover to the available space.
+				Object.assign( firstElementChild.style, {
+					width: `${ rects.reference.width }px`,
+					height: `${ rects.reference.height }px`,
+				} );
+			},
+		} ),
+	];
+}

package/src/popover/stories/index.tsx

@@ -31,6 +31,7 @@ const AVAILABLE_PLACEMENTS: PopoverProps[ 'placement' ][] = [
 	'left',
 	'left-start',
 	'left-end',
+	'overlay',
 ];
 
 const meta: ComponentMeta< typeof Popover > = {
@@ -170,7 +171,12 @@ export const AllPlacements: ComponentStory< typeof Popover > = ( {
 		</h2>
 		<div>
 			{ AVAILABLE_PLACEMENTS.map( ( p ) => (
-				<PopoverWithAnchor key={ p } placement={ p } { ...args }>
+				<PopoverWithAnchor
+					key={ p }
+					placement={ p }
+					{ ...args }
+					resize={ p === 'overlay' ? true : args.resize }
+				>
 					{ children }
 					<div>
 						<small>(placement: { p })</small>

package/src/popover/test/index.tsx

@@ -1,8 +1,8 @@
 /**
  * External dependencies
  */
-import { act, render, screen } from '@testing-library/react';
-import type { CSSProperties, ReactElement } from 'react';
+import { render, screen, waitFor } from '@testing-library/react';
+import type { CSSProperties } from 'react';
 
 /**
  * WordPress dependencies
@@ -91,25 +91,21 @@ const ALL_POSITIONS_TO_EXPECTED_PLACEMENTS: PositionToPlacementTuple[] = [
 
 describe( 'Popover', () => {
 	describe( 'Component', () => {
-		// Render UI and then wait for the `floating-ui` effects inside `Popover` to finish running
-		// See also: https://floating-ui.com/docs/react-dom#testing
-		async function renderAsync( ui: ReactElement ) {
-			const view = render( ui );
-			await act( () => Promise.resolve() );
-			return view;
-		}
-
 		describe( 'basic behavior', () => {
 			it( 'should render content', async () => {
-				await renderAsync( <Popover>Hello</Popover> );
+				render( <Popover>Hello</Popover> );
 
-				expect( screen.getByText( 'Hello' ) ).toBeInTheDocument();
+				await waitFor( () =>
+					expect( screen.getByText( 'Hello' ) ).toBeVisible()
+				);
 			} );
 
 			it( 'should forward additional props to portaled element', async () => {
-				await renderAsync( <Popover role="tooltip">Hello</Popover> );
+				render( <Popover role="tooltip">Hello</Popover> );
 
-				expect( screen.getByRole( 'tooltip' ) ).toBeInTheDocument();
+				await waitFor( () =>
+					expect( screen.getByRole( 'tooltip' ) ).toBeVisible()
+				);
 			} );
 		} );
 
@@ -129,32 +125,44 @@ describe( 'Popover', () => {
 					);
 				};
 
-				await renderAsync(
+				render(
 					<PopoverWithAnchor>Popover content</PopoverWithAnchor>
 				);
 
-				expect(
-					screen.getByText( 'Popover content' )
-				).toBeInTheDocument();
+				await waitFor( () =>
+					expect(
+						screen.getByText( 'Popover content' )
+					).toBeVisible()
+				);
 			} );
 		} );
 
 		describe( 'focus behavior', () => {
 			it( 'should focus the popover by default when opened', async () => {
-				await renderAsync(
+				render(
 					<Popover data-testid="popover-element">
 						Popover content
 					</Popover>
 				);
 
-				expect( screen.getByTestId( 'popover-element' ) ).toHaveFocus();
+				const popover = screen.getByTestId( 'popover-element' );
+
+				await waitFor( () => expect( popover ).toBeVisible() );
+
+				expect( popover ).toHaveFocus();
 			} );
 
 			it( 'should allow focus-on-open behavior to be disabled', async () => {
-				await renderAsync(
+				render(
 					<Popover focusOnMount={ false }>Popover content</Popover>
 				);
 
+				await waitFor( () =>
+					expect(
+						screen.getByText( 'Popover content' )
+					).toBeVisible()
+				);
+
 				expect( document.body ).toHaveFocus();
 			} );
 		} );

package/src/popover/types.ts

@@ -12,8 +12,10 @@ type DomRectWithOwnerDocument = DOMRect & {
 	ownerDocument?: Document;
 };
 
+type PopoverPlacement = Placement | 'overlay';
+
 export type AnimatedWrapperProps = {
-	placement: Placement;
+	placement: PopoverPlacement;
 	shouldAnimate?: boolean;
 };
 
@@ -111,7 +113,7 @@ export type PopoverProps = {
 	 *
 	 * @default 'bottom-start'
 	 */
-	placement?: Placement;
+	placement?: PopoverPlacement;
 	/**
 	 * Legacy way to specify the popover's position with respect to its anchor.
 	 * _Note: this prop is deprecated. Use the `placement` prop instead._