From 21b0d39de02cebeb5bc00f67009dd218370bf9cc Mon Sep 17 00:00:00 2001
From: Jakub Zych <jakub@keios.eu>
Date: Fri, 16 Oct 2026 09:54:02 +0200
Subject: [PATCH] feat(quick-261016-0fm): manual theme switch on the rail

- the rail's top button cycles system, light and dark and names the
  current choice; light and dark ignore prefers-color-scheme
- usePreferences applies the cached theme before the first await of boot,
  saves the choice through PUT /account/preferences and reverts with a
  toast when the save fails; me() applies the stored preference
---
 admin/src/app/theme.ts                    |  31 ++++--
 admin/src/components/shell/PluginRail.vue |  23 +++-
 admin/src/main.ts                         |   8 +-
 admin/src/state/useAuth.ts                |   3 +
 admin/src/state/usePreferences.ts         | 124 ++++++++++++++++++++++
 admin/src/state/useSidebar.ts             |   7 +-
 docs/backend/admin-spa.md                 |   2 +
 7 files changed, 181 insertions(+), 17 deletions(-)
 create mode 100644 admin/src/state/usePreferences.ts

diff --git a/admin/src/app/theme.ts b/admin/src/app/theme.ts
index 8ba825a..76a851e 100644
--- a/admin/src/app/theme.ts
+++ b/admin/src/app/theme.ts
@@ -1,15 +1,32 @@
-// Colour scheme (D-06, flagged assumption A6): the admin follows the system
-// preference only, with no toggle. The .dark class on the document element
-// swaps the design's dark tokens in main.css; the sidebar stays dark in both
-// modes and gains its #222b40 right border in dark mode.
+// Colour scheme (D-06; assumption A6 superseded). The admin follows the
+// system preference by default; light and dark are manual choices the admin
+// makes on the rail's top button and keeps per account (usePreferences). The
+// .dark class on the document element swaps the design's dark tokens in
+// main.css; the sidebar stays dark in both modes and gains its #222b40 right
+// border in dark mode.
 export const DARK_QUERY = '(prefers-color-scheme: dark)'
 
+/** The admin's theme: follow the system, or always light or dark. */
+export type ThemeChoice = 'system' | 'light' | 'dark'
+
+/** The theme choices in the order the rail button cycles through them. */
+export const THEME_CHOICES: readonly ThemeChoice[] = ['system', 'light', 'dark']
+
+export function isThemeChoice(value: unknown): value is ThemeChoice {
+  return typeof value === 'string' && (THEME_CHOICES as readonly string[]).includes(value)
+}
+
 /**
- * Applies the current preference and follows changes. Returns the
- * unsubscribe function.
+ * Applies a theme choice. light and dark set the class once and subscribe
+ * to nothing; system applies the current preference and follows changes.
+ * Returns the unsubscribe function.
  */
