From e209b3d8f0fb6c866b77e6f6eb34e298aec1c929 Mon Sep 17 00:00:00 2001 From: adobesamr <118492837+adobesamr@users.noreply.github.com> Date: Thu, 23 Feb 2023 15:05:08 -0800 Subject: [PATCH] Adds parseDuration documentation (#3844) * Adding parseDuration functionality Adds parseDuration function to internationalized/date package to parse ISO 8601 Duration strings into a DateTimeDuration object * separating parseDuration documentation to separate PR * corrects formatting issues * corrects documentation for parseDuration function * fix deps in @react-types/list (#4073) * fix(#4067): Storybook Provider addon: Express input:checkbox requires id to be labelled by htmlFor prop (#4068) * Explain Proxy in TableView (#4072) Explain proxy usage in TableView * Update lightningcss (#4070) update lightnincss * fix(#4078): MobileComboBox: searchbox should not have aria-expanded property (#4079) * Get rid of dupe id in DatePicker/useDatePicker (#4085) * Getting rid of duplicated id present in presentational element * generate a separate id instead to avoid useField complaining in useDateField a date field in a datepicker/rangepicker gets the field props removed from it, but we still need to call useField in useDateField which will complain that there isnt a aria labelledby so we still need to pass the field props * Code changes from docs-ts branch (#4090) * Add docs to more pages, and small wording updates --------- Co-authored-by: Daniel Lu Co-authored-by: Danni Co-authored-by: Reid Barber Co-authored-by: Michael Jordan Co-authored-by: Robert Snow Co-authored-by: Devon Govett --- .../@internationalized/date/docs/CalendarDate.mdx | 12 ++++++++++++ .../date/docs/CalendarDateTime.mdx | 15 +++++++++++++++ packages/@internationalized/date/docs/Time.mdx | 15 +++++++++++++++ .../date/docs/ZonedDateTime.mdx | 15 +++++++++++++++ 4 files changed, 57 insertions(+) diff --git a/packages/@internationalized/date/docs/CalendarDate.mdx b/packages/@internationalized/date/docs/CalendarDate.mdx index c7ef5de61d2..ab50273f291 100644 --- a/packages/@internationalized/date/docs/CalendarDate.mdx +++ b/packages/@internationalized/date/docs/CalendarDate.mdx @@ -130,6 +130,18 @@ date.subtract({years: 1, months: 1, days: 1}); // 2021-01-02 Adding or subtracting a duration that goes beyond the limits of a particular field will cause the date to be _balanced_. For example, adding one day to August 31st results in September 1st. In addition, if adding or subtracting one field causes another to be invalid, the date will be _constrained_. For example, adding one month to August 31st results in September 30th because September 31st does not exist. +### Parsing durations + +The function can be used to convert a [ISO 8601 duration string](https://en.wikipedia.org/wiki/ISO_8601#Durations) into a object. Negative values can be written by prefixing the entire string with a minus sign. + +```tsx +parseDuration('P3Y6M6W4D'); +// => {years: 3, months: 6, weeks: 6, days: 4} + +parseDuration('-P3Y6M6W4D'); +// => {years: -3, months: -6, weeks: -6, days: -4} +``` + ### Setting fields `CalendarDate` objects are immutable, which means their properties cannot be set directly. Instead, use the `set` method, and pass the fields to be modified. This will return a new `CalendarDate` with the updated values. diff --git a/packages/@internationalized/date/docs/CalendarDateTime.mdx b/packages/@internationalized/date/docs/CalendarDateTime.mdx index e5ebec8c94f..8c61d6075b7 100644 --- a/packages/@internationalized/date/docs/CalendarDateTime.mdx +++ b/packages/@internationalized/date/docs/CalendarDateTime.mdx @@ -128,6 +128,21 @@ date.subtract({minutes: 30}); // 2022-02-03T09:15 Adding or subtracting a duration that goes beyond the limits of a particular field will cause the date to be _balanced_. For example, adding one day to August 31st results in September 1st. In addition, if adding or subtracting one field causes another to be invalid, the date will be _constrained_. For example, adding one month to August 31st results in September 30th because September 31st does not exist. +### Parsing durations + +The function can be used to convert a [ISO 8601 duration string](https://en.wikipedia.org/wiki/ISO_8601#Durations) into a object. The smallest time unit may include decimal values written with a comma or period, and negative values can be written by prefixing the entire string with a minus sign. + +```tsx +parseDuration('P3Y6M6W4DT12H30M5S'); +// => {years: 3, months: 6, weeks: 6, days: 4, hours: 12, minutes: 30, seconds: 5} + +parseDuration('-P3Y6M6W4DT12H30M5S'); +// => {years: -3, months: -6, weeks: -6, days: -4, hours: -12, minutes: -30, seconds: -5} + +parseDuration('P3Y6M6W4DT12H30M5.5S'); +// => {years: 3, months: 6, weeks: 6, days: 4, hours: 12, minutes: 30, seconds: 5.5} +``` + ### Setting fields `CalendarDateTime` objects are immutable, which means their properties cannot be set directly. Instead, use the `set` method, and pass the fields to be modified. This will return a new `CalendarDateTime` with the updated values. diff --git a/packages/@internationalized/date/docs/Time.mdx b/packages/@internationalized/date/docs/Time.mdx index 0f66e782de3..f8ddf13bd98 100644 --- a/packages/@internationalized/date/docs/Time.mdx +++ b/packages/@internationalized/date/docs/Time.mdx @@ -74,6 +74,21 @@ time.add({seconds: 1}); // 09:45:01 Adding or subtracting a duration that goes beyond the limits of a particular field will cause the time to be _balanced_. For example, adding one minute to `09:59` results in `10:00`. +### Parsing durations + +The function can be used to convert a [ISO 8601 duration string](https://en.wikipedia.org/wiki/ISO_8601#Durations) into a object. The smallest time unit may include decimal values written with a comma or period, and negative values can be written by prefixing the entire string with a minus sign. + +```tsx +parseDuration('PT20H35M15S') +// => {hours: 20, minutes: 35, seconds: 15} + +parseDuration('-PT20H35M15S') +// => {hours: -20, minutes: -35, seconds: -15} + +parseDuration('PT20H35M15,75S') +// => {hours: 20, minutes: 35, seconds: 15.75} +``` + ### Setting fields `Time` objects are immutable, which means their properties cannot be set directly. Instead, use the `set` method, and pass the fields to be modified. This will return a new `Time` with the updated values. diff --git a/packages/@internationalized/date/docs/ZonedDateTime.mdx b/packages/@internationalized/date/docs/ZonedDateTime.mdx index ddab7b9377d..0aa139eb870 100644 --- a/packages/@internationalized/date/docs/ZonedDateTime.mdx +++ b/packages/@internationalized/date/docs/ZonedDateTime.mdx @@ -185,6 +185,21 @@ let date = parseZonedDateTime('2020-03-07T02:00-08:00[America/Los_Angeles]'); date.add({days: 1}); // 2020-03-08T03:00-07:00[America/Los_Angeles] ``` +### Parsing durations + +The function can be used to convert a [ISO 8601 duration string](https://en.wikipedia.org/wiki/ISO_8601#Durations) into a object. The smallest time unit may include decimal values written with a comma or period, and negative values can be written by prefixing the entire string with a minus sign. + +```tsx +parseDuration('P3Y6M6W4DT12H30M5S'); +// => {years: 3, months: 6, weeks: 6, days: 4, hours: 12, minutes: 30, seconds: 5} + +parseDuration('-P3Y6M6W4DT12H30M5S'); +// => {years: -3, months: -6, weeks: -6, days: -4, hours: -12, minutes: -30, seconds: -5} + +parseDuration('P3Y6M6W4DT12H30M5.5S'); +// => {years: 3, months: 6, weeks: 6, days: 4, hours: 12, minutes: 30, seconds: 5.5} +``` + ### Setting fields `ZonedDateTime` objects are immutable, which means their properties cannot be set directly. Instead, use the `set` method, and pass the fields to be modified. This will return a new `ZonedDateTime` with the updated values.