@wordpress/components 32.1.1-next.v.0 → 32.2.0

package/src/confirm-dialog/stories/index.story.tsx

@@ -33,6 +33,10 @@ const meta: Meta< typeof ConfirmDialog > = {
 		controls: {
 			expanded: true,
 		},
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'global',
+		},
 		docs: { canvas: { sourceState: 'shown' } },
 	},
 };

package/src/context/context-connect.ts

@@ -34,7 +34,7 @@ type ContextConnectOptions = {
  * @return The connected WordPressComponent
  */
 export function contextConnect<
-	C extends ( props: any, ref: ForwardedRef< any > ) => JSX.Element | null,
+	C extends ( props: any, ref: ForwardedRef< any > ) => ReactNode,
 >(
 	Component: C &
 		AcceptsTwoArgs<
@@ -55,7 +55,7 @@ export function contextConnect<
  * @return The connected WordPressComponent
  */
 export function contextConnectWithoutRef< P >(
-	Component: ( props: P ) => JSX.Element | null,
+	Component: ( props: P ) => ReactNode,
 	namespace: string
 ) {
 	return _contextConnect( Component, namespace );
@@ -65,7 +65,7 @@ export function contextConnectWithoutRef< P >(
 // The hope is that we can improve render performance by removing functional
 // component wrappers.
 function _contextConnect<
-	C extends ( props: any, ref: ForwardedRef< any > ) => JSX.Element | null,
+	C extends ( props: any, ref: ForwardedRef< any > ) => ReactNode,
 	O extends ContextConnectOptions,
 >(
 	Component: C,

package/src/context/context-system-provider.js

@@ -89,10 +89,10 @@ function useContextSystemBridge( { value } ) {
  * ```
  *
  * @template {Record<string, any>} T
- * @param {Object}                    options
- * @param {import('react').ReactNode} options.children Children to render.
- * @param {T}                         options.value    Props to render into connected components.
- * @return {JSX.Element} A Provider wrapped component.
+ * @param {Object}          options
+ * @param {React.ReactNode} options.children Children to render.
+ * @param {T}               options.value    Props to render into connected components.
+ * @return {React.JSX.Element} A Provider wrapped component.
  */
 const BaseContextSystemProvider = ( { children, value } ) => {
 	const contextValue = useContextSystemBridge( { value } );

package/src/context/test/__snapshots__/context-system-provider.js.snap

@@ -3,7 +3,7 @@
 exports[`props should render _override props 1`] = `
 <div>
   <div
-    class="components-component test-component emotion-0 emotion-1"
+    class="components-component test-component css-yi1hlk-View emotion-0"
     data-wp-c16t="true"
     data-wp-component="Component"
   >
@@ -15,7 +15,7 @@ exports[`props should render _override props 1`] = `
 exports[`props should render context props 1`] = `
 <div>
   <div
-    class="components-component emotion-0 emotion-1"
+    class="components-component css-yi1hlk-View emotion-0"
     data-wp-c16t="true"
     data-wp-component="Component"
   >
@@ -27,7 +27,7 @@ exports[`props should render context props 1`] = `
 exports[`props should render correctly 1`] = `
 <div>
   <div
-    class="components-component emotion-0 emotion-1"
+    class="components-component css-yi1hlk-View emotion-0"
     data-wp-c16t="true"
     data-wp-component="Component"
   />

package/src/context/wordpress-component.ts

@@ -24,7 +24,7 @@ export type WordPressComponentProps<
 	( IsPolymorphic extends true
 		? {
 				/** The HTML element or React component to render the component as. */
-				as?: T | keyof JSX.IntrinsicElements;
+				as?: T | keyof React.JSX.IntrinsicElements;
 		  }
 		: {} );
 
@@ -36,10 +36,8 @@ export type WordPressComponent<
 	< TT extends React.ElementType >(
 		props: WordPressComponentProps< O, TT, IsPolymorphic > &
 			( IsPolymorphic extends true ? { as: TT } : {} )
-	): JSX.Element | null;
-	(
-		props: WordPressComponentProps< O, T, IsPolymorphic >
-	): JSX.Element | null;
+	): React.ReactNode;
+	( props: WordPressComponentProps< O, T, IsPolymorphic > ): React.ReactNode;
 	displayName?: string;
 	/**
 	 * A CSS selector used to fake component interpolation in styled components

package/src/custom-gradient-picker/gradient-bar/control-points.tsx

@@ -129,7 +129,8 @@ function ControlPoints( {
 	onStopControlPointChange,
 	__experimentalIsRenderedInSidebar,
 }: ControlPointsProps ) {
-	const controlPointMoveStateRef = useRef< ControlPointMoveState >();
+	const controlPointMoveStateRef =
+		useRef< ControlPointMoveState >( undefined );
 
 	const onMouseMove = ( event: MouseEvent ) => {
 		if (
@@ -177,7 +178,7 @@ function ControlPoints( {
 	// Adding `cleanEventListeners` to the dependency array below requires the function itself to be wrapped in a `useCallback`
 	// This memoization would prevent the event listeners from being properly cleaned.
 	// Instead, we'll pass a ref to the function in our `useEffect` so `cleanEventListeners` itself is no longer a dependency.
-	const cleanEventListenersRef = useRef< () => void >();
+	const cleanEventListenersRef = useRef< () => void >( undefined );
 	cleanEventListenersRef.current = cleanEventListeners;
 
 	useEffect( () => {

package/src/custom-gradient-picker/stories/index.story.tsx

@@ -23,6 +23,11 @@ const meta: Meta< typeof CustomGradientPicker > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'not-recommended',
+			whereUsed: 'global',
+			notes: 'Mostly an internal component. Use `GradientPicker` instead.',
+		},
 	},
 };
 export default meta;

package/src/custom-gradient-picker/types.ts

@@ -100,7 +100,7 @@ export type ControlPointButtonProps = {
 export type ControlPointsProps = {
 	disableRemove: boolean;
 	disableAlpha: boolean;
-	gradientPickerDomRef: React.RefObject< HTMLDivElement >;
+	gradientPickerDomRef: React.RefObject< HTMLDivElement | null >;
 	ignoreMarkerPosition?: number;
 	value: ControlPoint[];
 	onChange: ( controlPoints: ControlPoint[] ) => void;

package/src/custom-select-control/stories/index.story.tsx

@@ -30,6 +30,11 @@ const meta: Meta< typeof CustomSelectControl > = {
 		docs: {
 			source: { excludeDecorators: true },
 		},
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'global',
+			notes: 'Will be superseded by `SelectControl` in `@wordpress/ui`, but continue using for now.',
+		},
 	},
 	decorators: [
 		( Story ) => (

package/src/custom-select-control-v2/custom-select.tsx

@@ -31,7 +31,7 @@ export const CustomSelectContext =
 CustomSelectContext.displayName = 'CustomSelectContext';
 
 function defaultRenderSelectedValue(
-	value: CustomSelectButtonProps[ 'value' ]
+	value: CustomSelectButtonProps[ 'defaultValue' ]
 ) {
 	const isValueEmpty = Array.isArray( value )
 		? value.length === 0

package/src/custom-select-control-v2/stories/index.story.tsx

@@ -31,6 +31,11 @@ const meta: Meta< typeof CustomSelectControlV2 > = {
 		docs: {
 			source: { excludeDecorators: true },
 		},
+		componentStatus: {
+			status: 'not-recommended',
+			whereUsed: 'global',
+			notes: 'Will be superseded by `SelectControl` in `@wordpress/ui`. Continue using `CustomSelectControl` (v1) for now.',
+		},
 	},
 	decorators: [
 		( Story ) => (
@@ -50,11 +55,11 @@ const meta: Meta< typeof CustomSelectControlV2 > = {
 export default meta;
 
 const Template: StoryFn< typeof CustomSelectControlV2 > = ( props ) => {
-	const [ value, setValue ] = useState< string | string[] >();
+	const [ value, setValue ] = useState< string | readonly string[] >();
 	return (
 		<CustomSelectControlV2
 			{ ...props }
-			onChange={ ( nextValue: string | string[] ) => {
+			onChange={ ( nextValue ) => {
 				setValue( nextValue );
 				props.onChange?.( nextValue );
 			} }
@@ -109,7 +114,7 @@ MultipleSelection.args = {
 	),
 };
 
-const renderItem = ( gravatar: string | string[] ) => {
+const renderItem = ( gravatar: string | readonly string[] ) => {
 	const avatar = `https://gravatar.com/avatar?d=${ gravatar }`;
 	return (
 		<div style={ { display: 'flex', alignItems: 'center' } }>

package/src/custom-select-control-v2/test/index.tsx

@@ -47,11 +47,11 @@ const defaultProps = {
 };
 
 const ControlledCustomSelectControl = ( props: CustomSelectProps ) => {
-	const [ value, setValue ] = useState< string | string[] >();
+	const [ value, setValue ] = useState< string | readonly string[] >();
 	return (
 		<UncontrolledCustomSelectControlV2
 			{ ...props }
-			onChange={ ( nextValue: string | string[] ) => {
+			onChange={ ( nextValue ) => {
 				setValue( nextValue );
 				props.onChange?.( nextValue );
 			} }
@@ -375,7 +375,7 @@ describe.each( [
 	} );
 
 	it( 'Should allow rendering a custom value when using `renderSelectedValue`', async () => {
-		const renderValue = ( value: string | string[] ) => {
+		const renderValue = ( value: string | readonly string[] ) => {
 			return <img src={ `${ value }.jpg` } alt={ value as string } />;
 		};
 

package/src/custom-select-control-v2/types.ts

@@ -32,21 +32,21 @@ export type CustomSelectButtonProps = {
 	 * An optional default value for the control when used in uncontrolled mode.
 	 * If left `undefined`, the first non-disabled item will be used.
 	 */
-	defaultValue?: string | string[];
+	defaultValue?: string | readonly string[];
 	/**
 	 * A function that receives the new value of the input.
 	 */
-	onChange?: ( newValue: string | string[] ) => void;
+	onChange?: ( newValue: string | readonly string[] ) => void;
 	/**
 	 * Can be used to render select UI with custom styled values.
 	 */
 	renderSelectedValue?: (
-		selectedValue: string | string[]
+		selectedValue: string | readonly string[]
 	) => React.ReactNode;
 	/**
 	 * The value of the control when used in uncontrolled mode.
 	 */
-	value?: string | string[];
+	value?: string | readonly string[];
 };
 
 // Props only exposed on the internal implementation

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

@@ -314,7 +314,7 @@ function Day( {
 	onClick,
 	onKeyDown,
 }: DayProps ) {
-	const ref = useRef< HTMLButtonElement >();
+	const ref = useRef< HTMLButtonElement >( null );
 
 	// Focus the day when it becomes focusable, e.g. because an arrow key is
 	// pressed. Only do this if focus is allowed - this stops us stealing focus

package/src/date-time/stories/date-time.story.tsx

@@ -25,6 +25,11 @@ const meta: Meta< typeof DateTimePicker > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Consider using a `TextControl` with `type="date"` or `type="datetime-local"` instead.',
+		},
 	},
 };
 export default meta;

package/src/date-time/stories/date.story.tsx

@@ -25,6 +25,11 @@ const meta: Meta< typeof DatePicker > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Consider using a `TextControl` with `type="date"` or `type="datetime-local"` instead.',
+		},
 	},
 };
 export default meta;

