@wordpress/date 5.29.1-next.f34ab90e9.0 → 5.30.1-next.836ecdcae.0

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 5.30.0 (2025-09-03)
+
+### Enhancements
+
+-   Improved TypeScript definitions ([67573](https://github.com/WordPress/gutenberg/pull/67573))
+
 ## 5.29.0 (2025-08-20)
 
 ## 5.28.0 (2025-08-07)

package/README.md

@@ -28,8 +28,8 @@ _Related_
 _Parameters_
 
 -   _dateFormat_ `string`: PHP-style formatting string. See [php.net/date](https://www.php.net/manual/en/function.date.php).
--   _dateValue_ `Moment | Date | string | undefined`: Date object or string, parsable by moment.js.
--   _timezone_ `string | number | undefined`: Timezone to output result in or a UTC offset. Defaults to timezone from site.
+-   _dateValue_ `Moment | Date | string | number`: Date object or string, parsable by moment.js.
+-   _timezone_ `string`: Timezone to output result in or a UTC offset. Defaults to timezone from site.
 
 _Returns_
 
@@ -49,12 +49,12 @@ _Related_
 _Parameters_
 
 -   _dateFormat_ `string`: PHP-style formatting string. See [php.net/date](https://www.php.net/manual/en/function.date.php).
--   _dateValue_ `Moment | Date | string | undefined`: Date object or string, parsable by moment.js.
--   _timezone_ `string | number | boolean | undefined=`: Timezone to output result in or a UTC offset. Defaults to timezone from site. Notice: `boolean` is effectively deprecated, but still supported for backward compatibility reasons.
+-   _dateValue_ `Moment | Date | string | number`: Date object or string, parsable by moment.js.
+-   _timezone_ `string | number | boolean`: Timezone to output result in or a UTC offset. Defaults to timezone from site. Notice: `boolean` is effectively deprecated, but still supported for backward compatibility reasons.
 
 _Returns_
 
--   `string`: Formatted date.
+-   Formatted date.
 
 ### format
 
@@ -63,11 +63,11 @@ Formats a date. Does not alter the date's timezone.
 _Parameters_
 
 -   _dateFormat_ `string`: PHP-style formatting string. See [php.net/date](https://www.php.net/manual/en/function.date.php).
--   _dateValue_ `Moment | Date | string | undefined`: Date object or string, parsable by moment.js.
+-   _dateValue_ `Moment | Date | string | number`: Date object or string, parsable by moment.js.
 
 _Returns_
 
--   `string`: Formatted date.
+-   Formatted date.
 
 ### getDate
 
@@ -75,11 +75,11 @@ Create and return a JavaScript Date Object from a date string in the WP timezone
 
 _Parameters_
 
--   _dateString_ `?string`: Date formatted in the WP timezone.
+-   _dateString_ `string | null`: Date formatted in the WP timezone.
 
 _Returns_
 
--   `Date`: Date
+-   Date
 
 ### getSettings
 
@@ -96,11 +96,11 @@ Formats a date (like `date()` in PHP), in the UTC timezone.
 _Parameters_
 
 -   _dateFormat_ `string`: PHP-style formatting string. See [php.net/date](https://www.php.net/manual/en/function.date.php).
--   _dateValue_ `Moment | Date | string | undefined`: Date object or string, parsable by moment.js.
+-   _dateValue_ `Moment | Date | string | number`: Date object or string, parsable by moment.js.
 
 _Returns_
 
--   `string`: Formatted date in English.
+-   Formatted date in English.
 
 ### gmdateI18n
 
@@ -109,11 +109,11 @@ Formats a date (like `wp_date()` in PHP), translating it into site's locale and
 _Parameters_
 
 -   _dateFormat_ `string`: PHP-style formatting string. See [php.net/date](https://www.php.net/manual/en/function.date.php).
--   _dateValue_ `Moment | Date | string | undefined`: Date object or string, parsable by moment.js.
+-   _dateValue_ `Moment | Date | string | number`: Date object or string, parsable by moment.js.
 
 _Returns_
 
--   `string`: Formatted date.
+-   Formatted date.
 
 ### humanTimeDiff
 
@@ -121,12 +121,12 @@ Returns a human-readable time difference between two dates, like human_time_diff
 
 _Parameters_
 
--   _from_ `Moment | Date | string`: From date, in the WP timezone.
--   _to_ `Moment | Date | string | undefined`: To date, formatted in the WP timezone.
+-   _from_ `Moment | Date | string | number`: From date, in the WP timezone.
+-   _to_ `Moment | Date | string | number`: To date, formatted in the WP timezone.
 
 _Returns_
 
--   `string`: Human-readable time difference.
+-   Human-readable time difference.
 
 ### isInTheFuture
 
@@ -134,11 +134,11 @@ Check whether a date is considered in the future according to the WordPress sett
 
 _Parameters_
 
--   _dateValue_ `string`: Date String or Date object in the Defined WP Timezone.
+-   _dateValue_ `Date | string | number`: Date String or Date object in the Defined WP Timezone.
 
 _Returns_
 
--   `boolean`: Is in the future.
+-   Is in the future.
 
 ### setSettings
 

package/build/index.js

@@ -4,6 +4,19 @@ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefau
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
+var _exportNames = {
+  setSettings: true,
+  getSettings: true,
+  __experimentalGetSettings: true,
+  format: true,
+  date: true,
+  gmdate: true,
+  dateI18n: true,
+  gmdateI18n: true,
+  isInTheFuture: true,
+  getDate: true,
+  humanTimeDiff: true
+};
 exports.__experimentalGetSettings = __experimentalGetSettings;
 exports.date = date;
 exports.dateI18n = dateI18n;
@@ -19,6 +32,18 @@ var _moment = _interopRequireDefault(require("moment"));
 require("moment-timezone/moment-timezone");
 require("moment-timezone/moment-timezone-utils");
 var _deprecated = _interopRequireDefault(require("@wordpress/deprecated"));
+var _types = require("./types");
+Object.keys(_types).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (Object.prototype.hasOwnProperty.call(_exportNames, key)) return;
+  if (key in exports && exports[key] === _types[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _types[key];
+    }
+  });
+});
 /**
  * External dependencies
  */
@@ -27,52 +52,8 @@ var _deprecated = _interopRequireDefault(require("@wordpress/deprecated"));
  * WordPress dependencies
  */
 
-/** @typedef {import('moment').Moment} Moment */
-/** @typedef {import('moment').LocaleSpecification} MomentLocaleSpecification */
-
-/**
- * @typedef MeridiemConfig
- * @property {string} am Lowercase AM.
- * @property {string} AM Uppercase AM.
- * @property {string} pm Lowercase PM.
- * @property {string} PM Uppercase PM.
- */
-
-/**
- * @typedef FormatsConfig
- * @property {string} time                Time format.
- * @property {string} date                Date format.
- * @property {string} datetime            Datetime format.
- * @property {string} datetimeAbbreviated Abbreviated datetime format.
- */
-
 /**
- * @typedef TimezoneConfig
- * @property {string} offset          Offset setting.
- * @property {string} offsetFormatted Offset setting with decimals formatted to minutes.
- * @property {string} string          The timezone as a string (e.g., `'America/Los_Angeles'`).
- * @property {string} abbr            Abbreviation for the timezone.
- */
-
-/* eslint-disable jsdoc/valid-types */
-/**
- * @typedef L10nSettings
- * @property {string}                                     locale        Moment locale.
- * @property {MomentLocaleSpecification['months']}        months        Locale months.
- * @property {MomentLocaleSpecification['monthsShort']}   monthsShort   Locale months short.
- * @property {MomentLocaleSpecification['weekdays']}      weekdays      Locale weekdays.
- * @property {MomentLocaleSpecification['weekdaysShort']} weekdaysShort Locale weekdays short.
- * @property {MeridiemConfig}                             meridiem      Meridiem config.
- * @property {MomentLocaleSpecification['relativeTime']}  relative      Relative time config.
- * @property {0|1|2|3|4|5|6}                              startOfWeek   Day that the week starts on.
- */
-/* eslint-enable jsdoc/valid-types */
-
-/**
- * @typedef DateSettings
- * @property {L10nSettings}   l10n     Localization settings.
- * @property {FormatsConfig}  formats  Date/time formats config.
- * @property {TimezoneConfig} timezone Timezone settings.
+ * Internal dependencies
  */
 
 const WP_ZONE = 'WP';
@@ -83,7 +64,6 @@ const VALID_UTC_OFFSET = /^[+-][0-1][0-9](:?[0-9][0-9])?$/;
 
 // Changes made here will likely need to be synced with Core in the file
 // src/wp-includes/script-loader.php in `wp_default_packages_inline_scripts()`.
-/** @type {DateSettings} */
 let settings = {
   l10n: {
     locale: 'en',
@@ -132,7 +112,7 @@ let settings = {
 /**
  * Adds a locale to moment, using the format supplied by `wp_localize_script()`.
  *
- * @param {DateSettings} dateSettings Settings, including locale data.
+ * @param dateSettings Settings, including locale data.
  */
 function setSettings(dateSettings) {
   settings = dateSettings;
@@ -238,31 +218,25 @@ function setupWPTimezone() {
 // Date constants.
 /**
  * Number of seconds in one minute.
- *
- * @type {number}
  */
 const MINUTE_IN_SECONDS = 60;
 /**
  * Number of minutes in one hour.
- *
- * @type {number}
  */
 const HOUR_IN_MINUTES = 60;
 /**
  * Number of seconds in one hour.
- *
- * @type {number}
  */
 const HOUR_IN_SECONDS = 60 * MINUTE_IN_SECONDS;
 
 /**
  * Map of PHP formats to Moment.js formats.
  *
- * These are used internally by {@link wp.date.format}, and are either
+ * These are used internally by {@link format}, and are either
  * a string representing the corresponding Moment.js format code, or a
  * function which returns the formatted string.
  *
- * This should only be used through {@link wp.date.format}, not
+ * This should only be used through {@link format}, not
  * directly.
  */
 const formatMap = {
@@ -275,9 +249,9 @@ const formatMap = {
   /**
    * Gets the ordinal suffix.
    *
-   * @param {Moment} momentDate Moment instance.
+   * @param momentDate Moment instance.
    *
-   * @return {string} Formatted date.
+   * @return Formatted date.
    */
   S(momentDate) {
     // Do - D.
@@ -289,9 +263,9 @@ const formatMap = {
   /**
    * Gets the day of the year (zero-indexed).
    *
-   * @param {Moment} momentDate Moment instance.
+   * @param momentDate Moment instance.
    *
-   * @return {string} Formatted date.
+   * @return Formatted date.
    */
   z(momentDate) {
     // DDD - 1.
@@ -307,9 +281,9 @@ const formatMap = {
   /**
    * Gets the days in the month.
    *
-   * @param {Moment} momentDate Moment instance.
+   * @param momentDate Moment instance.
    *
-   * @return {number} Formatted date.
+   * @return Formatted date.
    */
   t(momentDate) {
     return momentDate.daysInMonth();
@@ -318,9 +292,9 @@ const formatMap = {
   /**
    * Gets whether the current year is a leap year.
    *
-   * @param {Moment} momentDate Moment instance.
+   * @param momentDate Moment instance.
    *
-   * @return {string} Formatted date.
+   * @return Formatted date.
    */
   L(momentDate) {
     return momentDate.isLeapYear() ? '1' : '0';
@@ -334,9 +308,9 @@ const formatMap = {
   /**
    * Gets the current time in Swatch Internet Time (.beats).
    *
-   * @param {Moment} momentDate Moment instance.
+   * @param momentDate Moment instance.
    *
-   * @return {number} Formatted date.
+   * @return Formatted date.
    */
   B(momentDate) {
     const timezoned = (0, _moment.default)(momentDate).utcOffset(60);
@@ -358,9 +332,9 @@ const formatMap = {
   /**
    * Gets whether the timezone is in DST currently.
    *
-   * @param {Moment} momentDate Moment instance.
+   * @param momentDate Moment instance.
    *
-   * @return {string} Formatted date.
+   * @return Formatted date.
    */
   I(momentDate) {
     return momentDate.isDST() ? '1' : '0';
@@ -371,9 +345,9 @@ const formatMap = {
   /**
    * Gets the timezone offset in seconds.
    *
-   * @param {Moment} momentDate Moment instance.
+   * @param momentDate Moment instance.
    *
-   * @return {number} Formatted date.
+   * @return Formatted date.
    */
   Z(momentDate) {
     // Timezone offset in seconds.
@@ -388,9 +362,9 @@ const formatMap = {
   /**
    * Formats the date as RFC2822.
    *
-   * @param {Moment} momentDate Moment instance.
+   * @param momentDate Moment instance.
    *
-   * @return {string} Formatted date.
+   * @return Formatted date.
    */
   r(momentDate) {
     return momentDate.locale('en').format('ddd, DD MMM YYYY HH:mm:ss ZZ');
@@ -401,12 +375,12 @@ const formatMap = {
 /**
  * Formats a date. Does not alter the date's timezone.
  *
- * @param {string}                             dateFormat PHP-style formatting string.
- *                                                        See [php.net/date](https://www.php.net/manual/en/function.date.php).
- * @param {Moment | Date | string | undefined} dateValue  Date object or string,
- *                                                        parsable by moment.js.
+ * @param dateFormat PHP-style formatting string.
+ *                   See [php.net/date](https://www.php.net/manual/en/function.date.php).
+ * @param dateValue  Date object or string,
+ *                   parsable by moment.js.
  *
- * @return {string} Formatted date.
+ * @return Formatted date.
  */
 function format(dateFormat, dateValue = new Date()) {
   let i, char;
@@ -422,7 +396,7 @@ function format(dateFormat, dateValue = new Date()) {
       continue;
     }
     if (char in formatMap) {
-      const formatter = formatMap[(/** @type {keyof formatMap} */char)];
+      const formatter = formatMap[char];
       if (typeof formatter !== 'string') {
         // If the format is a function, call it.
         newFormat.push('[' + formatter(momentDate) + ']');
@@ -442,13 +416,13 @@ function format(dateFormat, dateValue = new Date()) {
 /**
  * Formats a date (like `date()` in PHP).
  *
- * @param {string}                             dateFormat PHP-style formatting string.
- *                                                        See [php.net/date](https://www.php.net/manual/en/function.date.php).
- * @param {Moment | Date | string | undefined} dateValue  Date object or string, parsable
- *                                                        by moment.js.
- * @param {string | number | undefined}        timezone   Timezone to output result in or a
- *                                                        UTC offset. Defaults to timezone from
- *                                                        site.
+ * @param  dateFormat PHP-style formatting string.
+ *                    See [php.net/date](https://www.php.net/manual/en/function.date.php).
+ * @param  dateValue  Date object or string, parsable
+ *                    by moment.js.
+ * @param  timezone   Timezone to output result in or a
+ *                    UTC offset. Defaults to timezone from
+ *                    site.
  *
  * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
  * @see https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC
@@ -463,12 +437,12 @@ function date(dateFormat, dateValue = new Date(), timezone) {
 /**
  * Formats a date (like `date()` in PHP), in the UTC timezone.
  *
- * @param {string}                             dateFormat PHP-style formatting string.
- *                                                        See [php.net/date](https://www.php.net/manual/en/function.date.php).
- * @param {Moment | Date | string | undefined} dateValue  Date object or string,
- *                                                        parsable by moment.js.
+ * @param dateFormat PHP-style formatting string.
+ *                   See [php.net/date](https://www.php.net/manual/en/function.date.php).
+ * @param dateValue  Date object or string,
+ *                   parsable by moment.js.
  *
- * @return {string} Formatted date in English.
+ * @return Formatted date in English.
  */
 function gmdate(dateFormat, dateValue = new Date()) {
   const dateMoment = (0, _moment.default)(dateValue).utc();
@@ -481,20 +455,20 @@ function gmdate(dateFormat, dateValue = new Date()) {
  * Backward Compatibility Notice: if `timezone` is set to `true`, the function
  * behaves like `gmdateI18n`.
  *
- * @param {string}                                 dateFormat PHP-style formatting string.
- *                                                            See [php.net/date](https://www.php.net/manual/en/function.date.php).
- * @param {Moment | Date | string | undefined}     dateValue  Date object or string, parsable by
- *                                                            moment.js.
- * @param {string | number | boolean | undefined=} timezone   Timezone to output result in or a
- *                                                            UTC offset. Defaults to timezone from
- *                                                            site. Notice: `boolean` is effectively
- *                                                            deprecated, but still supported for
- *                                                            backward compatibility reasons.
+ * @param dateFormat PHP-style formatting string.
+ *                   See [php.net/date](https://www.php.net/manual/en/function.date.php).
+ * @param dateValue  Date object or string, parsable by
+ *                   moment.js.
+ * @param timezone   Timezone to output result in or a
+ *                   UTC offset. Defaults to timezone from
+ *                   site. Notice: `boolean` is effectively
+ *                   deprecated, but still supported for
+ *                   backward compatibility reasons.
  *
  * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
  * @see https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC
  *
- * @return {string} Formatted date.
+ * @return  Formatted date.
  */
 function dateI18n(dateFormat, dateValue = new Date(), timezone) {
   if (true === timezone) {
@@ -512,12 +486,12 @@ function dateI18n(dateFormat, dateValue = new Date(), timezone) {
  * Formats a date (like `wp_date()` in PHP), translating it into site's locale
  * and using the UTC timezone.
  *
- * @param {string}                             dateFormat PHP-style formatting string.
- *                                                        See [php.net/date](https://www.php.net/manual/en/function.date.php).
- * @param {Moment | Date | string | undefined} dateValue  Date object or string,
- *                                                        parsable by moment.js.
+ * @param dateFormat PHP-style formatting string.
+ *                   See [php.net/date](https://www.php.net/manual/en/function.date.php).
+ * @param dateValue  Date object or string,
+ *                   parsable by moment.js.
  *
- * @return {string} Formatted date.
+ * @return Formatted date.
  */
 function gmdateI18n(dateFormat, dateValue = new Date()) {
   const dateMoment = (0, _moment.default)(dateValue).utc();
@@ -528,9 +502,9 @@ function gmdateI18n(dateFormat, dateValue = new Date()) {
 /**
  * Check whether a date is considered in the future according to the WordPress settings.
  *
- * @param {string} dateValue Date String or Date object in the Defined WP Timezone.
+ * @param dateValue Date String or Date object in the Defined WP Timezone.
  *
- * @return {boolean} Is in the future.
+ * @return Is in the future.
  */
 function isInTheFuture(dateValue) {
   const now = _moment.default.tz(WP_ZONE);
@@ -541,9 +515,9 @@ function isInTheFuture(dateValue) {
 /**
  * Create and return a JavaScript Date Object from a date string in the WP timezone.
  *
- * @param {?string} dateString Date formatted in the WP timezone.
+ * @param dateString Date formatted in the WP timezone.
  *
- * @return {Date} Date
+ * @return  Date
  */
 function getDate(dateString) {
   if (!dateString) {
@@ -555,10 +529,10 @@ function getDate(dateString) {
 /**
  * Returns a human-readable time difference between two dates, like human_time_diff() in PHP.
  *
- * @param {Moment | Date | string}             from From date, in the WP timezone.
- * @param {Moment | Date | string | undefined} to   To date, formatted in the WP timezone.
+ * @param from From date, in the WP timezone.
+ * @param to   To date, formatted in the WP timezone.
  *
- * @return {string} Human-readable time difference.
+ * @return Human-readable time difference.
  */
 function humanTimeDiff(from, to) {
   const fromMoment = _moment.default.tz(from, WP_ZONE);
@@ -569,22 +543,22 @@ function humanTimeDiff(from, to) {
 /**
  * Creates a moment instance using the given timezone or, if none is provided, using global settings.
  *
- * @param {Moment | Date | string | undefined} dateValue Date object or string, parsable
- *                                                       by moment.js.
- * @param {string | number | undefined}        timezone  Timezone to output result in or a
- *                                                       UTC offset. Defaults to timezone from
- *                                                       site.
+ * @param dateValue Date object or string, parsable
+ *                  by moment.js.
+ * @param timezone  Timezone to output result in or a
+ *                  UTC offset. Defaults to timezone from
+ *                  site.
  *
  * @see https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
  * @see https://en.wikipedia.org/wiki/ISO_8601#Time_offsets_from_UTC
  *
- * @return {Moment} a moment instance.
+ * @return A moment instance.
  */
 function buildMoment(dateValue, timezone = '') {
   const dateMoment = (0, _moment.default)(dateValue);
   if (timezone && !isUTCOffset(timezone)) {
     // The ! isUTCOffset() check guarantees that timezone is a string.
-    return dateMoment.tz(/** @type {string} */timezone);
+    return dateMoment.tz(timezone);
   }
   if (timezone && isUTCOffset(timezone)) {
     return dateMoment.utcOffset(timezone);
@@ -598,9 +572,9 @@ function buildMoment(dateValue, timezone = '') {
 /**
  * Returns whether a certain UTC offset is valid or not.
  *
- * @param {number|string} offset a UTC offset.
+ * @param offset a UTC offset.
  *
- * @return {boolean} whether a certain UTC offset is valid or not.
+ * @return  whether a certain UTC offset is valid or not.
  */
 function isUTCOffset(offset) {
   if ('number' === typeof offset) {