@wordpress/components 28.6.0 → 28.8.0

package/src/combobox-control/README.md

@@ -111,6 +111,13 @@ If the control is clicked, the dropdown will expand regardless of this prop.
 -   Required: No
 -   Default: `true`
 
+### placeholder
+
+If passed, the combobox input will show a placeholder string if no values are present.
+
+-   Type: `string`
+-   Required: No
+
 #### __experimentalRenderItem
 
 Custom renderer invoked for each option in the suggestion list. The render prop receives as its argument an object containing, under the `item` key, the single option's data (directly from the array of data passed to the `options` prop).

package/src/combobox-control/index.tsx

@@ -129,6 +129,7 @@ function ComboboxControl( props: ComboboxControlProps ) {
 		},
 		__experimentalRenderItem,
 		expandOnFocus = true,
+		placeholder,
 	} = useDeprecated36pxDefaultSizeProp( props );
 
 	const [ value, setValue ] = useControlledValue( {
@@ -340,6 +341,7 @@ function ComboboxControl( props: ComboboxControlProps ) {
 								className="components-combobox-control__input"
 								instanceId={ instanceId }
 								ref={ inputContainer }
+								placeholder={ placeholder }
 								value={ isExpanded ? inputValue : currentLabel }
 								onFocus={ onFocus }
 								onBlur={ onBlur }

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

@@ -31,6 +31,7 @@ export type ComboboxControlProps = Pick<
 	 *
 	 * @default false
 	 * @deprecated
+	 * @ignore
 	 */
 	__next36pxDefaultSize?: boolean;
 	/**
@@ -81,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

@@ -0,0 +1,30 @@
+/**
+ * External dependencies
+ */
+import * as Ariakit from '@ariakit/react';
+
+/**
+ * WordPress dependencies
+ */
+import { forwardRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { WordPressComponentProps } from '../context';
+import { useCompositeContext } from './context';
+import type { CompositeGroupLabelProps } from './types';
+
+export const CompositeGroupLabel = forwardRef<
+	HTMLDivElement,
+	WordPressComponentProps< CompositeGroupLabelProps, 'div', false >
+>( function CompositeGroupLabel( props, ref ) {
+	const context = useCompositeContext();
+	return (
+		<Ariakit.CompositeGroupLabel
+			store={ context.store as Ariakit.CompositeStore }
+			{ ...props }
+			ref={ ref }
+		/>
+	);
+} );

package/src/composite/group.tsx

@@ -0,0 +1,30 @@
+/**
+ * External dependencies
+ */
+import * as Ariakit from '@ariakit/react';
+
+/**
+ * WordPress dependencies
+ */
+import { forwardRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { WordPressComponentProps } from '../context';
+import { useCompositeContext } from './context';
+import type { CompositeGroupProps } from './types';
+
+export const CompositeGroup = forwardRef<
+	HTMLDivElement,
+	WordPressComponentProps< CompositeGroupProps, 'div', false >
+>( function CompositeGroup( props, ref ) {
+	const context = useCompositeContext();
+	return (
+		<Ariakit.CompositeGroup
+			store={ context.store as Ariakit.CompositeStore }
+			{ ...props }
+			ref={ ref }
+		/>
+	);
+} );

package/src/composite/hover.tsx

@@ -0,0 +1,30 @@
+/**
+ * External dependencies
+ */
+import * as Ariakit from '@ariakit/react';
+
+/**
+ * WordPress dependencies
+ */
+import { forwardRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { WordPressComponentProps } from '../context';
+import { useCompositeContext } from './context';
+import type { CompositeHoverProps } from './types';
+
+export const CompositeHover = forwardRef<
+	HTMLDivElement,
+	WordPressComponentProps< CompositeHoverProps, 'div', false >
+>( function CompositeHover( props, ref ) {
+	const context = useCompositeContext();
+	return (
+		<Ariakit.CompositeHover
+			store={ context.store as Ariakit.CompositeStore }
+			{ ...props }
+			ref={ ref }
+		/>
+	);
+} );

package/src/composite/index.tsx

@@ -16,148 +16,21 @@ import * as Ariakit from '@ariakit/react';
 /**
  * WordPress dependencies
  */
+import { isRTL } from '@wordpress/i18n';
 import { useMemo, forwardRef } from '@wordpress/element';
 
 /**
  * Internal dependencies
  */
 import type { WordPressComponentProps } from '../context';
-import { CompositeContext, useCompositeContext } from './context';
-import type {
-	CompositeStoreProps,
-	CompositeProps,
-	CompositeGroupProps,
-	CompositeGroupLabelProps,
-	CompositeItemProps,
-	CompositeRowProps,
-	CompositeHoverProps,
-	CompositeTypeaheadProps,
-} from './types';
-
-/**
- * Creates a composite store.
- *
- * @example
- * ```jsx
- * import { Composite, useCompositeStore } from '@wordpress/components';
- *
- * const store = useCompositeStore();
- * <Composite store={store}>
- *   <Composite.Item>Item</Composite.Item>
- *   <Composite.Item>Item</Composite.Item>
- *   <Composite.Item>Item</Composite.Item>
- * </Composite>
- * ```
- */
-export function useCompositeStore( {
-	focusLoop = false,
-	focusWrap = false,
-	focusShift = false,
-	virtualFocus = false,
-	orientation = 'both',
-	rtl = false,
-	...props
-}: CompositeStoreProps = {} ) {
-	return Ariakit.useCompositeStore( {
-		focusLoop,
-		focusWrap,
-		focusShift,
-		virtualFocus,
-		orientation,
-		rtl,
-		...props,
-	} );
-}
-
-const Group = forwardRef<
-	HTMLDivElement,
-	WordPressComponentProps< CompositeGroupProps, 'div', false >
->( function CompositeGroup( props, ref ) {
-	const context = useCompositeContext();
-	return (
-		<Ariakit.CompositeGroup
-			store={ context?.store }
-			{ ...props }
-			ref={ ref }
-		/>
-	);
-} );
-Group.displayName = 'Composite.Group';
-
-const GroupLabel = forwardRef<
-	HTMLDivElement,
-	WordPressComponentProps< CompositeGroupLabelProps, 'div', false >
->( function CompositeGroupLabel( props, ref ) {
-	const context = useCompositeContext();
-	return (
-		<Ariakit.CompositeGroupLabel
-			store={ context?.store }
-			{ ...props }
-			ref={ ref }
-		/>
-	);
-} );
-GroupLabel.displayName = 'Composite.GroupLabel';
-
-const Item = forwardRef<
-	HTMLButtonElement,
-	WordPressComponentProps< CompositeItemProps, 'button', false >
->( function CompositeItem( props, ref ) {
-	const context = useCompositeContext();
-	return (
-		<Ariakit.CompositeItem
-			store={ context?.store }
-			{ ...props }
-			ref={ ref }
-		/>
-	);
-} );
-Item.displayName = 'Composite.Item';
-
-const Row = forwardRef<
-	HTMLDivElement,
-	WordPressComponentProps< CompositeRowProps, 'div', false >
->( function CompositeRow( props, ref ) {
-	const context = useCompositeContext();
-	return (
-		<Ariakit.CompositeRow
-			store={ context?.store }
-			{ ...props }
-			ref={ ref }
-		/>
-	);
-} );
-Row.displayName = 'Composite.Row';
-
-const Hover = forwardRef<
-	HTMLDivElement,
-	WordPressComponentProps< CompositeHoverProps, 'div', false >
->( function CompositeHover( props, ref ) {
-	const context = useCompositeContext();
-	return (
-		<Ariakit.CompositeHover
-			store={ context?.store }
-			{ ...props }
-			ref={ ref }
-		/>
-	);
-} );
-Hover.displayName = 'Composite.Hover';
-
-const Typeahead = forwardRef<
-	HTMLDivElement,
-	WordPressComponentProps< CompositeTypeaheadProps, 'div', false >
->( function CompositeTypeahead( props, ref ) {
-	const context = useCompositeContext();
-	return (
-		<Ariakit.CompositeTypeahead
-			store={ context?.store }
-			{ ...props }
-			ref={ ref }
-		/>
-	);
-} );
-Typeahead.displayName = 'Composite.Typeahead';
+import { CompositeContext } from './context';
+import { CompositeGroup } from './group';
+import { CompositeGroupLabel } from './group-label';
+import { CompositeHover } from './hover';
+import { CompositeItem } from './item';
+import { CompositeRow } from './row';
+import { CompositeTypeahead } from './typeahead';
+import type { CompositeProps } from './types';
 
 /**
  * Renders a widget based on the WAI-ARIA [`composite`](https://w3c.github.io/aria/#composite)
@@ -166,10 +39,9 @@ Typeahead.displayName = 'Composite.Typeahead';
  *
  * @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>
@@ -180,9 +52,39 @@ export const Composite = Object.assign(
 		HTMLDivElement,
 		WordPressComponentProps< CompositeProps, 'div', false >
 	>( function Composite(
-		{ children, store, disabled = false, ...props },
+		{
+			// Composite store props
+			activeId,
+			defaultActiveId,
+			setActiveId,
+			focusLoop = false,
+			focusWrap = false,
+			focusShift = false,
+			virtualFocus = false,
+			orientation = 'both',
+			rtl = isRTL(),
+
+			// Composite component props
+			children,
+			disabled = false,
+
+			// Rest props
+			...props
+		},
 		ref
 	) {
+		const store = Ariakit.useCompositeStore( {
+			activeId,
+			defaultActiveId,
+			setActiveId,
+			focusLoop,
+			focusWrap,
+			focusShift,
+			virtualFocus,
+			orientation,
+			rtl,
+		} );
+
 		const contextValue = useMemo(
 			() => ( {
 				store,
@@ -204,16 +106,14 @@ export const Composite = Object.assign(
 		);
 	} ),
 	{
-		displayName: 'Composite',
 		/**
 		 * Renders a group element for composite items.
 		 *
 		 * @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>
@@ -222,7 +122,9 @@ export const Composite = Object.assign(
 		 * </Composite>
 		 * ```
 		 */
-		Group,
+		Group: Object.assign( CompositeGroup, {
+			displayName: 'Composite.Group',
+		} ),
 		/**
 		 * Renders a label in a composite group. This component must be wrapped with
 		 * `Composite.Group` so the `aria-labelledby` prop is properly set on the
@@ -230,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>
@@ -242,23 +143,24 @@ export const Composite = Object.assign(
 		 * </Composite>
 		 * ```
 		 */
-		GroupLabel,
+		GroupLabel: Object.assign( CompositeGroupLabel, {
+			displayName: 'Composite.GroupLabel',
+		} ),
 		/**
 		 * Renders a composite item.
 		 *
 		 * @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>
 		 * </Composite>
 		 * ```
 		 */
-		Item,
+		Item: Object.assign( CompositeItem, { displayName: 'Composite.Item' } ),
 		/**
 		 * Renders a composite row. Wrapping `Composite.Item` elements within
 		 * `Composite.Row` will create a two-dimensional composite widget, such as a
@@ -266,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>
@@ -283,7 +184,7 @@ export const Composite = Object.assign(
 		 * </Composite>
 		 * ```
 		 */
-		Row,
+		Row: Object.assign( CompositeRow, { displayName: 'Composite.Row' } ),
 		/**
 		 * Renders an element in a composite widget that receives focus on mouse move
 		 * and loses focus to the composite base element on mouse leave. This should
@@ -291,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>
@@ -304,7 +204,9 @@ export const Composite = Object.assign(
 		 * </Composite>
 		 * ```
 		 */
-		Hover,
+		Hover: Object.assign( CompositeHover, {
+			displayName: 'Composite.Hover',
+		} ),
 		/**
 		 * Renders a component that adds typeahead functionality to composite
 		 * components. Hitting printable character keys will move focus to the next
@@ -312,16 +214,17 @@ 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>
 		 * ```
 		 */
-		Typeahead,
+		Typeahead: Object.assign( CompositeTypeahead, {
+			displayName: 'Composite.Typeahead',
+		} ),
 		/**
 		 * The React context used by the composite components. It can be used by
 		 * to access the composite store, and to forward the context when composite
@@ -336,6 +239,8 @@ export const Composite = Object.assign(
 		 * const compositeContext = useContext( Composite.Context );
 		 * ```
 		 */
-		Context: CompositeContext,
+		Context: Object.assign( CompositeContext, {
+			displayName: 'Composite.Context',
+		} ),
 	}
 );

package/src/composite/item.tsx

@@ -0,0 +1,30 @@
+/**
+ * External dependencies
+ */
+import * as Ariakit from '@ariakit/react';
+
+/**
+ * WordPress dependencies
+ */
+import { forwardRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { WordPressComponentProps } from '../context';
+import { useCompositeContext } from './context';
+import type { CompositeItemProps } from './types';
+
+export const CompositeItem = forwardRef<
+	HTMLButtonElement,
+	WordPressComponentProps< CompositeItemProps, 'button', false >
+>( function CompositeItem( props, ref ) {
+	const context = useCompositeContext();
+	return (
+		<Ariakit.CompositeItem
+			store={ context.store as Ariakit.CompositeStore }
+			{ ...props }
+			ref={ ref }
+		/>
+	);
+} );