@wordpress/components 21.3.0 → 22.1.0

package/src/custom-select-control/README.md

@@ -131,6 +131,20 @@ Start opting into the unconstrained width style that will become the default in
 -   Required: No
 -   Default: `false`
 
+#### onMouseOver
+
+A handler for onMouseOver events.
+
+-   Type: `Function`
+-   Required: No
+
+#### onMouseOut
+
+A handler for onMouseOut events.
+
+-   Type: `Function`
+-   Required: No
+
 ## Related components
 
 -   Like this component, but implemented using a native `<select>` for when custom styling is not necessary, the `SelectControl` component.

package/src/custom-select-control/index.js

@@ -61,21 +61,27 @@ const stateReducer = (
 			return changes;
 	}
 };
-export default function CustomSelectControl( {
-	/** Start opting into the larger default height that will become the default size in a future version. */
-	__next36pxDefaultSize = false,
-	/** Start opting into the unconstrained width that will become the default in a future version. */
-	__nextUnconstrainedWidth = false,
-	className,
-	hideLabelFromVision,
-	label,
-	describedBy,
-	options: items,
-	onChange: onSelectedItemChange,
-	/** @type {import('../select-control/types').SelectControlProps.size} */
-	size = 'default',
-	value: _selectedItem,
-} ) {
+
+export default function CustomSelectControl( props ) {
+	const {
+		/** Start opting into the larger default height that will become the default size in a future version. */
+		__next36pxDefaultSize = false,
+		/** Start opting into the unconstrained width that will become the default in a future version. */
+		__nextUnconstrainedWidth = false,
+		className,
+		hideLabelFromVision,
+		label,
+		describedBy,
+		options: items,
+		onChange: onSelectedItemChange,
+		/** @type {import('../select-control/types').SelectControlProps.size} */
+		size = 'default',
+		value: _selectedItem,
+		onMouseOver,
+		onMouseOut,
+		__experimentalShowSelectedHint = false,
+	} = props;
+
 	const {
 		getLabelProps,
 		getToggleButtonProps,
@@ -173,6 +179,8 @@ export default function CustomSelectControl( {
 				suffix={ <SelectControlChevronDown /> }
 			>
 				<SelectControlSelect
+					onMouseOver={ onMouseOver }
+					onMouseOut={ onMouseOut }
 					as="button"
 					onFocus={ () => setIsFocused( true ) }
 					onBlur={ () => setIsFocused( false ) }
@@ -187,6 +195,12 @@ export default function CustomSelectControl( {
 					} ) }
 				>
 					{ itemToString( selectedItem ) }
+					{ __experimentalShowSelectedHint &&
+						selectedItem.__experimentalHint && (
+							<span className="components-custom-select-control__hint">
+								{ selectedItem.__experimentalHint }
+							</span>
+						) }
 				</SelectControlSelect>
 			</InputBaseWithBackCompatMinWidth>
 			{ /* eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions */ }

package/src/custom-select-control/stories/index.js

@@ -8,6 +8,7 @@ export default {
 	component: CustomSelectControl,
 	argTypes: {
 		__next36pxDefaultSize: { control: { type: 'boolean' } },
+		__experimentalShowSelectedHint: { control: { type: 'boolean' } },
 		size: {
 			control: {
 				type: 'radio',

package/src/custom-select-control/style.scss

@@ -9,6 +9,11 @@
 	outline: 0; // focus ring is handled elsewhere
 }
 
+.components-custom-select-control__hint {
+	color: $gray-600;
+	margin-left: 10px;
+}
+
 .components-custom-select-control__menu {
 	// Hide when collapsed.
 	&[aria-hidden="true"] {
@@ -50,7 +55,7 @@
 		background: $gray-300;
 	}
 	.components-custom-select-control__item-hint {
-		color: $gray-700;
+		color: $gray-600;
 		text-align: right;
 		padding-right: $grid-unit-05;
 	}

package/src/custom-select-control/test/index.js

@@ -46,4 +46,43 @@ describe( 'CustomSelectControl', () => {
 
 		expect( onKeyDown ).toHaveBeenCalledTimes( 0 );
 	} );
+
+	it( 'does not show selected hint by default', () => {
+		render(
+			<CustomSelectControl
+				label="Custom select"
+				options={ [
+					{
+						key: 'one',
+						name: 'One',
+						__experimentalHint: 'Hint',
+					},
+				] }
+				__nextUnconstrainedWidth
+			/>
+		);
+		expect(
+			screen.getByRole( 'button', { name: 'Custom select' } )
+		).not.toHaveTextContent( 'Hint' );
+	} );
+
+	it( 'shows selected hint when __experimentalShowSelectedHint is set', () => {
+		render(
+			<CustomSelectControl
+				label="Custom select"
+				options={ [
+					{
+						key: 'one',
+						name: 'One',
+						__experimentalHint: 'Hint',
+					},
+				] }
+				__experimentalShowSelectedHint
+				__nextUnconstrainedWidth
+			/>
+		);
+		expect(
+			screen.getByRole( 'button', { name: 'Custom select' } )
+		).toHaveTextContent( 'Hint' );
+	} );
 } );

package/src/dashicon/index.js

@@ -3,6 +3,7 @@
  *
  * @property {import('./types').IconKey} icon        Icon name
  * @property {string}                    [className] Class name
+ * @property {number}                    [size]      Size of the icon
  */
 /** @typedef {import('react').ComponentPropsWithoutRef<'span'> & OwnProps} Props */
 
@@ -10,7 +11,8 @@
  * @param {Props} props
  * @return {JSX.Element} Element
  */
-function Dashicon( { icon, className, ...extraProps } ) {
+
+function Dashicon( { icon, className, size = 20, style = {}, ...extraProps } ) {
 	const iconClass = [
 		'dashicon',
 		'dashicons',
@@ -20,7 +22,24 @@ function Dashicon( { icon, className, ...extraProps } ) {
 		.filter( Boolean )
 		.join( ' ' );
 
-	return <span className={ iconClass } { ...extraProps } />;
+	// For retro-compatibility reasons (for example if people are overriding icon size with CSS), we add inline styles just if the size is different to the default
+	const sizeStyles =
+		// using `!=` to catch both 20 and "20"
+		// eslint-disable-next-line eqeqeq
+		20 != size
+			? {
+					fontSize: `${ size }px`,
+					width: `${ size }px`,
+					height: `${ size }px`,
+			  }
+			: {};
+
+	const styles = {
+		...sizeStyles,
+		...style,
+	};
+
+	return <span className={ iconClass } style={ styles } { ...extraProps } />;
 }
 
 export default Dashicon;

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

@@ -16,7 +16,7 @@ describe( 'DatePicker', () => {
 
 		expect(
 			screen.getByRole( 'button', { name: 'May 2, 2022. Selected' } )
-		).not.toBeNull();
+		).toBeInTheDocument();
 	} );
 
 	it( "should highlight today's date when not provided a currentDate", () => {
@@ -27,7 +27,7 @@ describe( 'DatePicker', () => {
 			screen.getByRole( 'button', {
 				name: `${ todayDescription }. Selected`,
 			} )
-		).not.toBeNull();
+		).toBeInTheDocument();
 	} );
 
 	it( 'should call onChange when a day is selected', async () => {

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

@@ -207,6 +207,8 @@ function UnforwardedDateTimePicker(
  *       currentDate={ date }
  *       onChange={ ( newDate ) => setDate( newDate ) }
  *       is12Hour
+ *       __nextRemoveHelpButton
+ *       __nextRemoveResetButton
  *     />
  *   );
  * };

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

@@ -52,6 +52,10 @@ const Template: ComponentStory< typeof DateTimePicker > = ( {
 export const Default: ComponentStory< typeof DateTimePicker > = Template.bind(
 	{}
 );
+Default.args = {
+	__nextRemoveHelpButton: true,
+	__nextRemoveResetButton: true,
+};
 
 export const WithEvents: ComponentStory< typeof DateTimePicker > =
 	Template.bind( {} );

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

@@ -180,7 +180,7 @@ export function TimePicker( {
 			min={ 1 }
 			max={ 31 }
 			required
-			hideHTMLArrows
+			spinControls="none"
 			isPressEnterToChange
 			isDragEnabled={ false }
 			isShiftStepEnabled={ false }
@@ -246,7 +246,7 @@ export function TimePicker( {
 							min={ is12Hour ? 1 : 0 }
 							max={ is12Hour ? 12 : 23 }
 							required
-							hideHTMLArrows
+							spinControls="none"
 							isPressEnterToChange
 							isDragEnabled={ false }
 							isShiftStepEnabled={ false }
@@ -273,7 +273,7 @@ export function TimePicker( {
 							min={ 0 }
 							max={ 59 }
 							required
-							hideHTMLArrows
+							spinControls="none"
 							isPressEnterToChange
 							isDragEnabled={ false }
 							isShiftStepEnabled={ false }
@@ -344,7 +344,7 @@ export function TimePicker( {
 						min={ 1 }
 						max={ 9999 }
 						required
-						hideHTMLArrows
+						spinControls="none"
 						isPressEnterToChange
 						isDragEnabled={ false }
 						isShiftStepEnabled={ false }

package/src/date-time/types.ts

@@ -1,8 +1,3 @@
-/**
- * External dependencies
- */
-import type { Moment } from 'moment';
-
 export type TimePickerProps = {
 	/**
 	 * The initial current time the time picker should render.
@@ -30,20 +25,6 @@ export type DatePickerEvent = {
 	date: Date;
 };
 
-export type DatePickerDayProps = {
-	/**
-	 * The day to display.
-	 */
-	day: Moment;
-
-	/**
-	 * List of events to show on this day.
-	 *
-	 * @default []
-	 */
-	events?: DatePickerEvent[];
-};
-
 export type DatePickerProps = {
 	/**
 	 * The current date and time at initialization. Optionally pass in a `null`

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

@@ -38,6 +38,7 @@ exports[`DimensionControl rendering renders with custom sizes 1`] = `
   -webkit-justify-content: space-between;
   justify-content: space-between;
   height: 100%;
+  box-sizing: border-box;
   position: relative;
   border-radius: 2px;
   padding-top: 0;
@@ -309,6 +310,7 @@ exports[`DimensionControl rendering renders with defaults 1`] = `
   -webkit-justify-content: space-between;
   justify-content: space-between;
   height: 100%;
+  box-sizing: border-box;
   position: relative;
   border-radius: 2px;
   padding-top: 0;
@@ -590,6 +592,7 @@ exports[`DimensionControl rendering renders with icon and custom icon label 1`]
   -webkit-justify-content: space-between;
   justify-content: space-between;
   height: 100%;
+  box-sizing: border-box;
   position: relative;
   border-radius: 2px;
   padding-top: 0;
@@ -883,6 +886,7 @@ exports[`DimensionControl rendering renders with icon and default icon label 1`]
   -webkit-justify-content: space-between;
   justify-content: space-between;
   height: 100%;
+  box-sizing: border-box;
   position: relative;
   border-radius: 2px;
   padding-top: 0;

package/src/disabled/README.md

@@ -47,6 +47,8 @@ function CustomButton( props ) {
 }
 ```
 
+_Note: this component may not behave as expected in browsers that don't support [the `inert` HTML attribute](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/inert). We recommend adding [the official WICG polyfill](https://github.com/WICG/inert) when using this component in your project._
+
 ### Props
 
 The component accepts the following props:

package/src/disabled/index.tsx

@@ -15,7 +15,14 @@ const Context = createContext< boolean >( false );
 const { Consumer, Provider } = Context;
 
 /**
- * `Disabled` is a component which disables descendant tabbable elements and prevents pointer interaction.
+ * `Disabled` is a component which disables descendant tabbable elements and
+ * prevents pointer interaction.
+ *
+ * _Note: this component may not behave as expected in browsers that don't
+ * support the `inert` HTML attribute. We recommend adding the official WICG
+ * polyfill when using this component in your project._
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/inert
  *
  * ```jsx
  * import { Button, Disabled, TextControl } from '@wordpress/components';

package/src/disabled/test/index.tsx

@@ -24,7 +24,6 @@ describe( 'Disabled', () => {
 			</Disabled>
 		);
 
-		// @ts-ignore
 		expect( container.firstChild ).toHaveAttribute( 'inert' );
 	} );
 
@@ -40,12 +39,10 @@ describe( 'Disabled', () => {
 
 		const { container, rerender } = render( <MaybeDisable /> );
 
-		// @ts-ignore
 		expect( container.firstChild ).toHaveAttribute( 'inert' );
 
 		rerender( <MaybeDisable isDisabled={ false } /> );
 
-		// @ts-ignore
 		expect( container.firstChild ).not.toHaveAttribute( 'inert' );
 	} );
 
@@ -58,12 +55,10 @@ describe( 'Disabled', () => {
 
 		const { rerender, container } = render( <MaybeDisable /> );
 
-		// @ts-ignore
 		expect( container.firstChild ).toHaveAttribute( 'inert' );
 
 		rerender( <MaybeDisable isDisabled={ false } /> );
 
-		// @ts-ignore
 		expect( container.firstChild ).not.toHaveAttribute( 'inert' );
 	} );
 

package/src/divider/test/index.tsx

@@ -9,15 +9,13 @@ import { render, screen } from '@testing-library/react';
 import { Divider } from '..';
 
 describe( 'props', () => {
-	beforeEach( () => {
-		render( <Divider /> );
-	} );
-
 	test( 'should render correctly', () => {
+		render( <Divider /> );
 		expect( screen.getByRole( 'separator' ) ).toMatchSnapshot();
 	} );
 
 	test( 'should render marginStart', () => {
+		render( <Divider /> );
 		render( <Divider marginStart={ 5 } /> );
 
 		const dividers = screen.getAllByRole( 'separator' );
@@ -25,6 +23,7 @@ describe( 'props', () => {
 	} );
 
 	test( 'should render marginEnd', () => {
+		render( <Divider /> );
 		render( <Divider marginEnd={ 5 } /> );
 
 		const dividers = screen.getAllByRole( 'separator' );
@@ -32,6 +31,7 @@ describe( 'props', () => {
 	} );
 
 	test( 'should render margin', () => {
+		render( <Divider /> );
 		render( <Divider margin={ 7 } /> );
 
 		const dividers = screen.getAllByRole( 'separator' );

package/src/draggable/README.md

@@ -1,6 +1,6 @@
 # Draggable
 
-`Draggable` is a Component that provides a way to set up a cross-browser (including IE) customisable drag image and the transfer data for the drag event. It decouples the drag handle and the element to drag: use it by wrapping the component that will become the drag handle and providing the DOM ID of the element to drag.
+`Draggable` is a Component that provides a way to set up a cross-browser (including IE) customizable drag image and the transfer data for the drag event. It decouples the drag handle and the element to drag: use it by wrapping the component that will become the drag handle and providing the DOM ID of the element to drag.
 
 Note that the drag handle needs to declare the `draggable="true"` property and bind the `Draggable`s `onDraggableStart` and `onDraggableEnd` event handlers to its own `onDragStart` and `onDragEnd` respectively. `Draggable` takes care of the logic to setup the drag image and the transfer data, but is not concerned with creating an actual DOM element that is draggable.
 
@@ -8,44 +8,39 @@ Note that the drag handle needs to declare the `draggable="true"` property and b
 
 The component accepts the following props:
 
-### elementId
+### `elementId`: `string`
 
 The HTML id of the element to clone on drag
 
--   Type: `string`
 -   Required: Yes
 
-### transferData
+### `onDragEnd`: `( event: DragEvent ) => void`
 
-Arbitrary data object attached to the drag and drop event.
-
--   Type: `Object`
--   Required: Yes
-
-### onDragStart
-
-A function called when dragging starts. This callback receives the `event` object from the `dragstart` event as its first parameter.
+A function called when dragging ends. This callback receives the `event` object from the `dragend` event as its first parameter.
 
--   Type: `Function`
 -   Required: No
 -   Default: `noop`
 
-### onDragOver
+### `onDragOver`: `( event: DragEvent ) => void`
 
 A function called when the element being dragged is dragged over a valid drop target. This callback receives the `event` object from the `dragover` event as its first parameter.
 
--   Type: `Function`
 -   Required: No
 -   Default: `noop`
 
-### onDragEnd
+### `onDragStart`: `( event: DragEvent ) => void`
 
-A function called when dragging ends. This callback receives the `event` object from the `dragend` event as its first parameter.
+A function called when dragging starts. This callback receives the `event` object from the `dragstart` event as its first parameter.
 
--   Type: `Function`
 -   Required: No
 -   Default: `noop`
 
+### `transferData`: `unknown`
+
+Arbitrary data object attached to the drag and drop event.
+
+-   Required: Yes
+
 ## Usage
 
 ```jsx