@wordpress/components 25.11.1-next.f8d8eceb.0 → 25.13.0

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 },
@@ -42,8 +50,16 @@ const Template: StoryFn< typeof Tabs > = ( props ) => {
 			<Tabs.TabPanel id={ 'tab2' }>
 				<p>Selected tab: Tab 2</p>
 			</Tabs.TabPanel>
-			<Tabs.TabPanel id={ 'tab3' }>
+			<Tabs.TabPanel id={ 'tab3' } focusable={ false }>
 				<p>Selected tab: Tab 3</p>
+				<p>
+					This tabpanel has its <code>focusable</code> prop set to
+					<code> false</code>, so it won&apos;t get a tab stop.
+					<br />
+					Instead, the [Tab] key will move focus to the first
+					focusable element within the panel.
+				</p>
+				<Button variant="primary">I&apos;m a button!</Button>
 			</Tabs.TabPanel>
 		</Tabs>
 	);

package/src/tabs/styles.ts

@@ -101,3 +101,19 @@ export const Tab = styled( Ariakit.Tab )`
 		}
 	}
 `;
+
+export const TabPanel = styled( Ariakit.TabPanel )`
+	&:focus {
+		box-shadow: none;
+		outline: none;
+	}
+
+	&:focus-visible {
+		border-radius: 2px;
+		box-shadow: 0 0 0 var( --wp-admin-border-width-focus )
+			${ COLORS.theme.accent };
+		// Windows high contrast mode.
+		outline: 2px solid transparent;
+		outline-offset: 0;
+	}
+`;

package/src/tabs/tab.tsx

