@wordpress/components 19.15.0 → 20.0.0

package/src/popover/stories/index.js

@@ -1,121 +1,190 @@
-/**
- * External dependencies
- */
-import { boolean, select, text } from '@storybook/addon-knobs';
-
 /**
  * WordPress dependencies
  */
-import { useState } from '@wordpress/element';
+import { useState, useRef } from '@wordpress/element';
+import { __unstableIframe as Iframe } from '@wordpress/block-editor';
 
 /**
  * Internal dependencies
  */
-import { DraggableWrapper } from './_utils';
-import Popover from '../';
 import Button from '../../button';
+import { Provider as SlotFillProvider } from '../../slot-fill';
+import Popover from '../';
+
+// Format: "[yAxis] [xAxis]"
+// Valid yAxis values: 'top', 'middle', 'bottom'
+// Valid xAxis values: 'left', 'center', 'right'
+const AVAILABLE_POSITIONS = [
+	'top left',
+	'top center',
+	'top right',
+	'middle left',
+	'middle center',
+	'middle right',
+	'bottom left',
+	'bottom center',
+	'bottom right',
+];
+
+// Follows floating UI's conventions
+// See https://floating-ui.com/docs/computePosition#placement
+const AVAILABLE_PLACEMENTS = [
+	'top',
+	'top-start',
+	'top-end',
+	'right',
+	'right-start',
+	'right-end',
+	'bottom',
+	'bottom-start',
+	'bottom-end',
+	'left',
+	'left-start',
+	'left-end',
+];
 
 export default {
 	title: 'Components/Popover',
 	component: Popover,
-	parameters: {
-		knobs: { disable: false },
-	},
-};
-
-export const _default = () => {
-	const show = boolean( 'Example: Show', true );
-	const children = text( 'children', 'Popover Content' );
-	const animate = boolean( 'animate', false );
-	const focusOnMount = select(
-		'focusOnMount',
-		{
-			firstElement: 'firstElement',
-			container: 'container',
+	argTypes: {
+		anchorRef: { control: { type: null } },
+		anchorRect: { control: { type: null } },
+		animate: { control: { type: 'boolean' } },
+		children: { control: { type: null } },
+		className: { control: { type: 'text' } },
+		expandOnMobile: { control: { type: 'boolean' } },
+		focusOnMount: {
+			control: { type: 'select' },
+			options: [ 'firstElement', 'container', false ],
 		},
-		'firstElement'
-	);
-	const noArrow = boolean( 'noArrow', false );
-	const isAlternate = boolean( 'isAlternate', false );
-
-	const props = {
-		animate,
-		children,
-		focusOnMount,
-		noArrow,
-		isAlternate,
-	};
-
-	if ( ! show ) {
-		return null;
-	}
-
-	return <Popover { ...props } />;
+		getAnchorRect: { control: { type: null } },
+		headerTitle: { control: { type: 'text' } },
+		isAlternate: { control: { type: 'boolean' } },
+		noArrow: { control: { type: 'boolean' } },
+		onClose: { control: { type: null } },
+		offset: { control: { type: 'number' } },
+		onFocusOutside: { control: { type: null } },
+		placement: {
+			control: { type: 'select' },
+			options: AVAILABLE_PLACEMENTS,
+		},
+		position: {
+			control: { type: 'select' },
+			options: AVAILABLE_POSITIONS,
+		},
+		__unstableSlotName: { control: { type: null } },
+		__unstableObserveElement: { control: { type: null } },
+		__unstableForcePosition: { control: { type: 'boolean' } },
+		__unstableShift: { control: { type: 'boolean' } },
+	},
 };
 
-const DragExample = ( props ) => {
-	const { label, content, ...restProps } = props;
+const PopoverWithAnchor = ( args ) => {
+	const anchorRef = useRef( null );
 
 	return (
-		<div>
-			<div style={ { position: 'absolute', color: '#555' } }>
-				<p>Move the gray box around.</p>
-				<p>
-					The{ ' ' }
-					<strong style={ { background: 'pink' } }>
-						pink bordered
-					</strong>{ ' ' }
-					element is a parent.
-				</p>
-				<p>
-					The{ ' ' }
-					<strong style={ { background: 'cyan' } }>
-						cyan bordered
-					</strong>{ ' ' }
-					element is a sibling to <strong>Popover</strong>.
-				</p>
-				<p>
-					<strong>Popover</strong> aligns to the content within
-					parent.
-				</p>
-			</div>
-			<div
-				style={ {
-					height: '100vh',
-					width: '100%',
-					display: 'flex',
-					alignItems: 'center',
-					justifyContent: 'center',
-				} }
+		<div
+			style={ {
+				height: '200px',
+				display: 'flex',
+				justifyContent: 'center',
+				alignItems: 'center',
+			} }
+		>
+			<p
+				style={ { padding: '8px', background: 'salmon' } }
+				ref={ anchorRef }
 			>
-				<DraggableWrapper
-					style={ {
-						background: '#ddd',
-						border: '2px solid pink',
-						borderRadius: 4,
-						padding: 10,
-						userSelect: 'none',
-					} }
-				>
-					<div style={ { border: '2px solid cyan' } }>{ label }</div>
-					<Popover { ...restProps }>{ content }</Popover>
-				</DraggableWrapper>
-			</div>
+				Popover&apos;s anchor
+			</p>
+			<Popover { ...args } anchorRef={ anchorRef } />
 		</div>
 	);
 };
 
-export const positioning = () => {
-	const label = text( 'Example: Label', 'Drag Me!' );
-	const content = text( 'Example: Content', 'Popover' );
-	const noArrow = boolean( 'noArrow', false );
+export const Default = ( args ) => {
+	const [ isVisible, setIsVisible ] = useState( false );
+	const toggleVisible = () => {
+		setIsVisible( ( state ) => ! state );
+	};
 
 	return (
-		<DragExample label={ label } content={ content } noArrow={ noArrow } />
+		<div
+			style={ {
+				minWidth: '600px',
+				minHeight: '600px',
+				display: 'flex',
+				alignItems: 'center',
+				justifyContent: 'center',
+			} }
+		>
+			<Button variant="secondary" onClick={ toggleVisible }>
+				Toggle Popover
+				{ isVisible && <Popover { ...args } /> }
+			</Button>
+		</div>
 	);
 };
+Default.args = {
+	children: (
+		<div style={ { width: '280px', whiteSpace: 'normal' } }>
+			Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+			eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
+			ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
+			aliquip ex ea commodo consequat.
+		</div>
+	),
+};
+
+/**
+ * Resize / scroll the viewport to test the behavior of the popovers when they
+ * reach the viewport boundaries.
+ */
+export const AllPlacements = ( { children, ...args } ) => (
+	<div
+		style={ {
+			minWidth: '600px',
+			marginLeft: 'auto',
+			marginRight: 'auto',
+		} }
+	>
+		<h2>
+			Resize / scroll the viewport to test the behavior of the popovers
+			when they reach the viewport boundaries.
+		</h2>
+		<div>
+			{ AVAILABLE_PLACEMENTS.map( ( p ) => (
+				<PopoverWithAnchor key={ p } placement={ p } { ...args }>
+					{ children }
+					<div>
+						<small>(placement: { p })</small>
+					</div>
+				</PopoverWithAnchor>
+			) ) }
+		</div>
+	</div>
+);
+// Excluding placement and position since they all possible values
+// are passed directly in code.
+AllPlacements.parameters = {
+	controls: {
+		exclude: [ 'placement', 'position' ],
+	},
+};
+AllPlacements.args = {
+	...Default.args,
+	children: (
+		<div style={ { width: '280px', whiteSpace: 'normal' } }>
+			Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+			eiusmod tempor incididunt ut labore et dolore magna aliqua.
+		</div>
+	),
+	noArrow: false,
+	offset: 10,
+	__unstableForcePosition: true,
+};
 
-function DynamicHeightPopover() {
+export const DynamicHeight = ( { children, ...args } ) => {
 	const [ height, setHeight ] = useState( 200 );
 	const increase = () => setHeight( height + 100 );
 	const decrease = () => setHeight( height - 100 );
@@ -144,7 +213,7 @@ function DynamicHeightPopover() {
 			</p>
 
 			<div>
-				<Popover>
+				<Popover { ...args }>
 					<div
 						style={ {
 							height,
@@ -152,14 +221,62 @@ function DynamicHeightPopover() {
 							padding: '20px',
 						} }
 					>
-						Content with dynamic height
+						{ children }
 					</div>
 				</Popover>
 			</div>
 		</div>
 	);
-}
+};
+DynamicHeight.args = {
+	...Default.args,
+	children: 'Content with dynamic height',
+};
+
+export const WithSlotOutsideIframe = ( args ) => {
+	const anchorRef = useRef( null );
+	const slotName = 'popover-with-slot-outside-iframe';
 
-export const dynamicHeight = () => {
-	return <DynamicHeightPopover />;
+	return (
+		<SlotFillProvider>
+			<div>
+				<Popover.Slot name={ slotName } />
+				<Iframe
+					style={ {
+						width: '100%',
+						height: '400px',
+					} }
+				>
+					<div
+						style={ {
+							height: '200vh',
+							paddingTop: '10vh',
+						} }
+					>
+						<p
+							style={ {
+								padding: '8px',
+								background: 'salmon',
+								maxWidth: '200px',
+								marginTop: '100px',
+								marginLeft: 'auto',
+								marginRight: 'auto',
+							} }
+							ref={ anchorRef }
+						>
+							Popover&apos;s anchor
+						</p>
+						<Popover
+							{ ...args }
+							__unstableSlotName={ slotName }
+							anchorRef={ anchorRef }
+						/>
+					</div>
+				</Iframe>
+			</div>
+		</SlotFillProvider>
+	);
+};
+WithSlotOutsideIframe.args = {
+	...Default.args,
 };

package/src/popover/style.scss

@@ -1,3 +1,5 @@
+$arrow-triangle-base-size: 14px;
+
 .components-popover {
 	z-index: z-index(".components-popover");
 
@@ -31,7 +33,7 @@
 		position: static;
 		height: calc(100% - #{ $panel-header-height });
 		overflow-y: visible;
-		min-width: auto;
+		width: auto;
 		border: none;
 		outline: none;
 		border-top: $border-width solid $gray-900;
@@ -60,12 +62,64 @@
 
 .components-popover__arrow {
 	position: absolute;
-	background: $gray-400;
-	width: 8px;
-	height: 8px;
-	transform: rotate(45deg);
-	z-index: -1;
+	width: $arrow-triangle-base-size;
+	height: $arrow-triangle-base-size;
+	pointer-events: none;
+	display: flex;
+
+	// Thin line that helps to make sure that the underlying
+	// popover__content's outline is fully overlapped by the
+	// arrow
+	&::before {
+		content: "";
+		position: absolute;
+		top: -1px;
+		left: 1px;
+		height: 2px;
+		right: 1px;
+		background-color: $white;
+	}
+
+	// Position and rotate the arrow depending on the popover's placement.
+	// The `!important' is necessary to override the inline styles.
+	&.is-top {
+		bottom: -1 * $arrow-triangle-base-size !important;
+		transform: rotate(0);
+	}
+	&.is-right {
+		/*rtl:begin:ignore*/
+		left: -1 * $arrow-triangle-base-size !important;
+		transform: rotate(90deg);
+	}
+	&.is-bottom {
+		top: -1 * $arrow-triangle-base-size !important;
+		transform: rotate(180deg);
+	}
+	&.is-left {
+		/*rtl:begin:ignore*/
+		right: -1 * $arrow-triangle-base-size !important;
+		transform: rotate(-90deg);
+		/*rtl:end:ignore*/
+	}
+}
+
+.components-popover__triangle {
+	display: block;
+	flex: 1;
+}
+
+.components-popover__triangle-bg {
+	// Fill color is the same as the .components-popover__content's background
+	fill: $white;
+}
+
+.components-popover__triangle-border {
+	// Stroke colors are the same as the .components-popover__content's outline
+	fill: transparent;
+	stroke-width: $border-width;
+	stroke: $gray-400;
+
 	.is-alternate & {
-		background: $gray-900;
+		stroke: $gray-900;
 	}
 }

package/src/popover/test/__snapshots__/index.js.snap

@@ -1,11 +1,11 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
-exports[`Popover should pass additional props to portaled element 1`] = `
+exports[`Popover Component should pass additional props to portaled element 1`] = `
 <span>
   <div
-    class="components-popover components-animate__appear is-from-left is-from-top"
+    class="components-popover"
     role="tooltip"
-    style="position: absolute;"
+    style="position: absolute; opacity: 0; transform: translateY(-2em) scale(0) translateZ(0); transform-origin: 0% 0% 0;"
     tabindex="-1"
   >
     <div
@@ -17,11 +17,11 @@ exports[`Popover should pass additional props to portaled element 1`] = `
 </span>
 `;
 
-exports[`Popover should render content 1`] = `
+exports[`Popover Component should render content 1`] = `
 <span>
   <div
-    class="components-popover components-animate__appear is-from-left is-from-top"
-    style="position: absolute;"
+    class="components-popover"
+    style="position: absolute; opacity: 0; transform: translateY(-2em) scale(0) translateZ(0); transform-origin: 0% 0% 0;"
     tabindex="-1"
   >
     <div

package/src/popover/test/index.js

@@ -1,47 +1,162 @@
 /**
  * External dependencies
  */
-import { act, render } from '@testing-library/react';
+import { act, render, screen } from '@testing-library/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useRef } from '@wordpress/element';
 
 /**
  * Internal dependencies
  */
 import Popover from '../';
 
+import { positionToPlacement, placementToMotionAnimationProps } from '../utils';
+
 describe( 'Popover', () => {
-	afterEach( () => {
-		if ( document.activeElement ) {
-			document.activeElement.blur();
-		}
-	} );
+	describe( 'Component', () => {
+		afterEach( () => {
+			if ( document.activeElement ) {
+				document.activeElement.blur();
+			}
+		} );
+
+		it( 'should allow focus-on-open behavior to be disabled', () => {
+			expect( document.activeElement ).toBe( document.body );
 
-	it( 'should allow focus-on-open behavior to be disabled', () => {
-		expect( document.activeElement ).toBe( document.body );
+			act( () => {
+				render( <Popover focusOnMount={ false } /> );
 
-		act( () => {
-			render( <Popover focusOnMount={ false } /> );
+				jest.advanceTimersByTime( 1 );
+			} );
 
-			jest.advanceTimersByTime( 1 );
+			expect( document.activeElement ).toBe( document.body );
 		} );
 
-		expect( document.activeElement ).toBe( document.body );
-	} );
+		it( 'should render content', () => {
+			let result;
+			act( () => {
+				result = render( <Popover>Hello</Popover> );
+			} );
+
+			expect(
+				result.container.querySelector( 'span' )
+			).toMatchSnapshot();
+		} );
+
+		it( 'should pass additional props to portaled element', () => {
+			let result;
+			act( () => {
+				result = render( <Popover role="tooltip">Hello</Popover> );
+			} );
 
-	it( 'should render content', () => {
-		let result;
-		act( () => {
-			result = render( <Popover>Hello</Popover> );
+			expect(
+				result.container.querySelector( 'span' )
+			).toMatchSnapshot();
 		} );
 
-		expect( result.container.querySelector( 'span' ) ).toMatchSnapshot();
+		it( 'should render correctly when anchorRef is provided', () => {
+			const PopoverWithAnchor = ( args ) => {
+				const anchorRef = useRef( null );
+
+				return (
+					<div>
+						<p ref={ anchorRef }>Anchor</p>
+						<Popover { ...args } anchorRef={ anchorRef } />
+					</div>
+				);
+			};
+
+			render( <PopoverWithAnchor>Popover content</PopoverWithAnchor> );
+
+			expect( screen.getByText( 'Popover content' ) ).toBeInTheDocument();
+		} );
 	} );
 
-	it( 'should pass additional props to portaled element', () => {
-		let result;
-		act( () => {
-			result = render( <Popover role="tooltip">Hello</Popover> );
+	describe( 'positionToPlacement', () => {
+		it.each( [
+			[ 'top left', 'top-end' ],
+			[ 'top center', 'top' ],
+			[ 'top right', 'top-start' ],
+			[ 'middle left', 'left' ],
+			[ 'middle center', 'center' ],
+			[ 'middle right', 'right' ],
+			[ 'bottom left', 'bottom-end' ],
+			[ 'bottom center', 'bottom' ],
+			[ 'bottom right', 'bottom-start' ],
+		] )( 'converts `%s` to `%s`', ( inputPosition, expectedPlacement ) => {
+			expect( positionToPlacement( inputPosition ) ).toEqual(
+				expectedPlacement
+			);
 		} );
+	} );
 
-		expect( result.container.querySelector( 'span' ) ).toMatchSnapshot();
+	describe( 'placementToMotionAnimationProps', () => {
+		describe( 'animation origin', () => {
+			it.each( [
+				[ 'top', 0.5, 1 ],
+				[ 'top-start', 0, 1 ],
+				[ 'top-end', 1, 1 ],
+				[ 'right', 0, 0.5 ],
+				[ 'right-start', 0, 0 ],
+				[ 'right-end', 0, 1 ],
+				[ 'bottom', 0.5, 0 ],
+				[ 'bottom-start', 0, 0 ],
+				[ 'bottom-end', 1, 0 ],
+				[ 'left', 1, 0.5 ],
+				[ 'left-start', 1, 0 ],
+				[ 'left-end', 1, 1 ],
+			] )(
+				'for the `%s` placement computes an animation origin of (%d, %d)',
+				( inputPlacement, expectedOriginX, expectedOriginY ) => {
+					expect(
+						placementToMotionAnimationProps( inputPlacement )
+					).toEqual(
+						expect.objectContaining( {
+							style: expect.objectContaining( {
+								originX: expectedOriginX,
+								originY: expectedOriginY,
+							} ),
+						} )
+					);
+				}
+			);
+		} );
+		describe( 'initial translation', () => {
+			it.each( [
+				[ 'top', 'translateY', '2em' ],
+				[ 'top-start', 'translateY', '2em' ],
+				[ 'top-end', 'translateY', '2em' ],
+				[ 'right', 'translateX', '-2em' ],
+				[ 'right-start', 'translateX', '-2em' ],
+				[ 'right-end', 'translateX', '-2em' ],
+				[ 'bottom', 'translateY', '-2em' ],
+				[ 'bottom-start', 'translateY', '-2em' ],
+				[ 'bottom-end', 'translateY', '-2em' ],
+				[ 'left', 'translateX', '2em' ],
+				[ 'left-start', 'translateX', '2em' ],
+				[ 'left-end', 'translateX', '2em' ],
+			] )(
+				'for the `%s` placement computes an initial `%s` of `%s',
+				(
+					inputPlacement,
+					expectedTranslationProp,
+					expectedTranslationValue
+				) => {
+					expect(
+						placementToMotionAnimationProps( inputPlacement )
+					).toEqual(
+						expect.objectContaining( {
+							initial: expect.objectContaining( {
+								[ expectedTranslationProp ]:
+									expectedTranslationValue,
+							} ),
+						} )
+					);
+				}
+			);
+		} );
 	} );
 } );