-export function applyColorScheme(win: Window = window): () => void {
+export function applyColorScheme(win: Window = window, choice: ThemeChoice = 'system'): () => void {
   const root = win.document.documentElement
+  if (choice !== 'system') {
+    root.classList.toggle('dark', choice === 'dark')
+    return () => undefined
+  }
   if (typeof win.matchMedia !== 'function') {
     root.classList.remove('dark')
     return () => undefined
diff --git a/admin/src/components/shell/PluginRail.vue b/admin/src/components/shell/PluginRail.vue
index 14a1c48..8cb36fc 100644
--- a/admin/src/components/shell/PluginRail.vue
+++ b/admin/src/components/shell/PluginRail.vue
@@ -1,11 +1,12 @@
 <script setup lang="ts">
 import { computed, nextTick, onBeforeUnmount, ref, watch } from 'vue'
 import { RouterLink, useRoute } from 'vue-router'
-import { PanelLeftOpen, Settings, Sun } from '@lucide/vue'
+import { Moon, PanelLeftOpen, Settings, Sun, SunMoon } from '@lucide/vue'
 import { t } from '../../app/i18n'
 import { controllerIdFromPath } from '../../app/controllerRoutes'
 import { iconFor } from '../../app/icons'
 import { activeEntry, firstControllerPath, railEntries } from '../../state/useNavigation'
+import { cycleTheme, themeChoice } from '../../state/usePreferences'
 import { hasSettings, settingsLinkFor } from '../../state/useSettings'
 import { useSidebar } from '../../state/useSidebar'
 import SectionFlyout from './SectionFlyout.vue'
@@ -23,6 +24,13 @@ const FLYOUT_CLOSE_DELAY = 200
 const route = useRoute()
 const { collapsed, narrow, setCollapsed } = useSidebar()
 
+// The top button cycles the theme (system, light, dark) and names the
+// current choice; the icon shows it.
+const themeIcon = computed(() => ({ system: SunMoon, light: Sun, dark: Moon })[themeChoice.value])
+const themeLabel = computed(() =>
+  t('backend::lang.nav.theme', { mode: t(`backend::lang.nav.theme_${themeChoice.value}`) }),
+)
+
 const active = computed(() => activeEntry(String(route.params.vendor ?? ''), String(route.params.plugin ?? '')))
 
 // Ustawienia (D-21) is pinned to the bottom and shown only when the admin may
@@ -152,9 +160,16 @@ onBeforeUnmount(cancelClose)
     :aria-label="t('backend::lang.nav.plugins')"
     class="sticky top-0 flex h-screen w-rail shrink-0 flex-col items-center gap-1.5 self-start overflow-y-auto border-r border-side-border bg-side pt-3.5 pb-3"
   >
-    <span class="mb-3.5 flex size-10 items-center justify-center rounded-inner bg-accent-soft" title="SummerCMS">
-      <Sun :size="22" class="text-accent" aria-hidden="true" />
-    </span>
+    <button
+      type="button"
+      data-theme-toggle
+      :aria-label="themeLabel"
+      :title="themeLabel"
+      class="mb-3.5 flex size-10 shrink-0 items-center justify-center rounded-inner bg-accent-soft transition-colors duration-150 ease-out hover:bg-side-hover"
+      @click="cycleTheme"
+    >
+      <component :is="themeIcon" :size="22" class="text-accent" aria-hidden="true" />
+    </button>
     <RouterLink
       v-for="item in items"
       :key="item.entry.code"
diff --git a/admin/src/main.ts b/admin/src/main.ts
index 00ca70d..6105966 100644
--- a/admin/src/main.ts
+++ b/admin/src/main.ts
@@ -4,15 +4,17 @@ import { createAdminRouter } from './app/router'
 import { onUnauthorized } from './api/client'
 import { loadFieldTypes } from './app/fieldTypes'
 import { loadStrings } from './app/i18n'
-import { applyColorScheme } from './app/theme'
 import { expireSession, me } from './state/useAuth'
 import { loadNavigation } from './state/useNavigation'
+import { applyTheme, cachedTheme } from './state/usePreferences'
 import { loadSettings } from './state/useSettings'
 import './styles/main.css'
 
 async function boot(): Promise<void> {
-  // Dark mode follows the system preference before anything renders (A6).
-  applyColorScheme()
+  // The last theme choice (system unless the admin picked light or dark) is
+  // applied before the first await, so nothing renders in the wrong theme;
+  // me() then applies the admin's stored preference.
+  applyTheme(cachedTheme())
   // Boot order (research Pattern 7): the public strings bundle first, so the
   // login screen is translated, then the session, then navigation and the
   // plugin field types.
diff --git a/admin/src/state/useAuth.ts b/admin/src/state/useAuth.ts
index 4627329..f3ae6b0 100644
--- a/admin/src/state/useAuth.ts
+++ b/admin/src/state/useAuth.ts
@@ -5,6 +5,7 @@ import type { RouteLocationNormalizedLoaded, Router } from 'vue-router'
 import { api, onRefreshed, refreshSession } from '../api/client'
 import type { AdminProfile } from '../api/types'
 import { setListStateOwner } from './listState'
+import { applyProfilePreferences } from './usePreferences'
 import { setNavigation } from './useNavigation'
 import { setSettings } from './useSettings'
 
@@ -52,11 +53,13 @@ export async function login(identifier: string, password: string): Promise<boole
  * Loads the signed-in admin; null when the session is missing or expired.
  * The stored list queries follow the answer: a profile keeps only that
  * admin's (another admin's are removed, T-16.1-03), no profile removes all.
+ * The profile's UI preferences (theme) are applied before it returns.
  */
 export async function me(): Promise<AdminProfile | null> {
   const { data, response } = await api.GET('/auth/me')
   user.value = response.ok && data ? data.data : null
   setListStateOwner(user.value?.id ?? null)
+  await applyProfilePreferences(user.value)
   return user.value
 }
 
diff --git a/admin/src/state/usePreferences.ts b/admin/src/state/usePreferences.ts
new file mode 100644
index 0000000..afc8128
--- /dev/null
+++ b/admin/src/state/usePreferences.ts
@@ -0,0 +1,124 @@
+// The signed-in admin's UI preferences: the theme (system, light or dark).
+// The server keeps them per admin (GET /auth/me preferences, PUT
+// /account/preferences); the last choice is also cached in localStorage under
+// THEME_KEY, so boot applies it before the first await and the shell never
+// renders in the wrong theme. Only the choice's code is stored; tokens and
+// record data never are (T-261016-0fm-08).
+import { readonly, ref } from 'vue'
+import { api } from '../api/client'
+import type { AdminProfile } from '../api/types'
+import { t } from '../app/i18n'
+import { applyColorScheme, isThemeChoice, THEME_CHOICES, type ThemeChoice } from '../app/theme'
+import { showToast } from './useToasts'
+
+export const THEME_KEY = 'summer-admin.theme'
+
+const theme = ref<ThemeChoice>('system')
+let stopTheme: () => void = () => undefined
+
+/** The theme currently applied. */
+export const themeChoice = readonly(theme)
+
+function storage(): Storage | null {
+  try {
+    return typeof window === 'undefined' ? null : window.localStorage
+  } catch {
+    return null
+  }
+}
+
+function cache(key: string, value: string | null): void {
+  try {
+    if (value === null) {
+      storage()?.removeItem(key)
+    } else {
+      storage()?.setItem(key, value)
+    }
+  } catch {
+    // Storage may be full or disabled; the choice still holds for the session.
+  }
+}
+
+/** Caches a theme; system, the default, is stored as an absent key. */
+function cacheTheme(choice: ThemeChoice): void {
+  cache(THEME_KEY, choice === 'system' ? null : choice)
+}
+
+/** The cached theme when it is a valid choice, else system. */
+export function cachedTheme(): ThemeChoice {
+  try {
+    const value = storage()?.getItem(THEME_KEY)
+    return isThemeChoice(value) ? value : 'system'
+  } catch {
+    return 'system'
+  }
+}
+
+/** Applies a theme, replacing the previous one's media subscription. */
+export function applyTheme(choice: ThemeChoice): void {
+  stopTheme()
+  theme.value = choice
+  stopTheme = typeof window === 'undefined' ? () => undefined : applyColorScheme(window, choice)
+}
+
+/** The choice after current in the rail button's cycle. */
+export function nextTheme(current: ThemeChoice): ThemeChoice {
+  const index = THEME_CHOICES.indexOf(current)
+  return THEME_CHOICES[(index + 1) % THEME_CHOICES.length] ?? 'system'
+}
+
+/**
+ * Applies and caches a theme at once and saves it on the server. When the
+ * save fails the previous theme comes back and a danger toast says so.
+ */
+export async function setTheme(choice: ThemeChoice): Promise<void> {
+  const previous = theme.value
+  applyTheme(choice)
+  cacheTheme(choice)
+  let ok = false
+  try {
+    const { response } = await api.PUT('/account/preferences', { body: { theme: choice } })
+    ok = response.ok
+  } catch {
+    ok = false
+  }
+  if (ok) {
+    return
+  }
+  // A later click owns the theme now; only this request's choice is undone.
+  if (theme.value === choice) {
+    applyTheme(previous)
+    cacheTheme(previous)
+  }
+  showToast(t('backend::lang.myaccount.preferences_failed'), 'danger')
+}
+
+/** Moves to the next theme: system, light, dark, system. */
+export function cycleTheme(): Promise<void> {
+  return setTheme(nextTheme(theme.value))
+}
+
+/**
+ * Applies the preferences of a freshly loaded profile (boot and sign-in), so
+ * a second browser of the same admin shows the same theme.
+ */
+export async function applyProfilePreferences(profile: AdminProfile | null): Promise<void> {
+  const prefs = (profile as { preferences?: Partial<AdminProfile['preferences']> } | null)?.preferences
+  if (!prefs) {
+    return
+  }
+  if (isThemeChoice(prefs.theme)) {
+    if (prefs.theme !== theme.value) {
+      applyTheme(prefs.theme)
+    }
+    cacheTheme(prefs.theme)
+  }
+}
+
+export function usePreferences() {
+  return {
+    theme: themeChoice,
+    setTheme,
+    cycleTheme,
+  }
+}
diff --git a/admin/src/state/useSidebar.ts b/admin/src/state/useSidebar.ts
index 9bc6d56..c90d777 100644
--- a/admin/src/state/useSidebar.ts
+++ b/admin/src/state/useSidebar.ts
@@ -2,9 +2,10 @@
 // D-06, D-10). The section panel hides below about 1100px or when the admin
 // collapses it. The viewport only forces the collapse and never overwrites
 // the admin's own choice, which persists in localStorage as a boolean under
-// SIDEBAR_KEY. The only other writer of browser storage is listState.ts,
-// which keeps list query parameters per list; tokens and record data are
-// never stored (T-10-22, T-16.1-03).
+// SIDEBAR_KEY. The other writers of browser storage are listState.ts,
+// which keeps list query parameters per list, and usePreferences.ts, which
+// caches the theme and locale codes; tokens and record data are never stored
+// (T-10-22, T-16.1-03).
 import { computed, readonly, ref } from 'vue'
 
 export const SIDEBAR_KEY = 'summer-admin.sidebar'
diff --git a/docs/backend/admin-spa.md b/docs/backend/admin-spa.md
index 6d8b15e..d821321 100644
--- a/docs/backend/admin-spa.md
+++ b/docs/backend/admin-spa.md
@@ -35,6 +35,8 @@ A form whose schema carries `preview` has a read-only record screen at `<control
 
 The user menu in the top bar has a My account item that opens `<prefix>/account`. That screen edits the signed-in administrator's own first name, last name, email and subtitle, uploads and removes their avatar, shows the login read-only, changes the password when a new one is typed together with the current one, and manages personal API tokens (list, create with a show-once plaintext, revoke, show revoked). Server validation errors show on their fields, and a successful save updates the name and the avatar in the top bar without a reload. See [My account](users-and-permissions.md#my-account) and [API tokens](users-and-permissions.md#api-tokens).
 
+The button at the top of the plugin rail switches the theme: each click moves from system (follow the browser's `prefers-color-scheme`) to light, to dark and back to system, and its icon and label name the current choice. The choice is saved for the signed-in administrator through `PUT <prefix>/api/v1/account/preferences` and comes back as `preferences.theme` in `GET .../auth/me`, so another browser shows the same theme after sign-in. The SPA also caches the last choice in `localStorage` (`summer-admin.theme`) and applies it before anything renders. When the save fails the previous theme returns with an error message. See [My account](users-and-permissions.md#my-account).
+
 ## Types from OpenAPI
 
 The admin API is described by swag annotations in cabana. `scripts/check-admin-openapi.sh` generates the OpenAPI document (`admin/openapi/admin.json`) from them and the SPA's TypeScript types (`admin/src/api/schema.d.ts`) from the document, so the SPA's API client is checked against the server's shapes at compile time. Type overrides for swag live in the root `.swaggo` (it documents `json.RawMessage` as an untyped value, which swag cannot resolve on its own). `--check` fails when either committed file is out of date: