@wordpress/components 27.0.0 → 27.1.0

package/src/snackbar/test/index.tsx

@@ -0,0 +1,267 @@
+/**
+ * External dependencies
+ */
+import { render, screen, within } from '@testing-library/react';
+import { click } from '@ariakit/test';
+
+/**
+ * WordPress dependencies
+ */
+import { speak } from '@wordpress/a11y';
+import { SVG, Path } from '@wordpress/primitives';
+
+/**
+ * Internal dependencies
+ */
+import Snackbar from '../index';
+
+jest.mock( '@wordpress/a11y', () => ( { speak: jest.fn() } ) );
+const mockedSpeak = jest.mocked( speak );
+
+describe( 'Snackbar', () => {
+	const testId = 'snackbar';
+
+	beforeEach( () => {
+		mockedSpeak.mockReset();
+	} );
+
+	it( 'should render correctly', () => {
+		render( <Snackbar>Message</Snackbar> );
+
+		const snackbar = screen.getByTestId( testId );
+
+		expect( snackbar ).toBeVisible();
+		expect( snackbar ).toHaveTextContent( 'Message' );
+	} );
+
+	it( 'should render with an additional className', () => {
+		render( <Snackbar className="gutenberg">Message</Snackbar> );
+
+		expect( screen.getByTestId( testId ) ).toHaveClass( 'gutenberg' );
+	} );
+
+	it( 'should render with an icon', () => {
+		const testIcon = (
+			<SVG data-testid="icon">
+				<Path />
+			</SVG>
+		);
+
+		render( <Snackbar icon={ testIcon }>Message</Snackbar> );
+
+		const snackbar = screen.getByTestId( testId );
+		const icon = within( snackbar ).getByTestId( 'icon' );
+
+		expect( icon ).toBeVisible();
+	} );
+
+	it( 'should be dismissible by clicking the snackbar', async () => {
+		const onRemove = jest.fn();
+		const onDismiss = jest.fn();
+
+		render(
+			<Snackbar onRemove={ onRemove } onDismiss={ onDismiss }>
+				Message
+			</Snackbar>
+		);
+
+		const snackbar = screen.getByTestId( testId );
+
+		expect( snackbar ).toHaveAttribute( 'role', 'button' );
+		expect( snackbar ).toHaveAttribute(
+			'aria-label',
+			'Dismiss this notice'
+		);
+
+		await click( snackbar );
+
+		expect( onRemove ).toHaveBeenCalledTimes( 1 );
+		expect( onDismiss ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	it( 'should not be dismissible by clicking the snackbar when the `explicitDismiss` prop is set to `true`', async () => {
+		const onRemove = jest.fn();
+		const onDismiss = jest.fn();
+
+		render(
+			<Snackbar
+				explicitDismiss
+				onRemove={ onRemove }
+				onDismiss={ onDismiss }
+			>
+				Message
+			</Snackbar>
+		);
+
+		const snackbar = screen.getByTestId( testId );
+
+		expect( snackbar ).not.toHaveAttribute( 'role', 'button' );
+		expect( snackbar ).not.toHaveAttribute(
+			'aria-label',
+			'Dismiss this notice'
+		);
+		expect( snackbar ).toHaveClass(
+			'components-snackbar-explicit-dismiss'
+		);
+
+		await click( snackbar );
+
+		expect( onRemove ).not.toHaveBeenCalled();
+		expect( onDismiss ).not.toHaveBeenCalled();
+	} );
+
+	it( 'should be dismissible by clicking the close button when the `explicitDismiss` prop is set to `true`', async () => {
+		const onRemove = jest.fn();
+		const onDismiss = jest.fn();
+
+		render(
+			<Snackbar
+				explicitDismiss
+				onRemove={ onRemove }
+				onDismiss={ onDismiss }
+			>
+				Message
+			</Snackbar>
+		);
+
+		const snackbar = screen.getByTestId( testId );
+		const closeButton = within( snackbar ).getByRole( 'button', {
+			name: 'Dismiss this notice',
+		} );
+
+		await click( closeButton );
+
+		expect( onRemove ).toHaveBeenCalledTimes( 1 );
+		expect( onDismiss ).toHaveBeenCalledTimes( 1 );
+	} );
+
+	describe( 'actions', () => {
+		it( 'should render only the first action with a warning when multiple actions are passed', () => {
+			render(
+				<Snackbar
+					actions={ [
+						{ label: 'One', url: 'https://example.com' },
+						{ label: 'Two', url: 'https://example.com' },
+						{ label: 'Three', url: 'https://example.com' },
+					] }
+				>
+					Message
+				</Snackbar>
+			);
+
+			expect( console ).toHaveWarnedWith(
+				'Snackbar can only have one action. Use Notice if your message requires many actions.'
+			);
+
+			const snackbar = screen.getByTestId( testId );
+			const action = within( snackbar ).getByRole( 'link' );
+
+			expect( action ).toBeVisible();
+			expect( action ).toHaveTextContent( 'One' );
+		} );
+
+		it( 'should be rendered as a link when the `url` prop is set', () => {
+			render(
+				<Snackbar
+					actions={ [
+						{ label: 'View post', url: 'https://example.com' },
+					] }
+				>
+					Post updated.
+				</Snackbar>
+			);
+
+			const snackbar = screen.getByTestId( testId );
+			const link = within( snackbar ).getByRole( 'link', {
+				name: 'View post',
+			} );
+
+			expect( link ).toHaveAttribute( 'href', 'https://example.com' );
+		} );
+
+		it( 'should be rendered as a button and call `onClick` when the `onClick` prop is set', async () => {
+			const onClick = jest.fn();
+
+			render(
+				<Snackbar actions={ [ { label: 'View post', onClick } ] }>
+					Post updated.
+				</Snackbar>
+			);
+
+			const snackbar = screen.getByTestId( testId );
+			const button = within( snackbar ).getByRole( 'button', {
+				name: 'View post',
+			} );
+
+			await click( button );
+
+			expect( onClick ).toHaveBeenCalledTimes( 1 );
+		} );
+
+		it( 'should be rendered as a link when the `url` prop and the `onClick` are set', () => {
+			render(
+				<Snackbar
+					actions={ [
+						{
+							label: 'View post',
+							url: 'https://example.com',
+							onClick: () => {},
+						},
+					] }
+				>
+					Post updated.
+				</Snackbar>
+			);
+
+			const snackbar = screen.getByTestId( testId );
+			const link = within( snackbar ).getByRole( 'link', {
+				name: 'View post',
+			} );
+			expect( link ).toBeVisible();
+		} );
+	} );
+
+	describe( 'useSpokenMessage', () => {
+		it( 'should speak the given message', () => {
+			render( <Snackbar>FYI</Snackbar> );
+
+			expect( speak ).toHaveBeenCalledWith( 'FYI', 'polite' );
+		} );
+
+		it( 'should speak the given message by explicit politeness', () => {
+			render( <Snackbar politeness="assertive">Uh oh!</Snackbar> );
+
+			expect( speak ).toHaveBeenCalledWith( 'Uh oh!', 'assertive' );
+		} );
+
+		it( 'should coerce a message to a string', () => {
+			// This test assumes that `@wordpress/a11y` is capable of handling
+			// markup strings appropriately.
+			render(
+				<Snackbar>
+					With <em>emphasis</em> this time.
+				</Snackbar>
+			);
+
+			expect( speak ).toHaveBeenCalledWith(
+				'With <em>emphasis</em> this time.',
+				'polite'
+			);
+		} );
+
+		it( 'should not re-speak an effectively equivalent element message', () => {
+			const { rerender } = render(
+				<Snackbar>
+					With <em>emphasis</em> this time.
+				</Snackbar>
+			);
+			rerender(
+				<Snackbar>
+					With <em>emphasis</em> this time.
+				</Snackbar>
+			);
+
+			expect( speak ).toHaveBeenCalledTimes( 1 );
+		} );
+	} );
+} );

package/src/snackbar/test/list.tsx

@@ -0,0 +1,46 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+import { click } from '@ariakit/test';
+
+/**
+ * Internal dependencies
+ */
+import SnackbarList from '../list';
+
+window.scrollTo = jest.fn();
+
+describe( 'SnackbarList', () => {
+	afterEach( () => {
+		jest.resetAllMocks();
+	} );
+
+	it( 'should get focus after a snackbar is dismissed', async () => {
+		render(
+			<SnackbarList
+				notices={ [
+					{
+						id: 'ID_1',
+						content: 'Post published.',
+						explicitDismiss: true,
+					},
+					{
+						id: 'ID_2',
+						content: 'Post updated.',
+						explicitDismiss: true,
+					},
+				] }
+				onRemove={ () => {} }
+			/>
+		);
+
+		await click(
+			screen.getAllByRole( 'button', {
+				name: 'Dismiss this notice',
+			} )[ 0 ]
+		);
+
+		expect( screen.getByTestId( 'snackbar-list' ) ).toHaveFocus();
+	} );
+} );

package/src/snackbar/types.ts

@@ -6,7 +6,11 @@ import type { MutableRefObject, ReactNode } from 'react';
 /**
  * Internal dependencies
  */
-import type { NoticeProps, NoticeChildren } from '../notice/types';
+import type {
+	NoticeProps,
+	NoticeChildren,
+	NoticeAction,
+} from '../notice/types';
 
 type SnackbarOnlyProps = {
 	/**
@@ -28,8 +32,32 @@ type SnackbarOnlyProps = {
 	listRef?: MutableRefObject< HTMLDivElement | null >;
 };
 
-export type SnackbarProps = Omit< NoticeProps, '__unstableHTML' > &
-	SnackbarOnlyProps;
+export type SnackbarProps = Pick<
+	NoticeProps,
+	| 'className'
+	| 'children'
+	| 'spokenMessage'
+	| 'onRemove'
+	| 'politeness'
+	| 'onDismiss'
+> &
+	SnackbarOnlyProps & {
+		/**
+		 * An array of action objects. Each member object should contain:
+		 *
+		 * - `label`: `string` containing the text of the button/link
+		 * - `url`: `string` OR `onClick`: `( event: SyntheticEvent ) => void` to specify
+		 *    what the action does.
+		 *
+		 * The default appearance of an action button is inferred based on whether
+		 * `url` or `onClick` are provided, rendering the button as a link if
+		 * appropriate. If both props are provided, `url` takes precedence, and the
+		 * action button will render as an anchor tag.
+		 *
+		 * @default []
+		 */
+		actions?: Pick< NoticeAction, 'label' | 'url' | 'onClick' >[];
+	};
 
 export type SnackbarListProps = {
 	notices: Array<

package/src/tabs/README.md

@@ -14,7 +14,7 @@ Tabs organizes content across different screens, data sets, and interactions. It
 
 #### Uncontrolled Mode
 
-Tabs can be used in an uncontrolled mode, where the component manages its own state. In this mode, the `initialTabId` prop can be used to set the initially selected tab. If this prop is not set, the first tab will be selected by default. In addition, in most cases where the currently active tab becomes disabled or otherwise unavailable, uncontrolled mode will automatically fall back to selecting the first available tab.
+Tabs can be used in an uncontrolled mode, where the component manages its own state. In this mode, the `defaultTabId` prop can be used to set the initially selected tab. If this prop is not set, the first tab will be selected by default. In addition, in most cases where the currently active tab becomes disabled or otherwise unavailable, uncontrolled mode will automatically fall back to selecting the first available tab.
 
 ```jsx
 import { Tabs } from '@wordpress/components';
@@ -24,25 +24,25 @@ const onSelect = ( tabName ) => {
 };
 
 const MyUncontrolledTabs = () => (
-		<Tabs onSelect={onSelect} initialTab="tab2">
-			<Tabs.TabList >
-				<Tabs.Tab id={ 'tab1' } title={ 'Tab 1' }>
+		<Tabs onSelect={ onSelect } defaultTabId="tab2">
+			<Tabs.TabList>
+				<Tabs.Tab tabId="tab1" title="Tab 1">
 					Tab 1
 				</Tabs.Tab>
-				<Tabs.Tab id={ 'tab2' } title={ 'Tab 2' }>
+				<Tabs.Tab tabId="tab2" title="Tab 2">
 					Tab 2
 				</Tabs.Tab>
-				<Tabs.Tab id={ 'tab3' } title={ 'Tab 3' }>
+				<Tabs.Tab tabId="tab3" title="Tab 3">
 					Tab 3
 				</Tabs.Tab>
 			</Tabs.TabList>
-			<Tabs.TabPanel id={ 'tab1' }>
+			<Tabs.TabPanel tabId="tab1">
 				<p>Selected tab: Tab 1</p>
 			</Tabs.TabPanel>
-			<Tabs.TabPanel id={ 'tab2' }>
+			<Tabs.TabPanel tabId="tab2">
 				<p>Selected tab: Tab 2</p>
 			</Tabs.TabPanel>
-			<Tabs.TabPanel id={ 'tab3' }>
+			<Tabs.TabPanel tabId="tab3">
 				<p>Selected tab: Tab 3</p>
 			</Tabs.TabPanel>
 		</Tabs>
@@ -51,7 +51,7 @@ const MyUncontrolledTabs = () => (
 
 #### Controlled Mode
 
-Tabs can also be used in a controlled mode, where the parent component specifies the `selectedTabId` and the `onSelect` props to control tab selection. In this mode, the `initialTabId` prop will be ignored if it is provided. If the `selectedTabId` is `null`, no tab is selected. In this mode, if the currently selected tab becomes disabled or otherwise unavailable, the component will _not_ fall back to another available tab, leaving the controlling component in charge of implementing the desired logic.
+Tabs can also be used in a controlled mode, where the parent component specifies the `selectedTabId` and the `onSelect` props to control tab selection. In this mode, the `defaultTabId` prop will be ignored if it is provided. If the `selectedTabId` is `null`, no tab is selected. In this mode, if the currently selected tab becomes disabled or otherwise unavailable, the component will _not_ fall back to another available tab, leaving the controlling component in charge of implementing the desired logic.
 
 ```jsx
 import { Tabs } from '@wordpress/components';
@@ -71,24 +71,24 @@ const MyControlledTabs = () => (
 				onSelect( selectedId );
 			} }
 		>
-			<Tabs.TabList >
-				<Tabs.Tab id={ 'tab1' } title={ 'Tab 1' }>
+			<Tabs.TabList>
+				<Tabs.Tab tabId="tab1" title="Tab 1">
 					Tab 1
 				</Tabs.Tab>
-				<Tabs.Tab id={ 'tab2' } title={ 'Tab 2' }>
+				<Tabs.Tab tabId="tab2" title="Tab 2">
 					Tab 2
 				</Tabs.Tab>
-				<Tabs.Tab id={ 'tab3' } title={ 'Tab 3' }>
+				<Tabs.Tab tabId="tab3" title="Tab 3">
 					Tab 3
 				</Tabs.Tab>
 			</Tabs.TabList>
-			<Tabs.TabPanel id={ 'tab1' }>
+			<Tabs.TabPanel tabId="tab1">
 				<p>Selected tab: Tab 1</p>
 			</Tabs.TabPanel>
-			<Tabs.TabPanel id={ 'tab2' }>
+			<Tabs.TabPanel tabId="tab2">
 				<p>Selected tab: Tab 2</p>
 			</Tabs.TabPanel>
-			<Tabs.TabPanel id={ 'tab3' }>
+			<Tabs.TabPanel tabId="tab3">
 				<p>Selected tab: Tab 3</p>
 			</Tabs.TabPanel>
 		</Tabs>
@@ -120,7 +120,7 @@ When `true`, the tab will be selected when receiving focus (automatic tab activa
 -   Required: No
 -   Default: `true`
 
-###### `initialTabId`: `string`
+###### `defaultTabId`: `string`
 
 The id of the tab to be selected upon mounting of component. If this prop is not set, the first tab will be selected by default. The id provided will be internally prefixed with a unique instance ID to avoid collisions.
 

package/src/tabs/index.tsx

@@ -26,7 +26,7 @@ import { TabPanel } from './tabpanel';
 
 function Tabs( {
 	selectOnMove = true,
-	initialTabId,
+	defaultTabId,
 	orientation = 'horizontal',
 	onSelect,
 	children,
@@ -36,7 +36,7 @@ function Tabs( {
 	const store = Ariakit.useTabStore( {
 		selectOnMove,
 		orientation,
-		defaultSelectedId: initialTabId && `${ instanceId }-${ initialTabId }`,
+		defaultSelectedId: defaultTabId && `${ instanceId }-${ defaultTabId }`,
 		setSelectedId: ( selectedId ) => {
 			const strippedDownId =
 				typeof selectedId === 'string'
@@ -66,7 +66,7 @@ function Tabs( {
 		return ! item.dimmed;
 	} );
 	const initialTab = items.find(
-		( item ) => item.id === `${ instanceId }-${ initialTabId }`
+		( item ) => item.id === `${ instanceId }-${ defaultTabId }`
 	);
 
 	// Handle selecting the initial tab.
@@ -78,8 +78,8 @@ function Tabs( {
 		// Wait for the denoted initial tab to be declared before making a
 		// selection. This ensures that if a tab is declared lazily it can
 		// still receive initial selection, as well as ensuring no tab is
-		// selected if an invalid `initialTabId` is provided.
-		if ( initialTabId && ! initialTab ) {
+		// selected if an invalid `defaultTabId` is provided.
+		if ( defaultTabId && ! initialTab ) {
 			return;
 		}
 
@@ -101,7 +101,7 @@ function Tabs( {
 	}, [
 		firstEnabledTab,
 		initialTab,
-		initialTabId,
+		defaultTabId,
 		isControlled,
 		items,
 		selectedId,
@@ -122,7 +122,7 @@ function Tabs( {
 		}
 
 		// If the currently selected tab becomes disabled, fall back to the
-		// `initialTabId` if possible. Otherwise select the first
+		// `defaultTabId` if possible. Otherwise select the first
 		// enabled tab (if there is one).
 		if ( initialTab && ! initialTab.dimmed ) {
 			setSelectedId( initialTab.id );

package/src/tabs/stories/index.story.tsx

@@ -73,7 +73,7 @@ const DisabledTabTemplate: StoryFn< typeof Tabs > = ( props ) => {
 	return (
 		<Tabs { ...props }>
 			<Tabs.TabList>
-				<Tabs.Tab tabId="tab1" disabled={ true }>
+				<Tabs.Tab tabId="tab1" disabled>
 					Tab 1
 				</Tabs.Tab>
 				<Tabs.Tab tabId="tab2">Tab 2</Tabs.Tab>