feat(formatDate): add locale option to be extensible for absolute format #19157

dkaushik95 · 2025-04-17T00:01:14Z

Closes #

Currently absolute.format* doesn't work for our product since we allow users the option to switch to UTC time. Adding timeZone as a prop allows us to override the default timezone that Intl chooses.

Changelog

New

@carbon/utilities - Datetime.absolute now allows you to choose a timeZone which can be used to override the default timeZone while formatting datetime. This prop will be available to: formatTime, formatTime, format, and formatRange

Testing / Reviewing

Testers can try out the following use case:

timestamp: 1744835151846
use this timestamp to check the time difference between your locale and UTC
eg:

datetime: 1744835151846
utc string: Apr 16, 2025, 8:25:51 PM
local string: Apr 16, 2025, 1:25:51 PM

netlify · 2025-04-17T00:08:03Z

✅ Deploy Preview for v11-carbon-web-components ready!

Name	Link
🔨 Latest commit	`08832a8`
🔍 Latest deploy log	https://app.netlify.com/sites/v11-carbon-web-components/deploys/681a2b52ebf6be00081a9326
😎 Deploy Preview	https://deploy-preview-19157--v11-carbon-web-components.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

netlify · 2025-04-17T00:12:32Z

✅ Deploy Preview for v11-carbon-react ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`08832a8`
🔍 Latest deploy log	https://app.netlify.com/sites/v11-carbon-react/deploys/681a2b524621df000861fa8b
😎 Deploy Preview	https://deploy-preview-19157--v11-carbon-react.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

codecov · 2025-04-17T00:18:54Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 84.59%. Comparing base (5d1b860) to head (08832a8).
Report is 17 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main   #19157   +/-   ##
=======================================
  Coverage   84.59%   84.59%           
=======================================
  Files         380      380           
  Lines       14471    14471           
  Branches     4771     4737   -34     
=======================================
  Hits        12242    12242           
  Misses       2074     2074           
  Partials      155      155

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

nchevsky

@dkaushik95 Can you add unit test coverage in absolute-test.js?

packages/utilities/src/dateTimeFormat/absolute.ts

dkaushik95 · 2025-04-17T14:58:51Z

Thanks for the review @nchevsky . I have addressed all the review comments. Can you re-review it? Thanks!

packages/utilities/src/dateTimeFormat/absolute-test.js

packages/utilities/src/dateTimeFormat/absolute.ts

nchevsky · 2025-04-18T03:59:28Z

packages/utilities/src/dateTimeFormat/absolute-test.js

+      timeZones.forEach((timeZone) => {
+        const dtf = new Intl.DateTimeFormat(locale, {
+          timeStyle: style,
+          timeZone,
+        });
+        const expectedOutput = dtf.format(date);
+
+        test(`${style} with timeZone ${timeZone} → ${expectedOutput}`, () => {
+          const actualOutput = absolute.formatTime(date, {
+            locale,
+            style,
+            timeZone,
+          });
+          expect(actualOutput).toBe(expectedOutput);
+        });
+      });


I wouldn't put this within the timeStyle loop, as (a) it multiplies the number of iterations 4 → 12 and (b) timeStyle and timeZone aren't dependent on each other.

We don't even need to test three different time zones, for timeZone is simply passed through to Intl.DateTimeFormat regardless of its value. Some alternatives, in ascending order of complexity:

Test any two time zones so that, even if one happens to match the host's, the other won't; or

spy on Intl.DateTimeFormat and simply assert that absolute.format*() instantiated it with the given timeZone option; or

dynamically select a time zone other than the host's, and test just that one.

I'd personally go with # 2 as it's more of a true unit test, but seeing how none of the preexisting tests are written this way, it might be less controversial to stick with # 1.

Whichever you choose, please replicate to all tests. 🙏🏻

Hey, I chose the 1st option. I chose two timezones Tokyo and UTC so that it's always different for any host for at least one test. I also addressed the 2nd concern of using describe for timeZones so it should be consistent across all tests. I was trying different approaches and accidentally added both approaches :)

This will how the tests would show up.

At the end there will be 2 test cases for each function (8 iterations in all)

packages/utilities/src/dateTimeFormat/absolute-test.js

preetibansalui · 2025-04-30T14:11:06Z

@dkaushik95 I approved the PR and then realized we missed updating the documentation for the newly added option. Could you please add the relevant details to the README file?

dkaushik95 · 2025-05-05T20:42:19Z

@preetibansalui Hello! I have made changes to add documentation to the readme. Can you give it a review? Thanks!

preetibansalui

Looks good to me—just a small spelling correction needed.

preetibansalui · 2025-05-06T05:38:21Z

