@wordpress/components 21.3.0 → 22.0.0

package/src/slot-fill/use-slot.js

@@ -26,6 +26,9 @@ const useSlot = ( name ) => {
 		} );
 
 		return unsubscribe;
+		// Ignore reason: Modifying this dep array could introduce unexpected changes in behavior,
+		// so we'll leave it as=is until the hook can be properly refactored for exhaustive-deps.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [ name ] );
 
 	return slot;

package/src/snackbar/index.js

@@ -93,7 +93,7 @@ function Snackbar(
 		}, NOTICE_TIMEOUT );
 
 		return () => clearTimeout( timeoutHandle );
-	}, [ onDismiss, onRemove ] );
+	}, [ onDismiss, onRemove, explicitDismiss ] );
 
 	const classes = classnames( className, 'components-snackbar', {
 		'components-snackbar-explicit-dismiss': !! explicitDismiss,

package/src/surface/test/__snapshots__/index.tsx.snap

@@ -5,14 +5,16 @@ Snapshot Diff:
 - First value
 + Second value
 
-  <div
--   class="components-surface css-pt58n0-View-Surface-getBorders-primary e19lxcc00"
-+   class="components-surface css-soe81k-View-Surface-getBorders-primary e19lxcc00"
-    data-wp-c16t="true"
-    data-wp-component="Surface"
-  >
-    Surface
-  </div>
+@@ -1,8 +1,8 @@
+  <div>
+    <div
+-     class="components-surface css-pt58n0-View-Surface-getBorders-primary e19lxcc00"
++     class="components-surface css-soe81k-View-Surface-getBorders-primary e19lxcc00"
+      data-wp-c16t="true"
+      data-wp-component="Surface"
+    >
+      Surface
+    </div>
 `;
 
 exports[`props should render borderLeft 1`] = `
@@ -20,14 +22,16 @@ Snapshot Diff:
 - First value
 + Second value
 
-  <div
--   class="components-surface css-1vckp4o-View-Surface-getBorders-primary e19lxcc00"
-+   class="components-surface css-soe81k-View-Surface-getBorders-primary e19lxcc00"
-    data-wp-c16t="true"
-    data-wp-component="Surface"
-  >
-    Surface
-  </div>
+@@ -1,8 +1,8 @@
+  <div>
+    <div
+-     class="components-surface css-1vckp4o-View-Surface-getBorders-primary e19lxcc00"
++     class="components-surface css-soe81k-View-Surface-getBorders-primary e19lxcc00"
+      data-wp-c16t="true"
+      data-wp-component="Surface"
+    >
+      Surface
+    </div>
 `;
 
 exports[`props should render borderRight 1`] = `
@@ -35,14 +39,16 @@ Snapshot Diff:
 - First value
 + Second value
 
-  <div
--   class="components-surface css-sw9dzi-View-Surface-getBorders-primary e19lxcc00"
-+   class="components-surface css-soe81k-View-Surface-getBorders-primary e19lxcc00"
-    data-wp-c16t="true"
-    data-wp-component="Surface"
-  >
-    Surface
-  </div>
+@@ -1,8 +1,8 @@
+  <div>
+    <div
+-     class="components-surface css-sw9dzi-View-Surface-getBorders-primary e19lxcc00"
++     class="components-surface css-soe81k-View-Surface-getBorders-primary e19lxcc00"
+      data-wp-c16t="true"
+      data-wp-component="Surface"
+    >
+      Surface
+    </div>
 `;
 
 exports[`props should render borderTop 1`] = `
@@ -50,14 +56,16 @@ Snapshot Diff:
 - First value
 + Second value
 
-  <div
--   class="components-surface css-123k66h-View-Surface-getBorders-primary e19lxcc00"
-+   class="components-surface css-soe81k-View-Surface-getBorders-primary e19lxcc00"
-    data-wp-c16t="true"
-    data-wp-component="Surface"
-  >
-    Surface
-  </div>
+@@ -1,8 +1,8 @@
+  <div>
+    <div
+-     class="components-surface css-123k66h-View-Surface-getBorders-primary e19lxcc00"
++     class="components-surface css-soe81k-View-Surface-getBorders-primary e19lxcc00"
+      data-wp-c16t="true"
+      data-wp-component="Surface"
+    >
+      Surface
+    </div>
 `;
 
 exports[`props should render correctly 1`] = `
@@ -67,12 +75,14 @@ exports[`props should render correctly 1`] = `
   position: relative;
 }
 
-<div
-  class="components-surface emotion-0 emotion-1"
-  data-wp-c16t="true"
-  data-wp-component="Surface"
->
-  Surface
+<div>
+  <div
+    class="components-surface emotion-0 emotion-1"
+    data-wp-c16t="true"
+    data-wp-component="Surface"
+  >
+    Surface
+  </div>
 </div>
 `;
 
@@ -81,12 +91,14 @@ Snapshot Diff:
 - First value
 + Second value
 
-  <div
--   class="components-surface css-1m2pafr-View-Surface-getBorders-secondary e19lxcc00"
-+   class="components-surface css-soe81k-View-Surface-getBorders-primary e19lxcc00"
-    data-wp-c16t="true"
-    data-wp-component="Surface"
-  >
-    Surface
-  </div>
+@@ -1,8 +1,8 @@
+  <div>
+    <div
+-     class="components-surface css-1m2pafr-View-Surface-getBorders-secondary e19lxcc00"
++     class="components-surface css-soe81k-View-Surface-getBorders-primary e19lxcc00"
+      data-wp-c16t="true"
+      data-wp-component="Surface"
+    >
+      Surface
+    </div>
 `;

package/src/surface/test/index.tsx

@@ -16,43 +16,33 @@ describe( 'props', () => {
 	} );
 
 	test( 'should render correctly', () => {
-		expect( base.container.firstChild ).toMatchSnapshot();
+		expect( base.container ).toMatchSnapshot();
 	} );
 
 	test( 'should render variants', () => {
 		const { container } = render(
 			<Surface variant="secondary">Surface</Surface>
 		);
-		expect( container.firstChild ).toMatchDiffSnapshot(
-			base.container.firstChild
-		);
+		expect( container ).toMatchDiffSnapshot( base.container );
 	} );
 
 	test( 'should render borderLeft', () => {
 		const { container } = render( <Surface borderLeft>Surface</Surface> );
-		expect( container.firstChild ).toMatchDiffSnapshot(
-			base.container.firstChild
-		);
+		expect( container ).toMatchDiffSnapshot( base.container );
 	} );
 
 	test( 'should render borderRight', () => {
 		const { container } = render( <Surface borderRight>Surface</Surface> );
-		expect( container.firstChild ).toMatchDiffSnapshot(
-			base.container.firstChild
-		);
+		expect( container ).toMatchDiffSnapshot( base.container );
 	} );
 
 	test( 'should render borderTop', () => {
 		const { container } = render( <Surface borderTop>Surface</Surface> );
-		expect( container.firstChild ).toMatchDiffSnapshot(
-			base.container.firstChild
-		);
+		expect( container ).toMatchDiffSnapshot( base.container );
 	} );
 
 	test( 'should render borderBottom', () => {
 		const { container } = render( <Surface borderBottom>Surface</Surface> );
-		expect( container.firstChild ).toMatchDiffSnapshot(
-			base.container.firstChild
-		);
+		expect( container ).toMatchDiffSnapshot( base.container );
 	} );
 } );

package/src/tab-panel/index.tsx

@@ -97,11 +97,10 @@ export function TabPanel( {
 	const selectedId = `${ instanceId }-${ selectedTab?.name ?? 'none' }`;
 
 	useEffect( () => {
-		const newSelectedTab = find( tabs, { name: selected } );
-		if ( ! newSelectedTab && tabs.length > 0 ) {
+		if ( ! selectedTab?.name && tabs.length > 0 ) {
 			handleTabSelection( initialTabName || tabs[ 0 ].name );
 		}
-	}, [ tabs ] );
+	}, [ tabs, selectedTab?.name, initialTabName ] );
 
 	return (
 		<div className={ className }>

package/src/tab-panel/test/index.tsx

@@ -38,14 +38,22 @@ describe( 'TabPanel', () => {
 	it( 'should render a tabpanel, and clicking should change tabs', async () => {
 		const user = setupUser();
 		const panelRenderFunction = jest.fn();
+		const mockOnSelect = jest.fn();
 
-		render( <TabPanel tabs={ TABS } children={ panelRenderFunction } /> );
+		render(
+			<TabPanel
+				tabs={ TABS }
+				children={ panelRenderFunction }
+				onSelect={ mockOnSelect }
+			/>
+		);
 
 		expect( getSelectedTab() ).toHaveTextContent( 'Alpha' );
 		expect(
 			screen.getByRole( 'tabpanel', { name: 'Alpha' } )
 		).toBeInTheDocument();
 		expect( panelRenderFunction ).toHaveBeenLastCalledWith( TABS[ 0 ] );
+		expect( mockOnSelect ).toHaveBeenLastCalledWith( 'alpha' );
 
 		await user.click( screen.getByRole( 'tab', { name: 'Beta' } ) );
 
@@ -54,6 +62,7 @@ describe( 'TabPanel', () => {
 			screen.getByRole( 'tabpanel', { name: 'Beta' } )
 		).toBeInTheDocument();
 		expect( panelRenderFunction ).toHaveBeenLastCalledWith( TABS[ 1 ] );
+		expect( mockOnSelect ).toHaveBeenLastCalledWith( 'beta' );
 
 		await user.click( screen.getByRole( 'tab', { name: 'Alpha' } ) );
 
@@ -62,6 +71,7 @@ describe( 'TabPanel', () => {
 			screen.getByRole( 'tabpanel', { name: 'Alpha' } )
 		).toBeInTheDocument();
 		expect( panelRenderFunction ).toHaveBeenLastCalledWith( TABS[ 0 ] );
+		expect( mockOnSelect ).toHaveBeenLastCalledWith( 'alpha' );
 	} );
 
 	it( 'should render with a tab initially selected by prop initialTabIndex', () => {
@@ -117,4 +127,71 @@ describe( 'TabPanel', () => {
 			'gamma-class'
 		);
 	} );
+
+	it( 'should select `initialTabname` if defined', () => {
+		const mockOnSelect = jest.fn();
+
+		render(
+			<TabPanel
+				tabs={ TABS }
+				initialTabName="beta"
+				children={ () => undefined }
+				onSelect={ mockOnSelect }
+			/>
+		);
+		expect( getSelectedTab() ).toHaveTextContent( 'Beta' );
+		expect( mockOnSelect ).toHaveBeenLastCalledWith( 'beta' );
+	} );
+
+	describe( 'fallbacks when new tab list invalidates current selection', () => {
+		it( 'should select `initialTabName` if defined', async () => {
+			const user = setupUser();
+			const mockOnSelect = jest.fn();
+
+			const { rerender } = render(
+				<TabPanel
+					tabs={ TABS }
+					initialTabName="gamma"
+					children={ () => undefined }
+					onSelect={ mockOnSelect }
+				/>
+			);
+			await user.click( screen.getByRole( 'tab', { name: 'Alpha' } ) );
+
+			rerender(
+				<TabPanel
+					tabs={ TABS.slice( 1 ) /* remove alpha */ }
+					initialTabName="gamma"
+					children={ () => undefined }
+					onSelect={ mockOnSelect }
+				/>
+			);
+			expect( getSelectedTab() ).toHaveTextContent( 'Gamma' );
+			expect( mockOnSelect ).toHaveBeenLastCalledWith( 'gamma' );
+		} );
+
+		it( 'should select first tab if `initialTabName` not defined', async () => {
+			const user = setupUser();
+			const mockOnSelect = jest.fn();
+
+			const { rerender } = render(
+				<TabPanel
+					tabs={ TABS }
+					children={ () => undefined }
+					onSelect={ mockOnSelect }
+				/>
+			);
+			await user.click( screen.getByRole( 'tab', { name: 'Alpha' } ) );
+
+			rerender(
+				<TabPanel
+					tabs={ TABS.slice( 1 ) /* remove alpha */ }
+					children={ () => undefined }
+					onSelect={ mockOnSelect }
+				/>
+			);
+			expect( getSelectedTab() ).toHaveTextContent( 'Beta' );
+			expect( mockOnSelect ).toHaveBeenLastCalledWith( 'beta' );
+		} );
+	} );
 } );

package/src/text/test/__snapshots__/index.tsx.snap

@@ -31,17 +31,19 @@ exports[`Text should render highlighted words with highlightCaseSensitive 1`] =
   box-shadow: 0 0 0 1px rgba( 0, 0, 0, 0.05 ) inset,0 -1px 0 rgba( 0, 0, 0, 0.1 ) inset;
 }
 
-<span
-  class="components-truncate components-text emotion-0 emotion-1"
-  data-wp-c16t="true"
-  data-wp-component="Text"
->
+<div>
   <span
-    class=""
+    class="components-truncate components-text emotion-0 emotion-1"
+    data-wp-c16t="true"
+    data-wp-component="Text"
   >
-    Lorem ipsum.
+    <span
+      class=""
+    >
+      Lorem ipsum.
+    </span>
   </span>
-</span>
+</div>
 `;
 
 exports[`Text snapshot tests should render correctly 1`] = `
@@ -53,11 +55,13 @@ exports[`Text snapshot tests should render correctly 1`] = `
   font-weight: normal;
 }
 
-<span
-  class="components-truncate components-text emotion-0 emotion-1"
-  data-wp-c16t="true"
-  data-wp-component="Text"
->
-  Lorem ipsum.
-</span>
+<div>
+  <span
+    class="components-truncate components-text emotion-0 emotion-1"
+    data-wp-c16t="true"
+    data-wp-component="Text"
+  >
+    Lorem ipsum.
+  </span>
+</div>
 `;

package/src/text/test/index.tsx

@@ -14,7 +14,7 @@ describe( 'Text', () => {
 	describe( 'snapshot tests', () => {
 		test( 'should render correctly', () => {
 			const { container } = render( <Text>Lorem ipsum.</Text> );
-			expect( container.firstChild ).toMatchSnapshot();
+			expect( container ).toMatchSnapshot();
 		} );
 	} );
 
@@ -116,7 +116,7 @@ describe( 'Text', () => {
 			</Text>
 		);
 
-		expect( container.firstChild ).toMatchSnapshot();
+		expect( container ).toMatchSnapshot();
 		// It'll have a length of 1 because there shouldn't be anything but the single span being rendered.
 		expect( container.firstChild?.childNodes ).toHaveLength( 1 );
 	} );

package/src/text-control/index.tsx

@@ -62,8 +62,6 @@ function UnforwardedTextControl(
 /**
  * TextControl components let users enter and edit text.
  *
- *
- * @example
  * ```jsx
  * import { TextControl } from '@wordpress/components';
  * import { useState } from '@wordpress/element';

package/src/text-control/stories/index.tsx

@@ -17,12 +17,11 @@ const meta: ComponentMeta< typeof TextControl > = {
 	component: TextControl,
 	title: 'Components/TextControl',
 	argTypes: {
-		onChange: {
-			action: 'onChange',
-		},
-		value: {
-			control: { type: null },
-		},
+		help: { control: { type: 'text' } },
+		label: { control: { type: 'text' } },
+		type: { control: { type: 'text' } },
+		onChange: { action: 'onChange' },
+		value: { control: { type: null } },
 	},
 	parameters: {
 		controls: {

package/src/toggle-control/README.md

@@ -44,14 +44,16 @@ If this property is added, a label will be generated using label property as the
 ### help
 
 If this property is added, a help text will be generated using help property as the content.
+For controlled components the `help` prop can also be a function which will return a help text
+dynamically depending on the boolean `checked` parameter.
 
--   Type: `String|WPElement`
+-   Type: `String|WPElement|Function`
 -   Required: No
 
 ### checked
 
 If checked is true the toggle will be checked. If checked is false the toggle will be unchecked.
-If no value is passed the toggle will be unchecked.
+If no value is passed the toggle will be an uncontrolled component with unchecked initial value.
 
 -   Type: `Boolean`
 -   Required: No
@@ -74,5 +76,5 @@ A function that receives the checked state (boolean) as input.
 
 The class that will be added with `components-base-control` and `components-toggle-control` to the classes of the wrapper div. If no className is passed only `components-base-control` and `components-toggle-control` are used.
 
-Type: String
-Required: No
+-		Type: `String`
+-		Required: No

package/src/toggle-control/index.tsx

@@ -64,8 +64,19 @@ export function ToggleControl( {
 
 	let describedBy, helpLabel;
 	if ( help ) {
-		describedBy = id + '__help';
-		helpLabel = typeof help === 'function' ? help( checked ) : help;
+		if ( typeof help === 'function' ) {
+			// `help` as a function works only for controlled components where
+			// `checked` is passed down from parent component. Uncontrolled
+			// component can show only a static help label.
+			if ( checked !== undefined ) {
+				helpLabel = help( checked );
+			}
+		} else {
+			helpLabel = help;
+		}
+		if ( helpLabel ) {
+			describedBy = id + '__help';
+		}
 	}
 
 	return (

package/src/toggle-control/types.ts

@@ -13,10 +13,8 @@ export type ToggleControlProps = Pick<
 	FormToggleProps,
 	'checked' | 'disabled'
 > &
-	Pick<
-		BaseControlProps,
-		'__nextHasNoMarginBottom' | 'help' | 'className'
-	> & {
+	Pick< BaseControlProps, '__nextHasNoMarginBottom' | 'className' > & {
+		help?: ReactNode | ( ( checked: boolean ) => ReactNode );
 		/**
 		 * The label for the toggle.
 		 */

package/src/toggle-group-control/stories/index.tsx

@@ -124,11 +124,11 @@ WithIcons.args = {
 };
 
 /**
- * A borderless style may be preferred in some contexts.
+ * When the `isDeselectable` prop is true, the option can be deselected by clicking on it again.
  */
-export const Borderless: ComponentStory< typeof ToggleGroupControl > =
+export const Deselectable: ComponentStory< typeof ToggleGroupControl > =
 	Template.bind( {} );
-Borderless.args = {
+Deselectable.args = {
 	...WithIcons.args,
-	__experimentalIsBorderless: true,
+	isDeselectable: true,
 };