@wordpress/components 28.5.0 → 28.6.0

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/stories/index.story.tsx

@@ -0,0 +1,466 @@
+/**
+ * External dependencies
+ */
+import type { Meta, StoryFn } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { isRTL } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import { Composite, useCompositeStore } from '..';
+import { UseCompositeStorePlaceholder, transform } from './utils';
+
+const meta: Meta< typeof UseCompositeStorePlaceholder > = {
+	title: 'Components/Composite (V2)',
+	component: UseCompositeStorePlaceholder,
+	subcomponents: {
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		Composite,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		'Composite.Group': Composite.Group,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		'Composite.GroupLabel': Composite.GroupLabel,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		'Composite.Row': Composite.Row,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		'Composite.Item': Composite.Item,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		'Composite.Hover': Composite.Hover,
+		// @ts-expect-error - See https://github.com/storybookjs/storybook/issues/23170
+		'Composite.Typeahead': Composite.Typeahead,
+	},
+	argTypes: {
+		activeId: { control: 'text' },
+		defaultActiveId: { control: 'text' },
+		setActiveId: { control: { type: null } },
+		focusLoop: {
+			control: 'select',
+			options: [ true, false, 'horizontal', 'vertical', 'both' ],
+		},
+		focusShift: { control: 'boolean' },
+		focusWrap: { control: 'boolean' },
+		virtualFocus: { control: 'boolean' },
+		rtl: { control: 'boolean' },
+		orientation: {
+			control: 'select',
+			options: [ 'horizontal', 'vertical', 'both' ],
+		},
+	},
+	tags: [ 'status-private' ],
+	parameters: {
+		controls: { expanded: true },
+		docs: {
+			canvas: { sourceState: 'shown' },
+			source: { transform },
+			extractArgTypes: ( component: React.FunctionComponent ) => {
+				const commonArgTypes = {
+					render: {
+						name: 'render',
+						description:
+							'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.',
+						table: {
+							type: {
+								summary:
+									'RenderProp<React.HTMLAttributes<any> & { ref?: React.Ref<any> | undefined; }> | React.ReactElement<any, string | React.JSXElementConstructor<any>>',
+							},
+						},
+					},
+					children: {
+						name: 'children',
+						description: 'The contents of the component.',
+						table: { type: { summary: 'React.ReactNode' } },
+					},
+				};
+				const accessibleWhenDisabled = {
+					name: 'accessibleWhenDisabled',
+					description: `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).`,
+					table: {
+						type: {
+							summary: 'boolean',
+						},
+					},
+				};
+
+				const argTypes = {
+					useCompositeStore: {
+						activeId: {
+							name: 'activeId',
+							description: `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.`,
+							table: { type: { summary: 'string | null' } },
+						},
+						defaultActiveId: {
+							name: 'defaultActiveId',
+							description:
+								'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.',
+							table: { type: { summary: 'string | null' } },
+						},
+						setActiveId: {
+							name: 'setActiveId',
+							description:
+								'A callback that gets called when the `activeId` state changes.',
+							table: {
+								type: {
+									summary:
+										'((activeId: string | null | undefined) => void)',
+								},
+							},
+						},
+						focusLoop: {
+							name: 'focusLoop',
+							description: `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.`,
+							table: {
+								defaultValue: {
+									summary: 'false',
+								},
+								type: {
+									summary:
+										"boolean | 'horizontal' | 'vertical' | 'both'",
+								},
+							},
+						},
+						focusShift: {
+							name: 'focusShift',
+							description: `**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.`,
+							table: {
+								defaultValue: {
+									summary: 'false',
+								},
+								type: {
+									summary: 'boolean',
+								},
+							},
+						},
+						focusWrap: {
+							name: 'focusWrap',
+							description: `**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.`,
+							table: {
+								defaultValue: {
+									summary: 'false',
+								},
+								type: {
+									summary: 'boolean',
+								},
+							},
+						},
+						virtualFocus: {
+							name: 'virtualFocus',
+							description: `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.`,
+							table: {
+								defaultValue: {
+									summary: 'false',
+								},
+								type: {
+									summary: 'boolean',
+								},
+							},
+						},
+						orientation: {
+							name: 'orientation',
+							description: `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.`,
+							table: {
+								defaultValue: {
+									summary: "'both'",
+								},
+								type: {
+									summary:
+										"'horizontal' | 'vertical' | 'both'",
+								},
+							},
+						},
+						rtl: {
+							name: 'rtl',
+							description: `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.`,
+							table: {
+								defaultValue: {
+									summary: 'false',
+								},
+								type: {
+									summary: 'boolean',
+								},
+							},
+						},
+					},
+					Composite: {
+						...commonArgTypes,
+						store: {
+							name: 'store',
+							description:
+								'Object returned by the `useCompositeStore` hook.',
+							table: {
+								type: {
+									summary:
+										'CompositeStore<CompositeStoreItem>',
+								},
+							},
+							type: { required: true },
+						},
+						focusable: {
+							name: 'focusable',
+							description: `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.`,
+							table: {
+								type: {
+									summary: 'boolean',
+								},
+							},
+						},
+						disabled: {
+							name: 'disabled',
+							description: `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.`,
+							table: {
+								defaultValue: {
+									summary: 'false',
+								},
+								type: {
+									summary: 'boolean',
+								},
+							},
+						},
+						accessibleWhenDisabled,
+						onFocusVisible: {
+							name: 'onFocusVisible',
+							description: `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.`,
+							table: {
+								type: {
+									summary:
+										'(event: SyntheticEvent<HTMLElement>) => void',
+								},
+							},
+						},
+					},
+					'Composite.Group': commonArgTypes,
+					'Composite.GroupLabel': commonArgTypes,
+					'Composite.Row': commonArgTypes,
+					'Composite.Item': {
+						...commonArgTypes,
+						accessibleWhenDisabled,
+					},
+					'Composite.Hover': commonArgTypes,
+					'Composite.Typeahead': commonArgTypes,
+				};
+
+				const name = component.displayName ?? '';
+
+				return name in argTypes
+					? argTypes[ name as keyof typeof argTypes ]
+					: {};
+			},
+		},
+	},
+	decorators: [
+		( Story ) => {
+			return (
+				<>
+					{ /* Visually style the active composite item  */ }
+					<style>{ `
+						[data-active-item] {
+							background-color: #ffc0b5;
+						}
+					` }</style>
+					<Story />
+					<div
+						style={ {
+							marginTop: '2em',
+							fontSize: '12px',
+							fontStyle: 'italic',
+						} }
+					>
+						{ /* eslint-disable-next-line no-restricted-syntax */ }
+						<p id="list-title">Notes</p>
+						<ul aria-labelledby="list-title">
+							<li>
+								The active composite item is highlighted with a
+								different background color;
+							</li>
+							<li>
+								A composite item can be the active item even
+								when it doesn&apos;t have keyboard focus.
+							</li>
+						</ul>
+					</div>
+				</>
+			);
+		},
+	],
+};
+export default meta;
+
+export const Default: StoryFn< typeof UseCompositeStorePlaceholder > = (
+	storeProps
+) => {
+	const rtl = isRTL();
+	const store = useCompositeStore( { rtl, ...storeProps } );
+
+	return (
+		<Composite store={ store }>
+			<Composite.Item>Item one</Composite.Item>
+			<Composite.Item>Item two</Composite.Item>
+			<Composite.Item>Item three</Composite.Item>
+		</Composite>
+	);
+};
+
+export const Groups: StoryFn< typeof UseCompositeStorePlaceholder > = (
+	storeProps
+) => {
+	const rtl = isRTL();
+	const store = useCompositeStore( { rtl, ...storeProps } );
+
+	return (
+		<Composite store={ store }>
+			<Composite.Group>
+				<Composite.GroupLabel>Group one</Composite.GroupLabel>
+				<Composite.Item>Item 1.1</Composite.Item>
+				<Composite.Item>Item 1.2</Composite.Item>
+			</Composite.Group>
+			<Composite.Group>
+				<Composite.GroupLabel>Group two</Composite.GroupLabel>
+				<Composite.Item>Item 2.1</Composite.Item>
+				<Composite.Item>Item 2.1</Composite.Item>
+			</Composite.Group>
+		</Composite>
+	);
+};
+
+export const Grid: StoryFn< typeof UseCompositeStorePlaceholder > = (
+	storeProps
+) => {
+	const rtl = isRTL();
+	const store = useCompositeStore( { rtl, ...storeProps } );
+
+	return (
+		<Composite role="grid" store={ store } aria-label="Composite">
+			<Composite.Row role="row">
+				<Composite.Item role="gridcell">Item A1</Composite.Item>
+				<Composite.Item role="gridcell">Item A2</Composite.Item>
+				<Composite.Item role="gridcell">Item A3</Composite.Item>
+			</Composite.Row>
+			<Composite.Row role="row">
+				<Composite.Item role="gridcell">Item B1</Composite.Item>
+				<Composite.Item role="gridcell">Item B2</Composite.Item>
+				<Composite.Item role="gridcell">Item B3</Composite.Item>
+			</Composite.Row>
+			<Composite.Row role="row">
+				<Composite.Item role="gridcell">Item C1</Composite.Item>
+				<Composite.Item role="gridcell">Item C2</Composite.Item>
+				<Composite.Item role="gridcell">Item C3</Composite.Item>
+			</Composite.Row>
+		</Composite>
+	);
+};
+
+export const Hover: StoryFn< typeof UseCompositeStorePlaceholder > = (
+	storeProps
+) => {
+	const rtl = isRTL();
+	const store = useCompositeStore( { rtl, ...storeProps } );
+
+	return (
+		<Composite store={ store }>
+			<Composite.Hover render={ <Composite.Item /> }>
+				Hover item one
+			</Composite.Hover>
+			<Composite.Hover render={ <Composite.Item /> }>
+				Hover item two
+			</Composite.Hover>
+			<Composite.Hover render={ <Composite.Item /> }>
+				Hover item three
+			</Composite.Hover>
+		</Composite>
+	);
+};
+Hover.parameters = {
+	docs: {
+		description: {
+			story: 'Elements in the composite widget will receive focus on mouse move and lose focus to the composite base element on mouse leave.',
+		},
+	},
+};
+
+export const Typeahead: StoryFn< typeof UseCompositeStorePlaceholder > = (
+	storeProps
+) => {
+	const rtl = isRTL();
+	const store = useCompositeStore( { rtl, ...storeProps } );
+
+	return (
+		<Composite store={ store } render={ <Composite.Typeahead /> }>
+			<Composite.Item>Apple</Composite.Item>
+			<Composite.Item>Banana</Composite.Item>
+			<Composite.Item>Peach</Composite.Item>
+		</Composite>
+	);
+};
+Typeahead.parameters = {
+	docs: {
+		description: {
+			story: 'When focus in on the composite widget, hitting printable character keys will move focus to the next composite item that begins with the input characters.',
+		},
+	},
+};