packages/utilities/src/dateTimeFormat/README.md

+
+For `absolute` functions, you can provide `timeZone` as an optional property.
+This is usefull when (for example) you want to display utc time instead of a
+local timezone.


This is useful when (for example) you want to display UTC time instead of a
local time zone.

thanks! Fixed :)

preetibansalui

Thanks for the changes, This LGTM 👍

feat(formatDate): add locale option to be extensible for absolute format

fc43853

dkaushik95 requested review from a team as code owners April 17, 2025 00:01

dkaushik95 requested review from preetibansalui and ariellalgilmore April 17, 2025 00:01

nchevsky suggested changes Apr 17, 2025

View reviewed changes

packages/utilities/src/dateTimeFormat/absolute.ts Outdated Show resolved Hide resolved

packages/utilities/src/dateTimeFormat/absolute.ts Outdated Show resolved Hide resolved

packages/utilities/src/dateTimeFormat/absolute.ts Outdated Show resolved Hide resolved

dkaushik95 added 2 commits April 16, 2025 21:31

feat(dateTimeFormat): add timeZone option to formatDate and update tests

7ee00de

fix(dateTimeFormat): address pr comments for partial types

75939cc

dkaushik95 requested a review from nchevsky April 17, 2025 15:35

adamalston reviewed Apr 18, 2025

View reviewed changes

packages/utilities/src/dateTimeFormat/absolute-test.js Show resolved Hide resolved

packages/utilities/src/dateTimeFormat/absolute.ts Show resolved Hide resolved

nchevsky reviewed Apr 18, 2025

View reviewed changes

dkaushik95 requested review from nchevsky and adamalston April 21, 2025 16:03

nchevsky approved these changes Apr 21, 2025

View reviewed changes

dkaushik95 and others added 4 commits April 22, 2025 11:09

Merge branch 'main' into add-timezone-to-datetime

29d5a90

Merge branch 'main' into add-timezone-to-datetime

daac0e8

Merge branch 'main' into add-timezone-to-datetime

43e4f76

Merge branch 'main' into add-timezone-to-datetime

3568311

preetibansalui approved these changes Apr 30, 2025

View reviewed changes

preetibansalui added the status: one more review 👀 label Apr 30, 2025

preetibansalui self-requested a review April 30, 2025 14:12

preetibansalui removed the status: one more review 👀 label Apr 30, 2025

dkaushik95 added 2 commits May 5, 2025 13:40

docs(timezone): add docs for timezone

7c24587

Merge branch 'main' into add-timezone-to-datetime

cec0ae4

preetibansalui requested changes May 6, 2025

View reviewed changes

dkaushik95 added 2 commits May 6, 2025 08:30

fix(spelling): fix typo

f9b75b8

Merge branch 'main' into add-timezone-to-datetime

08832a8

dkaushik95 requested a review from preetibansalui May 12, 2025 15:44

preetibansalui approved these changes May 12, 2025

View reviewed changes

preetibansalui added the status: one more review 👀 label May 12, 2025

ariellalgilmore approved these changes May 12, 2025

View reviewed changes

ariellalgilmore added this pull request to the merge queue May 12, 2025

ariellalgilmore added status: ready to merge 🎉 and removed status: one more review 👀 labels May 12, 2025

Merged via the queue into carbon-design-system:main with commit 0ce2c4e May 12, 2025
37 checks passed

feat(formatDate): add locale option to be extensible for absolute format #19157

feat(formatDate): add locale option to be extensible for absolute format #19157

Uh oh!

Conversation

dkaushik95 commented Apr 17, 2025

Changelog

Testing / Reviewing

Uh oh!

netlify bot commented Apr 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for v11-carbon-web-components ready!

Uh oh!

netlify bot commented Apr 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for v11-carbon-react ready!

Uh oh!

codecov bot commented Apr 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

nchevsky left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

dkaushik95 commented Apr 17, 2025

Uh oh!

Uh oh!

Uh oh!

nchevsky Apr 18, 2025

Choose a reason for hiding this comment

Uh oh!

dkaushik95 Apr 21, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

preetibansalui commented Apr 30, 2025

Uh oh!

dkaushik95 commented May 5, 2025

Uh oh!

preetibansalui left a comment

Choose a reason for hiding this comment

Uh oh!

preetibansalui May 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dkaushik95 May 6, 2025

Choose a reason for hiding this comment

Uh oh!

preetibansalui left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

netlify bot commented Apr 17, 2025 •

edited

Loading

netlify bot commented Apr 17, 2025 •

edited

Loading

codecov bot commented Apr 17, 2025 •

edited

Loading

preetibansalui May 6, 2025 •

edited

Loading