@wordpress/components 23.5.0 → 23.7.0

package/build-types/visually-hidden/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/visually-hidden/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,oBAAY,mBAAmB,GAAG;IACjC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACpB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/visually-hidden/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,MAAM,MAAM,mBAAmB,GAAG;IACjC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACpB,CAAC"}

package/build-types/z-stack/types.d.ts

@@ -2,7 +2,7 @@
  * External dependencies
  */
 import type { ReactNode } from 'react';
-export declare type ZStackProps = {
+export type ZStackProps = {
     /**
      * Layers children elements on top of each other (first: highest z-index,
      * last: lowest z-index).

package/build-types/z-stack/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/z-stack/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,oBAAY,WAAW,GAAG;IACzB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACpB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/z-stack/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,MAAM,MAAM,WAAW,GAAG;IACzB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;CACpB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/components",
-	"version": "23.5.0",
+	"version": "23.7.0",
 	"description": "UI components for WordPress.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -37,24 +37,24 @@
 		"@emotion/styled": "^11.6.0",
 		"@emotion/utils": "^1.0.0",
 		"@floating-ui/react-dom": "1.0.0",
-		"@use-gesture/react": "^10.2.6",
-		"@wordpress/a11y": "^3.28.0",
-		"@wordpress/compose": "^6.5.0",
-		"@wordpress/date": "^4.28.0",
-		"@wordpress/deprecated": "^3.28.0",
-		"@wordpress/dom": "^3.28.0",
-		"@wordpress/element": "^5.5.0",
-		"@wordpress/escape-html": "^2.28.0",
-		"@wordpress/hooks": "^3.28.0",
-		"@wordpress/html-entities": "^3.28.0",
-		"@wordpress/i18n": "^4.28.0",
-		"@wordpress/icons": "^9.19.0",
-		"@wordpress/is-shallow-equal": "^4.28.0",
-		"@wordpress/keycodes": "^3.28.0",
-		"@wordpress/primitives": "^3.26.0",
-		"@wordpress/private-apis": "^0.10.0",
-		"@wordpress/rich-text": "^6.5.0",
-		"@wordpress/warning": "^2.28.0",
+		"@use-gesture/react": "^10.2.24",
+		"@wordpress/a11y": "^3.30.0",
+		"@wordpress/compose": "^6.7.0",
+		"@wordpress/date": "^4.30.0",
+		"@wordpress/deprecated": "^3.30.0",
+		"@wordpress/dom": "^3.30.0",
+		"@wordpress/element": "^5.7.0",
+		"@wordpress/escape-html": "^2.30.0",
+		"@wordpress/hooks": "^3.30.0",
+		"@wordpress/html-entities": "^3.30.0",
+		"@wordpress/i18n": "^4.30.0",
+		"@wordpress/icons": "^9.21.0",
+		"@wordpress/is-shallow-equal": "^4.30.0",
+		"@wordpress/keycodes": "^3.30.0",
+		"@wordpress/primitives": "^3.28.0",
+		"@wordpress/private-apis": "^0.12.0",
+		"@wordpress/rich-text": "^6.7.0",
+		"@wordpress/warning": "^2.30.0",
 		"change-case": "^4.1.2",
 		"classnames": "^2.3.1",
 		"colord": "^2.7.0",
@@ -85,5 +85,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "d5e03a74b79e3ca84afda24375474a103a063ee4"
+	"gitHead": "d5c28a67b11e91e3e4b8e90346bfcb90909364d6"
 }

package/src/angle-picker-control/angle-circle.tsx

@@ -91,7 +91,6 @@ function AngleCircle( {
 			ref={ angleCircleRef }
 			onMouseDown={ startDrag }
 			className="components-angle-picker-control__angle-circle"
-			style={ isDragging ? { cursor: 'grabbing' } : undefined }
 			{ ...props }
 		>
 			<CircleIndicatorWrapper

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

@@ -9,19 +9,16 @@ import classnames from 'classnames';
  */
 import deprecated from '@wordpress/deprecated';
 import { forwardRef } from '@wordpress/element';
-import { __ } from '@wordpress/i18n';
+import { isRTL, __ } from '@wordpress/i18n';
 
 /**
  * Internal dependencies
  */
-import { FlexBlock, FlexItem } from '../flex';
+import { FlexBlock } from '../flex';
+import { Spacer } from '../spacer';
 import NumberControl from '../number-control';
 import AngleCircle from './angle-circle';
-import { Root } from './styles/angle-picker-control-styles';
-import { space } from '../ui/utils/space';
-import { Text } from '../text';
-import { Spacer } from '../spacer';
-import { COLORS } from '../utils/colors-values';
+import { Root, UnitText } from './styles/angle-picker-control-styles';
 
 import type { WordPressComponentProps } from '../ui/context';
 import type { AnglePickerControlProps } from './types';
@@ -64,13 +61,18 @@ function UnforwardedAnglePickerControl(
 
 	const classes = classnames( 'components-angle-picker-control', className );
 
+	const unitText = <UnitText>°</UnitText>;
+	const [ prefixedUnitText, suffixedUnitText ] = isRTL()
+		? [ unitText, null ]
+		: [ null, unitText ];
+
 	return (
 		<Root
 			{ ...restProps }
 			ref={ ref }
 			__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
 			className={ classes }
-			gap={ 4 }
+			gap={ 2 }
 		>
 			<FlexBlock>
 				<NumberControl
@@ -83,32 +85,17 @@ function UnforwardedAnglePickerControl(
 					step="1"
 					value={ value }
 					spinControls="none"
-					suffix={
-						<Spacer
-							as={ Text }
-							marginBottom={ 0 }
-							marginRight={ space( 3 ) }
-							style={ {
-								color: COLORS.ui.theme,
-							} }
-						>
-							°
-						</Spacer>
-					}
+					prefix={ prefixedUnitText }
+					suffix={ suffixedUnitText }
 				/>
 			</FlexBlock>
-			<FlexItem
-				style={ {
-					marginBottom: space( 1 ),
-					marginTop: 'auto',
-				} }
-			>
+			<Spacer marginBottom="1" marginTop="auto">
 				<AngleCircle
 					aria-hidden="true"
 					value={ value }
 					onChange={ onChange }
 				/>
-			</FlexItem>
+			</Spacer>
 		</Root>
 	);
 }

package/src/angle-picker-control/styles/angle-picker-control-styles.tsx

@@ -10,12 +10,13 @@ import styled from '@emotion/styled';
 import { Flex } from '../../flex';
 import { COLORS } from '../../utils';
 import { space } from '../../ui/utils/space';
+import { Text } from '../../text';
 import CONFIG from '../../utils/config-values';
 
 import type { AnglePickerControlProps } from '../types';
 
 const CIRCLE_SIZE = 32;
-const INNER_CIRCLE_SIZE = 3;
+const INNER_CIRCLE_SIZE = 6;
 
 const deprecatedBottomMargin = ( {
 	__nextHasNoMarginBottom,
@@ -39,6 +40,10 @@ export const CircleRoot = styled.div`
 	height: ${ CIRCLE_SIZE }px;
 	overflow: hidden;
 	width: ${ CIRCLE_SIZE }px;
+
+	:active {
+		cursor: grabbing;
+	}
 `;
 
 export const CircleIndicatorWrapper = styled.div`
@@ -55,15 +60,17 @@ export const CircleIndicatorWrapper = styled.div`
 export const CircleIndicator = styled.div`
 	background: ${ COLORS.ui.theme };
 	border-radius: 50%;
-	border: ${ INNER_CIRCLE_SIZE }px solid ${ COLORS.ui.theme };
-	bottom: 0;
 	box-sizing: border-box;
 	display: block;
-	height: 0px;
-	left: 0;
-	margin: auto;
+	left: 50%;
+	top: 4px;
+	transform: translateX( -50% );
 	position: absolute;
-	right: 0;
-	top: -${ CIRCLE_SIZE / 2 }px;
-	width: 0px;
+	width: ${ INNER_CIRCLE_SIZE }px;
+	height: ${ INNER_CIRCLE_SIZE }px;
+`;
+
+export const UnitText = styled( Text )`
+	color: ${ COLORS.ui.theme };
+	margin-right: ${ space( 3 ) };
 `;

package/src/animate/index.tsx

@@ -0,0 +1,75 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+
+/**
+ * Internal dependencies
+ */
+import type { AnimateProps, GetAnimateOptions } from './types';
+
+/**
+ * @param type The animation type
+ * @return Default origin
+ */
+function getDefaultOrigin( type?: GetAnimateOptions[ 'type' ] ) {
+	return type === 'appear' ? 'top' : 'left';
+}
+
+/**
+ * @param options
+ *
+ * @return ClassName that applies the animations
+ */
+export function getAnimateClassName( options: GetAnimateOptions ) {
+	if ( options.type === 'loading' ) {
+		return classnames( 'components-animate__loading' );
+	}
+
+	const { type, origin = getDefaultOrigin( type ) } = options;
+
+	if ( type === 'appear' ) {
+		const [ yAxis, xAxis = 'center' ] = origin.split( ' ' );
+		return classnames( 'components-animate__appear', {
+			[ 'is-from-' + xAxis ]: xAxis !== 'center',
+			[ 'is-from-' + yAxis ]: yAxis !== 'middle',
+		} );
+	}
+
+	if ( type === 'slide-in' ) {
+		return classnames(
+			'components-animate__slide-in',
+			'is-from-' + origin
+		);
+	}
+
+	return undefined;
+}
+
+/**
+ * Simple interface to introduce animations to components.
+ *
+ * ```jsx
+ * import { Animate, Notice } from '@wordpress/components';
+ *
+ * const MyAnimatedNotice = () => (
+ * 	<Animate type="slide-in" options={ { origin: 'top' } }>
+ * 		{ ( { className } ) => (
+ * 			<Notice className={ className } status="success">
+ * 				<p>Animation finished.</p>
+ * 			</Notice>
+ * 		) }
+ * 	</Animate>
+ * );
+ * ```
+ */
+export function Animate( { type, options = {}, children }: AnimateProps ) {
+	return children( {
+		className: getAnimateClassName( {
+			type,
+			...options,
+		} as GetAnimateOptions ),
+	} );
+}
+
+export default Animate;

package/src/animate/stories/index.tsx

@@ -0,0 +1,102 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { Animate } from '..';
+import Notice from '../../notice';
+
+const meta: ComponentMeta< typeof Animate > = {
+	title: 'Components/Animate',
+	component: Animate,
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof Animate > = ( props ) => (
+	<Animate { ...props } />
+);
+
+export const Default: ComponentStory< typeof Animate > = Template.bind( {} );
+Default.args = {
+	children: ( { className } ) => (
+		<Notice className={ className } status="success">
+			<p>{ `No default animation. Use one of type = "appear", "slide-in", or "loading".` }</p>
+		</Notice>
+	),
+};
+
+export const AppearTopLeft: ComponentStory< typeof Animate > = Template.bind(
+	{}
+);
+AppearTopLeft.args = {
+	type: 'appear',
+	options: { origin: 'top left' },
+	children: ( { className } ) => (
+		<Notice className={ className } status="success">
+			<p>Appear animation. Origin: top left.</p>
+		</Notice>
+	),
+};
+export const AppearTopRight: ComponentStory< typeof Animate > = Template.bind(
+	{}
+);
+AppearTopRight.args = {
+	type: 'appear',
+	options: { origin: 'top right' },
+	children: ( { className } ) => (
+		<Notice className={ className } status="success">
+			<p>Appear animation. Origin: top right.</p>
+		</Notice>
+	),
+};
+export const AppearBottomLeft: ComponentStory< typeof Animate > = Template.bind(
+	{}
+);
+AppearBottomLeft.args = {
+	type: 'appear',
+	options: { origin: 'bottom left' },
+	children: ( { className } ) => (
+		<Notice className={ className } status="success">
+			<p>Appear animation. Origin: bottom left.</p>
+		</Notice>
+	),
+};
+export const AppearBottomRight: ComponentStory< typeof Animate > =
+	Template.bind( {} );
+AppearBottomRight.args = {
+	type: 'appear',
+	options: { origin: 'bottom right' },
+	children: ( { className } ) => (
+		<Notice className={ className } status="success">
+			<p>Appear animation. Origin: bottom right.</p>
+		</Notice>
+	),
+};
+
+export const Loading: ComponentStory< typeof Animate > = Template.bind( {} );
+Loading.args = {
+	type: 'loading',
+	children: ( { className } ) => (
+		<Notice className={ className } status="success">
+			<p>Loading animation.</p>
+		</Notice>
+	),
+};
+
+export const SlideIn: ComponentStory< typeof Animate > = Template.bind( {} );
+SlideIn.args = {
+	type: 'slide-in',
+	options: { origin: 'left' },
+	children: ( { className } ) => (
+		<Notice className={ className } status="success">
+			<p>Slide-in animation.</p>
+		</Notice>
+	),
+};

package/src/animate/types.ts

@@ -0,0 +1,32 @@
+export type AppearOptions = {
+	type: 'appear';
+	origin?:
+		| 'top'
+		| 'top left'
+		| 'top right'
+		| 'middle'
+		| 'middle left'
+		| 'middle right'
+		| 'bottom'
+		| 'bottom left'
+		| 'bottom right';
+};
+type SlideInOptions = { type: 'slide-in'; origin?: 'left' | 'right' };
+type LoadingOptions = { type: 'loading'; origin?: never };
+type NoAnimationOptions = { type?: never; origin?: never };
+
+export type GetAnimateOptions =
+	| AppearOptions
+	| SlideInOptions
+	| LoadingOptions
+	| NoAnimationOptions;
+
+// Create a new type that and distributes the `Pick` operator separately to
+// every individual type of a union, thus preserving that same union.
+type DistributiveTypeAndOptions< T extends { type?: any } > = T extends any
+	? Pick< T, 'type' > & { options?: Omit< T, 'type' > }
+	: never;
+
+export type AnimateProps = DistributiveTypeAndOptions< GetAnimateOptions > & {
+	children: ( props: { className?: string } ) => JSX.Element;
+};

package/src/autocomplete/README.md

@@ -2,6 +2,57 @@
 
 This component is used to provide autocompletion support for a child input component.
 
+## Props
+
+The following props are used to control the behavior of the component.
+
+### record
+
+The rich text value object the autocomleter is being applied to.
+
+-   Required: Yes
+-   Type: `RichTextValue`
+
+### onChange
+
+A function to be called when an option is selected to insert into the existing text.
+
+-   Required: Yes
+-   Type: `( value: string ) => void`
+
+A function to be called when an option is selected to replace the existing text.
+
+-   Required: Yes
+-   Type: `( arg: [ OptionCompletion[ 'value' ] ] ) => void;`
+
+### completers
+
+An array of all of the completers to apply to the current element.
+
+-   Required: Yes
+-   Type: `Array< WPCompleter >`
+ 
+### contentRef
+
+A ref containing the editable element that will serve as the anchor for `Autocomplete`'s `Popover`.
+
+-   Required: Yes
+-   `MutableRefObject< HTMLElement | undefined >`
+
+### children
+
+A function that returns nodes to be rendered within the Autocomplete.
+
+-   Required: Yes
+-   Type: `Function`
+
+### isSelected
+
+Whether or not the Autocomplte componenet is selected, and if its `Popover` should be displayed.
+
+- Required: Yes
+- Type: `Boolean`
+
 ## Autocompleters
 
 Autocompleters enable us to offer users options for completing text input. For example, Gutenberg includes a user autocompleter that provides a list of user names and completes a selection with a user mention like `@mary`.

package/src/autocomplete/{autocompleter-ui.js → autocompleter-ui.tsx}

@@ -12,6 +12,8 @@ import {
 	useEffect,
 	useState,
 } from '@wordpress/element';
+// Error expected because `@wordpress/rich-text` is not yet fully typed.
+// @ts-expect-error
 import { useAnchor } from '@wordpress/rich-text';
 import { useMergeRefs, useRefEffect } from '@wordpress/compose';
 
@@ -23,8 +25,9 @@ import Button from '../button';
 import Popover from '../popover';
 import { VisuallyHidden } from '../visually-hidden';
 import { createPortal } from 'react-dom';
+import type { AutocompleterUIProps, WPCompleter } from './types';
 
-export function getAutoCompleterUI( autocompleter ) {
+export function getAutoCompleterUI( autocompleter: WPCompleter ) {
 	const useItems = autocompleter.useItems
 		? autocompleter.useItems
 		: getDefaultUseItems( autocompleter );
@@ -39,17 +42,15 @@ export function getAutoCompleterUI( autocompleter ) {
 		onSelect,
 		onReset,
 		reset,
-		value,
 		contentRef,
-	} ) {
+	}: AutocompleterUIProps ) {
 		const [ items ] = useItems( filterValue );
 		const popoverAnchor = useAnchor( {
 			editableContentElement: contentRef.current,
-			value,
 		} );
 
 		const [ needsA11yCompat, setNeedsA11yCompat ] = useState( false );
-		const popoverRef = useRef();
+		const popoverRef = useRef< HTMLElement >( null );
 		const popoverRefs = useMergeRefs( [
 			popoverRef,
 			useRefEffect(
@@ -77,11 +78,15 @@ export function getAutoCompleterUI( autocompleter ) {
 			// eslint-disable-next-line react-hooks/exhaustive-deps
 		}, [ items ] );
 
-		if ( ! items.length > 0 ) {
+		if ( items.length === 0 ) {
 			return null;
 		}
 
-		const ListBox = ( { Component = 'div' } ) => (
+		const ListBox = ( {
+			Component = 'div',
+		}: {
+			Component?: React.ElementType;
+		} ) => (
 			<Component
 				id={ listBoxId }
 				role="listbox"
@@ -134,11 +139,17 @@ export function getAutoCompleterUI( autocompleter ) {
 	return AutocompleterUI;
 }
 
-function useOnClickOutside( ref, handler ) {
+function useOnClickOutside(
+	ref: React.RefObject< HTMLElement >,
+	handler: AutocompleterUIProps[ 'reset' ]
+) {
 	useEffect( () => {
-		const listener = ( event ) => {
+		const listener = ( event: MouseEvent | TouchEvent ) => {
 			// Do nothing if clicking ref's element or descendent elements, or if the ref is not referencing an element
-			if ( ! ref.current || ref.current.contains( event.target ) ) {
+			if (
+				! ref.current ||
+				ref.current.contains( event.target as Node )
+			) {
 				return;
 			}
 			handler( event );

package/src/autocomplete/{get-default-use-items.js → get-default-use-items.tsx}

@@ -13,8 +13,13 @@ import { useLayoutEffect, useState } from '@wordpress/element';
  * Internal dependencies
  */
 import { escapeRegExp } from '../utils/strings';
+import type { CancelablePromise, KeyedOption, WPCompleter } from './types';
 
-function filterOptions( search, options = [], maxResults = 10 ) {
+function filterOptions(
+	search: RegExp,
+	options: Array< KeyedOption > = [],
+	maxResults = 10
+) {
 	const filtered = [];
 	for ( let i = 0; i < options.length; i++ ) {
 		const option = options[ i ];
@@ -43,9 +48,9 @@ function filterOptions( search, options = [], maxResults = 10 ) {
 	return filtered;
 }
 
-export default function getDefaultUseItems( autocompleter ) {
-	return ( filterValue ) => {
-		const [ items, setItems ] = useState( [] );
+export default function getDefaultUseItems( autocompleter: WPCompleter ) {
+	return ( filterValue: string ) => {
+		const [ items, setItems ] = useState< Array< KeyedOption > >( [] );
 		/*
 		 * We support both synchronous and asynchronous retrieval of completer options
 		 * but internally treat all as async so we maintain a single, consistent code path.
@@ -61,7 +66,7 @@ export default function getDefaultUseItems( autocompleter ) {
 			const { options, isDebounced } = autocompleter;
 			const loadOptions = debounce(
 				() => {
-					const promise = Promise.resolve(
+					const promise: CancelablePromise = Promise.resolve(
 						typeof options === 'function'
 							? options( filterValue )
 							: options
@@ -112,6 +117,6 @@ export default function getDefaultUseItems( autocompleter ) {
 			};
 		}, [ filterValue ] );
 
-		return [ items ];
+		return [ items ] as const;
 	};
 }