@wordpress/components 23.5.0 → 23.6.0

package/src/autocomplete/types.ts

@@ -0,0 +1,220 @@
+/**
+ * WordPress dependencies
+ */
+import type { WPElement } from '@wordpress/element';
+/**
+ * Internal dependencies
+ */
+import type { useAutocomplete } from '.';
+
+// Insert the `value` into the text.
+export type InsertOption = {
+	action: 'insert-at-caret';
+	value: React.ReactNode;
+};
+
+// Replace the current block with the block specified in the `value` property
+export type ReplaceOption = { action: 'replace'; value: RichTextValue };
+
+export type OptionCompletion = React.ReactNode | InsertOption | ReplaceOption;
+
+type OptionLabel = string | WPElement | Array< string | WPElement >;
+export type KeyedOption = {
+	key: string;
+	value: any;
+	label: OptionLabel;
+	keywords: Array< string >;
+	isDisabled: boolean;
+};
+
+export type WPCompleter< TCompleterOption = any > = {
+	/**
+	 * The name of the completer. Useful for identifying a specific completer to
+	 * be overridden via extensibility hooks.
+	 */
+	name: string;
+	/**
+	 * The string prefix that should trigger the completer. For example,
+	 * Gutenberg's block completer is triggered when the '/' character is
+	 * entered.
+	 */
+	triggerPrefix: string;
+	/**
+	 * The raw options for completion. May be an array, a function that returns
+	 * an array, or a function that returns a promise for an array.
+	 * Options may be of any type or shape. The completer declares how those
+	 * options are rendered and what their completions should be when selected.
+	 */
+	options:
+		| ( (
+				query: string
+		  ) =>
+				| PromiseLike< readonly TCompleterOption[] >
+				| readonly TCompleterOption[] )
+		| readonly TCompleterOption[];
+	/**
+	 * A function that returns the keywords for the specified option.
+	 */
+	getOptionKeywords?: ( option: TCompleterOption ) => Array< string >;
+	/**
+	 * A function that returns whether or not the specified option is disabled.
+	 * Disabled options cannot be selected.
+	 */
+	isOptionDisabled?: ( option: TCompleterOption ) => boolean;
+	/**
+	 * A function that returns the label for a given option. A label may be a
+	 * string or a mixed array of strings, elements, and components.
+	 */
+	getOptionLabel: ( option: TCompleterOption ) => OptionLabel;
+	/**
+	 * A function that takes a Range before and a Range after the autocomplete
+	 * trigger and query text and returns a boolean indicating whether the
+	 * completer should be considered for that context.
+	 */
+	allowContext?: ( before: string, after: string ) => boolean;
+	/**
+	 * A function that takes an option and returns how the option should
+	 * be completed. By default, the result is a value to be inserted in the
+	 * text.
+	 * However, a completer may explicitly declare how a completion should be
+	 * treated by returning an object with `action` and `value` properties. The
+	 * `action` declares what should be done with the `value`.
+	 */
+	getOptionCompletion?: (
+		option: TCompleterOption,
+		query: string
+	) => OptionCompletion;
+	/**
+	 * A function that returns an array of items to be displayed in the
+	 * Autocomplete UI. These items have uniform shape and have been filtered by
+	 * `AutocompleterUIProps.filterValue`.
+	 */
+	useItems?: ( filterValue: string ) => readonly [ Array< KeyedOption > ];
+	/**
+	 * Whether or not changes to the `filterValue` should be debounced.
+	 */
+	isDebounced?: boolean;
+	/**
+	 * A CSS class name to be applied to the completion menu.
+	 */
+	className?: string;
+};
+
+type ContentRef = React.RefObject< HTMLElement >;
+
+export type AutocompleterUIProps = {
+	/**
+	 * The value to filter the options by.
+	 */
+	filterValue: string;
+	/**
+	 * An id unique to each instance of the component, used in the IDs of the
+	 * buttons generated for individual options.
+	 */
+	instanceId: number;
+	/**
+	 * The id of to be applied to the listbox of options.
+	 */
+	listBoxId: string | undefined;
+	/**
+	 * The class to apply to the wrapper element.
+	 */
+	className?: string;
+	/**
+	 * The index of the currently selected option.
+	 */
+	selectedIndex: number;
+	/**
+	 * A function to be called when the filterValue changes.
+	 */
+	onChangeOptions: ( items: Array< KeyedOption > ) => void;
+	/**
+	 * A function to be called when an option is selected.
+	 */
+	onSelect: ( option: KeyedOption ) => void;
+	/**
+	 * A function to be called when the completer is reset
+	 * (e.g. when the user hits the escape key).
+	 */
+	onReset?: () => void;
+	/**
+	 * A function that defines the behavior of the completer when it is reset
+	 */
+	reset: ( event: Event ) => void;
+	// This is optional because it's still needed for mobile/native.
+	/**
+	 * The rich text value object the autocompleter is being applied to.
+	 */
+	value?: RichTextValue;
+	/**
+	 * A ref containing the editable element that will serve as the anchor for
+	 * `Autocomplete`'s `Popover`.
+	 */
+	contentRef: ContentRef;
+};
+
+export type CancelablePromise< T = void > = Promise< T > & {
+	canceled?: boolean;
+};
+
+/**
+ * When `@wordpress/rich-text` is fully typed, the following
+ * types should be moved to and imported from there
+ *
+ * @see /packages/rich-text/src/create.js
+ */
+type RichTextFormat = {
+	type: string;
+};
+type RichTextFormatList = Array< RichTextFormat >;
+type RichTextValue = {
+	text: string;
+	formats?: Array< RichTextFormatList >;
+	replacements?: Array< RichTextFormat >;
+	start: number | undefined;
+	end: number | undefined;
+};
+
+export type UseAutocompleteProps = {
+	/**
+	 * The rich text value object the autocompleter is being applied to.
+	 */
+	record: RichTextValue & {
+		start: NonNullable< RichTextValue[ 'start' ] >;
+		end: NonNullable< RichTextValue[ 'end' ] >;
+	};
+	/**
+	 * A function to be called when an option is selected to insert into the
+	 * existing text.
+	 */
+	onChange: ( value: string ) => void;
+	/**
+	 * A function to be called when an option is selected to replace the
+	 * existing text.
+	 */
+	onReplace: ( values: RichTextValue[] ) => void;
+	/**
+	 * An array of all of the completers to apply to the current element.
+	 */
+	completers: Array< WPCompleter >;
+	/**
+	 * A ref containing the editable element that will serve as the anchor for
+	 * `Autocomplete`'s `Popover`.
+	 */
+	contentRef: ContentRef;
+};
+
+export type AutocompleteProps = UseAutocompleteProps & {
+	/**
+	 * A function that returns nodes to be rendered within the Autocomplete.
+	 */
+	children: (
+		props: Omit< ReturnType< typeof useAutocomplete >, 'popover' >
+	) => React.ReactNode;
+	/**
+	 * Whether or not the Autocomplte componenet is selected, and if its
+	 * `Popover`
+	 * should be displayed.
+	 */
+	isSelected: boolean;
+};

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

