@wordpress/components 29.12.0 → 30.0.0

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

@@ -0,0 +1,100 @@
+/**
+ * WordPress dependencies
+ */
+import { useState } from '@wordpress/element';
+
+/**
+ * External dependencies
+ */
+import type { Meta, StoryObj } from '@storybook/react';
+
+/**
+ * Internal dependencies
+ */
+import { ValidatedInputControl } from '..';
+import { formDecorator } from './story-utils';
+import type { ControlWithError } from '../../control-with-error';
+
+const meta: Meta< typeof ControlWithError > = {
+	title: 'Components (Experimental)/Validated Form Controls/Overview',
+	tags: [ 'status-private' ],
+	decorators: formDecorator,
+};
+export default meta;
+
+type Story = StoryObj< typeof ControlWithError >;
+
+/**
+ * When there are multiple controls with errors, attempting to submit will
+ * move focus to the first control with an error.
+ */
+export const WithMultipleControls: Story = {
+	render: function Template() {
+		const [ text, setText ] = useState( '' );
+		const [ text2, setText2 ] = useState( '' );
+
+		return (
+			<>
+				<ValidatedInputControl
+					label="Text"
+					required
+					value={ text }
+					help="The word 'error' will trigger an error."
+					customValidator={ ( value ) => {
+						if ( value?.toLowerCase() === 'error' ) {
+							return 'The word "error" is not allowed.';
+						}
+						return undefined;
+					} }
+					onChange={ ( value ) => setText( value ?? '' ) }
+				/>
+				<ValidatedInputControl
+					label="Text"
+					required
+					value={ text2 }
+					help="The word 'error' will trigger an error."
+					customValidator={ ( value ) => {
+						if ( value?.toLowerCase() === 'error' ) {
+							return 'The word "error" is not allowed.';
+						}
+						return undefined;
+					} }
+					onChange={ ( value ) => setText2( value ?? '' ) }
+				/>
+			</>
+		);
+	},
+};
+
+/**
+ * Help text can be configured to be hidden when a custom error is reported. Whether to opt for this approach
+ * will depend on context.
+ */
+export const WithHelpTextReplacement: Story = {
+	render: function Template() {
+		const [ text, setText ] = useState( '' );
+		const [ hasCustomError, setHasCustomError ] = useState( false );
+
+		return (
+			<ValidatedInputControl
+				label="Text"
+				required
+				value={ text }
+				help={
+					hasCustomError
+						? undefined
+						: 'The word "error" is not allowed.'
+				}
+				customValidator={ ( value ) => {
+					if ( value?.toLowerCase() === 'error' ) {
+						setHasCustomError( true );
+						return 'The word "error" is not allowed.';
+					}
+					setHasCustomError( false );
+					return undefined;
+				} }
+				onChange={ ( value ) => setText( value ?? '' ) }
+			/>
+		);
+	},
+};

package/src/validated-form-controls/components/stories/radio-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 { ValidatedRadioControl } from '../radio-control';
+import { formDecorator } from './story-utils';
+
+const meta: Meta< typeof ValidatedRadioControl > = {
+	title: 'Components (Experimental)/Validated Form Controls/ValidatedRadioControl',
+	component: ValidatedRadioControl,
+	tags: [ 'status-private' ],
+	decorators: formDecorator,
+	args: { onChange: () => {} },
+	argTypes: {
+		selected: { control: false },
+	},
+};
+export default meta;
+
+export const Default: StoryObj< typeof ValidatedRadioControl > = {
+	render: function Template( { onChange, ...args } ) {
+		const [ selected, setSelected ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedRadioControl
+				>[ 'selected' ]
+			>();
+
+		return (
+			<ValidatedRadioControl
+				{ ...args }
+				selected={ selected }
+				onChange={ ( value ) => {
+					setSelected( value );
+					onChange?.( value );
+				} }
+			/>
+		);
+	},
+};
+Default.args = {
+	required: true,
+	label: 'Radio',
+	help: 'Option B is not allowed.',
+	options: [
+		{ label: 'Option A', value: 'a' },
+		{ label: 'Option B (not allowed)', value: 'b' },
+	],
+	customValidator: ( value ) => {
+		if ( value === 'b' ) {
+			return 'Option B is not allowed.';
+		}
+		return undefined;
+	},
+};

package/src/validated-form-controls/components/stories/range-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 { formDecorator } from './story-utils';
+import { ValidatedRangeControl } from '../range-control';
+
+const meta: Meta< typeof ValidatedRangeControl > = {
+	title: 'Components (Experimental)/Validated Form Controls/ValidatedRangeControl',
+	component: ValidatedRangeControl,
+	tags: [ 'status-private' ],
+	decorators: formDecorator,
+	args: { onChange: () => {} },
+	argTypes: {
+		value: { control: false },
+	},
+};
+export default meta;
+
+export const Default: StoryObj< typeof ValidatedRangeControl > = {
+	render: function Template( { onChange, ...args } ) {
+		const [ value, setValue ] =
+			useState<
+				React.ComponentProps< typeof ValidatedRangeControl >[ 'value' ]
+			>();
+
+		return (
+			<ValidatedRangeControl
+				{ ...args }
+				value={ value }
+				onChange={ ( newValue ) => {
+					setValue( newValue );
+					onChange?.( newValue );
+				} }
+			/>
+		);
+	},
+};
+Default.args = {
+	required: true,
+	label: 'Range',
+	help: 'Odd numbers are not allowed.',
+	min: 0,
+	max: 20,
+	customValidator: ( value ) => {
+		if ( value && value % 2 !== 0 ) {
+			return 'Choose an even number.';
+		}
+		return undefined;
+	},
+};

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