@wordpress/components 28.7.0 → 28.8.0

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

@@ -188,6 +188,46 @@ describe.each( [
 		expect( input ).toHaveValue( targetOption.label );
 	} );
 
+	it( 'calls onFilterValueChange whenever the textbox changes', async () => {
+		const user = userEvent.setup();
+		const onFilterValueChangeSpy = jest.fn();
+		render(
+			<Component
+				options={ timezones }
+				label={ defaultLabelText }
+				onFilterValueChange={ onFilterValueChangeSpy }
+			/>
+		);
+
+		const input = getInput( defaultLabelText );
+
+		await user.type( input, 'a' );
+		expect( onFilterValueChangeSpy ).toHaveBeenCalledWith( 'a' );
+	} );
+
+	it( 'clears the textbox value if there is no selected value on blur', async () => {
+		const user = userEvent.setup();
+		const onFilterValueChangeSpy = jest.fn();
+		render(
+			<Component
+				options={ timezones }
+				label={ defaultLabelText }
+				onFilterValueChange={ onFilterValueChangeSpy }
+			/>
+		);
+		const input = getInput( defaultLabelText );
+
+		await user.type( input, 'a' );
+		expect( input ).toHaveValue( 'a' );
+
+		// Blur and focus the input.
+		await user.tab();
+		await user.click( input );
+
+		expect( input ).toHaveValue( '' );
+		expect( onFilterValueChangeSpy ).toHaveBeenLastCalledWith( '' );
+	} );
+
 	it( 'should select the correct option from a search', async () => {
 		const user = await userEvent.setup();
 		const targetOption = timezones[ 13 ];

package/src/combobox-control/types.ts

@@ -82,4 +82,8 @@ export type ComboboxControlProps = Pick<
 	 * The current value of the control.
 	 */
 	value?: string | null;
+	/**
+	 * If passed, the combobox input will show a placeholder string if no values are present.
+	 */
+	placeholder?: string;
 };

package/src/composite/README.md

@@ -1,18 +1,13 @@
 # `Composite`
 
-<div class="callout callout-alert">
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-</div>
-
 `Composite` provides a single tab stop on the page and allows navigation through the focusable descendants with arrow keys. This abstract component is based on the [WAI-ARIA Composite Role⁠](https://w3c.github.io/aria/#composite).
 
 ## Usage
 
 ```jsx
-import { Composite, useCompositeStore } from '@wordpress/components';
+import { Composite } from '@wordpress/components';
 
-const store = useCompositeStore();
-<Composite store={store}>
+<Composite>
   <Composite.Group>
     <Composite.GroupLabel>Label</Composite.GroupLabel>
     <Composite.Item>Item 1</Composite.Item>
@@ -21,11 +16,11 @@ const store = useCompositeStore();
 </Composite>
 ```
 
-## Hooks
+## Components
 
-### `useCompositeStore`
+### `Composite`
 
-Creates a composite store.
+Renders a composite widget.
 
 #### Props
 
@@ -131,20 +126,6 @@ This only affects the composite widget behavior. You still need to set `dir="rtl
 -   Required: no
 -   Default: `false`
 
-## Components
-
-### `Composite`
-
-Renders a composite widget.
-
-#### Props
-
-##### `store`: `CompositeStore<CompositeStoreItem>`
-
-Object returned by the `useCompositeStore` hook.
-
--   Required: yes
-
 ##### `render`: `RenderProp<React.HTMLAttributes<any> & { ref?: React.Ref<any> | undefined; }> | React.ReactElement<any, string | React.JSXElementConstructor<any>>`
 
 Allows the component to be rendered as a different HTML element or React component. The value can be a React element or a function that takes in the original component props and gives back a React element with the props merged.

package/src/composite/{context.ts → context.tsx}

@@ -8,7 +8,6 @@ import { createContext, useContext } from '@wordpress/element';
  */
 import type { CompositeContextProps } from './types';
 
-export const CompositeContext =
-	createContext< CompositeContextProps >( undefined );
+export const CompositeContext = createContext< CompositeContextProps >( {} );
 
 export const useCompositeContext = () => useContext( CompositeContext );

package/src/composite/group-label.tsx

@@ -22,7 +22,7 @@ export const CompositeGroupLabel = forwardRef<
 	const context = useCompositeContext();
 	return (
 		<Ariakit.CompositeGroupLabel
-			store={ context?.store }
+			store={ context.store as Ariakit.CompositeStore }
 			{ ...props }
 			ref={ ref }
 		/>

package/src/composite/group.tsx

@@ -22,7 +22,7 @@ export const CompositeGroup = forwardRef<
 	const context = useCompositeContext();
 	return (
 		<Ariakit.CompositeGroup
-			store={ context?.store }
+			store={ context.store as Ariakit.CompositeStore }
 			{ ...props }
 			ref={ ref }
 		/>

package/src/composite/hover.tsx

@@ -22,7 +22,7 @@ export const CompositeHover = forwardRef<
 	const context = useCompositeContext();
 	return (
 		<Ariakit.CompositeHover
-			store={ context?.store }
+			store={ context.store as Ariakit.CompositeStore }
 			{ ...props }
 			ref={ ref }
 		/>

package/src/composite/index.tsx

@@ -16,6 +16,7 @@ import * as Ariakit from '@ariakit/react';
 /**
  * WordPress dependencies
  */
+import { isRTL } from '@wordpress/i18n';
 import { useMemo, forwardRef } from '@wordpress/element';
 
 /**
@@ -38,10 +39,9 @@ import type { CompositeProps } from './types';
  *
  * @example
  * ```jsx
- * import { Composite, useCompositeStore } from '@wordpress/components';
+ * import { Composite } from '@wordpress/components';
  *
- * const store = useCompositeStore();
- * <Composite store={store}>
+ * <Composite>
  *   <Composite.Item>Item 1</Composite.Item>
  *   <Composite.Item>Item 2</Composite.Item>
  * </Composite>
@@ -62,21 +62,18 @@ export const Composite = Object.assign(
 			focusShift = false,
 			virtualFocus = false,
 			orientation = 'both',
-			rtl = false,
+			rtl = isRTL(),
 
 			// Composite component props
 			children,
 			disabled = false,
 
-			// To be removed
-			store: storeProp,
-
 			// Rest props
 			...props
 		},
 		ref
 	) {
-		const newStore = Ariakit.useCompositeStore( {
+		const store = Ariakit.useCompositeStore( {
 			activeId,
 			defaultActiveId,
 			setActiveId,
@@ -88,8 +85,6 @@ export const Composite = Object.assign(
 			rtl,
 		} );
 
-		const store = storeProp || newStore;
-
 		const contextValue = useMemo(
 			() => ( {
 				store,
@@ -116,10 +111,9 @@ export const Composite = Object.assign(
 		 *
 		 * @example
 		 * ```jsx
-		 * import { Composite, useCompositeStore } from '@wordpress/components';
+		 * import { Composite } from '@wordpress/components';
 		 *
-		 * const store = useCompositeStore();
-		 * <Composite store={store}>
+		 * <Composite>
 		 *   <Composite.Group>
 		 *     <Composite.GroupLabel>Label</Composite.GroupLabel>
 		 *     <Composite.Item>Item 1</Composite.Item>
@@ -138,10 +132,9 @@ export const Composite = Object.assign(
 		 *
 		 * @example
 		 * ```jsx
-		 * import { Composite, useCompositeStore } from '@wordpress/components';
+		 * import { Composite } from '@wordpress/components';
 		 *
-		 * const store = useCompositeStore();
-		 * <Composite store={store}>
+		 * <Composite>
 		 *   <Composite.Group>
 		 *     <Composite.GroupLabel>Label</Composite.GroupLabel>
 		 *     <Composite.Item>Item 1</Composite.Item>
@@ -158,10 +151,9 @@ export const Composite = Object.assign(
 		 *
 		 * @example
 		 * ```jsx
-		 * import { Composite, useCompositeStore } from '@wordpress/components';
+		 * import { Composite } from '@wordpress/components';
 		 *
-		 * const store = useCompositeStore();
-		 * <Composite store={store}>
+		 * <Composite>
 		 *   <Composite.Item>Item 1</Composite.Item>
 		 *   <Composite.Item>Item 2</Composite.Item>
 		 *   <Composite.Item>Item 3</Composite.Item>
@@ -176,10 +168,9 @@ export const Composite = Object.assign(
 		 *
 		 * @example
 		 * ```jsx
-		 * import { Composite, useCompositeStore } from '@wordpress/components';
+		 * import { Composite } from '@wordpress/components';
 		 *
-		 * const store = useCompositeStore();
-		 * <Composite store={store}>
+		 * <Composite>
 		 *   <Composite.Row>
 		 *     <Composite.Item>Item 1.1</Composite.Item>
 		 *     <Composite.Item>Item 1.2</Composite.Item>
@@ -201,10 +192,9 @@ export const Composite = Object.assign(
 		 *
 		 * @example
 		 * ```jsx
-		 * import { Composite, useCompositeStore } from '@wordpress/components';
+		 * import { Composite } from '@wordpress/components';
 		 *
-		 * const store = useCompositeStore();
-		 * <Composite store={store}>
+		 * <Composite>
 		 *   <Composite.Hover render={ <Composite.Item /> }>
 		 *     Item 1
 		 *   </Composite.Hover>
@@ -224,10 +214,9 @@ export const Composite = Object.assign(
 		 *
 		 * @example
 		 * ```jsx
-		 * import { Composite, useCompositeStore } from '@wordpress/components';
+		 * import { Composite } from '@wordpress/components';
 		 *
-		 * const store = useCompositeStore();
-		 * <Composite store={store} render={ <CompositeTypeahead /> }>
+		 * <Composite render={ <CompositeTypeahead /> }>
 		 *   <Composite.Item>Item 1</Composite.Item>
 		 *   <Composite.Item>Item 2</Composite.Item>
 		 * </Composite>

package/src/composite/item.tsx

@@ -22,7 +22,7 @@ export const CompositeItem = forwardRef<
 	const context = useCompositeContext();
 	return (
 		<Ariakit.CompositeItem
-			store={ context?.store }
+			store={ context.store as Ariakit.CompositeStore }
 			{ ...props }
 			ref={ ref }
 		/>

package/src/composite/legacy/index.tsx

@@ -13,17 +13,22 @@
  * @see https://ariakit.org/components/composite
  */
 
+/**
+ * External dependencies
+ */
+import * as Ariakit from '@ariakit/react';
+
 /**
  * WordPress dependencies
  */
 import { forwardRef } from '@wordpress/element';
+import { useInstanceId } from '@wordpress/compose';
+import deprecated from '@wordpress/deprecated';
 
 /**
  * Internal dependencies
  */
 import { Composite as Current } from '..';
-import { useCompositeStore } from '../store';
-import { useInstanceId } from '@wordpress/compose';
 
 type Orientation = 'horizontal' | 'vertical';
 
@@ -79,7 +84,7 @@ export interface LegacyStateOptions {
 
 type Component = React.FunctionComponent< any >;
 
-type CompositeStore = ReturnType< typeof useCompositeStore >;
+type CompositeStore = ReturnType< typeof Ariakit.useCompositeStore >;
 type CompositeStoreState = { store: CompositeStore };
 export type CompositeState = CompositeStoreState &
 	Required< Pick< LegacyStateOptions, 'baseId' > >;
@@ -119,12 +124,31 @@ function mapLegacyStatePropsToComponentProps(
 	return legacyProps;
 }
 
+const LEGACY_TO_NEW_DISPLAY_NAME = {
+	__unstableComposite: 'Composite',
+	__unstableCompositeGroup: 'Composite.Group or Composite.Row',
+	__unstableCompositeItem: 'Composite.Item',
+	__unstableUseCompositeState: 'Composite',
+};
+
 function proxyComposite< C extends Component >(
 	ProxiedComponent: C | React.ForwardRefExoticComponent< C >,
 	propMap: Record< string, string > = {}
 ): CompositeComponent< C > {
-	const displayName = ProxiedComponent.displayName;
+	const displayName = ProxiedComponent.displayName ?? '';
+
 	const Component = ( legacyProps: CompositeStateProps ) => {
+		deprecated( `wp.components.${ displayName }`, {
+			since: '6.7',
+			alternative: LEGACY_TO_NEW_DISPLAY_NAME.hasOwnProperty(
+				displayName
+			)
+				? LEGACY_TO_NEW_DISPLAY_NAME[
+						displayName as keyof typeof LEGACY_TO_NEW_DISPLAY_NAME
+				  ]
+				: undefined,
+		} );
+
 		const { store, ...rest } =
 			mapLegacyStatePropsToComponentProps( legacyProps );
 		const props = rest as ComponentProps< C >;
@@ -149,7 +173,7 @@ function proxyComposite< C extends Component >(
 // `CompositeRow`, but this has been split into two different
 // components. We handle that difference by checking on the
 // provided role, and returning the appropriate component.
-const unproxiedCompositeGroup = forwardRef<
+const UnproxiedCompositeGroup = forwardRef<
 	any,
 	React.ComponentPropsWithoutRef< typeof Current.Group | typeof Current.Row >
 >( ( { role, ...props }, ref ) => {
@@ -157,15 +181,52 @@ const unproxiedCompositeGroup = forwardRef<
 	return <Component ref={ ref } role={ role } { ...props } />;
 } );
 
-export const Composite = proxyComposite( Current, { baseId: 'id' } );
-export const CompositeGroup = proxyComposite( unproxiedCompositeGroup );
-export const CompositeItem = proxyComposite( Current.Item, {
-	focusable: 'accessibleWhenDisabled',
-} );
+/**
+ * _Note: please use the `Composite` component instead._
+ *
+ * @deprecated
+ */
+export const Composite = proxyComposite(
+	Object.assign( Current, { displayName: '__unstableComposite' } ),
+	{ baseId: 'id' }
+);
+/**
+ * _Note: please use the `Composite.Row` or `Composite.Group` components instead._
+ *
+ * @deprecated
+ */
+export const CompositeGroup = proxyComposite(
+	Object.assign( UnproxiedCompositeGroup, {
+		displayName: '__unstableCompositeGroup',
+	} )
+);
+/**
+ * _Note: please use the `Composite.Item` component instead._
+ *
+ * @deprecated
+ */
+export const CompositeItem = proxyComposite(
+	Object.assign( Current.Item, {
+		displayName: '__unstableCompositeItem',
+	} ),
+	{
+		focusable: 'accessibleWhenDisabled',
+	}
+);
 
+/**
+ * _Note: please use the `Composite` component instead._
+ *
+ * @deprecated
+ */
 export function useCompositeState(
 	legacyStateOptions: LegacyStateOptions = {}
 ): CompositeState {
+	deprecated( `wp.components.__unstableUseCompositeState`, {
+		since: '6.7',
+		alternative: LEGACY_TO_NEW_DISPLAY_NAME.__unstableUseCompositeState,
+	} );
+
 	const {
 		baseId,
 		currentId: defaultActiveId,
@@ -180,7 +241,7 @@ export function useCompositeState(
 
 	return {
 		baseId: useInstanceId( Composite, 'composite', baseId ),
-		store: useCompositeStore( {
+		store: Ariakit.useCompositeStore( {
 			defaultActiveId,
 			rtl,
 			orientation,

package/src/composite/legacy/stories/index.story.tsx

@@ -15,7 +15,8 @@ import {
 import { UseCompositeStatePlaceholder, transform } from './utils';
 
 const meta: Meta< typeof UseCompositeStatePlaceholder > = {
-	title: 'Components/Composite',
+	title: 'Components (Deprecated)/Composite (Unstable)',
+	id: 'components-composite-unstable',
 	component: UseCompositeStatePlaceholder,
 	subcomponents: {
 		Composite,

package/src/composite/legacy/test/index.tsx

@@ -1,7 +1,12 @@
 /**
  * External dependencies
  */
-import { queryByAttribute, render, screen } from '@testing-library/react';
+import {
+	queryByAttribute,
+	render,
+	screen,
+	renderHook,
+} from '@testing-library/react';
 import { press, waitFor } from '@ariakit/test';
 
 /**
@@ -156,6 +161,57 @@ function getShiftTestItems() {
 	};
 }
 
+// Checking for deprecation warnings before other tests because the `deprecated`
+// utility only fires a console.warn the first time a component is rendered.
+describe( 'Shows a deprecation warning', () => {
+	it( 'useCompositeState', () => {
+		renderHook( () => useCompositeState() );
+		expect( console ).toHaveWarnedWith(
+			'wp.components.__unstableUseCompositeState is deprecated since version 6.7. Please use Composite instead.'
+		);
+	} );
+	it( 'Composite', () => {
+		const Test = () => {
+			const props = useCompositeState();
+			return <Composite { ...props } />;
+		};
+		render( <Test /> );
+		expect( console ).toHaveWarnedWith(
+			'wp.components.__unstableComposite is deprecated since version 6.7. Please use Composite instead.'
+		);
+	} );
+	it( 'CompositeItem', () => {
+		const Test = () => {
+			const props = useCompositeState();
+			return (
+				<Composite { ...props }>
+					<CompositeItem { ...props } />
+				</Composite>
+			);
+		};
+		render( <Test /> );
+		expect( console ).toHaveWarnedWith(
+			'wp.components.__unstableCompositeItem is deprecated since version 6.7. Please use Composite.Item instead.'
+		);
+	} );
+	it( 'CompositeGroup', () => {
+		const Test = () => {
+			const props = useCompositeState();
+			return (
+				<Composite { ...props }>
+					<CompositeGroup { ...props }>
+						<CompositeItem { ...props } />
+					</CompositeGroup>
+				</Composite>
+			);
+		};
+		render( <Test /> );
+		expect( console ).toHaveWarnedWith(
+			'wp.components.__unstableCompositeGroup is deprecated since version 6.7. Please use Composite.Group or Composite.Row instead.'
+		);
+	} );
+} );
+
 describe.each( [
 	[
 		'With "spread" state',

package/src/composite/row.tsx

@@ -22,7 +22,7 @@ export const CompositeRow = forwardRef<
 	const context = useCompositeContext();
 	return (
 		<Ariakit.CompositeRow
-			store={ context?.store }
+			store={ context.store as Ariakit.CompositeStore }
 			{ ...props }
 			ref={ ref }
 		/>