feat: add getFormattedDateTime localization util

Author: abose

docs/API-Reference/command/Commands.md

@@ -476,6 +476,18 @@ Zooms out the editor view
 ## VIEW\_ZOOM\_SUBMENU
 Submenu for zoom options
 
+**Kind**: global variable  
+<a name="OPEN_IN_SUBMENU"></a>
+
+## OPEN\_IN\_SUBMENU
+Submenu for Open in project context menu
+
+**Kind**: global variable  
+<a name="OPEN_IN_SUBMENU_WS"></a>
+
+## OPEN\_IN\_SUBMENU\_WS
+Submenu for Open in working set context menu
+
 **Kind**: global variable  
 <a name="VIEW_INCREASE_FONT_SIZE"></a>
 
@@ -602,6 +614,24 @@ Shows current file in file tree
 ## NAVIGATE\_SHOW\_IN\_OS
 Shows current file in OS file explorer
 
+**Kind**: global variable  
+<a name="NAVIGATE_OPEN_IN_TERMINAL"></a>
+
+## NAVIGATE\_OPEN\_IN\_TERMINAL
+Shows current file in OS Terminal
+
+**Kind**: global variable  
+<a name="NAVIGATE_OPEN_IN_POWERSHELL"></a>
+
+## NAVIGATE\_OPEN\_IN\_POWERSHELL
+Shows current file in open powershell in Windows os
+
+**Kind**: global variable  
+<a name="NAVIGATE_OPEN_IN_DEFAULT_APP"></a>
+
+## NAVIGATE\_OPEN\_IN\_DEFAULT\_APP
+Open current file in the default associated app in the os
+
 **Kind**: global variable  
 <a name="NAVIGATE_QUICK_OPEN"></a>
 

docs/API-Reference/utils/LocalizationUtils.md

