@wordpress/components 19.8.4 → 19.11.0

package/src/circular-option-picker/style.scss

@@ -99,6 +99,7 @@ $color-palette-circle-spacing: 12px;
 		box-shadow: inset 0 0 0 1px rgba(0, 0, 0, 0.2);
 		// Show a thin circular outline in Windows high contrast mode, otherwise the button is invisible.
 		border: 1px solid transparent;
+		box-sizing: inherit;
 	}
 
 	&:focus {

package/src/color-palette/README.md

@@ -41,7 +41,6 @@ classes to be applied to the container.
 
 -   Type: `String`
 -   Required: No
--   Default: `Select or Upload Media`
 
 ### clearable
 

package/src/color-palette/index.js

@@ -6,7 +6,6 @@ import { map } from 'lodash';
 import { colord, extend } from 'colord';
 import namesPlugin from 'colord/plugins/names';
 import a11yPlugin from 'colord/plugins/a11y';
-import classnames from 'classnames';
 
 /**
  * WordPress dependencies
@@ -116,12 +115,12 @@ function MultiplePalettes( {
 export function CustomColorPickerDropdown( { isRenderedInSidebar, ...props } ) {
 	return (
 		<Dropdown
-			contentClassName={ classnames(
-				'components-color-palette__custom-color-dropdown-content',
-				{
-					'is-rendered-in-sidebar': isRenderedInSidebar,
-				}
-			) }
+			contentClassName="components-color-palette__custom-color-dropdown-content"
+			popoverProps={
+				isRenderedInSidebar
+					? { placement: 'left-start', offset: 20 }
+					: undefined
+			}
 			{ ...props }
 		/>
 	);
@@ -176,11 +175,6 @@ export default function ColorPalette( {
 		/>
 	);
 
-	let dropdownPosition;
-	if ( __experimentalIsRenderedInSidebar ) {
-		dropdownPosition = 'bottom left';
-	}
-
 	const colordColor = colord( value );
 
 	const valueWithoutLeadingHash = value?.startsWith( '#' )
@@ -211,7 +205,6 @@ export default function ColorPalette( {
 		<VStack spacing={ 3 } className={ className }>
 			{ ! disableCustomColors && (
 				<CustomColorPickerDropdown
-					position={ dropdownPosition }
 					isRenderedInSidebar={ __experimentalIsRenderedInSidebar }
 					renderContent={ renderCustomColorPicker }
 					renderToggle={ ( { isOpen, onToggle } ) => (

package/src/color-palette/style.scss

@@ -30,31 +30,16 @@
 	overflow: visible;
 	box-shadow: 0 4px 4px rgba(0, 0, 0, 0.05);
 	border: none;
+	outline: none;
 	border-radius: $radius-block-ui;
-	max-height: fit-content !important;
-	& > div {
-		padding: 0;
-	}
+	padding: 0;
+
 	.react-colorful__saturation {
 		border-top-right-radius: $radius-block-ui;
 		border-top-left-radius: $radius-block-ui;
 	}
 }
 
-@include break-medium() {
-	.components-dropdown__content.components-color-palette__custom-color-dropdown-content.is-rendered-in-sidebar {
-		.components-popover__content.components-popover__content {
-			margin-right: #{ math.div($sidebar-width, 2) + $grid-unit-20 };
-		}
-		&.is-from-top .components-popover__content {
-			margin-top: #{ -($grid-unit-60 + $grid-unit-15) };
-		}
-		&.is-from-bottom .components-popover__content {
-			margin-bottom: #{ -($grid-unit-60 + $grid-unit-15) };
-		}
-	}
-}
-
 .components-color-palette__custom-color-name {
 	text-align: left;
 }

package/src/color-palette/test/__snapshots__/index.js.snap

@@ -1186,13 +1186,12 @@ exports[`ColorPalette should render a dynamic toolbar of colors 1`] = `
                 >
                   <ForwardRef(Button)
                     className="components-circular-option-picker__clear"
-                    isSmall={true}
                     onClick={[Function]}
-                    variant="secondary"
+                    variant="tertiary"
                   >
                     <button
                       aria-describedby={null}
-                      className="components-button components-circular-option-picker__clear is-secondary is-small"
+                      className="components-button components-circular-option-picker__clear is-tertiary"
                       onClick={[Function]}
                       type="button"
                     >

package/src/confirm-dialog/stories/index.js

@@ -1,8 +1,3 @@
-/**
- * External dependencies
- */
-import { text } from '@storybook/addon-knobs';
-
 /**
  * WordPress dependencies
  */
@@ -15,102 +10,42 @@ import Button from '../../button';
 import { Heading } from '../../heading';
 import { ConfirmDialog } from '..';
 
-export default {
+const meta = {
 	component: ConfirmDialog,
 	title: 'Components (Experimental)/ConfirmDialog',
+	argTypes: {
+		children: {
+			control: { type: 'text' },
+		},
+		confirmButtonText: {
+			control: { type: 'text' },
+		},
+		cancelButtonText: {
+			control: { type: 'text' },
+		},
+		isOpen: {
+			control: { type: null },
+		},
+		onConfirm: {
+			control: { type: null },
+		},
+		onCancel: {
+			control: { type: null },
+		},
+	},
+	args: {
+		children: 'Would you like to privately publish the post now?',
+	},
 	parameters: {
-		knobs: { disable: false },
+		docs: { source: { state: 'open' } },
 	},
 };
 
-const daText = () =>
-	text( 'message', 'Would you like to privately publish the post now?' );
-const daCancelText = () => text( 'cancel button', 'No thanks' );
-const daConfirmText = () => text( 'confirm button', 'Yes please!' );
-
-// Simplest usage: just declare the component with the required `onConfirm` prop.
-export const _default = () => {
-	const [ confirmVal, setConfirmVal ] = useState( "Hasn't confirmed yet" );
-
-	return (
-		<>
-			<ConfirmDialog onConfirm={ () => setConfirmVal( 'Confirmed!' ) }>
-				{ daText() }
-			</ConfirmDialog>
-			<Heading level={ 1 }>{ confirmVal }</Heading>
-		</>
-	);
-};
-
-export const WithCustomButtonLabels = () => {
-	const [ confirmVal, setConfirmVal ] = useState( "Hasn't confirmed yet" );
-
-	return (
-		<>
-			<ConfirmDialog
-				onConfirm={ () => setConfirmVal( 'Confirmed!' ) }
-				cancelButtonText={ daCancelText() }
-				confirmButtonText={ daConfirmText() }
-			>
-				{ daText() }
-			</ConfirmDialog>
-			<Heading level={ 1 }>{ confirmVal }</Heading>
-		</>
-	);
-};
-
-export const WithJSXMessage = () => {
-	const [ confirmVal, setConfirmVal ] = useState( "Hasn't confirmed yet" );
-
-	return (
-		<>
-			<ConfirmDialog onConfirm={ () => setConfirmVal( 'Confirmed!' ) }>
-				<Heading level={ 2 }>{ daText() }</Heading>
-			</ConfirmDialog>
-			<Heading level={ 1 }>{ confirmVal }</Heading>
-		</>
-	);
-};
-
-export const VeeeryLongMessage = () => {
-	const [ confirmVal, setConfirmVal ] = useState( "Hasn't confirmed yet" );
+export default meta;
 
-	return (
-		<>
-			<ConfirmDialog onConfirm={ () => setConfirmVal( 'Confirmed!' ) }>
-				{ daText().repeat( 20 ) }
-			</ConfirmDialog>
-			<Heading level={ 1 }>{ confirmVal }</Heading>
-		</>
-	);
-};
-
-export const UncontrolledAndWithExplicitOnCancel = () => {
-	const [ confirmVal, setConfirmVal ] = useState(
-		"Hasn't confirmed or cancelled yet"
-	);
-
-	return (
-		<>
-			<ConfirmDialog
-				onConfirm={ () => setConfirmVal( 'Confirmed!' ) }
-				onCancel={ () => setConfirmVal( 'Cancelled' ) }
-			>
-				{ daText() }
-			</ConfirmDialog>
-			<Heading level={ 1 }>{ confirmVal }</Heading>
-		</>
-	);
-};
-
-// Controlled `ConfirmDialog`s require both `onConfirm` *and* `onCancel to be passed
-// It's expected that the user will then use it to hide the dialog, too (see the
-// `setIsOpen` calls below).
-export const Controlled = () => {
+const Template = ( args ) => {
 	const [ isOpen, setIsOpen ] = useState( false );
-	const [ confirmVal, setConfirmVal ] = useState(
-		"Hasn't confirmed or cancelled yet"
-	);
+	const [ confirmVal, setConfirmVal ] = useState( '' );
 
 	const handleConfirm = () => {
 		setConfirmVal( 'Confirmed!' );
@@ -121,22 +56,75 @@ export const Controlled = () => {
 		setConfirmVal( 'Cancelled' );
 		setIsOpen( false );
 	};
-
 	return (
 		<>
+			<Button variant="primary" onClick={ () => setIsOpen( true ) }>
+				Open ConfirmDialog
+			</Button>
+
 			<ConfirmDialog
+				{ ...args }
 				isOpen={ isOpen }
 				onConfirm={ handleConfirm }
 				onCancel={ handleCancel }
 			>
-				{ daText() }
+				{ args.children }
 			</ConfirmDialog>
 
 			<Heading level={ 1 }>{ confirmVal }</Heading>
-
-			<Button variant="primary" onClick={ () => setIsOpen( true ) }>
-				Open ConfirmDialog
-			</Button>
 		</>
 	);
 };
+
+// Simplest usage: just declare the component with the required `onConfirm` prop. Note: the `onCancel` prop is optional here, unless you'd like to render the component in Controlled mode (see below)
+export const _default = Template.bind( {} );
+const _defaultSnippet = `() => {
+  const [ isOpen, setIsOpen ] = useState( false );
+  const [ confirmVal, setConfirmVal ] = useState('');
+
+  const handleConfirm = () => {
+    setConfirmVal( 'Confirmed!' );
+    setIsOpen( false );
+  };
+
+  const handleCancel = () => {
+    setConfirmVal( 'Cancelled' );
+    setIsOpen( false );
+  };
+
+  return (
+    <>
+    <ConfirmDialog
+      isOpen={ isOpen }
+      onConfirm={ handleConfirm }
+      onCancel={ handleCancel }
+    >
+      Would you like to privately publish the post now?
+    </ConfirmDialog>
+
+    <Heading level={ 1 }>{ confirmVal }</Heading>
+
+    <Button variant="primary" onClick={ () => setIsOpen( true ) }>
+      Open ConfirmDialog
+    </Button>
+    </>
+    );
+  };`;
+_default.args = {};
+_default.parameters = {
+	docs: {
+		source: {
+			code: _defaultSnippet,
+			language: 'jsx',
+			type: 'auto',
+			format: 'true',
+		},
+	},
+};
+
+// To customize button text, pass the `cancelButtonText` and/or `confirmButtonText` props.
+export const withCustomButtonLabels = Template.bind( {} );
+withCustomButtonLabels.args = {
+	cancelButtonText: 'No thanks',
+	confirmButtonText: 'Yes please!',
+};

package/src/date-time/README.md

@@ -35,22 +35,20 @@ const MyDateTimePicker = () => {
 
 The component accepts the following props:
 
-### currentDate
+### `currentDate`: `Date | string | number | null`
 
 The current date and time at initialization. Optionally pass in a `null` value to specify no date is currently selected.
 
--   Type: `string`
 -   Required: No
 -   Default: today's date
 
-### onChange
+### `onChange`: `( date: string | null ) => void`
 
 The function called when a new date or time has been selected. It is passed the `currentDate` as an argument.
 
--   Type: `Function`
--   Required: Yes
+-   Required: No
 
-### is12Hour
+### `is12Hour`: `boolean`
 
 Whether we use a 12-hour clock. With a 12-hour clock, an AM/PM widget is displayed and the time format is assumed to be `MM-DD-YYYY` (as opposed to the default format `DD-MM-YYYY`).
 
@@ -58,16 +56,21 @@ Whether we use a 12-hour clock. With a 12-hour clock, an AM/PM widget is display
 -   Required: No
 -   Default: false
 
-### isInvalidDate
+### `isInvalidDate`: `( date: Date ) => boolean`
 
 A callback function which receives a Date object representing a day as an argument, and should return a Boolean to signify if the day is valid or not.
 
--   Type: `Function`
 -   Required: No
 
-### onMonthPreviewed
+### `onMonthPreviewed`: `( date: Date ) => void`
 
 A callback invoked when selecting the previous/next month in the date picker. The callback receives the new month date in the ISO format as an argument.
 
--   Type: `Function`
+-   Required: No
+
+### `events`: `{ date: Date }[]`
+
+List of events to show in the date picker. Each event will appear as a dot on the day of the event.
+
+-   Type: `Array`
 -   Required: No

package/src/date-time/{date.js → date.tsx}

@@ -3,10 +3,17 @@
  */
 import moment from 'moment';
 import classnames from 'classnames';
-
-// react-dates doesn't tree-shake correctly, so we import from the individual
-// component here, to avoid including too much of the library
-import DayPickerSingleDateController from 'react-dates/lib/components/DayPickerSingleDateController';
+import type { Moment } from 'moment';
+import { noop } from 'lodash';
+
+// `react-dates` doesn't tree-shake correctly, so we import from the individual
+// component here.
+// @ts-expect-error TypeScript won't find any type declarations at
+// `react-dates/lib/components/DayPickerSingleDateController` as they're located
+// at `react-dates`.
+import UntypedDayPickerSingleDateController from 'react-dates/lib/components/DayPickerSingleDateController';
+import type { DayPickerSingleDateController } from 'react-dates';
+const TypedDayPickerSingleDateController = UntypedDayPickerSingleDateController as DayPickerSingleDateController;
 
 /**
  * WordPress dependencies
@@ -18,15 +25,13 @@ import { isRTL, _n, sprintf } from '@wordpress/i18n';
  * Internal dependencies
  */
 import { getMomentDate } from './utils';
+import type { DatePickerDayProps, DatePickerProps } from './types';
 
-/**
- * Module Constants
- */
 const TIMEZONELESS_FORMAT = 'YYYY-MM-DDTHH:mm:ss';
 const ARIAL_LABEL_TIME_FORMAT = 'dddd, LL';
 
-function DatePickerDay( { day, events = [] } ) {
-	const ref = useRef();
+function DatePickerDay( { day, events = [] }: DatePickerDayProps ) {
+	const ref = useRef< HTMLDivElement >( null );
 
 	/*
 	 * a11y hack to make the `There is/are n events` string
@@ -36,7 +41,7 @@ function DatePickerDay( { day, events = [] } ) {
 	 */
 	useEffect( () => {
 		// Bail when no parent node.
-		if ( ! ref?.current?.parentNode ) {
+		if ( ! ( ref?.current?.parentNode instanceof Element ) ) {
 			return;
 		}
 
@@ -75,15 +80,34 @@ function DatePickerDay( { day, events = [] } ) {
 	);
 }
 
-function DatePicker( {
+/**
+ * DatePicker is a React component that renders a calendar for date selection.
+ *
+ * ```jsx
+ * import { DatePicker } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const MyDatePicker = () => {
+ *   const [ date, setDate ] = useState( new Date() );
+ *
+ *   return (
+ *     <DatePicker
+ *       currentDate={ date }
+ *       onChange={ ( newDate ) => setDate( newDate ) }
+ *     />
+ *   );
+ * };
+ * ```
+ */
+export function DatePicker( {
 	currentDate,
 	onChange,
 	events,
 	isInvalidDate,
 	onMonthPreviewed,
-} ) {
-	const nodeRef = useRef();
-	const onMonthPreviewedHandler = ( newMonthDate ) => {
+}: DatePickerProps ) {
+	const nodeRef = useRef< HTMLDivElement >( null );
+	const onMonthPreviewedHandler = ( newMonthDate: Moment ) => {
 		onMonthPreviewed?.( newMonthDate.toISOString() );
 		keepFocusInside();
 	};
@@ -111,7 +135,7 @@ function DatePicker( {
 			const focusRegion = nodeRef.current.querySelector(
 				'.DayPicker_focusRegion'
 			);
-			if ( ! focusRegion ) {
+			if ( ! ( focusRegion instanceof HTMLElement ) ) {
 				return;
 			}
 			// Keep the focus on focus region.
@@ -119,7 +143,11 @@ function DatePicker( {
 		}
 	};
 
-	const onChangeMoment = ( newDate ) => {
+	const onChangeMoment = ( newDate: Moment | null ) => {
+		if ( ! newDate ) {
+			return;
+		}
+
 		// If currentDate is null, use now as momentTime to designate hours, minutes, seconds.
 		const momentDate = currentDate ? moment( currentDate ) : moment();
 		const momentTime = {
@@ -128,13 +156,13 @@ function DatePicker( {
 			seconds: 0,
 		};
 
-		onChange( newDate.set( momentTime ).format( TIMEZONELESS_FORMAT ) );
+		onChange?.( newDate.set( momentTime ).format( TIMEZONELESS_FORMAT ) );
 
 		// Keep focus on the date picker.
 		keepFocusInside();
 	};
 
-	const getEventsPerDay = ( day ) => {
+	const getEventsPerDay = ( day: Moment ) => {
 		if ( ! events?.length ) {
 			return [];
 		}
@@ -148,7 +176,7 @@ function DatePicker( {
 
 	return (
 		<div className="components-datetime__date" ref={ nodeRef }>
-			<DayPickerSingleDateController
+			<TypedDayPickerSingleDateController
 				date={ momentDate }
 				daySize={ 30 }
 				focused
@@ -166,7 +194,7 @@ function DatePicker( {
 				dayAriaLabelFormat={ ARIAL_LABEL_TIME_FORMAT }
 				isRTL={ isRTL() }
 				isOutsideRange={ ( date ) => {
-					return isInvalidDate && isInvalidDate( date.toDate() );
+					return !! isInvalidDate && isInvalidDate( date.toDate() );
 				} }
 				onPrevMonthClick={ onMonthPreviewedHandler }
 				onNextMonthClick={ onMonthPreviewedHandler }
@@ -176,6 +204,7 @@ function DatePicker( {
 						events={ getEventsPerDay( day ) }
 					/>
 				) }
+				onFocusChange={ noop }
 			/>
 		</div>
 	);

package/src/date-time/{index.js → index.tsx}

@@ -5,6 +5,7 @@
 // See: https://github.com/airbnb/react-dates#initialize
 import 'react-dates/initialize';
 import { noop } from 'lodash';
+import type { ForwardedRef } from 'react';
 
 /**
  * WordPress dependencies
@@ -18,10 +19,11 @@ import { __, _x } from '@wordpress/i18n';
 import Button from '../button';
 import { default as DatePicker } from './date';
 import { default as TimePicker } from './time';
+import type { DateTimePickerProps } from './types';
 
 export { DatePicker, TimePicker };
 
-function DateTimePicker(
+function UnforwardedDateTimePicker(
 	{
 		currentDate,
 		is12Hour,
@@ -29,8 +31,8 @@ function DateTimePicker(
 		onMonthPreviewed = noop,
 		onChange,
 		events,
-	},
-	ref
+	}: DateTimePickerProps,
+	ref: ForwardedRef< any >
 ) {
 	const [ calendarHelpIsVisible, setCalendarHelpIsVisible ] = useState(
 		false
@@ -148,7 +150,7 @@ function DateTimePicker(
 					<Button
 						className="components-datetime__date-reset-button"
 						variant="link"
-						onClick={ () => onChange( null ) }
+						onClick={ () => onChange?.( null ) }
 					>
 						{ __( 'Reset' ) }
 					</Button>
@@ -167,4 +169,28 @@ function DateTimePicker(
 	);
 }
 
-export default forwardRef( DateTimePicker );
+/**
+ * DateTimePicker is a React component that renders a calendar and clock for
+ * date and time selection. The calendar and clock components can be accessed
+ * individually using the `DatePicker` and `TimePicker` components respectively.
+ *
+ * ```jsx
+ * import { DateTimePicker } from '@wordpress/components';
+ * import { useState } from '@wordpress/element';
+ *
+ * const MyDateTimePicker = () => {
+ *   const [ date, setDate ] = useState( new Date() );
+ *
+ *   return (
+ *     <DateTimePicker
+ *       currentDate={ date }
+ *       onChange={ ( newDate ) => setDate( newDate ) }
+ *       is12Hour
+ *     />
+ *   );
+ * };
+ * ```
+ */
+export const DateTimePicker = forwardRef( UnforwardedDateTimePicker );
+
+export default DateTimePicker;

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

@@ -0,0 +1,73 @@
+/**
+ * External dependencies
+ */
+import type { ComponentMeta, ComponentStory } from '@storybook/react';
+
+/**
+ * WordPress dependencies
+ */
+import { useState, useEffect } from '@wordpress/element';
+
+/**
+ * Internal dependencies
+ */
+import DatePicker from '../date';
+import { daysFromNow, isWeekend } from './utils';
+
+const meta: ComponentMeta< typeof DatePicker > = {
+	title: 'Components/DatePicker',
+	component: DatePicker,
+	argTypes: {
+		currentDate: { control: 'date' },
+		onChange: { action: 'onChange', control: { type: null } },
+	},
+	parameters: {
+		controls: { expanded: true },
+		docs: { source: { state: 'open' } },
+	},
+};
+export default meta;
+
+const Template: ComponentStory< typeof DatePicker > = ( {
+	currentDate,
+	onChange,
+	...args
+} ) => {
+	const [ date, setDate ] = useState( currentDate );
+	useEffect( () => {
+		setDate( currentDate );
+	}, [ currentDate ] );
+	return (
+		<DatePicker
+			{ ...args }
+			currentDate={ date }
+			onChange={ ( newDate ) => {
+				setDate( newDate );
+				onChange?.( newDate );
+			} }
+		/>
+	);
+};
+
+export const Default: ComponentStory< typeof DatePicker > = Template.bind( {} );
+
+export const WithEvents: ComponentStory< typeof DatePicker > = Template.bind(
+	{}
+);
+WithEvents.args = {
+	currentDate: new Date(),
+	events: [
+		{ date: daysFromNow( 2 ) },
+		{ date: daysFromNow( 4 ) },
+		{ date: daysFromNow( 6 ) },
+		{ date: daysFromNow( 8 ) },
+	],
+};
+
+export const WithInvalidDates: ComponentStory<
+	typeof DatePicker
+> = Template.bind( {} );
+WithInvalidDates.args = {
+	currentDate: new Date(),
+	isInvalidDate: isWeekend,
+};