@wordpress/components 29.12.0 → 30.0.0

package/src/validated-form-controls/components/toggle-control.tsx

@@ -0,0 +1,69 @@
+/**
+ * WordPress dependencies
+ */
+import { forwardRef, useRef, useEffect } from '@wordpress/element';
+import { useMergeRefs } from '@wordpress/compose';
+
+/**
+ * Internal dependencies
+ */
+import { ControlWithError } from '../control-with-error';
+import type { ValidatedControlProps } from './types';
+import ToggleControl from '../../toggle-control';
+import type { ToggleControlProps } from '../../toggle-control/types';
+
+type Value = ToggleControlProps[ 'checked' ];
+
+// TODO: Should we customize the default `missingValue` message? It says to "check this box".
+
+const UnforwardedValidatedToggleControl = (
+	{
+		required,
+		customValidator,
+		onChange,
+		markWhenOptional,
+		...restProps
+	}: Omit<
+		React.ComponentProps< typeof ToggleControl >,
+		'__nextHasNoMarginBottom'
+	> &
+		ValidatedControlProps< Value >,
+	forwardedRef: React.ForwardedRef< HTMLInputElement >
+) => {
+	const validityTargetRef = useRef< HTMLInputElement >( null );
+	const mergedRefs = useMergeRefs( [ forwardedRef, validityTargetRef ] );
+	const valueRef = useRef< Value >( restProps.checked );
+
+	// TODO: Upstream limitation - The `required` attribute is not passed down to the input,
+	// so we need to set it manually.
+	useEffect( () => {
+		if ( validityTargetRef.current ) {
+			validityTargetRef.current.required = required ?? false;
+		}
+	}, [ required ] );
+
+	return (
+		<ControlWithError
+			required={ required }
+			markWhenOptional={ markWhenOptional }
+			customValidator={ () => {
+				return customValidator?.( valueRef.current );
+			} }
+			getValidityTarget={ () => validityTargetRef.current }
+		>
+			<ToggleControl
+				__nextHasNoMarginBottom
+				ref={ mergedRefs }
+				onChange={ ( value ) => {
+					valueRef.current = value;
+					onChange?.( value );
+				} }
+				{ ...restProps }
+			/>
+		</ControlWithError>
+	);
+};
+
+export const ValidatedToggleControl = forwardRef(
+	UnforwardedValidatedToggleControl
+);

package/src/validated-form-controls/components/toggle-group-control.tsx

