@wordpress/components 25.6.1 → 25.8.0

package/src/circular-option-picker/README.md

@@ -80,6 +80,20 @@ The child elements.
 
 - Required: No
 
+### `asButtons`: `boolean`
+
+Whether the control should present as a set of buttons, each with its own tab stop.
+
+- Required: No
+- Default: `false`
+
+### `loop`: `boolean`
+
+Prevents keyboard interaction from wrapping around. Only used when `asButtons` is not true.
+
+- Required: No
+- Default: `true`
+
 ## Subcomponents
 
 ### `CircularOptionPicker.ButtonAction`

package/src/circular-option-picker/circular-option-picker-actions.tsx

@@ -0,0 +1,60 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+
+/**
+ * Internal dependencies
+ */
+import Button from '../button';
+import Dropdown from '../dropdown';
+import type { DropdownLinkActionProps } from './types';
+import type { WordPressComponentProps } from '../ui/context';
+import type { ButtonAsButtonProps } from '../button/types';
+
+export function DropdownLinkAction( {
+	buttonProps,
+	className,
+	dropdownProps,
+	linkText,
+}: DropdownLinkActionProps ) {
+	return (
+		<Dropdown
+			className={ classnames(
+				'components-circular-option-picker__dropdown-link-action',
+				className
+			) }
+			renderToggle={ ( { isOpen, onToggle } ) => (
+				<Button
+					aria-expanded={ isOpen }
+					aria-haspopup="true"
+					onClick={ onToggle }
+					variant="link"
+					{ ...buttonProps }
+				>
+					{ linkText }
+				</Button>
+			) }
+			{ ...dropdownProps }
+		/>
+	);
+}
+
+export function ButtonAction( {
+	className,
+	children,
+	...additionalProps
+}: WordPressComponentProps< ButtonAsButtonProps, 'button', false > ) {
+	return (
+		<Button
+			className={ classnames(
+				'components-circular-option-picker__clear',
+				className
+			) }
+			variant="tertiary"
+			{ ...additionalProps }
+		>
+			{ children }
+		</Button>
+	);
+}

package/src/circular-option-picker/circular-option-picker-context.tsx

@@ -0,0 +1,12 @@
+/**
+ * WordPress dependencies
+ */
+import { createContext } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import type { CircularOptionPickerContextProps } from './types';
+
+export const CircularOptionPickerContext =
+	createContext< CircularOptionPickerContextProps >( {} );

package/src/circular-option-picker/circular-option-picker-option-group.tsx

@@ -0,0 +1,34 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+
+/**
+ * Internal dependencies
+ */
+import type { OptionGroupProps } from './types';
+
+export function OptionGroup( {
+	className,
+	options,
+	...additionalProps
+}: OptionGroupProps ) {
+	const role =
+		'aria-label' in additionalProps || 'aria-labelledby' in additionalProps
+			? 'group'
+			: undefined;
+
+	return (
+		<div
+			{ ...additionalProps }
+			role={ role }
+			className={ classnames(
+				'components-circular-option-picker__option-group',
+				'components-circular-option-picker__swatches',
+				className
+			) }
+		>
+			{ options }
+		</div>
+	);
+}

package/src/circular-option-picker/circular-option-picker-option.tsx

