@wordpress/components 25.9.0 → 25.10.0

package/src/alignment-matrix-control/utils.tsx

@@ -2,6 +2,7 @@
  * WordPress dependencies
  */
 import { __ } from '@wordpress/i18n';
+
 /**
  * Internal dependencies
  */
@@ -31,16 +32,24 @@ export const ALIGNMENT_LABEL: Record< AlignmentMatrixControlValue, string > = {
 export const ALIGNMENTS = GRID.flat();
 
 /**
- * Parses and transforms an incoming value to better match the alignment values
+ * Normalizes and transforms an incoming value to better match the alignment values
  *
  * @param value An alignment value to parse.
  *
  * @return The parsed value.
  */
-export function transformValue( value: AlignmentMatrixControlValue ) {
-	const nextValue = value === 'center' ? 'center center' : value;
+function normalize( value?: string | null ) {
+	const normalized = value === 'center' ? 'center center' : value;
+
+	// Strictly speaking, this could be `string | null | undefined`,
+	// but will be validated shortly, so we're typecasting to an
+	// `AlignmentMatrixControlValue` to keep TypeScript happy.
+	const transformed = normalized?.replace(
+		'-',
+		' '
+	) as AlignmentMatrixControlValue;
 
-	return nextValue.replace( '-', ' ' ) as AlignmentMatrixControlValue;
+	return ALIGNMENTS.includes( transformed ) ? transformed : undefined;
 }
 
 /**
@@ -53,11 +62,25 @@ export function transformValue( value: AlignmentMatrixControlValue ) {
  */
 export function getItemId(
 	prefixId: string,
-	value: AlignmentMatrixControlValue
+	value?: AlignmentMatrixControlValue
 ) {
-	const valueId = transformValue( value ).replace( ' ', '-' );
+	const normalized = normalize( value );
+	if ( ! normalized ) return;
+
+	const id = normalized.replace( ' ', '-' );
+	return `${ prefixId }-${ id }`;
+}
 
-	return `${ prefixId }-${ valueId }`;
+/**
+ * Extracts an item value from its ID
+ *
+ * @param prefixId An ID prefix to remove
+ * @param id       An item ID
+ * @return         The item value
+ */
+export function getItemValue( prefixId: string, id?: string | null ) {
+	const value = id?.replace( prefixId + '-', '' );
+	return normalize( value );
 }
 
 /**
@@ -70,8 +93,9 @@ export function getItemId(
 export function getAlignmentIndex(
 	alignment: AlignmentMatrixControlValue = 'center'
 ) {
-	const item = transformValue( alignment );
-	const index = ALIGNMENTS.indexOf( item );
+	const normalized = normalize( alignment );
+	if ( ! normalized ) return undefined;
 
+	const index = ALIGNMENTS.indexOf( normalized );
 	return index > -1 ? index : undefined;
 }

package/src/button/style.scss

@@ -308,8 +308,7 @@
 	}
 
 	// Toggled style.
-	&[aria-pressed="true"],
-	&[aria-pressed="mixed"] {
+	&.is-pressed {
 		color: $components-color-foreground-inverted;
 		background: $components-color-foreground;
 

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

@@ -8,7 +8,7 @@ import type { ForwardedRef } from 'react';
  * WordPress dependencies
  */
 import { useInstanceId } from '@wordpress/compose';
-import { forwardRef, useContext, useEffect } from '@wordpress/element';
+import { forwardRef, useContext } from '@wordpress/element';
 import { Icon, check } from '@wordpress/icons';
 
 /**
@@ -16,15 +16,9 @@ import { Icon, check } from '@wordpress/icons';
  */
 import { CircularOptionPickerContext } from './circular-option-picker-context';
 import Button from '../button';
-import { CompositeItem } from '../composite';
+import { CompositeItem } from '../composite/v2';
 import Tooltip from '../tooltip';
-import type {
-	OptionProps,
-	CircularOptionPickerCompositeState,
-	CircularOptionPickerContextProps,
-} from './types';
-
-const hasSelectedOption = new Map();
+import type { OptionProps, CircularOptionPickerCompositeStore } from './types';
 
 function UnforwardedOptionAsButton(
 	props: {
@@ -40,7 +34,7 @@ function UnforwardedOptionAsButton(
 			{ ...additionalProps }
 			aria-pressed={ isPressed }
 			ref={ forwardedRef }
-		></Button>
+		/>
 	);
 }
 
@@ -51,38 +45,29 @@ function UnforwardedOptionAsOption(
 		id: string;
 		className?: string;
 		isSelected?: boolean;
-		context: CircularOptionPickerContextProps;
+		compositeStore: CircularOptionPickerCompositeStore;
 	},
 	forwardedRef: ForwardedRef< any >
 ) {
-	const { id, isSelected, context, ...additionalProps } = props;
-	const { isComposite, ..._compositeState } = context;
-	const compositeState =
-		_compositeState as CircularOptionPickerCompositeState;
-	const { baseId, currentId, setCurrentId } = compositeState;
+	const { id, isSelected, compositeStore, ...additionalProps } = props;
+	const activeId = compositeStore.useState( 'activeId' );
 
-	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 ] );
+	if ( isSelected && ! activeId ) {
+		compositeStore.setActiveId( id );
+	}
 
 	return (
 		<CompositeItem
-			{ ...additionalProps }
-			{ ...compositeState }
-			as={ Button }
+			render={
+				<Button
+					{ ...additionalProps }
+					role="option"
+					aria-selected={ !! isSelected }
+					ref={ forwardedRef }
+				/>
+			}
+			store={ compositeStore }
 			id={ id }
-			role="option"
-			aria-selected={ !! isSelected }
-			ref={ forwardedRef }
 		/>
 	);
 }
