@wordpress/components 22.0.0 → 23.0.0

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,
+		},
+	],
+};

package/src/snackbar/style.scss

@@ -22,7 +22,7 @@
 	&:focus {
 		box-shadow:
 			0 0 0 1px $white,
-			0 0 0 3px var(--wp-admin-theme-color);
+			0 0 0 3px $components-color-accent;
 	}
 
 	&.components-snackbar-explicit-dismiss {
@@ -64,7 +64,7 @@
 		}
 
 		&:hover {
-			color: var(--wp-admin-theme-color);
+			color: $components-color-accent;
 		}
 	}
 }

package/src/snackbar/types.ts

@@ -0,0 +1,116 @@
+/**
+ * External dependencies
+ */
+import type { MutableRefObject, ReactNode, SyntheticEvent } from 'react';
+
+export type NoticeActionWithURL = {
+	label: string;
+	url: string;
+	onClick?: ( event: SyntheticEvent ) => void;
+};
+
+type NoticeActionWithOnClick = {
+	label: string;
+	url?: string;
+	onClick: ( event: SyntheticEvent ) => void;
+};
+
+// TODO: move this type to the Notice component once it gets typed.
+export type NoticeAction = NoticeActionWithURL | NoticeActionWithOnClick;
+
+export type Notice = {
+	id: string;
+	spokenMessage: string;
+	actions: NoticeAction[];
+	icon?: ReactNode;
+	onDismiss?: () => void;
+	content: string;
+	isDismissible: boolean;
+	explicitDismiss: boolean;
+};
+
+export type SnackbarProps = {
+	/**
+	 * The displayed message of a notice.
+	 *
+	 * Also used as the spoken message for assistive technology,
+	 * unless `spokenMessage` is provided as an alternative message.
+	 */
+	children: string;
+	/**
+	 * Used to provide a custom spoken message.
+	 *
+	 * @default children
+	 */
+	spokenMessage?: Notice[ 'spokenMessage' ];
+	/**
+	 * A politeness level for the notice's spoken message. Should be provided as
+	 * one of the valid options for an `aria-live` attribute value. 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.
+	 *
+	 * @see https://www.w3.org/TR/wai-aria-1.1/#aria-live
+	 *
+	 * @default 'polite'
+	 */
+	politeness?: 'polite' | 'assertive';
+	/**
+	 * An array of action objects.
+	 *
+	 * Each member object should contain
+	 * a `label` and either a `url` link string or `onClick` callback function.
+	 *
+	 * @default []
+	 */
+	actions?: Notice[ 'actions' ];
+	/**
+	 * Called to remove the snackbar from the UI.
+	 */
+	onRemove?: () => void;
+	/**
+	 * The icon to render in the snackbar.
+	 *
+	 * @default null
+	 */
+	icon?: Notice[ 'icon' ];
+	/**
+	 * Whether to require user action to dismiss the snackbar.
+	 * By default, this is dismissed on a timeout, without user interaction.
+	 *
+	 * @default false
+	 */
+	explicitDismiss?: Notice[ 'explicitDismiss' ];
+	/**
+	 * 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?: Notice[ 'onDismiss' ];
+	/**
+	 * A ref to the list that contains the snackbar.
+	 */
+	listRef?: MutableRefObject< HTMLDivElement | null >;
+};
+
+export type SnackbarListProps = {
+	/**
+	 * Array of notices to render.
+	 */
+	notices: Notice[];
+	/**
+	 * Children to be rendered inside the notice list.
+	 */
+	children?: ReactNode;
+	/**
+	 * Function called when a notice should be removed / dismissed.
+	 */
+	onRemove?: ( id: Notice[ 'id' ] ) => void;
+};

package/src/spacer/test/index.tsx