@@ -0,0 +1,139 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+import type { ForwardedRef } from 'react';
+
+/**
+ * WordPress dependencies
+ */
+import { useInstanceId } from '@wordpress/compose';
+import { forwardRef, useContext, useEffect } from '@wordpress/element';
+import { Icon, check } from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import { CircularOptionPickerContext } from './circular-option-picker-context';
+import Button from '../button';
+import { CompositeItem } from '../composite';
+import Tooltip from '../tooltip';
+import type {
+	OptionProps,
+	CircularOptionPickerCompositeState,
+	CircularOptionPickerContextProps,
+} from './types';
+
+const hasSelectedOption = new Map();
+
+function UnforwardedOptionAsButton(
+	props: {
+		id?: string;
+		className?: string;
+		isPressed?: boolean;
+	},
+	forwardedRef: ForwardedRef< any >
+) {
+	return <Button { ...props } ref={ forwardedRef }></Button>;
+}
+
+const OptionAsButton = forwardRef( UnforwardedOptionAsButton );
+
+function UnforwardedOptionAsOption(
+	props: {
+		id: string;
+		className?: string;
+		isSelected?: boolean;
+		context: CircularOptionPickerContextProps;
+	},
+	forwardedRef: ForwardedRef< any >
+) {
+	const { id, className, isSelected, context, ...additionalProps } = props;
+	const { isComposite, ..._compositeState } = context;
+	const compositeState =
+		_compositeState as CircularOptionPickerCompositeState;
+	const { baseId, currentId, setCurrentId } = compositeState;
+
+	useEffect( () => {
+		// If we call `setCurrentId` here, it doesn't update for other
+		// Option renders in the same pass. So we have to store our own
+		// map to make sure that we only set the first selected option.
+		// We still need to check `currentId` because the control will
+		// update this as the user moves around, and that state should
+		// be maintained as the group gains and loses focus.
+		if ( isSelected && ! currentId && ! hasSelectedOption.get( baseId ) ) {
+			hasSelectedOption.set( baseId, true );
+			setCurrentId( id );
+		}
+	}, [ baseId, currentId, id, isSelected, setCurrentId ] );
+
+	return (
+		<CompositeItem
+			{ ...additionalProps }
+			{ ...compositeState }
+			as={ Button }
+			id={ id }
+			// Ideally we'd let the underlying `Button` component
+			// handle this by passing `isPressed` as a prop.
+			// Unfortunately doing so also sets `aria-pressed` as
+			// an attribute on the element, which is incompatible
+			// with `role="option"`, and there is no way at this
+			// point to override that behaviour.
+			className={ classnames( className, {
+				'is-pressed': isSelected,
+			} ) }
+			role="option"
+			aria-selected={ !! isSelected }
+			ref={ forwardedRef }
+		/>
+	);
+}
+
+const OptionAsOption = forwardRef( UnforwardedOptionAsOption );
+
+export function Option( {
+	className,
+	isSelected,
+	selectedIconProps = {},
+	tooltipText,
+	...additionalProps
+}: OptionProps ) {
+	const compositeContext = useContext( CircularOptionPickerContext );
+	const { isComposite, baseId } = compositeContext;
+	const id = useInstanceId(
+		Option,
+		baseId || 'components-circular-option-picker__option'
+	);
+
+	const commonProps = {
+		id,
+		className: 'components-circular-option-picker__option',
+		...additionalProps,
+	};
+
+	const optionControl = isComposite ? (
+		<OptionAsOption
+			{ ...commonProps }
+			context={ compositeContext }
+			isSelected={ isSelected }
+		/>
+	) : (
+		<OptionAsButton { ...commonProps } isPressed={ isSelected } />
+	);
+
+	return (
+		<div
+			className={ classnames(
+				className,
+				'components-circular-option-picker__option-wrapper'
+			) }
+		>
+			{ tooltipText ? (
+				<Tooltip text={ tooltipText }>{ optionControl }</Tooltip>
+			) : (
+				optionControl
+			) }
+			{ isSelected && <Icon icon={ check } { ...selectedIconProps } /> }
+		</div>
+	);
+}

package/src/circular-option-picker/circular-option-picker.tsx

