feat(useColorMode): add option to return auto mode (#1627)

Co-authored-by: Anthony Fu <anthonyfu117@hotmail.com>
Co-authored-by: dfreier <stone_stabiler.0x@icloud.com>

packages/core/useColorMode/component.ts

@@ -4,7 +4,7 @@ import { useColorMode } from '.'
 
 export const UseColorMode = defineComponent<UseColorModeOptions>({
   name: 'UseColorMode',
-  props: ['selector', 'attribute', 'modes', 'onChanged', 'storageKey', 'storage'] as unknown as undefined,
+  props: ['selector', 'attribute', 'modes', 'onChanged', 'storageKey', 'storage', 'emitAuto'] as unknown as undefined,
   setup(props, { slots }) {
     const mode = useColorMode(props)
     const data = reactive({

packages/core/useColorMode/demo.vue

@@ -2,13 +2,14 @@
 import { useColorMode, useCycleList } from '@vueuse/core'
 
 const mode = useColorMode({
+  emitAuto: true,
   modes: {
     contrast: 'dark contrast',
     cafe: 'cafe',
   },
 })
 
-const { next } = useCycleList(['dark', 'light', 'cafe', 'contrast'], { initialValue: mode })
+const { next } = useCycleList(['dark', 'light', 'cafe', 'contrast', 'auto'], { initialValue: mode })
 </script>
 
 <template>
@@ -17,6 +18,7 @@ const { next } = useCycleList(['dark', 'light', 'cafe', 'contrast'], { initialVa
     <i v-if="mode === 'light'" i-carbon-sun inline-block align-middle class="align-middle" />
     <i v-if="mode === 'cafe'" i-carbon-cafe inline-block align-middle class="align-middle" />
     <i v-if="mode === 'contrast'" i-carbon-contrast inline-block align-middle class="align-middle" />
+    <i v-if="mode === 'auto'" i-carbon-laptop inline-block align-middle class="align-middle" />
 
     <span class="ml-2 capitalize">{{ mode }}</span>
   </button>

packages/core/useColorMode/index.md

@@ -18,7 +18,7 @@ import { useColorMode } from '@vueuse/core'
 const mode = useColorMode() // Ref<'dark' | 'light'>
 ```
 
-By default, it will match with users' browser preference using `usePreferredDark` (a.k.a `auto` mode). When reading the ref, it will always return the current color mode (`dark`, `light` or your custom modes). When writing to the ref, it will trigger DOM updates and persist the color mode to local storage (or your custom storage). You can pass `auto` to set back to auto mode.
+By default, it will match with users' browser preference using `usePreferredDark` (a.k.a `auto` mode). When reading the ref, it will by default return the current color mode (`dark`, `light` or your custom modes). The `auto` mode can be included in the returned modes by enabling the `emitAuto` option. When writing to the ref, it will trigger DOM updates and persist the color mode to local storage (or your custom storage). You can pass `auto` to set back to auto mode.
 
 ```ts
 mode.value // 'dark' | 'light'

packages/core/useColorMode/index.test.ts

@@ -0,0 +1,16 @@
+import { expect } from 'vitest'
+import { useColorMode } from '.'
+
+describe('useColorMode', () => {
+  it('should translate auto mode', () => {
+    const mode = useColorMode()
+    mode.value = 'auto'
+    expect(mode.value).toBe('light')
+  })
+
+  it('should include auto mode', () => {
+    const mode = useColorMode({ emitAuto: true })
+    mode.value = 'auto'
+    expect(mode.value).toBe('auto')
+  })
+})

packages/core/useColorMode/index.ts

@@ -60,6 +60,16 @@ export interface UseColorModeOptions<T extends string = BasicColorSchema> extend
    * @default localStorage
    */
   storage?: StorageLike
+
+  /**
+   * Emit `auto` mode from state
+   *
+   * When set to `true`, preferred mode won't be translated into `light` or `dark`.
+   * This is useful when the fact that `auto` mode was selected needs to be known.
+   *
+   * @default undefined
+   */
+  emitAuto?: boolean
 }
 
 /**
@@ -77,6 +87,7 @@ export function useColorMode<T extends string = BasicColorSchema>(options: UseCo
     storageKey = 'vueuse-color-scheme',
     listenToStorageChanges = true,
     storageRef,
+    emitAuto,
   } = options
 
   const modes = {
@@ -95,7 +106,7 @@ export function useColorMode<T extends string = BasicColorSchema>(options: UseCo
 
   const state = computed<T | BasicColorSchema>({
     get() {
-      return store.value === 'auto'
+      return store.value === 'auto' && !emitAuto
         ? preferredMode.value
         : store.value
     },