@wordpress/components 21.3.0 → 22.0.0

package/src/number-control/test/index.js

@@ -2,6 +2,7 @@
  * External dependencies
  */
 import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 
 /**
  * WordPress dependencies
@@ -425,4 +426,53 @@ describe( 'NumberControl', () => {
 			expect( input.value ).toBe( '4' );
 		} );
 	} );
+
+	describe( 'custom spin buttons', () => {
+		test.each( [ undefined, 'none', 'native' ] )(
+			'should not appear when spinControls = %s',
+			( spinControls ) => {
+				render( <NumberControl spinControls={ spinControls } /> );
+				expect(
+					screen.queryByLabelText( 'Increment' )
+				).not.toBeInTheDocument();
+				expect(
+					screen.queryByLabelText( 'Decrement' )
+				).not.toBeInTheDocument();
+			}
+		);
+
+		test.each( [
+			[ 'up', '1', {} ],
+			[ 'up', '2', { value: '1' } ],
+			[ 'up', '12', { value: '10', step: '2' } ],
+			[ 'up', '10', { value: '10', max: '10' } ],
+			[ 'down', '-1', {} ],
+			[ 'down', '1', { value: '2' } ],
+			[ 'down', '10', { value: '12', step: '2' } ],
+			[ 'down', '10', { value: '10', min: '10' } ],
+		] )(
+			'should spin %s to %s when props = %o',
+			async ( direction, expectedValue, props ) => {
+				const user = userEvent.setup( {
+					advanceTimers: jest.advanceTimersByTime,
+				} );
+				const onChange = jest.fn();
+				render(
+					<NumberControl
+						{ ...props }
+						spinControls="custom"
+						onChange={ onChange }
+					/>
+				);
+				await user.click(
+					screen.getByLabelText(
+						direction === 'up' ? 'Increment' : 'Decrement'
+					)
+				);
+				expect( onChange ).toHaveBeenCalledWith( expectedValue, {
+					event: expect.anything(),
+				} );
+			}
+		);
+	} );
 } );

package/src/number-control/types.ts

@@ -10,9 +10,21 @@ export type NumberControlProps = Omit<
 	/**
 	 * If true, the default `input` HTML arrows will be hidden.
 	 *
+	 * @deprecated
 	 * @default false
 	 */
 	hideHTMLArrows?: boolean;
