feat(useIsDarkTheme): add useIsDarkTheme composable

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

docs/composables/useIsDarkTheme.md

@@ -0,0 +1,70 @@
+<!--
+  - SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+  - SPDX-License-Identifier: AGPL-3.0-or-later
+-->
+
+```ts static
+import {
+    useIsDarkTheme,
+    useIsDarkThemeElement,
+} from '@nextcloud/vue/dist/Composables/useIsDarkTheme.js'
+```
+
+Same as `isDarkTheme` functions, but with reactivity.
+
+## Definition
+
+```ts static
+/**
+ * Check whether the dark theme is enabled in Nextcloud on a specific element.
+ * If you need to check a whole page, use `useIsDarkTheme` instead.
+ *
+ * @param el - the element to check for the dark theme enabled on
+ * @return {ComputedRef<boolean>} - computed boolean whether the dark theme is enabled
+ */
+declare function useIsDarkThemeElement(el: MaybeRef<HTMLElement> = document.body): ComputedRef<boolean>
+
+/**
+ * Shared composable to check whether the dark theme is enabled in Nextcloud
+ *
+ * @return {ComputedRef<boolean>} - computed boolean whether the dark theme is enabled
+ */
+declare function useIsDarkTheme(): ComputedRef<boolean>
+```
+
+## Example
+
+```vue
+<template>
+    <div>
+        Is dark theme enabled? {{ isDarkTheme }}
+        <NcButton type="tertiary" @click="switchTheme">Switch theme</NcButton>
+    </div>
+</template>
+
+<script>
+export default {
+    setup() {
+        const isDarkTheme = useIsDarkTheme()
+
+        // For documentation only. Do not use in production.
+        const switchTheme = () => {
+            if (isDarkTheme.value) {
+                document.body.setAttribute('data-theme-light')
+                document.body.removeAttribute('data-theme-dark')
+                document.body.setAttribute('data-themes', 'light')
+            } else {
+                document.body.setAttribute('data-theme-dark')
+                document.body.removeAttribute('data-theme-light')
+                document.body.setAttribute('data-themes', 'dark')
+            }
+        }
+
+        return {
+            isDarkTheme,
+            switchTheme,
+        }
+    },
+}
+</script>
+```

src/composables/index.js

@@ -6,3 +6,4 @@
 export * from './useIsFullscreen/index.js'
 export * from './useIsMobile/index.js'
 export * from './useFormatDateTime.ts'
+export * from './useIsDarkTheme/index.ts'

src/composables/useIsDarkTheme/index.ts

@@ -0,0 +1,32 @@
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+import { computed } from 'vue'
+import type { ComputedRef } from 'vue'
+import { useCssVar, createSharedComposable } from '@vueuse/core'
+import type { MaybeRef } from '@vueuse/core'
+
+/**
+ * Check whether the dark theme is enabled in Nextcloud on a specific element.
+ * If you need to check a whole page, use `useIsDarkTheme` instead.
+ *
+ * @param el - the element to check for the dark theme enabled on
+ * @return {ComputedRef<boolean>} - computed boolean whether the dark theme is enabled
+ */
+export function useIsDarkThemeElement(el: MaybeRef<HTMLElement> = document.body): ComputedRef<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
+	const backgroundInvertIfDark = useCssVar('--background-invert-if-dark', el)
+	return computed(() => backgroundInvertIfDark.value === 'invert(100%)')
+}
+
+/**
+ * Shared composable to check whether the dark theme is enabled in Nextcloud
+ *
+ * @return {ComputedRef<boolean>} - computed boolean whether the dark theme is enabled
+ */
+export const useIsDarkTheme = createSharedComposable(() => useIsDarkThemeElement())

styleguide.config.js

@@ -143,6 +143,17 @@ module.exports = async () => {
 					},
 				],
 			},
+			{
+				name: 'Composables',
+				content: 'docs/composables.md',
+				sectionDepth: 1,
+				sections: [
+					{
+						name: 'useIsDarkTheme',
+						content: 'docs/composables/useIsDarkTheme.md',
+					},
+				],
+			},
 			{
 				name: 'Components',
 				content: 'docs/components.md',

styleguide/global.requires.js

@@ -11,6 +11,7 @@ import usernameToColor from '../src/functions/usernameToColor/index.js'
 import Tooltip from './../src/directives/Tooltip/index.js'
 import Focus from './../src/directives/Focus/index.js'
 import Linkify from './../src/directives/Linkify/index.js'
+import { useIsDarkTheme } from '../src/composables/index.js'
 
 import axios from '@nextcloud/axios'
 
@@ -166,6 +167,8 @@ window.emojiAddRecent = emojiAddRecent
 window.getCurrentSkinTone = getCurrentSkinTone
 window.setCurrentSkinTone = setCurrentSkinTone
 window.usernameToColor = usernameToColor
+// Exported composables
+window.useIsDarkTheme = useIsDarkTheme
 
 // Directives
 Vue.directive('Tooltip', Tooltip)