@wordpress/components 25.3.0 → 25.5.0

package/src/navigator/navigator-provider/component.tsx

@@ -148,6 +148,7 @@ function UnconnectedNavigatorProvider(
 				focusTargetSelector,
 				isBack = false,
 				skipFocus = false,
+				replace = false,
 				...restOptions
 			} = options;
 
@@ -172,34 +173,38 @@ function UnconnectedNavigatorProvider(
 					skipFocus,
 				};
 
-				if ( prevLocationHistory.length < 1 ) {
-					return [ newLocation ];
+				if ( prevLocationHistory.length === 0 ) {
+					return replace ? [] : [ newLocation ];
 				}
 
-				return [
-					...prevLocationHistory.slice(
-						prevLocationHistory.length > MAX_HISTORY_LENGTH - 1
-							? 1
-							: 0,
-						-1
-					),
-					// Assign `focusTargetSelector` to the previous location in history
-					// (the one we just navigated from).
-					{
-						...prevLocationHistory[
-							prevLocationHistory.length - 1
-						],
-						focusTargetSelector,
-					},
-					newLocation,
-				];
+				const newLocationHistory = prevLocationHistory.slice(
+					prevLocationHistory.length > MAX_HISTORY_LENGTH - 1 ? 1 : 0,
+					-1
+				);
+
+				if ( ! replace ) {
+					newLocationHistory.push(
+						// Assign `focusTargetSelector` to the previous location in history
+						// (the one we just navigated from).
+						{
+							...prevLocationHistory[
+								prevLocationHistory.length - 1
+							],
+							focusTargetSelector,
+						}
+					);
+				}
+
+				newLocationHistory.push( newLocation );
+
+				return newLocationHistory;
 			} );
 		},
 		[ goBack ]
 	);
 
