From 65de9c6d24d9f36f8b8213a2b8a15a324d132907 Mon Sep 17 00:00:00 2001
From: Cynthia <cynthia@cynthia.dev>
Date: Wed, 19 Feb 2025 14:02:26 +0100
Subject: [PATCH 1/2] feat(internationalized/date): add `durationToString`
 function to stringify durations as ISO 8061 strings

Additionally, this commit makes `parseDuration` accept decimal values for all time scale components rather than just ones after the time designator.
This is consistent with the ISO 8601-1:2019 specification and should improve interoperability.
---
 packages/@internationalized/date/src/index.ts |   3 +-
 .../@internationalized/date/src/string.ts     | 110 +++++++++++-
 .../date/tests/string.test.js                 | 167 +++++++++++++++---
 3 files changed, 246 insertions(+), 34 deletions(-)

diff --git a/packages/@internationalized/date/src/index.ts b/packages/@internationalized/date/src/index.ts
index 9fed618bc02..248470c3496 100644
--- a/packages/@internationalized/date/src/index.ts
+++ b/packages/@internationalized/date/src/index.ts
@@ -83,6 +83,7 @@ export {
   parseAbsolute,
   parseAbsoluteToLocal,
   parseZonedDateTime,
-  parseDuration
+  parseDuration,
+  durationToString
 } from './string';
 export {DateFormatter} from './DateFormatter';
