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

package/src/calendar/date-calendar/index.tsx

@@ -3,14 +3,18 @@
  */
 import { DayPicker } from 'react-day-picker';
 import { enUS } from 'react-day-picker/locale';
+/**
+ * WordPress dependencies
+ */
+import { useCallback } from '@wordpress/element';
 /**
  * Internal dependencies
  */
 import { COMMON_PROPS } from '../utils/constants';
 import { clampNumberOfMonths } from '../utils/misc';
-import { useControlledValue } from '../utils/use-controlled-value';
+import { useControlledValue } from '../../utils/hooks';
 import { useLocalizationProps } from '../utils/use-localization-props';
-import type { DateCalendarProps } from '../types';
+import type { DateCalendarProps, OnSelectHandler } from '../types';
 
 /**
  * `DateCalendar` is a React component that provides a customizable calendar
@@ -35,11 +39,21 @@ export const DateCalendar = ( {
 		mode: 'single',
 	} );
 
-	const [ selected, setSelected ] = useControlledValue< Date | undefined >( {
-		defaultValue: defaultSelected,
-		value: selectedProp,
-		onChange: onSelect,
-	} );
+	const onChange: OnSelectHandler< typeof selectedProp > = useCallback(
+		( selected, triggerDate, modifiers, e ) => {
+			// Convert internal `null` to `undefined` for the public event handler.
+			onSelect?.( selected ?? undefined, triggerDate, modifiers, e );
+		},
+		[ onSelect ]
+	);
+
+	const [ selected, setSelected ] = useControlledValue< typeof selectedProp >(
+		{
+			defaultValue: defaultSelected,
+			value: selectedProp,
+			onChange,
+		}
+	);
 
 	return (
 		<DayPicker
@@ -48,7 +62,7 @@ export const DateCalendar = ( {
 			{ ...props }
 			mode="single"
 			numberOfMonths={ clampNumberOfMonths( numberOfMonths ) }
-			selected={ selected }
+			selected={ selected ?? undefined }
 			onSelect={ setSelected }
 		/>
 	);

package/src/calendar/date-range-calendar/README.md

@@ -1,5 +1,7 @@
 # `DateRangeCalendar`
 
+🔒 This component is locked as a [private API](https://developer.wordpress.org/block-editor/reference-guides/packages/packages-private-apis/). We do not yet recommend using this outside of the Gutenberg project.
+
 `DateRangeCalendar` is a React component that provides a customizable calendar interface for **date range** selection.
 
 The component is built with accessibility in mind and follows ARIA best practices for calendar widgets. It provides keyboard navigation, screen reader support, and customizable labels for internationalization.
@@ -7,7 +9,7 @@ The component is built with accessibility in mind and follows ARIA best practice
 ## Usage example
 
 ```tsx
-import { DateRangeCalendar } from '@automattic/components';
+import { DateRangeCalendar } from '@wordpress/components';
 
 type DateRange = {
 	from: Date | undefined;
@@ -30,16 +32,16 @@ These props are shared between both single date and date range calendar modes.
 
 ### `required`
 
-- Type: `boolean`
-- Required: No
-- Default: `false`
+-   Type: `boolean`
+-   Required: No
+-   Default: `false`
 
 Whether the selection is required. When `true`, there always needs to be a date selected.
 
 ### `selected`
 
-- Type: `DateRange | undefined | null`
-- Required: No
+-   Type: `DateRange | undefined | null`
+-   Required: No
 
 The selected date range. A `DateRange` object has the following shape:
 
@@ -52,101 +54,101 @@ The selected date range. A `DateRange` object has the following shape:
 
 ### `onSelect`
 
-- Type: `(selected: DateRange | undefined, triggerDate: Date, modifiers: Modifiers, e: React.MouseEvent | React.KeyboardEvent) => void`
-- Required: No
+-   Type: `(selected: DateRange | undefined, triggerDate: Date, modifiers: Modifiers, e: React.MouseEvent | React.KeyboardEvent) => void`
+-   Required: No
 
 Event handler when the selection changes. The `selected` parameter will contain the new date range.
 
 ### `defaultSelected`
 
-- Type: `DateRange`
-- Required: No
+-   Type: `DateRange`
+-   Required: No
 
 The default selected range (for uncontrolled usage).
 
 ### `excludeDisabled`
 
-- Type: `boolean`
-- Required: No
+-   Type: `boolean`
+-   Required: No
 
 When `true`, the range will reset when including a disabled day. This is useful to prevent users from selecting ranges that include unavailable dates.
 
 ### `min`
 
-- Type: `number`
-- Required: No
+-   Type: `number`
+-   Required: No
 
 The minimum number of days to include in the range. If a user tries to select a range shorter than this, the selection will be adjusted to meet the minimum requirement.
 
 ### `max`
 
-- Type: `number`
-- Required: No
+-   Type: `number`
+-   Required: No
 
 The maximum number of days to include in the range. If a user tries to select a range longer than this, the selection will be adjusted to meet the maximum requirement.
 
 ### `defaultMonth`
 
-- Type: `Date`
-- Required: No
-- Default: Current month
+-   Type: `Date`
+-   Required: No
+-   Default: Current month
 
 The initial month to show in the calendar view (uncontrolled).
 
 ### `month`
 
-- Type: `Date`
-- Required: No
+-   Type: `Date`
+-   Required: No
 
 The month displayed in the calendar view (controlled). Use together with `onMonthChange` to change the month programmatically.
 
 ### `numberOfMonths`
 
-- Type: `number`
-- Required: No
-- Default: `1`
+-   Type: `number`
+-   Required: No
+-   Default: `1`
 
 The number of months displayed at once.
 
 ### `startMonth`
 
-- Type: `Date`
-- Required: No
+-   Type: `Date`
+-   Required: No
 
 The earliest month to start the month navigation.
 
 ### `endMonth`
 
-- Type: `Date`
-- Required: No
+-   Type: `Date`
+-   Required: No
 
 The latest month to end the month navigation.
 
 ### `autoFocus`
 
-- Type: `boolean`
-- Required: No
+-   Type: `boolean`
+-   Required: No
 
 Focus the first selected day (if set) or today's date (if not disabled). Use this prop when you need to focus the calendar after a user action (e.g. opening the dialog with the calendar).
 
 ### `disabled`
 
-- Type: `Matcher | Matcher[] | undefined`
-- Required: No
+-   Type: `Matcher | Matcher[] | undefined`
+-   Required: No
 
 Specify which days are disabled. Using `true` will disable all dates. See the [Matcher Types](#matcher-types) section for more details.
 
 ### `disableNavigation`
 
-- Type: `boolean`
-- Required: No
+-   Type: `boolean`
+-   Required: No
 
 Disable the navigation buttons.
 
 ### `labels`
 
-- Type: `object`
-- Required: No
+-   Type: `object`
+-   Required: No
 
 Use custom labels for internationalization. All labels are optional and have sensible defaults:
 
@@ -166,9 +168,9 @@ Use custom labels for internationalization. All labels are optional and have sen
 
 ### `locale`
 
-- Type: `Locale`
-- Required: No
-- Default: `enUS` from `@date-fns/locale`
+-   Type: `Locale`
+-   Required: No
+-   Default: `enUS` from `@date-fns/locale`
 
 The locale object used to localize dates. Pass a locale from `@date-fns/locale` to localize the calendar.
 
@@ -176,30 +178,30 @@ The locale object used to localize dates. Pass a locale from `@date-fns/locale`
 
 ### `weekStartsOn`
 
-- Type: `0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined`
-- Required: No
-- Default: Based on the `locale` prop
+-   Type: `0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined`
+-   Required: No
+-   Default: Based on the `locale` prop
 
 The index of the first day of the week (0 - Sunday). Overrides the locale's setting.
 
 ### `onMonthChange`
 
-- Type: `(month: Date) => void`
-- Required: No
+-   Type: `(month: Date) => void`
+-   Required: No
 
 Event fired when the user navigates between months.
 
 ### `timeZone`
 
-- Type: `string`
-- Required: No
+-   Type: `string`
+-   Required: No
 
 The time zone (IANA or UTC offset) to use in the calendar. See [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for possible values.
 
 When working with time zones, use the `TZDate` object exported by this package instead of the native `Date` object.
 
 ```tsx
-import { DateRangeCalendar, TZDate } from '@automattic/components';
+import { DateRangeCalendar, TZDate } from '@wordpress/components';
 
 export function WithTimeZone() {
 	const timeZone = 'America/New_York';
@@ -207,15 +209,21 @@ export function WithTimeZone() {
 		from: new TZDate( 2024, 12, 10, timeZone ), // Use `TZDate` instead of `Date`
 		to: new TZDate( 2024, 12, 8, timeZone ), // Use `TZDate` instead of `Date`
 	} );
-	return <DateRangeCalendar timeZone={ timeZone } selected={ selected } onSelect={ setSelected } />;
+	return (
+		<DateRangeCalendar
+			timeZone={ timeZone }
+			selected={ selected }
+			onSelect={ setSelected }
+		/>
+	);
 }
 ```
 
 ### `role`
 
-- Type: `'application' | 'dialog' | undefined`
-- Required: No
-- Default: `'application'`
+-   Type: `'application' | 'dialog' | undefined`
+-   Required: No
+-   Default: `'application'`
 
 The role attribute to add to the container element.
 
@@ -238,7 +246,10 @@ const dateMatcher: Matcher = new Date(); // Will match today's date
 ### Array Matcher
 
 ```typescript
-const arrayMatcher: Matcher = [ new Date( 2019, 1, 2 ), new Date( 2019, 1, 4 ) ]; // Will match the days in the array
+const arrayMatcher: Matcher = [
+	new Date( 2019, 1, 2 ),
+	new Date( 2019, 1, 4 ),
+]; // Will match the days in the array
 ```
 
 ### Date After Matcher

package/src/calendar/date-range-calendar/index.tsx

@@ -7,15 +7,19 @@ import { enUS } from 'react-day-picker/locale';
 /**
  * WordPress dependencies
  */
