@wordpress/components 29.12.0 → 30.0.0

package/src/calendar/date-range-calendar/README.md

@@ -0,0 +1,298 @@
+# `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.
+
+## Usage example
+
+```tsx
+import { DateRangeCalendar } from '@wordpress/components';
+
+type DateRange = {
+	from: Date | undefined;
+	to?: Date | undefined;
+};
+
+function MyComponent() {
+	const [ selected, setSelected ] = useState< DateRange >( {
+		from: new Date( date.getFullYear(), date.getMonth(), 1 ),
+		to: new Date(),
+	} );
+
+	return <DateRangeCalendar selected={ selected } onSelect={ setSelected } />;
+}
+```
+
+## Props
+
+These props are shared between both single date and date range calendar modes.
+
+### `required`
+
+-   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
+
+The selected date range. A `DateRange` object has the following shape:
+
+```typescript
+{
+  from: Date | undefined;
+  to?: Date | undefined;
+}
+```
+
+### `onSelect`
+
+-   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
+
+The default selected range (for uncontrolled usage).
+
+### `excludeDisabled`
+
+-   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
+
+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
+
+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
+
+The initial month to show in the calendar view (uncontrolled).
+
+### `month`
+
+-   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`
+
+The number of months displayed at once.
+
+### `startMonth`
+
+-   Type: `Date`
+-   Required: No
+
+The earliest month to start the month navigation.
+
+### `endMonth`
+
+-   Type: `Date`
+-   Required: No
+
+The latest month to end the month navigation.
+
+### `autoFocus`
+
+-   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
+
+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
+
+Disable the navigation buttons.
+
+### `labels`
+
+-   Type: `object`
+-   Required: No
+
+Use custom labels for internationalization. All labels are optional and have sensible defaults:
+
+```typescript
+{
+  labelNav?: () => string; // Navigation toolbar label
+  labelGrid?: (date: Date) => string; // Month grid label (default: "LLLL y")
+  labelGridcell?: (date: Date, modifiers?: Modifiers) => string; // Grid cell label
+  labelNext?: (month: Date | undefined) => string; // Next month button label
+  labelPrevious?: (month: Date | undefined) => string; // Previous month button label
+  labelDayButton?: (date: Date, modifiers?: Modifiers) => string; // Day button label
+  labelWeekday?: (date: Date) => string; // Weekday label
+}
+```
+
+**Important: For a correct localized experience, consumers should make sure the locale used for the translated labels and `locale` prop are consistent.**
+
+### `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.
+
+**Important: For a correct localized experience, consumers should make sure the locale used for the translated labels and `locale` prop are consistent.**
+
+### `weekStartsOn`
+
+-   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
+
+Event fired when the user navigates between months.
+
+### `timeZone`
+
+-   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 '@wordpress/components';
+
+export function WithTimeZone() {
+	const timeZone = 'America/New_York';
+	const [ selected, setSelected ] = useState< Date | undefined >( {
+		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 }
+		/>
+	);
+}
+```
+
+### `role`
+
+-   Type: `'application' | 'dialog' | undefined`
+-   Required: No
+-   Default: `'application'`
+
+The role attribute to add to the container element.
+
+## Matcher Types
+
+The calendar component uses a flexible matching system to determine which days should be disabled or have specific modifiers. Here are the available matcher types:
+
+### Boolean Matcher
+
+```typescript
+const booleanMatcher: Matcher = true; // Will always match the day
+```
+
+### Date Matcher
+
+```typescript
+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
+```
+
+### Date After Matcher
+
+```typescript
+const afterMatcher: DateAfter = { after: new Date( 2019, 1, 2 ) }; // Will match days after the 2nd of February 2019
+```
+
+### Date Before Matcher
+
+```typescript
+const beforeMatcher: DateBefore = { before: new Date( 2019, 1, 2 ) }; // Will match days before the 2nd of February 2019
+```
+
+### Date Interval Matcher
+
+```typescript
+const intervalMatcher: DateInterval = {
+	after: new Date( 2019, 1, 2 ),
+	before: new Date( 2019, 1, 5 ),
+}; // Will match the days between the 2nd and the 5th of February 2019 (exclusive)
+```
+
+### Date Range Matcher
+
+```typescript
+const rangeMatcher: DateRange = {
+	from: new Date( 2019, 1, 2 ),
+	to: new Date( 2019, 1, 5 ),
+}; // Will match the days between the 2nd and the 5th of February 2019 (inclusive)
+```
+
+### Day of Week Matcher
+
+```typescript
+const dayOfWeekMatcher: DayOfWeek = { dayOfWeek: 0 }; // Will match Sundays
+const weekendMatcher: DayOfWeek = { dayOfWeek: [ 0, 6 ] }; // Will match weekends
+```
+
+### Function Matcher
+
+```typescript
+const functionMatcher: Matcher = ( day: Date ) => {
+	return day.getMonth() === 2; // Will match when month is March
+};
+```

package/src/calendar/date-range-calendar/index.tsx

@@ -0,0 +1,215 @@
+/**
+ * External dependencies
+ */
+import { differenceInCalendarDays } from 'date-fns';
+import { DayPicker, rangeContainsModifiers } from 'react-day-picker';
+import { enUS } from 'react-day-picker/locale';
+/**
+ * WordPress dependencies
+ */
+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/hooks';
+import { useLocalizationProps } from '../utils/use-localization-props';
+import type {
+	DateRangeCalendarProps,
+	DateRange,
+	OnSelectHandler,
+} from '../types';
+
+export function usePreviewRange( {
+	selected,
+	hoveredDate,
+	excludeDisabled,
+	min,
+	max,
+	disabled,
+}: Pick<
+	DateRangeCalendarProps,
+	'selected' | 'excludeDisabled' | 'min' | 'max' | 'disabled'
+> & {
+	hoveredDate: Date | undefined;
+} ) {
+	return useMemo( () => {
+		if ( ! hoveredDate || ! selected?.from ) {
+			return;
+		}
+
+		let previewHighlight: DateRange | undefined;
+		let potentialNewRange: { from: Date; to: Date } | undefined;
+
+		// Hovering on a date before the start of the selected range
+		if ( hoveredDate < selected.from ) {
+			previewHighlight = {
+				from: hoveredDate,
+				to: selected.from,
+			};
+
+			potentialNewRange = {
+				from: hoveredDate,
+				to: selected.to ?? selected.from,
+			};
+		} else if (
+			selected.to &&
+			hoveredDate > selected.from &&
+			hoveredDate < selected.to
+		) {
+			// Hovering on a date between the start and end of the selected range
+			previewHighlight = {
+				from: selected.from,
+				to: hoveredDate,
+			};
+
+			potentialNewRange = {
+				from: selected.from,
+				to: hoveredDate,
+			};
+		} else if ( hoveredDate > selected.from ) {
+			// Hovering on a date after the end of the selected range (either
+			// because it's greater than selected.to, or because it's not defined)
+			previewHighlight = {
+				from: selected.to ?? selected.from,
+				to: hoveredDate,
+			};
+
+			potentialNewRange = {
+				from: selected.from,
+				to: hoveredDate,
+			};
+		}
+
+		if (
+			min !== undefined &&
+			min > 0 &&
+			potentialNewRange &&
+			differenceInCalendarDays(
+				potentialNewRange.to,
+				potentialNewRange.from
+			) < min
+		) {
+			previewHighlight = {
+				from: hoveredDate,
+				to: hoveredDate,
+			};
+		}
+
+		if (
+			max !== undefined &&
+			max > 0 &&
+			potentialNewRange &&
+			differenceInCalendarDays(
+				potentialNewRange.to,
+				potentialNewRange.from
+			) > max
+		) {
+			previewHighlight = {
+				from: hoveredDate,
+				to: hoveredDate,
+			};
+		}
+
+		if (
+			excludeDisabled &&
+			disabled &&
+			potentialNewRange &&
+			rangeContainsModifiers( potentialNewRange, disabled )
+		) {
+			previewHighlight = {
+				from: hoveredDate,
+				to: hoveredDate,
+			};
+		}
+
+		return previewHighlight;
+	}, [ selected, hoveredDate, excludeDisabled, min, max, disabled ] );
+}
+
+/**
+ * `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.
+ */
+export const DateRangeCalendar = ( {
+	defaultSelected,
+	selected: selectedProp,
+	onSelect,
+	numberOfMonths = 1,
+	excludeDisabled,
+	min,
+	max,
+	disabled,
+	locale = enUS,
+	timeZone,
+	...props
+}: DateRangeCalendarProps ) => {
+	const localizationProps = useLocalizationProps( {
+		locale,
+		timeZone,
+		mode: 'range',
+	} );
+
+	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
+	);
+
+	// Compute the preview range for hover effect
+	const previewRange = usePreviewRange( {
+		selected,
+		hoveredDate,
+		excludeDisabled,
+		min,
+		max,
+		disabled,
+	} );
+
+	const modifiers = useMemo( () => {
+		return {
+			preview: previewRange,
+			preview_start: previewRange?.from,
+			preview_end: previewRange?.to,
+		};
+	}, [ previewRange ] );
+
+	return (
+		<DayPicker
+			{ ...COMMON_PROPS }
+			{ ...localizationProps }
+			{ ...props }
+			mode="range"
+			numberOfMonths={ clampNumberOfMonths( numberOfMonths ) }
+			disabled={ disabled }
+			excludeDisabled={ excludeDisabled }
+			min={ min }
+			max={ max }
+			selected={ selected ?? undefined }
+			onSelect={ setSelected }
+			onDayMouseEnter={ ( date ) => setHoveredDate( date ) }
+			onDayMouseLeave={ () => setHoveredDate( undefined ) }
+			modifiers={ modifiers }
+			modifiersClassNames={ MODIFIER_CLASSNAMES }
+		/>
+	);
+};

package/src/calendar/index.tsx

@@ -0,0 +1,3 @@
+export { TZDate } from 'react-day-picker';
+export { DateCalendar } from './date-calendar';
+export { DateRangeCalendar } from './date-range-calendar';