@wordpress/components 29.12.0 → 30.0.0

package/src/calendar/types.ts

@@ -0,0 +1,342 @@
+/**
+ * External dependencies
+ */
+import type { Locale } from 'date-fns';
+import type * as React from 'react';
+
+/**
+ * Represents the modifiers that match a specific day in the calendar.
+ * @example
+ *   const modifiers: Modifiers = {
+ *   today: false, // the day is not today
+ *   selected: true, // the day is selected
+ *   disabled: false, // the day is not disabled
+ *   outside: false, // the day is not outside the month
+ *   focused: false, // the day is not focused
+ *
+ *   weekend: false // custom modifier example for matching a weekend
+ *   booked: true // custom modifier example for matching a booked day
+ *   available: false // custom modifier example for matching an available day
+ *   };
+ */
+export type Modifiers = Record< string, boolean >;
+
+/**
+ * A value or a function that matches a specific day.
+ * @example
+ *   // will always match the day
+ *   const booleanMatcher: Matcher = true;
+ *
+ *   // will match the today's date
+ *   const dateMatcher: Matcher = new Date();
+ *
+ *   // will match the days in the array
+ *   const arrayMatcher: Matcher = [
+ *     new Date(2019, 1, 2),
+ *     new Date(2019, 1, 4)
+ *   ];
+ *
+ *   // will match days after the 2nd of February 2019
+ *   const afterMatcher: DateAfter = { after: new Date(2019, 1, 2) };
+ *
+ *   // will match days before the 2nd of February 2019 }
+ *   const beforeMatcher: DateBefore = { before: new Date(2019, 1, 2) };
+ *
+ *   // will match Sundays
+ *   const dayOfWeekMatcher: DayOfWeek = {
+ *     dayOfWeek: 0
+ *   };
+ *
+ *   // will match the included days, except the two dates
+ *   const intervalMatcher: DateInterval = {
+ *     after: new Date(2019, 1, 2),
+ *     before: new Date(2019, 1, 5)
+ *   };
+ *
+ *   // will match the included days, including the two dates
+ *   const rangeMatcher: DateRange = {
+ *     from: new Date(2019, 1, 2),
+ *     to: new Date(2019, 1, 5)
+ *   };
+ *
+ *   // will match when the function return true
+ *   const functionMatcher: Matcher = (day: Date) => {
+ *     return day.getMonth() === 2; // match when month is March
+ *   };
+ */
+type Matcher =
+	| boolean
+	| ( ( date: Date ) => boolean )
+	| Date
+	| Date[]
+	| DateRange
+	| DateBefore
+	| DateAfter
+	| DateInterval
+	| DayOfWeek;
+/**
+ * Match a day falling after the specified date, with the date not included.
+ * @example
+ *   // Match days after the 2nd of February 2019
+ *   const matcher: DateAfter = { after: new Date(2019, 1, 2) };
+ */
+type DateAfter = {
+	after: Date;
+};
+/**
+ * Match a day falling before the specified date, with the date not included.
+ * @example
+ *   // Match days before the 2nd of February 2019
+ *   const matcher: DateBefore = { before: new Date(2019, 1, 2) };
+ */
+type DateBefore = {
+	before: Date;
+};
+/**
+ * An interval of dates. Differently from `DateRange`, the range ends here
+ * are not included.
+ * @example
+ *   // Match the days between the 2nd and the 5th of February 2019
+ *   const matcher: DateInterval = {
+ *     after: new Date(2019, 1, 2),
+ *     before: new Date(2019, 1, 5)
+ *   };
+ */
+type DateInterval = {
+	before: Date;
+	after: Date;
+};
+/**
+ * A range of dates. The range can be open. Differently from
+ * `DateInterval`, the range ends here are included.
+ * @example
+ *   // Match the days between the 2nd and the 5th of February 2019
+ *   const matcher: DateRange = {
+ *     from: new Date(2019, 1, 2),
+ *     to: new Date(2019, 1, 5)
+ *   };
+ */
+export type DateRange = {
+	from: Date | undefined;
+	to?: Date | undefined;
+};
+/**
+ * Match dates being one of the specified days of the week (`0-6`, where `0` is
+ * Sunday).
+ * @example
+ *   // Match Sundays
+ *   const matcher: DayOfWeek = { dayOfWeek: 0 };
+ *   // Match weekends
+ *   const matcher: DayOfWeek = { dayOfWeek: [0, 6] };
+ */
+type DayOfWeek = {
+	dayOfWeek: number | number[];
+};
+
+/**
+ * Shared handler type for `onSelect` callback when a selection mode is set.
+ * @example
+ *   const handleSelect: OnSelectHandler<Date> = (
+ *     selected,
+ *     triggerDate,
+ *     modifiers,
+ *     e
+ *   ) => {
+ *     console.log( "Selected:", selected );
+ *     console.log( "Triggered by:", triggerDate );
+ *   };
+ * @template T - The type of the selected item.
+ * @callback OnSelectHandler
+ * @param {T}                                      selected    - The selected item after the event.
+ * @param {Date}                                   triggerDate - The date when the event was triggered. This is
+ *                                                             typically the day clicked or interacted with.
+ * @param {Modifiers}                              modifiers   - The modifiers associated with the event.
+ * @param {React.MouseEvent | React.KeyboardEvent} e           - The event object.
+ */
+export type OnSelectHandler< T > = (
+	selected: T,
+	triggerDate: Date,
+	modifiers: Modifiers,
+	e: React.MouseEvent | React.KeyboardEvent
+) => void;
+
+export interface BaseProps
+	extends Omit<
+		React.HTMLAttributes< HTMLDivElement >,
+		'onSelect' | 'defaultValue'
+	> {
+	/**
+	 * Whether the selection is required.
+	 * When `true`, there always needs to be a date selected.
+	 * @default false
+	 */
+	required?: boolean;
+
+	/**
+	 * The initial month to show in the calendar view (uncontrolled).
+	 * @default The current month
+	 */
+	defaultMonth?: Date;
+	/**
+	 * The month displayed in the calendar view (controlled). Use together with
+	 * `onMonthChange` to change the month programmatically.
+	 */
+	month?: Date;
+	/**
+	 * The number of months displayed at once.
+	 * @default 1
+	 */
+	numberOfMonths?: number;
+	/**
+	 * The earliest month to start the month navigation.
+	 */
+	startMonth?: Date;
+	/**
+	 * The latest month to end the month navigation.
+	 */
+	endMonth?: Date;
+	/**
+	 * 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).
+	 */
+	autoFocus?: boolean;
+	/**
+	 * Specify which days are disabled. Using `true` will disable all dates.
+	 */
+	disabled?: Matcher | Matcher[] | undefined;
+	/**
+	 * Disable the navigation buttons.
+	 */
+	disableNavigation?: boolean;
+	/**
+	 * Use custom labels, useful for translating the component.
+	 *
+	 * For a correct localized experience, consumers should make sure the locale
+	 * used for the translated labels and `locale` prop are consistent.
+	 */
+	labels?: {
+		/**
+		 * The label for the navigation toolbar.
+		 * @default ""
+		 */
+		labelNav?: () => string;
+		/**
+		 * The label for the month grid.
+		 * @default "LLLL y" (e.g. "November 2022")
+		 */
+		labelGrid?: ( date: Date ) => string;
+		/**
+		 * The label for the gridcell, when the calendar is not interactive.
+		 * @default The formatted date.
+		 */
+		labelGridcell?: ( date: Date, modifiers?: Modifiers ) => string;
+		/**
+		 * The label for the "next month" button.
+		 * @default "Go to the Next Month"
+		 */
+		labelNext?: ( month: Date | undefined ) => string;
+		/**
+		 * The label for the "previous month" button.
+		 * @default "Go to the Previous Month"
+		 */
+		labelPrevious?: ( month: Date | undefined ) => string;
+		/**
+		 * The label for the day button.
+		 * @default The formatted date.
+		 */
+		labelDayButton?: ( date: Date, modifiers?: Modifiers ) => string;
+		/**
+		 * The label for the weekday.
+		 * @default ( date: Date ) => "Monday" | "Tuesday" | "Wednesday" | "Thursday" | "Friday" | "Saturday" | "Sunday"
+		 */
+		labelWeekday?: ( date: Date ) => string;
+	};
+
+	/**
+	 * The locale object used to localize dates. Pass a locale from
+	 * `@date-fns/locale` to localize the calendar.
+	 *
+	 * For a correct localized experience, consumers should make sure the locale
+	 * used for the translated labels and `locale` prop are consistent.
+	 * @see https://github.com/date-fns/date-fns/tree/main/src/locale for a list of the supported locales
+	 * @default The `enUS` locale from `@date-fns/locale`
+	 */
+	locale?: Locale;
+	/**
+	 * The index of the first day of the week (0 - Sunday). Overrides the locale's
+	 * one.
+	 * @default Based on the `locale` prop
+	 */
+	weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined;
+	/**
+	 * Event fired when the user navigates between months.
+	 */
+	onMonthChange?: ( month: Date ) => void;
+	/**
+	 * 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 the possible values.
+	 *
+	 * When working with time zones, use the `TZDate` object exported by this
+	 * package instead of the native `Date` object.
+	 * @example
+	 *   import { DateCalendar, TZDate } from "@wordpress/components";
+	 *
+	 *   export function WithTimeZone() {
+	 *     const timeZone = "America/New_York";
+	 *     const [ selected, setSelected ] = useState< Date | undefined >(
+	 *       new TZDate( 2024, 12, 10, timeZone ) // Use `TZDate` instead of `Date`
+	 *     );
+	 *     return (
+	 *       <DateCalendar
+	 *         timeZone={ timeZone }
+	 *         selected={ selected }
+	 *         onSelect={ setSelected }
+	 *     />
+	 *   );
+	 * }
+	 */
+	timeZone?: string;
+	/**
+	 * The role attribute to add to the container element.
+	 * @default 'application'
+	 */
+	role?: 'application' | 'dialog' | undefined;
+}
+
+interface SingleProps {
+	/** The selected date. */
+	selected?: Date | undefined | null;
+	/** Event handler when a day is selected. */
+	onSelect?: OnSelectHandler< Date | undefined >;
+	/** The default selected date (for uncontrolled usage). */
+	defaultSelected?: Date;
+}
+
+interface RangeProps {
+	/**
+	 * When `true`, the range will reset when including a disabled day.
+	 */
+	excludeDisabled?: boolean;
+	/**
+	 * The minimum number of nights to include in the range.
+	 */
+	min?: number;
+	/**
+	 * The maximum number of nights to include in the range.
+	 */
+	max?: number;
+	/** The selected range. */
+	selected?: DateRange | undefined | null;
+	/** Event handler when the selection changes. */
+	onSelect?: OnSelectHandler< DateRange | undefined >;
+	/** The default selected range (for uncontrolled usage). */
+	defaultSelected?: DateRange;
+}
+
+export type DateCalendarProps = BaseProps & SingleProps;
+export type DateRangeCalendarProps = BaseProps & RangeProps;

