@bagelink/vue 1.15.104 → 1.15.106

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@bagelink/vue",
   "type": "module",
-  "version": "1.15.104",
+  "version": "1.15.106",
   "description": "Bagel core sdk packages",
   "author": {
     "name": "Bagel Studio",

package/src/composables/useTheme.ts

@@ -45,6 +45,14 @@ const isDark = ref(false)
  */
 const allowDark = ref(false)
 
+/**
+ * Whether this project lets the user manually pick a theme. When false (the
+ * default), the app always follows the OS ("system") and ignores any saved
+ * manual choice — so it updates live with the OS and never gets stuck on a
+ * stale dark/light value. When true, a saved manual choice is honored.
+ */
+const manualSelection = ref(false)
+
 const isBrowser = typeof window !== 'undefined'
 
 function getSystemPrefersDark() {
@@ -104,14 +112,38 @@ function toggleTheme() {
 /**
  * Configure theme behavior for the current app. Call once at startup.
  *
- * @param options.allowDark  Enable dark mode for this project (default: false).
- *                           When false, dark / system-dark falls back to light.
+ * @param options.allowDark         Enable dark mode for this project (default: false).
+ *                                  When false, dark / system-dark falls back to light.
+ * @param options.manualSelection   Whether this project exposes a UI for the user to
+ *                                  manually pick a theme (default: false).
+ *                                  - false → always follow the OS ("system"); any
+ *                                    previously-saved manual choice is ignored, so the
+ *                                    app updates live when the OS color scheme changes.
+ *                                  - true  → honor the user's saved manual choice, and
+ *                                    fall back to "system" when they haven't picked one.
  */
-export function configureTheme(options: { allowDark?: boolean } = {}) {
+export function configureTheme(options: { allowDark?: boolean, manualSelection?: boolean } = {}) {
 	if (options.allowDark !== undefined) {
 		allowDark.value = options.allowDark
 	}
-	// Re-apply with the new policy so a previously-saved dark choice is corrected.
+	if (options.manualSelection !== undefined) {
+		manualSelection.value = options.manualSelection
+	}
+
+	// Register the matchMedia listener + colorMode watcher now, so OS color-scheme
+	// changes are picked up live — even if no component ever calls useTheme()
+	// (e.g. projects with no manual theme switcher). Without this, "system" mode
+	// wouldn't react until something mounted, forcing a refresh.
+	initTheme()
+
+	// When the project has no manual switcher, force "system" — even if initTheme()
+	// already ran earlier (via useTheme) and restored a stale saved value before
+	// this config was known.
+	if (!manualSelection.value) {
+		colorMode.value = 'system'
+	}
+
+	// Re-apply with the new policy so a previously-saved choice is corrected.
 	applyTheme(colorMode.value)
 }
 
@@ -152,9 +184,15 @@ function initTheme() {
 	if (initialized || !isBrowser) { return }
 	initialized = true
 
-	const saved = window.localStorage.getItem(STORAGE_KEY)
-	if (themeOptions.value.some(t => t.value === saved)) {
-		colorMode.value = saved!
+	// Only restore a saved manual choice when the project allows manual selection.
+	// Otherwise always follow the OS, so the app can't get stuck on a stale value.
+	if (manualSelection.value) {
+		const saved = window.localStorage.getItem(STORAGE_KEY)
+		if (themeOptions.value.some(t => t.value === saved)) {
+			colorMode.value = saved!
+		}
+	} else {
+		colorMode.value = 'system'
 	}
 
 	applyTheme(colorMode.value)
@@ -166,9 +204,11 @@ function initTheme() {
 		}
 	})
 
-	// Persist + apply on mode changes
+	// Persist + apply on mode changes (persist only matters for manual selection)
 	watch(colorMode, (newMode) => {
-		localStorage.setItem(STORAGE_KEY, newMode)
+		if (manualSelection.value) {
+			localStorage.setItem(STORAGE_KEY, newMode)
+		}
 		applyTheme(newMode)
 	})
 }