+	/**
+	 * The type of spin controls to display. These are butons that allow the
+	 * user to quickly increment and decrement the number.
+	 *
+	 * - 'none' - Do not show spin controls.
+	 * - 'native' - Use browser's native HTML `input` controls.
+	 * - 'custom' - Use plus and minus icon buttons.
+	 *
+	 * @default 'native'
+	 */
+	spinControls?: 'none' | 'native' | 'custom';
 	/**
 	 * If true, enables mouse drag gestures.
 	 *

package/src/popover/README.md

@@ -92,7 +92,7 @@ The element should be stored in state rather than a plain ref to ensure reactive
 
 ### `anchorRect`: `DomRectWithOwnerDocument`
 
-_Note: this prop is deprecated and will be removed in WordPress 6.3. Please use the `anchor` prop instead._
+_Note: this prop is deprecated. Please use the `anchor` prop instead._
 
 An object extending a `DOMRect` with an additional optional `ownerDocument` property, used to specify a fixed popover position.
 
@@ -100,7 +100,7 @@ An object extending a `DOMRect` with an additional optional `ownerDocument` prop
 
 ### `anchorRef`: `Element | PopoverAnchorRefReference | PopoverAnchorRefTopBottom | Range`
 
-_Note: this prop is deprecated and will be removed in WordPress 6.3. Please use the `anchor` prop instead._
+_Note: this prop is deprecated. Please use the `anchor` prop instead._
 
 Used to specify a fixed popover position. It can be an `Element`, a React reference to an `element`, an object with a `top` and a `bottom` properties (both pointing to elements), or a `range`.
 
@@ -157,7 +157,7 @@ When not provided, the `onClose` callback will be called instead.
 
 ### `getAnchorRect`: `( fallbackReferenceElement: Element | null ) => DomRectWithOwnerDocument`
 
-_Note: this prop is deprecated and will be removed in WordPress 6.3. Please use the `anchor` prop instead._
+_Note: this prop is deprecated. Please use the `anchor` prop instead._
 
 A function returning the same value as the one expected by the `anchorRect` prop, used to specify a dynamic popover position.
 
@@ -171,6 +171,8 @@ Used to customize the header text shown when the popover is toggled to fullscree
 
 ### `isAlternate`: `boolean`
 
+_Note: this prop is deprecated. Please use the `variant` prop with the `'toolbar'` values instead._
+
 Used to enable a different visual style for the popover.
 
 -   Required: No
@@ -212,8 +214,7 @@ Possible values:
 - `yAxis`: `'top' | 'middle' | 'bottom'`
 - `xAxis`: `'left' | 'center' | 'right'`
 - `corner`: `'top' | 'right' | 'bottom' | 'left'`
-
-
+<!-- Break into two separate lists using an HTML comment -->
 -   Required: No
 
 ### `resize`: `boolean`
@@ -223,8 +224,12 @@ Adjusts the size of the popover to prevent its contents from going out of view w
 -   Required: No
 -   Default: `true`
 
-### `range`: `unknown`
+### `variant`: `'toolbar' | 'unstyled'`
 
-_Note: this prop is deprecated and will be removed in WordPress 6.3. It has no effect on the component._
+Specifies the popover's style.
 
+Leave undefined for the default style. Possible values are:
+-   `unstyled`:  The popover is essentially without any visible style, it has no background, border, outline or drop shadow, but the popover contents are still displayed.
+-   `toolbar`: A style that has no elevation, but a high contrast with other elements. This matches the style of the [`Toolbar` component](/packages/components/toolbar/README.md).
+<!-- Break into two separate lists using an HTML comment -->
 -   Required: No

package/src/popover/index.tsx

@@ -169,7 +169,6 @@ const UnforwardedPopover = (
 		children,
 		className,
 		noArrow = true,
-		isAlternate,
 		position,
 		placement: placementProp = 'bottom-start',
 		offset: offsetProp = 0,
@@ -181,30 +180,23 @@ const UnforwardedPopover = (
 		flip = true,
 		resize = true,
 		shift = false,
+		variant,
 
 		// Deprecated props
 		__unstableForcePosition,
-		__unstableShift,
 		anchorRef,
 		anchorRect,
 		getAnchorRect,
-		range,
+		isAlternate,
 
 		// Rest
 		...contentProps
 	} = props;
 
-	if ( range ) {
-		deprecated( '`range` prop in wp.components.Popover', {
-			since: '6.1',
-			version: '6.3',
-		} );
-	}
-
 	let computedFlipProp = flip;
 	let computedResizeProp = resize;
 	if ( __unstableForcePosition !== undefined ) {
-		deprecated( '`__unstableForcePosition` prop wp.components.Popover', {
+		deprecated( '`__unstableForcePosition` prop in wp.components.Popover', {
 			since: '6.1',
 			version: '6.3',
 			alternative: '`flip={ false }` and  `resize={ false }`',
@@ -216,22 +208,9 @@ const UnforwardedPopover = (
 		computedResizeProp = ! __unstableForcePosition;
 	}
 
-	let shouldShift = shift;
-	if ( __unstableShift !== undefined ) {
-		deprecated( '`__unstableShift` prop in wp.components.Popover', {
-			since: '6.1',
-			version: '6.3',
-			alternative: '`shift` prop`',
-		} );
-
-		// Back-compat.
-		shouldShift = __unstableShift;
-	}
-
 	if ( anchorRef !== undefined ) {
 		deprecated( '`anchorRef` prop in wp.components.Popover', {
 			since: '6.1',
-			version: '6.3',
 			alternative: '`anchor` prop',
 		} );
 	}
@@ -239,7 +218,6 @@ const UnforwardedPopover = (
 	if ( anchorRect !== undefined ) {
 		deprecated( '`anchorRect` prop in wp.components.Popover', {
 			since: '6.1',
-			version: '6.3',
 			alternative: '`anchor` prop',
 		} );
 	}
@@ -247,12 +225,19 @@ const UnforwardedPopover = (
 	if ( getAnchorRect !== undefined ) {
 		deprecated( '`getAnchorRect` prop in wp.components.Popover', {
 			since: '6.1',
-			version: '6.3',
 			alternative: '`anchor` prop',
 		} );
 	}
 
-	const arrowRef = useRef( null );
+	const computedVariant = isAlternate ? 'toolbar' : variant;
+	if ( isAlternate !== undefined ) {
+		deprecated( '`isAlternate` prop in wp.components.Popover', {
+			since: '6.2',
+			alternative: "`variant` prop with the `'toolbar'` value",
+		} );
+	}
+
+	const arrowRef = useRef< HTMLElement | null >( null );
 
 	const [ fallbackReferenceElement, setFallbackReferenceElement ] =
 		useState< HTMLSpanElement | null >( null );
@@ -325,7 +310,7 @@ const UnforwardedPopover = (
 					},
 			  } )
 			: undefined,
-		shouldShift
+		shift
 			? shiftMiddleware( {
 					crossAxis: true,
 					limiter: customLimitShift(),
@@ -385,7 +370,7 @@ const UnforwardedPopover = (
 	} );
 
 	const arrowCallbackRef = useCallback(
-		( node ) => {
+		( node: HTMLElement | null ) => {
 			arrowRef.current = node;
 			update();
 		},
@@ -476,7 +461,12 @@ const UnforwardedPopover = (
 			placement={ computedPlacement }
 			className={ classnames( 'components-popover', className, {
 				'is-expanded': isExpanded,
-				'is-alternate': isAlternate,
+				// Use the 'alternate' classname for 'toolbar' variant for back compat.
+				[ `is-${
+					computedVariant === 'toolbar'
+						? 'alternate'
+						: computedVariant
+				}` ]: computedVariant,
 			} ) }
 			{ ...contentProps }
 			ref={ mergedFloatingRef }

package/src/popover/stories/index.tsx

@@ -80,7 +80,7 @@ const PopoverWithAnchor = ( args: PopoverProps ) => {
 	);
 };
 
-export const Default: ComponentStory< typeof Popover > = ( args ) => {
+const Template: ComponentStory< typeof Popover > = ( args ) => {
 	const [ isVisible, setIsVisible ] = useState( false );
 	const toggleVisible = () => {
 		setIsVisible( ( state ) => ! state );
@@ -114,6 +114,8 @@ export const Default: ComponentStory< typeof Popover > = ( args ) => {
 		</div>
 	);
 };
+
+export const Default: ComponentStory< typeof Popover > = Template.bind( {} );
 Default.args = {
 	children: (
 		<div style={ { width: '280px', whiteSpace: 'normal' } }>
@@ -125,6 +127,32 @@ Default.args = {
 	),
 };
 
+export const Toolbar: ComponentStory< typeof Popover > = Template.bind( {} );
+Toolbar.args = {
+	children: (
+		<div style={ { width: '280px', whiteSpace: 'normal' } }>
+			Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+			eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
+			ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
+			aliquip ex ea commodo consequat.
+		</div>
+	),
+	variant: 'toolbar',
+};
+
+export const Unstyled: ComponentStory< typeof Popover > = Template.bind( {} );
+Unstyled.args = {
+	children: (
+		<div style={ { width: '280px', whiteSpace: 'normal' } }>
+			Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+			eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
+			ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
+			aliquip ex ea commodo consequat.
+		</div>
+	),
+	variant: 'unstyled',
+};
+
 export const AllPlacements: ComponentStory< typeof Popover > = ( {
 	children,
 	...args

package/src/popover/style.scss

@@ -29,6 +29,15 @@ $arrow-triangle-base-size: 14px;
 		box-shadow: none;
 	}
 
+	// A style that gives the popover no visible ui.
+	.is-unstyled & {
+		background: none;
+		border: none;
+		border-radius: 0;
+		outline: none;
+		box-shadow: none;
+	}
+
 	.components-popover.is-expanded & {
 		position: static;
 		height: calc(100% - #{ $panel-header-height });

package/src/popover/types.ts

@@ -92,10 +92,6 @@ export type PopoverProps = {
 	 * fullscreen on mobile viewports (see the `expandOnMobile` prop).
 	 */
 	headerTitle?: string;
