@wordpress/components 19.11.0 → 19.12.0

package/src/input-control/reducer/reducer.ts

@@ -1,12 +1,12 @@
 /**
  * External dependencies
  */
-import type { SyntheticEvent } from 'react';
+import type { SyntheticEvent, ChangeEvent, PointerEvent } from 'react';
 
 /**
  * WordPress dependencies
  */
-import { useReducer } from '@wordpress/element';
+import { useReducer, useLayoutEffect, useRef } from '@wordpress/element';
 
 /**
  * Internal dependencies
@@ -18,6 +18,7 @@ import {
 	initialStateReducer,
 } from './state';
 import * as actions from './actions';
+import type { InputChangeCallback } from '../types';
 
 /**
  * Prepares initialState for the reducer.
@@ -108,9 +109,7 @@ function inputControlStateReducer(
 				break;
 		}
 
-		if ( action.payload.event ) {
-			nextState._event = action.payload.event;
-		}
+		nextState._event = action.payload.event;
 
 		/**
 		 * Send the nextState + action to the composedReducers via
@@ -131,13 +130,15 @@ function inputControlStateReducer(
  * This technique uses the "stateReducer" design pattern:
  * https://kentcdodds.com/blog/the-state-reducer-pattern/
  *
- * @param  stateReducer An external state reducer.
- * @param  initialState The initial state for the reducer.
+ * @param  stateReducer    An external state reducer.
+ * @param  initialState    The initial state for the reducer.
+ * @param  onChangeHandler A handler for the onChange event.
  * @return State, dispatch, and a collection of actions.
  */
 export function useInputControlStateReducer(
 	stateReducer: StateReducer = initialStateReducer,
-	initialState: Partial< InputState > = initialInputControlState
+	initialState: Partial< InputState > = initialInputControlState,
+	onChangeHandler: InputChangeCallback
 ) {
 	const [ state, dispatch ] = useReducer< StateReducer >(
 		inputControlStateReducer( stateReducer ),
@@ -148,15 +149,6 @@ export function useInputControlStateReducer(
 		nextValue: actions.ChangeEventAction[ 'payload' ][ 'value' ],
 		event: actions.ChangeEventAction[ 'payload' ][ 'event' ]
 	) => {
-		/**
-		 * Persist allows for the (Synthetic) event to be used outside of
-		 * this function call.
-		 * https://reactjs.org/docs/events.html#event-pooling
-		 */
-		if ( event && event.persist ) {
-			event.persist();
-		}
-
 		dispatch( {
 			type,
 			payload: { value: nextValue, event },
@@ -166,15 +158,6 @@ export function useInputControlStateReducer(
 	const createKeyEvent = ( type: actions.KeyEventAction[ 'type' ] ) => (
 		event: actions.KeyEventAction[ 'payload' ][ 'event' ]
 	) => {
-		/**
-		 * Persist allows for the (Synthetic) event to be used outside of
-		 * this function call.
-		 * https://reactjs.org/docs/events.html#event-pooling
-		 */
-		if ( event && event.persist ) {
-			event.persist();
-		}
-
 		dispatch( { type, payload: { event } } );
 	};
 
@@ -201,6 +184,37 @@ export function useInputControlStateReducer(
 	const pressDown = createKeyEvent( actions.PRESS_DOWN );
 	const pressEnter = createKeyEvent( actions.PRESS_ENTER );
 
+	const currentState = useRef( state );
+	const refProps = useRef( { value: initialState.value, onChangeHandler } );
+	useLayoutEffect( () => {
+		currentState.current = state;
+		refProps.current = { value: initialState.value, onChangeHandler };
+	} );
+	useLayoutEffect( () => {
+		if (
+			currentState.current._event !== undefined &&
+			state.value !== refProps.current.value &&
+			! state.isDirty
+		) {
+			refProps.current.onChangeHandler( state.value ?? '', {
+				event: currentState.current._event as
+					| ChangeEvent< HTMLInputElement >
+					| PointerEvent< HTMLInputElement >,
+			} );
+		}
+	}, [ state.value, state.isDirty ] );
+	useLayoutEffect( () => {
+		if (
+			initialState.value !== currentState.current.value &&
+			! currentState.current.isDirty
+		) {
+			dispatch( {
+				type: actions.RESET,
+				payload: { value: initialState.value },
+			} );
+		}
+	}, [ initialState.value ] );
+
 	return {
 		change,
 		commit,

package/src/input-control/reducer/state.ts

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { Reducer } from 'react';
+import type { Reducer, SyntheticEvent } from 'react';
 
 /**
  * Internal dependencies
@@ -9,7 +9,7 @@ import type { Reducer } from 'react';
 import type { InputAction } from './actions';
 
 export interface InputState {
-	_event: Event | {};
+	_event?: SyntheticEvent;
 	error: unknown;
 	initialValue?: string;
 	isDirty: boolean;
@@ -24,7 +24,6 @@ export type StateReducer = Reducer< InputState, InputAction >;
 export const initialStateReducer: StateReducer = ( state: InputState ) => state;
 
 export const initialInputControlState: InputState = {
-	_event: {},
 	error: null,
 	initialValue: '',
 	isDirty: false,

package/src/input-control/utils.ts

@@ -1,7 +1,22 @@
+/**
+ * External dependencies
+ */
+import type { FocusEventHandler } from 'react';
+
 /**
  * WordPress dependencies
  */
-import { useEffect } from '@wordpress/element';
+import {
+	useEffect,
+	useLayoutEffect,
+	useRef,
+	useState,
+} from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { InputChangeCallback } from './types';
 
 /**
  * Gets a CSS cursor value based on a drag direction.
@@ -52,3 +67,42 @@ export function useDragCursor(
 
 	return dragCursor;
 }
+
+export function useDraft( props: {
+	value: string | undefined;
+	onBlur?: FocusEventHandler;
+	onChange: InputChangeCallback;
+} ) {
+	const refPreviousValue = useRef( props.value );
+	const [ draft, setDraft ] = useState< {
+		value?: string;
+		isStale?: boolean;
+	} >( {} );
+	const value = draft.value !== undefined ? draft.value : props.value;
+
+	// Determines when to discard the draft value to restore controlled status.
+	// To do so, it tracks the previous value and marks the draft value as stale
+	// after each render.
+	useLayoutEffect( () => {
+		const { current: previousValue } = refPreviousValue;
+		refPreviousValue.current = props.value;
+		if ( draft.value !== undefined && ! draft.isStale )
+			setDraft( { ...draft, isStale: true } );
+		else if ( draft.isStale && props.value !== previousValue )
+			setDraft( {} );
+	}, [ props.value, draft ] );
+
+	const onChange: InputChangeCallback = ( nextValue, extra ) => {
+		// Mutates the draft value to avoid an extra effect run.
+		setDraft( ( current ) =>
+			Object.assign( current, { value: nextValue, isStale: false } )
+		);
+		props.onChange( nextValue, extra );
+	};
+	const onBlur: FocusEventHandler = ( event ) => {
+		setDraft( {} );
+		props.onBlur?.( event );
+	};
+
+	return { value, onBlur, onChange };
+}

package/src/popover/index.js

@@ -115,6 +115,7 @@ const Popover = (
 		__unstableSlotName = SLOT_NAME,
 		__unstableObserveElement,
 		__unstableForcePosition,
+		__unstableShift = false,
 		...contentProps
 	},
 	ref
@@ -134,26 +135,29 @@ const Popover = (
 		? positionToPlacement( position )
 		: placement;
 
-	/**
-	 * Offsets the the position of the popover when the anchor is inside an iframe.
-	 */
-	const frameOffset = useMemo( () => {
-		let ownerDocument = document;
+	const ownerDocument = useMemo( () => {
 		if ( anchorRef?.top ) {
-			ownerDocument = anchorRef?.top.ownerDocument;
+			return anchorRef?.top.ownerDocument;
 		} else if ( anchorRef?.startContainer ) {
-			ownerDocument = anchorRef.startContainer.ownerDocument;
+			return anchorRef.startContainer.ownerDocument;
 		} else if ( anchorRef?.current ) {
-			ownerDocument = anchorRef.current.ownerDocument;
+			return anchorRef.current.ownerDocument;
 		} else if ( anchorRef ) {
 			// This one should be deprecated.
-			ownerDocument = anchorRef.ownerDocument;
+			return anchorRef.ownerDocument;
 		} else if ( anchorRect && anchorRect?.ownerDocument ) {
-			ownerDocument = anchorRect.ownerDocument;
+			return anchorRect.ownerDocument;
 		} else if ( getAnchorRect ) {
-			ownerDocument = getAnchorRect()?.ownerDocument ?? document;
+			return getAnchorRect()?.ownerDocument ?? document;
 		}
 
+		return document;
+	}, [ anchorRef, anchorRect, getAnchorRect ] );
+
+	/**
+	 * Offsets the the position of the popover when the anchor is inside an iframe.
+	 */
+	const frameOffset = useMemo( () => {
 		const { defaultView } = ownerDocument;
 		const { frameElement } = defaultView;
 
@@ -171,7 +175,7 @@ const Popover = (
 				};
 			},
 		};
-	}, [ anchorRef, anchorRect, getAnchorRect ] );
+	}, [ ownerDocument ] );
 
 	const middlewares = [
 		frameOffset,
@@ -180,21 +184,23 @@ const Popover = (
 		__unstableForcePosition
 			? undefined
 			: size( {
-					apply( { width, height } ) {
+					apply( sizeProps ) {
+						const { height } = sizeProps;
 						if ( ! refs.floating.current ) return;
-
+						// Reduce the height of the popover to the available space.
 						Object.assign( refs.floating.current.firstChild.style, {
-							maxWidth: `${ width }px`,
 							maxHeight: `${ height }px`,
 							overflow: 'auto',
 						} );
 					},
 			  } ),
-		,
-		shift( {
-			crossAxis: true,
-			limiter: limitShift(),
-		} ),
+		__unstableShift
+			? shift( {
+					crossAxis: true,
+					limiter: limitShift(),
+					padding: 1, // Necessary to avoid flickering at the edge of the viewport.
+			  } )
+			: undefined,
 		hasArrow ? arrow( { element: arrowRef } ) : undefined,
 	].filter( ( m ) => !! m );
 	const anchorRefFallback = useRef( null );
@@ -270,13 +276,12 @@ const Popover = (
 			usedRef = {
 				getBoundingClientRect() {
 					const rect = getAnchorRect();
-					return {
-						...rect,
-						x: rect.x ?? rect.left,
-						y: rect.y ?? rect.top,
-						height: rect.height ?? rect.bottom - rect.top,
-						width: rect.width ?? rect.right - rect.left,
-					};
+					return new window.DOMRect(
+						rect.x ?? rect.left,
+						rect.y ?? rect.top,
+						rect.width ?? rect.right - rect.left,
+						rect.height ?? rect.bottom - rect.top
+					);
 				},
 			};
 		} else if ( anchorRefFallback.current ) {
@@ -309,6 +314,16 @@ const Popover = (
 		};
 	}, [ __unstableObserveElement ] );
 
+	// If we're using getAnchorRect, we need to update the position as we scroll the iframe.
+	useLayoutEffect( () => {
+		if ( ownerDocument === document ) {
+			return;
+		}
+
+		ownerDocument.addEventListener( 'scroll', update );
+		return () => ownerDocument.removeEventListener( 'scroll', update );
+	}, [ ownerDocument ] );
+
 	/** @type {false | string} */
 	const animateClassName =
 		!! animate &&

package/src/query-controls/README.md

@@ -179,7 +179,7 @@ A function that receives the new author value. If this is not specified, the aut
 
 #### onCategoryChange
 
-A function that receives the new author value. If this is not specified, the category controls are not included.
+A function that receives the new category value. If this is not specified, the category controls are not included.
 
 -   Type: `Function`
 -   Required: No

package/src/search-control/index.js

@@ -6,17 +6,16 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies
  */
-import { useInstanceId } from '@wordpress/compose';
+import { useInstanceId, useMergeRefs } from '@wordpress/compose';
 import { __ } from '@wordpress/i18n';
 import { Icon, search, closeSmall } from '@wordpress/icons';
-import { forwardRef } from '@wordpress/element';
+import { forwardRef, useRef } from '@wordpress/element';
 
 /**
  * Internal dependencies
  */
 import { Button } from '../';
 import BaseControl from '../base-control';
-import { useCombinedRef } from '../utils';
 
 function SearchControl(
 	{
@@ -30,10 +29,10 @@ function SearchControl(
 		help,
 		onClose,
 	},
-	ref
+	forwardedRef
 ) {
+	const searchRef = useRef();
 	const instanceId = useInstanceId( SearchControl );
-	const searchInput = useCombinedRef( ref );
 	const id = `components-search-control-${ instanceId }`;
 
 	const renderRightButton = () => {
@@ -54,7 +53,7 @@ function SearchControl(
 					label={ __( 'Reset search' ) }
 					onClick={ () => {
 						onChange( '' );
-						searchInput.current.focus();
+						searchRef.current.focus();
 					} }
 				/>
 			);
@@ -73,7 +72,7 @@ function SearchControl(
 		>
 			<div className="components-search-control__input-wrapper">
 				<input
-					ref={ searchInput }
+					ref={ useMergeRefs( [ searchRef, forwardedRef ] ) }
 					className="components-search-control__input"
 					id={ id }
 					type="search"

package/src/select-control/README.md

@@ -98,6 +98,7 @@ const MySelectControl = () => {
 				{ label: 'Small', value: '25%' },
 			] }
 			onChange={ ( newSize ) => setSize( newSize ) }
+			__nextHasNoMarginBottom
 		/>
 	);
 };
@@ -119,6 +120,7 @@ Render a user interface to select multiple users from a list.
 		{ value: 'b', label: 'User B' },
 		{ value: 'c', label: 'User c' },
 	] }
+	__nextHasNoMarginBottom
 />
 ```
 
@@ -133,6 +135,7 @@ const [ item, setItem ] = useState( '' );
     label={ __( 'Select an item:' ) }
     value={ item } // e.g: value = 'a'
     onChange={ ( selection ) => { setItem( selection ) } }
+    __nextHasNoMarginBottom
 >
 	<optgroup label="Theropods">
 		<option value="Tyrannosaurus">Tyrannosaurus</option>
@@ -215,6 +218,14 @@ If multiple is false the value received is a single value with the new selected
 -   Type: `function`
 -   Required: Yes
 
+### __nextHasNoMarginBottom
+
+Start opting into the new margin-free styles that will become the default in a future version.
+
+-   Type: `Boolean`
+-   Required: No
+-   Default: `false`
+
 ## Related components
 
 -   To select one option from a set, and you want to show them all the available options at once, use the `Radio` component.

package/src/select-control/index.tsx

@@ -47,6 +47,7 @@ function UnforwardedSelectControl(
 		children,
 		prefix,
 		suffix,
+		__nextHasNoMarginBottom = false,
 		...props
 	}: WordPressComponentProps< SelectControlProps, 'select', false >,
 	ref: ForwardedRef< HTMLSelectElement >
@@ -85,7 +86,11 @@ function UnforwardedSelectControl(
 
 	/* eslint-disable jsx-a11y/no-onchange */
 	return (
-		<BaseControl help={ help } id={ id }>
+		<BaseControl
+			help={ help }
+			id={ id }
+			__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
+		>
 			<InputBase
 				className={ classes }
 				disabled={ disabled }

package/src/select-control/types.ts

@@ -20,7 +20,7 @@ export interface SelectControlProps
 			| 'size'
 			| 'suffix'
 		>,
-		Pick< BaseControlProps, 'help' > {
+		Pick< BaseControlProps, 'help' | '__nextHasNoMarginBottom' > {
 	/**
 	 * If this property is added, multiple values can be selected. The value passed should be an array.
 	 *

package/src/slot-fill/README.md

@@ -2,7 +2,7 @@
 
 Slot and Fill are a pair of components which enable developers to render elsewhere in a React element tree, a pattern often referred to as "portal" rendering. It is a pattern for component extensibility, where a single Slot may be occupied by an indeterminate number of Fills elsewhere in the application.
 
-Slot Fill is heavily inspired by the [`react-slot-fill` library](https://github.com/camwest/react-slot-fill), but uses React's own portal rendering API, exposed as an unstable API in React 16 and slated to be promoted to a stable API in React 17.
+Slot Fill is heavily inspired by the [`react-slot-fill` library](https://github.com/camwest/react-slot-fill), but uses React's own portal rendering API.
 
 ## Usage
 

package/src/spacer/hook.ts

@@ -8,7 +8,7 @@ import { css } from '@emotion/react';
  */
 import { useContextSystem, WordPressComponentProps } from '../ui/context';
 import { space } from '../ui/utils/space';
-import { useCx } from '../utils/hooks/use-cx';
+import { rtl, useCx } from '../utils';
 import type { Props } from './types';
 
 const isDefined = < T >( o: T ): o is Exclude< T, null | undefined > =>
@@ -60,13 +60,13 @@ export function useSpacer( props: WordPressComponentProps< Props, 'div' > ) {
 				margin-bottom: ${ space( marginBottom ) };
 			`,
 		isDefined( marginLeft ) &&
-			css`
-				margin-left: ${ space( marginLeft ) };
-			`,
+			rtl( {
+				marginLeft: space( marginLeft ),
+			} )(),
 		isDefined( marginRight ) &&
-			css`
-				margin-right: ${ space( marginRight ) };
-			`,
+			rtl( {
+				marginRight: space( marginRight ),
+			} )(),
 		isDefined( padding ) &&
 			css`
 				padding: ${ space( padding ) };
@@ -90,13 +90,13 @@ export function useSpacer( props: WordPressComponentProps< Props, 'div' > ) {
 				padding-bottom: ${ space( paddingBottom ) };
 			`,
 		isDefined( paddingLeft ) &&
-			css`
-				padding-left: ${ space( paddingLeft ) };
-			`,
+			rtl( {
+				paddingLeft: space( paddingLeft ),
+			} )(),
 		isDefined( paddingRight ) &&
-			css`
-				padding-right: ${ space( paddingRight ) };
-			`,
+			rtl( {
+				paddingRight: space( paddingRight ),
+			} )(),
 		className
 	);
 

package/src/surface/README.md

@@ -13,7 +13,7 @@ In the example below, notice how the `Surface` renders in white (or dark gray if
 ```jsx
 import {
 	__experimentalSurface as Surface,
-	__experimentalText as Text
+	__experimentalText as Text,
 } from '@wordpress/components';
 
 function Example() {
@@ -27,46 +27,46 @@ function Example() {
 
 ## Props
 
-### `backgroundSize`: number
+### `backgroundSize`: `number`
 
-- Required: No
-- Default: `12`
+-   Required: No
+-   Default: `12`
 
 Determines the grid size for "dotted" and "grid" variants.
 
 ### `borderBottom`: `boolean`
 
-- Required: No
-- Default: `false`
+-   Required: No
+-   Default: `false`
 
 Renders a bottom border.
 
 ### `borderLeft`: `boolean`
 
-- Required: No
-- Default: `false`
+-   Required: No
+-   Default: `false`
 
 Renders a left border.
 
 ### `borderRight`: `boolean`
 
-- Required: No
-- Default: `false`
+-   Required: No
+-   Default: `false`
 
 Renders a right border.
 
 ### `borderTop`: `boolean`
 
-- Required: No
-- Default: `false`
+-   Required: No
+-   Default: `false`
 
 Renders a top border.
 
 ### `variant`: `string`
 
-- Required: No
-- Default: `false`
-- Allowed values: `primary`, `secondary`, `tertiary`, `dotted`, `grid`
+-   Required: No
+-   Default: `false`
+-   Allowed values: `primary`, `secondary`, `tertiary`, `dotted`, `grid`
 
 Modifies the background color of `Surface`.
 

package/src/surface/{component.js → component.tsx}

@@ -1,15 +1,21 @@
+/**
+ * External dependencies
+ */
+import type { ForwardedRef } from 'react';
+
 /**
  * Internal dependencies
  */
 import { contextConnect } from '../ui/context';
 import { View } from '../view';
 import { useSurface } from './hook';
+import type { SurfaceProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
 
-/**
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- * @param {import('react').ForwardedRef<any>}                                               forwardedRef
- */
-function Surface( props, forwardedRef ) {
+function UnconnectedSurface(
+	props: WordPressComponentProps< SurfaceProps, 'div' >,
+	forwardedRef: ForwardedRef< any >
+) {
 	const surfaceProps = useSurface( props );
 
 	return <View { ...surfaceProps } ref={ forwardedRef } />;
@@ -35,6 +41,6 @@ function Surface( props, forwardedRef ) {
  * }
  * ```
  */
-const ConnectedSurface = contextConnect( Surface, 'Surface' );
+export const Surface = contextConnect( UnconnectedSurface, 'Surface' );
 
-export default ConnectedSurface;
+export default Surface;

package/src/surface/{hook.js → hook.ts}

@@ -9,11 +9,12 @@ import { useMemo } from '@wordpress/element';
 import { useContextSystem } from '../ui/context';
 import * as styles from './styles';
 import { useCx } from '../utils/hooks/use-cx';
+import type { SurfaceProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
 
-/**
- * @param {import('../ui/context').WordPressComponentProps<import('./types').Props, 'div'>} props
- */
-export function useSurface( props ) {
+export function useSurface(
+	props: WordPressComponentProps< SurfaceProps, 'div' >
+) {
 	const {
 		backgroundSize = 12,
 		borderBottom = false,
@@ -28,14 +29,14 @@ export function useSurface( props ) {
 	const cx = useCx();
 
 	const classes = useMemo( () => {
-		const sx = {};
-
-		sx.borders = styles.getBorders( {
-			borderBottom,
-			borderLeft,
-			borderRight,
-			borderTop,
-		} );
+		const sx = {
+			borders: styles.getBorders( {
+				borderBottom,
+				borderLeft,
+				borderRight,
+				borderTop,
+			} ),
+		};
 
 		return cx(
 			styles.Surface,