feat(locale): add setTimezone & getTimezone functions

Signed-off-by: Sector6759 <149817326+Sector6759@users.noreply.github.com>

Author: Sector6759

lib/globals.d.ts

@@ -10,6 +10,7 @@ import type { PluralFunction, Translations } from './registry.ts'
 declare global {
 	var _nc_l10n_locale: string
 	var _nc_l10n_language: string
+	var _nc_l10n_timezone: string
 
 	var _oc_l10n_registry_translations: Record<string, Translations>
 	var _oc_l10n_registry_plural_functions: Record<string, PluralFunction>

lib/locale.ts

@@ -3,6 +3,8 @@
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
+import { getCapabilities } from '@nextcloud/capabilities'
+
 /**
  * Returns the user's locale
  */
@@ -57,6 +59,42 @@ export function setLanguage(lang: string): void {
 	}
 }
 
+/**
+ * Returns the user's timezone
+ *
+ * @since 3.5.0
+ */
+export function getTimezone(): string {
+	if (!globalThis._nc_l10n_timezone) {
+		let capabilities: undefined | { core?: { user?: { timezone?: string } } }
+		try {
+			capabilities = getCapabilities()
+		} catch {
+			// An error indicates getCapabilities threw due to no window object being present,
+			// which is the case when called outside of a browser runtime
+
+			// TODO: this try/catch block should be removed as soon as the @nextcloud/capabilities
+			// package has been updated to check for presence of the window object.
+			// Furthermore, everything except the return statement should be moved to the
+			// end of this file where the remaining global state is initialized.
+		}
+		globalThis._nc_l10n_timezone ??= capabilities?.core?.user?.timezone
+			|| Intl.DateTimeFormat().resolvedOptions().timeZone
+	}
+	return globalThis._nc_l10n_timezone
+}
+
+/**
+ * Set the current user's timezone (locally).
+ * This is to be used only for e.g. usage within web workers etc.
+ *
+ * @param timezone - The new timezone
+ * @since 3.5.0
+ */
+export function setTimezone(timezone: string): void {
+	globalThis._nc_l10n_timezone = timezone
+}
+
 /**
  * Check whether the current, or a given, language is read right-to-left
  *

package-lock.json

@@ -43,15 +43,16 @@
     "lint:fix": "eslint --fix lib tests",
     "prerelease:format-changelog": "node build/format-changelog.mjs",
     "test": "npm run test:dom && npm run test:node",
-    "test:coverage": "LANG=en-US vitest run --coverage",
-    "test:dom": "LANG=en-US vitest run",
-    "test:node": "LANG=en-US vitest run --environment node",
-    "test:watch": "LANG=en-US vitest watch"
+    "test:coverage": "LANG=en-US TZ=America/Chicago vitest run --coverage",
+    "test:dom": "LANG=en-US TZ=America/Chicago vitest run",
+    "test:node": "LANG=en-US TZ=America/Chicago vitest run --environment node",
+    "test:watch": "LANG=en-US TZ=America/Chicago vitest watch"
   },
   "browserslist": [
     "extends @nextcloud/browserslist-config"
   ],
   "dependencies": {
+    "@nextcloud/capabilities": "^1.2.1",
     "@nextcloud/router": "^3.1.0",
     "@nextcloud/typings": "^1.10.0",
     "@types/escape-html": "^1.0.4",

package.json

@@ -82,6 +82,27 @@ describe('getCanonicalLocale', () => {
 	})
 })
 
+describe('getTimezone', () => {
+	vi.spyOn(console, 'debug').mockImplementation(() => {})
+	it('returns the set timezone as it is', async () => {
+		mockTimezone('Europe/Berlin')
+		expect(await getTimezone()).toEqual('Europe/Berlin')
+	})
+
+	it('returns the environment timezone if no timezone is set', async () => {
+		mockTimezone(undefined)
+		expect(await getTimezone()).toEqual(process.env.TZ)
+	})
+})
+
+describe('setTimezone', () => {
+	it('sets the global state', async () => {
+		mockTimezone('Europe/Berlin')
+		await setTimezone('America/New_York')
+		expect(globalThis._nc_l10n_timezone).toBe('America/New_York')
+	})
+})
+
 async function getCanonicalLocale() {
 	const { getCanonicalLocale } = await import('../lib/locale.ts')
 	return getCanonicalLocale()
@@ -97,6 +118,11 @@ async function getLanguage() {
 	return getLanguage()
 }
 
+async function getTimezone() {
+	const { getTimezone } = await import('../lib/locale.ts')
+	return getTimezone()
+}
+
 async function setLocale(locale: string) {
 	const { setLocale } = await import('../lib/locale.ts')
 	return setLocale(locale)
@@ -107,6 +133,11 @@ async function setLanguage(language: string) {
 	return setLanguage(language)
 }
 
+async function setTimezone(timezone: string) {
+	const { setTimezone } = await import('../lib/locale.ts')
+	return setTimezone(timezone)
+}
+
 function mockLanguage(lang?: string) {
 	// @ts-expect-error - Mocking global state
 	globalThis._nc_l10n_language = lang
@@ -118,3 +149,7 @@ function mockLocale(locale?: string) {
 		delete globalThis.document.documentElement.dataset.locale
 	}
 }
+function mockTimezone(timezone?: string) {
+	// @ts-expect-error - Mocking global state
+	globalThis._nc_l10n_timezone = timezone
+}