@kolkrabbi/kol-framework 0.5.12 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-framework",
-  "version": "0.5.12",
+  "version": "0.6.0",
   "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",

package/src/ThemeToggle.jsx

@@ -2,7 +2,14 @@ import { Icon } from '@kolkrabbi/kol-icons'
 import { useTheme } from './theme.js'
 
 /**
- * Theme toggle — horizontal icon-swap button.
+ * Theme toggle — horizontal icon-swap button, tri-state (0.6.0).
+ *
+ * Clicking CYCLES light → dark → system → light. 'system' is the no-choice
+ * state: the stamp + saved key are cleared and the page follows
+ * prefers-color-scheme live (USER law: explicit choice > system/auto > light).
+ * The glyph shows the current mode — the split-circle `mode-toggle-01` for
+ * light/dark (rolling + spinning exactly as before), the v1 `desktop` glyph
+ * for system.
  *
  * Variants:
  *   icon     — icon-only button on the DS button ladder: `size` 'sm'|'md'|'lg'
@@ -23,24 +30,26 @@ import { useTheme } from './theme.js'
  *
  * Theme state lives in useTheme (./theme.js) — the exported machinery
  * (initial-state resolution, saved-choice re-stamp, system-follow, cross-
- * instance sync). This component is only the icon-swap UI on top of it.
- * The icon-swap slides a doubled `mode-toggle-01` (v1 set) horizontally
- * while both glyphs spin 180° in the same clock — the split-circle rolls
- * forward (>>) on dark→light and rolls back (<<) on light→dark (the
- * original roll behavior, restored 2026-07-29).
+ * instance sync). This component is only the glyph-roll UI on top of it.
  */