diff --git a/packages/@internationalized/date/src/string.ts b/packages/@internationalized/date/src/string.ts
index 04a7d3d8b40..804ff7d4798 100644
--- a/packages/@internationalized/date/src/string.ts
+++ b/packages/@internationalized/date/src/string.ts
@@ -23,7 +23,7 @@ const DATE_TIME_RE = /^([+-]\d{6}|\d{4})-(\d{2})-(\d{2})(?:T(\d{2}))?(?::(\d{2})
 const ZONED_DATE_TIME_RE = /^([+-]\d{6}|\d{4})-(\d{2})-(\d{2})(?:T(\d{2}))?(?::(\d{2}))?(?::(\d{2}))?(\.\d+)?(?:([+-]\d{2})(?::?(\d{2}))?)?\[(.*?)\]$/;
 const ABSOLUTE_RE = /^([+-]\d{6}|\d{4})-(\d{2})-(\d{2})(?:T(\d{2}))?(?::(\d{2}))?(?::(\d{2}))?(\.\d+)?(?:(?:([+-]\d{2})(?::?(\d{2}))?)|Z)$/;
 const DATE_TIME_DURATION_RE =
-    /^((?<negative>-)|\+)?P((?<years>\d*)Y)?((?<months>\d*)M)?((?<weeks>\d*)W)?((?<days>\d*)D)?((?<time>T)((?<hours>\d*[.,]?\d{1,9})H)?((?<minutes>\d*[.,]?\d{1,9})M)?((?<seconds>\d*[.,]?\d{1,9})S)?)?$/;
+    /^((?<negative>-)|\+)?P((?<years>\d*[.,]?\d{1,9})Y)?((?<months>\d*[.,]?\d{1,9})M)?((?<weeks>\d*[.,]?\d{1,9})W)?((?<days>\d*[.,]?\d{1,9})D)?((?<time>T)((?<hours>\d*[.,]?\d{1,9})H)?((?<minutes>\d*[.,]?\d{1,9})M)?((?<seconds>\d*[.,]?\d{1,9})S)?)?$/;
 const requiredDurationTimeGroups = ['hours', 'minutes', 'seconds'];
 const requiredDurationGroups = ['years', 'months', 'weeks', 'days', ...requiredDurationTimeGroups];
 
@@ -194,7 +194,7 @@ export function dateToString(date: CalendarDate): string {
   let gregorianDate = toCalendar(date, new GregorianCalendar());
   let year: string;
   if (gregorianDate.era === 'BC') {
-    year = gregorianDate.year === 1 
+    year = gregorianDate.year === 1
       ? '0000'
       : '-' + String(Math.abs(1 - gregorianDate.year)).padStart(6, '00');
   } else {
@@ -220,6 +220,32 @@ export function zonedDateTimeToString(date: ZonedDateTime): string {
   return `${dateTimeToString(date)}${offsetToString(date.offset)}[${date.timeZone}]`;
 }
 
+function validateDurationDecimal(duration: DateTimeDuration): boolean {
+  // Using fallthrough to make code concise.
+  // Note: this wouldn't catch invalid strings such as `PT1.5H0M0S` during parse.
+  switch (true) {
+    case (duration.years || 0) % 1 !== 0:
+      if (duration.months) { return false; }
+
+    case (duration.months || 0) % 1 !== 0:
+      if (duration.weeks) { return false; }
+
+    case (duration.weeks || 0) % 1 !== 0:
+      if (duration.days) { return false; }
+
+    case (duration.days || 0) % 1 !== 0:
+      if (duration.hours) { return false; }
+
+    case (duration.hours || 0) % 1 !== 0:
+      if (duration.minutes) { return false; }
+
+    case (duration.minutes || 0) % 1 !== 0:
+      if (duration.seconds || duration.milliseconds) { return false; }
+  }
+
+  return true;
+}
+
 /**
  * Parses an ISO 8601 duration string (e.g. "P3Y6M6W4DT12H30M5S").
  * @param value An ISO 8601 duration string.
@@ -264,23 +290,91 @@ export function parseDuration(value: string): Required<DateTimeDuration> {
     }
   }
 
-  const duration: Mutable<DateTimeDuration> = {
+  const duration: Mutable<Required<DateTimeDuration>> = {
     years: parseDurationGroup(match.groups?.years, isNegative),
     months: parseDurationGroup(match.groups?.months, isNegative),
     weeks: parseDurationGroup(match.groups?.weeks, isNegative),
     days: parseDurationGroup(match.groups?.days, isNegative),
     hours: parseDurationGroup(match.groups?.hours, isNegative),
     minutes: parseDurationGroup(match.groups?.minutes, isNegative),
-    seconds: parseDurationGroup(match.groups?.seconds, isNegative)
+    seconds: parseDurationGroup(match.groups?.seconds, isNegative),
+    milliseconds: 0
   };
 
-  if (duration.hours !== undefined && ((duration.hours % 1) !== 0) && (duration.minutes || duration.seconds)) {
+  if (!validateDurationDecimal(duration)) {
     throw new Error(`Invalid ISO 8601 Duration string: ${value} - only the smallest unit can be fractional`);
   }
 
-  if (duration.minutes !== undefined && ((duration.minutes % 1) !== 0) && duration.seconds) {
-    throw new Error(`Invalid ISO 8601 Duration string: ${value} - only the smallest unit can be fractional`);
+  return duration;
+}
+
+type NormalizedDuration = Omit<Required<DateTimeDuration>, 'weeks' | 'milliseconds'> & { isNegative: boolean }
+
+function normalizeDuration(duration: DateTimeDuration): NormalizedDuration {
+  const isNegative =
+    (duration.years || 0) < 0 ||
+    (duration.months || 0) < 0 ||
+    (duration.weeks || 0) < 0 ||
+    (duration.days || 0) < 0 ||
+    (duration.hours || 0) < 0 ||
+    (duration.minutes || 0) < 0 ||
+    (duration.seconds || 0) < 0;
+
+  const isPositive =
+    (duration.years || 0) > 0 ||
+    (duration.months || 0) > 0 ||
+    (duration.weeks || 0) > 0 ||
+    (duration.days || 0) > 0 ||
+    (duration.hours || 0) > 0 ||
+    (duration.minutes || 0) > 0 ||
+    (duration.seconds || 0) > 0;
+
+  if (isNegative && isPositive) {
+    throw new Error('Cannot stringify a duration with mixed positive and negative components');
+  }
+
+  if (!validateDurationDecimal(duration)) {
+    throw new Error('Cannot stringify a duration which contains fractional values other than in the lowest order component');
   }
 
-  return duration as Required<DateTimeDuration>;
+  const mul = isNegative ? -1 : 1;
+
+  return {
+    isNegative,
+
+    years: mul * (duration.years || 0),
+    months: mul * (duration.months || 0),
+    days: mul * (((duration.weeks || 0) * 7) + (duration.days || 0)),
+    hours: mul * (duration.hours || 0),
+    minutes: mul * (duration.minutes || 0),
+    seconds: mul * ((duration.seconds || 0) + ((duration.milliseconds || 0) / 1e3))
+  };
+}
+
+/**
+ * Formats a DateTimeDuration to an ISO 8601 duration string (e.g. "P3Y6M6W4DT12H30M5S").
+ * @param value A DateTimeDuration object.
+ * @returns An ISO 8601 duration string.
+ */
+export function durationToString(durationSrc: DateTimeDuration): string {
+  let durationString = 'P';
+  let timeDurationString = 'T';
+
+  const duration = normalizeDuration(durationSrc);
+
+  if (duration.years) { durationString += `${duration.years}Y`; }
+  if (duration.months) { durationString += `${duration.months}M`; }
+  if (duration.days) { durationString += `${duration.days}D`; }
+
+  if (duration.hours) { timeDurationString += `${duration.hours}H`; }
+  if (duration.minutes) { timeDurationString += `${duration.minutes}M`; }
+  if (duration.seconds) { timeDurationString += `${duration.seconds}S`; }
+
+  if (timeDurationString.length > 1) { durationString += timeDurationString; }
+
+  // ISO 8601-1:2019 § 5.5.2.3 a) "[...] at least one number and its designator shall be present."
+  // Picking day is arbitrary; it's the smallest unit that doesn't involve the time designator.
+  if (durationString.length < 2) { durationString += '0D'; }
+
+  return duration.isNegative ? `-${durationString}` : durationString;
 }
diff --git a/packages/@internationalized/date/tests/string.test.js b/packages/@internationalized/date/tests/string.test.js
index 705f7008a73..b5a51f0af9b 100644
--- a/packages/@internationalized/date/tests/string.test.js
+++ b/packages/@internationalized/date/tests/string.test.js
@@ -11,6 +11,7 @@
  */
 
 import {CalendarDate, CalendarDateTime, parseAbsolute, parseDate, parseDateTime, parseDuration, parseTime, parseZonedDateTime, Time, ZonedDateTime} from '../';
+import {durationToString} from '../src/string';
 
 describe('string conversion', function () {
   describe('parseTime', function () {
@@ -449,7 +450,8 @@ describe('string conversion', function () {
         days: 4,
         hours: 12,
         minutes: 30,
-        seconds: 5
+        seconds: 5,
+        milliseconds: 0
       });
     });
 
@@ -462,7 +464,8 @@ describe('string conversion', function () {
         days: 4,
         hours: 12,
         minutes: 30,
-        seconds: 5.5
+        seconds: 5.5,
+        milliseconds: 0
       });
     });
 
@@ -475,7 +478,8 @@ describe('string conversion', function () {
         days: 4,
         hours: 12,
         minutes: 30,
-        seconds: 5.5
+        seconds: 5.5,
+        milliseconds: 0
       });
     });
 
@@ -488,7 +492,8 @@ describe('string conversion', function () {
         days: 4,
         hours: 12,
         minutes: 30.5,
-        seconds: 0
+        seconds: 0,
+        milliseconds: 0
       });
     });
 
