@wordpress/components 26.0.1-next.5a1d1283.0 → 26.0.1

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

@@ -0,0 +1,61 @@
+/**
+ * External dependencies
+ */
+import type { StoryContext } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import type { CompositeStoreProps } from '..';
+
+export function UseCompositeStorePlaceholder( props: CompositeStoreProps ) {
+	return (
+		<dl>
+			{ Object.entries( props ).map( ( [ name, value ] ) => (
+				<>
+					<dt>{ name }</dt>
+					<dd>{ JSON.stringify( value ) }</dd>
+				</>
+			) ) }
+		</dl>
+	);
+}
+UseCompositeStorePlaceholder.displayName = 'useCompositeStore';
+
+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( ' {} ', '' );
+	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 });`,
+		'',
+		'return (',
+		'  ' +
+			code
+				// The generated output includes a full dump of everything
+				// in the store; the reader probably isn't interested in
+				// what that looks like, so instead we drop all of that
+				// in favor of the store generated above.
+				.replaceAll( /store=\{\{[\s\S]*?\}\}/g, 'store={ store }' )
+				// Now we tidy the output by removing any unnecessary
+				// whitespace...
+				.replaceAll( /<Composite\w+[\s\S]*?>/g, ( match ) =>
+					match.replaceAll( /\s+\s/g, ' ' )
+				)
+				// ...including around <Composite*> children...
+				.replaceAll(
+					/>\s*(\w[\w ]*?)\s*<\//g,
+					( _, value ) => `>${ value }</`
+				)
+				// ...and inside JSX definitions.
+				.replaceAll( '} >', '}>' )
+				// Finally we indent everything to make it more readable.
+				.replaceAll( /\n/g, '\n  ' ),
+		');',
+	].join( '\n' );
+}

package/src/composite/index.ts

@@ -0,0 +1,7 @@
+// Originally this pointed at a Reakit implementation of
+// `Composite`, but we are removing Reakit entirely from the
+// codebase. We will continue to support the Reakit API
+// through the 'legacy' version, which uses Ariakit under
+// the hood.
+
+export * from './legacy';

package/src/composite/legacy/index.tsx

@@ -0,0 +1,191 @@
+/**
+ * Composite is a component that may contain navigable items represented by
+ * CompositeItem. 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
+ */
+
+/**
+ * WordPress dependencies
+ */
+import { forwardRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import * as Current from '../current';
+import { useInstanceId } from '@wordpress/compose';
+
+type Orientation = 'horizontal' | 'vertical';
+
+export interface LegacyStateOptions {
+	/**
+	 * ID that will serve as a base for all the items IDs.
+	 */
+	baseId?: string;
+	/**
+	 * Determines how 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.
+	 *
+	 * @default false
+	 */
+	rtl?: boolean;
+	/**
+	 * 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.
+	 */
+	orientation?: Orientation;
+	/**
+	 * The current focused item `id`.
+	 */
+	currentId?: string;
+	/**
+	 * Determines how focus moves from the start and end of rows and columns.
+	 *
+	 * @default false
+	 */
+	loop?: boolean | Orientation;
+	/**
+	 * If enabled, moving to the next item from the last one in a row or column
+	 * will focus the first item in the next row or column and vice-versa.
+	 *
+	 * ** Has effect only on two-dimensional composites. **
+	 *
+	 * @default false
+	 */
+	wrap?: boolean | Orientation;
+	/**
+	 * If enabled, moving up or down when there's no next item or the next item
+	 * is disabled will shift to the item right before it.
+	 *
+	 * ** Has effect only on two-dimensional composites. **
+	 *
+	 * @default false
+	 */
+	shift?: boolean;
+	unstable_virtual?: boolean;
+}
+
+type Component = React.FunctionComponent< any >;
+
+type CompositeStore = ReturnType< typeof Current.useCompositeStore >;
+type CompositeStoreState = { store: CompositeStore };
+export type CompositeState = CompositeStoreState &
+	Required< Pick< LegacyStateOptions, 'baseId' > >;
+
+// Legacy composite components can either provide state through a
+// single `state` prop, or via individual props, usually through
+// spreading the state generated by `useCompositeState`.
+// That is, `<Composite* { ...state }>`.
+export type CompositeStateProps =
+	| { state: CompositeState }
+	| ( CompositeState & { state?: never } );
+type ComponentProps< C extends Component > = React.ComponentPropsWithRef< C >;
+export type CompositeProps< C extends Component > = ComponentProps< C > &
+	CompositeStateProps;
+type CompositeComponent< C extends Component > = (
+	props: CompositeProps< C >
+) => React.ReactElement;
+type CompositeComponentProps = CompositeState &
+	(
+		| ComponentProps< typeof Current.CompositeGroup >
+		| ComponentProps< typeof Current.CompositeItem >
+		| ComponentProps< typeof Current.CompositeRow >
+	);
+
+function mapLegacyStatePropsToComponentProps(
+	legacyProps: CompositeStateProps
+): CompositeComponentProps {
+	// If a `state` prop is provided, we unpack that; otherwise,
+	// the necessary props are provided directly in `legacyProps`.
+	if ( legacyProps.state ) {
+		const { state, ...rest } = legacyProps;
+		const { store, ...props } =
+			mapLegacyStatePropsToComponentProps( state );
+		return { ...rest, ...props, store };
+	}
+
+	return legacyProps;
+}
+
+function proxyComposite< C extends Component >(
+	ProxiedComponent: C | React.ForwardRefExoticComponent< C >,
+	propMap: Record< string, string > = {}
+): CompositeComponent< C > {
+	const displayName = ProxiedComponent.displayName;
+	const Component = ( legacyProps: CompositeStateProps ) => {
+		const { store, ...rest } =
+			mapLegacyStatePropsToComponentProps( legacyProps );
+		const props = rest as ComponentProps< C >;
+		props.id = useInstanceId( store, props.baseId, props.id );
+
+		Object.entries( propMap ).forEach( ( [ from, to ] ) => {
+			if ( props.hasOwnProperty( from ) ) {
+				Object.assign( props, { [ to ]: props[ from ] } );
+				delete props[ from ];
+			}
+		} );
+
+		delete props.baseId;
+
+		return <ProxiedComponent { ...props } store={ store } />;
+	};
+	Component.displayName = displayName;
+	return Component;
+}
+
+// The old `CompositeGroup` used to behave more like the current
+// `CompositeRow`, but this has been split into two different
+// components. We handle that difference by checking on the
+// provided role, and returning the appropriate component.
+const unproxiedCompositeGroup = forwardRef<
+	any,
+	React.ComponentPropsWithoutRef<
+		typeof Current.CompositeGroup | typeof Current.CompositeRow
+	>
+>( ( { role, ...props }, ref ) => {
+	const Component =
+		role === 'row' ? Current.CompositeRow : Current.CompositeGroup;
+	return <Component ref={ ref } role={ role } { ...props } />;
+} );
+unproxiedCompositeGroup.displayName = 'CompositeGroup';
+
+export const Composite = proxyComposite( Current.Composite, { baseId: 'id' } );
+export const CompositeGroup = proxyComposite( unproxiedCompositeGroup );
+export const CompositeItem = proxyComposite( Current.CompositeItem, {
+	focusable: 'accessibleWhenDisabled',
+} );
+
+export function useCompositeState(
+	legacyStateOptions: LegacyStateOptions = {}
+): CompositeState {
+	const {
+		baseId,
+		currentId: defaultActiveId,
+		orientation,
+		rtl = false,
+		loop: focusLoop = false,
+		wrap: focusWrap = false,
+		shift: focusShift = false,
+		// eslint-disable-next-line camelcase
+		unstable_virtual: virtualFocus,
+	} = legacyStateOptions;
+
+	return {
+		baseId: useInstanceId( Composite, 'composite', baseId ),
+		store: Current.useCompositeStore( {
+			defaultActiveId,
+			rtl,
+			orientation,
+			focusLoop,
+			focusShift,
+			focusWrap,
+			virtualFocus,
+		} ),
+	};
+}

package/src/composite/legacy/stories/index.story.tsx

@@ -0,0 +1,205 @@
+/**
+ * External dependencies
+ */
+import type { Meta, StoryFn } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import {
+	Composite,
+	CompositeGroup,
+	CompositeItem,
+	useCompositeState,
+} from '..';
+import { UseCompositeStatePlaceholder, transform } from './utils';
+
+const meta: Meta< typeof UseCompositeStatePlaceholder > = {
+	title: 'Components/Composite',
+	component: UseCompositeStatePlaceholder,
+	subcomponents: {
+		Composite,
+		CompositeGroup,
+		CompositeItem,
+	},
+	args: {},
+	parameters: {
+		controls: { exclude: /^unstable_/ },
+		docs: {
+			canvas: { sourceState: 'shown' },
+			source: { transform },
+		},
+	},
+	argTypes: {
+		orientation: { control: 'select' },
+		loop: {
+			control: 'select',
+			options: [ true, false, 'horizontal', 'vertical' ],
+		},
+		wrap: {
+			control: 'select',
+			options: [ true, false, 'horizontal', 'vertical' ],
+		},
+	},
+};
+export default meta;
+
+export const TwoDimensionsWithStateProp: StoryFn<
+	typeof UseCompositeStatePlaceholder
+> = ( initialState ) => {
+	const state = useCompositeState( initialState );
+
+	return (
+		<Composite
+			role="grid"
+			state={ state }
+			aria-label="Legacy Composite with state prop (two dimensions)"
+		>
+			<CompositeGroup state={ state } role="row">
+				<CompositeItem state={ state } role="gridcell">
+					Item A1
+				</CompositeItem>
+				<CompositeItem state={ state } role="gridcell">
+					Item A2
+				</CompositeItem>
+				<CompositeItem state={ state } role="gridcell">
+					Item A3
+				</CompositeItem>
+			</CompositeGroup>
+			<CompositeGroup state={ state } role="row">
+				<CompositeItem state={ state } role="gridcell">
+					Item B1
+				</CompositeItem>
+				<CompositeItem state={ state } role="gridcell">
+					Item B2
+				</CompositeItem>
+				<CompositeItem state={ state } role="gridcell">
+					Item B3
+				</CompositeItem>
+			</CompositeGroup>
+			<CompositeGroup state={ state } role="row">
+				<CompositeItem state={ state } role="gridcell">
+					Item C1
+				</CompositeItem>
+				<CompositeItem state={ state } role="gridcell">
+					Item C2
+				</CompositeItem>
+				<CompositeItem state={ state } role="gridcell">
+					Item C3
+				</CompositeItem>
+			</CompositeGroup>
+		</Composite>
+	);
+};
+TwoDimensionsWithStateProp.args = {};
+
+export const TwoDimensionsWithSpreadProps: StoryFn<
+	typeof UseCompositeStatePlaceholder
+> = ( initialState ) => {
+	const state = useCompositeState( initialState );
+
+	return (
+		<Composite
+			role="grid"
+			{ ...state }
+			aria-label="Legacy Composite with spread props (two dimensions)"
+		>
+			<CompositeGroup { ...state } role="row">
+				<CompositeItem { ...state } role="gridcell">
+					Item A1
+				</CompositeItem>
+				<CompositeItem { ...state } role="gridcell">
+					Item A2
+				</CompositeItem>
+				<CompositeItem { ...state } role="gridcell">
+					Item A3
+				</CompositeItem>
+			</CompositeGroup>
+			<CompositeGroup { ...state } role="row">
+				<CompositeItem { ...state } role="gridcell">
+					Item B1
+				</CompositeItem>
+				<CompositeItem { ...state } role="gridcell">
+					Item B2
+				</CompositeItem>
+				<CompositeItem { ...state } role="gridcell">
+					Item B3
+				</CompositeItem>
+			</CompositeGroup>
+			<CompositeGroup { ...state } role="row">
+				<CompositeItem { ...state } role="gridcell">
+					Item C1
+				</CompositeItem>
+				<CompositeItem { ...state } role="gridcell">
+					Item C2
+				</CompositeItem>
+				<CompositeItem { ...state } role="gridcell">
+					Item C3
+				</CompositeItem>
+			</CompositeGroup>
+		</Composite>
+	);
+};
+TwoDimensionsWithSpreadProps.args = {};
+
+export const OneDimensionWithStateProp: StoryFn<
+	typeof UseCompositeStatePlaceholder
+> = ( initialState ) => {
+	const state = useCompositeState( initialState );
+
+	return (
+		<Composite
+			role="list"
+			state={ state }
+			aria-label="Legacy Composite with state prop (one dimension)"
+		>
+			<CompositeItem state={ state } role="listitem">
+				Item 1
+			</CompositeItem>
+			<CompositeItem state={ state } role="listitem">
+				Item 2
+			</CompositeItem>
+			<CompositeItem state={ state } role="listitem">
+				Item 3
+			</CompositeItem>
+			<CompositeItem state={ state } role="listitem">
+				Item 4
+			</CompositeItem>
+			<CompositeItem state={ state } role="listitem">
+				Item 5
+			</CompositeItem>
+		</Composite>
+	);
+};
+OneDimensionWithStateProp.args = {};
+
+export const OneDimensionWithSpreadProps: StoryFn<
+	typeof UseCompositeStatePlaceholder
+> = ( initialState ) => {
+	const state = useCompositeState( initialState );
+
+	return (
+		<Composite
+			role="list"
+			{ ...state }
+			aria-label="Legacy Composite with spread props (one dimension)"
+		>
+			<CompositeItem { ...state } role="listitem">
+				Item 1
+			</CompositeItem>
+			<CompositeItem { ...state } role="listitem">
+				Item 2
+			</CompositeItem>
+			<CompositeItem { ...state } role="listitem">
+				Item 3
+			</CompositeItem>
+			<CompositeItem { ...state } role="listitem">
+				Item 4
+			</CompositeItem>
+			<CompositeItem { ...state } role="listitem">
+				Item 5
+			</CompositeItem>
+		</Composite>
+	);
+};
+OneDimensionWithSpreadProps.args = {};

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

@@ -0,0 +1,67 @@
+/**
+ * External dependencies
+ */
+import type { StoryContext } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import type { LegacyStateOptions } from '..';
+
+export function UseCompositeStatePlaceholder( props: LegacyStateOptions ) {
+	return (
+		<dl>
+			{ Object.entries( props ).map( ( [ name, value ] ) => (
+				<>
+					<dt>{ name }</dt>
+					<dd>{ JSON.stringify( value ) }</dd>
+				</>
+			) ) }
+		</dl>
+	);
+}
+UseCompositeStatePlaceholder.displayName = 'useCompositeState';
+
+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( ' {} ', '' );
+	return [
+		// Include a setup line, showing how to make use of
+		// `useCompositeState` to convert state options into
+		// a composite state option.
+		`const state = useCompositeState(${ state });`,
+		'',
+		'return (',
+		'  ' +
+			code
+				// The generated output includes a full dump of everything
+				// in the state; the reader probably isn't interested in
+				// what that looks like, so instead we drop all of that
+				// in favor of the state generated above.
+				.replaceAll( /state=\{\{[\s\S]*?\}\}/g, 'state={ state }' )
+				// The previous line only works for `state={ state }`, and
+				// doesn't replace spread props, so we do that separately.
+				.replaceAll( '=>', '' )
+				.replaceAll( /baseId=[^>]+?(\s*>)/g, ( _, close ) => {
+					return `{ ...state }${ close }`;
+				} )
+				// Now we tidy the output by removing any unnecessary
+				// whitespace...
+				.replaceAll( /<Composite\w+[\s\S]*?>/g, ( match ) =>
+					match.replaceAll( /\s+\s/g, ' ' )
+				)
+				// ...including around <Composite*> children...
+				.replaceAll(
+					/ >\s+([\w\s]*?)\s+<\//g,
+					( _, value ) => `>${ value }</`
+				)
+				// ...and inside JSX definitions.
+				.replaceAll( '} >', '}>' )
+				// Finally we indent everything to make it more readable.
+				.replaceAll( /\n/g, '\n  ' ),
+		');',
+	].join( '\n' );
+}