@wordpress/components 38.0.0 → 40.0.0

package/src/v-stack/types.ts

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import type { CSSProperties } from 'react';
-
-/**
- * Internal dependencies
- */
 import type { HStackAlignment, Props as HStackProps } from '../h-stack/types';
 
 export type VStackProps = Omit< HStackProps, 'alignment' | 'spacing' > & {

package/src/validated-form-controls/components/content-editable-control.tsx

@@ -1,17 +1,6 @@
-/**
- * External dependencies
- */
 import clsx from 'clsx';
-
-/**
- * WordPress dependencies
- */
 import { forwardRef, useRef } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
-import { ControlWithError } from '../control-with-error';
+import { ControlWithError } from '@wordpress/ui';
 import type { ValidatedControlProps } from './types';
 import ContentEditableControl from '../../content-editable-control';
 
@@ -45,6 +34,7 @@ const UnforwardedValidatedContentEditableControl = (
 	return (
 		<div className="components-validated-control__wrapper-with-error-delegate">
 			<ControlWithError
+				className="components-validated-control"
 				required={ required }
 				markWhenOptional={ markWhenOptional }
 				customValidity={ customValidity }

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

@@ -1,12 +1,5 @@
-/**
- * WordPress dependencies
- */
 import { forwardRef, useRef } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
-import { ControlWithError } from '../control-with-error';
+import { ControlWithError } from '@wordpress/ui';
 import type { ValidatedControlProps } from './types';
 import CustomSelectControl from '../../custom-select-control';
 
@@ -28,6 +21,7 @@ const UnforwardedValidatedCustomSelectControl = (
 			ref={ forwardedRef }
 		>
 			<ControlWithError
+				className="components-validated-control"
 				required={ required }
 				markWhenOptional={ markWhenOptional }
 				customValidity={ customValidity }

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

@@ -1,14 +1,5 @@
-export * from './checkbox-control';
-export * from './combobox-control';
 export * from './custom-select-control';
-export * from './form-token-field';
 export * from './input-control';
-export * from './number-control';
-export * from './radio-control';
 export * from './range-control';
 export * from './content-editable-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

@@ -1,13 +1,7 @@
-/**
- * WordPress dependencies
- */
 import { forwardRef, useRef } from '@wordpress/element';
 import { useMergeRefs } from '@wordpress/compose';
-
-/**
- * Internal dependencies
- */
-import { ControlWithError } from '../control-with-error';
+import deprecated from '@wordpress/deprecated';
+import { ControlWithError } from '@wordpress/ui';
 import type { ValidatedControlProps } from './types';
 import InputControl from '../../input-control';
 
@@ -20,11 +14,18 @@ const UnforwardedValidatedInputControl = (
 	}: React.ComponentProps< typeof InputControl > & ValidatedControlProps,
 	forwardedRef: React.ForwardedRef< HTMLInputElement >
 ) => {
+	deprecated( 'wp.components.privateApis.ValidatedInputControl', {
+		since: '7.2',
+		alternative: 'ValidatedInputControl from @wordpress/ui',
+		hint: 'This private API will be completely removed within a few Gutenberg plugin releases.',
+	} );
+
 	const validityTargetRef = useRef< HTMLInputElement >( null );
 	const mergedRefs = useMergeRefs( [ forwardedRef, validityTargetRef ] );
 
 	return (
 		<ControlWithError
+			className="components-validated-control"
 			required={ required }
 			markWhenOptional={ markWhenOptional }
 			customValidity={ customValidity }

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

@@ -1,13 +1,6 @@
-/**
- * WordPress dependencies
- */
 import { useMergeRefs } from '@wordpress/compose';
 import { forwardRef, useRef } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
-import { ControlWithError } from '../control-with-error';
+import { ControlWithError } from '@wordpress/ui';
 import type { ValidatedControlProps } from './types';
 import RangeControl from '../../range-control';
 
@@ -25,6 +18,7 @@ const UnforwardedValidatedRangeControl = (
 
 	return (
 		<ControlWithError
+			className="components-validated-control"
 			required={ required }
 			markWhenOptional={ markWhenOptional }
 			customValidity={ customValidity }

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

@@ -1,19 +1,15 @@
-/**
- * WordPress dependencies
- */
 import { useState } from '@wordpress/element';
-
-/**
- * External dependencies
- */
 import type { StoryObj, Meta } from '@storybook/react-vite';
-/**
- * Internal dependencies
- */
 import { formDecorator } from './story-utils';
 import { ValidatedContentEditableControl } from '../content-editable-control';
 
 const meta: Meta< typeof ValidatedContentEditableControl > = {
+	parameters: {
+		// FIXME: Contenteditable control is unlabeled (label).
+		// See: https://github.com/WordPress/gutenberg/issues/81596
+		a11y: { test: 'todo' },
+	},
+
 	title: 'Components/Selection & Input/Validated Form Controls/ValidatedContentEditableControl',
 	id: 'components-validatedcontenteditablecontrol',
 	component: ValidatedContentEditableControl,

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

@@ -1,20 +1,15 @@
-/**
- * WordPress dependencies
- */
 import { useState } from '@wordpress/element';
-
-/**
- * External dependencies
- */
 import type { StoryObj, Meta } from '@storybook/react-vite';
-
-/**
- * Internal dependencies
- */
 import { ValidatedCustomSelectControl } from '../custom-select-control';
 import { formDecorator } from './story-utils';
 
 const meta: Meta< typeof ValidatedCustomSelectControl > = {
+	parameters: {
+		// FIXME: Select lacks an accessible name in this story (select-name).
+		// See: https://github.com/WordPress/gutenberg/issues/81596
+		a11y: { test: 'todo' },
+	},
+
 	title: 'Components/Selection & Input/Validated Form Controls/ValidatedCustomSelectControl',
 	id: 'components-validatedcustomselectcontrol',
 	component: ValidatedCustomSelectControl,

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

@@ -1,52 +1,9 @@
-import { ArgTypes, Meta, Stories } from '@storybook/addon-docs/blocks';
-import * as OverviewStories from './overview.story';
-import { ValidatedInputControl } from '..';
+import { Meta } from '@storybook/addon-docs/blocks';
 
-<Meta of={ OverviewStories } title="Components/Selection & Input/Validated Form Controls/Overview" />
+<Meta title="Components/Selection & Input/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.
+Documentation for validated form controls has moved to `@wordpress/ui`.
 
-## 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', 'customValidity' ] } />
-
-## 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 show validation messages at an arbitrary point in time, unless the fields are wrapped in a `form` element. Currently, when to show validation messages to the user are handled by the component — any messages are first made visible on `blur` after the field is considered "touched", or if the user tries to submit the enclosing `form`. Messages can also be triggered to show at any time by calling the `reportValidity()` method on 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`, `CustomSelectControl`, and `FormTokenField` 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 />
+See the [Validated Form Controls overview](?path=/docs/design-system-form-with-validation-overview--docs) in the Design System docs.

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

@@ -1,16 +1,5 @@
-/**
- * WordPress dependencies
- */
 import { useState } from '@wordpress/element';
-
-/**
- * External dependencies
- */
 import type { StoryObj, Meta } from '@storybook/react-vite';
-
-/**
- * Internal dependencies
- */
 import { formDecorator } from './story-utils';
 import { ValidatedRangeControl } from '../range-control';
 

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

@@ -1,15 +1,4 @@
-/**
- * WordPress dependencies
- */
-
-/**
- * External dependencies
- */
 import type { Meta } from '@storybook/react-vite';
-
-/**
- * Internal dependencies
- */
 import Button from '../../../button';
 
 export const formDecorator: Meta[ 'decorators' ] = ( Story ) => (

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

@@ -1,13 +1,7 @@
-/**
- * WordPress dependencies
- */
 import { forwardRef, useRef } from '@wordpress/element';
 import { useMergeRefs } from '@wordpress/compose';
-
-/**
- * Internal dependencies
- */
-import { ControlWithError } from '../control-with-error';
+import deprecated from '@wordpress/deprecated';
+import { ControlWithError } from '@wordpress/ui';
 import type { ValidatedControlProps } from './types';
 import TextareaControl from '../../textarea-control';
 
@@ -20,11 +14,18 @@ const UnforwardedValidatedTextareaControl = (
 	}: React.ComponentProps< typeof TextareaControl > & ValidatedControlProps,
 	forwardedRef: React.ForwardedRef< HTMLTextAreaElement >
 ) => {
+	deprecated( 'wp.components.privateApis.ValidatedTextareaControl', {
+		since: '7.2',
+		alternative: 'ValidatedTextareaControl from @wordpress/ui',
+		hint: 'This private API will be completely removed within a few Gutenberg plugin releases.',
+	} );
+
 	const validityTargetRef = useRef< HTMLTextAreaElement >( null );
 	const mergedRefs = useMergeRefs( [ forwardedRef, validityTargetRef ] );
 
 	return (
 		<ControlWithError
+			className="components-validated-control"
 			required={ required }
 			markWhenOptional={ markWhenOptional }
 			customValidity={ customValidity }

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

@@ -1,2 +1 @@
 export * from './components';
-export * from './control-with-error';

package/src/validated-form-controls/style.scss

@@ -1,27 +1,23 @@
 @use "@wordpress/base-styles/colors" as *;
-@use "@wordpress/base-styles/variables" as *;
-@use "../utils/theme-variables" as *;
+
+%red-focus-ring {
+	--focus-color: #{ $alert-red };
+}
 
 .components-validated-control {
 	// For components based on InputBase
 	&:has(:is(input, select):invalid[data-validity-visible])
 	.components-input-control__backdrop {
-		--wp-components-color-accent: #{$alert-red};
-		border-color: $alert-red;
-	}
+		@extend %red-focus-ring;
 
-	// For TextControl, TextareaControl
-	:is(textarea, input[type="text"]):invalid[data-validity-visible] {
-		--wp-admin-theme-color: #{$alert-red};
-		--wp-components-color-accent: #{$alert-red};
 		border-color: $alert-red;
 	}
 
-	// For ComboboxControl
-	.components-combobox-control__suggestions-container:has(
-	input:invalid[data-validity-visible]
-):not(:has([aria-expanded="true"])) {
-		--wp-admin-theme-color: #{$alert-red};
+	// For TextareaControl
+	textarea:invalid[data-validity-visible] {
+		@extend %red-focus-ring;
+
+		border-color: $alert-red;
 	}
 }
 
@@ -30,25 +26,16 @@
 
 	// For CustomSelectControl
 	&:has(select:invalid[data-validity-visible]) .components-input-control__backdrop {
-		--wp-components-color-accent: #{$alert-red};
-		border-color: $alert-red;
-	}
-
-	// For ToggleGroupControl
-	&:has(input[type="radio"]:invalid[data-validity-visible]) {
-		--wp-components-color-accent: #{$alert-red};
-	}
+		@extend %red-focus-ring;
 
-	// For FormTokenField
-	&:has(input:invalid[data-validity-visible]) .components-form-token-field__input-container:not(:has([aria-expanded="true"])) {
-		--wp-admin-theme-color: #{$alert-red};
 		border-color: $alert-red;
 	}
 
 	// For ContentEditableControl
 	&:has(input:invalid[data-validity-visible])
 	.components-validated-control__content-editable [role="textbox"] {
-		--wp-admin-theme-color: #{$alert-red};
+		@extend %red-focus-ring;
+
 		border-color: $alert-red;
 	}
 }
@@ -61,46 +48,3 @@
 	opacity: 0;
 	pointer-events: none;
 }
-
-.components-validated-control__indicator {
-	display: flex;
-	align-items: flex-start;
-	gap: 4px;
-	margin: 8px 0 0;
-	font-family: $font-family-body;
-	font-size: $font-size-small;
-	line-height: 16px; // matches the icon size
-	color: $components-color-gray-700;
-	animation:
-		components-validated-control__indicator-jump 0.2s
-		cubic-bezier(0.68, -0.55, 0.27, 1.55);
-
-	&.is-invalid {
-		color: $alert-red;
-	}
-
-	&.is-valid {
-		color: color-mix(in srgb, $black 30%, $alert-green);
-	}
-}
-
-.components-validated-control__indicator-icon {
-	flex-shrink: 0;
-}
-
-.components-validated-control__indicator-spinner {
-	margin: 2px;
-	width: $grid-unit-15;
-	height: $grid-unit-15;
-}
-
-@keyframes components-validated-control__indicator-jump {
-	0% {
-		transform: translateY(-4px);
-		opacity: 0;
-	}
-	100% {
-		transform: translateY(0);
-		opacity: 1;
-	}
-}

package/src/validated-form-controls/test/input-control.tsx

@@ -2,6 +2,18 @@ import { render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { ValidatedInputControl } from '../components';
 
+describe( 'Shows a deprecation warning', () => {
+	it( 'ValidatedInputControl', () => {
+		render(
+			<ValidatedInputControl label="URL" help="Enter a full URL." />
+		);
+
+		expect( console ).toHaveWarnedWith(
+			'wp.components.privateApis.ValidatedInputControl is deprecated since version 7.2. Please use ValidatedInputControl from @wordpress/ui instead. Note: This private API will be completely removed within a few Gutenberg plugin releases.'
+		);
+	} );
+} );
+
 describe( 'ValidatedInputControl', () => {
 	it( 'should preserve the help description', () => {
 		render(

package/src/validated-form-controls/test/textarea-control.tsx

@@ -2,6 +2,23 @@ import { render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { ValidatedTextareaControl } from '../components';
 
+describe( 'Shows a deprecation warning', () => {
+	it( 'ValidatedTextareaControl', () => {
+		render(
+			<ValidatedTextareaControl
+				label="Bio"
+				help="A short bio."
+				onChange={ () => {} }
+				value=""
+			/>
+		);
+
+		expect( console ).toHaveWarnedWith(
+			'wp.components.privateApis.ValidatedTextareaControl is deprecated since version 7.2. Please use ValidatedTextareaControl from @wordpress/ui instead. Note: This private API will be completely removed within a few Gutenberg plugin releases.'
+		);
+	} );
+} );
+
 describe( 'ValidatedTextareaControl', () => {
 	it( 'should preserve the help description', () => {
 		render(

package/src/view/README.md

@@ -1,8 +1,6 @@
 # View
 
-<div class="callout callout-alert">
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-</div>
+<p class="callout callout-alert">This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.</p>
 
 `View` is a core component that renders everything in the library. It is the principle component in the entire library.
 

package/src/view/component.tsx

@@ -1,11 +1,4 @@
-/**
- * WordPress dependencies
- */
 import { forwardRef } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
 import type { WordPressComponentProps } from '../context';
 import { PolymorphicElement } from '../utils/polymorphic-element';
 

package/src/view/stories/index.story.tsx

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import type { Meta, StoryFn } from '@storybook/react-vite';
-
-/**
- * Internal dependencies
- */
 import { View } from '..';
 
 const meta: Meta< typeof View > = {

package/src/view/test/index.js

@@ -1,16 +1,5 @@
-/**
- * External dependencies
- */
 import { render, screen } from '@testing-library/react';
-
-/**
- * WordPress dependencies
- */
 import { forwardRef } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
 import { View } from '../index';
 
 describe( 'props', () => {

package/src/visually-hidden/component.tsx

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import type { ForwardedRef } from 'react';
-
-/**
- * Internal dependencies
- */
 import type { WordPressComponentProps } from '../context';
 import { useContextSystem, contextConnect } from '../context';
 import { visuallyHidden } from './styles';

package/src/visually-hidden/styles.ts

@@ -1,6 +1,3 @@
-/**
- * External dependencies
- */
 import type { CSSProperties } from 'react';
 
 export const visuallyHidden: CSSProperties = {

package/src/visually-hidden/types.ts

@@ -1,6 +1,3 @@
-/**
- * External dependencies
- */
 import type { ReactNode } from 'react';
 
 export type VisuallyHiddenProps = {

package/src/z-stack/README.md

@@ -1,8 +1,6 @@
 # ZStack
 
-<div class="callout callout-alert">
-This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.
-</div>
+<p class="callout callout-alert">This feature is still experimental. “Experimental” means this is an early implementation subject to drastic and breaking changes.</p>
 
 ## Usage
 

package/src/z-stack/component.tsx

@@ -1,19 +1,10 @@
-/**
- * External dependencies
- */
+import clsx from 'clsx';
 import type { ForwardedRef } from 'react';
-
-/**
- * WordPress dependencies
- */
 import { isValidElement } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
 import { getValidChildren } from '../utils/get-valid-children';
 import { contextConnect, useContextSystem } from '../context';
-import { ZStackView, ZStackChildView } from './styles';
+import { PolymorphicElement } from '../utils/polymorphic-element';
+import styles from './style.module.scss';
 import type { ZStackProps } from './types';
 import type { WordPressComponentProps } from '../context';
 
@@ -42,25 +33,31 @@ function UnconnectedZStack(
 		const key = isValidElement( child ) ? child.key : index;
 
 		return (
-			<ZStackChildView
-				offsetAmount={ offsetAmount }
-				zIndex={ zIndex }
+			<div
+				className={ styles.child }
+				style={ {
+					'--z-stack-offset': `${ offsetAmount }px`,
+					'--z-stack-z-index': zIndex,
+				} }
 				key={ key }
 			>
 				{ child }
-			</ZStackChildView>
+			</div>
 		);
 	} );
 
 	return (
-		<ZStackView
+		<PolymorphicElement
 			{ ...otherProps }
-			className={ className }
-			isLayered={ isLayered }
+			className={ clsx(
+				styles[ 'z-stack' ],
+				isLayered && styles.layered,
+				className
+			) }
 			ref={ forwardedRef }
 		>
 			{ clonedChildren }
-		</ZStackView>
+		</PolymorphicElement>
 	);
 }
 

package/src/z-stack/stories/index.story.tsx

@@ -1,12 +1,5 @@
-/**
- * External dependencies
- */
 import type { CSSProperties } from 'react';
 import type { Meta, StoryFn } from '@storybook/react-vite';
-
-/**
- * Internal dependencies
- */
 import { Elevation } from '../../elevation';
 import { View } from '../../view';
 import { ZStack } from '..';