@wordpress/components 29.13.1-next.719a03cbe.0 → 30.1.0

package/build-types/validated-form-controls/components/stories/select-control.story.d.ts

@@ -0,0 +1,12 @@
+/**
+ * External dependencies
+ */
+import type { StoryObj, Meta } from '@storybook/react';
+/**
+ * Internal dependencies
+ */
+import { ValidatedSelectControl } from '../select-control';
+declare const meta: Meta<typeof ValidatedSelectControl>;
+export default meta;
+export declare const Default: StoryObj<typeof ValidatedSelectControl>;
+//# sourceMappingURL=select-control.story.d.ts.map

package/build-types/validated-form-controls/components/stories/select-control.story.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-control.story.d.ts","sourceRoot":"","sources":["../../../../src/validated-form-controls/components/stories/select-control.story.tsx"],"names":[],"mappings":"AAKA;;GAEG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;GAEG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAG3D,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,sBAAsB,CAS9C,CAAC;AACF,eAAe,IAAI,CAAC;AAEpB,eAAO,MAAM,OAAO,EAAE,QAAQ,CAAE,OAAO,sBAAsB,CAe5D,CAAC"}

package/build-types/validated-form-controls/components/stories/story-utils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * WordPress dependencies
+ */
+/**
+ * External dependencies
+ */
+import type { Meta } from '@storybook/react';
+export declare const formDecorator: Meta['decorators'];
+//# sourceMappingURL=story-utils.d.ts.map

package/build-types/validated-form-controls/components/stories/story-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"story-utils.d.ts","sourceRoot":"","sources":["../../../../src/validated-form-controls/components/stories/story-utils.tsx"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAO7C,eAAO,MAAM,aAAa,EAAE,IAAI,CAAE,YAAY,CA+B7C,CAAC"}

package/build-types/validated-form-controls/components/stories/text-control.story.d.ts

@@ -0,0 +1,9 @@
+/**
+ * External dependencies
+ */
+import type { StoryObj, Meta } from '@storybook/react';
+import { ValidatedTextControl } from '../text-control';
+declare const meta: Meta<typeof ValidatedTextControl>;
+export default meta;
+export declare const Default: StoryObj<typeof ValidatedTextControl>;
+//# sourceMappingURL=text-control.story.d.ts.map

package/build-types/validated-form-controls/components/stories/text-control.story.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-control.story.d.ts","sourceRoot":"","sources":["../../../../src/validated-form-controls/components/stories/text-control.story.tsx"],"names":[],"mappings":"AAKA;;GAEG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAMvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAEvD,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,oBAAoB,CAS5C,CAAC;AACF,eAAe,IAAI,CAAC;AAEpB,eAAO,MAAM,OAAO,EAAE,QAAQ,CAAE,OAAO,oBAAoB,CAe1D,CAAC"}

package/build-types/validated-form-controls/components/stories/textarea-control.story.d.ts

@@ -0,0 +1,9 @@
+/**
+ * External dependencies
+ */
+import type { StoryObj, Meta } from '@storybook/react';
+import { ValidatedTextareaControl } from '../textarea-control';
+declare const meta: Meta<typeof ValidatedTextareaControl>;
+export default meta;
+export declare const Default: StoryObj<typeof ValidatedTextareaControl>;
+//# sourceMappingURL=textarea-control.story.d.ts.map

package/build-types/validated-form-controls/components/stories/textarea-control.story.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"textarea-control.story.d.ts","sourceRoot":"","sources":["../../../../src/validated-form-controls/components/stories/textarea-control.story.tsx"],"names":[],"mappings":"AAKA;;GAEG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAKvD,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAC;AAE/D,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,wBAAwB,CAOhD,CAAC;AACF,eAAe,IAAI,CAAC;AAEpB,eAAO,MAAM,OAAO,EAAE,QAAQ,CAAE,OAAO,wBAAwB,CAe9D,CAAC"}

package/build-types/validated-form-controls/components/stories/toggle-control.story.d.ts

