History

Ron Rennick c6048b5c49 Add glob, rimraf, and uuid to Syncpack (#46278 ) * add uuid to syncpack * add rimraf to syncpack * add glob to syncpack * Add changefile(s) from automation for the following project(s): @woocommerce/tracks, @woocommerce/product-editor, @woocommerce/onboarding, @woocommerce/number, @woocommerce/notices, @woocommerce/navigation, @woocommerce/internal-js-tests, @woocommerce/integrate-plugin, @woocommerce/expression-evaluation, @woocommerce/explat, @woocommerce/experimental, @woocommerce/eslint-plugin, @woocommerce/dependency-extraction-webpack-plugin, @woocommerce/date, @woocommerce/data, @woocommerce/customer-effort-score, @woocommerce/currency, @woocommerce/csv-export, @woocommerce/components, @woocommerce/block-templates, @woocommerce/ai, @woocommerce/admin-layout, @woocommerce/admin-e2e-tests, woocommerce --------- Co-authored-by: Ron Rennick <ronald.rennick@automattic.com> Co-authored-by: github-actions <github-actions@github.com>		2024-04-11 12:52:49 -03:00
..
changelog	Add glob, rimraf, and uuid to Syncpack (#46278 )	2024-04-11 12:52:49 -03:00
src	Revert " Temporarily commented out failing date package test due to the February 29th issue" (#45239 )	2024-03-01 22:12:09 +08:00
typings	Migrate @woocommerce/date to TS	2022-05-19 14:48:32 +08:00
.eslintrc.js	Add .eslintrc config to each packages	2022-03-29 16:08:07 +08:00
.npmrc	Moved WCA Packages	2022-03-18 14:25:26 -07:00
CHANGELOG.md	Prepare Packages for Release (#33776 )	2022-07-08 14:04:49 +12:00
PREVIOUS_CHANGELOG.md	Update JS packages changelogs (#33412 )	2022-06-16 10:06:31 +12:00
README.md	Moved WCA Packages	2022-03-18 14:25:26 -07:00
babel.config.js	Update dependencies and jest config to pass admin tests for pnpm 7 (#34428 )	2022-08-31 12:06:51 +08:00
composer.json	bump php version in packages/js/*/composer.json (#42020 )	2024-01-04 10:18:34 -04:00
composer.lock	Update changelogger to 3.3.0 to support PR number capturing with merge (#36266 )	2023-01-05 14:42:51 +05:30
jest.config.json	Fix Jest Preset (#42707 )	2023-12-12 09:58:13 -08:00
package.json	Add glob, rimraf, and uuid to Syncpack (#46278 )	2024-04-11 12:52:49 -03:00
tsconfig-cjs.json	Enforce Strict `@types` Dependencies (#37351 )	2023-03-23 18:02:20 -07:00
tsconfig.json	Enforce Strict `@types` Dependencies (#37351 )	2023-03-23 18:02:20 -07:00

README.md

Date

A collection of utilities to display and work with date values.

Installation

Install the module

pnpm install @woocommerce/date --save

This package assumes that your code will run in an ES2015+ environment. If you're using an environment that has limited or no support for ES2015+ such as lower versions of IE then using core-js or @babel/polyfill will add support for these methods. Learn more about it in Babel docs.

Usage

The date package makes use of the global window.wcSettings.timeZone. If a timezone is set, the current and last periods will be converted from your browser's timezone to the store timezone. If none is set, these periods will be based on your browser's timezone.

Functions

appendTimestamp ⇒ string: Adds timestamp to a string date.
getDateValue ⇒ DateValue: Get a DateValue object for a period described by a period, compare value, and start/end dates, for custom dates.
getDateParamsFromQueryMemoized ⇒ Object: Memoized internal logic of getDateParamsFromQuery().
getDateParamsFromQuery ⇒ DateParams: Add default date-related parameters to a query object
getCurrentDatesMemoized ⇒ Object: Memoized internal logic of getCurrentDates().
getCurrentDates ⇒ Object: Get Date Value Objects for a primary and secondary date range
getDateDifferenceInDays ⇒ number: Calculates the date difference between two dates. Used in calculating a matching date for previous period.
getPreviousDate ⇒ Object: Get the previous date for either the previous period of year.

toMoment(format, str) ⇒ Object | null: Convert a string to Moment object
getRangeLabel(after, before) ⇒ string: Given two dates, derive a string representation
getStoreTimeZoneMoment() ⇒ string: Gets the current time in the store time zone if set.
getLastPeriod(period, compare) ⇒ DateValue: Get a DateValue object for a period prior to the current period.
getCurrentPeriod(period, compare) ⇒ DateValue: Get a DateValue object for a curent period. The period begins on the first day of the period, and ends on the current day.
getAllowedIntervalsForQuery(query, defaultDateRange) ⇒ Array: Returns the allowed selectable intervals for a specific query.
getIntervalForQuery(query, defaultDateRange) ⇒ string: Returns the current interval to use.
getChartTypeForQuery(query) ⇒ string: Returns the current chart type to use.
getDateFormatsForInterval(interval, [ticks], [option]) ⇒ string: Returns date formats for the current interval.
getDateFormatsForIntervalD3(interval, [ticks]) ⇒ string: Returns d3 date formats for the current interval. See https://github.com/d3/d3-time-format for chart formats.
getDateFormatsForIntervalPhp(interval, [ticks]) ⇒ string: Returns php date formats for the current interval. See see https://www.php.net/manual/en/datetime.format.php.
loadLocaleData(config): Gutenberg's moment instance is loaded with i18n values, which are PHP date formats, ie 'LLL: "F j, Y g:i a"'. Override those with translations of moment style js formats.
validateDateInputForRange(type, value, [before], [after], format) ⇒ Object: Validate text input supplied for a date range.

Typedefs

DateValue : Object: DateValue Object
DateParams : Object: DateParams Object
validatedDate : Object

appendTimestamp ⇒ `string`

Adds timestamp to a string date.

Kind: global constant Returns: string - - String date with timestamp attached.

Param	Type	Description
date	`moment.Moment`	Date as a moment object.
timeOfDay	`string`	Either `start`, `now` or `end` of the day.

getDateValue ⇒ `DateValue`

Get a DateValue object for a period described by a period, compare value, and start/end dates, for custom dates.

Kind: global constant Returns: DateValue - - DateValue data about the selected period

Param	Type	Description
period	`string`	the chosen period
compare	`string`	`previous_period` or `previous_year`
[after]	`Object`	after date if custom period
[before]	`Object`	before date if custom period

getDateParamsFromQueryMemoized ⇒ `Object`

Memoized internal logic of getDateParamsFromQuery().

Kind: global constant Returns: Object - - date parameters derived from query parameters with added defaults

Param	Type	Description
period	`string`	period value, ie `last_week`
compare	`string`	compare value, ie `previous_year`
after	`string`	date in iso date format, ie `2018-07-03`
before	`string`	date in iso date format, ie `2018-07-03`
defaultDateRange	`string`	the store's default date range

getDateParamsFromQuery ⇒ `DateParams`

Add default date-related parameters to a query object

Kind: global constant Returns: DateParams - - date parameters derived from query parameters with added defaults

Param	Type	Description
query	`Object`	query object
query.period	`string`	period value, ie `last_week`
query.compare	`string`	compare value, ie `previous_year`
query.after	`string`	date in iso date format, ie `2018-07-03`
query.before	`string`	date in iso date format, ie `2018-07-03`
defaultDateRange	`string`	the store's default date range

getCurrentDatesMemoized ⇒ `Object`

Memoized internal logic of getCurrentDates().

Kind: global constant Returns: Object - - Primary and secondary DateValue objects

Param	Type	Description
period	`string`	period value, ie `last_week`
compare	`string`	compare value, ie `previous_year`
primaryStart	`Object`	primary query start DateTime, in Moment instance.
primaryEnd	`Object`	primary query start DateTime, in Moment instance.
secondaryStart	`Object`	primary query start DateTime, in Moment instance.
secondaryEnd	`Object`	primary query start DateTime, in Moment instance.

getCurrentDates ⇒ `Object`

Get Date Value Objects for a primary and secondary date range

Kind: global constant Returns: Object - - Primary and secondary DateValue objects

Param	Type	Description
query	`Object`	query object
query.period	`string`	period value, ie `last_week`
query.compare	`string`	compare value, ie `previous_year`
query.after	`string`	date in iso date format, ie `2018-07-03`
query.before	`string`	date in iso date format, ie `2018-07-03`
defaultDateRange	`string`	the store's default date range

getDateDifferenceInDays ⇒ `number`

Calculates the date difference between two dates. Used in calculating a matching date for previous period.

Kind: global constant Returns: number - - Difference in days.

Param	Type	Description
date	`string`	Date to compare
date2	`string`	Seconary date to compare

getPreviousDate ⇒ `Object`

Get the previous date for either the previous period of year.

Kind: global constant Returns: Object - - Calculated date

Param	Type	Description
date	`string`	Base date
date1	`string`	primary start
date2	`string`	secondary start
compare	`string`	`previous_period` or `previous_year`
interval	`string`	interval

toMoment(format, str) ⇒ `Object` | `null`

Convert a string to Moment object

Kind: global function Returns: Object | null - - Moment object representing given string

Param	Type	Description
format	`string`	localized date string format
str	`string`	date string

getRangeLabel(after, before) ⇒ `string`

Given two dates, derive a string representation

Kind: global function Returns: string - - text value for the supplied date range

Param	Type	Description
after	`Object`	start date
before	`Object`	end date

getStoreTimeZoneMoment() ⇒ `string`

Gets the current time in the store time zone if set.

Kind: global function Returns: string - - Datetime string.

getLastPeriod(period, compare) ⇒ `DateValue`

Get a DateValue object for a period prior to the current period.

Kind: global function Returns: DateValue - - DateValue data about the selected period

Param	Type	Description
period	`string`	the chosen period
compare	`string`	`previous_period` or `previous_year`

getCurrentPeriod(period, compare) ⇒ `DateValue`

Get a DateValue object for a curent period. The period begins on the first day of the period, and ends on the current day.

Kind: global function Returns: DateValue - - DateValue data about the selected period

Param	Type	Description
period	`string`	the chosen period
compare	`string`	`previous_period` or `previous_year`

getAllowedIntervalsForQuery(query, defaultDateRange) ⇒ `Array`

Returns the allowed selectable intervals for a specific query.

Kind: global function Returns: Array - Array containing allowed intervals.

Param	Type	Description
query	`Object`	Current query
defaultDateRange	`string`	the store's default date range

getIntervalForQuery(query, defaultDateRange) ⇒ `string`

Returns the current interval to use.

Kind: global function Returns: string - Current interval.

Param	Type	Description
query	`Object`	Current query
defaultDateRange	`string`	the store's default date range

getChartTypeForQuery(query) ⇒ `string`

Returns the current chart type to use.

Kind: global function Returns: string - Current chart type.

Param	Type	Description
query	`Object`	Current query
query.chartType	`string`

getDateFormatsForInterval(interval, [ticks], [option]) ⇒ `string`

Returns date formats for the current interval.

Kind: global function Returns: string - Current interval.

Param	Type	Description
interval	`string`	Interval to get date formats for.
[ticks]	`number`	Number of ticks the axis will have.
[option]	`Object`	Options
[option.type]	`string`	Date format type, d3 or php, defaults to d3.

getDateFormatsForIntervalD3(interval, [ticks]) ⇒ `string`

Returns d3 date formats for the current interval. See https://github.com/d3/d3-time-format for chart formats.

Kind: global function Returns: string - Current interval.

Param	Type	Description
interval	`string`	Interval to get date formats for.
[ticks]	`number`	Number of ticks the axis will have.

getDateFormatsForIntervalPhp(interval, [ticks]) ⇒ `string`

Returns php date formats for the current interval. See see https://www.php.net/manual/en/datetime.format.php.

Kind: global function Returns: string - Current interval.

Param	Type	Description
interval	`string`	Interval to get date formats for.
[ticks]	`number`	Number of ticks the axis will have.

loadLocaleData(config)

Gutenberg's moment instance is loaded with i18n values, which are PHP date formats, ie 'LLL: "F j, Y g:i a"'. Override those with translations of moment style js formats.

Kind: global function

Param	Type	Description
config	`Object`	Locale config object, from store settings.
config.userLocale	`string`
config.weekdaysShort	`Array`

validateDateInputForRange(type, value, [before], [after], format) ⇒ `Object`

Validate text input supplied for a date range.

Kind: global function Returns: Object - validatedDate - validated date object

Param	Type	Description
type	`string`	Designate beginning or end of range, eg `before` or `after`.
value	`string`	User input value
[before]	`Object` \| `null`	If already designated, the before date parameter
[after]	`Object` \| `null`	If already designated, the after date parameter
format	`string`	The expected date format in a user's locale

DateValue : `Object`

DateValue Object

Kind: global typedef Properties

Name	Type	Description
label	`string`	The translated value of the period.
range	`string`	The human readable value of a date range.
after	`moment.Moment`	Start of the date range.
before	`moment.Moment`	End of the date range.

DateParams : `Object`

DateParams Object

Kind: global typedef

Param	Type	Description
after	`moment.Moment` \| `null`	If the period supplied is "custom", this is the after date
before	`moment.Moment` \| `null`	If the period supplied is "custom", this is the before date

Properties

Name	Type	Description
period	`string`	period value, ie `last_week`
compare	`string`	compare valuer, ie previous_year

validatedDate : `Object`

Kind: global typedef Properties

Name	Type	Description
date	`Object` \| `null`	A resulting Moment date object or null, if invalid
error	`string`	An optional error message if date is invalid

README.md

Date

Installation

Usage

Functions

Typedefs

appendTimestamp ⇒ string

getDateValue ⇒ DateValue

getDateParamsFromQueryMemoized ⇒ Object

getDateParamsFromQuery ⇒ DateParams

getCurrentDatesMemoized ⇒ Object

getCurrentDates ⇒ Object

getDateDifferenceInDays ⇒ number

getPreviousDate ⇒ Object

toMoment(format, str) ⇒ Object | null

getRangeLabel(after, before) ⇒ string

getStoreTimeZoneMoment() ⇒ string

getLastPeriod(period, compare) ⇒ DateValue

getCurrentPeriod(period, compare) ⇒ DateValue

getAllowedIntervalsForQuery(query, defaultDateRange) ⇒ Array

getIntervalForQuery(query, defaultDateRange) ⇒ string

getChartTypeForQuery(query) ⇒ string

getDateFormatsForInterval(interval, [ticks], [option]) ⇒ string

getDateFormatsForIntervalD3(interval, [ticks]) ⇒ string

getDateFormatsForIntervalPhp(interval, [ticks]) ⇒ string

loadLocaleData(config)

validateDateInputForRange(type, value, [before], [after], format) ⇒ Object

DateValue : Object

DateParams : Object

validatedDate : Object

appendTimestamp ⇒ `string`

getDateValue ⇒ `DateValue`

getDateParamsFromQueryMemoized ⇒ `Object`

getDateParamsFromQuery ⇒ `DateParams`

getCurrentDatesMemoized ⇒ `Object`

getCurrentDates ⇒ `Object`

getDateDifferenceInDays ⇒ `number`

getPreviousDate ⇒ `Object`

toMoment(format, str) ⇒ `Object` | `null`

getRangeLabel(after, before) ⇒ `string`

getStoreTimeZoneMoment() ⇒ `string`

getLastPeriod(period, compare) ⇒ `DateValue`

getCurrentPeriod(period, compare) ⇒ `DateValue`

getAllowedIntervalsForQuery(query, defaultDateRange) ⇒ `Array`

getIntervalForQuery(query, defaultDateRange) ⇒ `string`

getChartTypeForQuery(query) ⇒ `string`

getDateFormatsForInterval(interval, [ticks], [option]) ⇒ `string`

getDateFormatsForIntervalD3(interval, [ticks]) ⇒ `string`

getDateFormatsForIntervalPhp(interval, [ticks]) ⇒ `string`

validateDateInputForRange(type, value, [before], [after], format) ⇒ `Object`

DateValue : `Object`

DateParams : `Object`

validatedDate : `Object`