@wordpress/components 23.9.0 → 25.0.0

package/src/autocomplete/README.md

@@ -152,57 +152,83 @@ Whether to apply debouncing for the autocompleter. Set to true to enable debounc
 
 ## Usage
 
-The following is a contrived completer for fresh fruit.
-
-```jsx
-import { Autocomplete } from '@wordpress/components';
-
-const MyAutocomplete = () => {
-	const autocompleters = [
-		{
-			name: 'fruit',
-			// The prefix that triggers this completer
-			triggerPrefix: '~',
-			// The option data
-			options: [
-				{ visual: '🍎', name: 'Apple', id: 1 },
-				{ visual: '🍊', name: 'Orange', id: 2 },
-				{ visual: '🍇', name: 'Grapes', id: 3 },
-			],
-			// Returns a label for an option like "🍊 Orange"
-			getOptionLabel: ( option ) => (
-				<span>
-					<span className="icon">{ option.visual }</span>
-					{ option.name }
-				</span>
-			),
-			// Declares that options should be matched by their name
-			getOptionKeywords: ( option ) => [ option.name ],
-			// Declares that the Grapes option is disabled
-			isOptionDisabled: ( option ) => option.name === 'Grapes',
-			// Declares completions should be inserted as abbreviations
-			getOptionCompletion: ( option ) => (
-				<abbr title={ option.name }>{ option.visual }</abbr>
-			),
-		},
-	];
-
-	return (
-		<div>
-			<Autocomplete completers={ autocompleters }>
-				{ ( { isExpanded, listBoxId, activeId } ) => (
-					<div
-						contentEditable
-						suppressContentEditableWarning
-						aria-autocomplete="list"
-						aria-expanded={ isExpanded }
-						aria-owns={ listBoxId }
-						aria-activedescendant={ activeId }
-					></div>
-				) }
-			</Autocomplete>
-			<p>Type ~ for triggering the autocomplete.</p>
-		</div>
+The `Autocomplete` component is not currently intended to be used as a standalone component. It is used by other packages to provide autocompletion support for the block editor.
+
+The block editor provides a separate, wrapped version of `Autocomplete` that supports the addition of custom completers via a filter.
+
+To implement your own completer in the block editor you will:
+1. Define the completer
+2. Write a callback that will add your completer to the list of existing completers
+3. Add a filter to the `editor.Autocomplete.completers` hook that will call your callback
+
+The following example will add a contrived "fruits" autocompleter to the block editor. Note that in the callback it's possible to limit this new completer to a specific block type. In this case, our "fruits" completer will only be available from the "core/paragraph" block type.
+
+```js
+( function () {
+	// Define the completer
+	const fruits = {
+		name: 'fruit',
+		// The prefix that triggers this completer
+		triggerPrefix: '~',
+		// The option data
+		options: [
+			{ visual: '🍎', name: 'Apple', id: 1 },
+			{ visual: '🍊', name: 'Orange', id: 2 },
+			{ visual: '🍇', name: 'Grapes', id: 3 },
+			{ visual: '🥭', name: 'Mango', id: 4 },
+			{ visual: '🍓', name: 'Strawberry', id: 5 },
+			{ visual: '🫐', name: 'Blueberry', id: 6 },
+			{ visual: '🍒', name: 'Cherry', id: 7 },
+		],
+		// Returns a label for an option like "🍊 Orange"
+		getOptionLabel: ( option ) => `${ option.visual } ${ option.name }`,
+		// Declares that options should be matched by their name
+		getOptionKeywords: ( option ) => [ option.name ],
+		// Declares that the Grapes option is disabled
+		isOptionDisabled: ( option ) => option.name === 'Grapes',
+		// Declares completions should be inserted as abbreviations
+		getOptionCompletion: ( option ) => option.visual,
+	};
+
+	// Define a callback that will add the custom completer to the list of completers
+	function appendTestCompleters( completers, blockName ) {
+		return blockName === 'core/paragraph'
+			? [ ...completers, fruits ]
+			: completers;
+	}
+
+	// Trigger our callback on the `editor.Autocomplete.completers` hook
+	wp.hooks.addFilter(
+		'editor.Autocomplete.completers',
+		'fruit-test/fruits',
+		appendTestCompleters,
+		11
 	);
-};
+} )();
+```
+
+Finally, enqueue your JavaScript file as you would any other, as in the following plugin example:
+
+```php
+<?php
+/**
+ * Plugin Name: Fruit Autocompleter
+ * Plugin URI: https://github.com/WordPress/gutenberg
+ * Author: Gutenberg Team
+ */
+
+/**
+ * Registers a custom script for the plugin.
+ */
+function enqueue_fruit_autocompleter_plugin_script() {
+	wp_enqueue_script(
+		'fruit-autocompleter',
+		plugins_url( '/index.js', __FILE__ ),
+		array(
+			'wp-hooks',
+		),
+	);
+}
+
+add_action( 'init', 'enqueue_fruit_autocompleter_plugin_script' );
 ```

package/src/autocomplete/autocompleter-ui.tsx

@@ -12,8 +12,6 @@ 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';
 

package/src/autocomplete/index.tsx

@@ -26,8 +26,6 @@ import {
 	insert,
 	isCollapsed,
 	getTextContent,
-	// Error expected because `@wordpress/rich-text` is not yet fully typed.
-	// @ts-expect-error
 } from '@wordpress/rich-text';
 import { speak } from '@wordpress/a11y';
 
@@ -241,6 +239,7 @@ export function useAutocomplete( {
 		if ( isCollapsed( record ) ) {
 			return getTextContent( slice( record, 0 ) );
 		}
+		return '';
 	}, [ record ] );
 
 	useEffect( () => {

package/src/autocomplete/types.ts

@@ -2,6 +2,8 @@
  * WordPress dependencies
  */
 import type { WPElement } from '@wordpress/element';
+import type { RichTextValue } from '@wordpress/rich-text';
+
 /**
  * Internal dependencies
  */
@@ -157,24 +159,6 @@ 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.
@@ -187,7 +171,7 @@ export type UseAutocompleteProps = {
 	 * A function to be called when an option is selected to insert into the
 	 * existing text.
 	 */
-	onChange: ( value: string ) => void;
+	onChange: ( value: RichTextValue ) => void;
 	/**
 	 * A function to be called when an option is selected to replace the
 	 * existing text.

package/src/button/index.tsx

@@ -75,6 +75,7 @@ export function UnforwardedButton(
 	ref: ForwardedRef< any >
 ) {
 	const {
+		__next40pxDefaultSize,
 		isSmall,
 		isPressed,
 		isBusy,
@@ -115,6 +116,7 @@ export function UnforwardedButton(
 			children?.[ 0 ]?.props?.className !== 'components-tooltip' );
 
 	const classes = classnames( 'components-button', className, {
+		'is-next-40px-default-size': __next40pxDefaultSize,
 		'is-secondary': variant === 'secondary',
 		'is-primary': variant === 'primary',
 		'is-small': isSmall,

package/src/button/style.scss

@@ -18,6 +18,10 @@
 	border-radius: $radius-block-ui;
 	color: $components-color-foreground;
 
+	&.is-next-40px-default-size {
+		height: $button-size-next-default-40px;
+	}
+
 	&[aria-expanded="true"],
 	&:hover {
 		color: $components-color-accent;
@@ -114,21 +118,14 @@
 		outline: 1px solid transparent;
 
 		&:active:not(:disabled) {
-			background: $components-color-gray-300;
-			color: $components-color-accent-darker-10;
 			box-shadow: none;
 		}
 
-		&:hover:not(:disabled) {
-			color: $components-color-accent-darker-10;
-		}
-
 		&:disabled,
 		&[aria-disabled="true"],
 		&[aria-disabled="true"]:hover {
-			// TODO: Prepare for theming (https://github.com/WordPress/gutenberg/pull/45466/files#r1030872724)
-			color: lighten($gray-700, 5%);
-			background: lighten($gray-300, 5%);
+			color: $gray-600;
+			background: transparent;
 			transform: none;
 			opacity: 1;
 			box-shadow: none;
@@ -160,13 +157,14 @@
 		white-space: nowrap;
 		color: $components-color-accent;
 		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) {
+		&:hover:not(:disabled, [aria-disabled="true"]) {
+			// TODO: Prepare for theming (https://github.com/WordPress/gutenberg/pull/45466/files#r1030872724)
 			background: rgba(var(--wp-admin-theme-color--rgb), 0.04);
 		}
 
-		&:active:not(:disabled) {
+		&:active:not(:disabled, [aria-disabled="true"]) {
+			// TODO: Prepare for theming (https://github.com/WordPress/gutenberg/pull/45466/files#r1030872724)
 			background: rgba(var(--wp-admin-theme-color--rgb), 0.08);
 		}
 
@@ -234,7 +232,7 @@
 		}
 	}
 
-	&:not([aria-disabled="true"]):active {
+	&:not(:disabled, [aria-disabled="true"]):active {
 		color: $components-color-foreground;
 	}
 
@@ -284,6 +282,10 @@
 		min-width: $button-size;
 		justify-content: center;
 
+		&.is-next-40px-default-size {
+			min-width: $button-size-next-default-40px;
+		}
+
 		.dashicon {
 			display: inline-block;
 			flex: 0 0 auto;
@@ -293,11 +295,9 @@
 
 		&.has-text {
 			justify-content: start;
-			padding-right: 12px;
-		}
-
-		&.has-text svg {
-			margin-right: $grid-unit-10;
+			padding-right: $grid-unit-15;
+			padding-left: $grid-unit-10;
+			gap: $grid-unit-05;
 		}
 
 		&.has-text .dashicon {

package/src/button/types.ts

@@ -18,6 +18,13 @@ export type ButtonAsButtonProps = BaseButtonProps & _ButtonProps;
 export type ButtonAsAnchorProps = BaseButtonProps & AnchorProps;
 
 type BaseButtonProps = {
+	/**
+	 * Start opting into the larger default height that will become the
+	 * default size in a future version.
+	 *
+	 * @default false
+	 */
+	__next40pxDefaultSize?: boolean;
 	/**
 	 * The button's children.
 	 */

package/src/card/card-media/README.md

@@ -1,6 +1,6 @@
 # CardMedia
 
-`CardMedia` provides a container for media elements within a [`Card`](/packages/components/src/card/card/README.md).
+`CardMedia` provides a container for full-bleed content within a [`Card`](/packages/components/src/card/card/README.md), such as images, video, or even just a background color.
 
 ## Usage
 

package/src/card/card-media/component.tsx

@@ -21,7 +21,8 @@ function UnconnectedCardMedia(
 }
 
 /**
- * `CardMedia` provides a container for media elements within a `Card`.
+ * `CardMedia` provides a container for full-bleed content within a `Card`,
+ * such as images, video, or even just a background color.
  *
  * @example
  * ```jsx

