feat(isDarkTheme): add isDarkTheme functions

Signed-off-by: Grigorii K. Shartsev <[email protected]>

docs/functions/isDarkTheme.md

@@ -0,0 +1,39 @@
+<!--
+  - SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+  - SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+```ts static
+import {
+    isDarkTheme,
+    checkIfDarkTheme,
+} from '@nextcloud/vue/dist/Functions/isDarkTheme.js'
+```
+
+Check whether the dark theme is enabled in Nextcloud. 
+
+You should not use `window.matchMedia.('(prefers-color-scheme: dark)')`. It checks for the user's system theme, but Nextcloud Dark theme could be enabled even on the light system theme.
+
+You should not use `[data-themes*=dark]` or `[data-theme-dark]` attributes on the body. It checks for explicitly set dark theme, but a user may use the system theme.
+
+## Definitions
+
+```ts static
+/**
+ * Check whether the dark theme is enabled in Nextcloud
+ *
+ * @param el - the element to check for the dark theme
+ * @return {boolean}
+ */
+declare function checkIfDarkTheme(el: HTMLElement = document.body): boolean;
+
+/**
+ * Whether the dark theme is enabled in Nextcloud.
+ * The variable is defined on page load and not reactive.
+ * Use `checkIfDarkTheme` if you need to check it at a specific moment.
+ * Use `useDarkTheme` if you need a reactive variable in a Vue component.
+ *
+ * @type {boolean}
+ */
+declare var isDarkTheme
+```

src/functions/index.js

@@ -6,4 +6,5 @@
 export * from './a11y/index.ts'
 export * from './emoji/index.ts'
 export * from './reference/index.js'
+export * from './isDarkTheme/index.ts'
 export { default as usernameToColor } from './usernameToColor/index.js'

src/functions/isDarkTheme/index.ts

@@ -0,0 +1,28 @@
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+/**
+ * Check whether the dark theme is enabled in Nextcloud
+ *
+ * @param el - the element to check for the dark theme
+ * @return {boolean}
+ */
+export function checkIfDarkTheme(el: HTMLElement = document.body): boolean {
+	// Nextcloud uses --background-invert-if-dark for dark theme filters in CSS
+	// Values:
+	// - 'invert(100%)' for the dark theme
+	// - 'no' for the light theme
+	return window.getComputedStyle(el).getPropertyValue('--background-invert-if-dark') === 'invert(100%)'
+}
+
+/**
+ * Whether the dark theme is enabled in Nextcloud.
+ * The variable is defined on page load and not reactive.
+ * Use `checkIfDarkTheme` if you need to check it at a specific moment.
+ * Use `useDarkTheme` if you need a reactive variable in a Vue component.
+ *
+ * @type {boolean}
+ */
+export const isDarkTheme = checkIfDarkTheme()

styleguide.config.js

@@ -125,6 +125,10 @@ module.exports = async () => {
 						name: 'emoji',
 						content: 'docs/functions/emoji.md',
 					},
+					{
+						name: 'isDarkTheme',
+						content: 'docs/functions/isDarkTheme.md',
+					},
 					{
 						name: 'usernameToColor',
 						content: 'docs/functions/usernameToColor.md',