@@ -14,8 +14,6 @@ import {
  */
 import { BorderControl } from '../';
 
-jest.useRealTimers();
-
 const colors = [
 	{ name: 'Gray', color: '#f6f7f7' },
 	{ name: 'Blue', color: '#72aee6' },

package/src/button/style.scss

@@ -121,7 +121,6 @@
 
 		&:hover:not(:disabled) {
 			color: $components-color-accent-darker-10;
-			box-shadow: inset 0 0 0 $border-width $components-color-accent-darker-10;
 		}
 
 		&:disabled,
@@ -147,6 +146,10 @@
 		white-space: nowrap;
 		color: $components-color-accent;
 		background: transparent;
+
+		&:hover:not(:disabled) {
+			box-shadow: inset 0 0 0 $border-width $components-color-accent-darker-10;
+		}
 	}
 
 	/**
@@ -159,6 +162,14 @@
 		background: transparent;
 		padding: $grid-unit-15 * 0.5; // This reduces the horizontal padding on tertiary/text buttons, so as to space them optically.
 
+		&:hover:not(:disabled) {
+			background: rgba(var(--wp-admin-theme-color--rgb), 0.04);
+		}
+
+		&:active:not(:disabled) {
+			background: rgba(var(--wp-admin-theme-color--rgb), 0.08);
+		}
+
 		.dashicon {
 			display: inline-block;
 			flex: 0 0 auto;

package/src/button/types.ts

@@ -33,7 +33,7 @@ type BaseButtonProps = {
 	/**
 	 * If provided, renders an Icon component inside the button.
 	 */
-	icon?: IconProps< unknown >[ 'icon' ];
+	icon?: IconProps[ 'icon' ];
 	/**
 	 * If provided with `icon`, sets the position of icon relative to the `text`.
 	 *
@@ -45,7 +45,7 @@ type BaseButtonProps = {
 	 * Please refer to the Icon component for more details regarding
 	 * the default value of its `size` prop.
 	 */
-	iconSize?: IconProps< unknown >[ 'size' ];
+	iconSize?: IconProps[ 'size' ];
 	/**
 	 * Indicates activity while a action is being performed.
 	 */

package/src/circular-option-picker/types.ts

@@ -57,7 +57,7 @@ export type OptionProps = Omit<
 > & {
 	className?: string;
 	tooltipText?: string;
-	isSelected: boolean;
+	isSelected?: boolean;
 	// `icon` is explicitly defined as 'check' by CircleOptionPicker.Option
 	// and is not intended to be overridden.
 	// `size` relies on the `Icon` component's default size of `24` to fit

package/src/color-palette/test/__snapshots__/index.tsx.snap

@@ -6,17 +6,18 @@ exports[`ColorPalette should allow disabling custom color picker 1`] = `
   display: -webkit-flex;
   display: -ms-flexbox;
   display: flex;
-  -webkit-align-items: normal;
-  -webkit-box-align: normal;
-  -ms-flex-align: normal;
-  align-items: normal;
+  -webkit-align-items: stretch;
+  -webkit-box-align: stretch;
+  -ms-flex-align: stretch;
+  align-items: stretch;
   -webkit-flex-direction: column;
   -ms-flex-direction: column;
   flex-direction: column;
   gap: calc(4px * 3);
-  -webkit-box-pack: justify;
-  -webkit-justify-content: space-between;
-  justify-content: space-between;
+  -webkit-box-pack: center;
+  -ms-flex-pack: center;
+  -webkit-justify-content: center;
+  justify-content: center;
 }
 
 .emotion-0>* {
@@ -103,17 +104,18 @@ exports[`ColorPalette should render a dynamic toolbar of colors 1`] = `
   display: -webkit-flex;
   display: -ms-flexbox;
   display: flex;
-  -webkit-align-items: normal;
-  -webkit-box-align: normal;
-  -ms-flex-align: normal;
-  align-items: normal;
+  -webkit-align-items: stretch;
+  -webkit-box-align: stretch;
+  -ms-flex-align: stretch;
+  align-items: stretch;
   -webkit-flex-direction: column;
   -ms-flex-direction: column;
   flex-direction: column;
   gap: calc(4px * 3);
-  -webkit-box-pack: justify;
-  -webkit-justify-content: space-between;
-  justify-content: space-between;
+  -webkit-box-pack: center;
+  -ms-flex-pack: center;
+  -webkit-justify-content: center;
+  justify-content: center;
 }
 
 .emotion-0>* {

package/src/custom-gradient-picker/gradient-bar/control-points.js

@@ -1,3 +1,5 @@
+// @ts-nocheck
+
 /**
  * External dependencies
  */

package/src/custom-gradient-picker/gradient-bar/index.js

@@ -1,3 +1,5 @@
+// @ts-nocheck
+
 /**
  * External dependencies
  */

package/src/custom-gradient-picker/gradient-bar/utils.js

@@ -1,3 +1,5 @@
+// @ts-nocheck
+
 /**
  * Internal dependencies
  */

package/src/custom-gradient-picker/index.js

@@ -1,3 +1,5 @@
+// @ts-nocheck
+
 /**
  * External dependencies
  */

package/src/custom-gradient-picker/serializer.js

@@ -1,3 +1,5 @@
+// @ts-nocheck
+
 export function serializeGradientColor( { type, value } ) {
 	if ( type === 'literal' ) {
 		return value;

package/src/custom-gradient-picker/utils.js

@@ -1,3 +1,5 @@
+// @ts-nocheck
+
 /**
  * External dependencies
  */

package/src/dimension-control/README.md

@@ -8,77 +8,46 @@ This feature is still experimental. “Experimental” means this is an early im
 
 ## Usage
 
-In a block's `edit` implementation, render a `<DimensionControl />` component.
-
 ```jsx
-import { registerBlockType } from '@wordpress/blocks';
-import { __ } from '@wordpress/i18n';
-import { DimensionControl } from '@wordpress/components';
-
-const partialRight =
-	( fn, ...partialArgs ) =>
-	( ...args ) =>
-		fn( ...args, ...partialArgs );
-
-registerBlockType( 'my-plugin/my-block', {
-	// ...
-
-	attributes: {
-		// other attributes here
-		// ...
-
-		paddingSize: {
-			type: 'string',
-		},
-	},
-
-	edit( { attributes, setAttributes, clientId } ) {
-		const { paddingSize } = attributes;
-
-		const updateSpacing = ( dimension, size, device = '' ) => {
-			setAttributes( {
-				[ `${ dimension }${ device }` ]: size,
-			} );
-		};
-
-		return (
-			<DimensionControl
-				label={ __( 'Padding' ) }
-				icon={ 'desktop' }
-				onChange={ partialRight( updateSpacing, 'paddingSize' ) }
-				value={ paddingSize }
-			/>
-		);
-	},
-} );
+import { useState } from 'react';
+import { __experimentalDimensionControl as DimensionControl } from '@wordpress/components';
+
+export default function MyCustomDimensionControl() {
+	const [ paddingSize, setPaddingSize ] = useState( '' );
+
+	return (
+		<DimensionControl
+			label={ 'Padding' }
+			icon={ 'desktop' }
+			onChange={ ( value ) => setPaddingSize( value ) }
+			value={ paddingSize }
+		/>
+	);
+}
 ```
 
-_Note:_ it is recommended to partially apply the value of the Block attribute to be updated (eg: `paddingSize`, `marginSize`...etc) to your callback functions. This avoids the need to unnecessarily couple the component to the Block attribute schema.
-
 _Note:_ by default, if you do not provide an initial `value` prop for the current dimension value, then no value will be selected (ie: there is no default dimension set).
 
 ## Props
 
 ### `label`
 
--   **Type:** `String`
--   **Default:** `undefined`
+-   **Type:** `string`
 -   **Required:** Yes
 
 The human readable label for the control.
 
 ### `value`
 
--   **Type:** `String`
--   **Default:** `''`
+-   **Type:** `string`
 -   **Required:** No
 
 The current value of the dimension UI control. If provided the UI with automatically select the value.
 
 ### `sizes`
 
--   **Type:** `Array`
--   **Default:** See `packages/block-editor/src/components/dimension-control/sizes.js`
+-   **Type:** `{ name: string; slug: string }[]`
+-   **Default:** See `packages/block-editor/src/components/dimension-control/sizes.ts`
 -   **Required:** No
 
 An optional array of size objects in the following shape:
@@ -101,16 +70,14 @@ By default a set of relative sizes (`small`, `medium`...etc) are provided. See `
 
 ### `icon`
 
--   **Type:** `String`
--   **Default:** `undefined`
+-   **Type:** `string`
 -   **Required:** No
 
 An optional dashicon to display before to the control label.
 
 ### `onChange`
 
--   **Type:** `Function`
--   **Default:** `undefined`
+-   **Type:** `( value?: string ) => void;`
 -   **Required:** No
 -   **Arguments:**:
     -   `size` - a string representing the selected size (eg: `medium`)
@@ -119,7 +86,7 @@ A callback which is triggered when a spacing size value changes (is selected/cli
 
 ### `className`
 
--   **Type:** `String`
+-   **Type:** `string`
 -   **Default:** `''`
 -   **Required:** No
 

package/src/dimension-control/index.tsx

@@ -0,0 +1,101 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import Icon from '../icon';
+import SelectControl from '../select-control';
+import sizesTable, { findSizeBySlug } from './sizes';
+import type { DimensionControlProps, Size } from './types';
+import type { SelectControlSingleSelectionProps } from '../select-control/types';
+
+/**
+ * `DimensionControl` is a component designed to provide a UI to control spacing and/or dimensions.
+ *
+ * This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
+ *
+ * ```jsx
+ * import { useState } from 'react';
+ * import { __experimentalDimensionControl as DimensionControl } from '@wordpress/components';
+ *
+ * export default function MyCustomDimensionControl() {
+ * 	const [ paddingSize, setPaddingSize ] = useState( '' );
+ *
+ * 	return (
+ * 		<DimensionControl
+ * 			label={ 'Padding' }
+ * 			icon={ 'desktop' }
+ * 			onChange={ ( value ) => setPaddingSize( value ) }
+ * 			value={ paddingSize }
+ * 		/>
+ * 	);
+ * }
+ * ```
+ */
+export function DimensionControl( props: DimensionControlProps ) {
+	const {
+		label,
+		value,
+		sizes = sizesTable,
+		icon,
+		onChange,
+		className = '',
+	} = props;
+
+	const onChangeSpacingSize: SelectControlSingleSelectionProps[ 'onChange' ] =
+		( val ) => {
+			const theSize = findSizeBySlug( sizes, val );
+
+			if ( ! theSize || value === theSize.slug ) {
+				onChange?.( undefined );
+			} else if ( typeof onChange === 'function' ) {
+				onChange( theSize.slug );
+			}
+		};
+
+	const formatSizesAsOptions = ( theSizes: Size[] ) => {
+		const options = theSizes.map( ( { name, slug } ) => ( {
+			label: name,
+			value: slug,
+		} ) );
+
+		return [
+			{
+				label: __( 'Default' ),
+				value: '',
+			},
+			...options,
+		];
+	};
+
+	const selectLabel = (
+		<>
+			{ icon && <Icon icon={ icon } /> }
+			{ label }
+		</>
+	);
+
+	return (
+		<SelectControl
+			className={ classnames(
+				className,
+				'block-editor-dimension-control'
+			) }
+			label={ selectLabel }
+			hideLabelFromVision={ false }
+			value={ value }
+			onChange={ onChangeSpacingSize }
+			options={ formatSizesAsOptions( sizes ) }
+		/>
+	);
+}
+
+export default DimensionControl;

package/src/dimension-control/{sizes.js → sizes.ts}

@@ -12,16 +12,19 @@
  */
 import { _x } from '@wordpress/i18n';
 
+/**
+ * Internal dependencies
+ */
+import type { Size } from './types';
+
 /**
  * Finds the correct size object from the provided sizes
  * table by size slug (eg: `medium`)
  *
- * @param {Array}  sizes containing objects for each size definition.
- * @param {string} slug  a string representation of the size (eg: `medium`).
- *
- * @return {Object} the matching size definition.
+ * @param sizes containing objects for each size definition.
+ * @param slug  a string representation of the size (eg: `medium`).
  */
-export const findSizeBySlug = ( sizes, slug ) =>
+export const findSizeBySlug = ( sizes: Size[], slug: string ) =>
 	sizes.find( ( size ) => slug === size.slug );
 
 export default [

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

@@ -0,0 +1,48 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+/**
+ * Internal dependencies
+ */
+import { DimensionControl } from '..';
+import sizes from '../sizes';
+
+/**
+ * WordPress dependencies
+ */
+import { desktop, tablet, mobile } from '@wordpress/icons';
+
+export default {
+	component: DimensionControl,
+	title: 'Components (Experimental)/DimensionControl',
+	argTypes: {
+		onChange: { action: 'onChange' },
+		value: { control: { type: null } },
+		icon: {
+			control: { type: 'select' },
+			options: [ '-', 'desktop', 'tablet', 'mobile' ],
+			mapping: {
+				'-': undefined,
+				desktop,
+				tablet,
+				mobile,
+			},
+		},
+		parameters: {
+			controls: { expanded: true },
+			docs: { source: { state: 'open' } },
+		},
+	},
+} as ComponentMeta< typeof DimensionControl >;
+
+const Template: ComponentStory< typeof DimensionControl > = ( args ) => (
+	<DimensionControl { ...args } />
+);
+
+export const Default = Template.bind( {} );
+
+Default.args = {
+	label: 'Please select a size',
+	sizes,
+};