package/src/calendar/utils/constants.ts

@@ -0,0 +1,62 @@
+/**
+ * Internal dependencies
+ */
+import { Day } from './day-cell';
+
+const CLASSNAMES = {
+	root: 'components-calendar',
+	day: 'components-calendar__day',
+	day_button: 'components-calendar__day-button',
+	caption_label: 'components-calendar__caption-label',
+	button_next: 'components-calendar__button-next',
+	button_previous: 'components-calendar__button-previous',
+	chevron: 'components-calendar__chevron',
+	nav: 'components-calendar__nav',
+	month_caption: 'components-calendar__month-caption',
+	months: 'components-calendar__months',
+	month_grid: 'components-calendar__month-grid',
+	weekday: 'components-calendar__weekday',
+	today: 'components-calendar__day--today',
+	selected: 'components-calendar__day--selected',
+	disabled: 'components-calendar__day--disabled',
+	hidden: 'components-calendar__day--hidden',
+	range_start: 'components-calendar__range-start',
+	range_end: 'components-calendar__range-end',
+	range_middle: 'components-calendar__range-middle',
+	weeks_before_enter: 'components-calendar__weeks-before-enter',
+	weeks_before_exit: 'components-calendar__weeks-before-exit',
+	weeks_after_enter: 'components-calendar__weeks-after-enter',
+	weeks_after_exit: 'components-calendar__weeks-after-exit',
+	caption_after_enter: 'components-calendar__caption-after-enter',
+	caption_after_exit: 'components-calendar__caption-after-exit',
+	caption_before_enter: 'components-calendar__caption-before-enter',
+	caption_before_exit: 'components-calendar__caption-before-exit',
+};
+export const MODIFIER_CLASSNAMES = {
+	preview: 'components-calendar__day--preview',
+	preview_start: 'components-calendar__day--preview-start',
+	preview_end: 'components-calendar__day--preview-end',
+};
+
+export const COMMON_PROPS = {
+	animate: true,
+	// Only show days in the current month
+	showOutsideDays: false,
+	// Hide week number column
+	showWeekNumber: false,
+	// Show weekdays row
+	hideWeekdays: false,
+	// Month and year caption are not interactive
+	captionLayout: 'label',
+	// Show a variable number of weeks depending on the month
+	fixedWeeks: false,
+	// Show navigation buttons
+	hideNavigation: false,
+	// Class names
+	classNames: CLASSNAMES,
+	// Default role
+	role: 'application',
+	components: {
+		Day,
+	},
+} as const;

