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

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/color-picker/styles.ts

@@ -91,6 +91,16 @@ export const ColorfulWrapper = styled.div`
 
 		// Shown instead of box-shadow to Windows high contrast mode.
 		outline: 2px solid transparent;
+
+		@media not ( prefers-reduced-motion ) {
+			transition: transform ${ CONFIG.transitionDurationFast } ease-in-out;
+		}
+	}
+
+	.react-colorful__interactive:focus .react-colorful__pointer {
+		box-shadow: 0 0 0 ${ CONFIG.borderWidthFocus } ${ CONFIG.surfaceColor };
+		border: ${ CONFIG.borderWidthFocus } solid black;
+		transform: translate( -50%, -50% ) scale( 1.5 );
 	}
 
 	.react-colorful__pointer-fill {

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/modal/style.scss

@@ -128,7 +128,7 @@
 	flex-direction: row;
 	justify-content: space-between;
 	align-items: center;
-	height: $header-height + $grid-unit-15;
+	height: $header-height + $grid-unit-10; // 72px
 	width: 100%;
 	z-index: z-index(".components-modal__header");
 	position: absolute;
@@ -175,7 +175,7 @@
 // Modal contents.
 .components-modal__content {
 	flex: 1;
-	margin-top: $header-height + $grid-unit-15;
+	margin-top: $header-height + $grid-unit-10;
 	// Small top padding required to avoid cutting off the visible outline when the first child element is focusable.
 	padding: $grid-unit-05 $grid-unit-40 $grid-unit-40;
 	overflow: auto;

package/src/palette-edit/index.tsx

@@ -22,7 +22,7 @@ import { useDebounce } from '@wordpress/compose';
  */
 import Button from '../button';
 import { ColorPicker } from '../color-picker';
-import { FlexItem } from '../flex';
+import { FlexBlock, FlexItem } from '../flex';
 import { HStack } from '../h-stack';
 import { Item, ItemGroup } from '../item-group';
 import { VStack } from '../v-stack';
@@ -229,7 +229,7 @@ function Option< T extends PaletteElement >( {
 				>
 					<IndicatorStyled colorValue={ value } />
 				</Button>
-				<FlexItem>
+				<FlexBlock>
 					{ ! canOnlyChangeValues ? (
 						<NameInput
 							label={
@@ -256,7 +256,7 @@ function Option< T extends PaletteElement >( {
 								  '\u00A0' }
 						</NameContainer>
 					) }
-				</FlexItem>
+				</FlexBlock>
 				{ ! canOnlyChangeValues && (
 					<FlexItem>
 						<RemoveButton

package/src/private-apis.ts

@@ -11,6 +11,13 @@ import { withIgnoreIMEEvents } from './utils/with-ignore-ime-events';
 import { lock } from './lock-unlock';
 import Badge from './badge';
 
+import { DateCalendar, DateRangeCalendar, TZDate } from './calendar';
+import {
+	ValidatedNumberControl,
+	ValidatedTextControl,
+	ValidatedToggleControl,
+} from './validated-form-controls';
+
 export const privateApis = {};
 lock( privateApis, {
 	__experimentalPopoverLegacyPositionToPlacement,
@@ -22,4 +29,10 @@ lock( privateApis, {
 	withIgnoreIMEEvents,
 	Badge,
 	normalizeTextString,
+	DateCalendar,
+	DateRangeCalendar,
+	TZDate,
+	ValidatedNumberControl,
+	ValidatedTextControl,
+	ValidatedToggleControl,
 } );

package/src/range-control/index.tsx

@@ -314,7 +314,7 @@ function UnforwardedRangeControl(
 						<SimpleTooltip
 							className="components-range-control__tooltip"
 							inputRef={ inputRef }
-							tooltipPosition="bottom"
+							tooltipPlacement="bottom"
 							renderTooltipContent={ renderTooltipContent }
 							show={ isCurrentlyFocused || showTooltip }
 							style={ offsetStyle }

package/src/range-control/styles/range-control-styles.ts

@@ -283,8 +283,8 @@ const tooltipShow = ( { show }: TooltipProps ) => {
 	`;
 };
 
