Add the UI toggle for changing theme

frontend/feat/feature-flags.json

@@ -31,22 +31,13 @@
       "supportsQuery": false,
       "storage": "session"
     },
-    "force_dark_mode": {
-      "status": {
-        "staging": "switchable",
-        "production": "disabled"
-      },
-      "defaultState": "off",
-      "description": "Force the site to render in dark mode.",
-      "storage": "session"
-    },
     "dark_mode_ui_toggle": {
       "status": {
         "staging": "switchable",
         "production": "disabled"
       },
       "defaultState": "off",
-      "description": "Display the UI toggle to change the site color theme.",
+      "description": "Display the UI toggle to change the site color theme and respect system preferences.",
       "storage": "cookie"
     }
   },

frontend/src/components/VFooter/VFooter.vue

@@ -7,11 +7,13 @@ import useResizeObserver from "~/composables/use-resize-observer"
 import { SCREEN_SIZES } from "~/constants/screens"
 
 import { useUiStore } from "~/stores/ui"
+import { useFeatureFlagStore } from "~/stores/feature-flag"
 
 import type { SelectFieldProps } from "~/components/VSelectField/VSelectField.vue"
 import VLink from "~/components/VLink.vue"
 import VBrand from "~/components/VBrand/VBrand.vue"
 import VLanguageSelect from "~/components/VLanguageSelect/VLanguageSelect.vue"
+import VThemeSelect from "~/components/VThemeSelect/VThemeSelect.vue"
 import VPageLinks from "~/components/VHeader/VPageLinks.vue"
 import VWordPressLink from "~/components/VHeader/VWordPressLink.vue"
 
