@wordpress/components 29.13.1-next.719a03cbe.0 → 30.1.0

package/src/validated-form-controls/components/stories/select-control.story.tsx

@@ -0,0 +1,60 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * External dependencies
+ */
+import type { StoryObj, Meta } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { ValidatedSelectControl } from '../select-control';
+import { formDecorator } from './story-utils';
+
+const meta: Meta< typeof ValidatedSelectControl > = {
+	title: 'Components (Experimental)/Validated Form Controls/ValidatedSelectControl',
+	component: ValidatedSelectControl,
+	tags: [ 'status-private' ],
+	decorators: formDecorator,
+	args: { onChange: () => {} },
+	argTypes: {
+		value: { control: false },
+	},
+};
+export default meta;
+
+export const Default: StoryObj< typeof ValidatedSelectControl > = {
+	render: function Template( { onChange, ...args } ) {
+		const [ value, setValue ] = useState( '' );
+
+		return (
+			<ValidatedSelectControl
+				{ ...args }
+				value={ value }
+				onChange={ ( newValue ) => {
+					setValue( newValue );
+					onChange?.( newValue );
+				} }
+			/>
+		);
+	},
+};
+Default.args = {
+	required: true,
+	label: 'Select',
+	help: 'Selecting option 1 will trigger an error.',
+	options: [
+		{ value: '', label: 'Select an option' },
+		{ value: '1', label: 'Option 1 (not allowed)' },
+		{ value: '2', label: 'Option 2' },
+	],
+	customValidator: ( value ) => {
+		if ( value === '1' ) {
+			return 'Option 1 is not allowed.';
+		}
+		return undefined;
+	},
+};

package/src/validated-form-controls/components/stories/story-utils.tsx

@@ -0,0 +1,46 @@
+/**
+ * WordPress dependencies
+ */
+
+/**
+ * External dependencies
+ */
+import type { Meta } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import Button from '../../../button';
+
+export const formDecorator: Meta[ 'decorators' ] = ( Story ) => (
+	<form
+		style={ {
+			fontFamily: 'sans-serif',
+			display: 'flex',
+			flexDirection: 'column',
+			alignItems: 'flex-start',
+			gap: 16,
+		} }
+		onSubmit={ ( e ) => {
+			e.preventDefault();
+			// eslint-disable-next-line no-alert
+			alert( 'Form submitted!' );
+		} }
+	>
+		<div
+			style={ {
+				display: 'flex',
+				flexDirection: 'column',
+				gap: 16,
+				alignItems: 'stretch',
+				width: 300,
+			} }
+		>
+			<Story />
+		</div>
+
+		<Button variant="primary" type="submit" __next40pxDefaultSize>
+			Submit
+		</Button>
+	</form>
+);

package/src/validated-form-controls/components/stories/text-control.story.tsx

@@ -0,0 +1,55 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * External dependencies
+ */
+import type { StoryObj, Meta } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { formDecorator } from './story-utils';
+import { ValidatedTextControl } from '../text-control';
+
+const meta: Meta< typeof ValidatedTextControl > = {
+	title: 'Components (Experimental)/Validated Form Controls/ValidatedTextControl',
+	component: ValidatedTextControl,
+	tags: [ 'status-private' ],
+	decorators: formDecorator,
+	args: { onChange: () => {} },
+	argTypes: {
+		value: { control: false },
+	},
+};
+export default meta;
+
+export const Default: StoryObj< typeof ValidatedTextControl > = {
+	render: function Template( { onChange, ...args } ) {
+		const [ value, setValue ] = useState( '' );
+
+		return (
+			<ValidatedTextControl
+				{ ...args }
+				value={ value }
+				onChange={ ( newValue ) => {
+					setValue( newValue );
+					onChange?.( newValue );
+				} }
+			/>
+		);
+	},
+};
+Default.args = {
+	required: true,
+	label: 'Text',
+	help: "The word 'error' will trigger an error.",
+	customValidator: ( value ) => {
+		if ( value?.toString().toLowerCase() === 'error' ) {
+			return 'The word "error" is not allowed.';
+		}
+		return undefined;
+	},
+};