@@ -501,7 +506,8 @@ describe('string conversion', function () {
         days: 4,
         hours: 12,
         minutes: 30.5,
-        seconds: 0
+        seconds: 0,
+        milliseconds: 0
       });
     });
 
@@ -514,7 +520,8 @@ describe('string conversion', function () {
         days: 4,
         hours: 12.5,
         minutes: 0,
-        seconds: 0
+        seconds: 0,
+        milliseconds: 0
       });
     });
 
@@ -527,7 +534,8 @@ describe('string conversion', function () {
         days: 4,
         hours: 12.5,
         minutes: 0,
-        seconds: 0
+        seconds: 0,
+        milliseconds: 0
       });
     });
 
@@ -540,7 +548,8 @@ describe('string conversion', function () {
         days: -4,
         hours: -12,
         minutes: -30,
-        seconds: -5
+        seconds: -5,
+        milliseconds: 0
       });
     });
 
@@ -553,7 +562,8 @@ describe('string conversion', function () {
         days: 4,
         hours: 12,
         minutes: 30,
-        seconds: 5
+        seconds: 5,
+        milliseconds: 0
       });
     });
 
@@ -566,7 +576,8 @@ describe('string conversion', function () {
         days: 0,
         hours: 20,
         minutes: 35,
-        seconds: 15
+        seconds: 15,
+        milliseconds: 0
       });
     });
 
@@ -579,7 +590,8 @@ describe('string conversion', function () {
         days: 6,
         hours: 0,
         minutes: 0,
-        seconds: 0
+        seconds: 0,
+        milliseconds: 0
       });
     });
 