@@ -0,0 +1,9 @@
+/**
+ * External dependencies
+ */
+import type { StoryObj, Meta } from '@storybook/react';
+import { ValidatedToggleControl } from '../toggle-control';
+declare const meta: Meta<typeof ValidatedToggleControl>;
+export default meta;
+export declare const Default: StoryObj<typeof ValidatedToggleControl>;
+//# sourceMappingURL=toggle-control.story.d.ts.map

package/build-types/validated-form-controls/components/stories/toggle-control.story.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toggle-control.story.d.ts","sourceRoot":"","sources":["../../../../src/validated-form-controls/components/stories/toggle-control.story.tsx"],"names":[],"mappings":"AAKA;;GAEG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAMvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,sBAAsB,CAS9C,CAAC;AACF,eAAe,IAAI,CAAC;AAEpB,eAAO,MAAM,OAAO,EAAE,QAAQ,CAAE,OAAO,sBAAsB,CAe5D,CAAC"}

package/build-types/validated-form-controls/components/stories/toggle-group-control.story.d.ts

@@ -0,0 +1,9 @@
+/**
+ * External dependencies
+ */
+import type { StoryObj, Meta } from '@storybook/react';
+import { ValidatedToggleGroupControl } from '../toggle-group-control';
+declare const meta: Meta<typeof ValidatedToggleGroupControl>;
+export default meta;
+export declare const Default: StoryObj<typeof ValidatedToggleGroupControl>;
+//# sourceMappingURL=toggle-group-control.story.d.ts.map

package/build-types/validated-form-controls/components/stories/toggle-group-control.story.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toggle-group-control.story.d.ts","sourceRoot":"","sources":["../../../../src/validated-form-controls/components/stories/toggle-group-control.story.tsx"],"names":[],"mappings":"AAKA;;GAEG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAMvD,OAAO,EAAE,2BAA2B,EAAE,MAAM,yBAAyB,CAAC;AAGtE,QAAA,MAAM,IAAI,EAAE,IAAI,CAAE,OAAO,2BAA2B,CASnD,CAAC;AACF,eAAe,IAAI,CAAC;AAEpB,eAAO,MAAM,OAAO,EAAE,QAAQ,CAAE,OAAO,2BAA2B,CAoBjE,CAAC"}

package/build-types/validated-form-controls/components/text-control.d.ts

@@ -0,0 +1,8 @@
+import type { ValidatedControlProps } from './types';
+export declare const ValidatedTextControl: import("react").ForwardRefExoticComponent<Omit<Omit<Pick<import("../../base-control/types").BaseControlProps, "help" | "label" | "className" | "hideLabelFromVision" | "__nextHasNoMarginBottom"> & {
+    onChange: (value: string) => void;
+    value: string | number;
+    type?: "date" | "datetime-local" | "email" | "number" | "password" | "tel" | "text" | "time" | "search" | "url";
+    __next40pxDefaultSize?: boolean;
+} & Omit<Omit<import("react").DetailedHTMLProps<import("react").InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref">, "help" | "label" | "className" | "type" | "children" | "onChange" | "value" | "as" | "__next40pxDefaultSize" | "hideLabelFromVision" | "__nextHasNoMarginBottom"> & import("react").RefAttributes<HTMLInputElement>, "__next40pxDefaultSize" | "__nextHasNoMarginBottom"> & ValidatedControlProps<string | number>, "ref"> & import("react").RefAttributes<HTMLInputElement>>;
+//# sourceMappingURL=text-control.d.ts.map

package/build-types/validated-form-controls/components/text-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-control.d.ts","sourceRoot":"","sources":["../../../src/validated-form-controls/components/text-control.tsx"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AA+CrD,eAAO,MAAM,oBAAoB;;;;;+eAEhC,CAAC"}

package/build-types/validated-form-controls/components/textarea-control.d.ts

