@wordpress/components 29.12.0 → 30.0.0

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

@@ -0,0 +1,61 @@
+/**
+ * WordPress dependencies
+ */
+import { forwardRef, useRef } from '@wordpress/element';
+import { useMergeRefs } from '@wordpress/compose';
+
+/**
+ * Internal dependencies
+ */
+import { ControlWithError } from '../control-with-error';
+import NumberControl from '../../number-control';
+import type { ValidatedControlProps } from './types';
+import type { NumberControlProps } from '../../number-control/types';
+
+type Value = NumberControlProps[ 'value' ];
+
+const UnforwardedValidatedNumberControl = (
+	{
+		required,
+		customValidator,
+		onChange,
+		markWhenOptional,
+		...restProps
+	}: Omit<
+		React.ComponentProps< typeof NumberControl >,
+		'__next40pxDefaultSize'
+	> &
+		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 }
+		>
+			<NumberControl
+				__next40pxDefaultSize
+				ref={ mergedRefs }
+				// TODO: Upstream limitation - When form is submitted when value is undefined, it will
+				// automatically set a clamped value (as defined by `min` attribute, so 0 by default).
+				onChange={ ( value, ...args ) => {
+					valueRef.current = value;
+					onChange?.( value, ...args );
+				} }
+				{ ...restProps }
+			/>
+		</ControlWithError>
+	);
+};
+
+export const ValidatedNumberControl = forwardRef(
+	UnforwardedValidatedNumberControl
+);

package/src/validated-form-controls/components/radio-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 RadioControl from '../../radio-control';
+import type { RadioControlProps } from '../../radio-control/types';
+
+type Value = RadioControlProps[ 'selected' ];
+
+const UnforwardedValidatedRadioControl = (
+	{
+		required,
+		customValidator,
+		onChange,
+		markWhenOptional,
+		...restProps
+	}: React.ComponentProps< typeof RadioControl > &
+		ValidatedControlProps< Value >,
+	forwardedRef: React.ForwardedRef< HTMLDivElement >
+) => {
+	const validityTargetRef = useRef< HTMLDivElement >( null );
+	const mergedRefs = useMergeRefs( [ forwardedRef, validityTargetRef ] );
+	const valueRef = useRef< Value >( restProps.selected );
+
+	return (
+		<ControlWithError
+			required={ required }
+			markWhenOptional={ markWhenOptional }
+			// TODO: Upstream limitation - RadioControl does not accept a ref.
+			ref={ mergedRefs }
+			customValidator={ () => {
+				return customValidator?.( valueRef.current );
+			} }
+			getValidityTarget={ () =>
+				validityTargetRef.current?.querySelector< HTMLInputElement >(
+					'input[type="radio"]'
+				)
+			}
+		>
+			<RadioControl
+				onChange={ ( value ) => {
+					valueRef.current = value;
+					onChange?.( value );
+				} }
+				{ ...restProps }
+			/>
+		</ControlWithError>
+	);
+};
+
+export const ValidatedRadioControl = forwardRef(
+	UnforwardedValidatedRadioControl
+);

package/src/validated-form-controls/components/range-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 RangeControl from '../../range-control';
+import type { RangeControlProps } from '../../range-control/types';
+
+type Value = RangeControlProps[ 'value' ];
+
+const UnforwardedValidatedRangeControl = (
+	{
+		required,
+		customValidator,
+		onChange,
+		markWhenOptional,
+		...restProps
+	}: Omit<
+		React.ComponentProps< typeof RangeControl >,
+		'__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 }
+		>
+			<RangeControl
+				__next40pxDefaultSize
+				__nextHasNoMarginBottom
+				ref={ mergedRefs }
+				onChange={ ( value ) => {
+					valueRef.current = value;
+					onChange?.( value );
+				} }
+				{ ...restProps }
+			/>
+		</ControlWithError>
+	);
+};
+
+export const ValidatedRangeControl = forwardRef(
+	UnforwardedValidatedRangeControl
+);

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

