@wordpress/components 23.3.1 → 23.4.0

package/build-types/utils/hooks/use-controlled-value.d.ts

@@ -7,10 +7,10 @@ declare type Props<T> = {
 /**
  * Simplified and improved implementation of useControlledState.
  *
- * @param  props
- * @param  props.defaultValue
- * @param  props.value
- * @param  props.onChange
+ * @param props
+ * @param props.defaultValue
+ * @param props.value
+ * @param props.onChange
  * @return The controlled value and the value setter.
  */
 export declare function useControlledValue<T>({ defaultValue, onChange, value: valueProp, }: Props<T>): readonly [T | undefined, import("react").Dispatch<import("react").SetStateAction<T | undefined>>];

package/build-types/utils/hooks/use-latest-ref.d.ts

@@ -8,7 +8,7 @@ import type { RefObject } from 'react';
  *
  * @see https://codesandbox.io/s/uselatestref-mlj3i?file=/src/App.tsx
  *
- * @param  value The value to reference
+ * @param value The value to reference
  * @return The prop reference.
  */
 export declare function useLatestRef<T>(value: T): RefObject<T>;

package/build-types/utils/unit-values.d.ts

@@ -1,7 +1,7 @@
 /**
  * Parses a number and unit from a value.
  *
- * @param  toParse Value to parse
+ * @param toParse Value to parse
  *
  * @return  The extracted number and unit.
  */
@@ -9,8 +9,8 @@ export declare function parseCSSUnitValue(toParse: string): [number | undefined,
 /**
  * Combines a value and a unit into a unit value.
  *
- * @param  value
- * @param  unit
+ * @param value
+ * @param unit
  *
  * @return The unit value.
  */

package/build-types/v-stack/component.d.ts

@@ -23,10 +23,10 @@
  * ```
  */
 export declare const VStack: import("../ui/context").WordPressComponent<"div", Omit<import("../flex/types").FlexProps, "gap" | "align"> & {
-    alignment?: "initial" | "left" | "right" | (string & {}) | "bottom" | "top" | "-moz-initial" | "inherit" | "revert" | "unset" | "stretch" | "center" | "end" | "flex-end" | "flex-start" | "start" | "baseline" | "normal" | "self-end" | "self-start" | "bottomLeft" | "bottomRight" | "edge" | "topLeft" | "topRight" | undefined;
+    alignment?: "initial" | "left" | "right" | (string & {}) | "bottom" | "top" | "-moz-initial" | "inherit" | "revert" | "unset" | "stretch" | "center" | "end" | "flex-end" | "flex-start" | "start" | "baseline" | "normal" | "self-end" | "self-start" | "edge" | "bottomLeft" | "bottomRight" | "topLeft" | "topRight" | undefined;
     spacing?: import("csstype").Property.Width<string | number> | undefined;
 } & {
-    alignment?: "initial" | "left" | "right" | (string & {}) | "bottom" | "top" | "-moz-initial" | "inherit" | "revert" | "unset" | "stretch" | "center" | "end" | "flex-end" | "flex-start" | "start" | "baseline" | "normal" | "self-end" | "self-start" | "bottomLeft" | "bottomRight" | "edge" | "topLeft" | "topRight" | undefined;
+    alignment?: "initial" | "left" | "right" | (string & {}) | "bottom" | "top" | "-moz-initial" | "inherit" | "revert" | "unset" | "stretch" | "center" | "end" | "flex-end" | "flex-start" | "start" | "baseline" | "normal" | "self-end" | "self-start" | "edge" | "bottomLeft" | "bottomRight" | "topLeft" | "topRight" | undefined;
     spacing?: import("csstype").Property.Width<string | number> | undefined;
 } & import("react").RefAttributes<any>, true>;
 export default VStack;

package/build-types/v-stack/hook.d.ts

@@ -18,7 +18,6 @@ export declare function useVStack(props: WordPressComponentProps<VStackProps, 'd
     key?: import("react").Key | null | undefined;
     slot?: string | undefined;
     title?: string | undefined;
-    id?: string | undefined;
     defaultChecked?: boolean | undefined;
     suppressContentEditableWarning?: boolean | undefined;
     suppressHydrationWarning?: boolean | undefined;
@@ -27,6 +26,7 @@ export declare function useVStack(props: WordPressComponentProps<VStackProps, 'd
     contextMenu?: string | undefined;
     dir?: string | undefined;
     draggable?: (boolean | "false" | "true") | undefined;
+    id?: string | undefined;
     lang?: string | undefined;
     placeholder?: string | undefined;
     spellCheck?: (boolean | "false" | "true") | undefined;
@@ -63,7 +63,7 @@ export declare function useVStack(props: WordPressComponentProps<VStackProps, 'd
     'aria-colindex'?: number | undefined;
     'aria-colspan'?: number | undefined;
     'aria-controls'?: string | undefined;
-    'aria-current'?: boolean | "page" | "false" | "true" | "time" | "location" | "step" | "date" | undefined;
+    'aria-current'?: boolean | "page" | "false" | "true" | "time" | "date" | "step" | "location" | undefined;
     'aria-describedby'?: string | undefined;
     'aria-details'?: string | undefined;
     'aria-disabled'?: (boolean | "false" | "true") | undefined;

package/build-types/v-stack/stories/index.d.ts

@@ -7,10 +7,10 @@ import { VStack } from '..';
 declare const meta: ComponentMeta<typeof VStack>;
 export default meta;
 export declare const Default: ComponentStory<import("../../ui/context").WordPressComponent<"div", Omit<import("../../flex/types").FlexProps, "gap" | "align"> & {
-    alignment?: "initial" | "left" | "right" | (string & {}) | "bottom" | "top" | "-moz-initial" | "inherit" | "revert" | "unset" | "stretch" | "center" | "end" | "flex-end" | "flex-start" | "start" | "baseline" | "normal" | "self-end" | "self-start" | "bottomLeft" | "bottomRight" | "edge" | "topLeft" | "topRight" | undefined;
+    alignment?: "initial" | "left" | "right" | (string & {}) | "bottom" | "top" | "-moz-initial" | "inherit" | "revert" | "unset" | "stretch" | "center" | "end" | "flex-end" | "flex-start" | "start" | "baseline" | "normal" | "self-end" | "self-start" | "edge" | "bottomLeft" | "bottomRight" | "topLeft" | "topRight" | undefined;
     spacing?: import("csstype").Property.Width<string | number> | undefined;
 } & {
-    alignment?: "initial" | "left" | "right" | (string & {}) | "bottom" | "top" | "-moz-initial" | "inherit" | "revert" | "unset" | "stretch" | "center" | "end" | "flex-end" | "flex-start" | "start" | "baseline" | "normal" | "self-end" | "self-start" | "bottomLeft" | "bottomRight" | "edge" | "topLeft" | "topRight" | undefined;
+    alignment?: "initial" | "left" | "right" | (string & {}) | "bottom" | "top" | "-moz-initial" | "inherit" | "revert" | "unset" | "stretch" | "center" | "end" | "flex-end" | "flex-start" | "start" | "baseline" | "normal" | "self-end" | "self-start" | "edge" | "bottomLeft" | "bottomRight" | "topLeft" | "topRight" | undefined;
     spacing?: import("csstype").Property.Width<string | number> | undefined;
 } & import("react").RefAttributes<any>, true>>;
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/components",
-	"version": "23.3.1",
+	"version": "23.4.0",
 	"description": "UI components for WordPress.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -38,22 +38,23 @@
 		"@emotion/utils": "^1.0.0",
 		"@floating-ui/react-dom": "^1.0.0",
 		"@use-gesture/react": "^10.2.6",
-		"@wordpress/a11y": "^3.26.1",
-		"@wordpress/compose": "^6.3.1",
-		"@wordpress/date": "^4.26.1",
-		"@wordpress/deprecated": "^3.26.1",
-		"@wordpress/dom": "^3.26.1",
-		"@wordpress/element": "^5.3.1",
-		"@wordpress/escape-html": "^2.26.1",
-		"@wordpress/hooks": "^3.26.1",
-		"@wordpress/html-entities": "^3.26.1",
-		"@wordpress/i18n": "^4.26.1",
-		"@wordpress/icons": "^9.17.1",
-		"@wordpress/is-shallow-equal": "^4.26.1",
-		"@wordpress/keycodes": "^3.26.1",
-		"@wordpress/primitives": "^3.24.1",
-		"@wordpress/rich-text": "^6.3.1",
-		"@wordpress/warning": "^2.26.1",
+		"@wordpress/a11y": "^3.27.0",
+		"@wordpress/compose": "^6.4.0",
+		"@wordpress/date": "^4.27.0",
+		"@wordpress/deprecated": "^3.27.0",
+		"@wordpress/dom": "^3.27.0",
+		"@wordpress/element": "^5.4.0",
+		"@wordpress/escape-html": "^2.27.0",
+		"@wordpress/hooks": "^3.27.0",
+		"@wordpress/html-entities": "^3.27.0",
+		"@wordpress/i18n": "^4.27.0",
+		"@wordpress/icons": "^9.18.0",
+		"@wordpress/is-shallow-equal": "^4.27.0",
+		"@wordpress/keycodes": "^3.27.0",
+		"@wordpress/primitives": "^3.25.0",
+		"@wordpress/private-apis": "^0.9.0",
+		"@wordpress/rich-text": "^6.4.0",
+		"@wordpress/warning": "^2.27.0",
 		"change-case": "^4.1.2",
 		"classnames": "^2.3.1",
 		"colord": "^2.7.0",
@@ -66,6 +67,7 @@
 		"highlight-words-core": "^1.2.2",
 		"lodash": "^4.17.21",
 		"memize": "^1.1.0",
+		"path-to-regexp": "^6.2.1",
 		"re-resizable": "^6.4.0",
 		"react-colorful": "^5.3.1",
 		"reakit": "^1.3.8",
@@ -81,5 +83,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "e9ff92d836928aba65dde94d9d193bc401a934d7"
+	"gitHead": "c25ff895413bad4354c55c0c2d732552618b0d56"
 }

package/src/alignment-matrix-control/utils.tsx

@@ -33,7 +33,7 @@ export const ALIGNMENTS = GRID.flat();
 /**
  * Parses and transforms an incoming value to better match the alignment values
  *
- * @param  value An alignment value to parse.
+ * @param value An alignment value to parse.
  *
  * @return The parsed value.
  */
@@ -46,8 +46,8 @@ export function transformValue( value: AlignmentMatrixControlValue ) {
 /**
  * Creates an item ID based on a prefix ID and an alignment value.
  *
- * @param  prefixId An ID to prefix.
- * @param  value    An alignment value.
+ * @param prefixId An ID to prefix.
+ * @param value    An alignment value.
  *
  * @return The item id.
  */
@@ -63,7 +63,7 @@ export function getItemId(
 /**
  * Retrieves the alignment index from a value.
  *
- * @param  alignment Value to check.
+ * @param alignment Value to check.
  *
  * @return The index of a matching alignment.
  */

package/src/angle-picker-control/README.md

@@ -1,6 +1,6 @@
 # AnglePickerControl
 
-AnglePickerControl is a React component to render a UI that allows users to pick an angle.
+`AnglePickerControl` is a React component to render a UI that allows users to pick an angle.
 Users can choose an angle in a visual UI with the mouse by dragging an angle indicator inside a circle or by directly inserting the desired angle in a text field.
 
 ## Usage
@@ -9,9 +9,15 @@ Users can choose an angle in a visual UI with the mouse by dragging an angle ind
 import { useState } from '@wordpress/element';
 import { AnglePickerControl } from '@wordpress/components';
 
-const MyAnglePicker = () => {
-	const [ angle, setAngle ] = useState();
-	return <AnglePickerControl value={ angle } onChange={ setAngle } __nextHasNoMarginBottom />;
+function Example() {
+	const [ angle, setAngle ] = useState( 0 );
+	return (
+		<AnglePickerControl
+			value={ angle }
+			onChange={ setAngle }
+			__nextHasNoMarginBottom
+		/>
+	);
 };
 ```
 
@@ -19,31 +25,28 @@ const MyAnglePicker = () => {
 
 The component accepts the following props.
 
-### label
+### `label`: `string`
 
-Label to use for the angle picker. If not set the a translated label "Angle" is used.
+Label to use for the angle picker.
 
--   Type: `String`
 -   Required: No
+-   Default: `__( 'Angle' )`
 
-### value
+### `value`: `number | string`
 
 The current value of the input. The value represents an angle in degrees and should be a value between 0 and 360.
 
--   Type: `Number`
 -   Required: Yes
 
-### onChange
+### `onChange`: `( value: number ) => void`
 
 A function that receives the new value of the input.
 
--   Type: `function`
 -   Required: Yes
 
-### __nextHasNoMarginBottom
+### `__nextHasNoMarginBottom`: `boolean`
 
 Start opting into the new margin-free styles that will become the default in a future version, currently scheduled to be WordPress 6.4. (The prop can be safely removed once this happens.)
 
--   Type: `boolean`
 -   Required: No
--   Default: `false`
+-   Default: `false`

package/src/angle-picker-control/{angle-circle.js → angle-circle.tsx}

@@ -13,12 +13,29 @@ import {
 	CircleIndicator,
 } from './styles/angle-picker-control-styles';
 
-function AngleCircle( { value, onChange, ...props } ) {
-	const angleCircleRef = useRef();
-	const angleCircleCenter = useRef();
-	const previousCursorValue = useRef();
+import type { WordPressComponentProps } from '../ui/context';
+import type { AngleCircleProps } from './types';
+
+type UseDraggingArgumentType = Parameters< typeof useDragging >[ 0 ];
+type UseDraggingCallbackEvent =
+	| Parameters< UseDraggingArgumentType[ 'onDragStart' ] >[ 0 ]
+	| Parameters< UseDraggingArgumentType[ 'onDragMove' ] >[ 0 ]
+	| Parameters< UseDraggingArgumentType[ 'onDragEnd' ] >[ 0 ];
+
+function AngleCircle( {
+	value,
+	onChange,
+	...props
+}: WordPressComponentProps< AngleCircleProps, 'div' > ) {
+	const angleCircleRef = useRef< HTMLDivElement | null >( null );
+	const angleCircleCenter = useRef< { x: number; y: number } | undefined >();
+	const previousCursorValue = useRef< CSSStyleDeclaration[ 'cursor' ] >();
 
 	const setAngleCircleCenter = () => {
+		if ( angleCircleRef.current === null ) {
+			return;
+		}
+
 		const rect = angleCircleRef.current.getBoundingClientRect();
 		angleCircleCenter.current = {
 			x: rect.x + rect.width / 2,
@@ -26,14 +43,26 @@ function AngleCircle( { value, onChange, ...props } ) {
 		};
 	};
 
-	const changeAngleToPosition = ( event ) => {
-		const { x: centerX, y: centerY } = angleCircleCenter.current;
+	const changeAngleToPosition = ( event: UseDraggingCallbackEvent ) => {
+		if ( event === undefined ) {
+			return;
+		}
+
 		// Prevent (drag) mouse events from selecting and accidentally
 		// triggering actions from other elements.
 		event.preventDefault();
 		// Input control needs to lose focus and by preventDefault above, it doesn't.
-		event.target.focus();
-		onChange( getAngle( centerX, centerY, event.clientX, event.clientY ) );
+		( event.target as HTMLDivElement | null )?.focus();
+
+		if (
+			angleCircleCenter.current !== undefined &&
+			onChange !== undefined
+		) {
+			const { x: centerX, y: centerY } = angleCircleCenter.current;
+			onChange(
+				getAngle( centerX, centerY, event.clientX, event.clientY )
+			);
+		}
 	};
 
 	const { startDrag, isDragging } = useDragging( {
@@ -52,13 +81,12 @@ function AngleCircle( { value, onChange, ...props } ) {
 			}
 			document.body.style.cursor = 'grabbing';
 		} else {
-			document.body.style.cursor = previousCursorValue.current || null;
+			document.body.style.cursor = previousCursorValue.current || '';
 			previousCursorValue.current = undefined;
 		}
 	}, [ isDragging ] );
 
 	return (
-		/* eslint-disable jsx-a11y/no-static-element-interactions */
 		<CircleRoot
 			ref={ angleCircleRef }
 			onMouseDown={ startDrag }
@@ -76,11 +104,15 @@ function AngleCircle( { value, onChange, ...props } ) {
 				<CircleIndicator className="components-angle-picker-control__angle-circle-indicator" />
 			</CircleIndicatorWrapper>
 		</CircleRoot>
-		/* eslint-enable jsx-a11y/no-static-element-interactions */
 	);
 }
 
-function getAngle( centerX, centerY, pointX, pointY ) {
+function getAngle(
+	centerX: number,
+	centerY: number,
+	pointX: number,
+	pointY: number
+) {
 	const y = pointY - centerY;
 	const x = pointX - centerX;
 

package/src/angle-picker-control/{index.js → index.tsx}

@@ -1,12 +1,14 @@
 /**
  * External dependencies
  */
+import type { ForwardedRef } from 'react';
 import classnames from 'classnames';
 
 /**
  * WordPress dependencies
  */
 import deprecated from '@wordpress/deprecated';
+import { forwardRef } from '@wordpress/element';
 import { __ } from '@wordpress/i18n';
 
 /**
@@ -21,14 +23,22 @@ import { Text } from '../text';
 import { Spacer } from '../spacer';
 import { COLORS } from '../utils/colors-values';
 
-export default function AnglePickerControl( {
-	/** Start opting into the new margin-free styles that will become the default in a future version. */
-	__nextHasNoMarginBottom = false,
-	className,
-	label = __( 'Angle' ),
-	onChange,
-	value,
-} ) {
+import type { WordPressComponentProps } from '../ui/context';
+import type { AnglePickerControlProps } from './types';
+
+function UnforwardedAnglePickerControl(
+	props: WordPressComponentProps< AnglePickerControlProps, 'div' >,
+	ref: ForwardedRef< any >
+) {
+	const {
+		__nextHasNoMarginBottom = false,
+		className,
+		label = __( 'Angle' ),
+		onChange,
+		value,
+		...restProps
+	} = props;
+
 	if ( ! __nextHasNoMarginBottom ) {
 		deprecated(
 			'Bottom margin styles for wp.components.AnglePickerControl',
@@ -40,9 +50,15 @@ export default function AnglePickerControl( {
 		);
 	}
 
-	const handleOnNumberChange = ( unprocessedValue ) => {
+	const handleOnNumberChange = ( unprocessedValue: string | undefined ) => {
+		if ( onChange === undefined ) {
+			return;
+		}
+
 		const inputValue =
-			unprocessedValue !== '' ? parseInt( unprocessedValue, 10 ) : 0;
+			unprocessedValue !== undefined && unprocessedValue !== ''
+				? parseInt( unprocessedValue, 10 )
+				: 0;
 		onChange( inputValue );
 	};
 
@@ -50,6 +66,8 @@ export default function AnglePickerControl( {
 
 	return (
 		<Root
+			{ ...restProps }
+			ref={ ref }
 			__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
 			className={ classes }
 			gap={ 4 }
@@ -94,3 +112,29 @@ export default function AnglePickerControl( {
 		</Root>
 	);
 }
+
+/**
+ * `AnglePickerControl` is a React component to render a UI that allows users to
+ * pick an angle. Users can choose an angle in a visual UI with the mouse by
+ * dragging an angle indicator inside a circle or by directly inserting the
+ * desired angle in a text field.
+ *
+ * ```jsx
+ * import { useState } from '@wordpress/element';
+ * import { AnglePickerControl } from '@wordpress/components';
+ *
+ * function Example() {
+ *   const [ angle, setAngle ] = useState( 0 );
+ *   return (
+ *     <AnglePickerControl
+ *       value={ angle }
+ *       onChange={ setAngle }
+ *       __nextHasNoMarginBottom
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export const AnglePickerControl = forwardRef( UnforwardedAnglePickerControl );
+
+export default AnglePickerControl;

package/src/angle-picker-control/stories/index.tsx

@@ -0,0 +1,57 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { AnglePickerControl } from '..';
+
+const meta: ComponentMeta< typeof AnglePickerControl > = {
+	title: 'Components/AnglePickerControl',
+	component: AnglePickerControl,
+	argTypes: {
+		as: { control: { type: null } },
+		value: { control: { type: null } },
+	},
+	parameters: {
+		actions: { argTypesRegex: '^on.*' },
+		controls: {
+			expanded: true,
+		},
+		docs: { source: { state: 'open' } },
+	},
+};
+
+export default meta;
+
+const AnglePickerWithState: ComponentStory< typeof AnglePickerControl > = ( {
+	onChange,
+	...args
+} ) => {
+	const [ angle, setAngle ] = useState< number >( 0 );
+
+	const handleChange = ( newValue: number ) => {
+		setAngle( newValue );
+		onChange( newValue );
+	};
+
+	return (
+		<AnglePickerControl
+			{ ...args }
+			value={ angle }
+			onChange={ handleChange }
+		/>
+	);
+};
+
+export const Default = AnglePickerWithState.bind( {} );
+Default.args = {
+	__nextHasNoMarginBottom: true,
+};

package/src/angle-picker-control/styles/{angle-picker-control-styles.js → angle-picker-control-styles.tsx}

@@ -12,10 +12,14 @@ import { COLORS } from '../../utils';
 import { space } from '../../ui/utils/space';
 import CONFIG from '../../utils/config-values';
 
+import type { AnglePickerControlProps } from '../types';
+
 const CIRCLE_SIZE = 32;
 const INNER_CIRCLE_SIZE = 3;
 
-const deprecatedBottomMargin = ( { __nextHasNoMarginBottom } ) => {
+const deprecatedBottomMargin = ( {
+	__nextHasNoMarginBottom,
+}: Pick< AnglePickerControlProps, '__nextHasNoMarginBottom' > ) => {
 	return ! __nextHasNoMarginBottom
 		? css`
 				margin-bottom: ${ space( 2 ) };

package/src/angle-picker-control/types.ts

@@ -0,0 +1,29 @@
+export type AnglePickerControlProps = {
+	/**
+	 * Start opting into the new margin-free styles that will become the default
+	 * in a future version.
+	 *
+	 * @default false
+	 */
+	__nextHasNoMarginBottom?: boolean;
+	/**
+	 * Label to use for the angle picker.
+	 *
+	 * @default __( 'Angle' )
+	 */
+	label?: string;
+	/**
+	 * A function that receives the new value of the input.
+	 */
+	onChange: ( value: number ) => void;
+	/**
+	 * The current value of the input. The value represents an angle in degrees
+	 * and should be a value between 0 and 360.
+	 */
+	value: number | string;
+};
+
+export type AngleCircleProps = Pick<
+	AnglePickerControlProps,
+	'value' | 'onChange'
+>;

package/src/autocomplete/autocompleter-ui.native.js

@@ -144,6 +144,7 @@ export function getAutoCompleterUI( autocompleter ) {
 					<Animated.View style={ contentStyles }>
 						<BackgroundView>
 							<ScrollView
+								testID="autocompleter"
 								ref={ scrollViewRef }
 								horizontal
 								contentContainerStyle={

package/src/base-control/hooks.ts

@@ -14,7 +14,7 @@ import type { BaseControlProps } from './types';
  *
  * Namely, it takes care of generating a unique `id`, properly associating it with the `label` and `help` elements.
  *
- * @param  props
+ * @param props
  */
 export function useBaseControlProps(
 	props: Omit< BaseControlProps, 'children' >