@@ -0,0 +1,7 @@
+import type { ValidatedControlProps } from './types';
+export declare const ValidatedTextareaControl: import("react").ForwardRefExoticComponent<Omit<Omit<Pick<import("../../base-control/types").BaseControlProps, "help" | "label" | "hideLabelFromVision" | "__nextHasNoMarginBottom"> & {
+    onChange: (value: string) => void;
+    value: string;
+    rows?: import("react").TextareaHTMLAttributes<HTMLTextAreaElement>["rows"];
+} & Omit<Omit<import("react").DetailedHTMLProps<import("react").TextareaHTMLAttributes<HTMLTextAreaElement>, HTMLTextAreaElement>, "ref">, "help" | "label" | "children" | "onChange" | "value" | "rows" | "as" | "hideLabelFromVision" | "__nextHasNoMarginBottom"> & import("react").RefAttributes<HTMLTextAreaElement>, "__nextHasNoMarginBottom"> & ValidatedControlProps<string>, "ref"> & import("react").RefAttributes<HTMLTextAreaElement>>;
+//# sourceMappingURL=textarea-control.d.ts.map

package/build-types/validated-form-controls/components/textarea-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"textarea-control.d.ts","sourceRoot":"","sources":["../../../src/validated-form-controls/components/textarea-control.tsx"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AA8CrD,eAAO,MAAM,wBAAwB;;;;mbAEpC,CAAC"}

package/build-types/validated-form-controls/components/toggle-control.d.ts

@@ -0,0 +1,7 @@
+import type { ValidatedControlProps } from './types';
+export declare const ValidatedToggleControl: import("react").ForwardRefExoticComponent<Omit<Omit<Pick<import("../../form-toggle/types").FormToggleProps, "disabled" | "checked"> & Pick<import("../../base-control/types").BaseControlProps, "className" | "__nextHasNoMarginBottom"> & {
+    help?: import("react").ReactNode | ((checked: boolean) => import("react").ReactNode);
+    label: import("react").ReactNode;
+    onChange: (value: boolean) => void;
+} & Omit<Omit<import("react").DetailedHTMLProps<import("react").InputHTMLAttributes<HTMLInputElement>, HTMLInputElement>, "ref">, "help" | "disabled" | "label" | "className" | "children" | "onChange" | "checked" | "as" | "__nextHasNoMarginBottom"> & import("react").RefAttributes<HTMLInputElement>, "__nextHasNoMarginBottom"> & ValidatedControlProps<boolean | undefined>, "ref"> & import("react").RefAttributes<HTMLInputElement>>;
+//# sourceMappingURL=toggle-control.d.ts.map

package/build-types/validated-form-controls/components/toggle-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toggle-control.d.ts","sourceRoot":"","sources":["../../../src/validated-form-controls/components/toggle-control.tsx"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAwDrD,eAAO,MAAM,sBAAsB;;;;6aAElC,CAAC"}

package/build-types/validated-form-controls/components/toggle-group-control.d.ts

@@ -0,0 +1,15 @@
+import type { ValidatedControlProps } from './types';
+export declare const ValidatedToggleGroupControl: import("react").ForwardRefExoticComponent<Omit<Omit<Pick<import("../../base-control/types").BaseControlProps, "help" | "__nextHasNoMarginBottom"> & {
+    label: string;
+    hideLabelFromVision?: boolean;
+    isAdaptiveWidth?: boolean;
+    isBlock?: boolean;
+    isDeselectable?: boolean;
+    onChange?: (value: string | number | undefined) => void;
+    value?: string | number;
+    children: import("react").ReactNode;
+    size?: "default" | "__unstable-large";
+    __next40pxDefaultSize?: boolean;
+    __shouldNotWarnDeprecated36pxSize?: boolean;
+} & import("react").RefAttributes<any> & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "size" | "help" | "label" | "children" | "onChange" | "value" | "as" | keyof import("react").RefAttributes<any> | "isBlock" | "__next40pxDefaultSize" | "__shouldNotWarnDeprecated36pxSize" | "hideLabelFromVision" | "__nextHasNoMarginBottom" | "isAdaptiveWidth" | "isDeselectable">, "__next40pxDefaultSize" | "__nextHasNoMarginBottom"> & ValidatedControlProps<string | number | undefined>, "ref"> & import("react").RefAttributes<HTMLInputElement>>;
+//# sourceMappingURL=toggle-group-control.d.ts.map