@@ -0,0 +1,34 @@
+### Import :
+```js
+const LocalizationUtils = brackets.getModule("utils/LocalizationUtils")
+```
+
+<a name="getLocalizedLabel"></a>
+
+## getLocalizedLabel(locale) ⇒ <code>string</code>
+Converts a language code to its written name, if possible.
+If not possible, the language code is simply returned.
+
+**Kind**: global function  
+**Returns**: <code>string</code> - The language's name or the given language code  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| locale | <code>string</code> | The two-char language code |
+
+<a name="getFormattedDateTime"></a>
+
+## getFormattedDateTime([date], [lang], [dateTimeFormat]) ⇒ <code>string</code>
+Formats a given date object into a locale-aware date and time string.
+
+**Kind**: global function  
+**Returns**: <code>string</code> - - The formatted date and time string (e.g., "Dec 24, 2024, 10:30 AM").  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| [date] | <code>Date</code> | The date object to format. If not provided, the current date and time will be used. |
+| [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'. |
+| [dateTimeFormat] | <code>Object</code> | Optional object specifying the date and time formatting options.                                    Defaults to { dateStyle: 'medium', timeStyle: 'short' }. |
+| [dateTimeFormat.dateStyle] | <code>string</code> | Specifies the date format style. One of: DATE_TIME_STYLE.* |
+| [dateTimeFormat.timeStyle] | <code>string</code> | Specifies the time format style. One of: DATE_TIME_STYLE.* |
+

docs/API-Reference/utils/NodeUtils.md

@@ -82,3 +82,28 @@ This is only available in the native app
 | fullFilePath | <code>string</code> | 
 | projectFullPath | <code>string</code> | 
 
+<a name="openNativeTerminal"></a>
+
+## openNativeTerminal(cwd, [usePowerShell])
+Runs ESLint on a file
+This is only available in the native app
+
+**Kind**: global function  
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| cwd | <code>string</code> |  | the working directory of terminal |
+| [usePowerShell] | <code>boolean</code> | <code>false</code> |  |
+
+<a name="openInDefaultApp"></a>
+
+## openInDefaultApp(fullPath) ⇒ <code>Promise.&lt;void&gt;</code>
+Opens a file in the default application for its type on Windows, macOS, and Linux.
+
+**Kind**: global function  
+**Returns**: <code>Promise.&lt;void&gt;</code> - - Resolves if the file/folder is opened successfully, rejects otherwise.  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| fullPath | <code>string</code> | The path to the file/folder to open. |
+

docs/API-Reference/widgets/PopUpManager.md

@@ -22,7 +22,8 @@ Add Esc key handling for a popup DOM element.
 | removeHandler | <code>function</code> | Pop-up specific remove (e.g. display:none or DOM removal) |
 | autoRemove | <code>Boolean</code> | Specify true to indicate the PopUpManager should      remove the popup from the _popUps array when the popup is closed. Specify false      when the popup is always persistant in the _popUps array. |
 | options | <code>object</code> |  |
-| options.popupManagesFocus | <code>boolean</code> | set to true if the popup manages focus restore on close |
+| [options.popupManagesFocus] | <code>boolean</code> | set to true if the popup manages focus restore on close |
+| [options.closeCurrentPopups] | <code>boolean</code> | set to true if you want to dismiss all exiting popups before              adding this. Useful when this should be the only popup visible. |
 
 <a name="removePopUp"></a>
 

src/brackets.js

@@ -138,6 +138,7 @@ define(function (require, exports, module) {
     require("language/JSONUtils");
     require("widgets/InlineMenu");
     require("thirdparty/tinycolor");
+    require("utils/LocalizationUtils");
 
     // DEPRECATED: In future we want to remove the global CodeMirror, but for now we
     // expose our required CodeMirror globally so as to avoid breaking extensions in the

src/utils/LocalizationUtils.js

@@ -19,15 +19,13 @@
  *
  */
 
-/**
- *  Utilities functions related to localization/i18n
- */
-define(function (require, exports, module) {
+// @INCLUDE_IN_API_DOCS
 
+define(function (require, exports, module) {
 
-    var Strings = require("strings");
+    const Strings = require("strings");
 
-    /*
+    /**
      * Converts a language code to its written name, if possible.
      * If not possible, the language code is simply returned.
      *
@@ -41,7 +39,41 @@ define(function (require, exports, module) {
         return i18n === undefined ? locale : i18n;
     }
 
+    const DATE_TIME_STYLE = {
+        FULL: "full",
+        LONG: "long",
+        MEDIUM: "medium",
+        SHORT: "short"
+    };
+
+    /**
+     * Formats a given date object into a locale-aware date and time string.
+     *
+     * @param {Date} [date] - The date object to format. If not provided, the current date and time will be used.
+     * @param {string} [lang] - Optional language code to use for formatting (e.g., 'en', 'fr').
+     *                          If not provided, defaults to the application locale or 'en'.
+     * @param {Object} [dateTimeFormat] - Optional object specifying the date and time formatting options.
+     *                                    Defaults to { dateStyle: 'medium', timeStyle: 'short' }.
+     * @param {string} [dateTimeFormat.dateStyle] - Specifies the date format style. One of: DATE_TIME_STYLE.*
+     * @param {string} [dateTimeFormat.timeStyle] - Specifies the time format style. One of: DATE_TIME_STYLE.*
+     * @returns {string} - The formatted date and time string (e.g., "Dec 24, 2024, 10:30 AM").
+     */
+    function getFormattedDateTime(date, lang, dateTimeFormat) {
+        if(!date){
+            date = new Date();
+        }
+        if(!dateTimeFormat){
+            dateTimeFormat = {
+                dateStyle: DATE_TIME_STYLE.MEDIUM,
+                timeStyle: DATE_TIME_STYLE.SHORT
+            };
+        }
+        return Intl.DateTimeFormat([lang || brackets.getLocale() || "en", "en"], dateTimeFormat).format(date);
+    }
 
     // Define public API
     exports.getLocalizedLabel = getLocalizedLabel;
+    exports.getFormattedDateTime = getFormattedDateTime;
+    // public constants
+    exports.DATE_TIME_STYLE = DATE_TIME_STYLE;
 });

test/UnitTestSuite.js

@@ -118,6 +118,7 @@ define(function (require, exports, module) {
     require("spec/TaskManager-integ-test");
     require("spec/Generic-integ-test");
     require("spec/spacing-auto-detect-integ-test");
+    require("spec/LocalizationUtils-test");
     // Integrated extension tests
     require("spec/Extn-InAppNotifications-integ-test");
     require("spec/Extn-RemoteFileAdapter-integ-test");

test/spec/LocalizationUtils-test.js

@@ -0,0 +1,140 @@
+/*
+ * GNU AGPL-3.0 License
+ *
+ * Copyright (c) 2021 - present core.ai . All rights reserved.
+ *
+ * This program is free software: you can redistribute it and/or modify it
+ * under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License
+ * for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see https://opensource.org/licenses/AGPL-3.0.
+ *
+ */
+
+/*global describe, it, expect*/
+
+define(function (require, exports, module) {
+    const LocalizationUtils = require("utils/LocalizationUtils");
+
+    describe("unit:LocalizationUtils", function () {
+
+        describe("getFormattedDateTime", function () {
+            it("should format date in default locale", function () {
+                const testDate = new Date(2024, 0, 1, 13, 30); // Jan 1, 2024, 1:30 PM
+                const formatted = LocalizationUtils.getFormattedDateTime(testDate);
+                expect(formatted).toMatch(/Jan(uary)? 1, 2024/);
+                expect(formatted).toMatch(/1:30 PM/);
+            });
+
+            it("should format date in specified locale fr", function () {
+                const testDate = new Date(2024, 0, 1, 13, 30); // Jan 1, 2024, 1:30 PM
+                const formatted = LocalizationUtils.getFormattedDateTime(testDate, "fr");
+                // Explicit check for French date and time format
+                expect(formatted).toBe("1 janv. 2024, 13:30");
+            });
+
+            it("should format in de locale", function () {
+                const testDate = new Date(2024, 0, 1, 13, 30); // Jan 1, 2024, 1:30 PM
+                const formatted = LocalizationUtils.getFormattedDateTime(testDate, "de"); // German
+                expect(formatted).toMatch(/01.01.2024, 13:30/);
+            });
+
+            it("should fallback to default locale if invalid locale specified", function () {
+                const testDate = new Date(2024, 0, 1, 13, 30); // Jan 1, 2024, 1:30 PM
+                const formatted = LocalizationUtils.getFormattedDateTime(testDate, "invalid-locale");
+                // Should still format in a valid way
+                expect(formatted).toBeTruthy();
+                expect(formatted.length).toBeGreaterThan(0);
+            });
+
+            it("should handle empty date input gracefully", function () {
+                const formattedNow = LocalizationUtils.getFormattedDateTime(); // No date provided
+                const now = new Date();
+                const expected = new Intl.DateTimeFormat('en', {
+                    dateStyle: 'medium',
+                    timeStyle: 'short'
+                }).format(now);
+
+                expect(formattedNow).toBe(expected);
+            });
+
+            it("should handle edge case dates", function () {
+                const epochDate = new Date(0); // Unix epoch
+                const formattedEpoch = LocalizationUtils.getFormattedDateTime(epochDate);
+                expect(formattedEpoch).toBeTruthy();
+
+                const farFutureDate = new Date(3000, 0, 1, 0, 0); // Jan 1, 3000
+                const formattedFuture = LocalizationUtils.getFormattedDateTime(farFutureDate);
+                expect(formattedFuture).toBeTruthy();
+            });
+
+            it("should correctly format using non-Latin locales", function () {
+                const testDate = new Date(2024, 0, 1, 13, 30); // Jan 1, 2024, 1:30 PM
+                const formatted = LocalizationUtils.getFormattedDateTime(testDate, "ja"); // Japanese
+                expect(formatted).toBe("2024/01/01 13:30");
+            });
+
+            it("should format using a custom dateStyle and timeStyle (FULL)", function () {
+                const testDate = new Date(2024, 0, 1, 13, 30); // Jan 1, 2024, 1:30 PM
+                const customFormat = {
+                    dateStyle: LocalizationUtils.DATE_TIME_STYLE.FULL,
+                    timeStyle: LocalizationUtils.DATE_TIME_STYLE.FULL
+                };
+                const formatted = LocalizationUtils.getFormattedDateTime(testDate, "en", customFormat);
+                // Example format: "Monday, January 1, 2024 at 1:30:00 PM GMT+1"
+                expect(formatted).toMatch(/Monday, January 1, 2024/);
+                expect(formatted).toMatch(/1:30:00 PM/);
+            });
+
+            it("should format using only dateStyle (SHORT)", function () {
+                const testDate = new Date(2024, 0, 1, 13, 30); // Jan 1, 2024, 1:30 PM
+                const customFormat = {
+                    dateStyle: LocalizationUtils.DATE_TIME_STYLE.SHORT
+                };
+                const formatted = LocalizationUtils.getFormattedDateTime(testDate, "en", customFormat);
+                // Example format: "1/1/24"
+                expect(formatted).toBe("1/1/24");
+            });
+
+            it("should format using only timeStyle (LONG)", function () {
+                const testDate = new Date(2024, 0, 1, 13, 30); // Jan 1, 2024, 1:30 PM
+                const customFormat = {
+                    timeStyle: LocalizationUtils.DATE_TIME_STYLE.LONG
+                };
+                const formatted = LocalizationUtils.getFormattedDateTime(testDate, "en", customFormat);
+                // Example format: "1:30:00 PM GMT+1"
+                expect(formatted).toMatch(/1:30:00 PM/);
+            });
+
+            it("should respect custom dateTimeFormat and locale", function () {
+                const testDate = new Date(2024, 0, 1, 13, 30); // Jan 1, 2024, 1:30 PM
+                const customFormat = {
+                    dateStyle: LocalizationUtils.DATE_TIME_STYLE.LONG,
+                    timeStyle: LocalizationUtils.DATE_TIME_STYLE.SHORT
+                };
+                const formatted = LocalizationUtils.getFormattedDateTime(testDate, "fr", customFormat);
+                // Example format: "1 janvier 2024 à 13:30"
+                expect(formatted).toBe("1 janvier 2024 à 13:30");
+            });
+
+            it("should default to current date with custom dateTimeFormat", function () {
+                const customFormat = {
+                    dateStyle: LocalizationUtils.DATE_TIME_STYLE.MEDIUM,
+                    timeStyle: LocalizationUtils.DATE_TIME_STYLE.MEDIUM
+                };
+                const formattedNow = LocalizationUtils.getFormattedDateTime(undefined, "en", customFormat); // No date provided
+                const now = new Date();
+                const expected = new Intl.DateTimeFormat("en", customFormat).format(now);
+
+                expect(formattedNow).toBe(expected);
+            });
+        });
+    });
+});