@wordpress/components 23.3.0 → 23.3.2

package/src/navigator/test/router.ts

@@ -0,0 +1,122 @@
+/**
+ * Internal dependencies
+ */
+import { patternMatch, findParent } from '../utils/router';
+
+describe( 'patternMatch', () => {
+	it( 'should return undefined if not pattern is matched', () => {
+		const result = patternMatch( '/test', [ { id: 'route', path: '/' } ] );
+		expect( result ).toBeUndefined();
+	} );
+
+	it( 'should match a pattern with no params', () => {
+		const result = patternMatch( '/test', [
+			{ id: 'route', path: '/test' },
+		] );
+		expect( result ).toEqual( { id: 'route', params: {} } );
+	} );
+
+	it( 'should match a pattern with params', () => {
+		const result = patternMatch( '/test/123', [
+			{ id: 'route', path: '/test/:id' },
+		] );
+		expect( result ).toEqual( { id: 'route', params: { id: '123' } } );
+	} );
+
+	it( 'should match the first pattern in case of ambiguity', () => {
+		const result = patternMatch( '/test/123', [
+			{ id: 'route1', path: '/test/:id' },
+			{ id: 'route2', path: '/test/123' },
+		] );
+		expect( result ).toEqual( { id: 'route1', params: { id: '123' } } );
+	} );
+
+	it( 'should match a pattern with optional params', () => {
+		const result = patternMatch( '/test', [
+			{ id: 'route', path: '/test/:id?' },
+		] );
+		expect( result ).toEqual( { id: 'route', params: {} } );
+	} );
+
+	it( 'should return an array of matches for the same param', () => {
+		const result = patternMatch( '/some/basic/route', [
+			{ id: 'route', path: '/:test+' },
+		] );
+		expect( result ).toEqual( {
+			id: 'route',
+			params: { test: [ 'some', 'basic', 'route' ] },
+		} );
+	} );
+} );
+
+describe( 'findParent', () => {
+	it( 'should return undefined if no parent is found', () => {
+		const result = findParent( '/test', [
+			{ id: 'route', path: '/test' },
+		] );
+		expect( result ).toBeUndefined();
+	} );
+
+	it( 'should return the parent path', () => {
+		const result = findParent( '/test', [
+			{ id: 'route1', path: '/test' },
+			{ id: 'route2', path: '/' },
+		] );
+		expect( result ).toEqual( '/' );
+	} );
+
+	it( 'should return to another parent path', () => {
+		const result = findParent( '/test/123', [
+			{ id: 'route1', path: '/test/:id' },
+			{ id: 'route2', path: '/test' },
+		] );
+		expect( result ).toEqual( '/test' );
+	} );
+
+	it( 'should return the parent path with params', () => {
+		const result = findParent( '/test/123/456', [
+			{ id: 'route1', path: '/test/:id/:subId' },
+			{ id: 'route2', path: '/test/:id' },
+		] );
+		expect( result ).toEqual( '/test/123' );
+	} );
+
+	it( 'should return the parent path with optional params', () => {
+		const result = findParent( '/test/123', [
+			{ id: 'route', path: '/test/:id?' },
+		] );
+		expect( result ).toEqual( '/test' );
+	} );
+
+	it( 'should return the grand parent if no parent found', () => {
+		const result = findParent( '/test/123/456', [
+			{ id: 'route1', path: '/test/:id/:subId' },
+			{ id: 'route2', path: '/test' },
+		] );
+		expect( result ).toEqual( '/test' );
+	} );
+
+	it( 'should return the root when no grand parent found', () => {
+		const result = findParent( '/test/nested/path', [
+			{ id: 'route1', path: '/other-path' },
+			{ id: 'route2', path: '/yet-another-path' },
+			{ id: 'root', path: '/' },
+		] );
+		expect( result ).toEqual( '/' );
+	} );
+
+	it( 'should return undefined when no potential parent found', () => {
+		const result = findParent( '/test/nested/path', [
+			{ id: 'route1', path: '/other-path' },
+			{ id: 'route2', path: '/yet-another-path' },
+		] );
+		expect( result ).toBeUndefined();
+	} );
+
+	it( 'should return undefined for non supported paths', () => {
+		const result = findParent( 'this-is-a-path', [
+			{ id: 'route', path: '/' },
+		] );
+		expect( result ).toBeUndefined();
+	} );
+} );