@@ -2,23 +2,24 @@
  * 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, TabProps >( function Tab(
-	{ children, id, className, disabled, render, style },
-	ref
-) {
-	const context = useContext( TabsContext );
+export const Tab = forwardRef<
+	HTMLButtonElement,
+	WordPressComponentProps< TabProps, 'button', false >
+>( function Tab( { children, id, 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;
@@ -28,10 +29,9 @@ export const Tab = forwardRef< HTMLButtonElement, TabProps >( function Tab(
 			ref={ ref }
 			store={ store }
 			id={ instancedTabId }
-			className={ className }
-			style={ style }
 			disabled={ disabled }
 			render={ render }
+			{ ...otherProps }
 		>
 			{ children }
 		</StyledTab>

package/src/tabs/tablist.tsx

@@ -16,25 +16,26 @@ import { forwardRef } from '@wordpress/element';
 import type { TabListProps } from './types';
 import { useTabsContext } from './context';
 import { TabListWrapper } from './styles';
+import type { WordPressComponentProps } from '../context';
 
-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>
-		);
+export const TabList = forwardRef<
+	HTMLDivElement,
+	WordPressComponentProps< TabListProps, 'div', false >
+>( function TabList( { children, ...otherProps }, 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 }
+			store={ store }
+			render={ <TabListWrapper /> }
+			{ ...otherProps }
+		>
+			{ children }
+		</Ariakit.TabList>
+	);
+} );

package/src/tabs/tabpanel.tsx

@@ -1,42 +1,43 @@
 /**
  * External dependencies
  */
-// eslint-disable-next-line no-restricted-imports
-import * as Ariakit from '@ariakit/react';
 
 /**
  * WordPress dependencies
  */
 
-import { forwardRef, useContext } from '@wordpress/element';
+import { forwardRef } from '@wordpress/element';
 
 /**
  * Internal dependencies
  */
 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, TabPanelProps >(
-	function TabPanel( { children, id, className, style }, ref ) {
-		const context = useContext( TabsContext );
-		if ( ! context ) {
-			warning( '`Tabs.TabPanel` must be wrapped in a `Tabs` component.' );
-			return null;
-		}
-		const { store, instanceId } = context;
-
-		return (
-			<Ariakit.TabPanel
-				ref={ ref }
-				style={ style }
-				store={ store }
-				id={ `${ instanceId }-${ id }-view` }
-				className={ className }
-			>
-				{ children }
-			</Ariakit.TabPanel>
-		);
+export const TabPanel = forwardRef<
+	HTMLDivElement,
+	WordPressComponentProps< TabPanelProps, 'div', false >
+>( function TabPanel( { children, id, 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;
+
+	return (
+		<StyledTabPanel
+			ref={ ref }
+			store={ store }
+			id={ `${ instanceId }-${ id }-view` }
+			focusable={ focusable }
+			{ ...otherProps }
+		>
+			{ children }
+		</StyledTabPanel>
+	);
+} );

package/src/tabs/test/index.tsx

@@ -7,7 +7,6 @@ import userEvent from '@testing-library/user-event';
 /**
  * WordPress dependencies
  */
-import { wordpress, category, media } from '@wordpress/icons';
 import { useState } from '@wordpress/element';
 
 /**
@@ -15,7 +14,6 @@ import { useState } from '@wordpress/element';
  */
 import Tabs from '..';
 import type { TabsProps } from '../types';
-import type { IconType } from '../../icon';
 
 type Tab = {
 	id: string;
@@ -23,9 +21,11 @@ type Tab = {
 	content: React.ReactNode;
 	tab: {
 		className?: string;
-		icon?: IconType;
 		disabled?: boolean;
 	};
+	tabpanel?: {
+		focusable?: boolean;
+	};
 };
 
 const TABS: Tab[] = [
@@ -33,19 +33,19 @@ const TABS: Tab[] = [
 		id: 'alpha',
 		title: 'Alpha',
 		content: 'Selected tab: Alpha',
-		tab: { className: 'alpha-class', icon: wordpress },
+		tab: { className: 'alpha-class' },
 	},
 	{
 		id: 'beta',
 		title: 'Beta',
 		content: 'Selected tab: Beta',
-		tab: { className: 'beta-class', icon: category },
+		tab: { className: 'beta-class' },
 	},
 	{
 		id: 'gamma',
 		title: 'Gamma',
 		content: 'Selected tab: Gamma',
-		tab: { className: 'gamma-class', icon: media },
+		tab: { className: 'gamma-class' },
 	},
 ];
 
@@ -55,17 +55,15 @@ const TABS_WITH_DELTA: Tab[] = [
 		id: 'delta',
 		title: 'Delta',
 		content: 'Selected tab: Delta',
-		tab: { className: 'delta-class', icon: media },
+		tab: { className: 'delta-class' },
 	},
 ];
 
 const UncontrolledTabs = ( {
 	tabs,
-	showTabIcons = false,
 	...props
 }: Omit< TabsProps, 'children' > & {
 	tabs: Tab[];
-	showTabIcons?: boolean;
 } ) => {
 	return (
 		<Tabs { ...props }>
@@ -76,14 +74,17 @@ const UncontrolledTabs = ( {
 						id={ tabObj.id }
 						className={ tabObj.tab.className }
 						disabled={ tabObj.tab.disabled }
-						icon={ showTabIcons ? tabObj.tab.icon : undefined }
 					>
-						{ showTabIcons ? null : tabObj.title }
+						{ tabObj.title }
 					</Tabs.Tab>
 				) ) }
 			</Tabs.TabList>
 			{ tabs.map( ( tabObj ) => (
-				<Tabs.TabPanel key={ tabObj.id } id={ tabObj.id }>
+				<Tabs.TabPanel
+					key={ tabObj.id }
+					id={ tabObj.id }
+					focusable={ tabObj.tabpanel?.focusable }
+				>
 					{ tabObj.content }
 				</Tabs.TabPanel>
 			) ) }
@@ -93,11 +94,9 @@ const UncontrolledTabs = ( {
 
 const ControlledTabs = ( {
 	tabs,
-	showTabIcons = false,
 	...props
 }: Omit< TabsProps, 'children' > & {
 	tabs: Tab[];
-	showTabIcons?: boolean;
 } ) => {
 	const [ selectedTabId, setSelectedTabId ] = useState<
 		string | undefined | null
@@ -119,9 +118,8 @@ const ControlledTabs = ( {
 						id={ tabObj.id }
 						className={ tabObj.tab.className }
 						disabled={ tabObj.tab.disabled }
-						icon={ showTabIcons ? tabObj.tab.icon : undefined }
 					>
-						{ showTabIcons ? null : tabObj.title }
+						{ tabObj.title }
 					</Tabs.Tab>
 				) ) }
 			</Tabs.TabList>
@@ -184,6 +182,63 @@ describe( 'Tabs', () => {
 			);
 		} );
 	} );
+	describe( 'Focus Behavior', () => {
+		it( 'should focus on the related TabPanel when pressing the Tab key', async () => {
+			const user = userEvent.setup();
+
+			render( <UncontrolledTabs tabs={ TABS } /> );
+
+			const selectedTabPanel = await screen.findByRole( 'tabpanel' );
+
+			// Tab should initially focus the first tab in the tablist, which
+			// is Alpha.
+			await user.keyboard( '[Tab]' );
+			expect(
+				await screen.findByRole( 'tab', { name: 'Alpha' } )
+			).toHaveFocus();
+
+			// By default the tabpanel should receive focus
+			await user.keyboard( '[Tab]' );
+			expect( selectedTabPanel ).toHaveFocus();
+		} );
+		it( 'should not focus on the related TabPanel when pressing the Tab key if `focusable: false` is set', async () => {
+			const user = userEvent.setup();
+
+			const TABS_WITH_ALPHA_FOCUSABLE_FALSE = TABS.map( ( tabObj ) =>
+				tabObj.id === 'alpha'
+					? {
+							...tabObj,
+							content: (
+								<>
+									Selected Tab: Alpha
+									<button>Alpha Button</button>
+								</>
+							),
+							tabpanel: { focusable: false },
+					  }
+					: tabObj
+			);
+
+			render(
+				<UncontrolledTabs tabs={ TABS_WITH_ALPHA_FOCUSABLE_FALSE } />
+			);
+
+			const alphaButton = await screen.findByRole( 'button', {
+				name: /alpha button/i,
+			} );
+
+			// Tab should initially focus the first tab in the tablist, which
+			// is Alpha.
+			await user.keyboard( '[Tab]' );
+			expect(
+				await screen.findByRole( 'tab', { name: 'Alpha' } )
+			).toHaveFocus();
+			// Because the alpha tabpanel is set to `focusable: false`, pressing
+			// the Tab key should focus the button, not the tabpanel
+			await user.keyboard( '[Tab]' );
+			expect( alphaButton ).toHaveFocus();
+		} );
+	} );
 
 	describe( 'Tab Attributes', () => {
 		it( "should apply the tab's `className` to the tab button", async () => {
@@ -469,6 +524,15 @@ describe( 'Tabs', () => {
 				await screen.findByRole( 'tab', { name: 'Alpha' } )
 			).toHaveFocus();
 
+			// This assertion ensures the component has had time to fully
+			// render, preventing flakiness.
+			// see https://github.com/WordPress/gutenberg/pull/55950
+			await waitFor( () =>
+				expect(
+					screen.getByRole( 'tab', { name: 'Beta' } )
+				).toHaveAttribute( 'tabindex', '-1' )
+			);
+
 			// Because all other tabs should have `tabindex=-1`, pressing Tab
 			// should NOT move the focus to the next tab, which is Beta.
 			// Instead, focus should go to the currently selected tabpanel (alpha).
@@ -792,6 +856,16 @@ describe( 'Tabs', () => {
 				// onSelect should not be called since the disabled tab is
 				// highlighted, but not selected.
 				await user.keyboard( '[Tab]' );
+
+				// This assertion ensures focus has time to move to the first
+				// tab before the test proceeds, preventing flakiness.
+				// see https://github.com/WordPress/gutenberg/pull/55950
+				await waitFor( () =>
+					expect(
+						screen.getByRole( 'tab', { name: 'Alpha' } )
+					).toHaveFocus()
+				);
+
 				await user.keyboard( '[ArrowLeft]' );
 				expect( mockOnSelect ).toHaveBeenCalledTimes( 1 );
 

package/src/tabs/types.ts

@@ -4,11 +4,6 @@
 // eslint-disable-next-line no-restricted-imports
 import type * as Ariakit from '@ariakit/react';
 
-/**
- * Internal dependencies
- */
-import type { IconType } from '../icon';
-
 export type TabsContextProps =
 	| {
 			/**
@@ -78,14 +73,6 @@ export type TabListProps = {
 	 * The children elements, which should be a series of `Tabs.TabPanel` components.
 	 */
 	children?: React.ReactNode;
-	/**
-	 * The class name to apply to the tablist.
-	 */
-	className?: string;
-	/**
-	 * Custom CSS styles for the rendered tablist.
-	 */
-	style?: React.CSSProperties;
 };
 
 export type TabProps = {
@@ -93,22 +80,10 @@ export type TabProps = {
 	 * The id of the tab, which is prepended with the `Tabs` instanceId.
 	 */
 	id: string;
-	/**
-	 * Custom CSS styles for the tab.
-	 */
-	style?: React.CSSProperties;
 	/**
 	 * The children elements, generally the text to display on the tab.
 	 */
 	children?: React.ReactNode;
-	/**
-	 * The class name to apply to the tab button.
-	 */
-	className?: string;
-	/**
-	 * The icon used for the tab button.
-	 */
-	icon?: IconType;
 	/**
 	 * Determines if the tab button should be disabled.
 	 *
@@ -128,15 +103,15 @@ export type TabPanelProps = {
 	 */
 	children?: React.ReactNode;
 	/**
-	 * A unique identifier for the TabPanel, which is used to generate a unique `id` for the underlying element.
+	 * A unique identifier for the tabpanel, which is used to generate a unique `id` for the underlying element.
 	 */
 	id: string;
 	/**
-	 * The class name to apply to the tabpanel.
-	 */
-	className?: string;
-	/**
-	 * Custom CSS styles for the rendered `TabPanel` component.
+	 * 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).
+	 *
+	 * @default true
 	 */
-	style?: React.CSSProperties;
+	focusable?: boolean;
 };

package/src/text/README.md

@@ -132,6 +132,8 @@ function Example() {
 
 Sets `Text` to have `display: block`.
 
+Note: text truncation only works when `isBlock` is `false`.
+
 ### isDestructive
 
 **Type**: `boolean`
@@ -196,7 +198,9 @@ function Example() {
 
 **Type**: `boolean`
 
-Enables text truncation. When `truncate` is set,we are able to truncate the long text in a variety of ways.
+Enables text truncation. When `truncate` is set, we are able to truncate the long text in a variety of ways.
+
+Note: text truncation won't work if the `isBlock` property is set to `true`
 
 ```jsx
 import { __experimentalText as Text } from '@wordpress/components';

package/src/text/types.ts

@@ -46,10 +46,14 @@ export interface Props extends TruncateProps {
 	isDestructive?: boolean;
 	/**
 	 * Escape characters in `highlightWords` which are meaningful in regular expressions.
+	 *
+	 * @default false
 	 */
 	highlightEscape?: boolean;
 	/**
 	 * Determines if `highlightWords` should be case sensitive.
+	 *
+	 * @default false
 	 */
 	highlightCaseSensitive?: boolean;
 	/**
@@ -57,7 +61,10 @@ export interface Props extends TruncateProps {
 	 */
 	highlightSanitize?: FindAllArgs[ 'sanitize' ];
 	/**
-	 * Sets `Text` to have `display: block`.
+	 * Sets `Text` to have `display: block`. Note: text truncation only works
+	 * when `isBlock` is `false`.
+	 *
+	 * @default false
 	 */
 	isBlock?: boolean;
 	/**
@@ -73,11 +80,15 @@ export interface Props extends TruncateProps {
 	 */
 	size?: CSSProperties[ 'fontSize' ] | TextSize;
 	/**
-	 * Enables text truncation. When `truncate` is set,we are able to truncate the long text in a variety of ways.
+	 * Enables text truncation. When `truncate` is set, we are able to truncate the long text in a variety of ways. Note: text truncation won't work if the `isBlock` property is set to `true`
+	 *
+	 * @default false
 	 */
 	truncate?: boolean;
 	/**
 	 * Uppercases the text content.
+	 *
+	 * @default false
 	 */
 	upperCase?: boolean;
 	/**
@@ -86,6 +97,8 @@ export interface Props extends TruncateProps {
 	variant?: TextVariant;
 	/**
 	 * Adjusts font-weight of the text.
+	 *
+	 * @default 'normal'
 	 */
 	weight?: CSSProperties[ 'fontWeight' ] | TextWeight;
 	/**

package/src/text-control/index.tsx

@@ -2,6 +2,7 @@
  * External dependencies
  */
 import type { ChangeEvent, ForwardedRef } from 'react';
+import classnames from 'classnames';
 
 /**
  * WordPress dependencies
@@ -22,6 +23,7 @@ function UnforwardedTextControl(
 ) {
 	const {
 		__nextHasNoMarginBottom,
+		__next40pxDefaultSize = false,
 		label,
 		hideLabelFromVision,
 		value,
@@ -46,7 +48,9 @@ function UnforwardedTextControl(
 			className={ className }
 		>
 			<input
-				className="components-text-control__input"
+				className={ classnames( 'components-text-control__input', {
+					'is-next-40px-default-size': __next40pxDefaultSize,
+				} ) }
 				type={ type }
 				id={ id }
 				value={ value }

package/src/text-control/style.scss

@@ -13,5 +13,10 @@
 .components-text-control__input[type="month"],
 .components-text-control__input[type="number"] {
 	width: 100%;
+	height: $grid-unit-40;
 	@include input-control;
+
+	&.is-next-40px-default-size {
+		height: $grid-unit-50;
+	}
 }

package/src/text-control/types.ts

@@ -25,4 +25,10 @@ export type TextControlProps = Pick<
 	 * @default 'text'
 	 */
 	type?: 'email' | 'number' | 'password' | 'tel' | 'text' | 'search' | 'url';
+	/**
+	 * Start opting into the larger default height that will become the default size in a future version.
+	 *
+	 * @default false
+	 */
+	__next40pxDefaultSize?: boolean;
 };

package/src/toggle-control/README.md

@@ -22,8 +22,8 @@ const MyToggleControl = () => {
 					: 'No fixed background.'
 			}
 			checked={ hasFixedBackground }
-			onChange={ () => {
-				setHasFixedBackground( ( state ) => ! state );
+			onChange={ (newValue) => {
+				setHasFixedBackground( newValue );
 			} }
 		/>
 	);

package/src/toggle-group-control/toggle-group-control/component.tsx

@@ -31,6 +31,7 @@ function UnconnectedToggleGroupControl(
 ) {
 	const {
 		__nextHasNoMarginBottom = false,
+		__next40pxDefaultSize = false,
 		className,
 		isAdaptiveWidth = false,
 		isBlock = false,
@@ -52,11 +53,16 @@ function UnconnectedToggleGroupControl(
 	const classes = useMemo(
 		() =>
 			cx(
-				styles.toggleGroupControl( { isBlock, isDeselectable, size } ),
+				styles.toggleGroupControl( {
+					isBlock,
+					isDeselectable,
+					size,
+					__next40pxDefaultSize,
+				} ),
 				isBlock && styles.block,
 				className
 			),
-		[ className, cx, isBlock, isDeselectable, size ]
+		[ className, cx, isBlock, isDeselectable, size, __next40pxDefaultSize ]
 	);
 
 	const MainControl = isDeselectable