@wordpress/components 30.2.1-next.0f6f9d12c.0 → 30.2.2-next.e256d081a.0

package/build-types/validated-form-controls/components/types.d.ts

@@ -10,18 +10,29 @@ export type ValidatedControlProps<V> = {
      */
     markWhenOptional?: boolean;
     /**
-     * A function that returns a custom validity message when applicable. This error message will be applied to the
-     * underlying element using the native [`setCustomValidity()` method](https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/setCustomValidity).
-     * This means the custom validator will be run _in addition_ to any other HTML attribute-based validation, and
-     * will be prioritized over any existing validity messages dictated by the HTML attributes.
-     * An empty string or `undefined` return value will clear any existing custom validity message.
+     * Optional callback to run when the input should be validated. Use this to set
+     * a `customValidity` as necessary.
      *
-     * Make sure you don't programatically pass a value (such as an initial value) to the control component
-     * that fails this validator, because the validator will only run for user-initiated changes.
+     * Always prefer using standard HTML attributes like `required` and `min`/`max` over
+     * custom validators when possible, as they are simpler and have localized error messages built in.
+     */
+    onValidate?: (currentValue: V) => void;
+    /**
+     * Show a custom message based on the validation status.
      *
-     * Always prefer using standard HTML attributes like `required` and `min`/`max` over custom validators
-     * when possible, as they are simpler and have localized error messages built in.
+     * - When `type` is `invalid`, the message will be applied to the underlying element using the
+     * native [`setCustomValidity()` method](https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/setCustomValidity).
+     * This means the custom message will be prioritized over any existing validity messages
+     * triggered by HTML attribute-based validation.
+     * - When `type` is `validating` or `valid`, the custom validity message of the underlying element
+     * will be cleared. If there are no remaining validity messages triggered by HTML attribute-based validation,
+     * the message will be presented as a status indicator rather than an error. These indicators are intended
+     * for asynchronous validation calls that may take more than 1 second to complete.
+     * Otherwise, custom errors can simply be cleared by setting the `customValidity` prop to `undefined`.
      */
-    customValidator?: (currentValue: V) => string | void;
+    customValidity?: {
+        type: 'validating' | 'valid' | 'invalid';
+        message: string;
+    };
 };
 //# sourceMappingURL=types.d.ts.map

package/build-types/validated-form-controls/components/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/validated-form-controls/components/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,qBAAqB,CAAE,CAAC,IAAK;IACxC;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;;;;;;OAYG;IAGH,eAAe,CAAC,EAAE,CAAE,YAAY,EAAE,CAAC,KAAM,MAAM,GAAG,IAAI,CAAC;CACvD,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/validated-form-controls/components/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,qBAAqB,CAAE,CAAC,IAAK;IACxC;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,CAAE,YAAY,EAAE,CAAC,KAAM,IAAI,CAAC;IACzC;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,EAAE;QAChB,IAAI,EAAE,YAAY,GAAG,OAAO,GAAG,SAAS,CAAC;QACzC,OAAO,EAAE,MAAM,CAAC;KAChB,CAAC;CACF,CAAC"}

package/build-types/validated-form-controls/control-with-error.d.ts

@@ -1,3 +1,4 @@
+import type { ValidatedControlProps } from './components/types';
 /**
  * HTML elements that support the Constraint Validation API.
  *
@@ -17,12 +18,10 @@ export declare const ControlWithError: import("react").ForwardRefExoticComponent
      */
     markWhenOptional?: boolean;
     /**
-     * A function that returns a custom validity message when applicable.
-     *
-     * This message will be applied to the element returned by `getValidityTarget`.
-     * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/setCustomValidity
+     * The callback to run when the input should be validated.
      */
-    customValidator?: () => string | void;
+    onValidate?: () => void;
+    customValidity?: ValidatedControlProps<unknown>["customValidity"];
     /**
      * A function that returns the actual element on which the validity data should be applied.
      */