package/build-types/validated-form-controls/components/toggle-group-control.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toggle-group-control.d.ts","sourceRoot":"","sources":["../../../src/validated-form-controls/components/toggle-group-control.tsx"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAsErD,eAAO,MAAM,2BAA2B;;;;;;;;;;;;2lBAEvC,CAAC"}

package/build-types/validated-form-controls/components/types.d.ts

@@ -0,0 +1,27 @@
+export type ValidatedControlProps<V> = {
+    /**
+     * Whether the control is required.
+     * @default false
+     */
+    required?: boolean;
+    /**
+     * Label the control as "optional" when _not_ `required`, instead of the inverse.
+     * @default false
+     */
+    markWhenOptional?: boolean;
+    /**
+     * A function that returns a custom validity message when applicable. This error message will be applied to the
+     * underlying element using the native [`setCustomValidity()` method](https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/setCustomValidity).
+     * This means the custom validator will be run _in addition_ to any other HTML attribute-based validation, and
+     * will be prioritized over any existing validity messages dictated by the HTML attributes.
+     * An empty string or `undefined` return value will clear any existing custom validity message.
+     *
+     * Make sure you don't programatically pass a value (such as an initial value) to the control component
+     * that fails this validator, because the validator will only run for user-initiated changes.
+     *
+     * Always prefer using standard HTML attributes like `required` and `min`/`max` over custom validators
+     * when possible, as they are simpler and have localized error messages built in.
+     */
+    customValidator?: (currentValue: V) => string | void;
+};
+//# sourceMappingURL=types.d.ts.map

package/build-types/validated-form-controls/components/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/validated-form-controls/components/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,qBAAqB,CAAE,CAAC,IAAK;IACxC;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;;;;;;;;;OAYG;IAGH,eAAe,CAAC,EAAE,CAAE,YAAY,EAAE,CAAC,KAAM,MAAM,GAAG,IAAI,CAAC;CACvD,CAAC"}

package/build-types/validated-form-controls/control-with-error.d.ts