package/src/date-time/stories/time.story.tsx

@@ -25,6 +25,11 @@ const meta: Meta< typeof TimePicker > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Consider using a `TextControl` with `type="date"` or `type="datetime-local"` instead.',
+		},
 	},
 };
 export default meta;

package/src/date-time/time/test/index.tsx

@@ -591,4 +591,46 @@ describe( 'TimePicker', () => {
 			} );
 		} );
 	} );
+
+	describe( 'ISO 8601 compliance', () => {
+		it( 'should handle years below 1000 with zero-padded output', async () => {
+			const user = userEvent.setup();
+			const onChangeSpy = jest.fn();
+
+			render(
+				<TimePicker
+					currentTime="0999-10-18T11:00:00"
+					onChange={ onChangeSpy }
+					is12Hour
+				/>
+			);
+
+			const yearInput = screen.getByLabelText( 'Year' );
+
+			// Verify initial input displays correctly
+			expect( yearInput ).toHaveValue( 999 );
+
+			// Change to year 500
+			await user.clear( yearInput );
+			await user.type( yearInput, '500' );
+			await user.keyboard( '{Tab}' );
+
+			// Verify input field value after change (human-readable, not zero-padded)
+			expect( yearInput ).toHaveValue( 500 );
+
+			// Verify onChange emits zero-padded ISO 8601 format
+			expect( onChangeSpy ).toHaveBeenCalled();
+			const lastCall =
+				onChangeSpy.mock.calls[ onChangeSpy.mock.calls.length - 1 ];
+			const outputDate = lastCall[ 0 ];
+
+			// Extract year from output and verify it's zero-padded to 4 digits
+			const yearMatch = outputDate.match( /^(\d{4})-/ );
+			expect( yearMatch ).not.toBeNull();
+			expect( yearMatch[ 1 ] ).toBe( '0500' ); // Explicitly verify zero-padded year
+
+			expect( outputDate ).not.toContain( 'NaN' );
+			expect( outputDate ).not.toContain( 'Invalid' );
+		} );
+	} );
 } );