@@ -0,0 +1,202 @@
+/**
+ * External dependencies
+ */
+import classnames from 'classnames';
+
+/**
+ * WordPress dependencies
+ */
+import { useInstanceId } from '@wordpress/compose';
+import { useEffect } from '@wordpress/element';
+import { isRTL } from '@wordpress/i18n';
+
+/**
+ * Internal dependencies
+ */
+import { CircularOptionPickerContext } from './circular-option-picker-context';
+import { Composite, useCompositeState } from '../composite';
+import type {
+	CircularOptionPickerProps,
+	ListboxCircularOptionPickerProps,
+	ButtonsCircularOptionPickerProps,
+} from './types';
+import { Option } from './circular-option-picker-option';
+import { OptionGroup } from './circular-option-picker-option-group';
+import {
+	ButtonAction,
+	DropdownLinkAction,
+} from './circular-option-picker-actions';
+
+/**
+ *`CircularOptionPicker` is a component that displays a set of options as circular buttons.
+ *
+ * ```jsx
+ * import { CircularOptionPicker } from '../circular-option-picker';
+ * import { useState } from '@wordpress/element';
+ *
+ * const Example = () => {
+ * 	const [ currentColor, setCurrentColor ] = useState();
+ * 	const colors = [
+ * 		{ color: '#f00', name: 'Red' },
+ * 		{ color: '#0f0', name: 'Green' },
+ * 		{ color: '#00f', name: 'Blue' },
+ * 	];
+ * 	const colorOptions = (
+ * 		<>
+ * 			{ colors.map( ( { color, name }, index ) => {
+ * 				return (
+ * 					<CircularOptionPicker.Option
+ * 						key={ `${ color }-${ index }` }
+ * 						tooltipText={ name }
+ * 						style={ { backgroundColor: color, color } }
+ * 						isSelected={ index === currentColor }
+ * 						onClick={ () => setCurrentColor( index ) }
+ * 						aria-label={ name }
+ * 					/>
+ * 				);
+ * 			} ) }
+ * 		</>
+ * 	);
+ * 	return (
+ * 		<CircularOptionPicker
+ * 				options={ colorOptions }
+ * 				actions={
+ * 					<CircularOptionPicker.ButtonAction
+ * 						onClick={ () => setCurrentColor( undefined ) }
+ * 					>
+ * 						{ 'Clear' }
+ * 					</CircularOptionPicker.ButtonAction>
+ * 				}
+ * 			/>
+ * 	);
+ * };
+ * ```
+ */
+
+function ListboxCircularOptionPicker(
+	props: ListboxCircularOptionPickerProps
+) {
+	const {
+		actions,
+		options,
+		baseId,
+		className,
+		loop = true,
+		children,
+		...additionalProps
+	} = props;
+	const rtl = isRTL();
+
+	const compositeState = useCompositeState( { baseId, loop, rtl } );
+	const { setBaseId, setLoop, setRTL } = compositeState;
+
+	// These are necessary as `useCompositeState` is sealed after
+	// the first render, so although unlikely to happen, if a state
+	// property should change, we need to process it accordingly.
+
+	useEffect( () => {
+		setBaseId( baseId );
+	}, [ setBaseId, baseId ] );
+
+	useEffect( () => {
+		setLoop( loop );
+	}, [ setLoop, loop ] );
+
+	useEffect( () => {
+		setRTL( rtl );
+	}, [ setRTL, rtl ] );
+
+	const compositeContext = {
+		isComposite: true,
+		...compositeState,
+	};
+
+	return (
+		<div className={ className }>
+			<CircularOptionPickerContext.Provider value={ compositeContext }>
+				<Composite
+					{ ...additionalProps }
+					{ ...compositeState }
+					role={ 'listbox' }
+				>
+					{ options }
+				</Composite>
+				{ children }
+				{ actions }
+			</CircularOptionPickerContext.Provider>
+		</div>
+	);
+}
+
+function ButtonsCircularOptionPicker(
+	props: ButtonsCircularOptionPickerProps
+) {
+	const { actions, options, children, baseId, ...additionalProps } = props;
+
+	return (
+		<div { ...additionalProps }>
+			<CircularOptionPickerContext.Provider
+				value={ { isComposite: false, baseId } }
+			>
+				{ options }
+				{ children }
+				{ actions }
+			</CircularOptionPickerContext.Provider>
+		</div>
+	);
+}
+
+function CircularOptionPicker( props: CircularOptionPickerProps ) {
+	const {
+		asButtons,
+		actions: actionsProp,
+		options: optionsProp,
+		children,
+		className,
+		...additionalProps
+	} = props;
+
+	const baseId = useInstanceId(
+		CircularOptionPicker,
+		'components-circular-option-picker',
+		additionalProps.id
+	);
+
+	const OptionPickerImplementation = asButtons
+		? ButtonsCircularOptionPicker
+		: ListboxCircularOptionPicker;
+
+	const actions = actionsProp ? (
+		<div className="components-circular-option-picker__custom-clear-wrapper">
+			{ actionsProp }
+		</div>
+	) : undefined;
+
+	const options = (
+		<div className={ 'components-circular-option-picker__swatches' }>
+			{ optionsProp }
+		</div>
+	);
+
+	return (
+		<OptionPickerImplementation
+			{ ...additionalProps }
+			baseId={ baseId }
+			className={ classnames(
+				'components-circular-option-picker',
+				className
+			) }
+			actions={ actions }
+			options={ options }
+		>
+			{ children }
+		</OptionPickerImplementation>
+	);
+}
+
+CircularOptionPicker.Option = Option;
+CircularOptionPicker.OptionGroup = OptionGroup;
+CircularOptionPicker.ButtonAction = ButtonAction;
+CircularOptionPicker.DropdownLinkAction = DropdownLinkAction;
+
+export default CircularOptionPicker;

package/src/circular-option-picker/index.tsx

@@ -1,180 +1,13 @@
-/**
- * External dependencies
- */
-import classnames from 'classnames';
-
-/**
- * WordPress dependencies
- */
-import { Icon, check } from '@wordpress/icons';
-
 /**
  * Internal dependencies
  */