package/src/validated-form-controls/components/stories/textarea-control.story.tsx

@@ -0,0 +1,52 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * External dependencies
+ */
+import type { StoryObj, Meta } from '@storybook/react';
+/**
+ * Internal dependencies
+ */
+import { formDecorator } from './story-utils';
+import { ValidatedTextareaControl } from '../textarea-control';
+
+const meta: Meta< typeof ValidatedTextareaControl > = {
+	title: 'Components (Experimental)/Validated Form Controls/ValidatedTextareaControl',
+	component: ValidatedTextareaControl,
+	tags: [ 'status-private' ],
+	decorators: formDecorator,
+	args: { onChange: () => {} },
+	argTypes: { value: { control: false } },
+};
+export default meta;
+
+export const Default: StoryObj< typeof ValidatedTextareaControl > = {
+	render: function Template( { onChange, ...args } ) {
+		const [ value, setValue ] = useState( '' );
+
+		return (
+			<ValidatedTextareaControl
+				{ ...args }
+				onChange={ ( newValue ) => {
+					setValue( newValue );
+					onChange?.( newValue );
+				} }
+				value={ value }
+			/>
+		);
+	},
+};
+Default.args = {
+	required: true,
+	label: 'Textarea',
+	help: 'The word "error" will trigger an error.',
+	customValidator: ( value ) => {
+		if ( value?.toLowerCase() === 'error' ) {
+			return 'The word "error" is not allowed.';
+		}
+		return undefined;
+	},
+};

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

@@ -0,0 +1,55 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * External dependencies
+ */
+import type { StoryObj, Meta } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { formDecorator } from './story-utils';
+import { ValidatedToggleControl } from '../toggle-control';
+
+const meta: Meta< typeof ValidatedToggleControl > = {
+	title: 'Components (Experimental)/Validated Form Controls/ValidatedToggleControl',
+	component: ValidatedToggleControl,
+	tags: [ 'status-private' ],
+	decorators: formDecorator,
+	args: { onChange: () => {} },
+	argTypes: {
+		checked: { control: false },
+	},
+};
+export default meta;
+
+export const Default: StoryObj< typeof ValidatedToggleControl > = {
+	render: function Template( { onChange, ...args } ) {
+		const [ checked, setChecked ] = useState( false );
+
+		return (
+			<ValidatedToggleControl
+				{ ...args }
+				checked={ checked }
+				onChange={ ( value ) => {
+					setChecked( value );
+					onChange?.( value );
+				} }
+			/>
+		);
+	},
+};
+Default.args = {
+	required: true,
+	label: 'Toggle',
+	help: 'This toggle may neither be enabled nor disabled.',
+	customValidator: ( value ) => {
+		if ( value ) {
+			return 'This toggle may not be enabled.';
+		}
+		return undefined;
+	},
+};

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