package/src/card/stories/index.tsx

@@ -41,31 +41,52 @@ const meta: ComponentMeta< typeof Card > = {
 export default meta;
 
 const Template: ComponentStory< typeof Card > = ( args ) => (
-	<Card { ...args }>
-		<CardHeader>
-			<Heading>CardHeader</Heading>
-		</CardHeader>
-		<CardBody>
-			<Text>CardBody</Text>
-		</CardBody>
-		<CardBody>
-			<Text>CardBody (before CardDivider)</Text>
-		</CardBody>
-		<CardDivider />
-		<CardBody>
-			<Text>CardBody (after CardDivider)</Text>
-		</CardBody>
-		<CardMedia>
-			<img
-				alt="Card Media"
-				src="https://images.unsplash.com/photo-1566125882500-87e10f726cdc?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1867&q=80"
-			/>
-		</CardMedia>
-		<CardFooter>
-			<Text>CardFooter</Text>
-			<Button variant="secondary">Action Button</Button>
-		</CardFooter>
-	</Card>
+	<Card { ...args } />
 );
 
-export const Default: ComponentStory< typeof Card > = Template.bind( {} );
+export const Default = Template.bind( {} );
+Default.args = {
+	children: (
+		<>
+			<CardHeader>
+				<Heading>CardHeader</Heading>
+			</CardHeader>
+			<CardBody>
+				<Text>CardBody</Text>
+			</CardBody>
+			<CardBody>
+				<Text>CardBody (before CardDivider)</Text>
+			</CardBody>
+			<CardDivider />
+			<CardBody>
+				<Text>CardBody (after CardDivider)</Text>
+			</CardBody>
+			<CardMedia>
+				<img
+					alt="Card Media"
+					src="https://images.unsplash.com/photo-1566125882500-87e10f726cdc?ixlib=rb-1.2.1&ixid=MnwxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8&auto=format&fit=crop&w=1867&q=80"
+				/>
+			</CardMedia>
+			<CardFooter>
+				<Text>CardFooter</Text>
+				<Button variant="secondary">Action Button</Button>
+			</CardFooter>
+		</>
+	),
+};
+
+/**
+ * `CardMedia` provides a container for full-bleed content within a `Card`,
+ * such as images, video, or even just a background color. The corners will be rounded if necessary.
+ */
+export const FullBleedContent = Template.bind( {} );
+FullBleedContent.args = {
+	...Default.args,
+	children: (
+		<CardMedia>
+			<div style={ { padding: 16, background: 'beige' } }>
+				Some full bleed content
+			</div>
+		</CardMedia>
+	),
+};

package/src/checkbox-control/style.scss

@@ -27,10 +27,7 @@ $checkbox-input-size-sm: 24px; // Width & height for small viewports.
 	@include reduce-motion("transition");
 
 	&:focus {
-		box-shadow: 0 0 0 ($border-width * 2) $white, 0 0 0 ($border-width * 2 + $border-width-focus) $components-color-accent;
-
-		// Only visible in Windows High Contrast mode.
-		outline: 2px solid transparent;
+		@include button-style-outset__focus(var(--wp-admin-theme-color));
 	}
 
 	&:checked,

package/src/color-picker/styles.ts

@@ -29,8 +29,13 @@ export const NumberControlWrapper = styled( NumberControl )`
 export const SelectControl = styled( InnerSelectControl )`
 	margin-left: ${ space( -2 ) };
 	width: 5em;
-	${ BackdropUI } {
-		display: none;
+	/*
+	 * Remove border, but preserve focus styles
+	 * TODO: this override should be removed,
+	 * see https://github.com/WordPress/gutenberg/pull/50609
+	 */
+	select:not( :focus ) ~ ${ BackdropUI }${ BackdropUI }${ BackdropUI } {
+		border-color: transparent;
 	}
 `;
 

package/src/combobox-control/index.tsx

@@ -32,6 +32,7 @@ import { useControlledValue } from '../utils/hooks';
 import { normalizeTextString } from '../utils/strings';
 import type { ComboboxControlOption, ComboboxControlProps } from './types';
 import type { TokenInputProps } from '../form-token-field/types';
+import { useDeprecated36pxDefaultSizeProp } from '../utils/use-deprecated-props';
 
 const noop = () => {};
 
@@ -104,23 +105,28 @@ const getIndexOfMatchingSuggestion = (
  * }
  * ```
  */
-function ComboboxControl( {
-	__nextHasNoMarginBottom = false,
-	__next36pxDefaultSize = false,
-	value: valueProp,
-	label,
-	options,
-	onChange: onChangeProp,
-	onFilterValueChange = noop,
-	hideLabelFromVision,
-	help,
-	allowReset = true,
-	className,
-	messages = {
-		selected: __( 'Item selected.' ),
-	},
-	__experimentalRenderItem,
-}: ComboboxControlProps ) {
+function ComboboxControl( props: ComboboxControlProps ) {
+	const {
+		__nextHasNoMarginBottom = false,
+		__next40pxDefaultSize = false,
+		value: valueProp,
+		label,
+		options,
+		onChange: onChangeProp,
+		onFilterValueChange = noop,
+		hideLabelFromVision,
+		help,
+		allowReset = true,
+		className,
+		messages = {
+			selected: __( 'Item selected.' ),
+		},
+		__experimentalRenderItem,
+	} = useDeprecated36pxDefaultSizeProp< ComboboxControlProps >(
+		props,
+		'wp.components.ComboboxControl'
+	);
+
 	const [ value, setValue ] = useControlledValue( {
 		value: valueProp,
 		onChange: onChangeProp,
@@ -314,7 +320,7 @@ function ComboboxControl( {
 					onKeyDown={ onKeyDown }
 				>
 					<InputWrapperFlex
-						__next36pxDefaultSize={ __next36pxDefaultSize }
+						__next40pxDefaultSize={ __next40pxDefaultSize }
 					>
 						<FlexBlock>
 							<TokenInput

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

@@ -65,7 +65,6 @@ const Template: ComponentStory< typeof ComboboxControl > = ( {
 };
 export const Default = Template.bind( {} );
 Default.args = {
-	__next36pxDefaultSize: false,
 	allowReset: false,
 	label: 'Select a country',
 	options: countryOptions,

package/src/combobox-control/styles.ts

@@ -12,9 +12,9 @@ import { space } from '../ui/utils/space';
 import type { ComboboxControlProps } from './types';
 
 const deprecatedDefaultSize = ( {
-	__next36pxDefaultSize,
-}: Pick< ComboboxControlProps, '__next36pxDefaultSize' > ) =>
-	! __next36pxDefaultSize &&
+	__next40pxDefaultSize,
+}: Pick< ComboboxControlProps, '__next40pxDefaultSize' > ) =>
+	! __next40pxDefaultSize &&
 	css`
 		height: 28px; // 30px - 2px vertical borders on parent container
 		padding-left: ${ space( 1 ) };
@@ -22,7 +22,7 @@ const deprecatedDefaultSize = ( {
 	`;
 
 export const InputWrapperFlex = styled( Flex )`
-	height: 34px; // 36px - 2px vertical borders on parent container
+	height: 38px; // 40px - 2px vertical borders on parent container
 	padding-left: ${ space( 2 ) };
 	padding-right: ${ space( 2 ) };
 

package/src/combobox-control/types.ts

@@ -26,11 +26,18 @@ export type ComboboxControlProps = Pick<
 		item: ComboboxControlOption;
 	} ) => React.ReactNode;
 	/**
-	 * Start opting into the larger default height that will become the default size in a future version.
+	 * Deprecated. Use `__next40pxDefaultSize` instead.
 	 *
 	 * @default false
+	 * @deprecated
 	 */
 	__next36pxDefaultSize?: boolean;
+	/**
+	 * Start opting into the larger default height that will become the default size in a future version.
+	 *
+	 * @default false
+	 */
+	__next40pxDefaultSize?: boolean;
 	/**
 	 * Show a reset button to clear the input.
 	 *

package/src/custom-gradient-picker/style.scss

@@ -76,14 +76,14 @@ $components-custom-gradient-picker__padding: $grid-unit-20; // 48px container, 1
 		padding: 0;
 
 		// Shadow and stroke.
-		box-shadow: inset 0 0 0 var(--wp-admin-border-width-focus) $white, 0 0 $border-width-focus 0 rgba($black, 0.25);
+		box-shadow: inset 0 0 0 var(--wp-admin-border-width-focus) $white, 0 0 $border-width-focus-fallback 0 rgba($black, 0.25);
 
 		// Windows High Contrast mode will show this outline, but not the box-shadow.
 		outline: 2px solid transparent;
 
 		&:focus,
 		&.is-active {
-			box-shadow: inset 0 0 0 calc(var(--wp-admin-border-width-focus) * 2) $white, 0 0 $border-width-focus 0 rgba($black, 0.25);
+			box-shadow: inset 0 0 0 calc(var(--wp-admin-border-width-focus) * 2) $white, 0 0 $border-width-focus-fallback 0 rgba($black, 0.25);
 
 			// Windows High Contrast mode will show this outline, but not the box-shadow.
 			outline: $border-width-tab solid transparent;

package/src/date-time/README.md

@@ -26,8 +26,6 @@ const MyDateTimePicker = () => {
 			currentDate={ date }
 			onChange={ ( newDate ) => setDate( newDate ) }
 			is12Hour={ true }
-			__nextRemoveHelpButton
-			__nextRemoveResetButton
 		/>
 	);
 };
@@ -83,17 +81,3 @@ The day that the week should start on. 0 for Sunday, 1 for Monday, etc.
 
 - Required: No
 - Default: 0
-
-### `__nextRemoveHelpButton`: `boolean`
-
-Start opting in to not displaying a Help button which will become the default in a future version.
-
-- Required: No
-- Default: `false`
-
-### `__nextRemoveResetButton`: `boolean`
-
-Start opting in to not displaying a Reset button which will become the default in a future version.
-
-- Required: No
-- Default: `false`