feat: Dark mode API and config, fix #388 (#438

docs/reference/client.md

@@ -23,3 +23,27 @@ if (!isCollecting()) {
   // do something only in the browser
 }
 ```
+
+## `isDark`
+
+Returns `true` if dark mode is enabled.
+
+```js
+import { isDark } from 'histoire/client'
+
+if (isDark()) {
+  // do something only in dark mode
+}
+```
+
+## `toggleDark`
+
+`toggleDark(value?: boolean): boolean`
+
+Toggles dark mode. If `value` is provided, it will be used instead of toggling. Returns the new value.
+
+```js
+import { toggleDark } from 'histoire/client'
+
+toggleDark(true)
+```

docs/reference/config.md

@@ -110,6 +110,9 @@ Properties:
 - `favicon: string`: Href to the favicon file (**not** processed by Vite). Put the file in the `public` directory.
 - `colors: Object`: Customize the colors. Each color should be an object with shades as keys.
 - `logoHref: string`: Add a link to the main logo
+- `defaultColorScheme: 'light' | 'dark' | 'auto'`: Default color scheme for the app. `'auto'` will use the system preference.
+- `hideColorSchemeSwitch: boolean`: Hides the dark mode button in the toolbar.
+- `storeColorScheme: boolean`: Enable persistence of the color scheme in the browser's local storage.
 
 ```ts
 import { defaultColors } from 'histoire'
@@ -127,6 +130,9 @@ export default defineConfig({
       primary: defaultColors.cyan,
     },
     logoHref: 'https://acme.com',
+    defaultColorScheme: 'light',
+    hideColorSchemeSwitch: true,
+    storeColorScheme: false,
   },
 })
 ```

package.json

@@ -29,7 +29,7 @@
     "@typescript-eslint/parser": "^5.18.0",
     "@vue/eslint-config-standard": "^6.1.0",
     "@vue/eslint-config-typescript": "^10.0.0",
-    "@vueuse/core": "^8.2.5",
+    "@vueuse/core": "^9.12.0",
     "autoprefixer": "^10.4.4",
     "conventional-changelog-cli": "^2.2.2",
     "eslint": "^8.13.0",

packages/histoire-app/src/app/api.ts

@@ -1 +1,9 @@
+import { isDark as _isDark } from './util/dark.js'
+
 export { logEvent } from './util/events.js'
+
+export { toggleDark } from './util/dark.js'
+
+export function isDark () {
+  return _isDark.value
+}

packages/histoire-app/src/app/components/app/AppHeader.vue

@@ -50,6 +50,7 @@ onKeyboardShortcut(['ctrl+shift+d', 'meta+shift+d'], (event) => {
       </a>
 
       <a
+        v-if="!histoireConfig.theme.hideColorSchemeSwitch"
         v-tooltip="makeTooltip('Toggle dark mode', ({ isMac }) => isMac ? 'meta+shift+d' : 'ctrl+shift+d')"
         class="htw-p-2 sm:htw-p-1 hover:htw-text-primary-500 dark:hover:htw-text-primary-400 htw-cursor-pointer htw-text-gray-900 dark:htw-text-gray-100"
         @click="toggleDark()"

packages/histoire-app/src/app/util/dark.ts

@@ -1,7 +1,12 @@
 import { watch } from 'vue'
 import { useDark, useToggle } from '@vueuse/core'
+import { histoireConfig } from './config.js'
 
-export const isDark = useDark({ valueDark: 'htw-dark' })
+export const isDark = useDark({
+  valueDark: 'htw-dark',
+  initialValue: histoireConfig.theme.defaultColorScheme,
+  storageKey: histoireConfig.theme.storeColorScheme ? 'histoire-color-scheme' : null,
+})
 export const toggleDark = useToggle(isDark)
 
 function applyDarkToControls () {

packages/histoire-controls/package.json

@@ -55,7 +55,7 @@
     "@types/node": "^17.0.32",
     "@vitejs/plugin-vue": "^4.0.0",
     "@vue/test-utils": "^2.2.10",
-    "@vueuse/core": "^8.2.5",
+    "@vueuse/core": "^9.12.0",
     "autoprefixer": "^10.4.4",
     "concurrently": "^7.1.0",
     "floating-vue": "^2.0.0-beta.19",

packages/histoire-shared/src/types/config.ts

@@ -116,6 +116,18 @@ export interface HistoireConfig {
      * Add a link to the main logo
      */
     logoHref?: string
+    /**
+     * Default color scheme for the app.
+     */
+    defaultColorScheme?: 'light' | 'dark' | 'auto'
+    /**
+     * Hides the dark mode button in the toolbar.
+     */
+    hideColorSchemeSwitch?: boolean
+    /**
+     * Enable persistence of the color scheme in the browser.
+     */
+    storeColorScheme?: boolean
   }
   /**
    * Setup file exporting a default function executed when setting up each story preview.

packages/histoire-vendors/package.json

@@ -35,7 +35,7 @@
     "@rollup/plugin-commonjs": "^23.0.3",
     "@rollup/plugin-node-resolve": "^15.0.1",
     "@types/node": "^18.0.3",
-    "@vueuse/core": "^8.2.5",
+    "@vueuse/core": "^9.12.0",
     "execa": "^6.1.0",
     "floating-vue": "^2.0.0-beta.19",
     "fs-extra": "^10.0.1",

packages/histoire/client.d.ts

@@ -14,3 +14,6 @@ export function logEvent (name: string, argument): void
  * Returns `true` when in the NodeJS server while collecting stories.
  */
 export function isCollecting (): boolean
+
+export function toggleDark (value?: boolean): boolean
+export function isDark (): boolean

packages/histoire/src/node/config.ts

@@ -48,6 +48,8 @@ export function getDefaultConfig (): HistoireConfig {
         primary: defaultColors.emerald,
         gray: defaultColors.zinc,
       },
+      defaultColorScheme: 'auto',
+      storeColorScheme: true,
     },
     responsivePresets: [
       {