package/src/calendar/utils/day-cell.tsx

@@ -0,0 +1,133 @@
+/**
+ * External dependencies
+ */
+import type { CalendarDay } from 'react-day-picker';
+/**
+ * Internal dependencies
+ */
+import type { Modifiers } from '../types';
+
+/**
+ * The dash array and offset are calculated by:
+ * - measuring the path length (eg 92,28384)
+ * - establishing how many segments should the path be split into (eg. 24)
+ * - dividing the path length by the number of segments (eg. 92,28384 / 24 = 3,84516)
+ * - playing with the dash offset to make sure the dashes look good on rounded corners
+ */
+
+/**
+ * Dashed rectangle. The dash array and offset are chosen to make sure dashes
+ * look good on rounded corners and have similar metrics to the other dash
+ * preview shapes.
+ */
+const PreviewDashStartAndEnd = () => {
+	return (
+		<svg
+			viewBox="0 0 32 32"
+			xmlns="http://www.w3.org/2000/svg"
+			fill="none"
+			stroke="currentColor"
+			strokeDasharray="3.7677"
+			strokeDashoffset="3.2"
+			strokeWidth="1"
+		>
+			<path d="M29.5,0.5 h-27 a2,2 0 0 0 -2,2 v27 a2,2 0 0 0 2,2 h27 a2,2 0 0 0 2,-2 v-27 a2,2 0 0 0 -2,-2" />
+		</svg>
+	);
+};
+
+/**
+ * Dashed top, left, and bottom sides, with rounded corners. The dash array and
+ * offset are chosen to make sure that multiple days in a row show a seamless
+ * dashed border, and the dashes look good on rounded corners.
+ */
+const PreviewDashStart = () => {
+	return (
+		<svg
+			viewBox="0 0 32 32"
+			xmlns="http://www.w3.org/2000/svg"
+			fill="none"
+			stroke="currentColor"
+			strokeDasharray="3.84516"
+			strokeDashoffset="1.9226"
+			strokeWidth="1"
+		>
+			<path d="M32,0.5 h-29.5 a2,2 0 0 0 -2,2 v27 a2,2 0 0 0 2,2 h30" />
+		</svg>
+	);
+};
+/**
+ * Dashed top and bottom sides. The dash array and offset are chosen
+ * to make sure that multiple days in a row show a seamless dashed border.
+ */
+const PreviewDashMiddle = () => {
+	return (
+		<svg
+			viewBox="0 0 32 32"
+			xmlns="http://www.w3.org/2000/svg"
+			fill="none"
+			stroke="currentColor"
+			strokeDasharray="3.9 4"
+			strokeDashoffset="2"
+			strokeWidth="1"
+		>
+			<line x1="0" y1="0.5" x2="100" y2="0.5" />
+			<line x1="0" y1="31.5" x2="100" y2="31.5" />
+		</svg>
+	);
+};
+/**
+ * Dashed top, right, and bottom sides, with rounded corners. The dash array and
+ * offset are chosen to make sure that multiple days in a row show a seamless
+ * dashed border, and the dashes look good on rounded corners.
+ */
+const PreviewDashEnd = () => {
+	return (
+		<svg
+			viewBox="0 0 32 32"
+			xmlns="http://www.w3.org/2000/svg"
+			fill="none"
+			stroke="currentColor"
+			strokeDasharray="3.84516"
+			strokeDashoffset="1.9226"
+			strokeWidth="1"
+		>
+			<path d="M0,0.5 h29.5 a2,2 0 0 1 2,2 v27 a2,2 0 0 1 -2,2 h-29.5" />
+		</svg>
+	);
+};
+
+/**
+ * Render a grid cell for a specific day in the calendar.
+ *
+ * Handles interaction and focus for the day.
+ * @see https://daypicker.dev/guides/custom-components
+ */
+export function Day(
+	props: {
+		/** The day to render. */
+		day: CalendarDay;
+		/** The modifiers to apply to the day. */
+		modifiers: Modifiers;
+	} & React.HTMLAttributes< HTMLDivElement >
+) {
+	const { day, modifiers, children, ...tdProps } = props;
+
+	let PreviewDash;
+	if ( modifiers.preview_start && modifiers.preview_end ) {
+		PreviewDash = PreviewDashStartAndEnd;
+	} else if ( modifiers.preview_start ) {
+		PreviewDash = PreviewDashStart;
+	} else if ( modifiers.preview_end ) {
+		PreviewDash = PreviewDashEnd;
+	} else if ( modifiers.preview ) {
+		PreviewDash = PreviewDashMiddle;
+	}
+
+	return (
+		<td { ...tdProps }>
+			{ PreviewDash && <PreviewDash /> }
+			{ children }
+		</td>
+	);
+}