package/src/date-time/utils.ts

@@ -139,7 +139,7 @@ export function setInConfiguredTimezone(
 		...updates,
 	};
 
-	const year = String( values.year );
+	const year = String( values.year ).padStart( 4, '0' );
 	const month = String( values.month + 1 ).padStart( 2, '0' );
 	const day = String( values.date ).padStart( 2, '0' );
 	const hours = String( values.hours ).padStart( 2, '0' );

package/src/disabled/context.ts

@@ -0,0 +1,6 @@
+import { createContext } from '@wordpress/element';
+
+const Context = createContext< boolean >( false );
+Context.displayName = 'DisabledContext';
+
+export default Context;

package/src/disabled/index.tsx

@@ -1,18 +1,8 @@
-/**
- * WordPress dependencies
- */
-import { createContext } from '@wordpress/element';
-
-/**
- * Internal dependencies
- */
 import { disabledStyles } from './styles/disabled-styles';
 import type { DisabledProps } from './types';
 import type { WordPressComponentProps } from '../context';
 import { useCx } from '../utils';
-
-const Context = createContext< boolean >( false );
-Context.displayName = 'DisabledContext';
+import Context from './context';
 
 const { Consumer, Provider } = Context;
 

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

@@ -30,6 +30,10 @@ const meta: Meta< typeof Disabled > = {
 			expanded: true,
 		},
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'global',
+		},
 	},
 };
 

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