-import { useMemo, useState } from '@wordpress/element';
+import { useMemo, useState, useCallback } from '@wordpress/element';
 /**
  * Internal dependencies
  */
 import { COMMON_PROPS, MODIFIER_CLASSNAMES } from '../utils/constants';
 import { clampNumberOfMonths } from '../utils/misc';
-import { useControlledValue } from '../utils/use-controlled-value';
+import { useControlledValue } from '../../utils/hooks';
 import { useLocalizationProps } from '../utils/use-localization-props';
-import type { DateRangeCalendarProps, DateRange } from '../types';
+import type {
+	DateRangeCalendarProps,
+	DateRange,
+	OnSelectHandler,
+} from '../types';
 
 export function usePreviewRange( {
 	selected,
@@ -151,13 +155,21 @@ export const DateRangeCalendar = ( {
 		mode: 'range',
 	} );
 
-	const [ selected, setSelected ] = useControlledValue<
-		DateRange | undefined
-	>( {
-		defaultValue: defaultSelected,
-		value: selectedProp,
-		onChange: onSelect,
-	} );
+	const onChange: OnSelectHandler< typeof selectedProp > = useCallback(
+		( selected, triggerDate, modifiers, e ) => {
+			// Convert internal `null` to `undefined` for the public event handler.
+			onSelect?.( selected ?? undefined, triggerDate, modifiers, e );
+		},
+		[ onSelect ]
+	);
+
+	const [ selected, setSelected ] = useControlledValue< typeof selectedProp >(
+		{
+			defaultValue: defaultSelected,
+			value: selectedProp,
+			onChange,
+		}
+	);
 
 	const [ hoveredDate, setHoveredDate ] = useState< Date | undefined >(
 		undefined
@@ -192,7 +204,7 @@ export const DateRangeCalendar = ( {
 			excludeDisabled={ excludeDisabled }
 			min={ min }
 			max={ max }
-			selected={ selected }
+			selected={ selected ?? undefined }
 			onSelect={ setSelected }
 			onDayMouseEnter={ ( date ) => setHoveredDate( date ) }
 			onDayMouseLeave={ () => setHoveredDate( undefined ) }

package/src/calendar/types.ts

@@ -153,7 +153,7 @@ type DayOfWeek = {
  * @param {Modifiers}                              modifiers   - The modifiers associated with the event.
  * @param {React.MouseEvent | React.KeyboardEvent} e           - The event object.
  */
-type OnSelectHandler< T > = (
+export type OnSelectHandler< T > = (
 	selected: T,
 	triggerDate: Date,
 	modifiers: Modifiers,
@@ -284,7 +284,7 @@ export interface BaseProps
 	 * When working with time zones, use the `TZDate` object exported by this
 	 * package instead of the native `Date` object.
 	 * @example
-	 *   import { DateCalendar, TZDate } from "@automattic/components";
+	 *   import { DateCalendar, TZDate } from "@wordpress/components";
 	 *
 	 *   export function WithTimeZone() {
 	 *     const timeZone = "America/New_York";

package/src/dimension-control/test/__snapshots__/index.test.js.snap

@@ -193,13 +193,13 @@ exports[`DimensionControl rendering renders with custom sizes 1`] = `
 
 <div>
   <div
-    class="components-base-control emotion-0 emotion-1"
+    class="components-base-control components-select-control block-editor-dimension-control emotion-0 emotion-1"
   >
     <div
       class="components-base-control__field emotion-2 emotion-3"
     >
       <div
-        class="components-flex components-input-base components-select-control block-editor-dimension-control emotion-4 emotion-5 emotion-6 emotion-7"
+        class="components-flex components-input-base emotion-4 emotion-5 emotion-6 emotion-7"
         data-wp-c16t="true"
         data-wp-component="InputBase"
       >
@@ -475,13 +475,13 @@ exports[`DimensionControl rendering renders with defaults 1`] = `
 
 <div>
   <div
-    class="components-base-control emotion-0 emotion-1"
+    class="components-base-control components-select-control block-editor-dimension-control emotion-0 emotion-1"
   >
     <div
       class="components-base-control__field emotion-2 emotion-3"
     >
       <div
-        class="components-flex components-input-base components-select-control block-editor-dimension-control emotion-4 emotion-5 emotion-6 emotion-7"
+        class="components-flex components-input-base emotion-4 emotion-5 emotion-6 emotion-7"
         data-wp-c16t="true"
         data-wp-component="InputBase"
       >
@@ -767,13 +767,13 @@ exports[`DimensionControl rendering renders with icon and custom icon label 1`]
 
 <div>
   <div
-    class="components-base-control emotion-0 emotion-1"
+    class="components-base-control components-select-control block-editor-dimension-control emotion-0 emotion-1"
   >
     <div
       class="components-base-control__field emotion-2 emotion-3"
     >
       <div
-        class="components-flex components-input-base components-select-control block-editor-dimension-control emotion-4 emotion-5 emotion-6 emotion-7"
+        class="components-flex components-input-base emotion-4 emotion-5 emotion-6 emotion-7"
         data-wp-c16t="true"
         data-wp-component="InputBase"
       >
@@ -1071,13 +1071,13 @@ exports[`DimensionControl rendering renders with icon and default icon label 1`]
 
 <div>
   <div
-    class="components-base-control emotion-0 emotion-1"
+    class="components-base-control components-select-control block-editor-dimension-control emotion-0 emotion-1"
   >
     <div
       class="components-base-control__field emotion-2 emotion-3"
     >
       <div
-        class="components-flex components-input-base components-select-control block-editor-dimension-control emotion-4 emotion-5 emotion-6 emotion-7"
+        class="components-flex components-input-base emotion-4 emotion-5 emotion-6 emotion-7"
         data-wp-c16t="true"
         data-wp-component="InputBase"
       >

package/src/icon/index.tsx

@@ -107,6 +107,8 @@ function Icon( {
 		return cloneElement( icon, {
 			// @ts-ignore Just forwarding the size prop along
 			size,
+			width: size,
+			height: size,
 			...additionalProps,
 		} );
 	}

package/src/index.ts

@@ -57,7 +57,6 @@ export {
 	CardHeader,
 	CardMedia,
 } from './card';
-export { DateCalendar, DateRangeCalendar, TZDate } from './calendar';
 export { default as CheckboxControl } from './checkbox-control';
 export { default as ClipboardButton } from './clipboard-button';
 export { default as __experimentalPaletteEdit } from './palette-edit';

package/src/private-apis.ts

@@ -11,6 +11,8 @@ import { withIgnoreIMEEvents } from './utils/with-ignore-ime-events';
 import { lock } from './lock-unlock';
 import Badge from './badge';
 
+import { DateCalendar, DateRangeCalendar, TZDate } from './calendar';
+
 export const privateApis = {};
 lock( privateApis, {
 	__experimentalPopoverLegacyPositionToPlacement,
@@ -22,4 +24,7 @@ lock( privateApis, {
 	withIgnoreIMEEvents,
 	Badge,
 	normalizeTextString,
+	DateCalendar,
+	DateRangeCalendar,
+	TZDate,
 } );

package/src/select-control/index.tsx

@@ -107,11 +107,11 @@ function UnforwardedSelectControl< V extends string >(
 		<BaseControl
 			help={ help }
 			id={ id }
+			className={ classes }
 			__nextHasNoMarginBottom={ __nextHasNoMarginBottom }
 			__associatedWPComponentName="SelectControl"
 		>
 			<StyledInputBase
-				className={ classes }
 				disabled={ disabled }
 				hideLabelFromVision={ hideLabelFromVision }
 				id={ id }

package/src/style.scss

@@ -1,7 +1,7 @@
 // Include the default WP Components color variables.
 // TODO: Remove this once all admin-scheme variables are accounted for in the wp-components fallback values.
 :root {
-	@include admin-scheme(#3858e9);
+	@include admin-scheme( #3858e9 );
 }
 
 // Variables
@@ -21,7 +21,6 @@
 @import "./combobox-control/style.scss";
 @import "./color-palette/style.scss";
 @import "./custom-gradient-picker/style.scss";
-@import "./dimension-control/style.scss";
 @import "./draggable/style.scss";
 @import "./drop-zone/style.scss";
 @import "./dropdown/style.scss";
@@ -56,3 +55,4 @@
 @import "./toolbar/toolbar-button/style.scss";
 @import "./toolbar/toolbar-group/style.scss";
 @import "./tooltip/style.scss";
+@import "./validated-form-controls/style.scss";

package/src/toggle-group-control/toggle-group-control/as-button-group.tsx

@@ -48,7 +48,9 @@ function UnforwardedToggleGroupControlAsButtonGroup(
 	const { value, defaultValue } =
 		useComputeControlledOrUncontrolledValue( valueProp );
 
-	const [ selectedValue, setSelectedValue ] = useControlledValue( {
+	const [ selectedValue, setSelectedValue ] = useControlledValue<
+		typeof value
+	>( {
 		defaultValue,
 		value,
 		onChange,

package/src/utils/hooks/use-controlled-value.ts

@@ -1,12 +1,12 @@
 /**
  * WordPress dependencies
  */
-import { useState } from '@wordpress/element';
+import { useCallback, useState } from '@wordpress/element';
 
 type Props< T > = {
 	defaultValue?: T;
 	value?: T;
-	onChange?: ( value: T ) => void;
+	onChange?: ( value: T, ...args: any[] ) => void;
 };
 
 /**
@@ -28,17 +28,25 @@ export function useControlledValue< T >( {
 	const [ state, setState ] = useState( initialValue );
 	const value = hasValue ? valueProp : state;
 
-	let setValue: ( nextValue: T ) => void;
+	const uncontrolledSetValue = useCallback(
+		( nextValue: T, ...args: any[] ) => {
+			setState( nextValue );
+			onChange?.( nextValue, ...args );
+		},
+		[ onChange ]
+	);
+
+	let setValue: typeof onChange;
 	if ( hasValue && typeof onChange === 'function' ) {
+		// Controlled mode.
 		setValue = onChange;
 	} else if ( ! hasValue && typeof onChange === 'function' ) {
-		setValue = ( nextValue ) => {
-			onChange( nextValue );
-			setState( nextValue );
-		};
+		// Uncontrolled mode, plus forwarding to the onChange prop.
+		setValue = uncontrolledSetValue;
 	} else {
+		// Uncontrolled mode, only update internal state.
 		setValue = setState;
 	}
 
-	return [ value, setValue as typeof setState ] as const;
+	return [ value, setValue ] as const;
 }

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

@@ -0,0 +1,64 @@
+/**
+ * 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 CheckboxControl from '../../checkbox-control';
+import type { CheckboxControlProps } from '../../checkbox-control/types';
+
+type Value = CheckboxControlProps[ 'checked' ];
+
+const UnforwardedValidatedCheckboxControl = (
+	{
+		required,
+		customValidator,
+		onChange,
+		markWhenOptional,
+		...restProps
+	}: Omit<
+		React.ComponentProps< typeof CheckboxControl >,
+		'__nextHasNoMarginBottom'
+	> &
+		ValidatedControlProps< Value >,
+	forwardedRef: React.ForwardedRef< HTMLInputElement >
+) => {
+	const validityTargetRef = useRef< HTMLDivElement >( null );
+	const mergedRefs = useMergeRefs( [ forwardedRef, validityTargetRef ] );
+	const valueRef = useRef< Value >( restProps.checked );
+
+	return (
+		<ControlWithError
+			required={ required }
+			markWhenOptional={ markWhenOptional }
+			ref={ mergedRefs }
+			customValidator={ () => {
+				return customValidator?.( valueRef.current );
+			} }
+			getValidityTarget={ () =>
+				validityTargetRef.current?.querySelector< HTMLInputElement >(
+					'input[type="checkbox"]'
+				)
+			}
+		>
+			<CheckboxControl
+				__nextHasNoMarginBottom
+				onChange={ ( value ) => {
+					valueRef.current = value;
+					onChange?.( value );
+				} }
+				// TODO: Upstream limitation - CheckboxControl doesn't support uncontrolled mode, visually.
+				{ ...restProps }
+			/>
+		</ControlWithError>
+	);
+};
+
+export const ValidatedCheckboxControl = forwardRef(
+	UnforwardedValidatedCheckboxControl
+);