package/src/calendar/utils/misc.ts

@@ -0,0 +1,3 @@
+export function clampNumberOfMonths( numberOfMonths: number ) {
+	return Math.min( 3, Math.max( 1, numberOfMonths ) );
+}

package/src/calendar/utils/use-localization-props.ts

@@ -0,0 +1,169 @@
+/**
+ * WordPress dependencies
+ */
+import { __, sprintf } from '@wordpress/i18n';
+import { useMemo } from '@wordpress/element';
+/**
+ * Internal dependencies
+ */
+import type { Modifiers, BaseProps } from '../types';
+
+function isLocaleRTL( localeCode: string ) {
+	const localeObj = new Intl.Locale( localeCode );
+	if ( 'getTextInfo' in localeObj ) {
+		// @ts-expect-error - getTextInfo is not typed yet
+		// see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/getTextInfo
+		return localeObj.getTextInfo().direction === 'rtl';
+	}
+	return [
+		'ar', // Arabic
+		'he', // Hebrew
+		'fa', // Persian (Farsi)
+		'ur', // Urdu
+		'ps', // Pashto
+		'syr', // Syriac
+		'dv', // Divehi
+		'ku', // Kurdish (Sorani)
+		'yi', // Yiddish
+	].includes( localeObj.language );
+}
+
+/**
+ * Returns localization props for the calendar components.
+ *
+ * Notes:
+ * - the following props should be intended as defaults, and should
+ *   be overridden by consumer props if listed as public props.
+ * - It is possible for the translated strings to use a different locale
+ *   than the formatted dates and the computed `dir`. This is because the
+ *   translation function doesn't expose the locale used for the translated
+ *   strings, meaning that the dates are formatted using the `locale` prop.
+ *   For a correct localized experience, consumers should make sure that
+ *   translation context and `locale` prop are consistent.
+ * @param props
+ * @param props.locale
+ * @param props.timeZone
+ * @param props.mode
+ */
+export const useLocalizationProps = ( {
+	locale,
+	timeZone,
+	mode,
+}: {
+	locale: NonNullable< BaseProps[ 'locale' ] >;
+	timeZone: BaseProps[ 'timeZone' ];
+	mode: 'single' | 'range';
+} ) => {
+	return useMemo( () => {
+		// ie. April 2025
+		const monthNameFormatter = new Intl.DateTimeFormat( locale.code, {
+			year: 'numeric',
+			month: 'long',
+			timeZone,
+		} );
+		// ie. M, T, W, T, F, S, S
+		const weekdayNarrowFormatter = new Intl.DateTimeFormat( locale.code, {
+			weekday: 'narrow',
+			timeZone,
+		} );
+		// ie. Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday
+		const weekdayLongFormatter = new Intl.DateTimeFormat( locale.code, {
+			weekday: 'long',
+			timeZone,
+		} );
+		// ie. Monday, April 29, 2025
+		const fullDateFormatter = new Intl.DateTimeFormat( locale.code, {
+			weekday: 'long',
+			year: 'numeric',
+			month: 'long',
+			day: 'numeric',
+			timeZone,
+		} );
+
+		// Note: the following props should be intended as defaults, and should
+		// be overridden by consumer props if listed as public props.
+		return {
+			'aria-label':
+				mode === 'single'
+					? __( 'Date calendar' )
+					: __( 'Date range calendar' ),
+			labels: {
+				/**
+				 * The label for the month grid.
+				 * @param date
+				 */
+				labelGrid: ( date: Date ) => monthNameFormatter.format( date ),
+				/**
+				 * The label for the gridcell, when the calendar is not interactive.
+				 * @param date
+				 * @param modifiers
+				 */
+				labelGridcell: (
+					date: Date,
+					/** The modifiers for the day. */
+					modifiers?: Modifiers
+				) => {
+					const formattedDate = fullDateFormatter.format( date );
+					let label = formattedDate;
+					if ( modifiers?.today ) {
+						label = sprintf(
+							// translators: %s is the full date (e.g. "Monday, April 29, 2025")
+							__( 'Today, %s' ),
+							formattedDate
+						);
+					}
+					return label;
+				},
+				/** The label for the "next month" button. */
+				labelNext: () => __( 'Go to the Next Month' ),
+				/** The label for the "previous month" button. */
+				labelPrevious: () => __( 'Go to the Previous Month' ),
+				/**
+				 * The label for the day button.
+				 * @param date
+				 * @param modifiers
+				 */
+				labelDayButton: (
+					date: Date,
+					/** The modifiers for the day. */
+					modifiers?: Modifiers
+				) => {
+					const formattedDate = fullDateFormatter.format( date );
+					let label = formattedDate;
+					if ( modifiers?.today ) {
+						label = sprintf(
+							// translators: %s is the full date (e.g. "Monday, April 29, 2025")
+							__( 'Today, %s' ),
+							formattedDate
+						);
+					}
+					if ( modifiers?.selected ) {
+						label = sprintf(
+							// translators: %s is the full date (e.g. "Monday, April 29, 2025")
+							__( '%s, selected' ),
+							formattedDate
+						);
+					}
+					return label;
+				},
+				/**
+				 * The label for the weekday.
+				 * @param date
+				 */
+				labelWeekday: ( date: Date ) =>
+					weekdayLongFormatter.format( date ),
+			},
+			locale,
+			dir: isLocaleRTL( locale.code ) ? 'rtl' : 'ltr',
+			formatters: {
+				formatWeekdayName: ( date: Date ) => {
+					return weekdayNarrowFormatter.format( date );
+				},
+				formatCaption: ( date: Date ) => {
+					return monthNameFormatter.format( date );
+				},
+			},
+			timeZone,
+		} as const;
+	}, [ locale, timeZone, mode ] );
+};