@wordpress/components 28.9.0 → 28.11.0

package/src/tabs/README.md

@@ -109,45 +109,81 @@ Tabs is comprised of four individual components:
 
 ###### `children`: `React.ReactNode`
 
-The children elements, which should be at least a `Tabs.Tablist` component and a series of `Tabs.TabPanel` components.
+The children elements, which should include one instance of the `Tabs.Tablist` component and as many instances of the `Tabs.TabPanel` components as there are `Tabs.Tab` components.
 
 -   Required: Yes
 
 ###### `selectOnMove`: `boolean`
 
-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.
+Determines if the tab should be selected when it receives focus. If set to `false`, the tab will only be selected upon clicking, not when using arrow keys to shift focus (manual tab activation). See the [official W3C docs](https://www.w3.org/WAI/ARIA/apg/patterns/tabpanel/) for more info.
 
 -   Required: No
 -   Default: `true`
 
-###### `defaultTabId`: `string`
+###### `selectedTabId`: `string | null`
+
+The id of the tab whose panel is currently visible.
+
+If left `undefined`, it will be automatically set to the first enabled tab, and the component assumes it is being used in "uncontrolled" mode.
+
+Consequently, any value different than `undefined` will set the component in "controlled" mode. When in "controlled" mode, the `null` value will result in no tabs being selected, and the tablist becoming tabbable.
+
+- Required: No
+
+###### `defaultTabId`: `string | null`
 
-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.
+The id of the tab whose panel is currently visible.
 
-_Note: this prop will be overridden by the `selectedTabId` prop if it is provided. (Controlled Mode)_
+If left `undefined`, it will be automatically set to the first enabled tab. If set to `null`, no tab will be selected, and the tablist will be tabbable.
+
+_Note: this prop will be overridden by the `selectedTabId` prop if it is provided (meaning the component will be used in "controlled" mode)._
 
 -   Required: No
 
 ###### `onSelect`: `( ( selectedId: string | null | undefined ) => void )`
 
-The function called when a tab has been selected. It is passed the selected tab's ID as an argument.
+The function called when the `selectedTabId` changes.
 
 -   Required: No
 -   Default: `noop`
 
-###### `orientation`: `horizontal | vertical`
+###### `activeTabId`: `string | null`
+
+The current active tab `id`. The active tab is the tab element within the tablist widget that has DOM focus.
+
+- `null` represents the tablist (ie. the base composite element). Users
+  will be able to navigate out of it using arrow keys;
+- If `activeTabId` is initially set to `null`, the base composite element
+  itself will have focus and users will be able to navigate to it using
+  arrow keys.
+
+- Required: No
+
+###### `defaultActiveTabId`: `string | null`
+
+The tab id that should be active by default when the composite widget is rendered. If `null`, the tablist element itself will have focus and users will be able to navigate to it using arrow keys. If `undefined`, the first enabled item will be focused.
 
-The orientation of the `tablist` (`vertical` or `horizontal`)
+_Note: this prop will be overridden by the `activeTabId` prop if it is provided._
 
 -   Required: No
--   Default: `horizontal`
 
-###### `selectedTabId`: `string | null`
+###### `onActiveTabIdChange`: `( ( activeId: string | null | undefined ) => void )`
 
-The ID of the tab to display. This id is prepended with the `Tabs` instanceId internally.
-If left `undefined`, the component assumes it is being used in uncontrolled mode. Consequently, any value different than `undefined` will set the component in `controlled` mode. When in controlled mode, the `null` value will result in no tab being selected.
+The function called when the `selectedTabId` changes.
 
-- Required: No
+-   Required: No
+-   Default: `noop`
+
+###### `orientation`: `'horizontal' | 'vertical' | 'both'`
+
+Defines the orientation of the tablist and determines which arrow keys can be used to move focus:
+
+- `both`: all arrow keys work;
+- `horizontal`: only left and right arrow keys work;
+- `vertical`: only up and down arrow keys work.
+
+-   Required: No
+-   Default: `horizontal`
 
 #### TabList
 
@@ -155,7 +191,7 @@ If left `undefined`, the component assumes it is being used in uncontrolled mode
 
 ###### `children`: `React.ReactNode`
 
-The children elements, which should be a series of `Tabs.TabPanel` components.
+The children elements, which should include one or more instances of the `Tabs.Tab` component.
 
 -   Required: No
 
@@ -165,26 +201,28 @@ The children elements, which should be a series of `Tabs.TabPanel` components.
 
 ###### `tabId`: `string`
 
-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.
+The unique ID of the tab. It will be used to register the tab and match it to a corresponding `Tabs.TabPanel` component. If not provided, a unique ID will be automatically generated.
 
 - Required: Yes
 
 ###### `children`: `React.ReactNode`
 
-The children elements, generally the text to display on the tab.
+The contents of the tab.
 
 - Required: No
 
 ###### `disabled`: `boolean`
 
-Determines if the tab button should be disabled.
+Determines if the tab should be disabled. Note that disabled tabs can still be accessed via the keyboard when navigating through the tablist.
 
 - Required: No
 - Default: `false`
 
 ###### `render`: `React.ReactNode`
 
-The type of component to render the tab button as. If this prop is not provided, the tab button will be rendered as a `button` element.
+Allows the component to be rendered as a different HTML element or React component. The value can be a React element or a function that takes in the original component props and gives back a React element with the props merged.
+
+By default, the tab will be rendered as a `button` element.
 
 - Required: No
 
@@ -194,19 +232,23 @@ The type of component to render the tab button as. If this prop is not provided,
 
 ###### `children`: `React.ReactNode`
 
-The children elements, generally the content to display on the tabpanel.
+The contents of the tab panel.
 
 - Required: No
 
 ###### `tabId`: `string`
 
-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.
+The unique `id` of the `Tabs.Tab` component controlling this panel. This connection is used to assign the `aria-labelledby` attribute to the tab panel and to determine if the tab panel should be visible.
+
+If not provided, this link is automatically established by matching the order of `Tabs.Tab` and `Tabs.TabPanel` elements in the DOM.
 
 - Required: Yes
 
 ###### `focusable`: `boolean`
 
-Determines whether or not the tabpanel element should be focusable. If `false`, pressing the tab key will skip over the tabpanel, and instead focus on the first focusable element in the panel (if there is one).
+Determines whether or not the tabpanel element should be focusable.
+
+If `false`, pressing the tab key will skip over the tabpanel, and instead focus on the first focusable element in the panel (if there is one).
 
 - Required: No
 - Default: `true`

package/src/tabs/index.tsx

@@ -2,18 +2,13 @@
  * External dependencies
  */
 import * as Ariakit from '@ariakit/react';
-import { useStoreState } from '@ariakit/react';
 
 /**
  * WordPress dependencies
  */
 import { useInstanceId } from '@wordpress/compose';
-import {
-	useEffect,
-	useLayoutEffect,
-	useMemo,
-	useRef,
-} from '@wordpress/element';
+import { useEffect, useMemo } from '@wordpress/element';
+import { isRTL } from '@wordpress/i18n';
 
 /**
  * Internal dependencies
@@ -24,191 +19,119 @@ import { Tab } from './tab';
 import { TabList } from './tablist';
 import { TabPanel } from './tabpanel';
 
-function Tabs( {
-	selectOnMove = true,
-	defaultTabId,
-	orientation = 'horizontal',
-	onSelect,
-	children,
-	selectedTabId,
-}: TabsProps ) {
-	const instanceId = useInstanceId( Tabs, 'tabs' );
-	const store = Ariakit.useTabStore( {
-		selectOnMove,
-		orientation,
-		defaultSelectedId: defaultTabId && `${ instanceId }-${ defaultTabId }`,
-		setSelectedId: ( selectedId ) => {
-			const strippedDownId =
-				typeof selectedId === 'string'
-					? selectedId.replace( `${ instanceId }-`, '' )
-					: selectedId;
-			onSelect?.( strippedDownId );
-		},
-		selectedId: selectedTabId && `${ instanceId }-${ selectedTabId }`,
-	} );
-
-	const isControlled = selectedTabId !== undefined;
-
-	const { items, selectedId, activeId } = useStoreState( store );
-	const { setSelectedId, setActiveId } = 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
-	// variables are undefined during the initial render.
-	const tabsHavePopulatedRef = useRef( false );
-	if ( items.length > 0 ) {
-		tabsHavePopulatedRef.current = true;
-	}
-
-	const selectedTab = items.find( ( item ) => item.id === selectedId );
-	const firstEnabledTab = items.find( ( item ) => {
-		// Ariakit internally refers to disabled tabs as `dimmed`.
-		return ! item.dimmed;
-	} );
-	const initialTab = items.find(
-		( item ) => item.id === `${ instanceId }-${ defaultTabId }`
-	);
-
-	// Handle selecting the initial tab.
-	useLayoutEffect( () => {
-		if ( isControlled ) {
-			return;
-		}
-
-		// 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 `defaultTabId` is provided.
-		if ( defaultTabId && ! initialTab ) {
-			return;
-		}
+function externalToInternalTabId(
+	externalId: string | undefined | null,
+	instanceId: string
+) {
+	return externalId && `${ instanceId }-${ externalId }`;
+}
 
-		// If the currently selected tab is missing (i.e. removed from the DOM),
-		// fall back to the initial tab or the first enabled tab if there is
-		// one. Otherwise, no tab should be selected.
-		if ( ! items.find( ( item ) => item.id === selectedId ) ) {
-			if ( initialTab && ! initialTab.dimmed ) {
-				setSelectedId( initialTab?.id );
-				return;
-			}
+function internalToExternalTabId(
+	internalId: string | undefined | null,
+	instanceId: string
+) {
+	return typeof internalId === 'string'
+		? internalId.replace( `${ instanceId }-`, '' )
+		: internalId;
+}
 
-			if ( firstEnabledTab ) {
-				setSelectedId( firstEnabledTab.id );
-			} else if ( tabsHavePopulatedRef.current ) {
-				setSelectedId( null );
-			}
-		}
-	}, [
-		firstEnabledTab,
-		initialTab,
+/**
+ * Display one panel of content at a time with a tabbed interface, based on the
+ * WAI-ARIA Tabs Pattern⁠.
+ *
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/tabs/
+ * ```
+ */
+export const Tabs = Object.assign(
+	function Tabs( {
+		selectOnMove = true,
 		defaultTabId,
-		isControlled,
-		items,
-		selectedId,
-		setSelectedId,
-	] );
-
-	// Handle the currently selected tab becoming disabled.
-	useLayoutEffect( () => {
-		if ( ! selectedTab?.dimmed ) {
-			return;
-		}
-
-		// In controlled mode, we trust that disabling tabs is done
-		// intentionally, and don't select a new tab automatically.
-		if ( isControlled ) {
-			setSelectedId( null );
-			return;
-		}
-
-		// If the currently selected tab becomes disabled, fall back to the
-		// `defaultTabId` if possible. Otherwise select the first
-		// enabled tab (if there is one).
-		if ( initialTab && ! initialTab.dimmed ) {
-			setSelectedId( initialTab.id );
-			return;
-		}
-
-		if ( firstEnabledTab ) {
-			setSelectedId( firstEnabledTab.id );
-		}
-	}, [
-		firstEnabledTab,
-		initialTab,
-		isControlled,
-		selectedTab?.dimmed,
-		setSelectedId,
-	] );
-
-	// Clear `selectedId` if the active tab is removed from the DOM in controlled mode.
-	useLayoutEffect( () => {
-		if ( ! isControlled ) {
-			return;
-		}
-
-		// Once the tabs have populated, if the `selectedTabId` still can't be
-		// found, clear the selection.
-		if (
-			tabsHavePopulatedRef.current &&
-			!! selectedTabId &&
-			! selectedTab
-		) {
-			setSelectedId( null );
-		}
-	}, [ isControlled, selectedTab, selectedTabId, setSelectedId ] );
-
-	useEffect( () => {
-		// If there is no active tab, fallback to place focus on the first enabled tab
-		// so there is always an active element
-		if ( selectedTabId === null && ! activeId && firstEnabledTab?.id ) {
-			setActiveId( firstEnabledTab.id );
-		}
-	}, [ selectedTabId, activeId, firstEnabledTab?.id, setActiveId ] );
-
-	useEffect( () => {
-		if ( ! isControlled ) {
-			return;
-		}
-
-		requestAnimationFrame( () => {
-			const focusedElement =
-				items?.[ 0 ]?.element?.ownerDocument.activeElement;
-
-			if (
-				! focusedElement ||
-				! items.some( ( item ) => focusedElement === item.element )
-			) {
-				return; // Return early if no tabs are focused.
-			}
-
-			// If, after ariakit re-computes the active tab, that tab doesn't match
-			// the currently focused tab, then we force an update to ariakit to avoid
-			// any mismatches, especially when navigating to previous/next tab with
-			// arrow keys.
-			if ( activeId !== focusedElement.id ) {
-				setActiveId( focusedElement.id );
-			}
+		orientation = 'horizontal',
+		onSelect,
+		children,
+		selectedTabId,
+		activeTabId,
+		defaultActiveTabId,
+		onActiveTabIdChange,
+	}: TabsProps ) {
+		const instanceId = useInstanceId( Tabs, 'tabs' );
+		const store = Ariakit.useTabStore( {
+			selectOnMove,
+			orientation,
+			defaultSelectedId: externalToInternalTabId(
+				defaultTabId,
+				instanceId
+			),
+			setSelectedId: ( newSelectedId ) => {
+				onSelect?.(
+					internalToExternalTabId( newSelectedId, instanceId )
+				);
+			},
+			selectedId: externalToInternalTabId( selectedTabId, instanceId ),
+			defaultActiveId: externalToInternalTabId(
+				defaultActiveTabId,
+				instanceId
+			),
+			setActiveId: ( newActiveId ) => {
+				onActiveTabIdChange?.(
+					internalToExternalTabId( newActiveId, instanceId )
+				);
+			},
+			activeId: externalToInternalTabId( activeTabId, instanceId ),
+			rtl: isRTL(),
 		} );
-	}, [ activeId, isControlled, items, setActiveId ] );
 
-	const contextValue = useMemo(
-		() => ( {
-			store,
-			instanceId,
+		const { items, activeId } = Ariakit.useStoreState( store );
+		const { setActiveId } = store;
+
+		useEffect( () => {
+			requestAnimationFrame( () => {
+				const focusedElement =
+					items?.[ 0 ]?.element?.ownerDocument.activeElement;
+
+				if (
+					! focusedElement ||
+					! items.some( ( item ) => focusedElement === item.element )
+				) {
+					return; // Return early if no tabs are focused.
+				}
+
+				// If, after ariakit re-computes the active tab, that tab doesn't match
+				// the currently focused tab, then we force an update to ariakit to avoid
+				// any mismatches, especially when navigating to previous/next tab with
+				// arrow keys.
+				if ( activeId !== focusedElement.id ) {
+					setActiveId( focusedElement.id );
+				}
+			} );
+		}, [ activeId, items, setActiveId ] );
+
+		const contextValue = useMemo(
+			() => ( {
+				store,
+				instanceId,
+			} ),
+			[ store, instanceId ]
+		);
+
+		return (
+			<TabsContext.Provider value={ contextValue }>
+				{ children }
+			</TabsContext.Provider>
+		);
+	},
+	{
+		Tab: Object.assign( Tab, {
+			displayName: 'Tabs.Tab',
 		} ),
-		[ store, instanceId ]
-	);
-
-	return (
-		<TabsContext.Provider value={ contextValue }>
-			{ children }
-		</TabsContext.Provider>
-	);
-}
-
-Tabs.TabList = TabList;
-Tabs.Tab = Tab;
-Tabs.TabPanel = TabPanel;
-Tabs.Context = TabsContext;
-
-export default Tabs;
+		TabList: Object.assign( TabList, {
+			displayName: 'Tabs.TabList',
+		} ),
+		TabPanel: Object.assign( TabPanel, {
+			displayName: 'Tabs.TabPanel',
+		} ),
+		Context: Object.assign( TabsContext, {
+			displayName: 'Tabs.Context',
+		} ),
+	}
+);

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

@@ -12,7 +12,7 @@ import { useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import Tabs from '..';
+import { Tabs } from '..';
 import { Slot, Fill, Provider as SlotFillProvider } from '../../slot-fill';
 import DropdownMenu from '../../dropdown-menu';
 import Button from '../../button';
@@ -20,7 +20,8 @@ import Tooltip from '../../tooltip';
 import Icon from '../../icon';
 
 const meta: Meta< typeof Tabs > = {
-	title: 'Components (Experimental)/Tabs',
+	title: 'Components/Containers/Tabs',
+	id: 'components-tabs',
 	component: Tabs,
 	subcomponents: {
 		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
@@ -29,6 +30,8 @@ const meta: Meta< typeof Tabs > = {
 		'Tabs.Tab': Tabs.Tab,
 		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
 		'Tabs.TabPanel': Tabs.TabPanel,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		'Tabs.Context': Tabs.Context,
 	},
 	tags: [ 'status-private' ],
 	parameters: {