@@ -36,6 +36,11 @@ const meta: Meta< typeof Divider > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'not-recommended',
+			whereUsed: 'global',
+			notes: 'Planned for deprecation.',
+		},
 	},
 };
 export default meta;

package/src/draggable/index.native.js

@@ -29,14 +29,14 @@ const { Provider } = Context;
 /**
  * Draggable component.
  *
- * @param {Object}      props               Component props.
- * @param {JSX.Element} props.children      Children to be rendered.
- * @param {Function}    [props.onDragEnd]   Callback when dragging ends.
- * @param {Function}    [props.onDragOver]  Callback when dragging happens over an element.
- * @param {Function}    [props.onDragStart] Callback when dragging starts.
- * @param {string}      [props.testID]      Id used for querying the pan gesture in tests.
+ * @param {Object}            props               Component props.
+ * @param {React.JSX.Element} props.children      Children to be rendered.
+ * @param {Function}          [props.onDragEnd]   Callback when dragging ends.
+ * @param {Function}          [props.onDragOver]  Callback when dragging happens over an element.
+ * @param {Function}          [props.onDragStart] Callback when dragging starts.
+ * @param {string}            [props.testID]      Id used for querying the pan gesture in tests.
  *
- * @return {JSX.Element} The component to be rendered.
+ * @return {React.JSX.Element} The component to be rendered.
  */
 const Draggable = ( {
 	children,
@@ -167,17 +167,17 @@ const Draggable = ( {
  *
  * This component acts as the trigger for the dragging functionality.
  *
- * @param {Object}      props                  Component props.
- * @param {JSX.Element} props.children         Children to be rendered.
- * @param {*}           props.id               Identifier passed within the event callbacks.
- * @param {boolean}     [props.enabled]        Enables the long-press gesture.
- * @param {number}      [props.maxDistance]    Maximum distance, that defines how far the finger is allowed to travel during a long press gesture.
- * @param {number}      [props.minDuration]    Minimum time, that a finger must remain pressed on the corresponding view.
- * @param {Function}    [props.onLongPress]    Callback when long-press gesture is triggered over an element.
- * @param {Function}    [props.onLongPressEnd] Callback when long-press gesture ends.
- * @param {string}      [props.testID]         Id used for querying the long-press gesture handler in tests.
+ * @param {Object}            props                  Component props.
+ * @param {React.JSX.Element} props.children         Children to be rendered.
+ * @param {*}                 props.id               Identifier passed within the event callbacks.
+ * @param {boolean}           [props.enabled]        Enables the long-press gesture.
+ * @param {number}            [props.maxDistance]    Maximum distance, that defines how far the finger is allowed to travel during a long press gesture.
+ * @param {number}            [props.minDuration]    Minimum time, that a finger must remain pressed on the corresponding view.
+ * @param {Function}          [props.onLongPress]    Callback when long-press gesture is triggered over an element.
+ * @param {Function}          [props.onLongPressEnd] Callback when long-press gesture ends.
+ * @param {string}            [props.testID]         Id used for querying the long-press gesture handler in tests.
  *
- * @return {JSX.Element} The component to be rendered.
+ * @return {React.JSX.Element} The component to be rendered.
  */
 const DraggableTrigger = ( {
 	children,

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

@@ -33,6 +33,11 @@ const meta: Meta< typeof Draggable > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { source: { code: '' } },
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'May be deprecated.',
+		},
 	},
 };
 export default meta;

package/src/draggable/types.ts

@@ -16,7 +16,7 @@ export type DraggableProps = {
 		 * `onDragEnd` handler.
 		 */
 		onDraggableEnd: ( event: DragEvent ) => void;
-	} ) => JSX.Element | null;
+	} ) => React.JSX.Element | null;
 	/**
 	 * Whether to append the cloned element to the `ownerDocument` body.
 	 * By default, elements sourced by id are appended to the element's wrapper.

package/src/drop-zone/stories/index.story.tsx

@@ -35,6 +35,10 @@ const meta: Meta< typeof DropZone > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'global',
+		},
 	},
 };
 export default meta;

package/src/drop-zone/types.ts

@@ -10,7 +10,7 @@ export type DropZoneProps = {
 	 *
 	 * @default "upload"
 	 */
