From d67d90335c68554e6783834943d42999e80a39ae Mon Sep 17 00:00:00 2001
From: Dominik Freier <dfreier@users.noreply.github.com>
Date: Wed, 6 Jul 2022 05:09:15 +0200
Subject: [PATCH] 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  |  2 +-
 packages/core/useColorMode/demo.vue      |  4 +++-
 packages/core/useColorMode/index.md      |  2 +-
 packages/core/useColorMode/index.test.ts | 16 ++++++++++++++++
 packages/core/useColorMode/index.ts      | 13 ++++++++++++-
 5 files changed, 33 insertions(+), 4 deletions(-)
 create mode 100644 packages/core/useColorMode/index.test.ts

diff --git a/packages/core/useColorMode/component.ts b/packages/core/useColorMode/component.ts
index 13e54b25f75..34f6845abc3 100644
--- a/packages/core/useColorMode/component.ts
+++ b/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({
diff --git a/packages/core/useColorMode/demo.vue b/packages/core/useColorMode/demo.vue
index a8ce85ec26b..a571692f8ef 100644
--- a/packages/core/useColorMode/demo.vue
+++ b/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>
diff --git a/packages/core/useColorMode/index.md b/packages/core/useColorMode/index.md
index 1aca8ac0dd5..d9b7f93a4f6 100644
--- a/packages/core/useColorMode/index.md
+++ b/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'
diff --git a/packages/core/useColorMode/index.test.ts b/packages/core/useColorMode/index.test.ts
new file mode 100644
index 00000000000..549e5050f66
--- /dev/null
+++ b/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')
+  })
+})
diff --git a/packages/core/useColorMode/index.ts b/packages/core/useColorMode/index.ts
index 9fde2d75d2a..61a64bdcbb7 100644
--- a/packages/core/useColorMode/index.ts
+++ b/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
     },