@@ -592,7 +604,8 @@ describe('string conversion', function () {
         days: 0,
         hours: 20,
         minutes: 0,
-        seconds: 15
+        seconds: 15,
+        milliseconds: 0
       });
     });
 
@@ -605,7 +618,66 @@ describe('string conversion', function () {
         days: 99,
         hours: 99,
         minutes: 99,
-        seconds: 99
+        seconds: 99,
+        milliseconds: 0
+      });
+    });
+
+
+    it('parses an ISO 8601 duration string that contains only years as a fractional value expressed with a period and returns a DateTimeDuration object', function () {
+      const duration = parseDuration('P0.5Y');
+      expect(duration).toStrictEqual({
+        years: 0.5,
+        months: 0,
+        weeks: 0,
+        days: 0,
+        hours: 0,
+        minutes: 0,
+        seconds: 0,
+        milliseconds: 0
+      });
+    });
+
+
+    it('parses an ISO 8601 duration string that contains years, months, and fractional values for months expressed with a comma and returns a DateTimeDuration object', function () {
+      const duration = parseDuration('P1Y0,5M');
+      expect(duration).toStrictEqual({
+        years: 1,
+        months: 0.5,
+        weeks: 0,
+        days: 0,
+        hours: 0,
+        minutes: 0,
+        seconds: 0,
+        milliseconds: 0
+      });
+    });
+
+    it('parses an ISO 8601 duration string that contains years, months, weeks, and fractional values for weeks expressed with a period and returns a DateTimeDuration object', function () {
+      const duration = parseDuration('P1Y1M0.5W');
+      expect(duration).toStrictEqual({
+        years: 1,
+        months: 1,
+        weeks: 0.5,
+        days: 0,
+        hours: 0,
+        minutes: 0,
+        seconds: 0,
+        milliseconds: 0
+      });
+    });
+
+    it('parses an ISO 8601 duration string that contains years, months, weeks, days and fractional values for days expressed with a comma and returns a DateTimeDuration object', function () {
+      const duration = parseDuration('P1Y1M1W0,5D');
+      expect(duration).toStrictEqual({
+        years: 1,
+        months: 1,
+        weeks: 1,
+        days: 0.5,
+        hours: 0,
+        minutes: 0,
+        seconds: 0,
+        milliseconds: 0
       });
     });
 
@@ -631,18 +703,6 @@ describe('string conversion', function () {
       expect(() => {
         parseDuration('P1Y1M1W1DT1H1M1.123456789123S');
       }).toThrow('Invalid ISO 8601 Duration string: P1Y1M1W1DT1H1M1.123456789123S');
-      expect(() => {
-        parseDuration('P0.5Y');
-      }).toThrow('Invalid ISO 8601 Duration string: P0.5Y');
-      expect(() => {
-        parseDuration('P1Y0,5M');
-      }).toThrow('Invalid ISO 8601 Duration string: P1Y0,5M');
-      expect(() => {
-        parseDuration('P1Y1M0.5W');
-      }).toThrow('Invalid ISO 8601 Duration string: P1Y1M0.5W');
-      expect(() => {
-        parseDuration('P1Y1M1W0,5D');
-      }).toThrow('Invalid ISO 8601 Duration string: P1Y1M1W0,5D');
       expect(() => {
         parseDuration('P1Y1M1W1DT0.5H5S');
       }).toThrow('Invalid ISO 8601 Duration string: P1Y1M1W1DT0.5H5S - only the smallest unit can be fractional');
@@ -652,6 +712,12 @@ describe('string conversion', function () {
       expect(() => {
         parseDuration('P1Y1M1W1DT1H0.5M0.5S');
       }).toThrow('Invalid ISO 8601 Duration string: P1Y1M1W1DT1H0.5M0.5S - only the smallest unit can be fractional');
+      expect(() => {
+        parseDuration('P1.5Y1M1W1DT1H5M5S');
+      }).toThrow('Invalid ISO 8601 Duration string: P1.5Y1M1W1DT1H5M5S - only the smallest unit can be fractional');
+      expect(() => {
+        parseDuration('P1.5Y1M1W1DT1H0.5M0.5S');
+      }).toThrow('Invalid ISO 8601 Duration string: P1.5Y1M1W1DT1H0.5M0.5S - only the smallest unit can be fractional');
       expect(() => {
         parseDuration('P');
       }).toThrow('Invalid ISO 8601 Duration string: P');
@@ -681,4 +747,55 @@ describe('string conversion', function () {
       }).toThrow('Invalid ISO 8601 Duration string: P1Y-1M');
     });
   });
