@wordpress/ui 0.6.0 → 0.7.1-next.v.0

package/src/icon-button/types.ts

@@ -0,0 +1,38 @@
+import { type ButtonProps } from '../button/types';
+import { type IconProps } from '../icon/types';
+
+export type IconButtonProps = Omit< ButtonProps, 'children' > & {
+	/**
+	 * A label describing the button's action, shown as a tooltip and to
+	 * assistive technology.
+	 */
+	label: string;
+
+	/**
+	 * The icon to display in the button.
+	 */
+	icon: IconProps[ 'icon' ];
+
+	/**
+	 * The keyboard shortcut associated with this button. When provided, the
+	 * shortcut is displayed in the tooltip and announced to assistive technology.
+	 *
+	 * **Note**: This prop is for display and accessibility purposes only — the
+	 * consumer is responsible for implementing the actual keyboard event handler.
+	 */
+	shortcut?: {
+		/**
+		 * The human-readable representation of the shortcut, displayed in the
+		 * tooltip. Use platform-appropriate symbols (e.g., "⌘S" on macOS,
+		 * "Ctrl+S" on Windows).
+		 */
+		displayShortcut: string;
+		/**
+		 * The shortcut in a format compatible with the
+		 * [aria-keyshortcuts](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-keyshortcuts)
+		 * attribute. Use "+" to separate keys and standard key names
+		 * (e.g., "Meta+S", "Control+Shift+P").
+		 */
+		ariaKeyShortcut: string;
+	};
+};

package/src/index.ts

@@ -3,6 +3,8 @@ export * from './box';
 export * from './button';
 export * from './form/primitives';
 export * from './icon';
+export * from './icon-button';
 export * from './stack';
+export * as Tabs from './tabs';
 export * as Tooltip from './tooltip';
 export * from './visually-hidden';

package/src/tabs/index.ts

@@ -0,0 +1,6 @@
+import { List } from './list';
+import { Panel } from './panel';
+import { Root } from './root';
+import { Tab } from './tab';
+
+export { Root, List, Panel, Tab };

package/src/tabs/list.tsx

