feat: add dateTimeFromNowFriendly localization util

Author: abose

docs/API-Reference/utils/LocalizationUtils.md

@@ -45,3 +45,19 @@ Returns a relative time string (e.g., "2 days ago", "in 3 hours") based on the d
 | [date] | <code>Date</code> | The date to compare with the current date and time. If not given, defaults to now. |
 | [lang] | <code>string</code> | Optional language code to use for formatting (e.g., 'en', 'fr').                          If not provided, defaults to the application locale or 'en'. |
 
+<a name="dateTimeFromNowFriendly"></a>
+
+## dateTimeFromNowFriendly(date, [lang]) ⇒ <code>string</code>
+Returns an intelligent date string.
+- For dates within the last 30 days or the future: relative time (e.g., "2 days ago", "in 3 hours").
+- For dates earlier this year: formatted date (e.g., "Jan 5").
+- For dates not in the current year: formatted date with year (e.g., "Jan 5, 2023").
+
+**Kind**: global function  
+**Returns**: <code>string</code> - - An intelligently formatted date string.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| date | <code>Date</code> | The date to compare and format. |
+| [lang] | <code>string</code> | Optional language code to use for formatting (e.g., 'en', 'fr'). |
+

src/utils/LocalizationUtils.js

@@ -102,11 +102,46 @@ define(function (require, exports, module) {
         }
     }
 
+    /**
+     * Returns an intelligent date string.
+     * - For dates within the last 30 days or the future: relative time (e.g., "2 days ago", "in 3 hours").
+     * - For dates earlier this year: formatted date (e.g., "Jan 5").
+     * - For dates not in the current year: formatted date with year (e.g., "Jan 5, 2023").
+     *
+     * @param {Date} date - The date to compare and format.
+     * @param {string} [lang] - Optional language code to use for formatting (e.g., 'en', 'fr').
+     * @returns {string} - An intelligently formatted date string.
+     */
+    function dateTimeFromNowFriendly(date, lang) {
+        const now = new Date();
+        const diffInMilliseconds = date - now;
+        const diffInDays = Math.floor(diffInMilliseconds / (1000 * 60 * 60 * 24));
+
+        // If within the last 30 days or the future, use relative time
+        if (Math.abs(diffInDays) <= 30) {
+            return dateTimeFromNow(date, lang);
+        }
+
+        // If in the current year, format as "MMM DD"
+        const currentYear = now.getFullYear();
+        const dateYear = date.getFullYear();
+
+        const languageOption = [lang || brackets.getLocale() || "en", "en"];
+
+        if (currentYear === dateYear) {
+            return new Intl.DateTimeFormat(languageOption, { month: "short", day: "numeric" }).format(date);
+        }
+
+        // For dates in previous years, format as "MMM DD, YYYY"
+        return new Intl.DateTimeFormat(languageOption,
+            { month: "short", day: "numeric", year: "numeric" }).format(date);
+    }
 
     // Define public API
     exports.getLocalizedLabel = getLocalizedLabel;
     exports.getFormattedDateTime = getFormattedDateTime;
     exports.dateTimeFromNow = dateTimeFromNow;
+    exports.dateTimeFromNowFriendly = dateTimeFromNowFriendly;
     // public constants
     exports.DATE_TIME_STYLE = DATE_TIME_STYLE;
 });

test/spec/LocalizationUtils-test.js

@@ -193,5 +193,79 @@ define(function (require, exports, module) {
                 expect(result).toBe("now");
             });
         });
+
+        describe("dateTimeFromNowFriendly", function () {
+            it("should use relative time for dates within the last 30 days", function () {
+                const testDate = new Date(Date.now() - 3 * 24 * 60 * 60 * 1000); // 3 days ago
+                const result = LocalizationUtils.dateTimeFromNowFriendly(testDate, "en");
+                expect(result).toBe("3 days ago");
+            });
+
+            it("should use relative time for dates in the future within 30 days", function () {
+                const testDate = new Date(Date.now() + 5 * 24 * 60 * 60 * 1000); // 5 days in the future
+                const result = LocalizationUtils.dateTimeFromNowFriendly(testDate, "en");
+                expect(result).toBe("in 5 days");
+            });
+
+            it("should use formatted date without year for dates earlier this year", function () {
+                const now = new Date();
+                const testDate = new Date(now.getFullYear(), 1, 15); // Feb 15 of current year
+                const result = LocalizationUtils.dateTimeFromNowFriendly(testDate, "en");
+                expect(result).toBe("Feb 15");
+            });
+
+            it("should use formatted date with year for dates in previous years", function () {
+                const testDate = new Date(2022, 6, 4); // July 4, 2022
+                const result = LocalizationUtils.dateTimeFromNowFriendly(testDate, "en");
+                expect(result).toBe("Jul 4, 2022");
+            });
+
+            it("should use formatted date with year for future dates in upcoming years", function () {
+                const testDate = new Date(new Date().getFullYear() + 2, 0, 1); // Jan 1, two years from now
+                const result = LocalizationUtils.dateTimeFromNowFriendly(testDate, "en");
+                expect(result).toBe("Jan 1, " + (new Date().getFullYear() + 2));
+            });
+
+            it("should handle relative time for today", function () {
+                const now = new Date();
+                const result = LocalizationUtils.dateTimeFromNowFriendly(now, "en");
+                expect(result).toBe("now");
+            });
+
+            // Relative time tests
+            it("should use relative time for dates within the last 30 days (de locale)", function () {
+                const testDate = new Date(Date.now() - 3 * 24 * 60 * 60 * 1000); // 3 days ago
+                const result = LocalizationUtils.dateTimeFromNowFriendly(testDate, "de");
+                expect(result).toBe("vor 3 Tagen");
+            });
+
+            it("should use relative time for dates in the future within 30 days (de locale)", function () {
+                const testDate = new Date(Date.now() + 5 * 24 * 60 * 60 * 1000); // 5 days in the future
+                const result = LocalizationUtils.dateTimeFromNowFriendly(testDate, "de");
+                expect(result).toBe("in 5 Tagen");
+            });
+
+            // Current year tests
+            it("should use formatted date without year for dates earlier this year (de locale)", function () {
+                const now = new Date();
+                const testDate = new Date(now.getFullYear(), 1, 15); // Feb 15 of current year
+                const result = LocalizationUtils.dateTimeFromNowFriendly(testDate, "de");
+                expect(result).toBe("15. Feb.");
+            });
+
+            // Non-current year tests
+            it("should use formatted date with year for dates in previous years (de locale)", function () {
+                const testDate = new Date(2022, 6, 4); // July 4, 2022
+                const result = LocalizationUtils.dateTimeFromNowFriendly(testDate, "de");
+                expect(result).toBe("4. Juli 2022");
+            });
+
+            it("should use formatted date with year for future dates in upcoming years (de locale)", function () {
+                const testDate = new Date(new Date().getFullYear() + 2, 0, 1); // Jan 1, two years from now
+                const result = LocalizationUtils.dateTimeFromNowFriendly(testDate, "de");
+                expect(result).toBe(`1. Jan. ${new Date().getFullYear() + 2}`);
+            });
+        });
+
     });
 });