@wordpress/components 28.5.0 → 28.6.0

package/src/composite/README.md

@@ -0,0 +1,325 @@
+# `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';
+
+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>
+```
+
+## Hooks
+
+### `useCompositeStore`
+
+Creates a composite store.
+
+#### Props
+
+##### `activeId`: `string | null`
+
+The current active item `id`. The active item is the element within the composite widget that has either DOM or virtual focus (in case the `virtualFocus` prop is enabled).
+
+-   `null` represents the base composite element (the one with a [composite role](https://w3c.github.io/aria/#composite)). Users will be able to navigate out of it using arrow keys.
+-   If `activeId` is initially set to `null`, the base composite element itself will have focus and users will be able to navigate to it using arrow keys.
+
+-   Required: no
+
+##### `defaultActiveId`: `string | null`
+
+The composite item id that should be active by default when the composite widget is rendered. If `null`, the composite element itself will have focus and users will be able to navigate to it using arrow keys. If `undefined`, the first enabled item will be focused.
+
+-   Required: no
+
+##### `setActiveId`: `((activeId: string | null | undefined) => void)`
+
+A callback that gets called when the `activeId` state changes.
+
+-   Required: no
+
+##### `focusLoop`: `boolean | 'horizontal' | 'vertical' | 'both'`
+
+Determines how the focus behaves when the user reaches the end of the composite widget.
+
+On one-dimensional composite widgets:
+
+-   `true` loops from the last item to the first item and vice-versa.
+-   `horizontal` loops only if `orientation` is `horizontal` or not set.
+-   `vertical` loops only if `orientation` is `vertical` or not set.
+-   If `activeId` is initially set to `null`, the composite element will be focused in between the last and first items.
+
+On two-dimensional composite widgets (ie. when using `CompositeRow`):
+
+-   `true` loops from the last row/column item to the first item in the same row/column and vice-versa. If it's the last item in the last row, it moves to the first item in the first row and vice-versa.
+-   `horizontal` loops only from the last row item to the first item in the same row.
+-   `vertical` loops only from the last column item to the first item in the column row.
+-   If `activeId` is initially set to `null`, vertical loop will have no effect as moving down from the last row or up from the first row will focus on the composite element.
+-   If `focusWrap` matches the value of `focusLoop`, it'll wrap between the last item in the last row or column and the first item in the first row or column and vice-versa.
+
+-   Required: no
+-   Default: `false`
+
+##### `focusShift`: `boolean`
+
+**Works only on two-dimensional composite widgets**.
+
+If enabled, moving up or down when there's no next item or when the next item is disabled will shift to the item right before it.
+
+-   Required: no
+-   Default: `false`
+
+##### `focusWrap`: `boolean`
+
+**Works only on two-dimensional composite widgets**.
+
+If enabled, moving to the next item from the last one in a row or column
+will focus on the first item in the next row or column and vice-versa.
+
+-   `true` wraps between rows and columns.
+-   `horizontal` wraps only between rows.
+-   `vertical` wraps only between columns.
+-   If `focusLoop` matches the value of `focusWrap`, it'll wrap between the
+    last item in the last row or column and the first item in the first row or
+    column and vice-versa.
+
+-   Required: no
+-   Default: `false`
+
+##### `virtualFocus`: `boolean`
+
+If enabled, the composite element will act as an [`aria-activedescendant`](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_focus_activedescendant)
+container instead of [roving tabindex](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#kbd_roving_tabindex). DOM focus will remain on the composite element while its items receive
+virtual focus.
+
+In both scenarios, the item in focus will carry the `data-active-item` attribute.
+
+-   Required: no
+-   Default: `false`
+
+##### `orientation`: `'horizontal' | 'vertical' | 'both'`
+
+Defines the orientation of the composite widget. If the composite has a single row or column (one-dimensional), the `orientation` value determines which arrow keys can be used to move focus:
+
+-   `both`: all arrow keys work.
+-   `horizontal`: only left and right arrow keys work.
+-   `vertical`: only up and down arrow keys work.
+
+It doesn't have any effect on two-dimensional composites.
+
+-   Required: no
+-   Default: `both`
+
+##### `rtl`: `boolean`
+
+Determines how the `store`'s `next` and `previous` functions will behave. If `rtl` is set to `true`, they will be inverted.
+
+This only affects the composite widget behavior. You still need to set `dir="rtl"` on HTML/CSS.
+
+-   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.
+
+-   Required: no
+
+##### `focusable`: `boolean`
+
+Makes the component a focusable element. When this element gains keyboard focus, it gets a `data-focus-visible` attribute and triggers the `onFocusVisible` prop.
+
+The component supports the `disabled` prop even for those elements not supporting the native `disabled` attribute. Disabled elements may be still accessible via keyboard by using the the `accessibleWhenDisabled` prop.
+
+Non-native focusable elements will lose their focusability entirely. However, native focusable elements will retain their inherent focusability.
+
+-   Required: no
+
+##### `disabled`: `boolean`
+
+Determines if the element is disabled. This sets the `aria-disabled` attribute accordingly, enabling support for all elements, including those that don't support the native `disabled` attribute.
+
+This feature can be combined with the `accessibleWhenDisabled` prop to
+make disabled elements still accessible via keyboard.
+
+**Note**: For this prop to work, the `focusable` prop must be set to
+`true`, if it's not set by default.
+
+-   Required: no
+-   Default: `false`
+
+##### `accessibleWhenDisabled`: `boolean`
+
+Indicates whether the element should be focusable even when it is
+`disabled`.
+
+This is important when discoverability is a concern. For example:
+
+> A toolbar in an editor contains a set of special smart paste functions
+> that are disabled when the clipboard is empty or when the function is not
+> applicable to the current content of the clipboard. It could be helpful to
+> keep the disabled buttons focusable if the ability to discover their
+> functionality is primarily via their presence on the toolbar.
+
+Learn more on [Focusability of disabled
+controls](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#focusabilityofdisabledcontrols).
+
+-   Required: no
+
+##### `onFocusVisible`: `(event: SyntheticEvent<HTMLElement>) => void`
+
+Custom event handler invoked when the element gains focus through keyboard interaction or a key press occurs while the element is in focus. This is the programmatic equivalent of the `data-focus-visible` attribute.
+
+**Note**: For this prop to work, the `focusable` prop must be set to `true` if it's not set by default.
+
+-   Required: no
+
+##### `children`: `React.ReactNode`
+
+The contents of the component.
+
+-   Required: no
+
+### `Composite.Group`
+
+Renders a group element for composite items.
+
+##### `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.
+
+-   Required: no
+
+##### `children`: `React.ReactNode`
+
+The contents of the component.
+
+-   Required: no
+
+### `Composite.GroupLabel`
+
+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.
+
+##### `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.
+
+-   Required: no
+
+##### `children`: `React.ReactNode`
+
+The contents of the component.
+
+-   Required: no
+
+### `Composite.Item`
+
+Renders a composite item.
+
+##### `accessibleWhenDisabled`: `boolean`
+
+Indicates whether the element should be focusable even when it is
+`disabled`.
+
+This is important when discoverability is a concern. For example:
+
+> A toolbar in an editor contains a set of special smart paste functions
+> that are disabled when the clipboard is empty or when the function is not
+> applicable to the current content of the clipboard. It could be helpful to
+> keep the disabled buttons focusable if the ability to discover their
+> functionality is primarily via their presence on the toolbar.
+
+Learn more on [Focusability of disabled
+controls](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/#focusabilityofdisabledcontrols).
+
+-   Required: no
+
+##### `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.
+
+-   Required: no
+
+##### `children`: `React.ReactNode`
+
+The contents of the component.
+
+-   Required: no
+
+### `Composite.Row`
+
+Renders a composite row. Wrapping `Composite.Item` elements within `Composite.Row` will create a two-dimensional composite widget, such as a grid.
+
+##### `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.
+
+-   Required: no
+
+##### `children`: `React.ReactNode`
+
+The contents of the component.
+
+-   Required: no
+
+### `Composite.Hover`
+
+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.
+
+##### `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.
+
+-   Required: no
+
+##### `children`: `React.ReactNode`
+
+The contents of the component.
+
+-   Required: no
+
+### `Composite.Typeahead`
+
+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.
+
+##### `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.
+
+-   Required: no
+
+##### `children`: `React.ReactNode`
+
+The contents of the component.
+
+-   Required: no
+
+### `Composite.Context`
+
+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.

package/src/composite/context.ts

@@ -0,0 +1,14 @@
+/**
+ * WordPress dependencies
+ */
+import { createContext, useContext } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { CompositeContextProps } from './types';
+
+export const CompositeContext =
+	createContext< CompositeContextProps >( undefined );
+
+export const useCompositeContext = () => useContext( CompositeContext );

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,
+	}
+);