@@ -9,64 +9,77 @@ import { render, screen } from '@testing-library/react';
 import { Spacer } from '../index';
 
 describe( 'props', () => {
-	beforeEach( () => {
+	test( 'should render correctly', () => {
 		render( <Spacer data-testid="spacer" /> );
-	} );
 
-	test( 'should render correctly', () => {
 		expect( screen.getByTestId( 'spacer' ) ).toMatchSnapshot();
 	} );
 
 	test( 'should render margin', () => {
+		render( <Spacer data-testid="spacer" /> );
 		render( <Spacer margin={ 5 } data-testid="customized-spacer" /> );
+
 		expect(
 			screen.getByTestId( 'customized-spacer' )
 		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
 	} );
 
 	test( 'should render marginX', () => {
+		render( <Spacer data-testid="spacer" /> );
 		render( <Spacer marginX={ 5 } data-testid="customized-spacer" /> );
+
 		expect(
 			screen.getByTestId( 'customized-spacer' )
 		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
 	} );
 
 	test( 'should render marginY', () => {
+		render( <Spacer data-testid="spacer" /> );
 		render( <Spacer marginY={ 5 } data-testid="customized-spacer" /> );
+
 		expect(
 			screen.getByTestId( 'customized-spacer' )
 		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
 	} );
 
 	test( 'should render marginTop', () => {
+		render( <Spacer data-testid="spacer" /> );
 		render( <Spacer marginTop={ 5 } data-testid="customized-spacer" /> );
+
 		expect(
 			screen.getByTestId( 'customized-spacer' )
 		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
 	} );
 
 	test( 'should render marginBottom', () => {
+		render( <Spacer data-testid="spacer" /> );
 		render( <Spacer marginBottom={ 5 } data-testid="customized-spacer" /> );
+
 		expect(
 			screen.getByTestId( 'customized-spacer' )
 		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
 	} );
 
 	test( 'should render marginLeft', () => {
+		render( <Spacer data-testid="spacer" /> );
 		render( <Spacer marginLeft={ 5 } data-testid="customized-spacer" /> );
+
 		expect(
 			screen.getByTestId( 'customized-spacer' )
 		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
 	} );
 
 	test( 'should render marginRight', () => {
+		render( <Spacer data-testid="spacer" /> );
 		render( <Spacer marginRight={ 5 } data-testid="customized-spacer" /> );
+
 		expect(
 			screen.getByTestId( 'customized-spacer' )
 		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
 	} );
 
 	test( 'should override margin props from less to more specific', () => {
+		render( <Spacer data-testid="spacer" /> );
 		render(
 			<Spacer
 				margin={ 10 }
@@ -76,63 +89,79 @@ describe( 'props', () => {
 				data-testid="customized-spacer"
 			/>
 		);
+
 		expect(
 			screen.getByTestId( 'customized-spacer' )
 		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
 	} );
 
 	test( 'should render padding', () => {
+		render( <Spacer data-testid="spacer" /> );
 		render( <Spacer padding={ 5 } data-testid="customized-spacer" /> );
+
 		expect(
 			screen.getByTestId( 'customized-spacer' )
 		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
 	} );
 
 	test( 'should render paddingX', () => {
+		render( <Spacer data-testid="spacer" /> );
 		render( <Spacer paddingX={ 5 } data-testid="customized-spacer" /> );
+
 		expect(
 			screen.getByTestId( 'customized-spacer' )
 		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
 	} );
 
 	test( 'should render paddingY', () => {
+		render( <Spacer data-testid="spacer" /> );
 		render( <Spacer paddingY={ 5 } data-testid="customized-spacer" /> );
+
 		expect(
 			screen.getByTestId( 'customized-spacer' )
 		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
 	} );
 
 	test( 'should render paddingTop', () => {
+		render( <Spacer data-testid="spacer" /> );
 		render( <Spacer paddingTop={ 5 } data-testid="customized-spacer" /> );
+
 		expect(
 			screen.getByTestId( 'customized-spacer' )
 		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
 	} );
 
 	test( 'should render paddingBottom', () => {
+		render( <Spacer data-testid="spacer" /> );
 		render(
 			<Spacer paddingBottom={ 5 } data-testid="customized-spacer" />
 		);
+
 		expect(
 			screen.getByTestId( 'customized-spacer' )
 		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
 	} );
 
 	test( 'should render paddingLeft', () => {
+		render( <Spacer data-testid="spacer" /> );
 		render( <Spacer paddingLeft={ 5 } data-testid="customized-spacer" /> );
+
 		expect(
 			screen.getByTestId( 'customized-spacer' )
 		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
 	} );
 
 	test( 'should render paddingRight', () => {
+		render( <Spacer data-testid="spacer" /> );
 		render( <Spacer paddingRight={ 5 } data-testid="customized-spacer" /> );
+
 		expect(
 			screen.getByTestId( 'customized-spacer' )
 		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );
 	} );
 
 	test( 'should override padding props from less to more specific', () => {
+		render( <Spacer data-testid="spacer" /> );
 		render(
 			<Spacer
 				padding={ 10 }
@@ -142,6 +171,7 @@ describe( 'props', () => {
 				data-testid="customized-spacer"
 			/>
 		);
+
 		expect(
 			screen.getByTestId( 'customized-spacer' )
 		).toMatchStyleDiffSnapshot( screen.getByTestId( 'spacer' ) );

package/src/spinner/styles.ts

@@ -24,7 +24,7 @@ export const StyledSpinner = styled.svg`
 	display: inline-block;
 	margin: 5px 11px 0;
 	position: relative;
-	color: var( --wp-admin-theme-color );
+	color: ${ COLORS.ui.theme };
 	overflow: visible;
 `;
 

package/src/surface/test/index.tsx

@@ -2,7 +2,6 @@
  * External dependencies
  */
 import { render } from '@testing-library/react';
-import type { RenderResult } from '@testing-library/react';
 
 /**
  * Internal dependencies
@@ -10,39 +9,40 @@ import type { RenderResult } from '@testing-library/react';
 import { Surface } from '../index';
 
 describe( 'props', () => {
-	let base: RenderResult;
-	beforeEach( () => {
-		base = render( <Surface>Surface</Surface> );
-	} );
-
 	test( 'should render correctly', () => {
-		expect( base.container ).toMatchSnapshot();
+		const { container } = render( <Surface>Surface</Surface> );
+		expect( container ).toMatchSnapshot();
 	} );
 
 	test( 'should render variants', () => {
+		const view = render( <Surface>Surface</Surface> );
 		const { container } = render(
 			<Surface variant="secondary">Surface</Surface>
 		);
-		expect( container ).toMatchDiffSnapshot( base.container );
+		expect( container ).toMatchDiffSnapshot( view.container );
 	} );
 
 	test( 'should render borderLeft', () => {
+		const view = render( <Surface>Surface</Surface> );
 		const { container } = render( <Surface borderLeft>Surface</Surface> );
-		expect( container ).toMatchDiffSnapshot( base.container );
+		expect( container ).toMatchDiffSnapshot( view.container );
 	} );
 
 	test( 'should render borderRight', () => {
+		const view = render( <Surface>Surface</Surface> );
 		const { container } = render( <Surface borderRight>Surface</Surface> );
-		expect( container ).toMatchDiffSnapshot( base.container );
+		expect( container ).toMatchDiffSnapshot( view.container );
 	} );
 
 	test( 'should render borderTop', () => {
+		const view = render( <Surface>Surface</Surface> );
 		const { container } = render( <Surface borderTop>Surface</Surface> );
-		expect( container ).toMatchDiffSnapshot( base.container );
+		expect( container ).toMatchDiffSnapshot( view.container );
 	} );
 
 	test( 'should render borderBottom', () => {
+		const view = render( <Surface>Surface</Surface> );
 		const { container } = render( <Surface borderBottom>Surface</Surface> );
-		expect( container ).toMatchDiffSnapshot( base.container );
+		expect( container ).toMatchDiffSnapshot( view.container );
 	} );
 } );

package/src/tab-panel/README.md

@@ -120,6 +120,7 @@ An array of objects containing the following properties:
 -   `name`: `(string)` Defines the key for the tab.
 -   `title`:`(string)` Defines the translated text for the tab.
 -   `className`:`(string)` Optional. Defines the class to put on the tab.
+-   `icon`:`(ReactNode)` Optional. When set, displays the icon in place of the tab title. The title is then rendered as an aria-label and tooltip.
 
 > > **Note:** Other fields may be added to the object and accessed from the child function if desired.
 
@@ -142,6 +143,14 @@ The name of the tab to be selected upon mounting of component. If this prop is n
 -   Required: No
 -   Default: none
 
+#### selectOnMove
+
+When `true`, the tab will be selected when receiving focus (automatic tab activation). When `false`, the tab will be selected only when clicked (manual tab activation). See the [official W3C docs](https://www.w3.org/WAI/ARIA/apg/patterns/tabpanel/) for more info.
+
+-   Type: `boolean`
+-   Required: No
+-   Default: `true`
+
 #### children
 
 A function which renders the tabviews given the selected tab. The function is passed the active tab object as an argument as defined the tabs prop.