package/src/navigator/types.ts

@@ -3,25 +3,38 @@
  */
 import type { ReactNode } from 'react';
 
+/**
+ * Internal dependencies
+ */
+import type { ButtonAsButtonProps } from '../button/types';
+
+export type MatchParams = Record< string, string | string[] >;
+
 type NavigateOptions = {
 	focusTargetSelector?: string;
+	isBack?: boolean;
 };
 
 export type NavigatorLocation = NavigateOptions & {
 	isInitial?: boolean;
-	isBack?: boolean;
 	path?: string;
 	hasRestoredFocus?: boolean;
 };
 
-export type NavigatorContext = {
+// Returned by the `useNavigator` hook.
+export type Navigator = {
 	location: NavigatorLocation;
+	params: MatchParams;
 	goTo: ( path: string, options?: NavigateOptions ) => void;
 	goBack: () => void;
+	goToParent: () => void;
 };
 
-// Returned by the `useNavigator` hook.
-export type Navigator = NavigatorContext;
+export type NavigatorContext = Navigator & {
+	addScreen: ( screen: Screen ) => void;
+	removeScreen: ( screen: Screen ) => void;
+	match?: string;
+};
 
 export type NavigatorProviderProps = {
 	/**
@@ -45,18 +58,19 @@ export type NavigatorScreenProps = {
 	children: ReactNode;
 };
 
-type ButtonProps = {
-	// TODO: should also extend `Button` prop types once the `Button` component
-	// is refactored to TypeScript.
-	variant?: 'primary' | 'secondary' | 'tertiary' | 'link';
-};
-export type NavigatorBackButtonProps = Omit< ButtonProps, 'href' > & {
+export type NavigatorBackButtonProps = ButtonAsButtonProps;
+
+export type NavigatorBackButtonHookProps = NavigatorBackButtonProps & {
 	/**
-	 * The children elements.
+	 * Whether we should navigate to the parent screen.
+	 *
+	 * @default 'false'
 	 */
-	children: ReactNode;
+	goToParent?: boolean;
 };
 
+export type NavigatorToParentButtonProps = NavigatorBackButtonProps;
+
 export type NavigatorButtonProps = NavigatorBackButtonProps & {
 	/**
 	 * The path of the screen to navigate to. The value of this prop needs to be
@@ -71,3 +85,8 @@ export type NavigatorButtonProps = NavigatorBackButtonProps & {
 	 */
 	attributeName?: string;
 };
+
+export type Screen = {
+	id: string;
+	path: string;
+};

package/src/navigator/use-navigator.ts

@@ -13,12 +13,15 @@ import type { Navigator } from './types';
  * Retrieves a `navigator` instance.
  */
 function useNavigator(): Navigator {
-	const { location, goTo, goBack } = useContext( NavigatorContext );
+	const { location, params, goTo, goBack, goToParent } =
+		useContext( NavigatorContext );
 
 	return {
 		location,
 		goTo,
 		goBack,
+		goToParent,
+		params,
 	};
 }
 

package/src/navigator/utils/router.ts

@@ -0,0 +1,49 @@
+/**
+ * External dependencies
+ */
+import { match } from 'path-to-regexp';
+
+/**
+ * Internal dependencies
+ */
+import type { Screen, MatchParams } from '../types';
+
+function matchPath( path: string, pattern: string ) {
+	const matchingFunction = match< MatchParams >( pattern, {
+		decode: decodeURIComponent,
+	} );
+	return matchingFunction( path );
+}
+
+export function patternMatch( path: string, screens: Screen[] ) {
+	for ( const screen of screens ) {
+		const matched = matchPath( path, screen.path );
+		if ( matched ) {
+			return { params: matched.params, id: screen.id };
+		}
+	}
+
+	return undefined;
+}
+
+export function findParent( path: string, screens: Screen[] ) {
+	if ( ! path.startsWith( '/' ) ) {
+		return undefined;
+	}
+	const pathParts = path.split( '/' );
+	let parentPath;
+	while ( pathParts.length > 1 && parentPath === undefined ) {
+		pathParts.pop();
+		const potentialParentPath =
+			pathParts.join( '/' ) === '' ? '/' : pathParts.join( '/' );
+		if (
+			screens.find( ( screen ) => {
+				return matchPath( potentialParentPath, screen.path ) !== false;
+			} )
+		) {
+			parentPath = potentialParentPath;
+		}
+	}
+
+	return parentPath;
+}

package/src/private-apis.js

@@ -0,0 +1,22 @@
+/**
+ * WordPress dependencies
+ */
+import { __dangerousOptInToUnstableAPIsOnlyForCoreModules } from '@wordpress/private-apis';
+
+/**
+ * Internal dependencies
+ */
+import { default as CustomSelectControl } from './custom-select-control';
+import { positionToPlacement as __experimentalPopoverLegacyPositionToPlacement } from './popover/utils';
+
+export const { lock, unlock } =
+	__dangerousOptInToUnstableAPIsOnlyForCoreModules(
+		'I know using unstable features means my plugin or theme will inevitably break on the next WordPress release.',
+		'@wordpress/components'
+	);
+
+export const privateApis = {};
+lock( privateApis, {
+	CustomSelectControl,
+	__experimentalPopoverLegacyPositionToPlacement,
+} );

package/src/select-control/README.md

@@ -187,7 +187,9 @@ If this property is added, a help text will be generated using help property as
 
 #### multiple
 
-If this property is added, multiple values can be selected. The value passed should be an array.
+If this property is added, multiple values can be selected. The `value` passed should be an array.
+
+In most cases, it is preferable to use the `FormTokenField` or `CheckboxControl` components instead.
 
 -   Type: `Boolean`
 -   Required: No

package/src/select-control/index.tsx

@@ -101,7 +101,9 @@ function UnforwardedSelectControl(
 				isFocused={ isFocused }
 				label={ label }
 				size={ size }
-				suffix={ suffix || <SelectControlChevronDown /> }
+				suffix={
+					suffix || ( ! multiple && <SelectControlChevronDown /> )
+				}
 				prefix={ prefix }
 				labelPosition={ labelPosition }
 				__next36pxDefaultSize={ __next36pxDefaultSize }

package/src/select-control/style.scss

@@ -1,16 +1,6 @@
 .components-select-control__input {
-	background: $white;
-	height: 36px;
-	line-height: 36px;
-	margin: 1px;
 	outline: 0;
-	width: 100%;
 	-webkit-tap-highlight-color: rgba(0, 0, 0, 0) !important;
-
-	@include break-medium() {
-		height: 28px;
-		line-height: 28px;
-	}
 }
 
 @media (max-width: #{ ($break-medium) }) {

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

@@ -13,7 +13,10 @@ import type { SelectControlProps } from '../types';
 import InputControlSuffixWrapper from '../../input-control/input-suffix-wrapper';
 
 interface SelectProps
-	extends Pick< SelectControlProps, '__next36pxDefaultSize' | 'disabled' > {
+	extends Pick<
+		SelectControlProps,
+		'__next36pxDefaultSize' | 'disabled' | 'multiple'
+	> {
 	// Using `selectSize` instead of `size` to avoid a type conflict with the
 	// `size` HTML attribute of the `select` element.
 	selectSize?: SelectControlProps[ 'size' ];
@@ -50,8 +53,15 @@ const fontSizeStyles = ( { selectSize = 'default' }: SelectProps ) => {
 
 const sizeStyles = ( {
 	__next36pxDefaultSize,
+	multiple,
 	selectSize = 'default',
 }: SelectProps ) => {
+	if ( multiple ) {
+		// When `multiple`, just use the native browser styles
+		// without setting explicit height.
+		return;
+	}
+
 	const sizes = {
 		default: {
 			height: 36,
@@ -91,33 +101,37 @@ export const chevronIconSize = 18;
 
 const sizePaddings = ( {
 	__next36pxDefaultSize,
+	multiple,
 	selectSize = 'default',
 }: SelectProps ) => {
-	const iconWidth = chevronIconSize;
-
-	const sizes = {
-		default: {
-			paddingLeft: 16,
-			paddingRight: 16 + iconWidth,
-		},
-		small: {
-			paddingLeft: 8,
-			paddingRight: 8 + iconWidth,
-		},
-		'__unstable-large': {
-			paddingLeft: 16,
-			paddingRight: 16 + iconWidth,
-		},
+	const padding = {
+		default: 16,
+		small: 8,
+		'__unstable-large': 16,
 	};
 
 	if ( ! __next36pxDefaultSize ) {
-		sizes.default = {
-			paddingLeft: 8,
-			paddingRight: 8 + iconWidth,
-		};
+		padding.default = 8;
 	}
 
-	return rtl( sizes[ selectSize ] || sizes.default );
+	const selectedPadding = padding[ selectSize ] || padding.default;
+
+	return rtl( {
+		paddingLeft: selectedPadding,
+		paddingRight: selectedPadding + chevronIconSize,
+		...( multiple
+			? {
+					paddingTop: selectedPadding,
+					paddingBottom: selectedPadding,
+			  }
+			: {} ),
+	} );
+};
+
+const overflowStyles = ( { multiple }: SelectProps ) => {
+	return {
+		overflow: multiple ? 'auto' : 'hidden',
+	};
 };
 
 // TODO: Resolve need to use &&& to increase specificity
@@ -137,7 +151,6 @@ export const Select = styled.select< SelectProps >`
 		width: 100%;
 		max-width: none;
 		cursor: pointer;
-		overflow: hidden;
 		white-space: nowrap;
 		text-overflow: ellipsis;
 
@@ -145,6 +158,7 @@ export const Select = styled.select< SelectProps >`
 		${ fontSizeStyles };
 		${ sizeStyles };
 		${ sizePaddings };
+		${ overflowStyles }
 	}
 `;
 

package/src/select-control/types.ts

@@ -23,7 +23,9 @@ export interface SelectControlProps
 		>,
 		Pick< BaseControlProps, 'help' | '__nextHasNoMarginBottom' > {
 	/**
-	 * If this property is added, multiple values can be selected. The value passed should be an array.
+	 * If this property is added, multiple values can be selected. The `value` passed should be an array.
+	 *
+	 * In most cases, it is preferable to use the `FormTokenField` or `CheckboxControl` components instead.
 	 *
 	 * @default false
 	 */

package/src/tools-panel/test/index.js

@@ -316,6 +316,71 @@ describe( 'ToolsPanel', () => {
 			expect( announcement ).toHaveAttribute( 'aria-live', 'assertive' );
 		} );
 
+		it( 'should render optional panel item when value is updated externally and panel has an ID', async () => {
+			const ToolsPanelOptional = ( { toolsPanelItemValue } ) => {
+				const itemProps = {
+					attributes: { value: toolsPanelItemValue },
+					hasValue: () => !! toolsPanelItemValue,
+					label: 'Alt',
+					onDeselect: jest.fn(),
+					onSelect: jest.fn(),
+				};
+
+				return (
+					<ToolsPanel { ...defaultProps }>
+						<ToolsPanelItem { ...itemProps }>
+							<div>Optional control</div>
+						</ToolsPanelItem>
+					</ToolsPanel>
+				);
+			};
+			const { rerender } = render( <ToolsPanelOptional /> );
+
+			const control = screen.queryByText( 'Optional control' );
+
+			expect( control ).not.toBeInTheDocument();
+
+			rerender( <ToolsPanelOptional toolsPanelItemValue={ 100 } /> );
+
+			const controlRerendered = screen.getByText( 'Optional control' );
+
+			expect( controlRerendered ).toBeInTheDocument();
+		} );
+
+		it( 'should render optional item when value is updated externally and panelId is null', async () => {
+			// This test partially covers: https://github.com/WordPress/gutenberg/issues/47368
+			const ToolsPanelOptional = ( { toolsPanelItemValue } ) => {
+				const itemProps = {
+					attributes: { value: toolsPanelItemValue },
+					hasValue: () => !! toolsPanelItemValue,
+					label: 'Alt',
+					onDeselect: jest.fn(),
+					onSelect: jest.fn(),
+				};
+
+				// The null panelId below simulates the panel prop when there
+				// are multiple blocks selected.
+				return (
+					<ToolsPanel { ...defaultProps } panelId={ null }>
+						<ToolsPanelItem { ...itemProps }>
+							<div>Optional control</div>
+						</ToolsPanelItem>
+					</ToolsPanel>
+				);
+			};
+
+			const { rerender } = render( <ToolsPanelOptional /> );
+			const control = screen.queryByText( 'Optional control' );
+
+			expect( control ).not.toBeInTheDocument();
+
+			rerender( <ToolsPanelOptional toolsPanelItemValue={ 99 } /> );
+
+			const controlRerendered = screen.getByText( 'Optional control' );
+
+			expect( controlRerendered ).toBeInTheDocument();
+		} );
+
 		it( 'should continue to render shown by default item after it is toggled off via menu item', async () => {
 			render(
 				<ToolsPanel { ...defaultProps }>

package/src/tools-panel/tools-panel/hook.ts

@@ -35,12 +35,11 @@ const generateMenuItems = ( {
 	panelItems.forEach( ( { hasValue, isShownByDefault, label } ) => {
 		const group = isShownByDefault ? 'default' : 'optional';
 
-		// If a menu item for this label already exists, do not overwrite its value.
-		// This can cause default controls that have been flagged as customized to
-		// lose their value.
+		// If a menu item for this label has already been flagged as customized
+		// (for default controls), or toggled on (for optional controls), do not
+		// overwrite its value as those controls would lose that state.
 		const existingItemValue = currentMenuItems?.[ group ]?.[ label ];
-		const value =
-			existingItemValue !== undefined ? existingItemValue : hasValue();
+		const value = existingItemValue ? existingItemValue : hasValue();
 
 		menuItems[ group ][ label ] = shouldReset ? false : value;
 	} );

package/src/tools-panel/tools-panel-item/hook.ts

@@ -86,30 +86,40 @@ export function useToolsPanelItem(
 		deregisterPanelItem,
 	] );
 
+	// Note: `label` is used as a key when building menu item state in
+	// `ToolsPanel`.
+	const menuGroup = isShownByDefault ? 'default' : 'optional';
+	const isMenuItemChecked = menuItems?.[ menuGroup ]?.[ label ];
+	const wasMenuItemChecked = usePrevious( isMenuItemChecked );
+	const isRegistered = menuItems?.[ menuGroup ]?.[ label ] !== undefined;
+
 	const isValueSet = hasValue();
 	const wasValueSet = usePrevious( isValueSet );
-
-	// If this item represents a default control it will need to notify the
-	// panel when a custom value has been set.
+	const newValueSet = isValueSet && ! wasValueSet;
+
+	// Notify the panel when an item's value has been set.
+	//
+	// 1. For default controls, this is so "reset" appears beside its menu item.
+	// 2. For optional controls, when the panel ID is `null`, it allows the
+	// panel to ensure the item is toggled on for display in the menu, given the
+	// value has been set external to the control.
 	useEffect( () => {
-		if ( isShownByDefault && isValueSet && ! wasValueSet ) {
-			flagItemCustomization( label );
+		if ( ! newValueSet ) {
+			return;
+		}
+
+		if ( isShownByDefault || currentPanelId === null ) {
+			flagItemCustomization( label, menuGroup );
 		}
 	}, [
-		isValueSet,
-		wasValueSet,
+		currentPanelId,
+		newValueSet,
 		isShownByDefault,
+		menuGroup,
 		label,
 		flagItemCustomization,
 	] );
 
-	// Note: `label` is used as a key when building menu item state in
-	// `ToolsPanel`.
-	const menuGroup = isShownByDefault ? 'default' : 'optional';
-	const isMenuItemChecked = menuItems?.[ menuGroup ]?.[ label ];
-	const wasMenuItemChecked = usePrevious( isMenuItemChecked );
-	const isRegistered = menuItems?.[ menuGroup ]?.[ label ] !== undefined;
-
 	// Determine if the panel item's corresponding menu is being toggled and
 	// trigger appropriate callback if it is.
 	useEffect( () => {

package/tsconfig.json

@@ -24,11 +24,15 @@
 		{ "path": "../deprecated" },
 		{ "path": "../dom" },
 		{ "path": "../element" },
-		{ "path": "../html-entities" },
+		{ "path": "../escape-html" },
 		{ "path": "../hooks" },
+		{ "path": "../html-entities" },
+		{ "path": "../i18n" },
 		{ "path": "../icons" },
 		{ "path": "../is-shallow-equal" },
+		{ "path": "../keycodes" },
 		{ "path": "../primitives" },
+		{ "path": "../private-apis" },
 		{ "path": "../react-i18n" },
 		{ "path": "../warning" }
 	],