@wordpress/components 28.5.0 → 28.7.0

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 }
+			{ ...props }
+			ref={ ref }
+		/>
+	);
+} );

package/src/composite/index.tsx

@@ -0,0 +1,257 @@
+/**
+ * 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 } 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)
+ * 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(
+		{
+			// Composite store props
+			activeId,
+			defaultActiveId,
+			setActiveId,
+			focusLoop = false,
+			focusWrap = false,
+			focusShift = false,
+			virtualFocus = false,
+			orientation = 'both',
+			rtl = false,
+
+			// Composite component props
+			children,
+			disabled = false,
+
+			// To be removed
+			store: storeProp,
+
+			// Rest props
+			...props
+		},
+		ref
+	) {
+		const newStore = Ariakit.useCompositeStore( {
+			activeId,
+			defaultActiveId,
+			setActiveId,
+			focusLoop,
+			focusWrap,
+			focusShift,
+			virtualFocus,
+			orientation,
+			rtl,
+		} );
+
+		const store = storeProp || newStore;
+
+		const contextValue = useMemo(
+			() => ( {
+				store,
+			} ),
+			[ store ]
+		);
+
+		return (
+			<Ariakit.Composite
+				disabled={ disabled }
+				store={ store }
+				{ ...props }
+				ref={ ref }
+			>
+				<CompositeContext.Provider value={ contextValue }>
+					{ children }
+				</CompositeContext.Provider>
+			</Ariakit.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: 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
+		 * 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: Object.assign( CompositeGroupLabel, {
+			displayName: '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: 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
+		 * 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: 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
+		 * 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: 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
+		 * 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: 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
+		 * 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: 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 }
+			{ ...props }
+			ref={ ref }
+		/>
+	);
+} );

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,8 @@ import { forwardRef } from '@wordpress/element';
 /**
  * Internal dependencies
  */
-import * as Current from '../current';
+import { Composite as Current } from '..';
+import { useCompositeStore } from '../store';
 import { useInstanceId } from '@wordpress/compose';
 
 type Orientation = 'horizontal' | 'vertical';
@@ -73,7 +79,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 +99,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 +151,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 +180,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/row.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 { CompositeRowProps } from './types';
+
+export const CompositeRow = forwardRef<
+	HTMLDivElement,
+	WordPressComponentProps< CompositeRowProps, 'div', false >
+>( function CompositeRow( props, ref ) {
+	const context = useCompositeContext();
+	return (
+		<Ariakit.CompositeRow
+			store={ context?.store }
+			{ ...props }
+			ref={ ref }
+		/>
+	);
+} );

package/src/composite/store.ts

@@ -0,0 +1,46 @@
+/**
+ * External dependencies
+ */
+import * as Ariakit from '@ariakit/react';
+
+/**
+ * Internal dependencies
+ */
+import type { CompositeStoreProps } from './types';
+
+// Props are already documented in TypeScript types.
+// eslint-disable-next-line jsdoc/require-param
+/**
+ * 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,
+	} );
+}