@wordpress/components 29.12.0 → 30.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/components",
-	"version": "29.12.0",
+	"version": "30.0.0",
 	"description": "UI components for WordPress.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -40,27 +40,27 @@
 		"@emotion/serialize": "^1.0.2",
 		"@emotion/styled": "^11.6.0",
 		"@emotion/utils": "^1.0.0",
-		"@floating-ui/react-dom": "^2.0.8",
+		"@floating-ui/react-dom": "2.0.8",
 		"@types/gradient-parser": "0.1.3",
 		"@types/highlight-words-core": "1.2.1",
 		"@use-gesture/react": "^10.3.1",
-		"@wordpress/a11y": "^4.26.0",
-		"@wordpress/compose": "^7.26.0",
-		"@wordpress/date": "^5.26.0",
-		"@wordpress/deprecated": "^4.26.0",
-		"@wordpress/dom": "^4.26.0",
-		"@wordpress/element": "^6.26.0",
-		"@wordpress/escape-html": "^3.26.0",
-		"@wordpress/hooks": "^4.26.0",
-		"@wordpress/html-entities": "^4.26.0",
-		"@wordpress/i18n": "^5.26.0",
-		"@wordpress/icons": "^10.26.0",
-		"@wordpress/is-shallow-equal": "^5.26.0",
-		"@wordpress/keycodes": "^4.26.0",
-		"@wordpress/primitives": "^4.26.0",
-		"@wordpress/private-apis": "^1.26.0",
-		"@wordpress/rich-text": "^7.26.0",
-		"@wordpress/warning": "^3.26.0",
+		"@wordpress/a11y": "^4.27.0",
+		"@wordpress/compose": "^7.27.0",
+		"@wordpress/date": "^5.27.0",
+		"@wordpress/deprecated": "^4.27.0",
+		"@wordpress/dom": "^4.27.0",
+		"@wordpress/element": "^6.27.0",
+		"@wordpress/escape-html": "^3.27.0",
+		"@wordpress/hooks": "^4.27.0",
+		"@wordpress/html-entities": "^4.27.0",
+		"@wordpress/i18n": "^6.0.0",
+		"@wordpress/icons": "^10.27.0",
+		"@wordpress/is-shallow-equal": "^5.27.0",
+		"@wordpress/keycodes": "^4.27.0",
+		"@wordpress/primitives": "^4.27.0",
+		"@wordpress/private-apis": "^1.27.0",
+		"@wordpress/rich-text": "^7.27.0",
+		"@wordpress/warning": "^3.27.0",
 		"change-case": "^4.1.2",
 		"clsx": "^2.1.1",
 		"colord": "^2.7.0",
@@ -75,6 +75,7 @@
 		"path-to-regexp": "^6.2.1",
 		"re-resizable": "^6.4.0",
 		"react-colorful": "^5.3.1",
+		"react-day-picker": "^9.7.0",
 		"remove-accents": "^0.5.0",
 		"uuid": "^9.0.1"
 	},
@@ -85,5 +86,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "35e26942820d8237771af0c58e45b4303f0497f1"
+	"gitHead": "abe06a6f2aef8d03c30ea9d5b3e133f041e523b1"
 }

package/src/autocomplete/index.tsx

@@ -126,6 +126,10 @@ export function useAutocomplete( {
 		// Reset autocomplete state after insertion rather than before
 		// so insertion events don't cause the completion menu to redisplay.
 		reset();
+
+		// Make sure that the content remains focused after making a selection
+		// and that the text cursor position is not lost.
+		contentRef.current?.focus();
 	}
 
 	function reset() {

package/src/box-control/input-control.tsx

@@ -178,14 +178,23 @@ export default function BoxInputControl( {
 	const presetIndex = hasPresetValue
 		? getPresetIndexFromValue( mergedValue, presetKey, presets )
 		: undefined;
-	const marks = hasPresets
-		? [ { value: 0, label: '', tooltip: __( 'None' ) } ].concat(
-				presets.map( ( preset, index ) => ( {
+	const marks: Array< {
+		value: number;
+		label: string;
+		tooltip: string;
+	} > = hasPresets
+		? [
+				{
+					value: 0,
+					label: '',
+					tooltip: __( 'None' ),
+				},
+				...presets.map( ( preset, index ) => ( {
 					value: index + 1,
 					label: '',
 					tooltip: preset.name ?? preset.slug,
-				} ) )
-		  )
+				} ) ),
+		  ]
 		: [];
 
 	return (

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

@@ -0,0 +1,261 @@
+# `DateCalendar`
+
+🔒 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.
+
+`DateCalendar` is a React component that provides a customizable calendar interface for **single date** 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 { DateCalendar } from '@wordpress/components';
+
+function MyComponent() {
+	const [ selected, setSelected ] = useState< Date >( new Date() );
+
+	return <DateCalendar 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: `Date | undefined | null`
+-   Required: No
+
+The selected date.
+
+### `onSelect`
+
+-   Type: `(selected: Date | undefined, triggerDate: Date, modifiers: Modifiers, e: React.MouseEvent | React.KeyboardEvent) => void`
+-   Required: No
+
+Event handler when a day is selected.
+
+### `defaultSelected`
+
+-   Type: `Date`
+-   Required: No
+
+The default selected date (for uncontrolled usage).
+
+### `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 { 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 }
+		/>
+	);
+}
+```
+
+### `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-calendar/index.tsx

@@ -0,0 +1,69 @@
+/**
+ * External dependencies
+ */
+import { DayPicker } from 'react-day-picker';
+import { enUS } from 'react-day-picker/locale';
+/**
+ * WordPress dependencies
+ */
+import { useCallback } from '@wordpress/element';
+/**
+ * Internal dependencies
+ */
+import { COMMON_PROPS } from '../utils/constants';
+import { clampNumberOfMonths } from '../utils/misc';
+import { useControlledValue } from '../../utils/hooks';
+import { useLocalizationProps } from '../utils/use-localization-props';
+import type { DateCalendarProps, OnSelectHandler } from '../types';
+
+/**
+ * `DateCalendar` is a React component that provides a customizable calendar
+ * interface for **single date** 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 DateCalendar = ( {
+	defaultSelected,
+	selected: selectedProp,
+	onSelect,
+	numberOfMonths = 1,
+	locale = enUS,
+	timeZone,
+	...props
+}: DateCalendarProps ) => {
+	const localizationProps = useLocalizationProps( {
+		locale,
+		timeZone,
+		mode: 'single',
+	} );
+
+	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,
+		}
+	);
+
+	return (
+		<DayPicker
+			{ ...COMMON_PROPS }
+			{ ...localizationProps }
+			{ ...props }
+			mode="single"
+			numberOfMonths={ clampNumberOfMonths( numberOfMonths ) }
+			selected={ selected ?? undefined }
+			onSelect={ setSelected }
+		/>
+	);
+};