-	/**
-	 * Used to enable a different visual style for the popover.
-	 */
-	isAlternate?: boolean;
 	/**
 	 * Used to show/hide the arrow that points at the popover's anchor.
 	 *
@@ -138,7 +134,20 @@ export type PopoverProps = {
 	 * @default false
 	 */
 	shift?: boolean;
-
+	/**
+	 * Specifies the popover's style.
+	 *
+	 * Leave undefined for the default style. Other values are:
+	 * - 'unstyled':  The popover is essentially without any visible style, it
+	 *                has no background, border, outline or drop shadow, but
+	 *                the popover contents are still displayed.
+	 * - 'toolbar':   A style that has no elevation, but a high contrast with
+	 *                other elements. This is matches the style of the
+	 *                `Toolbar` component.
+	 *
+	 * @default undefined
+	 */
+	variant?: 'unstyled' | 'toolbar';
 	// Deprecated props
 	/**
 	 * Prevent the popover from flipping and resizing when meeting the viewport
@@ -148,14 +157,6 @@ export type PopoverProps = {
 	 * @deprecated
 	 */
 	__unstableForcePosition?: boolean;
-	/**
-	 * Enables the `Popover` to shift in order to stay in view when meeting the
-	 * viewport edges.
-	 * _Note: this prop is deprecated. Use the `shift` prop instead._
-	 *
-	 * @deprecated
-	 */
-	__unstableShift?: boolean;
 	/**
 	 * An object extending a `DOMRect` with an additional optional `ownerDocument`
 	 * property, used to specify a fixed popover position.
@@ -185,9 +186,11 @@ export type PopoverProps = {
 		fallbackReferenceElement: Element | null
 	) => DomRectWithOwnerDocument;
 	/**
-	 * _Note: this prop is deprecated and has no effect on the component._
+	 * Used to enable a different visual style for the popover.
+	 * _Note: this prop is deprecated. Use the `variant` prop with the
+	 * 'toolbar' value instead._
 	 *
 	 * @deprecated
 	 */