package/src/composite/{current/stories → stories}/utils.tsx

@@ -6,8 +6,23 @@ import type { StoryContext } from '@storybook/react';
 /**
  * Internal dependencies
  */
-import type { CompositeStoreProps } from '..';
+import type { CompositeStoreProps } 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.
+ *
+ * ```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 function UseCompositeStorePlaceholder( props: CompositeStoreProps ) {
 	return (
 		<dl>
@@ -22,17 +37,17 @@ export function UseCompositeStorePlaceholder( props: CompositeStoreProps ) {
 }
 UseCompositeStorePlaceholder.displayName = 'useCompositeStore';
 
+// The output generated by Storybook for these components is
+// messy, so we apply this transform to make it more useful
+// for anyone reading the docs.
 export function transform( code: string, context: StoryContext ) {
-	// The output generated by Storybook for these components is
-	// messy, so we apply this transform to make it more useful
-	// for anyone reading the docs.
-	const config = ` ${ JSON.stringify( context.args, null, 2 ) } `;
-	const state = config.replace( ' {} ', '' );
+	const storeConfig = ` ${ JSON.stringify( context.args, null, 2 ) } `;
+	const formattedStoreConfig = storeConfig.replace( ' {} ', '' );
 	return [
 		// Include a setup line, showing how to make use of
 		// `useCompositeStore` to convert store options into
 		// a composite store prop.
-		`const store = useCompositeStore(${ state });`,
+		`const store = useCompositeStore(${ formattedStoreConfig });`,
 		'',
 		'return (',
 		'  ' +