+
+  describe('durationToString', function () {
+    it('should stringify a DateTimeDuration as an ISO 8601 compliant string', function () {
+      const duration = {years: 1, months: 2, days: 3, hours: 4, minutes: 5, seconds: 6};
+      expect(durationToString(duration)).toBe('P1Y2M3DT4H5M6S');
+    });
+
+    it('should stringify a DateTimeDuration with milliseconds as an ISO 8601 compliant string', function () {
+      const duration = {years: 1, months: 2, days: 3, hours: 4, minutes: 5, seconds: 6, milliseconds: 50};
+      expect(durationToString(duration)).toBe('P1Y2M3DT4H5M6.05S');
+    });
+
+    it('should stringify a DateTimeDuration with the last component of the duration being a decimal', function () {
+      const duration = {years: 1, months: 2, days: 3, hours: 4, minutes: 5, seconds: 6.5};
+      expect(durationToString(duration)).toBe('P1Y2M3DT4H5M6.5S');
+    });
+
+    it('should stringify a DateTimeDuration with decimal seconds and milliseconds', function () {
+      const duration = {years: 1, months: 2, days: 3, hours: 4, minutes: 5, seconds: 6.5, milliseconds: 1234};
+      expect(durationToString(duration)).toBe('P1Y2M3DT4H5M7.734S');
+    });
+
+    it('should not produce a string with the W time scale component', function () {
+      const duration = {weeks: 2, days: 6};
+      expect(durationToString(duration)).toBe('P20D');
+    });
+
+    it('should stringify a DateTimeDuration with negative values', function () {
+      const duration = {years: -1, months: -2, days: -3, hours: -4, minutes: -5, seconds: -6};
+      expect(durationToString(duration)).toBe('-P1Y2M3DT4H5M6S');
+    });
+
+    it('should throw an error if the DateTimeDuration has mixed positive and negative components', function () {
+      const duration = {years: -1, months: -2, days: 3, hours: -4, minutes: -5, seconds: -6};
+      expect(() => durationToString(duration)).toThrow('Cannot stringify a duration with mixed positive and negative components');
+    });
+
+    it('should throw an error if the DateTimeDuration has a decimal component that\'s not the lowest order', function () {
+      const duration = {years: 1, months: 2, days: 3, hours: 4, minutes: 5.5, seconds: 6};
+      expect(() => durationToString(duration)).toThrow('Cannot stringify a duration which contains fractional values other than in the lowest order component');
+    });
+
+    it('should throw an error if the DateTimeDuration has decimal minutes, no seconds, and milliseconds', function () {
+      const duration = {years: 1, months: 2, days: 3, hours: 4, minutes: 5.5, milliseconds: 6};
+      expect(() => durationToString(duration)).toThrow('Cannot stringify a duration which contains fractional values other than in the lowest order component');
+    });
+
+    it('should produce a valid ISO 8601 string for zero duration', function () {
+      expect(durationToString({})).toBe('P0D');
+    });
+  });
 });

From d01f77f44b5a6b8cb13fc23828f1ed9587f42be4 Mon Sep 17 00:00:00 2001
From: Cynthia <cynthia@cynthia.dev>
Date: Wed, 19 Feb 2025 14:08:44 +0100
Subject: [PATCH 2/2] docs(internationalized/date): document `durationToString`

---
 .../@internationalized/date/docs/CalendarDate.mdx   | 10 ++++++++++
 .../date/docs/CalendarDateTime.mdx                  | 13 +++++++++++++
 packages/@internationalized/date/docs/Time.mdx      | 13 +++++++++++++
 .../@internationalized/date/docs/ZonedDateTime.mdx  | 13 +++++++++++++
 4 files changed, 49 insertions(+)

