wrap with a <time> element by default

README.md

@@ -33,3 +33,4 @@ import TimeAgo from "react-timeago-i18n";
 | `formatOptions` | [options for `Intl.RelativeTimeFormat`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat#basic_format_usage) | `undefined`          |
 | `hideSeconds`   | If `true`, values smaller than 1 minute will shown as "1 minute" instead of frequently updating seconds.                                                             | `false`              |
 | `roundStrategy` | By default, values are `floor`ed (e.g. 11.9 months becomes "1 year"). If this is not desired, the rounding strategy can be changed to `round`.                       | `"floor"`            |
+| `timeElement`   | By default, the result is wrapped in `<time title="..."> ... </time>`, unless you set this property to `false`                                                       | `true`               |

src/__tests__/index.test.tsx

@@ -1,4 +1,4 @@
-import { vi } from "vitest";
+import { assert, vi } from "vitest";
 import { render, screen } from "@testing-library/react";
 import "@testing-library/jest-dom";
 import TimeAgo, { TimeAgoProps } from "../index.js";
@@ -110,4 +110,25 @@ describe("TimeAgo", () => {
       }
     );
   });
+
+  describe("time element", () => {
+    it.each`
+      date            | locale     | tooltip         | isoDate
+      ${"2023-02-06"} | ${"en-US"} | ${"2/6/2023, "} | ${"2023-02-06T00:00:00.000Z"}
+      ${"2019-02-06"} | ${"de"}    | ${"6.2.2019, "} | ${"2019-02-06T00:00:00.000Z"}
+    `(
+      "renders a tooltip for $date in $locale",
+      ({ date, locale, tooltip, isoDate }) => {
+        const element = setup({
+          date,
+          hideSeconds: true,
+          locale,
+        }).querySelector("time");
+
+        assert(element instanceof HTMLTimeElement);
+        expect(element.title).toContain(tooltip);
+        expect(element.dateTime).toBe(isoDate);
+      }
+    );
+  });
 });

src/index.tsx

@@ -46,6 +46,14 @@ export type TimeAgoProps = {
    * strategy can be changed to `round` or even `ceil`.
    */
   roundStrategy?: RoundStrategy;
+  /**
+   * by default, the result is wrapped in an
+   * {@link HTMLTimeElement} (`<time>`), with the `title`
+   * attribute set to {@link Date.toLocaleString}. If
+   * `timeElement` is set to `false`, then the text is
+   * returned with no `<time>` element.
+   */
+  timeElement?: boolean;
 };
 
 const TimeAgo = memo<TimeAgoProps>(
@@ -55,6 +63,7 @@ const TimeAgo = memo<TimeAgoProps>(
     formatOptions,
     hideSeconds,
     roundStrategy,
+    timeElement = true,
   }) => {
     const [text, setText] = useState("");
     const [unit, setUnit] = useState<Unit>();
@@ -70,9 +79,12 @@ const TimeAgo = memo<TimeAgoProps>(
       [locale, formatOptions]
     );
 
-    const doUpdate = useCallback(() => {
-      const dateObject = date instanceof Date ? date : new Date(date);
+    const dateObject = useMemo(
+      () => (date instanceof Date ? date : new Date(date)),
+      [date]
+    );
 
+    const doUpdate = useCallback(() => {
       const [value, newUnit] = timeSince(dateObject, roundStrategy);
       setText(
         newUnit === "seconds" && hideSeconds
@@ -83,7 +95,7 @@ const TimeAgo = memo<TimeAgoProps>(
       // setUnit is auto-batched with the previous setState,
       // in react 18+, and auto-aborted if this would be a
       // no-op in all react versions.
-    }, [date, formatter, hideSeconds, roundStrategy]);
+    }, [dateObject, formatter, hideSeconds, roundStrategy]);
 
     useEffect(doUpdate, [doUpdate]);
 
@@ -96,8 +108,17 @@ const TimeAgo = memo<TimeAgoProps>(
       return () => clearInterval(intervalId);
     }, [unit, doUpdate]);
 
-    // avoid using a JSX fragment to keep things simple
-    return text;
+    return timeElement ? (
+      <time
+        title={dateObject.toLocaleString(locale)}
+        dateTime={dateObject.toISOString()}
+      >
+        {text}
+      </time>
+    ) : (
+      // avoid using a JSX fragment to keep things simple
+      text
+    );
   }
 );
 TimeAgo.displayName = "TimeAgo";