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

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

@@ -0,0 +1,77 @@
+/**
+ * WordPress dependencies
+ */
+import { useMergeRefs } from '@wordpress/compose';
+import { forwardRef, useEffect, useRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { ControlWithError } from '../control-with-error';
+import type { ValidatedControlProps } from './types';
+import ComboboxControl from '../../combobox-control';
+import type { ComboboxControlProps } from '../../combobox-control/types';
+
+type Value = ComboboxControlProps[ 'value' ];
+
+const UnforwardedValidatedComboboxControl = (
+	{
+		required,
+		customValidator,
+		onChange,
+		markWhenOptional,
+		...restProps
+	}: Omit<
+		React.ComponentProps< typeof ComboboxControl >,
+		'__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
+);

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

@@ -0,0 +1,86 @@
+/**
+ * WordPress dependencies
+ */
+import { forwardRef, useRef } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import { ControlWithError } from '../control-with-error';
+import type { ValidatedControlProps } from './types';
+import CustomSelectControl from '../../custom-select-control';
+import type {
+	CustomSelectOption,
+	CustomSelectProps,
+} from '../../custom-select-control/types';
+
+type CustomSelectControlProps = CustomSelectProps< CustomSelectOption >;
+
+type Value = CustomSelectControlProps[ 'value' ];
+
+const UnforwardedValidatedCustomSelectControl = (
+	{
+		required,
+		customValidator,
+		onChange,
+		markWhenOptional,
+		...restProps
+	}: Omit<
+		React.ComponentProps< typeof CustomSelectControl >,
+		'__next40pxDefaultSize'
+	> &
+		ValidatedControlProps< Value >,
+	forwardedRef: React.ForwardedRef< HTMLDivElement >
+) => {
+	const validityTargetRef = useRef< HTMLSelectElement >( null );
+	const valueRef = useRef< Value >( restProps.value );
+
+	return (
+		<div
+			className="components-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="components-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
+);

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

@@ -0,0 +1,12 @@
+export * from './checkbox-control';
+export * from './combobox-control';
+export * from './custom-select-control';
+export * from './input-control';
+export * from './number-control';
+export * from './radio-control';
+export * from './range-control';
+export * from './select-control';
+export * from './text-control';
+export * from './textarea-control';
+export * from './toggle-control';
+export * from './toggle-group-control';

package/src/validated-form-controls/components/input-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 InputControl from '../../input-control';
+import type { InputControlProps } from '../../input-control/types';
+
+type Value = InputControlProps[ 'value' ];
+
+const UnforwardedValidatedInputControl = (
+	{
+		required,
+		customValidator,
+		onChange,
+		markWhenOptional,
+		...restProps
+	}: Omit<
+		React.ComponentProps< typeof InputControl >,
+		'__next40pxDefaultSize'
+	> &
+		ValidatedControlProps< InputControlProps[ '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 }
+		>
+			<InputControl
+				__next40pxDefaultSize
+				ref={ mergedRefs }
+				onChange={ ( value, ...args ) => {
+					valueRef.current = value;
+					onChange?.( value, ...args );
+				} }
+				{ ...restProps }
+			/>
+		</ControlWithError>
+	);
+};
+
+export const ValidatedInputControl = forwardRef(
+	UnforwardedValidatedInputControl
+);

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