diff --git a/packages/@internationalized/date/docs/CalendarDate.mdx b/packages/@internationalized/date/docs/CalendarDate.mdx
index ab51b533a97..4b8c48e10de 100644
--- a/packages/@internationalized/date/docs/CalendarDate.mdx
+++ b/packages/@internationalized/date/docs/CalendarDate.mdx
@@ -142,6 +142,16 @@ parseDuration('-P3Y6M6W4D');
 // => {years: -3, months: -6, weeks: -6, days: -4}
 ```
 
+A <TypeLink links={docs.links} type={docs.exports.DateTimeDuration} /> object can be converted back to a [ISO 8601 duration string](https://en.wikipedia.org/wiki/ISO_8601#Durations) by using <TypeLink links={docs.links} type={docs.exports.durationToString} />.
+
+```tsx
+durationToString({years: 3, months: 6, weeks: 6, days: 4});
+// => 'P3Y6M6W4D'
+
+durationToString({years: -3, months: -6, weeks: -6, days: -4});
+// => '-P3Y6M6W4D'
+```
+
 ### 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 3796777ed49..195b47c6303 100644
--- a/packages/@internationalized/date/docs/CalendarDateTime.mdx
+++ b/packages/@internationalized/date/docs/CalendarDateTime.mdx
@@ -143,6 +143,19 @@ parseDuration('P3Y6M6W4DT12H30M5.5S');
 // => {years: 3, months: 6, weeks: 6, days: 4, hours: 12, minutes: 30, seconds: 5.5}
 ```
 
+A <TypeLink links={docs.links} type={docs.exports.DateTimeDuration} /> object can be converted back to a [ISO 8601 duration string](https://en.wikipedia.org/wiki/ISO_8601#Durations) by using <TypeLink links={docs.links} type={docs.exports.durationToString} />.
+
+```tsx
+durationToString({years: 3, months: 6, weeks: 6, days: 4, hours: 12, minutes: 30, seconds: 5});
+// => 'P3Y6M6W4DT12H30M5S'
+
+durationToString({years: -3, months: -6, weeks: -6, days: -4, hours: -12, minutes: -30, seconds: -5});
+// => '-P3Y6M6W4DT12H30M5S'
+
+durationToString({years: 3, months: 6, weeks: 6, days: 4, hours: 12, minutes: 30, seconds: 5.5});
+// => 'P3Y6M6W4DT12H30M5.5S'
+```
+
 ### 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 0a6d7f59e94..3e59b55a23f 100644
--- a/packages/@internationalized/date/docs/Time.mdx
+++ b/packages/@internationalized/date/docs/Time.mdx
@@ -89,6 +89,19 @@ parseDuration('PT20H35M15,75S')
 // => {hours: 20, minutes: 35, seconds: 15.75}
 ```
 
+A <TypeLink links={docs.links} type={docs.exports.DateTimeDuration} /> object can be converted back to a [ISO 8601 duration string](https://en.wikipedia.org/wiki/ISO_8601#Durations) by using <TypeLink links={docs.links} type={docs.exports.durationToString} />.
+
+```tsx
+durationToString({hours: 20, minutes: 35, seconds: 15})
+// => 'PT20H35M15S'
+
+durationToString({hours: -20, minutes: -35, seconds: -15})
+// => '-PT20H35M15S'
+
+durationToString({hours: 20, minutes: 35, seconds: 15.75})
+// => 'PT20H35M15,75S'
+```
+
 ### 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 543f89db6dd..e4ab716dd8f 100644
--- a/packages/@internationalized/date/docs/ZonedDateTime.mdx
+++ b/packages/@internationalized/date/docs/ZonedDateTime.mdx
@@ -213,6 +213,19 @@ parseDuration('P3Y6M6W4DT12H30M5.5S');
 // => {years: 3, months: 6, weeks: 6, days: 4, hours: 12, minutes: 30, seconds: 5.5}
 ```
 
+A <TypeLink links={docs.links} type={docs.exports.DateTimeDuration} /> object can be converted back to a [ISO 8601 duration string](https://en.wikipedia.org/wiki/ISO_8601#Durations) by using <TypeLink links={docs.links} type={docs.exports.durationToString} />.
+
+```tsx
+durationToString({years: 3, months: 6, weeks: 6, days: 4, hours: 12, minutes: 30, seconds: 5});
+// => 'P3Y6M6W4DT12H30M5S'
+
+durationToString({years: -3, months: -6, weeks: -6, days: -4, hours: -12, minutes: -30, seconds: -5});
+// => '-P3Y6M6W4DT12H30M5S'
+
+durationToString({years: 3, months: 6, weeks: 6, days: 4, hours: 12, minutes: 30, seconds: 5.5});
+// => 'P3Y6M6W4DT12H30M5.5S'
+```
+
 ### 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.