-	range?: unknown;
+	isAlternate?: boolean;
 };

package/src/radio-group/README.md

@@ -1,5 +1,9 @@
 # RadioGroup
 
+<div class="callout callout-alert">
+This component is deprecated. Consider using `RadioControl` or `ToggleGroupControl` instead.
+</div>
+
 <div class="callout callout-alert">
 This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
 </div>

package/src/radio-group/index.js

@@ -1,3 +1,5 @@
+// @ts-nocheck
+
 /**
  * External dependencies
  */
@@ -12,7 +14,7 @@ import { forwardRef } from '@wordpress/element';
  * Internal dependencies
  */
 import ButtonGroup from '../button-group';
-import RadioContext from '../radio-context';
+import RadioContext from './radio-context';
 
 function RadioGroup(
 	{ label, checked, defaultChecked, disabled, onChange, ...props },
@@ -43,4 +45,7 @@ function RadioGroup(
 	);
 }
 
+/**
+ * @deprecated Use `RadioControl` or `ToggleGroupControl` instead.
+ */
 export default forwardRef( RadioGroup );

package/src/{radio → radio-group/radio}/index.js

@@ -1,3 +1,5 @@
+// @ts-nocheck
+
 /**
  * External dependencies
  */
@@ -11,7 +13,7 @@ import { useContext, forwardRef } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import Button from '../button';
+import Button from '../../button';
 import RadioContext from '../radio-context';
 
 function Radio( { children, value, ...props }, ref ) {
@@ -32,4 +34,7 @@ function Radio( { children, value, ...props }, ref ) {
 	);
 }
 
+/**
+ * @deprecated Use `RadioControl` or `ToggleGroupControl` instead.
+ */
 export default forwardRef( Radio );

package/src/radio-group/stories/index.js

