@wordpress/components 28.8.6 → 28.10.0

package/src/navigator/use-navigator.ts

@@ -10,7 +10,10 @@ import { NavigatorContext } from './context';
 import type { Navigator } from './types';
 
 /**
- * Retrieves a `navigator` instance.
+ * Retrieves a `navigator` instance. This hook provides advanced functionality,
+ * such as imperatively navigating to a new location (with options like
+ * navigating back or skipping focus restoration) and accessing the current
+ * location and path parameters.
  */
 export function useNavigator(): Navigator {
 	const { location, params, goTo, goBack, goToParent } =

package/src/range-control/styles/range-control-styles.ts

@@ -57,7 +57,10 @@ const wrapperMargin = ( { marks, __nextHasNoMarginBottom }: WrapperProps ) => {
 	return '';
 };
 
-export const Wrapper = styled.div< WrapperProps >`
+export const Wrapper = styled( 'div', {
+	shouldForwardProp: ( prop: string ) =>
+		! [ 'color', '__nextHasNoMarginBottom', 'marks' ].includes( prop ),
+} )< WrapperProps >`
 	display: block;
 	flex: 1;
 	position: relative;
@@ -261,9 +264,20 @@ export const InputRange = styled.input`
 `;
 
 const tooltipShow = ( { show }: TooltipProps ) => {
-	return css( {
-		opacity: show ? 1 : 0,
-	} );
+	return css`
+		display: ${ show ? 'inline-block' : 'none' };
+		opacity: ${ show ? 1 : 0 };
+
+		@media not ( prefers-reduced-motion ) {
+			transition:
+				opacity 120ms ease,
+				display 120ms ease allow-discrete;
+		}
+
+		@starting-style {
+			opacity: 0;
+		}
+	`;
 };
 
 const tooltipPosition = ( { position }: TooltipProps ) => {
@@ -284,10 +298,8 @@ export const Tooltip = styled.span< TooltipProps >`
 	background: rgba( 0, 0, 0, 0.8 );
 	border-radius: ${ CONFIG.radiusSmall };
 	color: white;
-	display: inline-block;
 	font-size: 12px;
 	min-width: 32px;
-	opacity: 0;
 	padding: 4px 8px;
 	pointer-events: none;
 	position: absolute;
@@ -295,11 +307,8 @@ export const Tooltip = styled.span< TooltipProps >`
 	user-select: none;
 	line-height: 1.4;
 
-	@media not ( prefers-reduced-motion ) {
-		transition: opacity 120ms ease;
-	}
-
 	${ tooltipShow };
+
 	${ tooltipPosition };
 	${ rtl(
 		{ transform: 'translateX(-50%)' },

package/src/range-control/tooltip.tsx

@@ -40,7 +40,7 @@ export default function SimpleTooltip(
 	return (
 		<Tooltip
 			{ ...restProps }
-			aria-hidden={ show }
+			aria-hidden="false"
 			className={ classes }
 			position={ position }
 			show={ show }

package/src/search-control/README.md

@@ -76,6 +76,8 @@ A function that receives the value of the input.
 
 #### onClose
 
+_Note: this prop is deprecated._
+
 When an `onClose` callback is provided, the search control will render a close button that will trigger the given callback.
 
 Use this if you want the button to trigger your own logic to close the search field entirely, rather than just clearing the input value.

package/src/search-control/index.tsx

@@ -10,6 +10,7 @@ import { useInstanceId, useMergeRefs } from '@wordpress/compose';
 import { __ } from '@wordpress/i18n';
 import { Icon, search, closeSmall } from '@wordpress/icons';
 import { forwardRef, useMemo, useRef } from '@wordpress/element';
+import deprecated from '@wordpress/deprecated';
 
 /**
  * Internal dependencies
@@ -31,6 +32,12 @@ function SuffixItem( {
 		return <Icon icon={ search } />;
 	}
 
+	if ( onClose ) {
+		deprecated( '`onClose` prop in wp.components.SearchControl', {
+			since: '6.8',
+		} );
+	}
+
 	const onReset = () => {
 		onChange( '' );
 		searchRef.current?.focus();
@@ -67,7 +74,7 @@ function UnforwardedSearchControl(
 ) {
 	// @ts-expect-error The `disabled` prop is not yet supported in the SearchControl component.
 	// Work with the design team (@WordPress/gutenberg-design) if you need this feature.
-	delete restProps.disabled;
+	const { disabled, ...filteredRestProps } = restProps;
 
 	const searchRef = useRef< HTMLInputElement >( null );
 	const instanceId = useInstanceId(
@@ -117,7 +124,7 @@ function UnforwardedSearchControl(
 						/>
 					</SuffixItemWrapper>
 				}
-				{ ...restProps }
+				{ ...filteredRestProps }
 			/>
 		</ContextSystemProvider>
 	);

package/src/search-control/stories/index.story.tsx

@@ -50,18 +50,3 @@ Default.args = {
 	help: 'Help text to explain the input.',
 	__nextHasNoMarginBottom: true,
 };
-
-/**
- * When an `onClose` callback is provided, the search control will render a close button
- * that will trigger the given callback.
- *
- * Use this if you want the button to trigger your own logic to close the search field entirely,
- * rather than just clearing the input value.
- */
-export const WithOnClose = Template.bind( {} );
-WithOnClose.args = {
-	...Default.args,
-};
-WithOnClose.argTypes = {
-	onClose: { action: 'onClose' },
-};

package/src/search-control/test/index.tsx

@@ -72,13 +72,16 @@ describe( 'SearchControl', () => {
 			expect( onChangeSpy ).toHaveBeenLastCalledWith( '' );
 		} );
 
-		it( 'should should render a Close button (instead of Reset) when onClose function is provided', async () => {
+		it( 'should render a Close button (instead of Reset) when onClose function is provided', async () => {
 			const onChangeSpy = jest.fn();
 			const onCloseSpy = jest.fn();
 			render(
 				<Component onChange={ onChangeSpy } onClose={ onCloseSpy } />
 			);
 
+			expect( console ).toHaveWarnedWith(
+				'`onClose` prop in wp.components.SearchControl is deprecated since version 6.8.'
+			);
 			expect(
 				screen.queryByRole( 'button', { name: 'Close search' } )
 			).toBeVisible();

package/src/search-control/types.ts

@@ -40,6 +40,9 @@ export type SearchControlProps = Pick< InputControlProps, 'help' | 'value' > & {
 	 *
 	 * Use this if you want the button to trigger your own logic to close the search field entirely,
 	 * rather than just clearing the input value.
+	 *
+	 * @deprecated
+	 * @ignore
 	 */
 	onClose?: () => void;
 	/** @ignore */

package/src/select-control/stories/index.story.tsx

@@ -12,6 +12,7 @@ import { useState } from '@wordpress/element';
  * Internal dependencies
  */
 import SelectControl from '../';
+import { InputControlPrefixWrapper } from '../../input-control/input-prefix-wrapper';
 
 const meta: Meta< typeof SelectControl > = {
 	title: 'Components/SelectControl',
@@ -64,6 +65,7 @@ const SelectControlWithState: StoryFn< typeof SelectControl > = ( props ) => {
 export const Default = SelectControlWithState.bind( {} );
 Default.args = {
 	__nextHasNoMarginBottom: true,
+	label: 'Label',
 	options: [
 		{ value: '', label: 'Select an Option', disabled: true },
 		{ value: 'a', label: 'Option A' },
@@ -76,7 +78,6 @@ export const WithLabelAndHelpText = SelectControlWithState.bind( {} );
 WithLabelAndHelpText.args = {
 	...Default.args,
 	help: 'Help text to explain the select control.',
-	label: 'Value',
 };
 
 /**
@@ -86,6 +87,7 @@ WithLabelAndHelpText.args = {
 export const WithCustomChildren = SelectControlWithState.bind( {} );
 WithCustomChildren.args = {
 	__nextHasNoMarginBottom: true,
+	label: 'Label',
 	children: (
 		<>
 			<option value="option-1">Option 1</option>
@@ -104,8 +106,19 @@ WithCustomChildren.args = {
 	),
 };
 
+/**
+ * By default, the prefix is aligned with the edge of the input border, with no padding.
+ * If you want to apply standard padding in accordance with the size variant, wrap the element in the `<InputControlPrefixWrapper>` component.
+ */
+export const WithPrefix = SelectControlWithState.bind( {} );
+WithPrefix.args = {
+	...Default.args,
+	prefix: <InputControlPrefixWrapper>Prefix:</InputControlPrefixWrapper>,
+};
+
 export const Minimal = SelectControlWithState.bind( {} );
 Minimal.args = {
 	...Default.args,
 	variant: 'minimal',
+	hideLabelFromVision: true,
 };

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

@@ -70,6 +70,112 @@ const Template: StoryFn< typeof Tabs > = ( props ) => {
 
 export const Default = Template.bind( {} );
 
+export const SizeAndOverflowPlayground: StoryFn< typeof Tabs > = ( props ) => {
+	const [ fullWidth, setFullWidth ] = useState( false );
+	return (
+		<div>
+			<div style={ { maxWidth: '40rem', marginBottom: '1rem' } }>
+				<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' } }
+				variant="primary"
+				onClick={ () => setFullWidth( ! fullWidth ) }
+			>
+				{ fullWidth
+					? 'Remove width: 100% from TabList'
+					: 'Set width: 100% in TabList' }
+			</Button>
+			<Tabs { ...props }>
+				<div
+					style={ {
+						width: '20rem',
+						border: '2px dotted red',
+						padding: '1rem',
+						resize: 'horizontal',
+						overflow: 'auto',
+					} }
+				>
+					<Tabs.TabList
+						style={ {
+							maxWidth: '100%',
+							width: fullWidth ? '100%' : undefined,
+						} }
+					>
+						<Tabs.Tab tabId="tab1">
+							Label with multiple words
+						</Tabs.Tab>
+						<Tabs.Tab tabId="tab2">Short</Tabs.Tab>
+						<Tabs.Tab tabId="tab3">
+							Hippopotomonstrosesquippedaliophobia
+						</Tabs.Tab>
+						<Tabs.Tab tabId="tab4">Tab 4</Tabs.Tab>
+						<Tabs.Tab tabId="tab5">Tab 5</Tabs.Tab>
+					</Tabs.TabList>
+				</div>
+				<Tabs.TabPanel tabId="tab1">
+					<p>Selected tab: Tab 1</p>
+					<p>(Label with multiple words)</p>
+				</Tabs.TabPanel>
+				<Tabs.TabPanel tabId="tab2">
+					<p>Selected tab: Tab 2</p>
+					<p>(Short)</p>
+				</Tabs.TabPanel>
+				<Tabs.TabPanel tabId="tab3">
+					<p>Selected tab: Tab 3</p>
+					<p>(Hippopotomonstrosesquippedaliophobia)</p>
+				</Tabs.TabPanel>
+				<Tabs.TabPanel tabId="tab4">
+					<p>Selected tab: Tab 4</p>
+				</Tabs.TabPanel>
+				<Tabs.TabPanel tabId="tab5">
+					<p>Selected tab: Tab 5</p>
+				</Tabs.TabPanel>
+			</Tabs>
+		</div>
+	);
+};
+SizeAndOverflowPlayground.args = {
+	defaultTabId: 'tab4',
+};
+
 const VerticalTemplate: StoryFn< typeof Tabs > = ( props ) => {
 	return (
 		<Tabs orientation="vertical" { ...props }>

package/src/tabs/styles.ts

@@ -9,39 +9,45 @@ import * as Ariakit from '@ariakit/react';
  */
 import { COLORS, CONFIG } from '../utils';
 import { space } from '../utils/space';
+import Icon from '../icon';
 
 export const TabListWrapper = styled.div`
-	position: relative;
 	display: flex;
 	align-items: stretch;
-	flex-direction: row;
-	text-align: center;
+	overflow-x: auto;
 
 	&[aria-orientation='vertical'] {
 		flex-direction: column;
-		text-align: start;
 	}
 
-	@media not ( prefers-reduced-motion ) {
-		&.is-animation-enabled::after {
-			transition-property: transform;
-			transition-duration: 0.2s;
-			transition-timing-function: ease-out;
-		}
+	:where( [aria-orientation='horizontal'] ) {
+		width: fit-content;
 	}
+
 	--direction-factor: 1;
-	--direction-origin-x: left;
-	--indicator-start: var( --indicator-left );
+	--direction-start: left;
+	--direction-end: right;
+	--selected-start: var( --selected-left, 0 );
 	&:dir( rtl ) {
 		--direction-factor: -1;
-		--direction-origin-x: right;
-		--indicator-start: var( --indicator-right );
+		--direction-start: right;
+		--direction-end: left;
+		--selected-start: var( --selected-right, 0 );
+	}
+
+	@media not ( prefers-reduced-motion ) {
+		&[data-indicator-animated]::before {
+			transition-property: transform, border-radius, border-block;
+			transition-duration: 0.2s;
+			transition-timing-function: ease-out;
+		}
 	}
-	&::after {
+	position: relative;
+	&::before {
 		content: '';
 		position: absolute;
 		pointer-events: none;
-		transform-origin: var( --direction-origin-x ) top;
+		transform-origin: var( --direction-start ) top;
 
 		// Windows high contrast mode.
 		outline: 2px solid transparent;
@@ -51,60 +57,112 @@ export const TabListWrapper = styled.div`
 	/* Using a large value to avoid antialiasing rounding issues
 			when scaling in the transform, see: https://stackoverflow.com/a/52159123 */
 	--antialiasing-factor: 100;
-	&:not( [aria-orientation='vertical'] ) {
-		&::after {
+	&[aria-orientation='horizontal'] {
+		--fade-width: 4rem;
+		--fade-gradient-base: transparent 0%, black var( --fade-width );
+		--fade-gradient-composed: var( --fade-gradient-base ), black 60%,
+			transparent 50%;
+		&.is-overflowing-first {
+			mask-image: linear-gradient(
+				to var( --direction-end ),
+				var( --fade-gradient-base )
+			);
+		}
+		&.is-overflowing-last {
+			mask-image: linear-gradient(
+				to var( --direction-start ),
+				var( --fade-gradient-base )
+			);
+		}
+		&.is-overflowing-first.is-overflowing-last {
+			mask-image: linear-gradient(
+					to right,
+					var( --fade-gradient-composed )
+				),
+				linear-gradient( to left, var( --fade-gradient-composed ) );
+		}
+
+		&::before {
 			bottom: 0;
 			height: 0;
 			width: calc( var( --antialiasing-factor ) * 1px );
 			transform: translateX(
 					calc(
-						var( --indicator-start ) * var( --direction-factor ) *
+						var( --selected-start ) * var( --direction-factor ) *
 							1px
 					)
 				)
 				scaleX(
 					calc(
-						var( --indicator-width ) / var( --antialiasing-factor )
+						var( --selected-width, 0 ) /
+							var( --antialiasing-factor )
 					)
 				);
 			border-bottom: var( --wp-admin-border-width-focus ) solid
 				${ COLORS.theme.accent };
 		}
 	}
-	&[aria-orientation='vertical']::after {
-		z-index: -1;
-		top: 0;
-		left: 0;
-		width: 100%;
-		height: calc( var( --antialiasing-factor ) * 1px );
-		transform: translateY( calc( var( --indicator-top ) * 1px ) )
-			scaleY(
-				calc( var( --indicator-height ) / var( --antialiasing-factor ) )
+	&[aria-orientation='vertical'] {
+		&::before {
+			/* Adjusting the border radius to match the scaling in the y axis. */
+			border-radius: ${ CONFIG.radiusSmall } /
+				calc(
+					${ CONFIG.radiusSmall } /
+						(
+							var( --selected-height, 0 ) /
+								var( --antialiasing-factor )
+						)
+				);
+			top: 0;
+			left: 0;
+			width: 100%;
+			height: calc( var( --antialiasing-factor ) * 1px );
+			transform: translateY( calc( var( --selected-top, 0 ) * 1px ) )
+				scaleY(
+					calc(
+						var( --selected-height, 0 ) /
+							var( --antialiasing-factor )
+					)
+				);
+			background-color: color-mix(
+				in srgb,
+				${ COLORS.theme.accent },
+				transparent 96%
+			);
+		}
+		&[data-select-on-move='true']:has(
+				:is( :focus-visible, [data-focus-visible] )
+			)::before {
+			box-sizing: border-box;
+			border: var( --wp-admin-border-width-focus ) solid
+				${ COLORS.theme.accent };
+			/* Adjusting the border width to match the scaling in the y axis. */
+			border-block-width: calc(
+				var( --wp-admin-border-width-focus, 1px ) /
+					(
+						var( --selected-height, 0 ) /
+							var( --antialiasing-factor )
+					)
 			);
-		background-color: ${ COLORS.theme.gray[ 100 ] };
+		}
 	}
 `;
 
 export const Tab = styled( Ariakit.Tab )`
 	& {
-		display: inline-flex;
-		align-items: center;
-		position: relative;
+		/* Resets */
 		border-radius: 0;
-		min-height: ${ space(
-			12
-		) }; // Avoid fixed height to allow for long strings that go in multiple lines.
-		height: auto;
 		background: transparent;
 		border: none;
 		box-shadow: none;
+
+		flex: 1 0 auto;
+		white-space: nowrap;
+		display: flex;
+		align-items: center;
 		cursor: pointer;
-		line-height: 1.2; // Some languages characters e.g. Japanese may have a native higher line-height.
-		padding: ${ space( 4 ) };
-		margin-left: 0;
-		font-weight: 500;
-		text-align: inherit;
-		hyphens: auto;
+		line-height: 1.2; // Characters in some languages (e.g. Japanese) may have a native higher line-height.
+		font-weight: 400;
 		color: ${ COLORS.theme.foreground };
 
 		&[aria-disabled='true'] {
@@ -112,24 +170,19 @@ export const Tab = styled( Ariakit.Tab )`
 			color: ${ COLORS.ui.textDisabled };
 		}
 
-		&:not( [aria-disabled='true'] ):hover {
+		&:not( [aria-disabled='true'] ):is( :hover, [data-focus-visible] ) {
 			color: ${ COLORS.theme.accent };
 		}
 
 		&:focus:not( :disabled ) {
-			position: relative;
 			box-shadow: none;
 			outline: none;
 		}
 
-		// Focus.
-		&::before {
-			content: '';
+		// Focus indicator.
+		position: relative;
+		&::after {
 			position: absolute;
-			top: ${ space( 3 ) };
-			right: ${ space( 3 ) };
-			bottom: ${ space( 3 ) };
-			left: ${ space( 3 ) };
 			pointer-events: none;
 
 			// Draw the indicator.
@@ -142,19 +195,69 @@ export const Tab = styled( Ariakit.Tab )`
 			opacity: 0;
 
 			@media not ( prefers-reduced-motion ) {
-				transition: opacity 0.1s linear;
+				transition: opacity 0.15s 0.15s linear;
 			}
 		}
 
-		&:focus-visible::before {
+		&[data-focus-visible]::after {
 			opacity: 1;
 		}
 	}
 
+	[aria-orientation='horizontal'] & {
+		padding-inline: ${ space( 4 ) };
+		height: ${ space( 12 ) };
+		text-align: center;
+		scroll-margin: 24px;
+
+		&::after {
+			content: '';
+			inset: ${ space( 3 ) };
+		}
+	}
+
 	[aria-orientation='vertical'] & {
-		min-height: ${ space(
-			10
-		) }; // Avoid fixed height to allow for long strings that go in multiple lines.
+		padding: ${ space( 2 ) } ${ space( 3 ) };
+		min-height: ${ space( 10 ) };
+		text-align: start;
+
+		&[aria-selected='true'] {
+			color: ${ COLORS.theme.accent };
+			fill: currentColor;
+		}
+	}
+	[aria-orientation='vertical'][data-select-on-move='false'] &::after {
+		content: '';
+		inset: var( --wp-admin-border-width-focus );
+	}
+`;
+
+export const TabChildren = styled.span`
+	flex-grow: 1;
+`;
+
+export const TabChevron = styled( Icon )`
+	flex-shrink: 0;
+	margin-inline-end: ${ space( -1 ) };
+	[aria-orientation='horizontal'] & {
+		display: none;
+	}
+	opacity: 0;
+	[role='tab']:is( [aria-selected='true'], [data-focus-visible], :hover ) & {
+		opacity: 1;
+	}
+	// The chevron is transitioned into existence when selectOnMove is enabled,
+	// because otherwise it looks jarring, as it shows up outside of the focus
+	// indicator that's being animated at the same time.
+	@media not ( prefers-reduced-motion ) {
+		[data-select-on-move='true']
+			[role='tab']:is( [aria-selected='true'],  )
+			& {
+			transition: opacity 0.3s ease-in;
+		}
+	}
+	&:dir( rtl ) {
+		rotate: 180deg;
 	}
 `;
 
@@ -164,7 +267,7 @@ export const TabPanel = styled( Ariakit.TabPanel )`
 		outline: none;
 	}
 
-	&:focus-visible {
+	&[data-focus-visible] {
 		box-shadow: 0 0 0 var( --wp-admin-border-width-focus )
 			${ COLORS.theme.accent };
 		// Windows high contrast mode.

package/src/tabs/tab.tsx

@@ -10,8 +10,13 @@ import { forwardRef } from '@wordpress/element';
 import type { TabProps } from './types';
 import warning from '@wordpress/warning';
 import { useTabsContext } from './context';
-import { Tab as StyledTab } from './styles';
+import {
+	Tab as StyledTab,
+	TabChildren as StyledTabChildren,
+	TabChevron as StyledTabChevron,
+} from './styles';
 import type { WordPressComponentProps } from '../context';
+import { chevronRight } from '@wordpress/icons';
 
 export const Tab = forwardRef<
 	HTMLButtonElement,
@@ -33,7 +38,8 @@ export const Tab = forwardRef<
 			render={ render }
 			{ ...otherProps }
 		>
-			{ children }
+			<StyledTabChildren>{ children }</StyledTabChildren>
+			<StyledTabChevron icon={ chevronRight } />
 		</StyledTab>
 	);
 } );