@@ -0,0 +1,36 @@
+/**
+ * HTML elements that support the Constraint Validation API.
+ *
+ * Here, we exclude HTMLButtonElement because although it does technically support the API,
+ * normal buttons are actually exempted from any validation.
+ * @see https://developer.mozilla.org/en-US/docs/Learn_web_development/Extensions/Forms/Form_validation
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLButtonElement/willValidate
+ */
+type ValidityTarget = HTMLFieldSetElement | HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement;
+export declare const ControlWithError: import("react").ForwardRefExoticComponent<{
+    /**
+     * Whether the control is required.
+     */
+    required?: boolean;
+    /**
+     * Label the control as "optional" when _not_ `required`, instead of the inverse.
+     */
+    markWhenOptional?: boolean;
+    /**
+     * A function that returns a custom validity message when applicable.
+     *
+     * This message will be applied to the element returned by `getValidityTarget`.
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/setCustomValidity
+     */
+    customValidator?: () => string | void;
+    /**
+     * A function that returns the actual element on which the validity data should be applied.
+     */
+    getValidityTarget: () => ValidityTarget | null | undefined;
+    /**
+     * The control component to apply validation to.
+     */
+    children: import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>>;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export {};
+//# sourceMappingURL=control-with-error.d.ts.map

package/build-types/validated-form-controls/control-with-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-with-error.d.ts","sourceRoot":"","sources":["../../src/validated-form-controls/control-with-error.tsx"],"names":[],"mappings":"AA6CA;;;;;;;GAOG;AACH,KAAK,cAAc,GAChB,mBAAmB,GACnB,gBAAgB,GAChB,iBAAiB,GACjB,mBAAmB,CAAC;AA4IvB,eAAO,MAAM,gBAAgB;IAlI3B;;OAEG;eACQ,OAAO;IAClB;;OAEG;uBACgB,OAAO;IAC1B;;;;;OAKG;sBACe,MAAM,MAAM,GAAG,IAAI;IACrC;;OAEG;uBACgB,MAAM,cAAc,GAAG,IAAI,GAAG,SAAS;IAC1D;;OAEG;;kDA6GoE,CAAC"}

package/build-types/validated-form-controls/index.d.ts

@@ -0,0 +1,3 @@
+export * from './components';
+export * from './control-with-error';
+//# sourceMappingURL=index.d.ts.map

package/build-types/validated-form-controls/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/validated-form-controls/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,sBAAsB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@wordpress/components",
-	"version": "29.13.1-next.719a03cbe.0",
+	"version": "30.1.0",
 	"description": "UI components for WordPress.",
 	"author": "The WordPress Contributors",
 	"license": "GPL-2.0-or-later",
@@ -44,23 +44,23 @@
 		"@types/gradient-parser": "0.1.3",
 		"@types/highlight-words-core": "1.2.1",
 		"@use-gesture/react": "^10.3.1",
-		"@wordpress/a11y": "^4.26.1-next.719a03cbe.0",
-		"@wordpress/compose": "^7.26.1-next.719a03cbe.0",
-		"@wordpress/date": "^5.26.1-next.719a03cbe.0",
-		"@wordpress/deprecated": "^4.26.1-next.719a03cbe.0",
-		"@wordpress/dom": "^4.26.1-next.719a03cbe.0",
-		"@wordpress/element": "^6.26.1-next.719a03cbe.0",
-		"@wordpress/escape-html": "^3.26.1-next.719a03cbe.0",
-		"@wordpress/hooks": "^4.26.1-next.719a03cbe.0",
-		"@wordpress/html-entities": "^4.26.1-next.719a03cbe.0",
-		"@wordpress/i18n": "^6.0.1-next.719a03cbe.0",
-		"@wordpress/icons": "^10.26.2-next.719a03cbe.0",
-		"@wordpress/is-shallow-equal": "^5.26.1-next.719a03cbe.0",
-		"@wordpress/keycodes": "^4.26.1-next.719a03cbe.0",
-		"@wordpress/primitives": "^4.26.1-next.719a03cbe.0",
-		"@wordpress/private-apis": "^1.26.1-next.719a03cbe.0",
-		"@wordpress/rich-text": "^7.26.1-next.719a03cbe.0",
-		"@wordpress/warning": "^3.26.1-next.719a03cbe.0",
+		"@wordpress/a11y": "^4.28.0",
+		"@wordpress/compose": "^7.28.0",
+		"@wordpress/date": "^5.28.0",
+		"@wordpress/deprecated": "^4.28.0",
+		"@wordpress/dom": "^4.28.0",
+		"@wordpress/element": "^6.28.0",
+		"@wordpress/escape-html": "^3.28.0",
+		"@wordpress/hooks": "^4.28.0",
+		"@wordpress/html-entities": "^4.28.0",
+		"@wordpress/i18n": "^6.1.0",
+		"@wordpress/icons": "^10.28.0",
+		"@wordpress/is-shallow-equal": "^5.28.0",
+		"@wordpress/keycodes": "^4.28.0",
+		"@wordpress/primitives": "^4.28.0",
+		"@wordpress/private-apis": "^1.28.0",
+		"@wordpress/rich-text": "^7.28.0",
+		"@wordpress/warning": "^3.28.0",
 		"change-case": "^4.1.2",
 		"clsx": "^2.1.1",
 		"colord": "^2.7.0",
@@ -86,5 +86,5 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"gitHead": "5e146e949c2765411a8310bcc2641a88d036a6d9"
+	"gitHead": "28cc2098f5ee28f89096b638533796538f495f72"
 }

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/calendar/date-calendar/README.md

@@ -1,5 +1,7 @@
 # `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.