-	icon?: JSX.Element;
+	icon?: React.JSX.Element;
 	/**
 	 * A string to be shown within the drop zone area.
 	 *

package/src/dropdown/index.tsx

@@ -61,7 +61,7 @@ const UnconnectedDropdown = (
 	// re-renders when the popover's anchor updates.
 	const [ fallbackPopoverAnchor, setFallbackPopoverAnchor ] =
 		useState< HTMLDivElement | null >( null );
-	const containerRef = useRef< HTMLDivElement >();
+	const containerRef = useRef< HTMLDivElement >( null );
 
 	const [ isOpen, setIsOpen ] = useControlledValue( {
 		defaultValue: defaultOpen,

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

@@ -41,6 +41,10 @@ const meta: Meta< typeof Dropdown > = {
 		controls: {
 			expanded: true,
 		},
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'global',
+		},
 	},
 };
 export default meta;

package/src/dropdown-menu/stories/index.story.tsx

@@ -30,6 +30,11 @@ const meta: Meta< typeof DropdownMenu > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'When building for the Gutenberg repo, use `Menu` instead. Otherwise, continue using for now.',
+		},
 	},
 	args: {
 		onToggle: fn(),

package/src/dropdown-menu/types.ts

@@ -58,7 +58,7 @@ type ToggleProps = Partial<
 		'label' | 'text'
 	>
 > & {
-	as?: React.ElementType | keyof JSX.IntrinsicElements;
+	as?: React.ElementType | keyof React.JSX.IntrinsicElements;
 	'data-toolbar-item'?: boolean;
 };
 

package/src/duotone-picker/stories/duotone-picker.story.tsx

@@ -24,6 +24,10 @@ const meta: Meta< typeof DuotonePicker > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'editor',
+		},
 	},
 };
 export default meta;

package/src/duotone-picker/stories/duotone-swatch.story.tsx

@@ -14,6 +14,10 @@ const meta: Meta< typeof DuotoneSwatch > = {
 	parameters: {
 		controls: { expanded: true },
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'editor',
+		},
 	},
 };
 export default meta;

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

@@ -21,6 +21,11 @@ const meta: Meta< typeof Elevation > = {
 			expanded: true,
 		},
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'not-recommended',
+			whereUsed: 'global',
+			notes: 'Planned for deprecation. Use [elevation tokens](?path=/docs/foundations-design-language-elevation--page) from `@wordpress/base-styles` instead.',
+		},
 	},
 };
 export default meta;

package/src/external-link/index.tsx

@@ -67,7 +67,11 @@ function UnforwardedExternalLink(
 				{ children }
 			</span>
 			<span
-				className="components-external-link__icon"
+				className={ clsx(
+					'components-external-link__icon',
+					// This class prevents the arrow from being replaced by a Twemoji image.
+					'wp-exclude-emoji'
+				) }
 				aria-label={
 					/* translators: accessibility text */
 					__( '(opens in a new tab)' )

package/src/external-link/stories/index.story.tsx

@@ -20,6 +20,10 @@ const meta: Meta< typeof ExternalLink > = {
 			expanded: true,
 		},
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'stable',
+			whereUsed: 'global',
+		},
 	},
 };
 export default meta;

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

@@ -31,6 +31,11 @@ const meta: Meta< typeof Flex > = {
 			expanded: true,
 		},
 		docs: { canvas: { sourceState: 'shown' } },
+		componentStatus: {
+			status: 'not-recommended',
+			whereUsed: 'global',
+			notes: 'Planned for deprecation. For use cases not covered by `HStack` and `VStack`, write your own CSS.',
+		},
 	},
 };
 export default meta;