@kolkrabbi/kol-framework 0.5.3 → 0.5.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-framework",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "description": "KOL app shell — sidenav, layout, theme toggle, footer, heroes + brand color layer. SideNav takes nav data as props so the tree stays app-local.",
   "license": "MIT",
   "type": "module",
@@ -27,8 +27,8 @@
     "app-shell"
   ],
   "dependencies": {
-    "@kolkrabbi/kol-component": "0.12.0",
-    "@kolkrabbi/kol-icons": "0.7.0"
+    "@kolkrabbi/kol-icons": "0.7.0",
+    "@kolkrabbi/kol-component": "0.12.0"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",

package/src/theme.js

@@ -2,12 +2,14 @@ import { useEffect, useState } from 'react'
 
 /* Theme-state machinery — the logic behind ThemeToggle, exported so app code
  * (navbars, heroes, anything theme-aware) can read/set the theme without
- * mounting the toggle UI. Policy: the DS is light-first (USER law, theme
- * 0.9.2 dropped the OS-follow auto-dark CSS); an explicit choice is an
- * app-set data-theme attribute or a saved user toggle, and absent both the
- * theme is light — never the OS preference, so state can't disagree with
- * what the CSS renders. `data-theme` + localStorage are written ONLY through
- * applyTheme (a user action) — mounting a reader leaves the DOM untouched. */
+ * mounting the toggle UI. Policy (USER law, corrected 2026-07-28):
+ * explicit choice > system/auto > light. An explicit choice is an app-set
+ * data-theme attribute or a saved user toggle; absent both, the theme
+ * follows prefers-color-scheme (the theme CSS ≥0.11.6 mirrors this via
+ * `:root:not([data-theme])`, so state and render agree); light is the
+ * last-resort fallback. A consumer stamps data-theme to veto the OS.
+ * `data-theme` + localStorage are written ONLY through applyTheme (a user
+ * action) — mounting a reader leaves the DOM untouched. */
 
 export const THEME_STORAGE_KEY = 'kol-theme'
 
@@ -23,7 +25,8 @@ function getExplicitTheme() {
 
 export function getInitialTheme() {
   if (typeof document === 'undefined') return 'light'
-  return getExplicitTheme() ?? 'light'
+  return getExplicitTheme()
+    ?? (window.matchMedia?.('(prefers-color-scheme: dark)')?.matches ? 'dark' : 'light')
 }
 
 /** Stamp + persist an explicit theme choice. */
@@ -37,8 +40,8 @@ export function applyTheme(theme) {
  *
  * All instances observe the html `data-theme` attribute, so any writer
  * (this hook's setTheme, ThemeToggle, an app boot script) updates every
- * reader. When the page has no explicit choice, the theme is light
- * (light-first law). Returns { theme, isDark, setTheme, toggle }.
+ * reader. When the page has no explicit choice, the theme follows the
+ * system (explicit > system > light). Returns { theme, isDark, setTheme, toggle }.
  */
 export function useTheme() {
   const [theme, setThemeState] = useState(getInitialTheme)
@@ -62,8 +65,19 @@ export function useTheme() {
     })
     observer.observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme'] })
 
+    /* No explicit choice anywhere — follow live OS switches, like the
+     * theme CSS's :root:not([data-theme]) block. */
+    const mq = window.matchMedia?.('(prefers-color-scheme: dark)')
+    const onChange = (e) => {
+      try { if (localStorage.getItem(THEME_STORAGE_KEY)) return } catch { /* storage blocked */ }
+      if (document.documentElement.dataset.theme) return
+      setThemeState(e.matches ? 'dark' : 'light')
+    }
+    mq?.addEventListener?.('change', onChange)
+
     return () => {
       observer.disconnect()
+      mq?.removeEventListener?.('change', onChange)
     }
   }, [])