@@ -0,0 +1,82 @@
+/**
+ * WordPress dependencies
+ */
+import { forwardRef, useId, useRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { ControlWithError } from '../control-with-error';
+import type { ValidatedControlProps } from './types';
+import { ToggleGroupControl } from '../../toggle-group-control';
+import type { ToggleGroupControlProps } from '../../toggle-group-control/types';
+
+type Value = ToggleGroupControlProps[ 'value' ];
+
+const UnforwardedValidatedToggleGroupControl = (
+	{
+		required,
+		customValidator,
+		onChange,
+		markWhenOptional,
+		...restProps
+	}: Omit<
+		React.ComponentProps< typeof ToggleGroupControl >,
+		'__next40pxDefaultSize' | '__nextHasNoMarginBottom'
+	> &
+		ValidatedControlProps< Value >,
+	forwardedRef: React.ForwardedRef< HTMLInputElement >
+) => {
+	const validityTargetRef = useRef< HTMLInputElement >( null );
+	const valueRef = useRef< Value >( restProps.value );
+
+	const nameAttr = useId();
+
+	return (
+		<div className="components-validated-control__wrapper-with-error-delegate">
+			<ControlWithError
+				required={ required }
+				markWhenOptional={ markWhenOptional }
+				customValidator={ () => {
+					return customValidator?.( valueRef.current );
+				} }
+				getValidityTarget={ () => validityTargetRef.current }
+			>
+				<ToggleGroupControl
+					__nextHasNoMarginBottom
+					__next40pxDefaultSize
+					ref={ forwardedRef }
+					// TODO: Upstream limitation - In uncontrolled mode, starting from an undefined value then
+					// setting a value has a visual bug.
+					onChange={ ( value ) => {
+						valueRef.current = value;
+						onChange?.( value );
+					} }
+					{ ...restProps }
+				/>
+			</ControlWithError>
+			<input
+				className="components-validated-control__error-delegate"
+				type="radio"
+				ref={ validityTargetRef }
+				required={ required }
+				checked={ restProps.value !== null }
+				tabIndex={ -1 }
+				// A name attribute is needed for the `required` behavior to work.
+				name={ nameAttr }
+				onChange={ () => {} }
+				onFocus={ ( e ) => {
+					e.target.previousElementSibling
+						?.querySelector< HTMLButtonElement | HTMLInputElement >(
+							'[data-active-item="true"]'
+						)
+						?.focus();
+				} }
+			/>
+		</div>
+	);
+};
+
+export const ValidatedToggleGroupControl = forwardRef(
+	UnforwardedValidatedToggleGroupControl
+);

package/src/validated-form-controls/components/types.ts

@@ -0,0 +1,28 @@
+export type ValidatedControlProps< V > = {
+	/**
+	 * Whether the control is required.
+	 * @default false
+	 */
+	required?: boolean;
+	/**
+	 * Label the control as "optional" when _not_ `required`, instead of the inverse.
+	 * @default false
+	 */
+	markWhenOptional?: boolean;
+	/**
+	 * A function that returns a custom validity message when applicable. This error message will be applied to the
+	 * underlying element using the native [`setCustomValidity()` method](https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/setCustomValidity).
+	 * This means the custom validator will be run _in addition_ to any other HTML attribute-based validation, and
+	 * will be prioritized over any existing validity messages dictated by the HTML attributes.
+	 * An empty string or `undefined` return value will clear any existing custom validity message.
+	 *
+	 * Make sure you don't programatically pass a value (such as an initial value) to the control component
+	 * that fails this validator, because the validator will only run for user-initiated changes.
+	 *
+	 * Always prefer using standard HTML attributes like `required` and `min`/`max` over custom validators
+	 * when possible, as they are simpler and have localized error messages built in.
+	 */
+	// TODO: Technically, we could add an optional `customValidity` string prop so the consumer can set
+	// an error message at any point in time. We should wait until we have a use case though.
+	customValidator?: ( currentValue: V ) => string | void;
+};

package/src/validated-form-controls/control-with-error.tsx

@@ -0,0 +1,198 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import { error } from '@wordpress/icons';
+
+/**
+ * External dependencies
+ */
+import {
+	cloneElement,
+	forwardRef,
+	useEffect,
+	useState,
+} from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { withIgnoreIMEEvents } from '../utils/with-ignore-ime-events';
+
+import Icon from '../icon';
+
+function appendRequiredIndicator(
+	label: React.ReactNode,
+	required: boolean | undefined,
+	markWhenOptional: boolean | undefined
+) {
+	if ( required && ! markWhenOptional ) {
+		return (
+			<>
+				{ label } { `(${ __( 'Required' ) })` }
+			</>
+		);
+	}
+	if ( ! required && markWhenOptional ) {
+		return (
+			<>
+				{ label } { `(${ __( 'Optional' ) })` }
+			</>
+		);
+	}
+	return label;
+}
+
+/**
+ * HTML elements that support the Constraint Validation API.
+ *
+ * Here, we exclude HTMLButtonElement because although it does technically support the API,
+ * normal buttons are actually exempted from any validation.
+ * @see https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLButtonElement/willValidate
+ */
+type ValidityTarget =
+	| HTMLFieldSetElement
+	| HTMLInputElement
+	| HTMLSelectElement
+	| HTMLTextAreaElement;
+
+function UnforwardedControlWithError< C extends React.ReactElement >(
+	{
+		required,
+		markWhenOptional,
+		customValidator,
+		getValidityTarget,
+		children,
+	}: {
+		/**
+		 * Whether the control is required.
+		 */
+		required?: boolean;
+		/**
+		 * Label the control as "optional" when _not_ `required`, instead of the inverse.
+		 */
+		markWhenOptional?: boolean;
+		/**
+		 * A function that returns a custom validity message when applicable.
+		 *
+		 * This message will be applied to the element returned by `getValidityTarget`.
+		 * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/setCustomValidity
+		 */
+		customValidator?: () => string | void;
+		/**
+		 * A function that returns the actual element on which the validity data should be applied.
+		 */
+		getValidityTarget: () => ValidityTarget | null | undefined;
+		/**
+		 * The control component to apply validation to.
+		 */
+		children: C;
+	},
+	forwardedRef: React.ForwardedRef< HTMLDivElement >
+) {
+	const [ errorMessage, setErrorMessage ] = useState< string | undefined >();
+	const [ isTouched, setIsTouched ] = useState( false );
+
+	// Ensure that error messages are visible after user attemps to submit a form
+	// with multiple invalid fields.
+	useEffect( () => {
+		const validityTarget = getValidityTarget();
+		const showValidationMessage = () =>
+			setErrorMessage( validityTarget?.validationMessage );
+
+		validityTarget?.addEventListener( 'invalid', showValidationMessage );
+
+		return () => {
+			validityTarget?.removeEventListener(
+				'invalid',
+				showValidationMessage
+			);
+		};
+	} );
+
+	const validate = () => {
+		const message = customValidator?.();
+		const validityTarget = getValidityTarget();
+
+		validityTarget?.setCustomValidity( message ?? '' );
+		setErrorMessage( validityTarget?.validationMessage );
+	};
+
+	const onBlur = ( event: React.FocusEvent< HTMLDivElement > ) => {
+		// Only consider "blurred from the component" if focus has fully left the wrapping div.
+		// This prevents unnecessary blurs from components with multiple focusable elements.
+		if (
+			! event.relatedTarget ||
+			! event.currentTarget.contains( event.relatedTarget )
+		) {
+			setIsTouched( true );
+
+			const validityTarget = getValidityTarget();
+
+			// Prevents a double flash of the native error tooltip when the control is already showing one.
+			if ( ! validityTarget?.validity.valid ) {
+				if ( ! errorMessage ) {
+					setErrorMessage( validityTarget?.validationMessage );
+				}
+				return;
+			}
+
+			validate();
+		}
+	};
+
+	const onChange = ( ...args: unknown[] ) => {
+		children.props.onChange?.( ...args );
+
+		// Only validate incrementally if the field has blurred at least once,
+		// or currently has an error message.
+		if ( isTouched || errorMessage ) {
+			validate();
+		}
+	};
+
+	const onKeyDown = ( event: React.KeyboardEvent< HTMLDivElement > ) => {
+		// Ensures that custom validators are triggered when the user submits by pressing Enter,
+		// without ever blurring the control.
+		if ( event.key === 'Enter' ) {
+			validate();
+		}
+	};
+
+	return (
+		// Disable reason: Just listening to a bubbled event, not for interaction.
+		// eslint-disable-next-line jsx-a11y/no-static-element-interactions
+		<div
+			className="components-validated-control"
+			ref={ forwardedRef }
+			onBlur={ onBlur }
+			onKeyDown={ withIgnoreIMEEvents( onKeyDown ) }
+		>
+			{ cloneElement( children, {
+				label: appendRequiredIndicator(
+					children.props.label,
+					required,
+					markWhenOptional
+				),
+				onChange,
+				required,
+			} ) }
+			<div aria-live="polite">
+				{ errorMessage && (
+					<p className="components-validated-control__error">
+						<Icon
+							className="components-validated-control__error-icon"
+							icon={ error }
+							size={ 16 }
+							fill="currentColor"
+						/>
+						{ errorMessage }
+					</p>
+				) }
+			</div>
+		</div>
+	);
+}
+
+export const ControlWithError = forwardRef( UnforwardedControlWithError );

package/src/validated-form-controls/index.ts

@@ -0,0 +1,2 @@
+export * from './components';
+export * from './control-with-error';

package/src/validated-form-controls/style.scss

@@ -0,0 +1,75 @@
+.components-validated-control {
+	// For components based on InputBase
+	&:has(:is(input, select):user-invalid)
+	.components-input-control__backdrop {
+		--wp-components-color-accent: $alert-red;
+		border-color: $alert-red;
+	}
+
+	// For TextControl, TextareaControl
+	:is(textarea, input[type="text"]):user-invalid {
+		--wp-admin-theme-color: $alert-red;
+		--wp-components-color-accent: $alert-red;
+		border-color: $alert-red;
+	}
+
+	// For ComboboxControl
+	.components-combobox-control__suggestions-container:has(
+	input:user-invalid
+):not(:has([aria-expanded="true"])) {
+		border-color: $alert-red;
+	}
+}
+
+.components-validated-control__wrapper-with-error-delegate {
+	position: relative;
+
+	// For CustomSelectControl
+	&:has(select:user-invalid) .components-input-control__backdrop {
+		--wp-components-color-accent: $alert-red;
+		border-color: $alert-red;
+	}
+
+	// For ToggleGroupControl
+	&:has(input[type="radio"]:invalid) {
+		--wp-components-color-accent: $alert-red;
+	}
+}
+
+.components-validated-control__error-delegate {
+	position: absolute;
+	top: 0;
+	height: 100%;
+	width: 100%;
+	opacity: 0;
+	pointer-events: none;
+}
+
+.components-validated-control__error {
+	display: flex;
+	align-items: flex-start;
+	gap: 4px;
+	margin: 8px 0 0;
+	font-family: $font-family-body;
+	font-size: 0.75rem;
+	line-height: 16px; // matches the icon size
+	color: $alert-red;
+	animation:
+		components-validated-control__error-jump 0.2s
+		cubic-bezier(0.68, -0.55, 0.27, 1.55);
+}
+
+.components-validated-control__error-icon {
+	flex-shrink: 0;
+}
+
+@keyframes components-validated-control__error-jump {
+	0% {
+		transform: translateY(-4px);
+		opacity: 0;
+	}
+	100% {
+		transform: translateY(0);
+		opacity: 1;
+	}
+}