Add validated form controls (#100771)

* Add form validation prototypes

* Add more components

* Change "required" indicator

* Refactor

* Add password example

* Fix styling on longer errors

* Split ToggleGroup story

* ToggleGroupControl: Try custom handling

* Better screen reader support?

* Explicitly read "(Required)" label suffix

This may be redundant sometimes due to the `required` attribute on the element itself, but some components like ToggleGroupControl cannot be marked as `required` via attribute.

* ToggleGroupControl: Prevent React warning

* RadioControl: Add custom handling

* Add support for NumberControl, CheckboxControl, ToggleControl

* Add support for SelectControl and CustomSelectControl

* Add support for TextControl, fix state bugs

* Add support for TextareaControl

* Add support for ComboboxControl, RangeControl

* Improve TODO comments

* Check InputControl will suffix button (needs fix)

* Expand support for error styles

* Add more TODOs

* Fix bug in password example

* Stricter types for ValidityTarget

* Add prop descriptions

* Remove unused rest prop passing in ControlWithError

* Move `required` prop to wrapper component

* Encapsulate into components

* Rename CSS class

* Extract delegate styles

* Add clarification for custom validity

* Remove unneeded optional chaining

* Add Overview doc

* Split out CheckboxControl story

* Simplify SR announcements

* Improve UX on blur when tooltip visible

* Split out InputControl stories

* Work around types

* Fix story arg passing

* Extract more stories

* Improve UX on forms with multiple errors

* Remove __next props from docs

* Add "mark when optional" functionality

* Tweak and simplify docs

* Rename

* Fix bug in CustomSelectControl

* When errored on submit, start incremental validation

* Use error icon instead

* Tighten vertical margins on error message

As suggested by @elizaan36

* Add supplemental examples

* Handle direct submissions with no blurring

* Document default values on props

* Improve custom validator docs (based on feedback)

* Rename prop to `customValidator`

* Update Storybook config to reflect current setup

* Support ReactNode in label

* Resolve React display name errors

* Rename to `children` prop

* Move `children` prop down

* Move to JSX children

* Add prop description

* Add changelog

Author: mirka

packages/components/.storybook/main.js

@@ -2,7 +2,10 @@ const storybookDefaultConfig = require( '@automattic/calypso-storybook' );
 
 module.exports = {
 	...storybookDefaultConfig( {
-		stories: [ '../{src,styles}/**/*.stories.{js,jsx,ts,tsx}', './**/*.mdx' ],
+		stories: [
+			'../{src,styles}/**/*.stories.{js,jsx,ts,tsx}',
+			'../{src,styles,.storybook}/**/*.mdx',
+		],
 	} ),
 	docs: { autodocs: true },
 };

packages/components/.storybook/preview.js

@@ -12,7 +12,7 @@ const parameters = {
 	},
 	options: {
 		storySort: ( a, b ) => {
-			const sectionOrder = [ 'WP Overrides', 'Deprecated', 'Unaudited' ];
+			const sectionOrder = [ 'Validated Form Controls', 'WP Overrides', 'Deprecated', 'Unaudited' ];
 			const aIndex = sectionOrder.findIndex( ( prefix ) => a.title.startsWith( prefix ) );
 			const bIndex = sectionOrder.findIndex( ( prefix ) => b.title.startsWith( prefix ) );
 

packages/components/CHANGELOG.md

@@ -7,6 +7,7 @@
 ### Enhancements
 
 - Add `BigSkyLogo.Mark` component ([#103612](https://github.com/Automattic/wp-calypso/pull/103612)).
+- Add `ValidatedFormControls` components, still in beta ([#100771](https://github.com/Automattic/wp-calypso/pull/100771)).
 
 ## 2.3.0
 

packages/components/src/utils/with-ignore-ime-events.ts

@@ -0,0 +1,31 @@
+// Copied from @wordpress/components
+
+/**
+ * A higher-order function that wraps a keydown event handler to ensure it is not an IME event.
+ *
+ * In CJK languages, an IME (Input Method Editor) is used to input complex characters.
+ * During an IME composition, keydown events (e.g. Enter or Escape) can be fired
+ * which are intended to control the IME and not the application.
+ * These events should be ignored by any application logic.
+ * @param keydownHandler The keydown event handler to execute after ensuring it was not an IME event.
+ * @returns A wrapped version of the given event handler that ignores IME events.
+ */
+export function withIgnoreIMEEvents< E extends React.KeyboardEvent | KeyboardEvent >(
+	keydownHandler: ( event: E ) => void
+) {
+	return ( event: E ) => {
+		const { isComposing } = 'nativeEvent' in event ? event.nativeEvent : event;
+
+		if (
+			isComposing ||
+			// Workaround for Mac Safari where the final Enter/Backspace of an IME composition
+			// is `isComposing=false`, even though it's technically still part of the composition.
+			// These can only be detected by keyCode.
+			event.keyCode === 229
+		) {
+			return;
+		}
+
+		keydownHandler( event );
+	};
+}

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

@@ -0,0 +1,45 @@
+import { fn } from '@storybook/test';
+import { useState } from 'react';
+import { ValidatedCheckboxControl } from './checkbox-control';
+import { formDecorator } from './story-utils';
+import type { StoryObj, Meta } from '@storybook/react';
+
+const meta: Meta< typeof ValidatedCheckboxControl > = {
+	title: 'Validated Form Controls/ValidatedCheckboxControl',
+	component: ValidatedCheckboxControl,
+	decorators: formDecorator,
+	args: { onChange: fn() },
+	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.';
+		}
+	},
+};

packages/components/src/validated-form-controls/components/checkbox-control.tsx

@@ -0,0 +1,48 @@
+import { CheckboxControl } from '@wordpress/components';
+import { useMergeRefs } from '@wordpress/compose';
+import { forwardRef, useRef } from 'react';
+import { ControlWithError } from '../control-with-error';
+import type { CheckboxControlProps, ValidatedControlProps } from './types';
+
+type Value = CheckboxControlProps[ 'checked' ];
+
+const UnforwardedValidatedCheckboxControl = (
+	{
+		required,
+		customValidator,
+		onChange,
+		markWhenOptional,
+		...restProps
+	}: Omit< CheckboxControlProps, '__nextHasNoMarginBottom' > & ValidatedControlProps< Value >,
+	forwardedRef: React.ForwardedRef< HTMLInputElement >
+) => {
+	const validityTargetRef = useRef< HTMLDivElement >( null );
+	const mergedRefs = useMergeRefs( [ forwardedRef, validityTargetRef ] );
+	const valueRef = useRef< Value >( restProps.checked );
+
+	return (
+		<ControlWithError
+			required={ required }
+			markWhenOptional={ markWhenOptional }
+			ref={ mergedRefs }
+			customValidator={ () => {
+				return customValidator?.( valueRef.current );
+			} }
+			getValidityTarget={ () =>
+				validityTargetRef.current?.querySelector< HTMLInputElement >( 'input[type="checkbox"]' )
+			}
+		>
+			<CheckboxControl
+				__nextHasNoMarginBottom
+				onChange={ ( value ) => {
+					valueRef.current = value;
+					onChange?.( value );
+				} }
+				// TODO: Upstream limitation - CheckboxControl doesn't support uncontrolled mode, visually.
+				{ ...restProps }
+			/>
+		</ControlWithError>
+	);
+};
+
+export const ValidatedCheckboxControl = forwardRef( UnforwardedValidatedCheckboxControl );

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

@@ -0,0 +1,48 @@
+import { fn } from '@storybook/test';
+import { useState } from 'react';
+import { ValidatedComboboxControl } from './combobox-control';
+import { formDecorator } from './story-utils';
+import type { Meta, StoryObj } from '@storybook/react';
+
+const meta: Meta< typeof ValidatedComboboxControl > = {
+	title: 'Validated Form Controls/ValidatedComboboxControl',
+	component: ValidatedComboboxControl,
+	decorators: formDecorator,
+	args: { onChange: fn() },
+	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.';
+		}
+	},
+};

packages/components/src/validated-form-controls/components/combobox-control.tsx

@@ -0,0 +1,60 @@
+import { ComboboxControl } from '@wordpress/components';
+import { useMergeRefs } from '@wordpress/compose';
+import { forwardRef, useEffect, useRef } from 'react';
+import { ControlWithError } from '../control-with-error';
+import type { ComboboxControlProps, ValidatedControlProps } from './types';
+
+type Value = ComboboxControlProps[ 'value' ];
+
+const UnforwardedValidatedComboboxControl = (
+	{
+		required,
+		customValidator,
+		onChange,
+		markWhenOptional,
+		...restProps
+	}: Omit< ComboboxControlProps, '__next40pxDefaultSize' | '__nextHasNoMarginBottom' > &
+		ValidatedControlProps< Value >,
+	forwardedRef: React.ForwardedRef< HTMLInputElement >
+) => {
+	const validityTargetRef = useRef< HTMLInputElement >( null );
+	const mergedRefs = useMergeRefs( [ forwardedRef, validityTargetRef ] );
+	const valueRef = useRef< Value >( restProps.value );
+
+	// TODO: Upstream limitation - The `required` attribute is not passed down to the input,
+	// so we need to set it manually.
+	useEffect( () => {
+		const input =
+			validityTargetRef.current?.querySelector< HTMLInputElement >( 'input[role="combobox"]' );
+		if ( input ) {
+			input.required = required ?? false;
+		}
+	}, [ required ] );
+
+	return (
+		// TODO: Bug - Missing value error is not cleared immediately on change, waits for blur.
+		<ControlWithError
+			required={ required }
+			markWhenOptional={ markWhenOptional }
+			ref={ mergedRefs }
+			customValidator={ () => {
+				return customValidator?.( valueRef.current );
+			} }
+			getValidityTarget={ () =>
+				validityTargetRef.current?.querySelector< HTMLInputElement >( 'input[role="combobox"]' )
+			}
+		>
+			<ComboboxControl
+				__nextHasNoMarginBottom
+				__next40pxDefaultSize
+				{ ...restProps }
+				onChange={ ( value ) => {
+					valueRef.current = value;
+					onChange?.( value );
+				} }
+			/>
+		</ControlWithError>
+	);
+};
+
+export const ValidatedComboboxControl = forwardRef( UnforwardedValidatedComboboxControl );

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

@@ -0,0 +1,48 @@
+import { fn } from '@storybook/test';
+import { useState } from 'react';
+import { ValidatedCustomSelectControl } from './custom-select-control';
+import { formDecorator } from './story-utils';
+import type { Meta, StoryObj } from '@storybook/react';
+
+const meta: Meta< typeof ValidatedCustomSelectControl > = {
+	title: 'Validated Form Controls/ValidatedCustomSelectControl',
+	component: ValidatedCustomSelectControl,
+	decorators: formDecorator,
+	args: { onChange: fn() },
+	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.';
+		}
+	},
+};

packages/components/src/validated-form-controls/components/custom-select-control.tsx

@@ -0,0 +1,62 @@
+import { CustomSelectControl } from '@wordpress/components';
+import { forwardRef, useRef } from 'react';
+import { ControlWithError } from '../control-with-error';
+import type { CustomSelectControlProps, ValidatedControlProps } from './types';
+
+type Value = CustomSelectControlProps[ 'value' ];
+
+const UnforwardedValidatedCustomSelectControl = (
+	{
+		required,
+		customValidator,
+		onChange,
+		markWhenOptional,
+		...restProps
+	}: Omit< CustomSelectControlProps, '__next40pxDefaultSize' > & ValidatedControlProps< Value >,
+	forwardedRef: React.ForwardedRef< HTMLDivElement >
+) => {
+	const validityTargetRef = useRef< HTMLSelectElement >( null );
+	const valueRef = useRef< Value >( restProps.value );
+
+	return (
+		<div className="a8c-validated-control__wrapper-with-error-delegate" ref={ forwardedRef }>
+			<ControlWithError
+				required={ required }
+				markWhenOptional={ markWhenOptional }
+				customValidator={ () => {
+					return customValidator?.( valueRef.current );
+				} }
+				getValidityTarget={ () => validityTargetRef.current }
+			>
+				<CustomSelectControl
+					// TODO: Upstream limitation - Required isn't passed down correctly,
+					// so it needs to be set on a delegate element.
+					__next40pxDefaultSize
+					onChange={ ( value ) => {
+						valueRef.current = value.selectedItem;
+						onChange?.( value );
+					} }
+					{ ...restProps }
+				/>
+			</ControlWithError>
+			<select
+				className="a8c-validated-control__error-delegate"
+				ref={ validityTargetRef }
+				required={ required }
+				tabIndex={ -1 }
+				value={ restProps.value?.key ? 'hasvalue' : '' }
+				onChange={ () => {} }
+				onFocus={ ( e ) => {
+					e.target.previousElementSibling
+						?.querySelector< HTMLButtonElement >( '[role="combobox"]' )
+						?.focus();
+				} }
+			>
+				<option value="">No selection</option>
+				<option value="hasvalue">Has selection</option>
+			</select>
+		</div>
+	);
+};
+
+export const ValidatedCustomSelectControl = forwardRef( UnforwardedValidatedCustomSelectControl );