@wordpress/components 28.8.4 → 28.9.0

package/src/border-control/border-control/README.md

@@ -1,10 +1,6 @@
-#  BorderControl
+# BorderControl
 
-<div class="callout callout-alert">
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-</div>
-<br />
-This component provides control over a border's color, style, and width.
+An input control for a border's color, style, and width.
 
 ## Development guidelines
 
@@ -21,7 +17,7 @@ a "shape" abstraction.
 
 ```jsx
 import { useState } from 'react';
-import { __experimentalBorderControl as BorderControl } from '@wordpress/components';
+import { BorderControl } from '@wordpress/components';
 import { __ } from '@wordpress/i18n';
 
 const colors = [
@@ -58,41 +54,41 @@ colors are organized by multiple origins.
 
 Each color may be an object containing a `name` and `color` value.
 
-- Required: No
-- Default: `[]`
+-   Required: No
+-   Default: `[]`
 
 ### `disableCustomColors`: `boolean`
 
 This toggles the ability to choose custom colors.
 
-- Required: No
+-   Required: No
 
 ### `disableUnits`: `boolean`
 
 This controls whether unit selection should be disabled.
 
-- Required: No
+-   Required: No
 
 ### `enableAlpha`: `boolean`
 
 This controls whether the alpha channel will be offered when selecting
 custom colors.
 
-- Required: No
-- Default: `false`
+-   Required: No
+-   Default: `true`
 
 ### `enableStyle`: `boolean`
 
 This controls whether to support border style selection.
 
-- Required: No
-- Default: `true`
+-   Required: No
+-   Default: `true`
 
 ### `hideLabelFromVision`: `boolean`
 
 Provides control over whether the label will only be visible to screen readers.
 
-- Required: No
+-   Required: No
 
 ### `isCompact`: `boolean`
 
@@ -100,7 +96,7 @@ This flags the `BorderControl` to render with a more compact appearance. It
 restricts the width of the control and prevents it from expanding to take up
 additional space.
 
-- Required: No
+-   Required: No
 
 ### `label`: `string`
 
@@ -109,7 +105,7 @@ If provided, a label will be generated using this as the content.
 _Whether it is visible only to screen readers is controlled via
 `hideLabelFromVision`._
 
-- Required: No
+-   Required: No
 
 ### `onChange`: `( value?: Object ) => void`
 
@@ -118,7 +114,7 @@ that selects or clears, border color, style, or width.
 
 _Note: the value may be `undefined` if a user clears all border properties._
 
-- Required: Yes
+-   Required: Yes
 
 ### `shouldSanitizeBorder`: `boolean`
 
@@ -126,23 +122,16 @@ If opted into, sanitizing the border means that if no width or color have been
 selected, the border style is also cleared and `undefined` is returned as the
 new border value.
 
-- Required: No
-- Default: true
-
-### `showDropdownHeader`: `boolean`
-
-Whether or not to render a header for the border color and style picker
-dropdown. The header includes a label for the color picker and a close button.
-
-- Required: No
+-   Required: No
+-   Default: `true`
 
 ### `size`: `string`
 
 Size of the control.
 
-- Required: No
-- Default: `default`
-- Allowed values: `default`, `__unstable-large`
+-   Required: No
+-   Default: `default`
+-   Allowed values: `default`, `__unstable-large`
 
 ### `value`: `Object`
 
@@ -150,6 +139,7 @@ An object representing a border or `undefined`. Used to set the current border
 configuration for this component.
 
 Example:
+
 ```js
  {
 	color: '#72aee6',
@@ -158,25 +148,25 @@ Example:
 }
 ```
 
-- Required: No
+-   Required: No
 
 ### `width`: `CSSProperties[ 'width' ]`
 
 Controls the visual width of the `BorderControl`. It has no effect if the
 `isCompact` prop is set to `true`.
 
-- Required: No
+-   Required: No
 
 ### `withSlider`: `boolean`
 
 Flags whether this `BorderControl` should also render a `RangeControl` for
 additional control over a border's width.
 
-- Required: No
+-   Required: No
 
 ### `__next40pxDefaultSize`: `boolean`
 
 Start opting into the larger default height that will become the default size in a future version.
 
-- Required: No
-- Default: `false`
+-   Required: No
+-   Default: `false`

package/src/border-control/border-control/component.tsx

@@ -91,7 +91,6 @@ const UnconnectedBorderControl = (
 								previousStyleSelection={
 									previousStyleSelection
 								}
-								showDropdownHeader={ showDropdownHeader }
 								__experimentalIsRenderedInSidebar={
 									__experimentalIsRenderedInSidebar
 								}
@@ -141,7 +140,7 @@ const UnconnectedBorderControl = (
  * a "shape" abstraction.
  *
  * ```jsx