@@ -7,7 +9,7 @@ The component is built with accessibility in mind and follows ARIA best practice
 ## Usage example
 
 ```tsx
-import { DateCalendar } from '@automattic/components';
+import { DateCalendar } from '@wordpress/components';
 
 function MyComponent() {
 	const [ selected, setSelected ] = useState< Date >( new Date() );
@@ -22,95 +24,95 @@ These props are shared between both single date and date range calendar modes.
 
 ### `required`
 
-- Type: `boolean`
-- Required: No
-- Default: `false`
+-   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
+-   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
+-   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
+-   Type: `Date`
+-   Required: No
 
 The default selected date (for uncontrolled usage).
 
 ### `defaultMonth`
 
-- Type: `Date`
-- Required: No
-- Default: Current month
+-   Type: `Date`
+-   Required: No
+-   Default: Current month
 
 The initial month to show in the calendar view (uncontrolled).
 
 ### `month`
 
-- Type: `Date`
-- Required: No
+-   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`
+-   Type: `number`
+-   Required: No
+-   Default: `1`
 
 The number of months displayed at once.
 
 ### `startMonth`
 
-- Type: `Date`
-- Required: No
+-   Type: `Date`
+-   Required: No
 
 The earliest month to start the month navigation.
 
 ### `endMonth`
 
-- Type: `Date`
-- Required: No
+-   Type: `Date`
+-   Required: No
 
 The latest month to end the month navigation.
 
 ### `autoFocus`
 
-- Type: `boolean`
-- Required: No
+-   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
+-   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
+-   Type: `boolean`
+-   Required: No
 
 Disable the navigation buttons.
 
 ### `labels`
 
-- Type: `object`
-- Required: No
+-   Type: `object`
+-   Required: No
 
 Use custom labels for internationalization. All labels are optional and have sensible defaults:
 
@@ -130,9 +132,9 @@ Use custom labels for internationalization. All labels are optional and have sen
 
 ### `locale`
 
-- Type: `Locale`
-- Required: No
-- Default: `enUS` from `@date-fns/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.
 
@@ -140,45 +142,51 @@ The locale object used to localize dates. Pass a locale from `@date-fns/locale`
 
 ### `weekStartsOn`
 
-- Type: `0 | 1 | 2 | 3 | 4 | 5 | 6 | undefined`
-- Required: No
-- Default: Based on the `locale` prop
+-   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
+-   Type: `(month: Date) => void`
+-   Required: No
 
 Event fired when the user navigates between months.
 
 ### `timeZone`
 
-- Type: `string`
-- Required: No
+-   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 '@automattic/components';
+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 } />;
+	return (
+		<DateCalendar
+			timeZone={ timeZone }
+			selected={ selected }
+			onSelect={ setSelected }
+		/>
+	);
 }
 ```
 
 ### `role`
 
-- Type: `'application' | 'dialog' | undefined`
-- Required: No
-- Default: `'application'`
+-   Type: `'application' | 'dialog' | undefined`
+-   Required: No
+-   Default: `'application'`
 
 The role attribute to add to the container element.
 
@@ -201,7 +209,10 @@ 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
+const arrayMatcher: Matcher = [
+	new Date( 2019, 1, 2 ),
+	new Date( 2019, 1, 4 ),
+]; // Will match the days in the array
 ```
 
 ### Date After Matcher

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

@@ -3,14 +3,18 @@
  */
 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/use-controlled-value';
+import { useControlledValue } from '../../utils/hooks';
 import { useLocalizationProps } from '../utils/use-localization-props';
-import type { DateCalendarProps } from '../types';
+import type { DateCalendarProps, OnSelectHandler } from '../types';
 
 /**
  * `DateCalendar` is a React component that provides a customizable calendar
@@ -35,11 +39,21 @@ export const DateCalendar = ( {
 		mode: 'single',
 	} );
 
-	const [ selected, setSelected ] = useControlledValue< Date | undefined >( {
-		defaultValue: defaultSelected,
-		value: selectedProp,
-		onChange: onSelect,
-	} );
+	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
@@ -48,7 +62,7 @@ export const DateCalendar = ( {
 			{ ...props }
 			mode="single"
 			numberOfMonths={ clampNumberOfMonths( numberOfMonths ) }
-			selected={ selected }
+			selected={ selected ?? undefined }
 			onSelect={ setSelected }
 		/>
 	);