@wordpress/components 29.13.1-next.719a03cbe.0 → 30.1.1-next.46f643fa0.0

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 />

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