@@ -96,8 +81,9 @@ export function Option( {
 	tooltipText,
 	...additionalProps
 }: OptionProps ) {
-	const compositeContext = useContext( CircularOptionPickerContext );
-	const { isComposite, baseId } = compositeContext;
+	const { baseId, compositeStore } = useContext(
+		CircularOptionPickerContext
+	);
 	const id = useInstanceId(
 		Option,
 		baseId || 'components-circular-option-picker__option'
@@ -109,10 +95,10 @@ export function Option( {
 		...additionalProps,
 	};
 
-	const optionControl = isComposite ? (
+	const optionControl = compositeStore ? (
 		<OptionAsOption
 			{ ...commonProps }
-			context={ compositeContext }
+			compositeStore={ compositeStore }
 			isSelected={ isSelected }
 		/>
 	) : (

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

@@ -7,14 +7,13 @@ 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 { Composite, useCompositeStore } from '../composite/v2';
 import type {
 	CircularOptionPickerProps,
 	ListboxCircularOptionPickerProps,
@@ -85,30 +84,15 @@ function ListboxCircularOptionPicker(
 		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 compositeStore = useCompositeStore( {
+		focusLoop: loop,
+		rtl: isRTL(),
+	} );
 
 	const compositeContext = {
-		isComposite: true,
-		...compositeState,
+		baseId,
+		compositeStore,
 	};
 
 	return (
@@ -116,7 +100,8 @@ function ListboxCircularOptionPicker(
 			<CircularOptionPickerContext.Provider value={ compositeContext }>
 				<Composite
 					{ ...additionalProps }
-					{ ...compositeState }
+					id={ baseId }
+					store={ compositeStore }
 					role={ 'listbox' }
 				>
 					{ options }
@@ -134,10 +119,8 @@ function ButtonsCircularOptionPicker(
 	const { actions, options, children, baseId, ...additionalProps } = props;
 
 	return (
-		<div { ...additionalProps }>
-			<CircularOptionPickerContext.Provider
-				value={ { isComposite: false, baseId } }
-			>
+		<div { ...additionalProps } id={ baseId }>
+			<CircularOptionPickerContext.Provider value={ { baseId } }>
 				{ options }
 				{ children }
 				{ actions }

package/src/circular-option-picker/types.ts

@@ -14,7 +14,7 @@ import type { Icon } from '@wordpress/icons';
 import type { ButtonAsButtonProps } from '../button/types';
 import type { DropdownProps } from '../dropdown/types';
 import type { WordPressComponentProps } from '../context';
-import type { CompositeState } from '../composite';
+import type { CompositeStore } from '../composite/v2';
 
 type CommonCircularOptionPickerProps = {
 	/**
@@ -123,7 +123,8 @@ export type OptionProps = Omit<
 	>;
 };
 
-export type CircularOptionPickerCompositeState = CompositeState;
-export type CircularOptionPickerContextProps =
-	| { isComposite?: false; baseId?: string }
-	| ( { isComposite: true } & CircularOptionPickerCompositeState );
+export type CircularOptionPickerCompositeStore = CompositeStore;
+export type CircularOptionPickerContextProps = {
+	baseId?: string;
+	compositeStore?: CircularOptionPickerCompositeStore;
+};

package/src/color-palette/index.tsx

@@ -147,6 +147,10 @@ export function CustomColorPickerDropdown( {
 	const popoverProps = useMemo< DropdownProps[ 'popoverProps' ] >(
 		() => ( {
 			shift: true,
+			// Disabling resize as it would otherwise cause the popover to show
+			// scrollbars while dragging the color picker's handle close to the
+			// popover edge.
+			resize: false,
 			...( isRenderedInSidebar
 				? {
 						// When in the sidebar: open to the left (stacking),
@@ -299,6 +303,7 @@ function UnforwardedColorPalette(
 								style={ {
 									background: value,
 								} }
+								type="button"
 							/>
 							<VStack
 								className="components-color-palette__custom-color-text-wrapper"
@@ -307,7 +312,7 @@ function UnforwardedColorPalette(
 								<Truncate className="components-color-palette__custom-color-name">
 									{ value
 										? buttonLabelName
-										: 'No color selected' }
+										: __( 'No color selected' ) }
 								</Truncate>
 								{ /*
 								This `Truncate` is always rendered, even if

package/src/color-picker/component.tsx

@@ -10,7 +10,7 @@ import namesPlugin from 'colord/plugins/names';
  * WordPress dependencies
  */
 import { useCallback, useState, useMemo } from '@wordpress/element';
-import { useDebounce } from '@wordpress/compose';
+import { useDebounce, useMergeRefs } from '@wordpress/compose';
 import { __ } from '@wordpress/i18n';
 
 /**
@@ -49,8 +49,24 @@ const UnconnectedColorPicker = (
 		onChange,
 		defaultValue = '#fff',
 		copyFormat,
+
+		// Context
+		onPickerDragStart,
+		onPickerDragEnd,
 		...divProps
-	} = useContextSystem( props, 'ColorPicker' );
+	} = useContextSystem<
+		ColorPickerProps & {
+			onPickerDragStart?: ( event: MouseEvent ) => void;
+			onPickerDragEnd?: ( event: MouseEvent ) => void;
+		}
+	>( props, 'ColorPicker' );
+
+	const [ containerEl, setContainerEl ] = useState< HTMLElement | null >(
+		null
+	);
+	const containerRef = ( node: HTMLElement | null ) => {
+		setContainerEl( node );
+	};
 
 	// Use a safe default value for the color and remove the possibility of `undefined`.
 	const [ color, setColor ] = useControlledValue( {
@@ -77,11 +93,17 @@ const UnconnectedColorPicker = (
 	);
 
 	return (
-		<ColorfulWrapper ref={ forwardedRef } { ...divProps }>
+		<ColorfulWrapper
+			ref={ useMergeRefs( [ containerRef, forwardedRef ] ) }
+			{ ...divProps }
+		>
 			<Picker
+				containerEl={ containerEl }
 				onChange={ handleChange }
 				color={ safeColordColor }
 				enableAlpha={ enableAlpha }
+				onDragStart={ onPickerDragStart }
+				onDragEnd={ onPickerDragEnd }
 			/>
 			<AuxiliaryColorArtefactWrapper>
 				<AuxiliaryColorArtefactHStackHeader justify="space-between">

package/src/color-picker/picker.tsx

@@ -7,18 +7,112 @@ import { colord } from 'colord';
 /**
  * WordPress dependencies
  */
-import { useMemo } from '@wordpress/element';
+import { useMemo, useEffect, useRef } from '@wordpress/element';
 /**
  * Internal dependencies
  */
 import type { PickerProps } from './types';
 
-export const Picker = ( { color, enableAlpha, onChange }: PickerProps ) => {
+/**
+ * Track the start and the end of drag pointer events related to controlling
+ * the picker's saturation / hue / alpha, and fire the corresponding callbacks.
+ * This is particularly useful to implement synergies like the one with the
+ * `Popover` component, where a pointer events "trap" is rendered while
+ * the user is dragging the pointer to avoid potential interference with iframe
+ * elements.
+ *
+ * @param props
+ * @param props.containerEl
+ * @param props.onDragStart
+ * @param props.onDragEnd
+ */
+const useOnPickerDrag = ( {
+	containerEl,
+	onDragStart,
+	onDragEnd,
+}: Pick< PickerProps, 'containerEl' | 'onDragStart' | 'onDragEnd' > ) => {
+	const isDragging = useRef( false );
+	const leftWhileDragging = useRef( false );
+	useEffect( () => {
+		if ( ! containerEl || ( ! onDragStart && ! onDragEnd ) ) {
+			return;
+		}
+		const interactiveElements = [
+			containerEl.querySelector( '.react-colorful__saturation' ),
+			containerEl.querySelector( '.react-colorful__hue' ),
+			containerEl.querySelector( '.react-colorful__alpha' ),
+		].filter( ( el ) => !! el ) as Element[];
+
+		if ( interactiveElements.length === 0 ) {
+			return;
+		}
+
+		const doc = containerEl.ownerDocument;
+
+		const onPointerUp: EventListener = ( event ) => {
+			isDragging.current = false;
+			leftWhileDragging.current = false;
+			onDragEnd?.( event as MouseEvent );
+		};
+
+		const onPointerDown: EventListener = ( event ) => {
+			isDragging.current = true;
+			onDragStart?.( event as MouseEvent );
+		};
+
+		const onPointerLeave: EventListener = () => {
+			leftWhileDragging.current = isDragging.current;
+		};
+
+		// Try to detect if the user released the pointer while away from the
+		// current window. If the check is successfull, the dragEnd callback will
+		// called as soon as the pointer re-enters the window (better late than never)
+		const onPointerEnter: EventListener = ( event ) => {
+			const noPointerButtonsArePressed =
+				( event as PointerEvent ).buttons === 0;
+
+			if ( leftWhileDragging.current && noPointerButtonsArePressed ) {
+				onPointerUp( event );
+			}
+		};
+
+		// The pointerdown event is added on the interactive elements,
+		// while the remaining events are added on the document object since
+		// the pointer wouldn't necessarily be hovering the initial interactive
+		// element at that point.
+		interactiveElements.forEach( ( el ) =>
+			el.addEventListener( 'pointerdown', onPointerDown )
+		);
+		doc.addEventListener( 'pointerup', onPointerUp );
+		doc.addEventListener( 'pointerenter', onPointerEnter );
+		doc.addEventListener( 'pointerleave', onPointerLeave );
+
+		return () => {
+			interactiveElements.forEach( ( el ) =>
+				el.removeEventListener( 'pointerdown', onPointerDown )
+			);
+			doc.removeEventListener( 'pointerup', onPointerUp );
+			doc.removeEventListener( 'pointerenter', onPointerEnter );
+			doc.removeEventListener( 'pointerleave', onPointerUp );
+		};
+	}, [ onDragStart, onDragEnd, containerEl ] );
+};
+
+export const Picker = ( {
+	color,
+	enableAlpha,
+	onChange,
+	onDragStart,
+	onDragEnd,
+	containerEl,
+}: PickerProps ) => {
 	const Component = enableAlpha
 		? RgbaStringColorPicker
 		: RgbStringColorPicker;
 	const rgbColor = useMemo( () => color.toRgbString(), [ color ] );
 
+	useOnPickerDrag( { containerEl, onDragStart, onDragEnd } );
+
 	return (
 		<Component
 			color={ rgbColor }

package/src/color-picker/styles.ts

@@ -81,7 +81,6 @@ export const ColorfulWrapper = styled.div`
 		align-items: center;
 		width: 216px;
 		height: auto;
-		overflow: hidden;
 	}
 
 	.react-colorful__saturation {

package/src/color-picker/types.ts

@@ -59,6 +59,9 @@ export interface PickerProps {
 	color: Colord;
 	enableAlpha: boolean;
 	onChange: ( nextColor: Colord ) => void;
+	containerEl: HTMLElement | null;
+	onDragStart?: ( event: MouseEvent ) => void;
+	onDragEnd?: ( event: MouseEvent ) => void;
 }
 
 export interface ColorInputProps {

package/src/composite/v2.ts

@@ -0,0 +1,22 @@
+/**
+ * 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
+ */
+
+/* eslint-disable-next-line no-restricted-imports */
+export {
+	Composite,
+	CompositeGroup,
+	CompositeGroupLabel,
+	CompositeItem,
+	CompositeRow,
+	useCompositeStore,
+} from '@ariakit/react';
+
+/* eslint-disable-next-line no-restricted-imports */
+export type { CompositeStore } from '@ariakit/react';

package/src/confirm-dialog/README.md

@@ -137,4 +137,4 @@ The optional custom text to display as the confirmation button's label
 -   Required: No
 -   Default: "Cancel"
 
-The optional custom text to display as the cancelation button's label
+The optional custom text to display as the cancellation button's label

package/src/confirm-dialog/component.tsx

@@ -1,8 +1,3 @@
-/**
- * External dependencies
- */
-import type { ForwardedRef, KeyboardEvent } from 'react';
-
 /**
  * WordPress dependencies
  */
@@ -13,7 +8,7 @@ import { useCallback, useEffect, useRef, useState } from '@wordpress/element';
  * Internal dependencies
  */
 import Modal from '../modal';
-import type { OwnProps, DialogInputEvent } from './types';
+import type { ConfirmDialogProps, DialogInputEvent } from './types';
 import type { WordPressComponentProps } from '../context';
 import { useContextSystem, contextConnect } from '../context';
 import { Flex } from '../flex';
@@ -23,10 +18,10 @@ import { VStack } from '../v-stack';
 import * as styles from './styles';
 import { useCx } from '../utils/hooks/use-cx';
 
-function ConfirmDialog(
-	props: WordPressComponentProps< OwnProps, 'div', false >,
-	forwardedRef: ForwardedRef< any >
-) {
+const UnconnectedConfirmDialog = (
+	props: WordPressComponentProps< ConfirmDialogProps, 'div', false >,
+	forwardedRef: React.ForwardedRef< any >
+) => {
 	const {
 		isOpen: isOpenProp,
 		onConfirm,
@@ -67,7 +62,7 @@ function ConfirmDialog(
 	);
 
 	const handleEnter = useCallback(
-		( event: KeyboardEvent< HTMLDivElement > ) => {
+		( event: React.KeyboardEvent< HTMLDivElement > ) => {
 			// Avoid triggering the 'confirm' action when a button is focused,
 			// as this can cause a double submission.
 			const isConfirmOrCancelButton =
@@ -120,6 +115,77 @@ function ConfirmDialog(
 			) }
 		</>
 	);
-}
+};
 
-export default contextConnect( ConfirmDialog, 'ConfirmDialog' );
+/**
+ * `ConfirmDialog` is built of top of [`Modal`](/packages/components/src/modal/README.md)
+ * and displays a confirmation dialog, with _confirm_ and _cancel_ buttons.
+ * The dialog is confirmed by clicking the _confirm_ button or by pressing the `Enter` key.
+ * It is cancelled (closed) by clicking the _cancel_ button, by pressing the `ESC` key, or by
+ * clicking outside the dialog focus (i.e, the overlay).
+ *
+ * `ConfirmDialog` has two main implicit modes: controlled and uncontrolled.
+ *
+ * UnControlled:
+ *
+ * Allows the component to be used standalone, just by declaring it as part of another React's component render method:
+ * -   It will be automatically open (displayed) upon mounting;
+ * -   It will be automatically closed when clicking the _cancel_ button, by pressing the `ESC` key, or by clicking outside the dialog focus (i.e, the overlay);
+ * -   `onCancel` is not mandatory but can be passed. Even if passed, the dialog will still be able to close itself.
+ *
+ * Activating this mode is as simple as omitting the `isOpen` prop. The only mandatory prop, in this case, is the `onConfirm` callback. The message is passed as the `children`. You can pass any JSX you'd like, which allows to further format the message or include sub-component if you'd like:
+ *
+ * ```jsx
+ * import { __experimentalConfirmDialog as ConfirmDialog } from '@wordpress/components';
+ *
+ * function Example() {
+ * 	return (
+ * 		<ConfirmDialog onConfirm={ () => console.debug( ' Confirmed! ' ) }>
+ * 			Are you sure? <strong>This action cannot be undone!</strong>
+ * 		</ConfirmDialog>
+ * 	);
+ * }
+ * ```
+ *
+ *
+ * Controlled mode:
+ *  Let the parent component control when the dialog is open/closed. It's activated when a
+ * boolean value is passed to `isOpen`:
+ * -   It will not be automatically closed. You need to let it know when to open/close by updating the value of the `isOpen` prop;
+ * -   Both `onConfirm` and the `onCancel` callbacks are mandatory props in this mode;
+ * -   You'll want to update the state that controls `isOpen` by updating it from the `onCancel` and `onConfirm` callbacks.
+ *
+ *```jsx
+ * import { __experimentalConfirmDialog as ConfirmDialog } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * function Example() {
+ * 	const [ isOpen, setIsOpen ] = useState( true );
+ *
+ * 	const handleConfirm = () => {
+ * 		console.debug( 'Confirmed!' );
+ * 		setIsOpen( false );
+ * 	};
+ *
+ * 	const handleCancel = () => {
+ * 		console.debug( 'Cancelled!' );
+ * 		setIsOpen( false );
+ * 	};
+ *
+ * 	return (
+ * 		<ConfirmDialog
+ * 			isOpen={ isOpen }
+ * 			onConfirm={ handleConfirm }
+ * 			onCancel={ handleCancel }
+ * 		>
+ * 			Are you sure? <strong>This action cannot be undone!</strong>
+ * 		</ConfirmDialog>
+ * 	);
+ * }
+ * ```
+ */
+export const ConfirmDialog = contextConnect(
+	UnconnectedConfirmDialog,
+	'ConfirmDialog'
+);
+export default ConfirmDialog;