@wordpress/components 28.4.0 → 28.6.0

package/src/composite/index.tsx

@@ -0,0 +1,341 @@
+/**
+ * Composite is a component that may contain navigable items represented by
+ * Composite.Item. It's inspired by the WAI-ARIA Composite Role and implements
+ * all the keyboard navigation mechanisms to ensure that there's only one
+ * tab stop for the whole Composite element. This means that it can behave as
+ * a roving tabindex or aria-activedescendant container.
+ *
+ * @see https://ariakit.org/components/composite
+ */
+
+/**
+ * External dependencies
+ */
+import * as Ariakit from '@ariakit/react';
+
+/**
+ * WordPress dependencies
+ */
+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';
+
+/**
+ * Renders a widget based on the WAI-ARIA [`composite`](https://w3c.github.io/aria/#composite)
+ * role, which provides a single tab stop on the page and arrow key navigation
+ * through the focusable descendants.
+ *
+ * @example
+ * ```jsx
+ * import { Composite, useCompositeStore } from '@wordpress/components';
+ *
+ * const store = useCompositeStore();
+ * <Composite store={store}>
+ *   <Composite.Item>Item 1</Composite.Item>
+ *   <Composite.Item>Item 2</Composite.Item>
+ * </Composite>
+ * ```
+ */
+export const Composite = Object.assign(
+	forwardRef<
+		HTMLDivElement,
+		WordPressComponentProps< CompositeProps, 'div', false >
+	>( function Composite(
+		{ children, store, disabled = false, ...props },
+		ref
+	) {
+		const contextValue = useMemo(
+			() => ( {
+				store,
+			} ),
+			[ store ]
+		);
+
+		return (
+			<Ariakit.Composite
+				disabled={ disabled }
+				store={ store }
+				{ ...props }
+				ref={ ref }
+			>
+				<CompositeContext.Provider value={ contextValue }>
+					{ children }
+				</CompositeContext.Provider>
+			</Ariakit.Composite>
+		);
+	} ),
+	{
+		displayName: 'Composite',
+		/**
+		 * Renders a group element for composite items.
+		 *
+		 * @example
+		 * ```jsx
+		 * import { Composite, useCompositeStore } from '@wordpress/components';
+		 *
+		 * const store = useCompositeStore();
+		 * <Composite store={store}>
+		 *   <Composite.Group>
+		 *     <Composite.GroupLabel>Label</Composite.GroupLabel>
+		 *     <Composite.Item>Item 1</Composite.Item>
+		 *     <Composite.Item>Item 2</Composite.Item>
+		 *   </CompositeGroup>
+		 * </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
+		 * composite group element.
+		 *
+		 * @example
+		 * ```jsx
+		 * import { Composite, useCompositeStore } from '@wordpress/components';
+		 *
+		 * const store = useCompositeStore();
+		 * <Composite store={store}>
+		 *   <Composite.Group>
+		 *     <Composite.GroupLabel>Label</Composite.GroupLabel>
+		 *     <Composite.Item>Item 1</Composite.Item>
+		 *     <Composite.Item>Item 2</Composite.Item>
+		 *   </CompositeGroup>
+		 * </Composite>
+		 * ```
+		 */
+		GroupLabel,
+		/**
+		 * Renders a composite item.
+		 *
+		 * @example
+		 * ```jsx
+		 * import { Composite, useCompositeStore } from '@wordpress/components';
+		 *
+		 * const store = useCompositeStore();
+		 * <Composite store={store}>
+		 *   <Composite.Item>Item 1</Composite.Item>
+		 *   <Composite.Item>Item 2</Composite.Item>
+		 *   <Composite.Item>Item 3</Composite.Item>
+		 * </Composite>
+		 * ```
+		 */
+		Item,
+		/**
+		 * Renders a composite row. Wrapping `Composite.Item` elements within
+		 * `Composite.Row` will create a two-dimensional composite widget, such as a
+		 * grid.
+		 *
+		 * @example
+		 * ```jsx
+		 * import { Composite, useCompositeStore } from '@wordpress/components';
+		 *
+		 * const store = useCompositeStore();
+		 * <Composite store={store}>
+		 *   <Composite.Row>
+		 *     <Composite.Item>Item 1.1</Composite.Item>
+		 *     <Composite.Item>Item 1.2</Composite.Item>
+		 *     <Composite.Item>Item 1.3</Composite.Item>
+		 *   </Composite.Row>
+		 *   <Composite.Row>
+		 *     <Composite.Item>Item 2.1</Composite.Item>
+		 *     <Composite.Item>Item 2.2</Composite.Item>
+		 *     <Composite.Item>Item 2.3</Composite.Item>
+		 *   </Composite.Row>
+		 * </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
+		 * be combined with the `Composite.Item` component.
+		 *
+		 * @example
+		 * ```jsx
+		 * import { Composite, useCompositeStore } from '@wordpress/components';
+		 *
+		 * const store = useCompositeStore();
+		 * <Composite store={store}>
+		 *   <Composite.Hover render={ <Composite.Item /> }>
+		 *     Item 1
+		 *   </Composite.Hover>
+		 *   <Composite.Hover render={ <Composite.Item /> }>
+		 *     Item 2
+		 *   </Composite.Hover>
+		 * </Composite>
+		 * ```
+		 */
+		Hover,
+		/**
+		 * Renders a component that adds typeahead functionality to composite
+		 * components. Hitting printable character keys will move focus to the next
+		 * composite item that begins with the input characters.
+		 *
+		 * @example
+		 * ```jsx
+		 * import { Composite, useCompositeStore } from '@wordpress/components';
+		 *
+		 * const store = useCompositeStore();
+		 * <Composite store={store} render={ <CompositeTypeahead /> }>
+		 *   <Composite.Item>Item 1</Composite.Item>
+		 *   <Composite.Item>Item 2</Composite.Item>
+		 * </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
+		 * sub-components are rendered across portals (ie. `SlotFill` components)
+		 * that would not otherwise forward the context to the `Fill` children.
+		 *
+		 * @example
+		 * ```jsx
+		 * import { Composite } from '@wordpress/components';
+		 * import { useContext } from '@wordpress/element';
+		 *
+		 * const compositeContext = useContext( Composite.Context );
+		 * ```
+		 */
+		Context: CompositeContext,
+	}
+);