-const tooltipPosition = ( { position }: TooltipProps ) => {
-	const isBottom = position === 'bottom';
+const tooltipPlacement = ( { placement }: TooltipProps ) => {
+	const isBottom = placement === 'bottom';
 
 	if ( isBottom ) {
 		return css`
@@ -312,7 +312,7 @@ export const Tooltip = styled.span< TooltipProps >`
 
 	${ tooltipShow };
 
-	${ tooltipPosition };
+	${ tooltipPlacement };
 	${ rtl(
 		{ transform: 'translateX(-50%)' },
 		{ transform: 'translateX(50%)' }

package/src/range-control/tooltip.tsx

@@ -22,7 +22,7 @@ export default function SimpleTooltip(
 	const {
 		className,
 		inputRef,
-		tooltipPosition,
+		tooltipPlacement,
 		show = false,
 		style = {},
 		value = 0,
@@ -30,7 +30,7 @@ export default function SimpleTooltip(
 		zIndex = 100,
 		...restProps
 	} = props;
-	const position = useTooltipPosition( { inputRef, tooltipPosition } );
+	const placement = useTooltipPlacement( { inputRef, tooltipPlacement } );
 	const classes = clsx( 'components-simple-tooltip', className );
 	const styles = {
 		...style,
@@ -42,7 +42,7 @@ export default function SimpleTooltip(
 			{ ...restProps }
 			aria-hidden="false"
 			className={ classes }
-			position={ position }
+			placement={ placement }
 			show={ show }
 			role="tooltip"
 			style={ styles }
@@ -52,26 +52,26 @@ export default function SimpleTooltip(
 	);
 }
 
-function useTooltipPosition( { inputRef, tooltipPosition }: TooltipProps ) {
-	const [ position, setPosition ] = useState< string >();
+function useTooltipPlacement( { inputRef, tooltipPlacement }: TooltipProps ) {
+	const [ placement, setPlacement ] = useState< string >();
 
-	const setTooltipPosition = useCallback( () => {
+	const setTooltipPlacement = useCallback( () => {
 		if ( inputRef && inputRef.current ) {
-			setPosition( tooltipPosition );
+			setPlacement( tooltipPlacement );
 		}
-	}, [ tooltipPosition, inputRef ] );
+	}, [ tooltipPlacement, inputRef ] );
 
 	useEffect( () => {
-		setTooltipPosition();
-	}, [ setTooltipPosition ] );
+		setTooltipPlacement();
+	}, [ setTooltipPlacement ] );
 
 	useEffect( () => {
-		window.addEventListener( 'resize', setTooltipPosition );
+		window.addEventListener( 'resize', setTooltipPlacement );
 
 		return () => {
-			window.removeEventListener( 'resize', setTooltipPosition );
+			window.removeEventListener( 'resize', setTooltipPlacement );
 		};
 	} );
 
-	return position;
+	return placement;
 }

package/src/range-control/types.ts

@@ -269,9 +269,9 @@ export type ThumbProps = {
 
 export type TooltipProps = {
 	show?: boolean;
-	position?: string;
+	placement?: string;
 	inputRef?: MutableRefObject< HTMLElement | undefined >;
-	tooltipPosition?: string;
+	tooltipPlacement?: string;
 	value?: ControlledRangeValue;
 	renderTooltipContent?: (
 		value?: ControlledRangeValue

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/text-control/stories/index.story.tsx

@@ -56,6 +56,7 @@ export const Default: StoryFn< typeof TextControl > = DefaultTemplate.bind(
 Default.args = {
 	__nextHasNoMarginBottom: true,
 	__next40pxDefaultSize: true,
+	placeholder: 'Placeholder',
 };
 
 export const WithLabelAndHelpText: StoryFn< typeof TextControl > =