@wordpress/components 25.9.0 → 25.10.0

package/src/tabs/index.tsx

@@ -0,0 +1,167 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import * as Ariakit from '@ariakit/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useInstanceId } from '@wordpress/compose';
+import { useEffect, useLayoutEffect, useRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { TabsProps } from './types';
+import { TabsContext } from './context';
+import { Tab } from './tab';
+import { TabList } from './tablist';
+import { TabPanel } from './tabpanel';
+
+function Tabs( {
+	selectOnMove = true,
+	initialTabId,
+	orientation = 'horizontal',
+	onSelect,
+	children,
+	selectedTabId,
+}: TabsProps ) {
+	const instanceId = useInstanceId( Tabs, 'tabs' );
+	const store = Ariakit.useTabStore( {
+		selectOnMove,
+		orientation,
+		defaultSelectedId: initialTabId && `${ instanceId }-${ initialTabId }`,
+		setSelectedId: ( selectedId ) => {
+			const strippedDownId =
+				typeof selectedId === 'string'
+					? selectedId.replace( `${ instanceId }-`, '' )
+					: selectedId;
+			onSelect?.( strippedDownId );
+		},
+		selectedId: selectedTabId && `${ instanceId }-${ selectedTabId }`,
+	} );
+
+	const isControlled = selectedTabId !== undefined;
+
+	const { items, selectedId } = store.useState();
+	const { setSelectedId } = 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 tabsHavePopulated = useRef( false );
+	if ( items.length > 0 ) {
+		tabsHavePopulated.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 }-${ initialTabId }`
+	);
+
+	// 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 `initialTabId` is provided.
+		if ( initialTabId && ! initialTab ) {
+			return;
+		}
+
+		// 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;
+			}
+
+			if ( firstEnabledTab ) {
+				setSelectedId( firstEnabledTab.id );
+			} else if ( tabsHavePopulated.current ) {
+				setSelectedId( null );
+			}
+		}
+	}, [
+		firstEnabledTab,
+		initialTab,
+		initialTabId,
+		isControlled,
+		items,
+		selectedId,
+		setSelectedId,
+	] );
+
+	// Handle the currently selected tab becoming disabled.
+	useEffect( () => {
+		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
+		// `initialTabId` 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.
+	useEffect( () => {
+		if ( ! isControlled ) {
+			return;
+		}
+
+		// Once the tabs have populated, if the `selectedTabId` still can't be
+		// found, clear the selection.
+		if ( tabsHavePopulated.current && !! selectedTabId && ! selectedTab ) {
+			setSelectedId( null );
+		}
+	}, [
+		isControlled,
+		selectedId,
+		selectedTab,
+		selectedTabId,
+		setSelectedId,
+	] );
+
+	return (
+		<TabsContext.Provider value={ { store, instanceId } }>
+			{ children }
+		</TabsContext.Provider>
+	);
+}
+
+Tabs.TabList = TabList;
+Tabs.Tab = Tab;
+Tabs.TabPanel = TabPanel;
+export default Tabs;

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

@@ -0,0 +1,352 @@
+/**
+ * External dependencies
+ */
+import type { Meta, StoryFn } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { wordpress, more, link } from '@wordpress/icons';
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import Tabs from '..';
+import { Slot, Fill, Provider as SlotFillProvider } from '../../slot-fill';
+import DropdownMenu from '../../dropdown-menu';
+import Button from '../../button';
+
+const meta: Meta< typeof Tabs > = {
+	title: 'Components (Experimental)/Tabs',
+	component: Tabs,
+	parameters: {
+		actions: { argTypesRegex: '^on.*' },
+		controls: { expanded: true },
+		docs: { canvas: { sourceState: 'shown' } },
+	},
+};
+export default meta;
+
+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.TabList>
+			<Tabs.TabPanel id={ 'tab1' }>
+				<p>Selected tab: Tab 1</p>
+			</Tabs.TabPanel>
+			<Tabs.TabPanel id={ 'tab2' }>
+				<p>Selected tab: Tab 2</p>
+			</Tabs.TabPanel>
+			<Tabs.TabPanel id={ 'tab3' }>
+				<p>Selected tab: Tab 3</p>
+			</Tabs.TabPanel>
+		</Tabs>
+	);
+};
+
+export const Default = Template.bind( {} );
+
+const DisabledTabTemplate: StoryFn< typeof Tabs > = ( props ) => {
+	return (
+		<Tabs { ...props }>
+			<Tabs.TabList>
+				<Tabs.Tab id={ 'tab1' } disabled={ true }>
+					Tab 1
+				</Tabs.Tab>
+				<Tabs.Tab id={ 'tab2' }>Tab 2</Tabs.Tab>
+				<Tabs.Tab id={ 'tab3' }>Tab 3</Tabs.Tab>
+			</Tabs.TabList>
+			<Tabs.TabPanel id={ 'tab1' }>
+				<p>Selected tab: Tab 1</p>
+			</Tabs.TabPanel>
+			<Tabs.TabPanel id={ 'tab2' }>
+				<p>Selected tab: Tab 2</p>
+			</Tabs.TabPanel>
+			<Tabs.TabPanel id={ 'tab3' }>
+				<p>Selected tab: Tab 3</p>
+			</Tabs.TabPanel>
+		</Tabs>
+	);
+};
+export const DisabledTab = DisabledTabTemplate.bind( {} );
+
+const WithTabIconsAndTooltipsTemplate: StoryFn< typeof Tabs > = ( props ) => {
+	return (
+		<Tabs { ...props }>
+			<Tabs.TabList>
+				<Tabs.Tab
+					id={ 'tab1' }
+					render={
+						<Button icon={ wordpress } label="Tab 1" showTooltip />
+					}
+				/>
+				<Tabs.Tab
+					id={ 'tab2' }
+					render={
+						<Button icon={ link } label="Tab 2" showTooltip />
+					}
+				/>
+				<Tabs.Tab
+					id={ 'tab3' }
+					render={
+						<Button icon={ more } label="Tab 3" showTooltip />
+					}
+				/>
+			</Tabs.TabList>
+			<Tabs.TabPanel id={ 'tab1' }>
+				<p>Selected tab: Tab 1</p>
+			</Tabs.TabPanel>
+			<Tabs.TabPanel id={ 'tab2' }>
+				<p>Selected tab: Tab 2</p>
+			</Tabs.TabPanel>
+			<Tabs.TabPanel id={ 'tab3' }>
+				<p>Selected tab: Tab 3</p>
+			</Tabs.TabPanel>
+		</Tabs>
+	);
+};
+export const WithTabIconsAndTooltips = WithTabIconsAndTooltipsTemplate.bind(
+	{}
+);
+
+export const ManualActivation = Template.bind( {} );
+ManualActivation.args = {
+	selectOnMove: false,
+};
+
+const UsingSlotFillTemplate: StoryFn< typeof Tabs > = ( props ) => {
+	return (
+		<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.TabList>
+				<Fill name="tabs-are-fun">
+					<Tabs.TabPanel id={ 'tab1' }>
+						<p>Selected tab: Tab 1</p>
+					</Tabs.TabPanel>
+					<Tabs.TabPanel id={ 'tab2' }>
+						<p>Selected tab: Tab 2</p>
+					</Tabs.TabPanel>
+					<Tabs.TabPanel id={ 'tab3' }>
+						<p>Selected tab: Tab 3</p>
+					</Tabs.TabPanel>
+				</Fill>
+			</Tabs>
+			<div
+				style={ {
+					border: '2px solid #999',
+					width: '300px',
+					margin: '20px auto',
+				} }
+			>
+				<p>other stuff</p>
+				<p>other stuff</p>
+				<p>this is fun!</p>
+				<p>other stuff</p>
+				<Slot bubblesVirtually as="div" name="tabs-are-fun" />
+			</div>
+		</SlotFillProvider>
+	);
+};
+export const UsingSlotFill = UsingSlotFillTemplate.bind( {} );
+UsingSlotFill.storyName = 'Using SlotFill';
+
+const CloseButtonTemplate: StoryFn< typeof Tabs > = ( props ) => {
+	const [ isOpen, setIsOpen ] = useState( true );
+
+	return (
+		<>
+			{ isOpen ? (
+				<div
+					style={ {
+						width: '400px',
+						height: '100vh',
+						borderRight: '1px solid #333',
+					} }
+				>
+					<Tabs { ...props }>
+						<div
+							style={ {
+								display: 'flex',
+								borderBottom: '1px solid #333',
+							} }
+						>
+							<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.TabList>
+							<Button
+								variant={ 'tertiary' }
+								style={ {
+									marginLeft: 'auto',
+									alignSelf: 'center',
+								} }
+								onClick={ () => setIsOpen( false ) }
+							>
+								Close Tabs
+							</Button>
+						</div>
+						<Tabs.TabPanel id={ 'tab1' }>
+							<p>Selected tab: Tab 1</p>
+						</Tabs.TabPanel>
+						<Tabs.TabPanel id={ 'tab2' }>
+							<p>Selected tab: Tab 2</p>
+						</Tabs.TabPanel>
+						<Tabs.TabPanel id={ 'tab3' }>
+							<p>Selected tab: Tab 3</p>
+						</Tabs.TabPanel>
+					</Tabs>
+				</div>
+			) : (
+				<Button
+					variant={ 'tertiary' }
+					onClick={ () => setIsOpen( true ) }
+				>
+					Open Tabs
+				</Button>
+			) }
+		</>
+	);
+};
+export const InsertCustomElements = CloseButtonTemplate.bind( {} );
+
+const ControlledModeTemplate: StoryFn< typeof Tabs > = ( props ) => {
+	const [ selectedTabId, setSelectedTabId ] = useState<
+		string | undefined | null
+	>( props.selectedTabId );
+
+	return (
+		<>
+			<Tabs
+				{ ...props }
+				selectedTabId={ selectedTabId }
+				onSelect={ ( selectedId ) => {
+					setSelectedTabId( selectedId );
+					props.onSelect?.( selectedId );
+				} }
+			>
+				<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.TabList>
+				<Tabs.TabPanel id={ 'tab1' }>
+					<p>Selected tab: Tab 1</p>
+				</Tabs.TabPanel>
+				<Tabs.TabPanel id={ 'tab2' }>
+					<p>Selected tab: Tab 2</p>
+				</Tabs.TabPanel>
+				<Tabs.TabPanel id={ 'tab3' }>
+					<p>Selected tab: Tab 3</p>
+				</Tabs.TabPanel>
+			</Tabs>
+			{
+				<div style={ { marginTop: '200px' } }>
+					<p>Select a tab:</p>
+					<DropdownMenu
+						controls={ [
+							{
+								onClick: () => setSelectedTabId( 'tab1' ),
+								title: 'Tab 1',
+								isActive: selectedTabId === 'tab1',
+							},
+							{
+								onClick: () => setSelectedTabId( 'tab2' ),
+								title: 'Tab 2',
+								isActive: selectedTabId === 'tab2',
+							},
+							{
+								onClick: () => setSelectedTabId( 'tab3' ),
+								title: 'Tab 3',
+								isActive: selectedTabId === 'tab3',
+							},
+						] }
+						label="Choose a tab. The power is yours."
+					/>
+				</div>
+			}
+		</>
+	);
+};
+
+export const ControlledMode = ControlledModeTemplate.bind( {} );
+ControlledMode.args = {
+	selectedTabId: 'tab3',
+};
+
+const TabBecomesDisabledTemplate: StoryFn< typeof Tabs > = ( props ) => {
+	const [ disableTab2, setDisableTab2 ] = useState( false );
+
+	return (
+		<>
+			<Button
+				variant="primary"
+				onClick={ () => setDisableTab2( ! disableTab2 ) }
+			>
+				{ disableTab2 ? 'Enable' : 'Disable' } Tab 2
+			</Button>
+			<Tabs { ...props }>
+				<Tabs.TabList>
+					<Tabs.Tab id={ 'tab1' }>Tab 1</Tabs.Tab>
+					<Tabs.Tab id={ 'tab2' } disabled={ disableTab2 }>
+						Tab 2
+					</Tabs.Tab>
+					<Tabs.Tab id={ 'tab3' }>Tab 3</Tabs.Tab>
+				</Tabs.TabList>
+				<Tabs.TabPanel id={ 'tab1' }>
+					<p>Selected tab: Tab 1</p>
+				</Tabs.TabPanel>
+				<Tabs.TabPanel id={ 'tab2' }>
+					<p>Selected tab: Tab 2</p>
+				</Tabs.TabPanel>
+				<Tabs.TabPanel id={ 'tab3' }>
+					<p>Selected tab: Tab 3</p>
+				</Tabs.TabPanel>
+			</Tabs>
+		</>
+	);
+};
+export const TabBecomesDisabled = TabBecomesDisabledTemplate.bind( {} );
+
+const TabGetsRemovedTemplate: StoryFn< typeof Tabs > = ( props ) => {
+	const [ removeTab1, setRemoveTab1 ] = useState( false );
+
+	return (
+		<>
+			<Button
+				variant="primary"
+				onClick={ () => setRemoveTab1( ! removeTab1 ) }
+			>
+				{ removeTab1 ? 'Restore' : 'Remove' } Tab 1
+			</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>
+				</Tabs.TabList>
+				<Tabs.TabPanel id={ 'tab1' }>
+					<p>Selected tab: Tab 1</p>
+				</Tabs.TabPanel>
+				<Tabs.TabPanel id={ 'tab2' }>
+					<p>Selected tab: Tab 2</p>
+				</Tabs.TabPanel>
+				<Tabs.TabPanel id={ 'tab3' }>
+					<p>Selected tab: Tab 3</p>
+				</Tabs.TabPanel>
+			</Tabs>
+		</>
+	);
+};
+export const TabGetsRemoved = TabGetsRemovedTemplate.bind( {} );

package/src/tabs/styles.ts

@@ -0,0 +1,103 @@
+/**
+ * External dependencies
+ */
+import styled from '@emotion/styled';
+// eslint-disable-next-line no-restricted-imports
+import * as Ariakit from '@ariakit/react';
+
+/**
+ * Internal dependencies
+ */
+import { COLORS } from '../utils';
+import { space } from '../utils/space';
+import { reduceMotion } from '../utils/reduce-motion';
+
+export const TabListWrapper = styled.div`
+	display: flex;
+	align-items: stretch;
+	flex-direction: row;
+	&[aria-orientation='vertical'] {
+		flex-direction: column;
+	}
+`;
+
+export const Tab = styled( Ariakit.Tab )`
+	&& {
+		position: relative;
+		border-radius: 0;
+		height: ${ space( 12 ) };
+		background: transparent;
+		border: none;
+		box-shadow: none;
+		cursor: pointer;
+		padding: 3px ${ space( 4 ) }; // Use padding to offset the [aria-selected="true"] border, this benefits Windows High Contrast mode
+		margin-left: 0;
+		font-weight: 500;
+
+		&[aria-disabled='true'] {
+			cursor: default;
+			opacity: 0.3;
+		}
+
+		&:focus:not( :disabled ) {
+			position: relative;
+			box-shadow: none;
+			outline: none;
+		}
+
+		// Tab indicator
+		&::after {
+			content: '';
+			position: absolute;
+			right: 0;
+			bottom: 0;
+			left: 0;
+			pointer-events: none;
+
+			// Draw the indicator.
+			background: ${ COLORS.theme.accent };
+			height: calc( 0 * var( --wp-admin-border-width-focus ) );
+			border-radius: 0;
+
+			// Animation
+			transition: all 0.1s linear;
+			${ reduceMotion( 'transition' ) };
+		}
+
+		// Active.
+		&[aria-selected='true']::after {
+			height: calc( 1 * var( --wp-admin-border-width-focus ) );
+
+			// Windows high contrast mode.
+			outline: 2px solid transparent;
+			outline-offset: -1px;
+		}
+
+		// Focus.
+		&::before {
+			content: '';
+			position: absolute;
+			top: ${ space( 3 ) };
+			right: ${ space( 3 ) };
+			bottom: ${ space( 3 ) };
+			left: ${ space( 3 ) };
+			pointer-events: none;
+
+			// Draw the indicator.
+			box-shadow: 0 0 0 0 transparent;
+			border-radius: 2px;
+
+			// Animation
+			transition: all 0.1s linear;
+			${ reduceMotion( 'transition' ) };
+		}
+
+		&:focus-visible::before {
+			box-shadow: 0 0 0 var( --wp-admin-border-width-focus )
+				${ COLORS.theme.accent };
+
+			// Windows high contrast mode.
+			outline: 2px solid transparent;
+		}
+	}
+`;

package/src/tabs/tab.tsx

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

package/src/tabs/tablist.tsx

@@ -0,0 +1,40 @@
+/**
+ * External dependencies
+ */
+// eslint-disable-next-line no-restricted-imports
+import * as Ariakit from '@ariakit/react';
+
+/**
+ * WordPress dependencies
+ */
+import warning from '@wordpress/warning';
+import { forwardRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { TabListProps } from './types';
+import { useTabsContext } from './context';
+import { TabListWrapper } from './styles';
+
+export const TabList = forwardRef< HTMLDivElement, TabListProps >(
+	function TabList( { children, className, style }, ref ) {
+		const context = useTabsContext();
+		if ( ! context ) {
+			warning( '`Tabs.TabList` must be wrapped in a `Tabs` component.' );
+			return null;
+		}
+		const { store } = context;
+		return (
+			<Ariakit.TabList
+				ref={ ref }
+				style={ style }
+				store={ store }
+				className={ className }
+				render={ <TabListWrapper /> }
+			>
+				{ children }
+			</Ariakit.TabList>
+		);
+	}
+);