@@ -0,0 +1,66 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * External dependencies
+ */
+import type { StoryObj, Meta } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { formDecorator } from './story-utils';
+import { ValidatedToggleGroupControl } from '../toggle-group-control';
+import { ToggleGroupControlOption } from '../../../toggle-group-control';
+
+const meta: Meta< typeof ValidatedToggleGroupControl > = {
+	title: 'Components (Experimental)/Validated Form Controls/ValidatedToggleGroupControl',
+	component: ValidatedToggleGroupControl,
+	tags: [ 'status-private' ],
+	decorators: formDecorator,
+	args: { onChange: () => {} },
+	argTypes: {
+		value: { control: false },
+	},
+};
+export default meta;
+
+export const Default: StoryObj< typeof ValidatedToggleGroupControl > = {
+	render: function Template( { onChange, ...args } ) {
+		const [ value, setValue ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedToggleGroupControl
+				>[ 'value' ]
+			>( '1' );
+
+		return (
+			<ValidatedToggleGroupControl
+				{ ...args }
+				value={ value }
+				onChange={ ( newValue ) => {
+					setValue( newValue );
+					onChange?.( newValue );
+				} }
+			/>
+		);
+	},
+};
+Default.args = {
+	required: true,
+	label: 'Toggle Group',
+	isBlock: true,
+	children: [
+		<ToggleGroupControlOption value="1" key="1" label="Option 1" />,
+		<ToggleGroupControlOption value="2" key="2" label="Option 2" />,
+	],
+	help: 'Selecting option 2 will trigger an error.',
+	customValidator: ( value ) => {
+		if ( value === '2' ) {
+			return 'Option 2 is not allowed.';
+		}
+		return undefined;
+	},
+};

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

@@ -0,0 +1,60 @@
+/**
+ * WordPress dependencies
+ */
+import { useMergeRefs } from '@wordpress/compose';
+import { forwardRef, useRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { ControlWithError } from '../control-with-error';
+import type { ValidatedControlProps } from './types';
+import TextControl from '../../text-control';
+import type { TextControlProps } from '../../text-control/types';
+
+type Value = TextControlProps[ 'value' ];
+
+const UnforwardedValidatedTextControl = (
+	{
+		required,
+		customValidator,
+		onChange,
+		markWhenOptional,
+		...restProps
+	}: Omit<
+		React.ComponentProps< typeof TextControl >,
+		'__next40pxDefaultSize' | '__nextHasNoMarginBottom'
+	> &
+		ValidatedControlProps< Value >,
+	forwardedRef: React.ForwardedRef< HTMLInputElement >
+) => {
+	const validityTargetRef = useRef< HTMLInputElement >( null );
+	const mergedRefs = useMergeRefs( [ forwardedRef, validityTargetRef ] );
+	const valueRef = useRef< Value >( restProps.value );
+
+	return (
+		<ControlWithError
+			required={ required }
+			markWhenOptional={ markWhenOptional }
+			customValidator={ () => {
+				return customValidator?.( valueRef.current );
+			} }
+			getValidityTarget={ () => validityTargetRef.current }
+		>
+			<TextControl
+				__next40pxDefaultSize
+				__nextHasNoMarginBottom
+				ref={ mergedRefs }
+				onChange={ ( value ) => {
+					valueRef.current = value;
+					onChange?.( value );
+				} }
+				{ ...restProps }
+			/>
+		</ControlWithError>
+	);
+};
+
+export const ValidatedTextControl = forwardRef(
+	UnforwardedValidatedTextControl
+);

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

@@ -0,0 +1,59 @@
+/**
+ * WordPress dependencies
+ */
+import { forwardRef, useRef } from '@wordpress/element';
+import { useMergeRefs } from '@wordpress/compose';
+
+/**
+ * Internal dependencies
+ */
+import { ControlWithError } from '../control-with-error';
+import type { ValidatedControlProps } from './types';
+import TextareaControl from '../../textarea-control';
+import type { TextareaControlProps } from '../../textarea-control/types';
+
+type Value = TextareaControlProps[ 'value' ];
+
+const UnforwardedValidatedTextareaControl = (
+	{
+		required,
+		customValidator,
+		onChange,
+		markWhenOptional,
+		...restProps
+	}: Omit<
+		React.ComponentProps< typeof TextareaControl >,
+		'__nextHasNoMarginBottom'
+	> &
+		ValidatedControlProps< Value >,
+	forwardedRef: React.ForwardedRef< HTMLTextAreaElement >
+) => {
+	const validityTargetRef = useRef< HTMLTextAreaElement >( null );
+	const mergedRefs = useMergeRefs( [ forwardedRef, validityTargetRef ] );
+	const valueRef = useRef< Value >( restProps.value );
+
+	return (
+		<ControlWithError
+			required={ required }
+			markWhenOptional={ markWhenOptional }
+			customValidator={ () => {
+				return customValidator?.( valueRef.current );
+			} }
+			getValidityTarget={ () => validityTargetRef.current }
+		>
+			<TextareaControl
+				__nextHasNoMarginBottom
+				ref={ mergedRefs }
+				onChange={ ( value ) => {
+					valueRef.current = value;
+					onChange?.( value );
+				} }
+				{ ...restProps }
+			/>
+		</ControlWithError>
+	);
+};
+
+export const ValidatedTextareaControl = forwardRef(
+	UnforwardedValidatedTextareaControl
+);

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;
+};