@@ -25,6 +27,7 @@ export default defineComponent({
     VWordPressLink,
     VPageLinks,
     VLanguageSelect,
+    VThemeSelect,
     VLink,
     VBrand,
   },
@@ -50,6 +53,11 @@ export default defineComponent({
 
     const isContentMode = computed(() => props.mode === "content")
 
+    const featureFlagStore = useFeatureFlagStore()
+    const showThemeSwitcher = computed(() =>
+      featureFlagStore.isOn("dark_mode_ui_toggle")
+    )
+
     /** JS-based responsiveness */
     const footerEl = ref<HTMLElement | null>(null)
     const initialWidth = SCREEN_SIZES[uiStore.breakpoint]
@@ -76,6 +84,7 @@ export default defineComponent({
       isContentMode,
       allPages,
       currentPage,
+      showThemeSwitcher,
 
       footerEl,
       variantNames,
@@ -110,11 +119,23 @@ export default defineComponent({
 
     <!-- Locale chooser and WordPress affiliation graphic -->
     <div class="locale-and-wp flex flex-col justify-between">
-      <VLanguageSelect
-        v-bind="languageProps"
-        class="language max-w-full border-secondary"
-      />
-      <VWordPressLink mode="light" />
+      <template v-if="showThemeSwitcher">
+        <VWordPressLink mode="light" />
+        <div class="flex flex-row items-center gap-6">
+          <VLanguageSelect
+            v-bind="languageProps"
+            class="language max-w-full border-secondary"
+          />
+          <VThemeSelect class="border-secondary" />
+        </div>
+      </template>
+      <template v-else>
+        <VLanguageSelect
+          v-bind="languageProps"
+          class="language max-w-full border-secondary"
+        />
+        <VWordPressLink mode="light" />
+      </template>
     </div>
   </footer>
 </template>

frontend/src/components/VSelectField/VSelectField.vue

@@ -34,10 +34,12 @@ const props = withDefaults(
     fieldId: string
     labelText: string
     choices: Choice[]
+    showSelected?: boolean
   }>(),
   {
     modelValue: "",
     blankText: "",
+    showSelected: true,
   }
 )
 
@@ -85,8 +87,11 @@ const splitAttrs = computed(() => {
     <select
       :id="fieldId"
       v-model="selectValue"
-      class="flex h-[calc(theme(spacing.10)_-_2_*_theme(borderWidth.DEFAULT))] w-full appearance-none truncate bg-tx pe-10"
-      :class="hasStartContent ? 'ps-10' : 'ps-2'"
+      class="flex h-[calc(theme(spacing.10)_-_2_*_theme(borderWidth.DEFAULT))] appearance-none truncate bg-tx pe-10"
+      :class="[
+        showSelected ? 'w-full' : 'w-0',
+        hasStartContent ? 'ps-10' : 'ps-2',
+      ]"
       :name="fieldName"
       v-bind="splitAttrs.nonClassAttrs"
       :aria-label="labelText"

frontend/src/components/VThemeSelect/VThemeSelect.vue

@@ -0,0 +1,100 @@
+<!--
+Present users with a way to change the app theme between three options:
+light, dark and system.
+-->
+
+<script setup lang="ts">
+import { useI18n } from "#imports"
+
+import { computed, type ComputedRef } from "vue"
+import { usePreferredColorScheme } from "@vueuse/core"
+
+import { useUiStore } from "~/stores/ui"
+
+import VIcon from "~/components/VIcon/VIcon.vue"
+import VSelectField, {
+  type Choice,
+} from "~/components/VSelectField/VSelectField.vue"
+
+/**
+ * `ActualColorMode` is the evaluated form of `ColorMode`.
+ *
+ * It's value is the same as `ColorMode` for light and dark color modes
+ * but for the system color mode, it evaluates to either depending on
+ * the user's system theme.
+ */
+type ActualColorMode = "light" | "dark"
+
+const i18n = useI18n({ useScope: "global" })
+const uiStore = useUiStore()
+
+const THEME_ICON_NAME = Object.freeze({
+  light: "sun",
+  dark: "moon",
+})
+
+const THEME_TEXT = {
+  light: i18n.t(`theme.choices.light`),
+  dark: i18n.t(`theme.choices.dark`),
+}
+
+const colorMode = computed({
+  get: () => uiStore.colorMode,
+  set: (value) => {
+    uiStore.setColorMode(value)
+  },
+})
+
+/**
+ * Get the user's preferred color scheme at the OS level. If the user
+ * has not set an OS level preference, we fall back to light mode.
+ */
+const preferredColorScheme: ComputedRef<ActualColorMode> = computed(() => {
+  const pref = usePreferredColorScheme()
+  return pref.value === "no-preference" ? "light" : pref.value
+})
+
+/**
+ * Get the user's preferred color scheme at the app level. If the user
+ * has set the color mode to "system", we fall back to the OS level
+ * preference.
+ */
+const actualColorMode: ComputedRef<ActualColorMode> = computed(() =>
+  colorMode.value === "system" ? preferredColorScheme.value : colorMode.value
+)
+
+/**
+ * The icon always reflects the actual theme applied to the site.
+ * Therefore, it must be based on the value of `actualColorMode`.
+ */
+const currentThemeIcon = computed(() => THEME_ICON_NAME[actualColorMode.value])
+
+/**
+ * The choices are computed because the text for the color mode choice
+ * "system" is dynamic and reflects the user's preferred color scheme at
+ * the OS-level.
+ */
+const choices: ComputedRef<Choice[]> = computed(() => {
+  const systemText = `${i18n.t(`theme.choices.system`)} (${THEME_TEXT[preferredColorScheme.value]})`
+  return [
+    { key: "light", text: THEME_TEXT.light },
+    { key: "dark", text: THEME_TEXT.dark },
+    { key: "system", text: systemText },
+  ]
+})
+</script>
+
+<template>
+  <VSelectField
+    v-model="colorMode"
+    field-id="theme"
+    :choices="choices"
+    :blank-text="$t('theme.theme')"
+    :label-text="$t('theme.theme')"
+    :show-selected="false"
+  >
+    <template #start>
+      <VIcon :name="currentThemeIcon" />
+    </template>
+  </VSelectField>
+</template>

frontend/src/composables/use-dark-mode.ts

@@ -1,26 +1,44 @@
-import { computed } from "#imports"
+import { computed, useUiStore } from "#imports"
 
 import { useFeatureFlagStore } from "~/stores/feature-flag"
 
 export const DARK_MODE_CLASS = "dark-mode"
 export const LIGHT_MODE_CLASS = "light-mode"
 
 /**
- * TODO: Replace with the user's actual dark mode preference.
- * Dark mode detection will be based on user preference,
- * overwritten by the "force_dark_mode" feature flag.
+ * Determines the dark mode setting based on user preference or feature flag.
+ *
+ * When dark mode toggling is disabled, the site is in "light mode".
+ *
+ * When the "dark_mode_ui_toggle" flag is enabled, the site will respect
+ * the user system preference by default.
+ *
  */
 export function useDarkMode() {
+  const uiStore = useUiStore()
   const featureFlagStore = useFeatureFlagStore()
 
-  const isDarkMode = computed(() => featureFlagStore.isOn("force_dark_mode"))
-  const cssClass = computed(() =>
-    isDarkMode.value ? DARK_MODE_CLASS : LIGHT_MODE_CLASS
+  const darkModeToggleable = computed(() =>
+    featureFlagStore.isOn("dark_mode_ui_toggle")
   )
 
+  const colorMode = computed(() => {
+    if (darkModeToggleable.value) {
+      return uiStore.colorMode
+    }
+    return "light"
+  })
+
+  const cssClass = computed(() => {
+    return {
+      light: LIGHT_MODE_CLASS,
+      dark: DARK_MODE_CLASS,
+      system: "",
+    }[colorMode.value]
+  })
+
   return {
-    isDarkMode,
-    /** The CSS class representing the current color mode. */
+    colorMode,
     cssClass,
   }
 }

frontend/src/locales/scripts/en.json5

@@ -1085,6 +1085,14 @@
   language: {
     language: "Language",
   },
+  theme: {
+    theme: "Theme",
+    choices: {
+      dark: "Dark",
+      light: "Light",
+      system: "System",
+    },
+  },
   recentSearches: {
     heading: "Recent searches",
     clear: {

frontend/src/pages/preferences.vue

@@ -4,6 +4,7 @@ import { definePageMeta } from "#imports"
 import { computed } from "vue"
 
 import { useFeatureFlagStore } from "~/stores/feature-flag"
+import { isFlagName } from "~/types/feature-flag"
 import { SWITCHABLE, ON, OFF } from "~/constants/feature-flag"
 
 import VContentPage from "~/components/VContentPage.vue"
@@ -33,6 +34,9 @@ const handleChange = ({
   name: string
   checked?: boolean
 }) => {
+  if (!isFlagName(name)) {
+    return
+  }
   featureFlagStore.toggleFeature(name, checked ? ON : OFF)
 }
 

frontend/src/stores/feature-flag.ts

@@ -293,7 +293,7 @@ export const useFeatureFlagStore = defineStore(FEATURE_FLAG, {
      * @param name - the name of the flag to toggle
      * @param targetState - the desired state of the feature flag
      */
-    toggleFeature(name: string, targetState: FeatureState) {
+    toggleFeature(name: FlagName, targetState: FeatureState) {
       if (!isFlagName(name)) {
         throw new Error(`Toggling invalid feature flag: ${name}`)
       }
@@ -315,7 +315,7 @@ export const useFeatureFlagStore = defineStore(FEATURE_FLAG, {
       storage.value = this.flags.analytics.state === ON ? null : true
     },
 
-    isSwitchable(name: string) {
+    isSwitchable(name: FlagName) {
       if (!isFlagName(name)) {
         throw new Error(`Invalid feature flag accessed: ${name}`)
       }
@@ -328,7 +328,7 @@ export const useFeatureFlagStore = defineStore(FEATURE_FLAG, {
      *
      * @returns `true` if the flag is on, false otherwise
      */
-    isOn(name: string) {
+    isOn(name: FlagName) {
       if (!isFlagName(name)) {
         throw new Error(`Invalid feature flag accessed: ${name}`)
       }