+const MODE_LABEL = { light: 'Light mode', dark: 'Dark mode', system: 'System' }
+const NEXT_MODE = { light: 'dark', dark: 'system', system: 'light' }
+
 export default function ThemeToggle({ variant = 'icon', size = 'md', className = '' }) {
-  const { isDark, toggle } = useTheme()
+  const { isDark, mode, cycle } = useTheme()
 
-  const next = isDark ? 'light' : 'dark'
-  const handleToggle = toggle
+  const next = NEXT_MODE[mode]
+  const nextLabel = next === 'system' ? 'system theme' : `${next} mode`
+  const handleToggle = cycle
 
-  /* The roll: the strip slides one glyph-width while each glyph spins 180° in
-   * the same clock — dark→light rolls forward (>>), light→dark rolls back (<<). */
+  /* The roll: the strip slides one glyph-width per mode while the split-circle
+   * glyphs spin 180° in the same clock — dark→light rolls forward (>>),
+   * light→dark rolls back (<<), system slides on to the desktop glyph. */
   const glyphSpin = {
     transform: isDark ? 'rotate(0deg)' : 'rotate(180deg)',
     lineHeight: 0,
   }
+  const slot = mode === 'dark' ? 0 : mode === 'light' ? 1 : 2
   const iconSwap = (size) => (
     <span
       className="relative inline-block overflow-hidden"
@@ -49,7 +58,7 @@ export default function ThemeToggle({ variant = 'icon', size = 'md', className =
     >
       <span
         className="flex transition-transform duration-500 ease-in-out"
-        style={{ width: size * 2, transform: isDark ? 'translateX(0)' : `translateX(-${size}px)` }}
+        style={{ width: size * 3, transform: `translateX(-${slot * size}px)` }}
       >
         <span className="inline-flex transition-transform duration-500 ease-in-out" style={glyphSpin}>
           <Icon name="mode-toggle-01" size={size} />
@@ -57,22 +66,29 @@ export default function ThemeToggle({ variant = 'icon', size = 'md', className =
         <span className="inline-flex transition-transform duration-500 ease-in-out" style={glyphSpin}>
           <Icon name="mode-toggle-01" size={size} />
         </span>
+        <span className="inline-flex" style={{ lineHeight: 0 }}>
+          <Icon name="desktop" size={size} />
+        </span>
       </span>
     </span>
   )
 
   if (variant === 'button') {
     const mono = size === 'sm' ? 'kol-mono-12' : size === 'lg' ? 'kol-mono-16' : 'kol-mono-14'
-    const glyph = size === 'sm' ? 16 : size === 'lg' ? 24 : 20
+    /* Text-adjacent glyph law: the glyph must never exceed the rung's mono
+     * line box (16/18/22), or it inflates the button past the ladder height —
+     * playwright-measured against a same-rung kol-btn: 14/16/18 keeps them
+     * pixel-equal. (The 16/20/24 pairing law is for pinned icon-only squares.) */
+    const glyph = size === 'sm' ? 14 : size === 'lg' ? 18 : 16
     return (
       <button
         type="button"
         onClick={handleToggle}
-        aria-label={`Switch to ${next} mode`}
+        aria-label={`Switch to ${nextLabel}`}
         className={`kol-btn kol-btn-primary kol-btn-${size} ${mono} gap-2 ${className}`.trim()}
       >
         {iconSwap(glyph)}
-        <span>{isDark ? 'Dark mode' : 'Light mode'}</span>
+        <span>{MODE_LABEL[mode]}</span>
       </button>
     )
   }
@@ -86,7 +102,7 @@ export default function ThemeToggle({ variant = 'icon', size = 'md', className =
       <button
         type="button"
         onClick={handleToggle}
-        aria-label={`Switch to ${next} mode`}
+        aria-label={`Switch to ${nextLabel}`}
         className={`${chromeCls} ${className}`.trim()}
       >
         <span className="inline-flex items-center justify-center shrink-0" aria-hidden="true">
@@ -96,7 +112,7 @@ export default function ThemeToggle({ variant = 'icon', size = 'md', className =
          * at narrow viewports without subjecting the button to the muted
          * sidenav-hop text-color override. */}
         <span className="kol-sidenav-hop-label flex-1 min-w-0 text-left">
-          {isDark ? 'Dark mode' : 'Light mode'}
+          {MODE_LABEL[mode]}
         </span>
       </button>
     )
@@ -111,8 +127,8 @@ export default function ThemeToggle({ variant = 'icon', size = 'md', className =
     <button
       type="button"
       onClick={handleToggle}
-      aria-label={`Switch to ${next} mode`}
-      title={`Switch to ${next} mode`}
+      aria-label={`Switch to ${nextLabel}`}
+      title={`Switch to ${nextLabel}`}
       className={`kol-btn kol-btn-nav kol-btn-${size} kol-btn-icon ${className}`.trim()}
     >
       {iconSwap(glyph)}

package/src/theme.js

@@ -8,6 +8,11 @@ import { useEffect, useState } from 'react'
  * 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.
+ *
+ * Tri-state (0.6.0): `mode` is 'light' | 'dark' | 'system'. 'system' is the
+ * absence of an explicit choice — applyTheme('system') clears the stamp and
+ * the saved key, handing the page back to the OS. `theme` stays the RESOLVED
+ * value ('light'|'dark') so existing consumers keep working unchanged.
  * `data-theme` + localStorage are written ONLY through applyTheme (a user
  * action) — mounting a reader leaves the DOM untouched. */
 
@@ -23,14 +28,27 @@ function getExplicitTheme() {
   return null
 }
 
+/* One resolver for both axes: mode (the choice) + theme (what renders). */
+function resolveThemeState() {
+  const explicit = getExplicitTheme()
+  if (explicit) return { mode: explicit, theme: explicit }
+  const dark = window.matchMedia?.('(prefers-color-scheme: dark)')?.matches
+  return { mode: 'system', theme: dark ? 'dark' : 'light' }
+}
+
 export function getInitialTheme() {
   if (typeof document === 'undefined') return 'light'
-  return getExplicitTheme()
-    ?? (window.matchMedia?.('(prefers-color-scheme: dark)')?.matches ? 'dark' : 'light')
+  return resolveThemeState().theme
 }
 
-/** Stamp + persist an explicit theme choice. */
+/** Stamp + persist an explicit theme choice — or 'system' to clear both and
+ * hand the page back to prefers-color-scheme. */
 export function applyTheme(theme) {
+  if (theme === 'system') {
+    delete document.documentElement.dataset.theme
+    try { localStorage.removeItem(THEME_STORAGE_KEY) } catch { /* storage blocked */ }
+    return
+  }
   document.documentElement.dataset.theme = theme
   try { localStorage.setItem(THEME_STORAGE_KEY, theme) } catch { /* storage blocked */ }
 }
@@ -41,16 +59,26 @@ 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 follows the
- * system (explicit > system > light). Returns { theme, isDark, setTheme, toggle }.
+ * system (explicit > system > light).
+ * Returns { theme, isDark, mode, setTheme, toggle, cycle }:
+ *   theme  — resolved 'light' | 'dark' (what renders right now)
+ *   mode   — 'light' | 'dark' | 'system' (what is chosen)
+ *   setTheme(t) — stamp 'light'/'dark', or 'system' to follow the OS
+ *   toggle — binary light↔dark (always an explicit choice; kept for compat)
+ *   cycle  — light → dark → system → light (the tri-state control)
  */
 export function useTheme() {
-  const [theme, setThemeState] = useState(getInitialTheme)
+  const [state, setState] = useState(() =>
+    typeof document === 'undefined'
+      ? { mode: 'light', theme: 'light' }
+      : resolveThemeState()
+  )
 
   useEffect(() => {
     /* Re-stamp a previously saved user choice so persistence works in apps
      * with no theme boot script — but only when the app itself hasn't set
      * data-theme (an app-set attribute always wins over storage). Idempotent
-     * across instances. */
+     * across instances; the observer below picks the stamp up. */
     const attr = document.documentElement.dataset.theme
     let saved = null
     try { saved = localStorage.getItem(THEME_STORAGE_KEY) } catch { /* storage blocked */ }
@@ -58,38 +86,33 @@ export function useTheme() {
       document.documentElement.dataset.theme = saved
     }
 
-    /* Sync with any data-theme writer. */
-    const observer = new MutationObserver(() => {
-      const current = document.documentElement.dataset.theme
-      if (current === 'light' || current === 'dark') setThemeState(current)
-    })
+    /* One sync path for every writer: data-theme mutations (stamp OR removal)
+     * and live OS switches both re-resolve. resolveThemeState ignores the OS
+     * whenever an explicit choice exists, so the guards are inherent. */
+    const sync = () => setState(resolveThemeState())
+    const observer = new MutationObserver(sync)
     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)
+    mq?.addEventListener?.('change', sync)
 
+    sync()
     return () => {
       observer.disconnect()
-      mq?.removeEventListener?.('change', onChange)
+      mq?.removeEventListener?.('change', sync)
     }
   }, [])
 
   const setTheme = (t) => {
-    setThemeState(t)
     applyTheme(t)
+    setState(resolveThemeState())
   }
 
   return {
-    theme,
-    isDark: theme === 'dark',
+    theme: state.theme,
+    isDark: state.theme === 'dark',
+    mode: state.mode,
     setTheme,
-    toggle: () => setTheme(theme === 'dark' ? 'light' : 'dark'),
+    toggle: () => setTheme(state.theme === 'dark' ? 'light' : 'dark'),
+    cycle: () => setTheme(state.mode === 'light' ? 'dark' : state.mode === 'dark' ? 'system' : 'light'),
   }
 }