@@ -0,0 +1,75 @@
+/**
+ * WordPress dependencies
+ */
+import { forwardRef, useRef } from '@wordpress/element';
+import { useMergeRefs } from '@wordpress/compose';
+
+/**
+ * Internal dependencies
+ */
+import { ControlWithError } from '../control-with-error';
+import SelectControl from '../../select-control';
+import type { ValidatedControlProps } from './types';
+import type { SelectControlProps as _SelectControlProps } from '../../select-control/types';
+
+// Only support single value selection
+type SelectControlProps = Omit<
+	_SelectControlProps,
+	'multiple' | 'onChange' | 'value'
+> & {
+	onChange?: ( value: string ) => void;
+	value?: string;
+};
+
+type Value = SelectControlProps[ 'value' ];
+
+const UnforwardedValidatedSelectControl = (
+	{
+		required,
+		customValidator,
+		onChange,
+		markWhenOptional,
+		...restProps
+	}: Omit<
+		React.ComponentProps< typeof SelectControl >,
+		| '__next40pxDefaultSize'
+		| '__nextHasNoMarginBottom'
+		| 'multiple'
+		| 'onChange'
+		| 'value'
+	> & {
+		value?: string;
+		onChange: ( value: string ) => void;
+	} & ValidatedControlProps< Value >,
+	forwardedRef: React.ForwardedRef< HTMLSelectElement >
+) => {
+	const validityTargetRef = useRef< HTMLSelectElement >( 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 }
+		>
+			<SelectControl
+				__nextHasNoMarginBottom
+				__next40pxDefaultSize
+				ref={ mergedRefs }
+				onChange={ ( value ) => {
+					valueRef.current = value;
+					onChange?.( value );
+				} }
+				{ ...restProps }
+			/>
+		</ControlWithError>
+	);
+};
+
+export const ValidatedSelectControl = forwardRef(
+	UnforwardedValidatedSelectControl
+);

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

@@ -0,0 +1,57 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * External dependencies
+ */
+import type { StoryObj, Meta } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { ValidatedCheckboxControl } from '../checkbox-control';
+import { formDecorator } from './story-utils';
+
+const meta: Meta< typeof ValidatedCheckboxControl > = {
+	title: 'Components (Experimental)/Validated Form Controls/ValidatedCheckboxControl',
+	component: ValidatedCheckboxControl,
+	tags: [ 'status-private' ],
+	decorators: formDecorator,
+	args: { onChange: () => {} },
+	argTypes: {
+		checked: { control: false },
+		// TODO: Figure out why this deprecated prop is still showing up here and not in the WP Storybook.
+		heading: { table: { disable: true } },
+	},
+};
+export default meta;
+
+export const Default: StoryObj< typeof ValidatedCheckboxControl > = {
+	render: function Template( { onChange, ...args } ) {
+		const [ checked, setChecked ] = useState( false );
+
+		return (
+			<ValidatedCheckboxControl
+				{ ...args }
+				checked={ checked }
+				onChange={ ( value ) => {
+					setChecked( value );
+					onChange?.( value );
+				} }
+			/>
+		);
+	},
+};
+Default.args = {
+	required: true,
+	label: 'Checkbox',
+	help: 'This checkbox may neither be checked nor unchecked.',
+	customValidator: ( value ) => {
+		if ( value ) {
+			return 'This checkbox may not be checked.';
+		}
+		return undefined;
+	},
+};

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

