@wordpress/components 25.12.0 → 25.14.0

package/src/spinner/README.md

@@ -17,3 +17,5 @@ function Example() {
 The spinner component should:
 
 -   Signal to users that the processing of their request is underway and will soon complete.
+
+Check out the [Storybook page](https://wordpress.github.io/gutenberg/?path=/docs/components-spinner--docs) for a visual exploration of this component.

package/src/tabs/README.md

@@ -163,9 +163,9 @@ The children elements, which should be a series of `Tabs.TabPanel` components.
 
 ##### Props
 
-###### `id`: `string`
+###### `tabId`: `string`
 
-The id of the tab, which is prepended with the `Tabs` instance ID.
+A unique identifier for the tab, which is used to generate a unique id for the underlying element. The value of this prop should match with the value of the `tabId` prop on the corresponding `Tabs.TabPanel` component.
 
 - Required: Yes
 
@@ -198,9 +198,9 @@ The children elements, generally the content to display on the tabpanel.
 
 - Required: No
 
-###### `id`: `string`
+###### `tabId`: `string`
 
-The id of the tabpanel, which is combined with the `Tabs` instance ID and the suffix `-view`
+A unique identifier for the tabpanel, which is used to generate an instanced id for the underlying element. The value of this prop should match with the value of the `tabId` prop on the corresponding `Tabs.Tab` component.
 
 - Required: Yes
 

package/src/tabs/index.tsx

@@ -8,7 +8,7 @@ import * as Ariakit from '@ariakit/react';
  * WordPress dependencies
  */
 import { useInstanceId } from '@wordpress/compose';
-import { useLayoutEffect, useRef } from '@wordpress/element';
+import { useLayoutEffect, useMemo, useRef } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -45,7 +45,7 @@ function Tabs( {
 	const isControlled = selectedTabId !== undefined;
 
 	const { items, selectedId } = store.useState();
-	const { setSelectedId } = store;
+	const { setSelectedId, move } = store;
 
 	// Keep track of whether tabs have been populated. This is used to prevent
 	// certain effects from firing too early while tab data and relevant
@@ -154,8 +154,37 @@ function Tabs( {
 		setSelectedId,
 	] );
 
+	// In controlled mode, make sure browser focus follows the selected tab if
+	// the selection is changed while a tab is already being focused.
+	useLayoutEffect( () => {
+		if ( ! isControlled || ! selectOnMove ) {
+			return;
+		}
+		const currentItem = items.find( ( item ) => item.id === selectedId );
+		const activeElement = currentItem?.element?.ownerDocument.activeElement;
+		const tabsHasFocus = items.some( ( item ) => {
+			return activeElement && activeElement === item.element;
+		} );
+
+		if (
+			activeElement &&
+			tabsHasFocus &&
+			selectedId !== activeElement.id
+		) {
+			move( selectedId );
+		}
+	}, [ isControlled, items, move, selectOnMove, selectedId ] );
+
+	const contextValue = useMemo(
+		() => ( {
+			store,
+			instanceId,
+		} ),
+		[ store, instanceId ]
+	);
+
 	return (
-		<TabsContext.Provider value={ { store, instanceId } }>
+		<TabsContext.Provider value={ contextValue }>
 			{ children }
 		</TabsContext.Provider>
 	);
@@ -164,4 +193,6 @@ function Tabs( {
 Tabs.TabList = TabList;
 Tabs.Tab = Tab;
 Tabs.TabPanel = TabPanel;
+Tabs.Context = TabsContext;
+
 export default Tabs;

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

@@ -20,6 +20,14 @@ import Button from '../../button';
 const meta: Meta< typeof Tabs > = {
 	title: 'Components (Experimental)/Tabs',
 	component: Tabs,
+	subcomponents: {
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		'Tabs.TabList': Tabs.TabList,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		'Tabs.Tab': Tabs.Tab,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		'Tabs.TabPanel': Tabs.TabPanel,
+	},
 	parameters: {
 		actions: { argTypesRegex: '^on.*' },
 		controls: { expanded: true },
@@ -32,17 +40,17 @@ const Template: StoryFn< typeof Tabs > = ( props ) => {
 	return (
 		<Tabs { ...props }>
 			<Tabs.TabList>
-				<Tabs.Tab id={ 'tab1' }>Tab 1</Tabs.Tab>
-				<Tabs.Tab id={ 'tab2' }>Tab 2</Tabs.Tab>
-				<Tabs.Tab id={ 'tab3' }>Tab 3</Tabs.Tab>
+				<Tabs.Tab tabId="tab1">Tab 1</Tabs.Tab>
+				<Tabs.Tab tabId="tab2">Tab 2</Tabs.Tab>
+				<Tabs.Tab tabId="tab3">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' } focusable={ false }>
+			<Tabs.TabPanel tabId="tab3" focusable={ false }>
 				<p>Selected tab: Tab 3</p>
 				<p>
 					This tabpanel has its <code>focusable</code> prop set to
@@ -63,19 +71,19 @@ const DisabledTabTemplate: StoryFn< typeof Tabs > = ( props ) => {
 	return (
 		<Tabs { ...props }>
 			<Tabs.TabList>
-				<Tabs.Tab id={ 'tab1' } disabled={ true }>
+				<Tabs.Tab tabId="tab1" disabled={ true }>
 					Tab 1
 				</Tabs.Tab>
-				<Tabs.Tab id={ 'tab2' }>Tab 2</Tabs.Tab>
-				<Tabs.Tab id={ 'tab3' }>Tab 3</Tabs.Tab>
+				<Tabs.Tab tabId="tab2">Tab 2</Tabs.Tab>
+				<Tabs.Tab tabId="tab3">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>
@@ -88,31 +96,31 @@ const WithTabIconsAndTooltipsTemplate: StoryFn< typeof Tabs > = ( props ) => {
 		<Tabs { ...props }>
 			<Tabs.TabList>
 				<Tabs.Tab
-					id={ 'tab1' }
+					tabId="tab1"
 					render={
 						<Button icon={ wordpress } label="Tab 1" showTooltip />
 					}
 				/>
 				<Tabs.Tab
-					id={ 'tab2' }
+					tabId="tab2"
 					render={
 						<Button icon={ link } label="Tab 2" showTooltip />
 					}
 				/>
 				<Tabs.Tab
-					id={ 'tab3' }
+					tabId="tab3"
 					render={
 						<Button icon={ more } label="Tab 3" showTooltip />
 					}
 				/>
 			</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>
@@ -132,18 +140,18 @@ const UsingSlotFillTemplate: StoryFn< typeof Tabs > = ( props ) => {
 		<SlotFillProvider>
 			<Tabs { ...props }>
 				<Tabs.TabList>
-					<Tabs.Tab id={ 'tab1' }>Tab 1</Tabs.Tab>
-					<Tabs.Tab id={ 'tab2' }>Tab 2</Tabs.Tab>
-					<Tabs.Tab id={ 'tab3' }>Tab 3</Tabs.Tab>
+					<Tabs.Tab tabId="tab1">Tab 1</Tabs.Tab>
+					<Tabs.Tab tabId="tab2">Tab 2</Tabs.Tab>
+					<Tabs.Tab tabId="tab3">Tab 3</Tabs.Tab>
 				</Tabs.TabList>
 				<Fill name="tabs-are-fun">
-					<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>
 				</Fill>
@@ -188,9 +196,9 @@ const CloseButtonTemplate: StoryFn< typeof Tabs > = ( props ) => {
 							} }
 						>
 							<Tabs.TabList>
-								<Tabs.Tab id={ 'tab1' }>Tab 1</Tabs.Tab>
-								<Tabs.Tab id={ 'tab2' }>Tab 2</Tabs.Tab>
-								<Tabs.Tab id={ 'tab3' }>Tab 3</Tabs.Tab>
+								<Tabs.Tab tabId="tab1">Tab 1</Tabs.Tab>
+								<Tabs.Tab tabId="tab2">Tab 2</Tabs.Tab>
+								<Tabs.Tab tabId="tab3">Tab 3</Tabs.Tab>
 							</Tabs.TabList>
 							<Button
 								variant={ 'tertiary' }
@@ -203,13 +211,13 @@ const CloseButtonTemplate: StoryFn< typeof Tabs > = ( props ) => {
 								Close Tabs
 							</Button>
 						</div>
-						<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>
@@ -243,19 +251,19 @@ const ControlledModeTemplate: StoryFn< typeof Tabs > = ( props ) => {
 				} }
 			>
 				<Tabs.TabList>
-					<Tabs.Tab id={ 'tab1' }>Tab 1</Tabs.Tab>
+					<Tabs.Tab tabId="tab1">Tab 1</Tabs.Tab>
 
-					<Tabs.Tab id={ 'tab2' }>Tab 2</Tabs.Tab>
+					<Tabs.Tab tabId="tab2">Tab 2</Tabs.Tab>
 
-					<Tabs.Tab id={ 'tab3' }>Tab 3</Tabs.Tab>
+					<Tabs.Tab tabId="tab3">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>
@@ -306,19 +314,19 @@ const TabBecomesDisabledTemplate: StoryFn< typeof Tabs > = ( props ) => {
 			</Button>
 			<Tabs { ...props }>
 				<Tabs.TabList>
-					<Tabs.Tab id={ 'tab1' }>Tab 1</Tabs.Tab>
-					<Tabs.Tab id={ 'tab2' } disabled={ disableTab2 }>
+					<Tabs.Tab tabId="tab1">Tab 1</Tabs.Tab>
+					<Tabs.Tab tabId="tab2" disabled={ disableTab2 }>
 						Tab 2
 					</Tabs.Tab>
-					<Tabs.Tab id={ 'tab3' }>Tab 3</Tabs.Tab>
+					<Tabs.Tab tabId="tab3">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>
@@ -340,17 +348,17 @@ const TabGetsRemovedTemplate: StoryFn< typeof Tabs > = ( props ) => {
 			</Button>
 			<Tabs { ...props }>
 				<Tabs.TabList>
-					{ ! removeTab1 && <Tabs.Tab id={ 'tab1' }>Tab 1</Tabs.Tab> }
-					<Tabs.Tab id={ 'tab2' }>Tab 2</Tabs.Tab>
-					<Tabs.Tab id={ 'tab3' }>Tab 3</Tabs.Tab>
+					{ ! removeTab1 && <Tabs.Tab tabId="tab1">Tab 1</Tabs.Tab> }
+					<Tabs.Tab tabId="tab2">Tab 2</Tabs.Tab>
+					<Tabs.Tab tabId="tab3">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>

package/src/tabs/tab.tsx

@@ -2,28 +2,28 @@
  * WordPress dependencies
  */
 
-import { useContext, forwardRef } from '@wordpress/element';
+import { forwardRef } from '@wordpress/element';
 
 /**
  * Internal dependencies
  */
 import type { TabProps } from './types';
 import warning from '@wordpress/warning';
-import { TabsContext } from './context';
+import { useTabsContext } from './context';
 import { Tab as StyledTab } from './styles';
 import type { WordPressComponentProps } from '../context';
 
 export const Tab = forwardRef<
 	HTMLButtonElement,
-	WordPressComponentProps< TabProps, 'button', false >
->( function Tab( { children, id, disabled, render, ...otherProps }, ref ) {
-	const context = useContext( TabsContext );
+	Omit< WordPressComponentProps< TabProps, 'button', false >, 'id' >
+>( function Tab( { children, tabId, disabled, render, ...otherProps }, ref ) {
+	const context = useTabsContext();
 	if ( ! context ) {
-		warning( '`Tabs.TabList` must be wrapped in a `Tabs` component.' );
+		warning( '`Tabs.Tab` must be wrapped in a `Tabs` component.' );
 		return null;
 	}
 	const { store, instanceId } = context;
-	const instancedTabId = `${ instanceId }-${ id }`;
+	const instancedTabId = `${ instanceId }-${ tabId }`;
 	return (
 		<StyledTab
 			ref={ ref }

package/src/tabs/tabpanel.tsx

@@ -6,7 +6,7 @@
  * WordPress dependencies
  */
 
-import { forwardRef, useContext } from '@wordpress/element';
+import { forwardRef } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -15,25 +15,29 @@ import type { TabPanelProps } from './types';
 import { TabPanel as StyledTabPanel } from './styles';
 
 import warning from '@wordpress/warning';
-import { TabsContext } from './context';
+import { useTabsContext } from './context';
 import type { WordPressComponentProps } from '../context';
 
 export const TabPanel = forwardRef<
 	HTMLDivElement,
-	WordPressComponentProps< TabPanelProps, 'div', false >
->( function TabPanel( { children, id, focusable = true, ...otherProps }, ref ) {
-	const context = useContext( TabsContext );
+	Omit< WordPressComponentProps< TabPanelProps, 'div', false >, 'id' >
+>( function TabPanel(
+	{ children, tabId, focusable = true, ...otherProps },
+	ref
+) {
+	const context = useTabsContext();
 	if ( ! context ) {
 		warning( '`Tabs.TabPanel` must be wrapped in a `Tabs` component.' );
 		return null;
 	}
 	const { store, instanceId } = context;
+	const instancedTabId = `${ instanceId }-${ tabId }`;
 
 	return (
 		<StyledTabPanel
 			ref={ ref }
 			store={ store }
-			id={ `${ instanceId }-${ id }-view` }
+			id={ instancedTabId }
 			focusable={ focusable }
 			{ ...otherProps }
 		>