@@ -6,12 +6,21 @@ import { useState } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import Radio from '../../radio';
+import Radio from '../radio';
 import RadioGroup from '../';
 
 export default {
-	title: 'Components (Experimental)/RadioGroup',
+	title: 'Components (Deprecated)/RadioGroup',
+	subcomponents: { Radio },
 	component: RadioGroup,
+	parameters: {
+		docs: {
+			description: {
+				component:
+					'This component is deprecated. Use `RadioControl` or `ToggleGroupControl` instead.',
+			},
+		},
+	},
 };
 
 export const _default = () => {

package/src/sandbox/test/index.js

@@ -39,9 +39,9 @@ describe( 'Sandbox', () => {
 	};
 
 	it( 'should rerender with new emdeded content if html prop changes', () => {
-		const result = render( <TestWrapper /> );
+		const { container } = render( <TestWrapper /> );
 
-		const iframe = result.container.querySelector( '.components-sandbox' );
+		const iframe = container.querySelector( '.components-sandbox' );
 
 		let sandboxedIframe =
 			iframe.contentWindow.document.body.querySelector( '.mock-iframe' );

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

@@ -25,15 +25,17 @@ const meta: ComponentMeta< typeof SelectControl > = {
 		value: { control: { type: null } },
 	},
 	parameters: {
+		actions: { argTypesRegex: '^on.*' },
 		controls: { expanded: true },
 		docs: { source: { state: 'open' } },
 	},
 };
 export default meta;
 
-const SelectControlWithState: ComponentStory< typeof SelectControl > = (
-	args
-) => {
+const SelectControlWithState: ComponentStory< typeof SelectControl > = ( {
+	onChange,
+	...args
+} ) => {
 	const [ selection, setSelection ] =
 		useState< ComponentProps< typeof SelectControl >[ 'value' ] >();
 
@@ -41,7 +43,10 @@ const SelectControlWithState: ComponentStory< typeof SelectControl > = (
 		<SelectControl
 			{ ...args }
 			value={ selection }
-			onChange={ setSelection }
+			onChange={ ( value ) => {
+				setSelection( value );
+				onChange?.( value );
+			} }
 		/>
 	);
 };

package/src/slot-fill/bubbles-virtually/fill.js

@@ -28,18 +28,18 @@ function useForceUpdate() {
 }
 
 export default function Fill( { name, children } ) {
-	const slot = useSlot( name );
+	const { registerFill, unregisterFill, ...slot } = useSlot( name );
 	const ref = useRef( { rerender: useForceUpdate() } );
 
 	useEffect( () => {
-		// We register fills so we can keep track of their existance.
+		// We register fills so we can keep track of their existence.
 		// Some Slot implementations need to know if there're already fills
 		// registered so they can choose to render themselves or not.
-		slot.registerFill( ref );
+		registerFill( ref );
 		return () => {
-			slot.unregisterFill( ref );
+			unregisterFill( ref );
 		};
-	}, [ slot.registerFill, slot.unregisterFill ] );
+	}, [ registerFill, unregisterFill ] );
 
 	if ( ! slot.ref || ! slot.ref.current ) {
 		return null;

package/src/slot-fill/bubbles-virtually/slot.js

@@ -19,19 +19,21 @@ function Slot(
 	{ name, fillProps = {}, as: Component = 'div', ...props },
 	forwardedRef
 ) {
-	const registry = useContext( SlotFillContext );
+	const { registerSlot, unregisterSlot, ...registry } =
+		useContext( SlotFillContext );
 	const ref = useRef();
 
 	useLayoutEffect( () => {
-		registry.registerSlot( name, ref, fillProps );
+		registerSlot( name, ref, fillProps );
 		return () => {
-			registry.unregisterSlot( name, ref );
+			unregisterSlot( name, ref );
 		};
-		// We are not including fillProps in the deps because we don't want to
-		// unregister and register the slot whenever fillProps change, which would
-		// cause the fill to be re-mounted. We are only considering the initial value
-		// of fillProps.
-	}, [ registry.registerSlot, registry.unregisterSlot, name ] );
+		// Ignore reason: We don't want to unregister and register the slot whenever
+		// `fillProps` change, which would cause the fill to be re-mounted. Instead,
+		// we can just update the slot (see hook below).
+		// For more context, see https://github.com/WordPress/gutenberg/pull/44403#discussion_r994415973
+		// eslint-disable-next-line react-hooks/exhaustive-deps
+	}, [ registerSlot, unregisterSlot, name ] );
 	// fillProps may be an update that interacts with the layout, so we
 	// useLayoutEffect.
 	useLayoutEffect( () => {

package/src/slot-fill/bubbles-virtually/use-slot.js

@@ -15,7 +15,13 @@ import { useCallback, useContext } from '@wordpress/element';
 import SlotFillContext from './slot-fill-context';
 
 export default function useSlot( name ) {
-	const registry = useContext( SlotFillContext );
+	const {
+		updateSlot: registryUpdateSlot,
+		unregisterSlot: registryUnregisterSlot,
+		registerFill: registryRegisterFill,
+		unregisterFill: registryUnregisterFill,
+		...registry
+	} = useContext( SlotFillContext );
 	const slots = useSnapshot( registry.slots, { sync: true } );
 	// The important bit here is that this call ensures
 	// the hook only causes a re-render if the slot
@@ -24,30 +30,30 @@ export default function useSlot( name ) {
 
 	const updateSlot = useCallback(
 		( fillProps ) => {
-			registry.updateSlot( name, fillProps );
+			registryUpdateSlot( name, fillProps );
 		},
-		[ name, registry.updateSlot ]
+		[ name, registryUpdateSlot ]
 	);
 
 	const unregisterSlot = useCallback(
 		( slotRef ) => {
-			registry.unregisterSlot( name, slotRef );
+			registryUnregisterSlot( name, slotRef );
 		},
-		[ name, registry.unregisterSlot ]
+		[ name, registryUnregisterSlot ]
 	);
 
 	const registerFill = useCallback(
 		( fillRef ) => {
-			registry.registerFill( name, fillRef );
+			registryRegisterFill( name, fillRef );
 		},
-		[ name, registry.registerFill ]
+		[ name, registryRegisterFill ]
 	);
 
 	const unregisterFill = useCallback(
 		( fillRef ) => {
-			registry.unregisterFill( name, fillRef );
+			registryUnregisterFill( name, fillRef );
 		},
-		[ name, registry.unregisterFill ]
+		[ name, registryUnregisterFill ]
 	);
 
 	return {

package/src/slot-fill/fill.js

@@ -20,8 +20,12 @@ function FillComponent( { name, children, registerFill, unregisterFill } ) {
 	} );
 
 	useLayoutEffect( () => {
-		registerFill( name, ref.current );
-		return () => unregisterFill( name, ref.current );
+		const refValue = ref.current;
+		registerFill( name, refValue );
+		return () => unregisterFill( name, refValue );
+		// Ignore reason: the useLayoutEffects here are written to fire at specific times, and introducing new dependencies could cause unexpected changes in behavior.
+		// We'll leave them as-is until a more detailed investigation/refactor can be performed.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [] );
 
 	useLayoutEffect( () => {
@@ -29,6 +33,9 @@ function FillComponent( { name, children, registerFill, unregisterFill } ) {
 		if ( slot ) {
 			slot.forceUpdate();
 		}
+		// Ignore reason: the useLayoutEffects here are written to fire at specific times, and introducing new dependencies could cause unexpected changes in behavior.
+		// We'll leave them as-is until a more detailed investigation/refactor can be performed.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [ children ] );
 
 	useLayoutEffect( () => {
@@ -39,6 +46,9 @@ function FillComponent( { name, children, registerFill, unregisterFill } ) {
 		unregisterFill( ref.current.name, ref.current );
 		ref.current.name = name;
 		registerFill( name, ref.current );
+		// Ignore reason: the useLayoutEffects here are written to fire at specific times, and introducing new dependencies could cause unexpected changes in behavior.
+		// We'll leave them as-is until a more detailed investigation/refactor can be performed.
+		// eslint-disable-next-line react-hooks/exhaustive-deps
 	}, [ name ] );
 
 	if ( ! slot || ! slot.node ) {