@@ -0,0 +1,64 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * External dependencies
+ */
+import type { StoryObj, Meta } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { ValidatedComboboxControl } from '../combobox-control';
+import { formDecorator } from './story-utils';
+
+const meta: Meta< typeof ValidatedComboboxControl > = {
+	title: 'Components (Experimental)/Validated Form Controls/ValidatedComboboxControl',
+	component: ValidatedComboboxControl,
+	tags: [ 'status-private' ],
+	decorators: formDecorator,
+	args: { onChange: () => {} },
+	argTypes: {
+		value: { control: false },
+	},
+};
+export default meta;
+
+export const Default: StoryObj< typeof ValidatedComboboxControl > = {
+	render: function Template( { onChange, ...args } ) {
+		const [ value, setValue ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedComboboxControl
+				>[ 'value' ]
+			>();
+
+		return (
+			<ValidatedComboboxControl
+				{ ...args }
+				value={ value }
+				onChange={ ( newValue ) => {
+					setValue( newValue );
+					onChange?.( newValue );
+				} }
+			/>
+		);
+	},
+};
+Default.args = {
+	required: true,
+	label: 'Combobox',
+	help: 'Option A is not allowed.',
+	options: [
+		{ value: 'a', label: 'Option A (not allowed)' },
+		{ value: 'b', label: 'Option B' },
+	],
+	customValidator: ( value ) => {
+		if ( value === 'a' ) {
+			return 'Option A is not allowed.';
+		}
+		return undefined;
+	},
+};

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

@@ -0,0 +1,64 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * External dependencies
+ */
+import type { StoryObj, Meta } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { ValidatedCustomSelectControl } from '../custom-select-control';
+import { formDecorator } from './story-utils';
+
+const meta: Meta< typeof ValidatedCustomSelectControl > = {
+	title: 'Components (Experimental)/Validated Form Controls/ValidatedCustomSelectControl',
+	component: ValidatedCustomSelectControl,
+	tags: [ 'status-private' ],
+	decorators: formDecorator,
+	args: { onChange: () => {} },
+	argTypes: {
+		value: { control: false },
+	},
+};
+export default meta;
+
+export const Default: StoryObj< typeof ValidatedCustomSelectControl > = {
+	render: function Template( { onChange, ...args } ) {
+		const [ value, setValue ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedCustomSelectControl
+				>[ 'value' ]
+			>();
+
+		return (
+			<ValidatedCustomSelectControl
+				{ ...args }
+				value={ value }
+				onChange={ ( newValue ) => {
+					setValue( newValue.selectedItem );
+					onChange?.( newValue );
+				} }
+			/>
+		);
+	},
+};
+Default.args = {
+	required: true,
+	label: 'Custom Select',
+	options: [
+		{ key: '', name: 'Select an option' },
+		{ key: 'a', name: 'Option A (not allowed)' },
+		{ key: 'b', name: 'Option B' },
+	],
+	customValidator: ( value ) => {
+		if ( value?.key === 'a' ) {
+			return 'Option A is not allowed.';
+		}
+		return undefined;
+	},
+};

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

@@ -0,0 +1,132 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * External dependencies
+ */
+import type { StoryObj, Meta } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { seen, unseen } from '@wordpress/icons';
+
+/**
+ * Internal dependencies
+ */
+import { ValidatedInputControl } from '../input-control';
+import { formDecorator } from './story-utils';
+import InputControlSuffixWrapper from '../../../input-control/input-suffix-wrapper';
+import { Button } from '../../../button';
+
+const meta: Meta< typeof ValidatedInputControl > = {
+	title: 'Components (Experimental)/Validated Form Controls/ValidatedInputControl',
+	component: ValidatedInputControl,
+	tags: [ 'status-private' ],
+	decorators: formDecorator,
+	args: { onChange: () => {} },
+	argTypes: {
+		__unstableInputWidth: { control: { type: 'text' } },
+		__unstableStateReducer: { control: false },
+		onChange: { control: false },
+		prefix: { control: false },
+		suffix: { control: false },
+		type: { control: { type: 'text' } },
+		value: { control: false },
+	},
+};
+export default meta;
+
+export const Default: StoryObj< typeof ValidatedInputControl > = {
+	render: function Template( { onChange, ...args } ) {
+		const [ value, setValue ] =
+			useState<
+				React.ComponentProps< typeof ValidatedInputControl >[ 'value' ]
+			>( '' );
+
+		return (
+			<ValidatedInputControl
+				{ ...args }
+				value={ value }
+				onChange={ ( newValue, ...rest ) => {
+					setValue( newValue );
+					onChange?.( newValue, ...rest );
+				} }
+			/>
+		);
+	},
+};
+Default.args = {
+	required: true,
+	label: 'Input',
+	help: 'The word "error" will trigger an error.',
+	customValidator: ( value ) => {
+		if ( value?.toLowerCase() === 'error' ) {
+			return 'The word "error" is not allowed.';
+		}
+		return undefined;
+	},
+};
+
+/**
+ * This demonstrates how password validation would work with the standard implementation.
+ *
+ * We are planning to move to a custom implementation more tailored to the password use case.
+ */
+export const Password: StoryObj< typeof ValidatedInputControl > = {
+	render: function Template( { onChange, ...args } ) {
+		const [ value, setValue ] =
+			useState<
+				React.ComponentProps< typeof ValidatedInputControl >[ 'value' ]
+			>( '' );
+		const [ visible, setVisible ] = useState( false );
+
+		return (
+			<ValidatedInputControl
+				{ ...args }
+				type={ visible ? 'text' : 'password' }
+				suffix={
+					<InputControlSuffixWrapper variant="control">
+						<Button
+							size="small"
+							icon={ visible ? unseen : seen }
+							onClick={ () => setVisible( ( v ) => ! v ) }
+							label={
+								visible ? 'Hide password' : 'Show password'
+							}
+						/>
+					</InputControlSuffixWrapper>
+				}
+				value={ value }
+				onChange={ ( newValue, ...rest ) => {
+					setValue( newValue );
+					onChange?.( newValue, ...rest );
+				} }
+			/>
+		);
+	},
+};
+Password.args = {
+	required: true,
+	label: 'Password',
+	help: 'Minimum 8 characters, include a number, capital letter, and symbol (!@£$%^&*#).',
+	minLength: 8,
+	customValidator: ( value ) => {
+		if ( ! /\d/.test( value ?? '' ) ) {
+			return 'Password must include at least one number.';
+		}
+		if ( ! /[A-Z]/.test( value ?? '' ) ) {
+			return 'Password must include at least one capital letter.';
+		}
+		if ( ! /[!@£$%^&*#]/.test( value ?? '' ) ) {
+			return 'Password must include at least one symbol.';
+		}
+		return undefined;
+	},
+};
+Password.argTypes = {
+	suffix: { control: false },
+	type: { control: false },
+};

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

@@ -0,0 +1,62 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * External dependencies
+ */
+import type { StoryObj, Meta } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { ValidatedNumberControl } from '../number-control';
+import { formDecorator } from './story-utils';
+
+const meta: Meta< typeof ValidatedNumberControl > = {
+	title: 'Components (Experimental)/Validated Form Controls/ValidatedNumberControl',
+	component: ValidatedNumberControl,
+	tags: [ 'status-private' ],
+	decorators: formDecorator,
+	args: { onChange: () => {} },
+	argTypes: {
+		prefix: { control: { type: 'text' } },
+		step: { control: { type: 'text' } },
+		suffix: { control: { type: 'text' } },
+		type: { control: { type: 'text' } },
+		value: { control: false },
+	},
+};
+export default meta;
+
+export const Default: StoryObj< typeof ValidatedNumberControl > = {
+	render: function Template( { onChange, ...args } ) {
+		const [ value, setValue ] =
+			useState<
+				React.ComponentProps< typeof ValidatedNumberControl >[ 'value' ]
+			>();
+
+		return (
+			<ValidatedNumberControl
+				{ ...args }
+				value={ value }
+				onChange={ ( newValue, ...rest ) => {
+					setValue( newValue );
+					onChange?.( newValue, ...rest );
+				} }
+			/>
+		);
+	},
+};
+Default.args = {
+	required: true,
+	label: 'Number',
+	help: 'Odd numbers are not allowed.',
+	customValidator: ( value ) => {
+		if ( value && parseInt( value.toString(), 10 ) % 2 !== 0 ) {
+			return 'Choose an even number.';
+		}
+		return undefined;
+	},
+};

package/src/validated-form-controls/components/stories/overview.mdx

@@ -0,0 +1,52 @@
+import { ArgTypes, Meta, Stories } from '@storybook/blocks';
+import * as OverviewStories from './overview.story';
+import { ValidatedInputControl } from '..';
+
+<Meta of={ OverviewStories } title="Components (Private)/Validated Form Controls/Overview" />
+
+# Validated Form Controls
+
+This section contains form control components that extend [WordPress components](https://wordpress.github.io/gutenberg/) with additional validation capabilities.
+
+## Status: Beta
+
+We are still gathering feedback and iterating. Please get in touch with `@WordPress/gutenberg-components`  if you are interested in trying them out in the Gutenberg app.
+
+## Usage
+
+Component APIs are the same as the underlying WordPress components, with the addition of some optional props:
+
+<ArgTypes of={ ValidatedInputControl } include={ [ 'required', 'markWhenOptional', 'customValidator' ] } />
+
+## Implementation
+
+These components are designed to work with the native HTML5 [Constraint Validation API](https://developer.mozilla.org/en-US/docs/Web/API/Constraint_validation). Using this browser API as the "source of truth" for form element errors has these benefits:
+
+- Ability to use CSS selectors like `:invalid`, `:user-invalid`, `:required`, and `:optional`.
+- Ability to use simple HTML attribute-based constraints (e.g. `min`, `max`, `required`, `pattern`, `type`) together with fully custom validation logic (with the `setCustomValidity()` method).
+- Attribute-based constraints will already have localized, user-facing error messages built in.
+- When a user clicks the form submit button, the browser will automatically check the validity states of all enclosed form elements and block the submit when there are errors. It will also automatically scroll and focus to the first erroring element and show a prominent error popover.
+- While not _all_ aspects of the Constraint Validation API are well-supported in all screen readers yet, many aspects are, and will continue to improve. We can supplement any accessibility shortcomings with things like `aria-live` announcements of error messages.
+
+## Current limitations
+
+### No easy access to underlying validation APIs
+
+- The consumer does not have a simple way to trigger their custom validators at an arbitrary point in time. Currently, the validation timings for custom validators are handled by the component — first on `blur`, and then on every `change` after the field is considered "touched". Note that this limitation only applies to **custom** validators, not the standard attribute-based validators like `required` or `pattern`, which can be triggered at any time using the `reportValidity()` method on either the underlying control element or the wrapping `<form>` element.
+- The consumer does not have direct access to the [`validity` object](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState) of the underlying element.
+
+We don't foresee these being needed much, but it is technically possible by the consumer accessing the target element's validation APIs via `ref`. Better docs or ergonomics can be added when we have actual use cases.
+
+### Delegate elements
+
+The implementations for `ToggleGroupControl` and `CustomSelectControl` use a "delegate" element for validation, due to upstream limitations that prevent us from using the actual underlying elements for constraint validation. A delegate element in this context is a visually hidden form element that we "delegate" the Constraint Validation API concerns to.
+
+This is not ideal, but lets us maintain a consistent mechanism to scroll to the invalid field when attempting to submit, and block the form from submitting. It is hopefully fine as a stopgap, given the low amount of actual validation that will need happen on these two specific components.
+
+### Controlled mode only
+
+Some of the underlying WordPress components currently do not fully support uncontrolled mode. For now, we recommend sticking to controlled mode to avoid any issues.
+
+## Examples
+
+<Stories />