-	const goToParent: NavigatorContextType[ 'goToParent' ] =
-		useCallback( () => {
+	const goToParent: NavigatorContextType[ 'goToParent' ] = useCallback(
+		( options = {} ) => {
 			const currentPath =
 				currentLocationHistory.current[
 					currentLocationHistory.current.length - 1
@@ -214,8 +219,10 @@ function UnconnectedNavigatorProvider(
 			if ( parentPath === undefined ) {
 				return;
 			}
-			goTo( parentPath, { isBack: true } );
-		}, [ goTo ] );
+			goTo( parentPath, { ...options, isBack: true } );
+		},
+		[ goTo ]
+	);
 
 	const navigatorContextValue: NavigatorContextType = useMemo(
 		() => ( {

package/src/navigator/types.ts

@@ -14,8 +14,11 @@ export type NavigateOptions = {
 	focusTargetSelector?: string;
 	isBack?: boolean;
 	skipFocus?: boolean;
+	replace?: boolean;
 };
 
+export type NavigateToParentOptions = Omit< NavigateOptions, 'isBack' >;
+
 export type NavigatorLocation = NavigateOptions & {
 	isInitial?: boolean;
 	path?: string;
@@ -28,7 +31,7 @@ export type Navigator = {
 	params: MatchParams;
 	goTo: ( path: string, options?: NavigateOptions ) => void;
 	goBack: () => void;
-	goToParent: () => void;
+	goToParent: ( options?: NavigateToParentOptions ) => void;
 };
 
 export type NavigatorContext = Navigator & {

package/src/placeholder/style.scss

@@ -161,6 +161,11 @@
 			padding: 0 $grid-unit-10 2px;
 		}
 	}
+	.components-placeholder__learn-more {
+		.components-external-link {
+			color: var(--wp-admin-theme-color);
+		}
+	}
 }
 
 

package/src/private-apis.ts

@@ -8,6 +8,7 @@ import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/pri
  */
 import { default as CustomSelectControl } from './custom-select-control';
 import { positionToPlacement as __experimentalPopoverLegacyPositionToPlacement } from './popover/utils';
+import { default as ProgressBar } from './progress-bar';
 import { createPrivateSlotFill } from './slot-fill';
 import {
 	DropdownMenu as DropdownMenuV2,
@@ -45,4 +46,5 @@ lock( privateApis, {
 	DropdownMenuSeparatorV2,
 	DropdownSubMenuV2,
 	DropdownSubMenuTriggerV2,
+	ProgressBar,
 } );

package/src/progress-bar/README.md

@@ -0,0 +1,30 @@
+# ProgressBar
+
+<div class="callout callout-alert">
+This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+</div>
+
+A simple horizontal progress bar component.
+
+Supports two modes: determinate and indeterminate. A progress bar is determinate when a specific progress value has been specified (from 0 to 100), and indeterminate when a value hasn't been specified.
+
+### Props
+
+The component accepts the following props:
+
+#### `value`: `number`
+
+The progress value, a number from 0 to 100.
+If a `value` is not specified, the progress bar will be considered indeterminate.
+
+-   Required: No
+
+##### `className`: `string`
+
+A CSS class to apply to the underlying `div` element, serving as a progress bar track.
+
+- Required: No
+
+#### Inherited props
+
+Any additional props will be passed the underlying `<progress/>` element.

package/src/progress-bar/index.tsx

@@ -0,0 +1,45 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import { forwardRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import * as ProgressBarStyled from './styles';
+import type { ProgressBarProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
+
+function UnforwardedProgressBar(
+	props: WordPressComponentProps< ProgressBarProps, 'progress', false >,
+	ref: ForwardedRef< HTMLProgressElement >
+) {
+	const { className, value, ...progressProps } = props;
+	const isIndeterminate = ! Number.isFinite( value );
+
+	return (
+		<ProgressBarStyled.Track className={ className }>
+			<ProgressBarStyled.Indicator
+				isIndeterminate={ isIndeterminate }
+				value={ value }
+			/>
+			<ProgressBarStyled.ProgressElement
+				max={ 100 }
+				value={ value }
+				aria-label={ __( 'Loading …' ) }
+				ref={ ref }
+				{ ...progressProps }
+			/>
+		</ProgressBarStyled.Track>
+	);
+}
+
+export const ProgressBar = forwardRef( UnforwardedProgressBar );
+
+export default ProgressBar;

package/src/progress-bar/stories/index.tsx

@@ -0,0 +1,33 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { ProgressBar } from '..';
+
+const meta: ComponentMeta< typeof ProgressBar > = {
+	component: ProgressBar,
+	title: 'Components (Experimental)/ProgressBar',
+	argTypes: {
+		value: { control: { type: 'number', min: 0, max: 100, step: 1 } },
+	},
+	parameters: {
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof ProgressBar > = ( { ...args } ) => {
+	return <ProgressBar { ...args } />;
+};
+
+export const Default: ComponentStory< typeof ProgressBar > = Template.bind(
+	{}
+);
+Default.args = {};

package/src/progress-bar/styles.ts

@@ -0,0 +1,67 @@
+/**
+ * External dependencies
+ */
+import styled from '@emotion/styled';
+import { css, keyframes } from '@emotion/react';
+
+/**
+ * Internal dependencies
+ */
+import { COLORS, CONFIG } from '../utils';
+
+const animateProgressBar = keyframes( {
+	'0%': {
+		left: '-50%',
+	},
+	'100%': {
+		left: '100%',
+	},
+} );
+
+// Width of the indicator for the indeterminate progress bar
+export const INDETERMINATE_TRACK_WIDTH = 50;
+
+export const Track = styled.div`
+	position: relative;
+	overflow: hidden;
+	width: 100%;
+	max-width: 160px;
+	height: ${ CONFIG.borderWidthFocus };
+	background-color: var(
+		--wp-components-color-gray-100,
+		${ COLORS.gray[ 100 ] }
+	);
+	border-radius: ${ CONFIG.radiusBlockUi };
+`;
+
+export const Indicator = styled.div< {
+	isIndeterminate: boolean;
+	value?: number;
+} >`
+	display: inline-block;
+	position: absolute;
+	top: 0;
+	height: 100%;
+	border-radius: ${ CONFIG.radiusBlockUi };
+	background-color: ${ COLORS.ui.theme };
+
+	${ ( { isIndeterminate, value } ) =>
+		isIndeterminate
+			? css( {
+					animationDuration: '1.5s',
+					animationTimingFunction: 'ease-in-out',
+					animationIterationCount: 'infinite',
+					animationName: animateProgressBar,
+					width: `${ INDETERMINATE_TRACK_WIDTH }%`,
+			  } )
+			: css( { width: `${ value }%` } ) };
+`;
+
+export const ProgressElement = styled.progress`
+	position: absolute;
+	top: 0;
+	left: 0;
+	opacity: 0;
+	width: 100%;
+	height: 100%;
+`;

package/src/progress-bar/test/index.tsx

@@ -0,0 +1,79 @@
+/**
+ * External dependencies
+ */
+import { render, screen } from '@testing-library/react';
+
+/**
+ * Internal dependencies
+ */
+import { ProgressBar } from '..';
+import { INDETERMINATE_TRACK_WIDTH } from '../styles';
+
+describe( 'ProgressBar', () => {
+	it( 'should render an indeterminate semantic progress bar element', () => {
+		render( <ProgressBar /> );
+
+		const progressBar = screen.getByRole( 'progressbar' );
+
+		expect( progressBar ).toBeInTheDocument();
+		expect( progressBar ).not.toBeVisible();
+		expect( progressBar ).not.toHaveValue();
+	} );
+
+	it( 'should render a determinate semantic progress bar element', () => {
+		render( <ProgressBar value={ 55 } /> );
+
+		const progressBar = screen.getByRole( 'progressbar' );
+
+		expect( progressBar ).toBeInTheDocument();
+		expect( progressBar ).not.toBeVisible();
+		expect( progressBar ).toHaveValue( 55 );
+	} );
+
+	it( 'should use `INDETERMINATE_TRACK_WIDTH`% as track width for indeterminate progress bar', () => {
+		const { container } = render( <ProgressBar /> );
+
+		/**
+		 * We're intentionally not using an accessible selector, because
+		 * the track is an intentionally non-interactive presentation element.
+		 */
+		// eslint-disable-next-line testing-library/no-container, testing-library/no-node-access
+		const indicator = container.firstChild?.firstChild;
+
+		expect( indicator ).toHaveStyle( {
+			width: `${ INDETERMINATE_TRACK_WIDTH }%`,
+		} );
+	} );
+
+	it( 'should use `value`% as width for determinate progress bar', () => {
+		const { container } = render( <ProgressBar value={ 55 } /> );
+
+		/**
+		 * We're intentionally not using an accessible selector, because
+		 * the track is an intentionally non-interactive presentation element.
+		 */
+		// eslint-disable-next-line testing-library/no-container, testing-library/no-node-access
+		const indicator = container.firstChild?.firstChild;
+
+		expect( indicator ).toHaveStyle( {
+			width: '55%',
+		} );
+	} );
+
+	it( 'should pass any additional props down to the underlying `progress` element', () => {
+		const id = 'foo-bar-123';
+		const ariaLabel = 'in progress...';
+		const style = { opacity: 1 };
+
+		render(
+			<ProgressBar id={ id } aria-label={ ariaLabel } style={ style } />
+		);
+
+		expect( screen.getByRole( 'progressbar' ) ).toHaveAttribute( 'id', id );
+		expect( screen.getByRole( 'progressbar' ) ).toHaveAttribute(
+			'aria-label',
+			ariaLabel
+		);
+		expect( screen.getByRole( 'progressbar' ) ).toHaveStyle( style );
+	} );
+} );

package/src/progress-bar/types.ts

@@ -0,0 +1,11 @@
+export type ProgressBarProps = {
+	/**
+	 * Value of the progress bar.
+	 */
+	value?: number;
+
+	/**
+	 * A CSS class to apply to the progress bar wrapper (track) element.
+	 */
+	className?: string;
+};

package/src/query-controls/index.native.js

@@ -84,6 +84,7 @@ const QueryControls = memo(
 				) }
 				{ onNumberOfItemsChange && (
 					<RangeControl
+						__next40pxDefaultSize
 						label={ __( 'Number of items' ) }
 						value={ numberOfItems }
 						onChange={ onNumberOfItemsChange }

package/src/query-controls/index.tsx

@@ -177,6 +177,7 @@ export function QueryControls( {
 				onNumberOfItemsChange && (
 					<RangeControl
 						__nextHasNoMarginBottom
+						__next40pxDefaultSize
 						key="query-controls-range-control"
 						label={ __( 'Number of items' ) }
 						value={ numberOfItems }