@wordpress/components 22.1.0 → 23.0.0

package/src/resizable-box/style.scss

@@ -54,6 +54,7 @@ $resize-handler-container-size: $resize-handler-size + ($grid-unit-05 * 2); // M
 	right: calc(50% - 1px);
 	transition: transform 0.1s ease-in;
 	@include reduce-motion("transition");
+	will-change: transform;
 	opacity: 0;
 }
 

package/src/sandbox/test/index.js

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import { fireEvent, render, screen } from '@testing-library/react';
+import { fireEvent, render, screen, within } from '@testing-library/react';
 
 /**
  * WordPress dependencies
@@ -16,15 +16,15 @@ import Sandbox from '../';
 describe( 'Sandbox', () => {
 	const TestWrapper = () => {
 		const [ html, setHtml ] = useState(
-			// MuatationObserver implementation from JSDom does not work as intended
+			// MutationObserver implementation from JSDom does not work as intended
 			// with iframes so we need to ignore it for the time being.
 			'<script type="text/javascript">window.MutationObserver = null;</script>' +
-				'<iframe class="mock-iframe" src="https://super.embed"></iframe>'
+				'<iframe title="Mock Iframe" src="https://super.embed"></iframe>'
 		);
 
 		const updateHtml = () => {
 			setHtml(
-				'<iframe class="mock-iframe" src="https://another.super.embed"></iframe>'
+				'<iframe title="Mock Iframe" src="https://another.super.embed"></iframe>'
 			);
 		};
 
@@ -33,18 +33,19 @@ describe( 'Sandbox', () => {
 				<button onClick={ updateHtml } className="mock-button">
 					Mock Button
 				</button>
-				<Sandbox html={ html } />
+				<Sandbox html={ html } title="Sandbox Title" />
 			</div>
 		);
 	};
 
 	it( 'should rerender with new emdeded content if html prop changes', () => {
-		const { container } = render( <TestWrapper /> );
+		render( <TestWrapper /> );
 
-		const iframe = container.querySelector( '.components-sandbox' );
+		const iframe = screen.getByTitle( 'Sandbox Title' );
 
-		let sandboxedIframe =
-			iframe.contentWindow.document.body.querySelector( '.mock-iframe' );
+		let sandboxedIframe = within(
+			iframe.contentWindow.document.body
+		).getByTitle( 'Mock Iframe' );
 
 		expect( sandboxedIframe ).toHaveAttribute(
 			'src',
@@ -53,8 +54,9 @@ describe( 'Sandbox', () => {
 
 		fireEvent.click( screen.getByRole( 'button' ) );
 
-		sandboxedIframe =
-			iframe.contentWindow.document.body.querySelector( '.mock-iframe' );
+		sandboxedIframe = within(
+			iframe.contentWindow.document.body
+		).getByTitle( 'Mock Iframe' );
 
 		expect( sandboxedIframe ).toHaveAttribute(
 			'src',

package/src/search-control/style.scss

@@ -10,6 +10,10 @@
 		width: 100%;
 		height: $grid-unit-60;
 
+		// Unset inherited values.
+		margin-left: 0;
+		margin-right: 0;
+
 		/* Fonts smaller than 16px causes mobile safari to zoom. */
 		font-size: $mobile-text-min-font-size;
 		@include break-small {

package/src/snackbar/README.md

@@ -36,17 +36,72 @@ const MySnackbarNotice = () => (
 );
 ```
 
-#### Props
+### Props
 
 The following props are used to control the display of the component.
 
--   `children`: (string) The displayed message of a notice. Also used as the spoken message for assistive technology, unless `spokenMessage` is provided as an alternative message.
--   `spokenMessage`: (string) Used to provide a custom spoken message in place of the `children` default.
--   `politeness`: (string) A politeness level for the notice's spoken message. Should be provided as one of the valid options for [an `aria-live` attribute value](https://www.w3.org/TR/wai-aria-1.1/#aria-live). Defaults to `"polite"`. Note that this value should be considered a suggestion; assistive technologies may override it based on internal heuristics.
-    -   A value of `'assertive'` is to be used for important, and usually time-sensitive, information. It will interrupt anything else the screen reader is announcing in that moment.
-    -   A value of `'polite'` is to be used for advisory information. It should not interrupt what the screen reader is announcing in that moment (the "speech queue") or interrupt the current task.
--   `onRemove`: function called when dismissing the notice.
--   `actions`: (array) an array of action objects. Each member object should contain a `label` and either a `url` link string or `onClick` callback function.
+#### `actions`: `NoticeAction[]`
+
+An array of action objects. Each member object should contain a `label` and either a `url` link string or `onClick` callback function.
+
+-   Required: No
+-   Default: `[]`
+
+#### `children`: `string`
+
+The displayed message of a notice. Also used as the spoken message for assistive technology, unless `spokenMessage` is provided as an alternative message.
+
+-   Required: Yes
+
+#### `explicitDismiss`: `boolean`
+
+Whether to require user action to dismiss the snackbar. By default, this is dismissed on a timeout, without user interaction.
+
+-   Required: No
+-   Default: `false`
+
+#### `icon`: `ReactNode`
+
+The icon to render in the snackbar.
+
+-   Required: No
+-   Default: `null`
+
+#### `listRef`: `MutableRefObject< HTMLDivElement | null >`
+
+A ref to the list that contains the snackbar.
+
+-   Required: No
+
+#### `onDismiss`: `() => void`
+
+A callback executed when the snackbar is dismissed. It is distinct from onRemove, which _looks_ like a callback but is actually the function to call to remove the snackbar from the UI.
+
+-   Required: No
+
+#### `onRemove`: `() => void`
+
+Function called when dismissing the notice.
+
+-   Required: No
+
+#### `politeness`: `'polite' | 'assertive'`
+
+A politeness level for the notice's spoken message. Should be provided as one of the valid options for [an `aria-live` attribute value](https://www.w3.org/TR/wai-aria-1.1/#aria-live). Note that this value should be considered a suggestion; assistive technologies may override it based on internal heuristics.
+
+A value of `'assertive'` is to be used for important, and usually time-sensitive, information. It will interrupt anything else the screen reader is announcing in that moment.
+
+A value of `'polite'` is to be used for advisory information. It should not interrupt what the screen reader is announcing in that moment (the "speech queue") or interrupt the current task.
+
+-   Required: No
+-   Default: `'polite'`
+
+#### `spokenMessage`: `string`
+
+Used to provide a custom spoken message.
+
+-   Required: No
+-   Default: `children`
 
 ## Related components
 

package/src/snackbar/{index.js → index.tsx}

@@ -1,6 +1,7 @@
 /**
  * External dependencies
  */
+import type { ForwardedRef, KeyboardEvent, MouseEvent } from 'react';
 import classnames from 'classnames';
 
 /**
@@ -14,21 +15,23 @@ import warning from '@wordpress/warning';
 /**
  * Internal dependencies
  */
-import { Button } from '../';
+import Button from '../button';
+import type { NoticeAction, SnackbarProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
 
-const noop = () => {};
 const NOTICE_TIMEOUT = 10000;
 
-/** @typedef {import('@wordpress/element').WPElement} WPElement */
-
 /**
  * Custom hook which announces the message with the given politeness, if a
  * valid message is provided.
  *
- * @param {string|WPElement}     [message]  Message to announce.
- * @param {'polite'|'assertive'} politeness Politeness to announce.
+ * @param  message    Message to announce.
+ * @param  politeness Politeness to announce.
  */
-function useSpokenMessage( message, politeness ) {
+function useSpokenMessage(
+	message: SnackbarProps[ 'spokenMessage' ],
+	politeness: NonNullable< SnackbarProps[ 'politeness' ] >
+) {
 	const spokenMessage =
 		typeof message === 'string' ? message : renderToString( message );
 
@@ -39,42 +42,43 @@ function useSpokenMessage( message, politeness ) {
 	}, [ spokenMessage, politeness ] );
 }
 
-function Snackbar(
+function UnforwardedSnackbar(
 	{
 		className,
 		children,
 		spokenMessage = children,
 		politeness = 'polite',
 		actions = [],
-		onRemove = noop,
+		onRemove,
 		icon = null,
 		explicitDismiss = false,
 		// onDismiss is a callback executed when the snackbar is dismissed.
 		// It is distinct from onRemove, which _looks_ like a callback but is
 		// actually the function to call to remove the snackbar from the UI.
-		onDismiss = noop,
+		onDismiss,
 		listRef,
-	},
-	ref
+	}: WordPressComponentProps< SnackbarProps, 'div' >,
+	ref: ForwardedRef< any >
 ) {
-	onDismiss = onDismiss || noop;
-
-	function dismissMe( event ) {
+	function dismissMe( event: KeyboardEvent | MouseEvent ) {
 		if ( event && event.preventDefault ) {
 			event.preventDefault();
 		}
 
 		// Prevent focus loss by moving it to the list element.
-		listRef.current.focus();
+		listRef?.current?.focus();
 
-		onDismiss();
-		onRemove();
+		onDismiss?.();
+		onRemove?.();
 	}
 
-	function onActionClick( event, onClick ) {
+	function onActionClick(
+		event: MouseEvent,
+		onClick: NoticeAction[ 'onClick' ]
+	) {
 		event.stopPropagation();
 
-		onRemove();
+		onRemove?.();
 
 		if ( onClick ) {
 			onClick( event );
@@ -87,8 +91,8 @@ function Snackbar(
 	useEffect( () => {
 		const timeoutHandle = setTimeout( () => {
 			if ( ! explicitDismiss ) {
-				onDismiss();
-				onRemove();
+				onDismiss?.();
+				onRemove?.();
 			}
 		}, NOTICE_TIMEOUT );
 
@@ -118,10 +122,10 @@ function Snackbar(
 		<div
 			ref={ ref }
 			className={ classes }
-			onClick={ ! explicitDismiss ? dismissMe : noop }
-			tabIndex="0"
+			onClick={ ! explicitDismiss ? dismissMe : undefined }
+			tabIndex={ 0 }
 			role={ ! explicitDismiss ? 'button' : '' }
-			onKeyPress={ ! explicitDismiss ? dismissMe : noop }
+			onKeyPress={ ! explicitDismiss ? dismissMe : undefined }
 			aria-label={ ! explicitDismiss ? __( 'Dismiss this notice' ) : '' }
 		>
 			<div className={ snackbarContentClassnames }>
@@ -135,7 +139,7 @@ function Snackbar(
 							key={ index }
 							href={ url }
 							variant="tertiary"
-							onClick={ ( event ) =>
+							onClick={ ( event: MouseEvent ) =>
 								onActionClick( event, onClick )
 							}
 							className="components-snackbar__action"
@@ -148,7 +152,7 @@ function Snackbar(
 					<span
 						role="button"
 						aria-label="Dismiss this notice"
-						tabIndex="0"
+						tabIndex={ 0 }
 						className="components-snackbar__dismiss-button"
 						onClick={ dismissMe }
 						onKeyPress={ dismissMe }
@@ -161,4 +165,18 @@ function Snackbar(
 	);
 }
 
-export default forwardRef( Snackbar );
+/**
+ * A Snackbar displays a succinct message that is cleared out after a small delay.
+ *
+ * It can also offer the user options, like viewing a published post.
+ * But these options should also be available elsewhere in the UI.
+ *
+ * ```jsx
+ * const MySnackbarNotice = () => (
+ *   <Snackbar>Post published successfully.</Snackbar>
+ * );
+ * ```
+ */
+export const Snackbar = forwardRef( UnforwardedSnackbar );
+
+export default Snackbar;

package/src/snackbar/{list.js → list.tsx}

@@ -12,13 +12,14 @@ import { useRef } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import Snackbar from './';
+import Snackbar from '.';
 import {
 	__unstableMotion as motion,
 	__unstableAnimatePresence as AnimatePresence,
 } from '../animation';
+import type { Notice, SnackbarListProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
 
-const noop = () => {};
 const SNACKBAR_VARIANTS = {
 	init: {
 		height: 0,
@@ -39,28 +40,28 @@ const SNACKBAR_VARIANTS = {
 	},
 };
 
-const SNACKBAR_REDUCE_MOTION_VARIANTS = {
-	init: false,
-	open: false,
-	exit: false,
-};
-
 /**
  * Renders a list of notices.
  *
- * @param {Object}   $0           Props passed to the component.
- * @param {Array}    $0.notices   Array of notices to render.
- * @param {Function} $0.onRemove  Function called when a notice should be removed / dismissed.
- * @param {Object}   $0.className Name of the class used by the component.
- * @param {Object}   $0.children  Array of children to be rendered inside the notice list.
- *
- * @return {Object} The rendered notices list.
+ * ```jsx
+ * const MySnackbarListNotice = () => (
+ *   <SnackbarList
+ *     notices={ notices }
+ *     onRemove={ removeNotice }
+ *   />
+ * );
+ * ```
  */
-function SnackbarList( { notices, className, children, onRemove = noop } ) {
-	const listRef = useRef();
+export function SnackbarList( {
+	notices,
+	className,
+	children,
+	onRemove,
+}: WordPressComponentProps< SnackbarListProps, 'div' > ) {
+	const listRef = useRef< HTMLDivElement | null >( null );
 	const isReducedMotion = useReducedMotion();
 	className = classnames( 'components-snackbar-list', className );
-	const removeNotice = ( notice ) => () => onRemove( notice.id );
+	const removeNotice = ( notice: Notice ) => () => onRemove?.( notice.id );
 	return (
 		<div className={ className } tabIndex={ -1 } ref={ listRef }>
 			{ children }
@@ -76,9 +77,7 @@ function SnackbarList( { notices, className, children, onRemove = noop } ) {
 							exit={ 'exit' }
 							key={ notice.id }
 							variants={
-								isReducedMotion
-									? SNACKBAR_REDUCE_MOTION_VARIANTS
-									: SNACKBAR_VARIANTS
+								isReducedMotion ? undefined : SNACKBAR_VARIANTS
 							}
 						>
 							<div className="components-snackbar-list__notice-container">

package/src/snackbar/stories/index.tsx

@@ -0,0 +1,96 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import Snackbar from '..';
+
+const meta: ComponentMeta< typeof Snackbar > = {
+	title: 'Components/Snackbar',
+	component: Snackbar,
+	argTypes: {
+		as: { control: { type: null } },
+		onRemove: {
+			action: 'onRemove',
+			control: { type: null },
+		},
+		onDismiss: {
+			action: 'onDismiss',
+			control: { type: null },
+		},
+		listRef: {
+			control: { type: null },
+		},
+	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const DefaultTemplate: ComponentStory< typeof Snackbar > = ( {
+	children,
+	...props
+} ) => {
+	return <Snackbar { ...props }>{ children }</Snackbar>;
+};
+
+export const Default: ComponentStory< typeof Snackbar > = DefaultTemplate.bind(
+	{}
+);
+Default.args = {
+	children:
+		'Use Snackbars to communicate low priority, non-interruptive messages to the user.',
+};
+
+export const WithActions: ComponentStory< typeof Snackbar > =
+	DefaultTemplate.bind( {} );
+WithActions.args = {
+	actions: [
+		{
+			label: 'Open WP.org',
+			url: 'https://wordpress.org',
+		},
+	],
+	children: 'Use Snackbars with an action link to an external page.',
+};
+
+export const WithIcon: ComponentStory< typeof Snackbar > = DefaultTemplate.bind(
+	{}
+);
+WithIcon.args = {
+	children: 'Add an icon to make your snackbar stand out',
+	icon: (
+		<span role="img" aria-label="Icon" style={ { fontSize: 21 } }>
+			🌮
+		</span>
+	),
+};
+
+export const WithExplicitDismiss: ComponentStory< typeof Snackbar > =
+	DefaultTemplate.bind( {} );
+WithExplicitDismiss.args = {
+	children:
+		'Add a cross to explicitly close the snackbar, and do not hide it automatically',
+	explicitDismiss: true,
+};
+
+export const WithActionAndExplicitDismiss: ComponentStory< typeof Snackbar > =
+	DefaultTemplate.bind( {} );
+WithActionAndExplicitDismiss.args = {
+	actions: [
+		{
+			label: 'Open WP.org',
+			url: 'https://wordpress.org',
+		},
+	],
+	children:
+		'Add an action and a cross to explicitly close the snackbar, and do not hide it automatically',
+	explicitDismiss: true,
+};

package/src/snackbar/stories/list.tsx

@@ -0,0 +1,98 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import SnackbarList from '../list';
+
+const meta: ComponentMeta< typeof SnackbarList > = {
+	title: 'Components/SnackbarList',
+	component: SnackbarList,
+	argTypes: {
+		as: { control: { type: null } },
+		onRemove: {
+			action: 'onRemove',
+			control: { type: null },
+		},
+	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+export const Default: ComponentStory< typeof SnackbarList > = ( {
+	children,
+	notices: noticesProp,
+	...props
+} ) => {
+	const [ notices, setNotices ] = useState( noticesProp );
+
+	const onRemove = ( id: string ) => {
+		const matchIndex = notices.findIndex( ( n ) => n.id === id );
+		if ( matchIndex > -1 ) {
+			setNotices( [
+				...notices.slice( 0, matchIndex ),
+				...notices.slice( matchIndex + 1 ),
+			] );
+		}
+	};
+
+	return (
+		<SnackbarList { ...props } notices={ notices } onRemove={ onRemove }>
+			{ children }
+		</SnackbarList>
+	);
+};
+
+Default.args = {
+	children:
+		'Use SnackbarList to communicate multiple low priority, non-interruptive messages to the user.',
+	notices: [
+		{
+			id: 'SAVE_POST_NOTICE_ID_1',
+			spokenMessage: 'Post published.',
+			actions: [
+				{
+					label: 'View Post',
+					url: 'https://example.com/?p=522',
+				},
+			],
+			content: 'Post published.',
+			isDismissible: true,
+			explicitDismiss: false,
+		},
+		{
+			id: 'SAVE_POST_NOTICE_ID_2',
+			spokenMessage: 'Post updated',
+			actions: [
+				{
+					label: 'View Post',
+					url: 'https://example.com/?p=522',
+				},
+			],
+			content: 'Post updated.',
+			isDismissible: true,
+			explicitDismiss: false,
+		},
+		{
+			id: 'global1',
+			spokenMessage: 'All content copied.',
+			actions: [],
+			content: 'All content copied.',
+			isDismissible: true,
+			explicitDismiss: false,
+		},
+	],
+};