feat(Timestamp): allowed displayed datetime to be UTC (#9649)

* feat(Timestamp): allowed displayed datetime to be UTC

* Updated rendering of default UTC suffix

packages/react-core/src/components/Timestamp/Timestamp.tsx

@@ -64,6 +64,10 @@ export interface TimestampProps extends React.HTMLProps<HTMLSpanElement> {
    * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#Locale_identification_and_negotiation
    */
   locale?: string;
+  /** Flag indicating whether the default content should be displayed as a UTC string
+   * instead of a local string.
+   */
+  shouldDisplayUTC?: boolean;
   /** Determines the format of the displayed time in the timestamp and UTC tooltip. Examples:
    * "Full" => 11:25:00 AM Eastern Daylight Time
    * "Long" => 11:25:00 AM EDT
@@ -84,6 +88,7 @@ export const Timestamp: React.FunctionComponent<TimestampProps> = ({
   displaySuffix = '',
   is12Hour,
   locale,
+  shouldDisplayUTC,
   timeFormat,
   tooltip,
   ...props
@@ -117,16 +122,20 @@ export const Timestamp: React.FunctionComponent<TimestampProps> = ({
     ...formatOptions,
     ...(hasTimeFormat && { timeStyle: timeFormat })
   });
-  const defaultDisplay = `${dateAsLocaleString}${displaySuffix ? ' ' + displaySuffix : ''}`;
 
   const utcTimeFormat = timeFormat !== 'short' ? 'medium' : 'short';
   const convertToUTCString = (date: Date) => new Date(date).toUTCString().slice(0, -3);
   const utcDateString = new Date(convertToUTCString(date)).toLocaleString(locale, {
     ...formatOptions,
     ...(hasTimeFormat && { timeStyle: utcTimeFormat })
   });
-  const defaultTooltipContent = `${utcDateString}${tooltip?.suffix ? ' ' + tooltip.suffix : ' UTC'}`;
+  const defaultUTCSuffix = timeFormat === 'full' ? 'Coordinated Universal Time' : 'UTC';
+  const createUTCContent = (customSuffix: string) =>
+    `${utcDateString} ${customSuffix ? customSuffix : defaultUTCSuffix}`;
 
+  const defaultDisplay = shouldDisplayUTC
+    ? createUTCContent(displaySuffix)
+    : `${dateAsLocaleString}${displaySuffix ? ' ' + displaySuffix : ''}`;
   const { dateTime, ...propsWithoutDateTime } = props;
 
   const timestamp = (
@@ -143,7 +152,7 @@ export const Timestamp: React.FunctionComponent<TimestampProps> = ({
 
   return tooltip ? (
     <Tooltip
-      content={tooltip.variant === TimestampTooltipVariant.default ? defaultTooltipContent : tooltip.content}
+      content={tooltip.variant === TimestampTooltipVariant.default ? createUTCContent(tooltip.suffix) : tooltip.content}
       {...tooltip.tooltipProps}
     >
       {timestamp}

packages/react-core/src/components/Timestamp/__tests__/Timestamp.test.tsx

@@ -55,6 +55,12 @@ test('Renders passed in date with default formatting', () => {
   expect(screen.getByText('1/1/2022, 12:00:00 AM')).toBeInTheDocument();
 });
 
+test('Renders passed in date as UTC when shouldDisplayUTC is true', () => {
+  render(<Timestamp shouldDisplayUTC date={new Date(2022, 0, 1)} />);
+
+  expect(screen.getByText('1/1/2022, 5:00:00 AM UTC')).toBeInTheDocument();
+});
+
 test('Renders with correct datetime attribute when date is passed in', () => {
   const passedDate = new Date(2022, 0, 1);
   render(<Timestamp date={passedDate} />);

packages/react-core/src/components/Timestamp/examples/Timestamp.md

@@ -12,7 +12,10 @@ beta: true
 
 By default, a timestamp will display the current date and time based on the current locale if the `date` prop is not passed in.
 
+Passing the `shouldDisplayUTC` property will display the UTC date and time instead of the current or passed in locale.
+
 ```ts file="./TimestampDefault.tsx"
+
 ```
 
 ### Basic formats
@@ -22,13 +25,15 @@ The format of the displayed content can be customized by passing in the `dateFor
 You can also pass in the `displaySuffix` prop to display a custom suffix at the end of the displayed content. This will not override a timezone that is already displayed from the applied time format.
 
 ```ts file="./TimestampBasicFormats.tsx"
+
 ```
 
 ### Custom format
 
 The format of the displayed content can be further customized by passing in the `customFormat` prop. Read [datetime format options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#options) for a list of options that can be passed in.
 
 ```ts file="./TimestampCustomFormat.tsx"
+
 ```
 
 ### Default tooltip
@@ -38,6 +43,7 @@ To render a tooltip that displays the timestamp content as a UTC time, you can p
 You can customize the suffix of this default tooltip variant by passing in `suffix` to the `tooltip` prop.
 
 ```ts file="./TimestampDefaultTooltip.tsx"
+
 ```
 
 ### Custom content
@@ -47,11 +53,13 @@ To display custom content, such as a relative time or prefacing text, you can pa
 When also rendering a default tooltip with the `tooltip` prop, you can pass in the `dateFormat` and/or `timeFormat` props to customize the tooltip content without affecting the custom timestamp content.
 
 ```ts file="TimestampCustomContent.tsx"
+
 ```
 
 ### Custom tooltip
 
 By passing in `variant="custom"` and `content` to the `tooltip` prop, you can display custom content within the timestamp's tooltip.
 
 ```ts file="TimestampCustomTooltip.tsx"
+
 ```

packages/react-core/src/components/Timestamp/examples/TimestampDefault.tsx

@@ -1,4 +1,10 @@
 import React from 'react';
 import { Timestamp } from '@patternfly/react-core';
 
-export const TimestampDefault: React.FunctionComponent = () => <Timestamp />;
+export const TimestampDefault: React.FunctionComponent = () => (
+  <>
+    <Timestamp />
+    <br />
+    <Timestamp shouldDisplayUTC />
+  </>
+);

packages/react-core/src/components/Timestamp/examples/TimestampDefaultTooltip.tsx

@@ -11,7 +11,7 @@ export const TimestampDefaultTooltip: React.FunctionComponent = () => {
       <br />
       <Timestamp
         date={currentDate}
-        tooltip={{ variant: TimestampTooltipVariant.default, suffix: 'Coordinated Universal Time' }}
+        tooltip={{ variant: TimestampTooltipVariant.default, suffix: 'Coordinated Universal Time (UTC)' }}
       />
     </>
   );