woocommerce/packages/js/date/README.md

18 KiB

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

appendTimestampstring

Adds timestamp to a string date.

getDateValueDateValue

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

getDateParamsFromQueryMemoizedObject

Memoized internal logic of getDateParamsFromQuery().

getDateParamsFromQueryDateParams

Add default date-related parameters to a query object

getCurrentDatesMemoizedObject

Memoized internal logic of getCurrentDates().

getCurrentDatesObject

Get Date Value Objects for a primary and secondary date range

getDateDifferenceInDaysnumber

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

getPreviousDateObject

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