- * import { __experimentalBorderControl as BorderControl } from '@wordpress/components';
+ * import { BorderControl } from '@wordpress/components';
  * import { __ } from '@wordpress/i18n';
  *
  * const colors = [

package/src/border-control/border-control-dropdown/component.tsx

@@ -7,7 +7,6 @@ import type { CSSProperties } from 'react';
  * WordPress dependencies
  */
 import { __, sprintf } from '@wordpress/i18n';
-import { closeSmall } from '@wordpress/icons';
 
 /**
  * Internal dependencies
@@ -17,12 +16,10 @@ import Button from '../../button';
 import ColorIndicator from '../../color-indicator';
 import ColorPalette from '../../color-palette';
 import Dropdown from '../../dropdown';
-import { HStack } from '../../h-stack';
 import { VStack } from '../../v-stack';
 import type { WordPressComponentProps } from '../../context';
 import { contextConnect } from '../../context';
 import { useBorderControlDropdown } from './hook';
-import { StyledLabel } from '../../base-control/styles/base-control-styles';
 import DropdownContentWrapper from '../../dropdown/dropdown-content-wrapper';
 
 import type { ColorObject } from '../../color-palette/types';
@@ -149,7 +146,6 @@ const BorderControlDropdown = (
 		popoverContentClassName,
 		popoverControlsClassName,
 		resetButtonClassName,
-		showDropdownHeader,
 		size,
 		__unstablePopoverProps,
 		...otherProps
@@ -197,17 +193,6 @@ const BorderControlDropdown = (
 		<>
 			<DropdownContentWrapper paddingSize="medium">
 				<VStack className={ popoverControlsClassName } spacing={ 6 }>
-					{ showDropdownHeader ? (
-						<HStack>
-							<StyledLabel>{ __( 'Border color' ) }</StyledLabel>
-							<Button
-								size="small"
-								label={ __( 'Close border color' ) }
-								icon={ closeSmall }
-								onClick={ onClose }
-							/>
-						</HStack>
-					) : undefined }
 					<ColorPalette
 						className={ popoverContentClassName }
 						value={ color }
@@ -237,6 +222,7 @@ const BorderControlDropdown = (
 							onReset();
 							onClose();
 						} }
+						__next40pxDefaultSize
 					>
 						{ __( 'Reset' ) }
 					</Button>

package/src/border-control/stories/index.story.tsx

@@ -16,7 +16,7 @@ import { BorderControl } from '..';
 import type { Border } from '../types';
 
 const meta: Meta< typeof BorderControl > = {
-	title: 'Components (Experimental)/BorderControl',
+	title: 'Components/BorderControl',
 	component: BorderControl,
 	argTypes: {
 		onChange: {
@@ -93,6 +93,9 @@ export const Default = Template.bind( {} );
 Default.args = {
 	colors,
 	label: 'Border',
+	enableAlpha: true,
+	enableStyle: true,
+	shouldSanitizeBorder: true,
 };
 
 /**
@@ -133,12 +136,3 @@ WithMultipleOrigins.args = {
 	...Default.args,
 	colors: multipleOriginColors,
 };
-
-/**
- * Allow the alpha channel to be edited on each color.
- */
-export const WithAlphaEnabled = Template.bind( {} );
-WithAlphaEnabled.args = {
-	...Default.args,
-	enableAlpha: true,
-};

package/src/border-control/styles.ts

@@ -156,7 +156,6 @@ export const resetButton = css`
 		border-top: ${ CONFIG.borderWidth } solid ${ COLORS.gray[ 400 ] };
 		border-top-left-radius: 0;
 		border-top-right-radius: 0;
-		height: 40px;
 	}
 `;
 

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

@@ -148,19 +148,6 @@ describe( 'BorderControl', () => {
 			expect( resetButton ).toBeInTheDocument();
 		} );
 
-		it( 'should render color and style popover header', async () => {
-			const user = userEvent.setup();
-			const props = createProps( { showDropdownHeader: true } );
-			render( <BorderControl { ...props } /> );
-			await openPopover( user );
-
-			const headerLabel = screen.getByText( 'Border color' );
-			const closeButton = getButton( 'Close border color' );
-
-			expect( headerLabel ).toBeInTheDocument();
-			expect( closeButton ).toBeInTheDocument();
-		} );
-
 		it( 'should not render style options when opted out of', async () => {
 			const user = userEvent.setup();
 			const props = createProps( { enableStyle: false } );
@@ -346,10 +333,10 @@ describe( 'BorderControl', () => {
 
 		it( 'should take no action when color and style popover is closed', async () => {
 			const user = userEvent.setup();
-			const props = createProps( { showDropdownHeader: true } );
+			const props = createProps();
 			render( <BorderControl { ...props } /> );
 			await openPopover( user );
-			await user.click( getButton( 'Close border color' ) );
+			await user.keyboard( 'Escape' );
 
 			expect( props.onChange ).not.toHaveBeenCalled();
 		} );

package/src/border-control/types.ts

@@ -18,12 +18,19 @@ export type Border = {
 
 export type ColorProps = Pick<
 	ColorPaletteProps,
-	'colors' | 'enableAlpha' | '__experimentalIsRenderedInSidebar'
+	'colors' | '__experimentalIsRenderedInSidebar'
 > & {
 	/**
 	 * This toggles the ability to choose custom colors.
 	 */
 	disableCustomColors?: boolean;
+	/**
+	 * This controls whether the alpha channel will be offered when selecting
+	 * custom colors.
+	 *
+	 * @default true
+	 */
+	enableAlpha?: boolean;
 };
 
 export type LabelProps = {
@@ -78,9 +85,8 @@ export type BorderControlProps = ColorProps &
 		 */
 		shouldSanitizeBorder?: boolean;
 		/**
-		 * Whether or not to show the header for the border color and style
-		 * picker dropdown. The header includes a label for the color picker
-		 * and a close button.
+		 * @deprecated This prop no longer has any effect.
+		 * @ignore
 		 */
 		showDropdownHeader?: boolean;
 		/**
@@ -139,9 +145,8 @@ export type DropdownProps = ColorProps &
 		 */
 		previousStyleSelection?: string;
 		/**
-		 * Whether or not to render a header for the border color and style picker
-		 * dropdown. The header includes a label for the color picker and a
-		 * close button.
+		 * @deprecated This prop no longer has any effect.
+		 * @ignore
 		 */
 		showDropdownHeader?: boolean;
 	};

package/src/box-control/README.md

@@ -1,18 +1,14 @@
 # BoxControl
 
-<div class="callout callout-alert">
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-</div>
-
-BoxControl components let users set values for Top, Right, Bottom, and Left. This can be used as an input control for values like `padding` or `margin`.
+A control that lets users set values for top, right, bottom, and left. Can be used as an input control for values like `padding` or `margin`.
 
 ## Usage
 
 ```jsx
 import { useState } from 'react';
-import { __experimentalBoxControl as BoxControl } from '@wordpress/components';
+import { BoxControl } from '@wordpress/components';
 
-const Example = () => {
+function Example() {
 	const [ values, setValues ] = useState( {
 		top: '50px',
 		left: '10%',
@@ -26,23 +22,24 @@ const Example = () => {
 			onChange={ ( nextValues ) => setValues( nextValues ) }
 		/>
 	);
-};
+}
 ```
 
 ## Props
+
 ### `allowReset`: `boolean`
 
 If this property is true, a button to reset the box control is rendered.
 
-- Required: No
-- Default: `true`
+-   Required: No
+-   Default: `true`
 
 ### `splitOnAxis`: `boolean`
 
 If this property is true, when the box control is unlinked, vertical and horizontal controls can be used instead of updating individual sides.
 
-- Required: No
-- Default: `false`
+-   Required: No
+-   Default: `false`
 
 ### `inputProps`: `object`
 

package/src/box-control/index.tsx

@@ -47,14 +47,14 @@ function useUniqueId( idProp?: string ) {
 }
 
 /**
- * BoxControl components let users set values for Top, Right, Bottom, and Left.
- * This can be used as an input control for values like `padding` or `margin`.
+ * A control that lets users set values for top, right, bottom, and left. Can be
+ * used as an input control for values like `padding` or `margin`.
  *
  * ```jsx
- * import { __experimentalBoxControl as BoxControl } from '@wordpress/components';
+ * import { BoxControl } from '@wordpress/components';
  * import { useState } from '@wordpress/element';
  *
- * const Example = () => {
+ * function Example() {
  * 	const [ values, setValues ] = useState( {
  * 		top: '50px',
  * 		left: '10%',

package/src/box-control/stories/index.story.tsx

@@ -14,7 +14,7 @@ import { useState } from '@wordpress/element';
 import BoxControl from '../';
 
 const meta: Meta< typeof BoxControl > = {
-	title: 'Components (Experimental)/BoxControl',
+	title: 'Components/BoxControl',
 	component: BoxControl,
 	argTypes: {
 		values: { control: { type: null } },

package/src/box-control/types.ts

@@ -37,13 +37,13 @@ export type BoxControlProps = Pick<
 	/**
 	 * Props for the internal `UnitControl` components.
 	 *
-	 * @default `{ min: 0 }`
+	 * @default { min: 0 }
 	 */
 	inputProps?: UnitControlPassthroughProps;
 	/**
 	 * Heading label for the control.
 	 *
-	 * @default `__( 'Box Control' )`
+	 * @default __( 'Box Control' )
 	 */
 	label?: string;
 	/**
@@ -53,7 +53,7 @@ export type BoxControlProps = Pick<
 	/**
 	 * The `top`, `right`, `bottom`, and `left` box dimension values to use when the control is reset.
 	 *
-	 * @default `{ top: undefined, right: undefined, bottom: undefined, left: undefined }`
+	 * @default { top: undefined, right: undefined, bottom: undefined, left: undefined }
 	 */
 	resetValues?: BoxControlValue;
 	/**

package/src/composite/group-label.tsx

@@ -20,11 +20,13 @@ export const CompositeGroupLabel = forwardRef<
 	WordPressComponentProps< CompositeGroupLabelProps, 'div', false >
 >( function CompositeGroupLabel( props, ref ) {
 	const context = useCompositeContext();
+
+	// @ts-expect-error The store prop is undocumented and only used by the
+	// legacy compat layer. The `store` prop is documented, but its type is
+	// obfuscated to discourage its use outside of the component's internals.
+	const store = ( props.store ?? context.store ) as Ariakit.CompositeStore;
+
 	return (
-		<Ariakit.CompositeGroupLabel
-			store={ context.store as Ariakit.CompositeStore }
-			{ ...props }
-			ref={ ref }
-		/>
+		<Ariakit.CompositeGroupLabel store={ store } { ...props } ref={ ref } />
 	);
 } );

package/src/composite/group.tsx

@@ -20,11 +20,11 @@ export const CompositeGroup = forwardRef<
 	WordPressComponentProps< CompositeGroupProps, 'div', false >
 >( function CompositeGroup( props, ref ) {
 	const context = useCompositeContext();
-	return (
-		<Ariakit.CompositeGroup
-			store={ context.store as Ariakit.CompositeStore }
-			{ ...props }
-			ref={ ref }
-		/>
-	);
+
+	// @ts-expect-error The store prop is undocumented and only used by the
+	// legacy compat layer. The `store` prop is documented, but its type is
+	// obfuscated to discourage its use outside of the component's internals.
+	const store = ( props.store ?? context.store ) as Ariakit.CompositeStore;
+
+	return <Ariakit.CompositeGroup store={ store } { ...props } ref={ ref } />;
 } );

package/src/composite/hover.tsx

@@ -20,11 +20,11 @@ export const CompositeHover = forwardRef<
 	WordPressComponentProps< CompositeHoverProps, 'div', false >
 >( function CompositeHover( props, ref ) {
 	const context = useCompositeContext();
-	return (
-		<Ariakit.CompositeHover
-			store={ context.store as Ariakit.CompositeStore }
-			{ ...props }
-			ref={ ref }
-		/>
-	);
+
+	// @ts-expect-error The store prop is undocumented and only used by the
+	// legacy compat layer. The `store` prop is documented, but its type is
+	// obfuscated to discourage its use outside of the component's internals.
+	const store = ( props.store ?? context.store ) as Ariakit.CompositeStore;
+
+	return <Ariakit.CompositeGroup store={ store } { ...props } ref={ ref } />;
 } );

package/src/composite/index.tsx

@@ -73,7 +73,10 @@ export const Composite = Object.assign(
 		},
 		ref
 	) {
-		const store = Ariakit.useCompositeStore( {
+		// @ts-expect-error The store prop is undocumented and only used by the
+		// legacy compat layer.
+		const storeProp = props.store as Ariakit.CompositeStore;
+		const internalStore = Ariakit.useCompositeStore( {
 			activeId,
 			defaultActiveId,
 			setActiveId,
@@ -85,6 +88,8 @@ export const Composite = Object.assign(
 			rtl,
 		} );
 
+		const store = storeProp ?? internalStore;
+
 		const contextValue = useMemo(
 			() => ( {
 				store,

package/src/composite/item.tsx

@@ -20,9 +20,27 @@ export const CompositeItem = forwardRef<
 	WordPressComponentProps< CompositeItemProps, 'button', false >
 >( function CompositeItem( props, ref ) {
 	const context = useCompositeContext();
+
+	// @ts-expect-error The store prop is undocumented and only used by the
+	// legacy compat layer. The `store` prop is documented, but its type is
+	// obfuscated to discourage its use outside of the component's internals.
+	const store = ( props.store ?? context.store ) as Ariakit.CompositeStore;
+
+	// If the active item is not connected, Composite may end up in a state
+	// where none of the items are tabbable. In this case, we force all items to
+	// be tabbable, so that as soon as an item received focus, it becomes active
+	// and Composite goes back to working as expected.
+	const tabbable = Ariakit.useStoreState( store, ( state ) => {
+		return (
+			state?.activeId !== null &&
+			! store?.item( state?.activeId )?.element?.isConnected
+		);
+	} );
+
 	return (
 		<Ariakit.CompositeItem
-			store={ context.store as Ariakit.CompositeStore }
+			store={ store }
+			tabbable={ tabbable }
 			{ ...props }
 			ref={ ref }
 		/>