@@ -0,0 +1,130 @@
+import { forwardRef, useEffect, useState } from '@wordpress/element';
+import clsx from 'clsx';
+import { Tabs as _Tabs } from '@base-ui/react/tabs';
+import { useMergeRefs } from '@wordpress/compose';
+import styles from './style.module.css';
+import type { TabListProps } from './types';
+
+// Account for sub-pixel rounding errors.
+const SCROLL_EPSILON = 1;
+
+/**
+ * Groups the individual tab buttons.
+ *
+ * `Tabs` is a collection of React components that combine to render
+ * an [ARIA-compliant tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/).
+ */
+export const List = forwardRef< HTMLDivElement, TabListProps >(
+	function TabList(
+		{
+			children,
+			variant = 'default',
+			className,
+			activateOnFocus,
+			render,
+			...otherProps
+		},
+		forwardedRef
+	) {
+		const [ listEl, setListEl ] = useState< HTMLDivElement | null >( null );
+		const [ overflow, setOverflow ] = useState< {
+			first: boolean;
+			last: boolean;
+			isScrolling: boolean;
+		} >( {
+			first: false,
+			last: false,
+			isScrolling: false,
+		} );
+
+		// Check if list is overflowing when it scrolls or resizes.
+		useEffect( () => {
+			if ( ! listEl ) {
+				return;
+			}
+
+			const measureOverflow = () => {
+				const { scrollWidth, clientWidth, scrollLeft } = listEl;
+				const maxScroll = Math.max( scrollWidth - clientWidth, 0 );
+				const direction =
+					listEl.dir ||
+					( typeof window !== 'undefined'
+						? window.getComputedStyle( listEl ).direction
+						: 'ltr' );
+
+				const scrollFromStart =
+					direction === 'rtl' && scrollLeft < 0
+						? // In RTL layouts, scrollLeft is typically 0 at the visual "start"
+						  // (right edge) and becomes negative toward the "end" (left edge).
+						  // Normalize value for correct first/last detection logic.
+						  -scrollLeft
+						: scrollLeft;
+
+				// Use SCROLL_EPSILON to handle subpixel rendering differences.
+				setOverflow( {
+					first: scrollFromStart > SCROLL_EPSILON,
+					last: scrollFromStart < maxScroll - SCROLL_EPSILON,
+					isScrolling: scrollWidth > clientWidth,
+				} );
+			};
+
+			const resizeObserver = new ResizeObserver( measureOverflow );
+			resizeObserver.observe( listEl );
+
+			let scrollTick = false;
+			const throttleMeasureOverflowOnScroll = () => {
+				if ( ! scrollTick ) {
+					requestAnimationFrame( () => {
+						measureOverflow();
+						scrollTick = false;
+					} );
+					scrollTick = true;
+				}
+			};
+			listEl.addEventListener(
+				'scroll',
+				throttleMeasureOverflowOnScroll,
+				{ passive: true }
+			);
+
+			// Initial check.
+			measureOverflow();
+
+			return () => {
+				listEl.removeEventListener(
+					'scroll',
+					throttleMeasureOverflowOnScroll
+				);
+				resizeObserver.disconnect();
+			};
+		}, [ listEl ] );
+
+		const mergedListRef = useMergeRefs( [
+			forwardedRef,
+			( el: HTMLDivElement | null ) => setListEl( el ),
+		] );
+
+		return (
+			<_Tabs.List
+				ref={ mergedListRef }
+				activateOnFocus={ activateOnFocus }
+				data-select-on-move={ activateOnFocus ? 'true' : 'false' }
+				className={ clsx(
+					styles.tablist,
+					overflow.first && styles[ 'is-overflowing-first' ],
+					overflow.last && styles[ 'is-overflowing-last' ],
+					styles[ `is-${ variant }-variant` ],
+					className
+				) }
+				{ ...otherProps }
+				tabIndex={
+					otherProps.tabIndex ??
+					( overflow.isScrolling ? -1 : undefined )
+				}
+			>
+				{ children }
+				<_Tabs.Indicator className={ styles.indicator } />
+			</_Tabs.List>
+		);
+	}
+);

package/src/tabs/panel.tsx

@@ -0,0 +1,23 @@
+import { forwardRef } from '@wordpress/element';
+import clsx from 'clsx';
+import { Tabs as _Tabs } from '@base-ui/react/tabs';
+import styles from './style.module.css';
+import type { TabPanelProps } from './types';
+
+/**
+ * A panel displayed when the corresponding tab is active.
+ *
+ * `Tabs` is a collection of React components that combine to render
+ * an [ARIA-compliant tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/).
+ */
+export const Panel = forwardRef< HTMLDivElement, TabPanelProps >(
+	function TabPanel( { className, ...otherProps }, forwardedRef ) {
+		return (
+			<_Tabs.Panel
+				ref={ forwardedRef }
+				className={ clsx( styles.tabpanel, className ) }
+				{ ...otherProps }
+			/>
+		);
+	}
+);

package/src/tabs/root.tsx

@@ -0,0 +1,15 @@
+import { forwardRef } from '@wordpress/element';
+import { Tabs as _Tabs } from '@base-ui/react/tabs';
+import type { TabRootProps } from './types';
+
+/**
+ * Groups the tabs and the corresponding panels.
+ *
+ * `Tabs` is a collection of React components that combine to render
+ * an [ARIA-compliant tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/).
+ */
+export const Root = forwardRef< HTMLDivElement, TabRootProps >(
+	function TabsRoot( { ...otherProps }, forwardedRef ) {
+		return <_Tabs.Root ref={ forwardedRef } { ...otherProps } />;
+	}
+);

package/src/tabs/stories/best-practices.mdx

@@ -0,0 +1,85 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Design System/Components/Tabs/Best Practices" />
+
+# Tabs
+
+## Usage
+
+### Uncontrolled Mode
+
+`Tabs` can be used in an uncontrolled mode, where the component manages its own state. In this mode, the `defaultValue` prop can be used to set the initially selected tab.
+
+```jsx
+import { Tabs } from '@wordpress/ui';
+
+const MyUncontrolledTabs = () => (
+	<Tabs.Root
+		onValueChange={ ( tab ) => console.log( 'New selected tab: ', tab ) }
+		defaultValue="tab2"
+	>
+		<Tabs.List>
+			<Tabs.Tab value="tab1">Tab 1</Tabs.Tab>
+			<Tabs.Tab value="tab2">Tab 2</Tabs.Tab>
+			<Tabs.Tab value="tab3">Tab 3</Tabs.Tab>
+		</Tabs.List>
+		<Tabs.Panel value="tab1">
+			<p>Selected tab: Tab 1</p>
+		</Tabs.Panel>
+		<Tabs.Panel value="tab2">
+			<p>Selected tab: Tab 2</p>
+		</Tabs.Panel>
+		<Tabs.Panel value="tab3">
+			<p>Selected tab: Tab 3</p>
+		</Tabs.Panel>
+	</Tabs.Root>
+);
+```
+
+### Controlled Mode
+
+Tabs can also be used in a controlled mode, where the parent component uses the `value` and `onValueChange` props to control tab selection. In this mode, the `defaultValue` prop will be ignored if it is provided. To indicate that no tabs are selected, pass `null` to the `value`.
+
+```tsx
+import { useState } from 'react';
+import { Tabs } from '@wordpress/ui';
+
+const MyControlledTabs = () => {
+	const [ selectedTabId, setSelectedTabId ] = useState<
+		string | undefined | null
+	>( null );
+
+	return (
+		<Tabs.Root
+			value={ selectedTabId }
+			onValueChange={ ( newSelectedTabId ) => {
+				setSelectedTabId( newSelectedTabId );
+				console.log( 'Selecting tab', newSelectedTabId );
+			} }
+		>
+			<Tabs.List>
+				<Tabs.Tab value="tab1">Tab 1</Tabs.Tab>
+				<Tabs.Tab value="tab2">Tab 2</Tabs.Tab>
+				<Tabs.Tab value="tab3">Tab 3</Tabs.Tab>
+			</Tabs.List>
+			<Tabs.Panel value="tab1">
+				<p>Selected tab: Tab 1</p>
+			</Tabs.Panel>
+			<Tabs.Panel value="tab2">
+				<p>Selected tab: Tab 2</p>
+			</Tabs.Panel>
+			<Tabs.Panel value="tab3">
+				<p>Selected tab: Tab 3</p>
+			</Tabs.Panel>
+		</Tabs.Root>
+	);
+};
+```
+
+### Using `Tabs` with links
+
+The semantics implemented by the `Tabs` component don't align well with the semantics needed by a list of links. Furthermore, end users usually expect every link to be tabbable, while `Tabs.List` is a [composite](https://w3c.github.io/aria/#composite) widget acting as a single tab stop.
+
+For these reasons, even if the `Tabs` component is fully extensible, we don't recommend using `Tabs` with links, and we don't currently provide any related Storybook example.
+
+We may provide a dedicated component for tabs-like links in the future based on the feedback received.

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