package/src/composite/legacy/index.tsx

@@ -5,6 +5,11 @@
  * tab stop for the whole Composite element. This means that it can behave as
  * a roving tabindex or aria-activedescendant container.
  *
+ * This file aims at providing components that are as close as possible to the
+ * original `reakit`-based implementation (which was removed from the codebase),
+ * although it is recommended that consumers of the package switch to the stable,
+ * un-prefixed, `ariakit`-based version of `Composite`.
+ *
  * @see https://ariakit.org/components/composite
  */
 
@@ -16,7 +21,7 @@ import { forwardRef } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import * as Current from '../current';
+import { Composite as Current, useCompositeStore } from '..';
 import { useInstanceId } from '@wordpress/compose';
 
 type Orientation = 'horizontal' | 'vertical';
@@ -73,7 +78,7 @@ export interface LegacyStateOptions {
 
 type Component = React.FunctionComponent< any >;
 
-type CompositeStore = ReturnType< typeof Current.useCompositeStore >;
+type CompositeStore = ReturnType< typeof useCompositeStore >;
 type CompositeStoreState = { store: CompositeStore };
 export type CompositeState = CompositeStoreState &
 	Required< Pick< LegacyStateOptions, 'baseId' > >;
@@ -93,9 +98,9 @@ type CompositeComponent< C extends Component > = (
 ) => React.ReactElement;
 type CompositeComponentProps = CompositeState &
 	(
-		| ComponentProps< typeof Current.CompositeGroup >
-		| ComponentProps< typeof Current.CompositeItem >
-		| ComponentProps< typeof Current.CompositeRow >
+		| ComponentProps< typeof Current.Group >
+		| ComponentProps< typeof Current.Item >
+		| ComponentProps< typeof Current.Row >
 	);
 
 function mapLegacyStatePropsToComponentProps(
@@ -145,19 +150,15 @@ function proxyComposite< C extends Component >(
 // provided role, and returning the appropriate component.
 const unproxiedCompositeGroup = forwardRef<
 	any,
-	React.ComponentPropsWithoutRef<
-		typeof Current.CompositeGroup | typeof Current.CompositeRow
-	>
+	React.ComponentPropsWithoutRef< typeof Current.Group | typeof Current.Row >
 >( ( { role, ...props }, ref ) => {
-	const Component =
-		role === 'row' ? Current.CompositeRow : Current.CompositeGroup;
+	const Component = role === 'row' ? Current.Row : Current.Group;
 	return <Component ref={ ref } role={ role } { ...props } />;
 } );
-unproxiedCompositeGroup.displayName = 'CompositeGroup';
 
-export const Composite = proxyComposite( Current.Composite, { baseId: 'id' } );
+export const Composite = proxyComposite( Current, { baseId: 'id' } );
 export const CompositeGroup = proxyComposite( unproxiedCompositeGroup );
-export const CompositeItem = proxyComposite( Current.CompositeItem, {
+export const CompositeItem = proxyComposite( Current.Item, {
 	focusable: 'accessibleWhenDisabled',
 } );
 
@@ -178,7 +179,7 @@ export function useCompositeState(
 
 	return {
 		baseId: useInstanceId( Composite, 'composite', baseId ),
-		store: Current.useCompositeStore( {
+		store: useCompositeStore( {
 			defaultActiveId,
 			rtl,
 			orientation,

package/src/composite/legacy/stories/utils.tsx

@@ -8,6 +8,25 @@ import type { StoryContext } from '@storybook/react';
  */
 import type { LegacyStateOptions } from '..';
 
+/**
+ * Renders a composite widget.
+ *
+ * This unstable component is deprecated. Use `Composite` instead.
+ *
+ * ```jsx
+ * import {
+ * 	__unstableUseCompositeState as useCompositeState,
+ * 	__unstableComposite as Composite,
+ * 	__unstableCompositeItem as CompositeItem,
+ * } from '@wordpress/components';
+ *
+ * const state = useCompositeState();
+ * <Composite state={ state }>
+ * 	<CompositeItem>Item 1</CompositeItem>
+ * 	<CompositeItem>Item 2</CompositeItem>
+ * </Composite>;
+ * ```
+ */
 export function UseCompositeStatePlaceholder( props: LegacyStateOptions ) {
 	return (
 		<dl>

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

@@ -2,7 +2,7 @@
  * External dependencies
  */
 import { queryByAttribute, render, screen } from '@testing-library/react';
-import { press, sleep, waitFor } from '@ariakit/test';
+import { press, waitFor } from '@ariakit/test';
 
 /**
  * Internal dependencies
@@ -47,7 +47,7 @@ async function renderAndValidate( ...args: Parameters< typeof render > ) {
 		const activeButton = queryByAttribute(
 			'data-active-item',
 			view.baseElement,
-			''
+			'true'
 		);
 		expect( activeButton ).not.toBeNull();
 	} );
@@ -178,13 +178,10 @@ describe.each( [
 		);
 		renderAndValidate( <Test /> );
 
-		await sleep();
 		await press.Tab();
 		expect( screen.getByText( 'Before' ) ).toHaveFocus();
-		await sleep();
 		await press.Tab();
 		expect( screen.getByText( 'Item 1' ) ).toHaveFocus();
-		await sleep();
 		await press.Tab();
 		expect( screen.getByText( 'After' ) ).toHaveFocus();
 		await press.ShiftTab();
@@ -213,7 +210,6 @@ describe.each( [
 
 		expect( item2 ).toBeDisabled();
 
-		await sleep();
 		await press.Tab();
 		expect( item1 ).toHaveFocus();
 		await press.ArrowDown();
@@ -243,7 +239,6 @@ describe.each( [
 		expect( item2 ).toBeEnabled();
 		expect( item2 ).toHaveAttribute( 'aria-disabled', 'true' );
 
-		await sleep();
 		await press.Tab();
 		expect( item1 ).toHaveFocus();
 		await press.ArrowDown();
@@ -279,7 +274,6 @@ describe.each( [
 		renderAndValidate( <Test /> );
 		const { item2 } = getOneDimensionalItems();
 
-		await sleep();
 		await press.Tab();
 		await waitFor( () => expect( item2 ).toHaveFocus() );
 	} );
@@ -323,7 +317,6 @@ describe.each( [
 		test( 'All directions work with no orientation', async () => {
 			const { item1, item2, item3 } = useOneDimensionalTest();
 
-			await sleep();
 			await press.Tab();
 			expect( item1 ).toHaveFocus();
 			await press.ArrowDown();
@@ -361,7 +354,6 @@ describe.each( [
 				orientation: 'horizontal',
 			} );
 
-			await sleep();
 			await press.Tab();
 			expect( item1 ).toHaveFocus();
 			await press.ArrowDown();
@@ -391,7 +383,6 @@ describe.each( [
 				orientation: 'vertical',
 			} );
 
-			await sleep();
 			await press.Tab();
 			expect( item1 ).toHaveFocus();
 			await press( next );
@@ -421,7 +412,6 @@ describe.each( [
 				loop: true,
 			} );
 
-			await sleep();
 			await press.Tab();
 			expect( item1 ).toHaveFocus();
 			await press.ArrowDown();
@@ -444,7 +434,6 @@ describe.each( [
 			const { itemA1, itemA2, itemA3, itemB1, itemB2, itemC1, itemC3 } =
 				useTwoDimensionalTest();
 
-			await sleep();
 			await press.Tab();
 			expect( itemA1 ).toHaveFocus();
 			await press.ArrowUp();
@@ -481,7 +470,6 @@ describe.each( [
 			const { itemA1, itemA2, itemA3, itemB1, itemC1, itemC3 } =
 				useTwoDimensionalTest( { loop: true } );
 
-			await sleep();
 			await press.Tab();
 			expect( itemA1 ).toHaveFocus();
 			await press( next );
@@ -506,7 +494,6 @@ describe.each( [
 			const { itemA1, itemA2, itemA3, itemB1, itemC1, itemC3 } =
 				useTwoDimensionalTest( { wrap: true } );
 
-			await sleep();
 			await press.Tab();
 			expect( itemA1 ).toHaveFocus();
 			await press( next );
@@ -539,7 +526,6 @@ describe.each( [
 				wrap: true,
 			} );
 
-			await sleep();
 			await press.Tab();
 			expect( itemA1 ).toHaveFocus();
 			await press( previous );
@@ -555,7 +541,6 @@ describe.each( [
 		test( 'Focus shifts if vertical neighbour unavailable when shift enabled', async () => {
 			const { itemA1, itemB1, itemB2, itemC1 } = useShiftTest( true );
 
-			await sleep();
 			await press.Tab();
 			expect( itemA1 ).toHaveFocus();
 			await press.ArrowDown();
@@ -577,7 +562,6 @@ describe.each( [
 		test( 'Focus does not shift if vertical neighbour unavailable when shift not enabled', async () => {
 			const { itemA1, itemB1, itemB2 } = useShiftTest( false );
 
-			await sleep();
 			await press.Tab();
 			expect( itemA1 ).toHaveFocus();
 			await press.ArrowDown();