package/build-types/validated-form-controls/control-with-error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"control-with-error.d.ts","sourceRoot":"","sources":["../../src/validated-form-controls/control-with-error.tsx"],"names":[],"mappings":"AA6CA;;;;;;;GAOG;AACH,KAAK,cAAc,GAChB,mBAAmB,GACnB,gBAAgB,GAChB,iBAAiB,GACjB,mBAAmB,CAAC;AA4IvB,eAAO,MAAM,gBAAgB;IAlI3B;;OAEG;eACQ,OAAO;IAClB;;OAEG;uBACgB,OAAO;IAC1B;;;;;OAKG;sBACe,MAAM,MAAM,GAAG,IAAI;IACrC;;OAEG;uBACgB,MAAM,cAAc,GAAG,IAAI,GAAG,SAAS;IAC1D;;OAEG;;kDA6GoE,CAAC"}
+{"version":3,"file":"control-with-error.d.ts","sourceRoot":"","sources":["../../src/validated-form-controls/control-with-error.tsx"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAyBhE;;;;;;;GAOG;AACH,KAAK,cAAc,GAChB,mBAAmB,GACnB,gBAAgB,GAChB,iBAAiB,GACjB,mBAAmB,CAAC;AAoMvB,eAAO,MAAM,gBAAgB;IAzL3B;;OAEG;eACQ,OAAO;IAClB;;OAEG;uBACgB,OAAO;IAC1B;;OAEG;iBACU,MAAM,IAAI;qBACN,qBAAqB,CAAE,OAAO,CAAE,CAAE,gBAAgB,CAAE;IACrE;;OAEG;uBACgB,MAAM,cAAc,GAAG,IAAI,GAAG,SAAS;IAC1D;;OAEG;;kDAsKoE,CAAC"}

package/build-types/validated-form-controls/test/control-with-error.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=control-with-error.d.ts.map

package/build-types/validated-form-controls/test/control-with-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-with-error.d.ts","sourceRoot":"","sources":["../../../src/validated-form-controls/test/control-with-error.tsx"],"names":[],"mappings":""}

package/build-types/validated-form-controls/validity-indicator.d.ts

@@ -0,0 +1,5 @@
+export declare function ValidityIndicator({ type, message, }: {
+    type: 'validating' | 'valid' | 'invalid';
+    message?: string;
+}): import("react").JSX.Element;
+//# sourceMappingURL=validity-indicator.d.ts.map

package/build-types/validated-form-controls/validity-indicator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validity-indicator.d.ts","sourceRoot":"","sources":["../../src/validated-form-controls/validity-indicator.tsx"],"names":[],"mappings":"AAgBA,wBAAgB,iBAAiB,CAAE,EAClC,IAAI,EACJ,OAAO,GACP,EAAE;IACF,IAAI,EAAE,YAAY,GAAG,OAAO,GAAG,SAAS,CAAC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,+BAyBA"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/components",
-	"version": "30.2.1-next.0f6f9d12c.0",
+	"version": "30.2.2-next.e256d081a.0",
 	"description": "UI components for WordPress.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -44,23 +44,23 @@
 		"@types/gradient-parser": "1.1.0",
 		"@types/highlight-words-core": "1.2.1",
 		"@use-gesture/react": "^10.3.1",
-		"@wordpress/a11y": "^4.28.1-next.0f6f9d12c.0",
-		"@wordpress/compose": "^7.28.1-next.0f6f9d12c.0",
-		"@wordpress/date": "^5.28.1-next.0f6f9d12c.0",
-		"@wordpress/deprecated": "^4.28.1-next.0f6f9d12c.0",
-		"@wordpress/dom": "^4.28.1-next.0f6f9d12c.0",
-		"@wordpress/element": "^6.28.1-next.0f6f9d12c.0",
-		"@wordpress/escape-html": "^3.28.1-next.0f6f9d12c.0",
-		"@wordpress/hooks": "^4.28.1-next.0f6f9d12c.0",
-		"@wordpress/html-entities": "^4.28.1-next.0f6f9d12c.0",
-		"@wordpress/i18n": "^6.1.1-next.0f6f9d12c.0",
-		"@wordpress/icons": "^10.28.2-next.0f6f9d12c.0",
-		"@wordpress/is-shallow-equal": "^5.28.1-next.0f6f9d12c.0",
-		"@wordpress/keycodes": "^4.28.1-next.0f6f9d12c.0",
-		"@wordpress/primitives": "^4.28.1-next.0f6f9d12c.0",
-		"@wordpress/private-apis": "^1.28.1-next.0f6f9d12c.0",
-		"@wordpress/rich-text": "^7.28.1-next.0f6f9d12c.0",
-		"@wordpress/warning": "^3.28.1-next.0f6f9d12c.0",
+		"@wordpress/a11y": "^4.29.1-next.e256d081a.0",
+		"@wordpress/compose": "^7.29.1-next.e256d081a.0",
+		"@wordpress/date": "^5.30.1-next.e256d081a.0",
+		"@wordpress/deprecated": "^4.29.1-next.e256d081a.0",
+		"@wordpress/dom": "^4.29.1-next.e256d081a.0",
+		"@wordpress/element": "^6.29.1-next.e256d081a.0",
+		"@wordpress/escape-html": "^3.29.1-next.e256d081a.0",
+		"@wordpress/hooks": "^4.29.1-next.e256d081a.0",
+		"@wordpress/html-entities": "^4.29.1-next.e256d081a.0",
+		"@wordpress/i18n": "^6.2.1-next.e256d081a.0",
+		"@wordpress/icons": "^10.29.1-next.e256d081a.0",
+		"@wordpress/is-shallow-equal": "^5.29.1-next.e256d081a.0",
+		"@wordpress/keycodes": "^4.29.1-next.e256d081a.0",
+		"@wordpress/primitives": "^4.29.1-next.e256d081a.0",
+		"@wordpress/private-apis": "^1.29.1-next.e256d081a.0",
+		"@wordpress/rich-text": "^7.29.1-next.e256d081a.0",
+		"@wordpress/warning": "^3.29.1-next.e256d081a.0",
 		"change-case": "^4.1.2",
 		"clsx": "^2.1.1",
 		"colord": "^2.7.0",
@@ -86,5 +86,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "7d4f4367e2f76deddf4a09b540e6b2f9f4c3fe9f"
+	"gitHead": "7d529ba9a461795d5f1572d3856de33f744287c2"
 }

package/src/calendar/style.scss

@@ -1,9 +1,9 @@
 /* Root of the component. */
 // Internal variables
 $wp-components-calendar-outline-focus: var(--wp-admin-border-width-focus) solid $components-color-accent;
-$wp-components-calendar-button-height: 2rem;
-$wp-components-calendar-button-width: 2rem;
-$wp-components-calendar-nav-height: 2rem;
+$wp-components-calendar-button-height: $grid-unit-40;
+$wp-components-calendar-button-width: $grid-unit-40;
+$wp-components-calendar-nav-height: $grid-unit-40;
 $wp-components-calendar-range-middle-background-color: color-mix(in srgb, $components-color-accent 4%, transparent);
 $wp-components-calendar-preview-border-color: color-mix(in srgb, $components-color-accent 16%, transparent);
 
@@ -13,10 +13,10 @@ $wp-components-calendar-preview-border-color: color-mix(in srgb, $components-col
 	position: relative; /* Required to position the navigation toolbar. */
 	box-sizing: border-box;
 	display: inline flow-root;
-	color: $gray-900;
-	background-color: $white;
-	font-size: 13px;
-	font-weight: 400;
+	color: $components-color-foreground;
+	background-color: $components-color-background;
+	font-size: $font-size-medium;
+	font-weight: $font-weight-regular;
 	z-index: 0; // Create a stacking context and render on top of the background.
 
 	*,
@@ -35,7 +35,7 @@ $wp-components-calendar-preview-border-color: color-mix(in srgb, $components-col
 	// date follows the same color as the button's text, since the button
 	// inherits its text color.
 	&:has(.components-calendar__day-button:disabled) {
-		color: $gray-600;
+		color: $components-color-disabled;
 	}
 	&:has(.components-calendar__day-button:hover:not(:disabled)),
 	&:has(.components-calendar__day-button:focus-visible) {
@@ -57,7 +57,7 @@ $wp-components-calendar-preview-border-color: color-mix(in srgb, $components-col
 	height: $wp-components-calendar-button-height;
 
 	border: none;
-	border-radius: 2px;
+	border-radius: $radius-small;
 
 	font: inherit;
 	font-variant-numeric: tabular-nums;
@@ -73,7 +73,7 @@ $wp-components-calendar-preview-border-color: color-mix(in srgb, $components-col
 		z-index: -1;
 		inset: 0;
 		border: none; // No default border to avoid polluting high-contrast mode.
-		border-radius: 2px;
+		border-radius: $radius-small;
 	}
 
 	// Use the button's ::after to show the selection preview.
@@ -117,7 +117,7 @@ $wp-components-calendar-preview-border-color: color-mix(in srgb, $components-col
 .components-calendar__button-next,
 .components-calendar__button-previous {
 	border: none;
-	border-radius: 2px;
+	border-radius: $radius-small;
 	background: none;
 	padding: 0;
 	margin: 0;
@@ -139,7 +139,7 @@ $wp-components-calendar-preview-border-color: color-mix(in srgb, $components-col
 	&[aria-disabled="true"] {
 		cursor: revert;
 
-		color: $gray-600;
+		color: $components-color-disabled;
 	}
 
 	&:focus-visible {
@@ -150,8 +150,8 @@ $wp-components-calendar-preview-border-color: color-mix(in srgb, $components-col
 .components-calendar__chevron {
 	display: inline-block;
 	fill: currentColor;
-	width: 16px;
-	height: 16px;
+	width: $grid-unit-20;
+	height: $grid-unit-20;
 }
 
 .components-calendar[dir="rtl"]
@@ -167,7 +167,7 @@ $wp-components-calendar-preview-border-color: color-mix(in srgb, $components-col
 	align-content: center;
 
 	height: $wp-components-calendar-nav-height;
-	margin-bottom: 12px;
+	margin-bottom: $grid-unit-15;
 }
 
 .components-calendar__months {
@@ -175,13 +175,13 @@ $wp-components-calendar-preview-border-color: color-mix(in srgb, $components-col
 	display: flex;
 	justify-content: center;
 	flex-wrap: wrap;
-	gap: 1rem;
+	gap: $grid-unit-20;
 	max-width: fit-content;
 }
 
 .components-calendar__month-grid {
 	border-collapse: separate;
-	border-spacing: 0 4px;
+	border-spacing: 0 $grid-unit-05;
 }
 
 .components-calendar__nav {
@@ -202,7 +202,7 @@ $wp-components-calendar-preview-border-color: color-mix(in srgb, $components-col
 	height: $wp-components-calendar-button-height;
 	padding: 0;
 
-	color: $gray-700;
+	color: $components-color-gray-700;
 	text-align: center;
 	text-transform: uppercase;
 }
@@ -227,12 +227,12 @@ $wp-components-calendar-preview-border-color: color-mix(in srgb, $components-col
 	.components-calendar__day-button,
 	.components-calendar__day-button:hover:not(:disabled)
 ) {
-		color: $white;
+		color: $components-color-foreground-inverted;
 	}
 
 	.components-calendar__day-button {
 		&::before {
-			background-color: $gray-900;
+			background-color: $components-color-foreground;
 			// Render a transparent border to highlight the selected day in
 			// forced-colors (high-contrast) mode, since the background is not
 			// visible.
@@ -240,11 +240,11 @@ $wp-components-calendar-preview-border-color: color-mix(in srgb, $components-col
 		}
 
 		&:disabled::before {
-			background-color: $gray-600;
+			background-color: $components-color-disabled;
 		}
 
 		&:hover:not(:disabled)::before {
-			background-color: $gray-800;
+			background-color: $components-color-gray-800;
 		}
 	}
 }

package/src/context/context-connect.ts

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { ForwardedRef, ReactChild, ReactNode } from 'react';
+import type { ForwardedRef, ReactElement, ReactNode } from 'react';
 
 /**
  * WordPress dependencies
@@ -114,7 +114,7 @@ function _contextConnect<
  * @return The connected namespaces.
  */
 export function getConnectNamespace(
-	Component: ReactChild | undefined | {}
+	Component: ReactElement | number | string | undefined | {}
 ): string[] {
 	if ( ! Component ) {
 		return [];

package/src/menu-item/index.tsx

@@ -67,6 +67,7 @@ function UnforwardedMenuItem(
 			role={ role }
 			icon={ iconPosition === 'left' ? icon : undefined }
 			className={ className }
+			accessibleWhenDisabled
 			{ ...buttonProps }
 		>
 			<span className="components-menu-item__item">{ children }</span>

package/src/tabs/styles.ts

@@ -7,7 +7,7 @@ import * as Ariakit from '@ariakit/react';
 /**
  * Internal dependencies
  */
-import { COLORS, CONFIG } from '../utils';
+import { COLORS, CONFIG, font } from '../utils';
 import { space } from '../utils/space';
 import Icon from '../icon';
 
@@ -163,6 +163,7 @@ export const Tab = styled( Ariakit.Tab )`
 		cursor: pointer;
 		line-height: 1.2; // Characters in some languages (e.g. Japanese) may have a native higher line-height.
 		font-weight: 400;
+		font-size: ${ font( 'default.fontSize' ) };
 		color: ${ COLORS.theme.foreground };
 
 		&[aria-disabled='true'] {

package/src/tools-panel/stories/index.story.tsx

@@ -54,7 +54,7 @@ export const Default: StoryFn< typeof ToolsPanel > = ( {
 	const [ height, setHeight ] = useState< string | undefined >();
 	const [ minHeight, setMinHeight ] = useState< string | undefined >();
 	const [ width, setWidth ] = useState< string | undefined >();
-	const [ scale, setScale ] = useState< React.ReactText | undefined >();
+	const [ scale, setScale ] = useState< number | string | undefined >();
 
 	const resetAll: typeof resetAllProp = ( filters ) => {
 		setHeight( undefined );
@@ -414,7 +414,7 @@ export const WithConditionalDefaultControl: StoryFn< typeof ToolsPanel > = ( {
 } ) => {
 	const [ attributes, setAttributes ] = useState< {
 		height?: string;
-		scale?: React.ReactText;
+		scale?: number | string;
 	} >( {} );
 	const { height, scale } = attributes;
 
@@ -512,7 +512,7 @@ export const WithConditionallyRenderedControl: StoryFn<
 > = ( { resetAll: resetAllProp, panelId, ...props } ) => {
 	const [ attributes, setAttributes ] = useState< {
 		height?: string;
-		scale?: React.ReactText;
+		scale?: number | string;
 	} >( {} );
 	const { height, scale } = attributes;
 

package/src/utils/font-size.ts

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { CSSProperties, ReactText } from 'react';
+import type { CSSProperties } from 'react';
 
 /**
  * Internal dependencies
@@ -61,7 +61,7 @@ export function getFontSize(
 	return `calc(${ ratio } * ${ CONFIG.fontSize })`;
 }
 
-export function getHeadingFontSize( size: ReactText = 3 ): string {
+export function getHeadingFontSize( size: number | string = 3 ): string {
 	if ( ! HEADING_FONT_SIZES.includes( size as HeadingSize ) ) {
 		return getFontSize( size );
 	}

package/src/utils/get-valid-children.ts

@@ -1,7 +1,7 @@
 /**
  * External dependencies
  */
-import type { ReactNode, ReactChild, ReactFragment, ReactPortal } from 'react';
+import type { ReactNode, ReactElement, ReactPortal } from 'react';
 
 /**
  * WordPress dependencies
@@ -17,7 +17,9 @@ import { Children, isValidElement } from '@wordpress/element';
  */
 export function getValidChildren(
 	children: ReactNode
-): Array< ReactChild | ReactFragment | ReactPortal > {
+): Array<
+	ReactElement | number | string | Iterable< ReactNode > | ReactPortal
+> {
 	if ( typeof children === 'string' ) {
 		return [ children ];
 	}

package/src/utils/theme-variables.scss

@@ -29,3 +29,4 @@ $components-color-light-gray-placeholder: color-mix(in srgb, $components-color-b
 
 // Semantic aliases (prefer these over raw gray values when applicable).
 $components-color-border: #{ $components-color-gray-600 };
+$components-color-disabled: #{ $components-color-gray-600 };

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

@@ -17,7 +17,8 @@ type Value = CheckboxControlProps[ 'checked' ];
 const UnforwardedValidatedCheckboxControl = (
 	{
 		required,
-		customValidator,
+		onValidate,
+		customValidity,
 		onChange,
 		markWhenOptional,
 		...restProps
@@ -37,9 +38,10 @@ const UnforwardedValidatedCheckboxControl = (
 			required={ required }
 			markWhenOptional={ markWhenOptional }
 			ref={ mergedRefs }
-			customValidator={ () => {
-				return customValidator?.( valueRef.current );
+			onValidate={ () => {
+				return onValidate?.( valueRef.current );
 			} }
+			customValidity={ customValidity }
 			getValidityTarget={ () =>
 				validityTargetRef.current?.querySelector< HTMLInputElement >(
 					'input[type="checkbox"]'

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

@@ -17,7 +17,8 @@ type Value = ComboboxControlProps[ 'value' ];
 const UnforwardedValidatedComboboxControl = (
 	{
 		required,
-		customValidator,
+		onValidate,
+		customValidity,
 		onChange,
 		markWhenOptional,
 		...restProps
@@ -50,9 +51,10 @@ const UnforwardedValidatedComboboxControl = (
 			required={ required }
 			markWhenOptional={ markWhenOptional }
 			ref={ mergedRefs }
-			customValidator={ () => {
-				return customValidator?.( valueRef.current );
+			onValidate={ () => {
+				return onValidate?.( valueRef.current );
 			} }
+			customValidity={ customValidity }
 			getValidityTarget={ () =>
 				validityTargetRef.current?.querySelector< HTMLInputElement >(
 					'input[role="combobox"]'

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

@@ -21,7 +21,8 @@ type Value = CustomSelectControlProps[ 'value' ];
 const UnforwardedValidatedCustomSelectControl = (
 	{
 		required,
-		customValidator,
+		onValidate,
+		customValidity,
 		onChange,
 		markWhenOptional,
 		...restProps
@@ -43,9 +44,10 @@ const UnforwardedValidatedCustomSelectControl = (
 			<ControlWithError
 				required={ required }
 				markWhenOptional={ markWhenOptional }
-				customValidator={ () => {
-					return customValidator?.( valueRef.current );
+				onValidate={ () => {
+					return onValidate?.( valueRef.current );
 				} }
+				customValidity={ customValidity }
 				getValidityTarget={ () => validityTargetRef.current }
 			>
 				<CustomSelectControl

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

@@ -17,7 +17,8 @@ type Value = InputControlProps[ 'value' ];
 const UnforwardedValidatedInputControl = (
 	{
 		required,
-		customValidator,
+		onValidate,
+		customValidity,
 		onChange,
 		markWhenOptional,
 		...restProps
@@ -36,9 +37,10 @@ const UnforwardedValidatedInputControl = (
 		<ControlWithError
 			required={ required }
 			markWhenOptional={ markWhenOptional }
-			customValidator={ () => {
-				return customValidator?.( valueRef.current );
+			onValidate={ () => {
+				return onValidate?.( valueRef.current );
 			} }
+			customValidity={ customValidity }
 			getValidityTarget={ () => validityTargetRef.current }
 		>
 			<InputControl

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

@@ -17,7 +17,8 @@ type Value = NumberControlProps[ 'value' ];
 const UnforwardedValidatedNumberControl = (
 	{
 		required,
-		customValidator,
+		onValidate,
+		customValidity,
 		onChange,
 		markWhenOptional,
 		...restProps
@@ -36,9 +37,10 @@ const UnforwardedValidatedNumberControl = (
 		<ControlWithError
 			required={ required }
 			markWhenOptional={ markWhenOptional }
-			customValidator={ () => {
-				return customValidator?.( valueRef.current );
+			onValidate={ () => {
+				return onValidate?.( valueRef.current );
 			} }
+			customValidity={ customValidity }
 			getValidityTarget={ () => validityTargetRef.current }
 		>
 			<NumberControl

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

@@ -17,7 +17,8 @@ type Value = RadioControlProps[ 'selected' ];
 const UnforwardedValidatedRadioControl = (
 	{
 		required,
-		customValidator,
+		onValidate,
+		customValidity,
 		onChange,
 		markWhenOptional,
 		...restProps
@@ -35,9 +36,10 @@ const UnforwardedValidatedRadioControl = (
 			markWhenOptional={ markWhenOptional }
 			// TODO: Upstream limitation - RadioControl does not accept a ref.
 			ref={ mergedRefs }
-			customValidator={ () => {
-				return customValidator?.( valueRef.current );
+			onValidate={ () => {
+				return onValidate?.( valueRef.current );
 			} }
+			customValidity={ customValidity }
 			getValidityTarget={ () =>
 				validityTargetRef.current?.querySelector< HTMLInputElement >(
 					'input[type="radio"]'

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

@@ -17,7 +17,8 @@ type Value = RangeControlProps[ 'value' ];
 const UnforwardedValidatedRangeControl = (
 	{
 		required,
-		customValidator,
+		onValidate,
+		customValidity,
 		onChange,
 		markWhenOptional,
 		...restProps
@@ -36,9 +37,10 @@ const UnforwardedValidatedRangeControl = (
 		<ControlWithError
 			required={ required }
 			markWhenOptional={ markWhenOptional }
-			customValidator={ () => {
-				return customValidator?.( valueRef.current );
+			onValidate={ () => {
+				return onValidate?.( valueRef.current );
 			} }
+			customValidity={ customValidity }
 			getValidityTarget={ () => validityTargetRef.current }
 		>
 			<RangeControl

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

@@ -26,7 +26,8 @@ type Value = SelectControlProps[ 'value' ];
 const UnforwardedValidatedSelectControl = (
 	{
 		required,
-		customValidator,
+		onValidate,
+		customValidity,
 		onChange,
 		markWhenOptional,
 		...restProps
@@ -51,9 +52,10 @@ const UnforwardedValidatedSelectControl = (
 		<ControlWithError
 			required={ required }
 			markWhenOptional={ markWhenOptional }
-			customValidator={ () => {
-				return customValidator?.( valueRef.current );
+			onValidate={ () => {
+				return onValidate?.( valueRef.current );
 			} }
+			customValidity={ customValidity }
 			getValidityTarget={ () => validityTargetRef.current }
 		>
 			<SelectControl

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

@@ -32,6 +32,12 @@ export default meta;
 export const Default: StoryObj< typeof ValidatedCheckboxControl > = {
 	render: function Template( { onChange, ...args } ) {
 		const [ checked, setChecked ] = useState( false );
+		const [ customValidity, setCustomValidity ] =
+			useState<
+				React.ComponentProps<
+					typeof ValidatedCheckboxControl
+				>[ 'customValidity' ]
+			>( undefined );
 
 		return (
 			<ValidatedCheckboxControl
@@ -41,6 +47,17 @@ export const Default: StoryObj< typeof ValidatedCheckboxControl > = {
 					setChecked( value );
 					onChange?.( value );
 				} }
+				onValidate={ ( value ) => {
+					if ( value ) {
+						setCustomValidity( {
+							type: 'invalid',
+							message: 'This checkbox may not be checked.',
+						} );
+					} else {
+						setCustomValidity( undefined );
+					}
+				} }
+				customValidity={ customValidity }
 			/>
 		);
 	},
@@ -49,10 +66,4 @@ 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;
-	},
 };