-import Button from '../button';
-import Dropdown from '../dropdown';
-import Tooltip from '../tooltip';
-import type {
-	CircularOptionPickerProps,
-	DropdownLinkActionProps,
-	OptionProps,
-} from './types';
-import type { WordPressComponentProps } from '../ui/context';
-import type { ButtonAsButtonProps } from '../button/types';
-
-export function Option( {
-	className,
-	isSelected,
-	selectedIconProps,
-	tooltipText,
-	...additionalProps
-}: OptionProps ) {
-	const optionButton = (
-		<Button
-			isPressed={ isSelected }
-			className="components-circular-option-picker__option"
-			{ ...additionalProps }
-		/>
-	);
-	return (
-		<div
-			className={ classnames(
-				className,
-				'components-circular-option-picker__option-wrapper'
-			) }
-		>
-			{ tooltipText ? (
-				<Tooltip text={ tooltipText }>{ optionButton }</Tooltip>
-			) : (
-				optionButton
-			) }
-			{ isSelected && (
-				<Icon
-					icon={ check }
-					{ ...( selectedIconProps ? selectedIconProps : {} ) }
-				/>
-			) }
-		</div>
-	);
-}
-
-export function DropdownLinkAction( {
-	buttonProps,
-	className,
-	dropdownProps,
-	linkText,
-}: DropdownLinkActionProps ) {
-	return (
-		<Dropdown
-			className={ classnames(
-				'components-circular-option-picker__dropdown-link-action',
-				className
-			) }
-			renderToggle={ ( { isOpen, onToggle } ) => (
-				<Button
-					aria-expanded={ isOpen }
-					aria-haspopup="true"
-					onClick={ onToggle }
-					variant="link"
-					{ ...buttonProps }
-				>
-					{ linkText }
-				</Button>
-			) }
-			{ ...dropdownProps }
-		/>
-	);
-}
-
-export function ButtonAction( {
-	className,
-	children,
-	...additionalProps
-}: WordPressComponentProps< ButtonAsButtonProps, 'button', false > ) {
-	return (
-		<Button
-			className={ classnames(
-				'components-circular-option-picker__clear',
-				className
-			) }
-			variant="tertiary"
-			{ ...additionalProps }
-		>
-			{ children }
-		</Button>
-	);
-}
-
-/**
- *`CircularOptionPicker` is a component that displays a set of options as circular buttons.
- *
- * ```jsx
- * import { CircularOptionPicker } from '../circular-option-picker';
- * import { useState } from '@wordpress/element';
- *
- * const Example = () => {
- * 	const [ currentColor, setCurrentColor ] = useState();
- * 	const colors = [
- * 		{ color: '#f00', name: 'Red' },
- * 		{ color: '#0f0', name: 'Green' },
- * 		{ color: '#00f', name: 'Blue' },
- * 	];
- * 	const colorOptions = (
- * 		<>
- * 			{ colors.map( ( { color, name }, index ) => {
- * 				return (
- * 					<CircularOptionPicker.Option
- * 						key={ `${ color }-${ index }` }
- * 						tooltipText={ name }
- * 						style={ { backgroundColor: color, color } }
- * 						isSelected={ index === currentColor }
- * 						onClick={ () => setCurrentColor( index ) }
- * 						aria-label={ name }
- * 					/>
- * 				);
- * 			} ) }
- * 		</>
- * 	);
- * 	return (
- * 		<CircularOptionPicker
- * 				options={ colorOptions }
- * 				actions={
- * 					<CircularOptionPicker.ButtonAction
- * 						onClick={ () => setCurrentColor( undefined ) }
- * 					>
- * 						{ 'Clear' }
- * 					</CircularOptionPicker.ButtonAction>
- * 				}
- * 			/>
- * 	);
- * };
- * ```
- */
-
-function CircularOptionPicker( props: CircularOptionPickerProps ) {
-	const { actions, className, options, children } = props;
-	return (
-		<div
-			className={ classnames(
-				'components-circular-option-picker',
-				className
-			) }
-		>
-			<div className="components-circular-option-picker__swatches">
-				{ options }
-			</div>
-			{ children }
-			{ actions && (
-				<div className="components-circular-option-picker__custom-clear-wrapper">
-					{ actions }
-				</div>
-			) }
-		</div>
-	);
-}
+import CircularOptionPicker from './circular-option-picker';
 
-CircularOptionPicker.Option = Option;
-CircularOptionPicker.ButtonAction = ButtonAction;
-CircularOptionPicker.DropdownLinkAction = DropdownLinkAction;
+export { Option } from './circular-option-picker-option';
+export { OptionGroup } from './circular-option-picker-option-group';
+export {
+	ButtonAction,
+	DropdownLinkAction,
+} from './circular-option-picker-actions';
 
 export default CircularOptionPicker;