@@ -0,0 +1,363 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useState, cloneElement } from '@wordpress/element';
+import { link, more, wordpress } from '@wordpress/icons';
+import { Tabs, Tooltip } from '../..';
+
+const meta: Meta< typeof Tabs.Root > = {
+	title: 'Design System/Components/Tabs',
+	component: Tabs.Root,
+	subcomponents: {
+		'Tabs.List': Tabs.List,
+		'Tabs.Tab': Tabs.Tab,
+		'Tabs.Panel': Tabs.Panel,
+	},
+};
+export default meta;
+
+const ThemedParagraph = ( { children }: { children: React.ReactNode } ) => {
+	return (
+		<p style={ { color: 'var( --wpds-color-fg-content-neutral )' } }>
+			{ children }
+		</p>
+	);
+};
+
+export const Default: StoryObj< typeof Tabs.Root > = {
+	args: {
+		defaultValue: 'tab1',
+		children: (
+			<>
+				<Tabs.List>
+					<Tabs.Tab value="tab1">Tab 1</Tabs.Tab>
+					<Tabs.Tab value="tab2">Tab 2</Tabs.Tab>
+					<Tabs.Tab value="tab3">Tab 3</Tabs.Tab>
+				</Tabs.List>
+				<Tabs.Panel value="tab1">
+					<ThemedParagraph>Selected tab: Tab 1</ThemedParagraph>
+				</Tabs.Panel>
+				<Tabs.Panel value="tab2">
+					<ThemedParagraph>Selected tab: Tab 2</ThemedParagraph>
+				</Tabs.Panel>
+				<Tabs.Panel value="tab3">
+					<ThemedParagraph>Selected tab: Tab 3</ThemedParagraph>
+				</Tabs.Panel>
+			</>
+		),
+	},
+};
+
+export const Minimal: StoryObj< typeof Tabs.Root > = {
+	args: {
+		...Default.args,
+		children: (
+			<>
+				<Tabs.List variant="minimal">
+					<Tabs.Tab value="tab1">Tab 1</Tabs.Tab>
+					<Tabs.Tab value="tab2">Tab 2</Tabs.Tab>
+					<Tabs.Tab value="tab3">Tab 3</Tabs.Tab>
+				</Tabs.List>
+				<Tabs.Panel value="tab1">
+					<ThemedParagraph>Selected tab: Tab 1</ThemedParagraph>
+				</Tabs.Panel>
+				<Tabs.Panel value="tab2">
+					<ThemedParagraph>Selected tab: Tab 2</ThemedParagraph>
+				</Tabs.Panel>
+				<Tabs.Panel value="tab3">
+					<ThemedParagraph>Selected tab: Tab 3</ThemedParagraph>
+				</Tabs.Panel>
+			</>
+		),
+	},
+};
+
+export const SizeAndOverflowPlayground: StoryObj< typeof Tabs.Root > = {
+	render: function SizeAndOverflowPlayground( props ) {
+		const [ fullWidth, setFullWidth ] = useState( false );
+		return (
+			<div>
+				<div
+					style={ {
+						maxWidth: '40rem',
+						marginBottom: '1rem',
+						color: 'var( --wpds-color-fg-content-neutral )',
+					} }
+				>
+					<p>
+						This story helps understand how the TabList component
+						behaves under different conditions. The container below
+						(with the dotted red border) can be horizontally
+						resized, and it has a bit of padding to be out of the
+						way of the TabList.
+					</p>
+					<p>
+						The button will toggle between full width (adding{ ' ' }
+						<code>width: 100%</code>) and the default width.
+					</p>
+					<p>Try the following:</p>
+					<ul>
+						<li>
+							<strong>Small container</strong> that causes tabs to
+							overflow with scroll.
+						</li>
+						<li>
+							<strong>Large container</strong> that exceeds the
+							normal width of the tabs.
+							<ul>
+								<li>
+									<strong>
+										With <code>width: 100%</code>
+									</strong>{ ' ' }
+									set on the TabList (tabs fill up the space).
+								</li>
+								<li>
+									<strong>
+										Without <code>width: 100%</code>
+									</strong>{ ' ' }
+									(defaults to <code>auto</code>) set on the
+									TabList (tabs take up space proportional to
+									their content).
+								</li>
+							</ul>
+						</li>
+					</ul>
+				</div>
+				<button
+					style={ { marginBottom: '1rem' } }
+					onClick={ () => setFullWidth( ! fullWidth ) }
+				>
+					{ fullWidth
+						? 'Remove width: 100% from TabList'
+						: 'Set width: 100% in TabList' }
+				</button>
+				<Tabs.Root
+					{ ...props }
+					style={ {
+						...props.style,
+						width: '20rem',
+						border: '2px dotted red',
+						padding: '1rem',
+						resize: 'horizontal',
+						overflow: 'auto',
+					} }
+				>
+					<Tabs.List
+						style={ {
+							maxWidth: '100%',
+							width: fullWidth ? '100%' : undefined,
+						} }
+					>
+						<Tabs.Tab value="tab1">
+							Label with multiple words
+						</Tabs.Tab>
+						<Tabs.Tab value="tab2">Short</Tabs.Tab>
+						<Tabs.Tab value="tab3">
+							Hippopotomonstrosesquippedaliophobia
+						</Tabs.Tab>
+						<Tabs.Tab value="tab4">Tab 4</Tabs.Tab>
+						<Tabs.Tab value="tab5">Tab 5</Tabs.Tab>
+					</Tabs.List>
+
+					<Tabs.Panel value="tab1">
+						<ThemedParagraph>Selected tab: Tab 1</ThemedParagraph>
+						<ThemedParagraph>
+							(Label with multiple words)
+						</ThemedParagraph>
+					</Tabs.Panel>
+					<Tabs.Panel value="tab2">
+						<ThemedParagraph>Selected tab: Tab 2</ThemedParagraph>
+						<ThemedParagraph>(Short)</ThemedParagraph>
+					</Tabs.Panel>
+					<Tabs.Panel value="tab3">
+						<ThemedParagraph>Selected tab: Tab 3</ThemedParagraph>
+						<ThemedParagraph>
+							(Hippopotomonstrosesquippedaliophobia)
+						</ThemedParagraph>
+					</Tabs.Panel>
+					<Tabs.Panel value="tab4">
+						<ThemedParagraph>Selected tab: Tab 4</ThemedParagraph>
+					</Tabs.Panel>
+					<Tabs.Panel value="tab5">
+						<ThemedParagraph>Selected tab: Tab 5</ThemedParagraph>
+					</Tabs.Panel>
+				</Tabs.Root>
+			</div>
+		);
+	},
+	args: {
+		...Default.args,
+		defaultValue: 'tab4',
+	},
+};
+
+export const Vertical: StoryObj< typeof Tabs.Root > = {
+	args: {
+		...Default.args,
+		orientation: 'vertical',
+		style: {
+			minWidth: '320px',
+			display: 'grid',
+			gridTemplateColumns: '120px 1fr',
+			gap: '24px',
+		},
+	},
+};
+
+export const WithDisabledTab: StoryObj< typeof Tabs.Root > = {
+	args: {
+		...Default.args,
+		defaultValue: 'tab3',
+		children: (
+			<>
+				<Tabs.List>
+					<Tabs.Tab value="tab1" disabled>
+						Tab 1
+					</Tabs.Tab>
+					<Tabs.Tab value="tab2">Tab 2</Tabs.Tab>
+					<Tabs.Tab value="tab3">Tab 3</Tabs.Tab>
+				</Tabs.List>
+				<Tabs.Panel value="tab1">
+					<ThemedParagraph>Selected tab: Tab 1</ThemedParagraph>
+				</Tabs.Panel>
+				<Tabs.Panel value="tab2">
+					<ThemedParagraph>Selected tab: Tab 2</ThemedParagraph>
+				</Tabs.Panel>
+				<Tabs.Panel value="tab3">
+					<ThemedParagraph>Selected tab: Tab 3</ThemedParagraph>
+				</Tabs.Panel>
+			</>
+		),
+	},
+};
+
+const LinkIcon = ( props: React.SVGProps< SVGSVGElement > ) => {
+	return cloneElement( link, props );
+};
+
+const MoreIcon = ( props: React.SVGProps< SVGSVGElement > ) => {
+	return cloneElement( more, props );
+};
+
+const WordpressIcon = ( props: React.SVGProps< SVGSVGElement > ) => {
+	return cloneElement( wordpress, props );
+};
+
+const tabWithIconsData = [
+	{
+		value: 'tab1',
+		label: 'Tab one',
+		icon: WordpressIcon,
+	},
+	{
+		value: 'tab2',
+		label: 'Tab two',
+		icon: LinkIcon,
+	},
+	{
+		value: 'tab3',
+		label: 'Tab three',
+		icon: MoreIcon,
+	},
+];
+
+export const WithTabIconsAndTooltips: StoryObj< typeof Tabs.Root > = {
+	args: {
+		...Default.args,
+		children: (
+			<>
+				<Tabs.List>
+					{ tabWithIconsData.map(
+						( { value, label, icon: Icon } ) => (
+							<Tooltip.Root key={ value }>
+								<Tooltip.Trigger
+									aria-label={ label }
+									render={ <Tabs.Tab value={ value } /> }
+								>
+									{ /* TODO: potentially refactor with new Icon component */ }
+									<Icon
+										style={ {
+											width: '20px',
+											height: '20px',
+										} }
+									/>
+								</Tooltip.Trigger>
+								<Tooltip.Popup align="center" side="top">
+									{ label }
+								</Tooltip.Popup>
+							</Tooltip.Root>
+						)
+					) }
+				</Tabs.List>
+				{ tabWithIconsData.map( ( { value, label } ) => (
+					<Tabs.Panel value={ value } key={ value }>
+						<ThemedParagraph>
+							Selected tab: { label }
+						</ThemedParagraph>
+					</Tabs.Panel>
+				) ) }
+			</>
+		),
+	},
+};
+
+export const WithPanelsAlwaysMounted: StoryObj< typeof Tabs.Root > = {
+	args: {
+		...Default.args,
+		children: (
+			<>
+				<Tabs.List>
+					<Tabs.Tab value="tab1">Tab 1</Tabs.Tab>
+					<Tabs.Tab value="tab2">Tab 2</Tabs.Tab>
+					<Tabs.Tab value="tab3">Tab 3</Tabs.Tab>
+				</Tabs.List>
+				<Tabs.Panel value="tab1" keepMounted>
+					<ThemedParagraph>Selected tab: Tab 1</ThemedParagraph>
+				</Tabs.Panel>
+				<Tabs.Panel value="tab2" keepMounted>
+					<ThemedParagraph>Selected tab: Tab 2</ThemedParagraph>
+				</Tabs.Panel>
+				<Tabs.Panel value="tab3" keepMounted>
+					<ThemedParagraph>Selected tab: Tab 3</ThemedParagraph>
+				</Tabs.Panel>
+			</>
+		),
+	},
+};
+
+export const WithNonFocusablePanels: StoryObj< typeof Tabs.Root > = {
+	args: {
+		...Default.args,
+		children: (
+			<>
+				<Tabs.List>
+					<Tabs.Tab value="tab1">Tab 1</Tabs.Tab>
+					<Tabs.Tab value="tab2">Tab 2</Tabs.Tab>
+					<Tabs.Tab value="tab3">Tab 3</Tabs.Tab>
+				</Tabs.List>
+				<Tabs.Panel value="tab1" tabIndex={ -1 }>
+					<ThemedParagraph>Selected tab: Tab 1</ThemedParagraph>
+					<ThemedParagraph>
+						This tabpanel is not focusable, therefore tabbing into
+						it will focus its first tabbable child.
+					</ThemedParagraph>
+					<button>Focus me</button>
+				</Tabs.Panel>
+				<Tabs.Panel value="tab2" tabIndex={ -1 }>
+					<ThemedParagraph>Selected tab: Tab 2</ThemedParagraph>
+					<ThemedParagraph>
+						This tabpanel is not focusable, therefore tabbing into
+						it will focus its first tabbable child.
+					</ThemedParagraph>
+					<button>Focus me</button>
+				</Tabs.Panel>
+				<Tabs.Panel value="tab3" tabIndex={ -1 }>
+					<ThemedParagraph>Selected tab: Tab 3</ThemedParagraph>
+					<ThemedParagraph>
+						This tabpanel is not focusable, therefore tabbing into
+						it will focus its first tabbable child.
+					</ThemedParagraph>
+					<button>Focus me</button>
+				</Tabs.Panel>
+			</>
+		),
+	},
+};