@kolkrabbi/kol-framework 0.4.1 → 0.5.0

package/kol-framework.css

@@ -630,6 +630,29 @@ code, pre {
   padding-top: 32px;
 }
 
+/* Filename chip — same scale as the lang chip; no text-transform (casing
+ * law: filenames render as authored). When both chips show, the lang chip
+ * yields the top-left slot and sits inboard of the copy button. */
+.kol-codeblock-filename {
+  position: absolute;
+  top: 8px;
+  left: 12px;
+  font-family: var(--kol-font-family-mono, monospace);
+  font-size: 10px;
+  font-weight: 600;
+  letter-spacing: 0.08em;
+  color: var(--kol-fg-40);
+}
+
+.kol-codeblock-filename ~ .kol-codeblock-lang {
+  left: auto;
+  right: 56px;
+}
+
+.kol-codeblock-filename + pre {
+  padding-top: 32px;
+}
+
 /* Positioning only — the chip look itself is the CopyButton atom
  * (.kol-copy-btn in kol-theme). */
 .kol-codeblock-copy {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-framework",
-  "version": "0.4.1",
+  "version": "0.5.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",
@@ -27,8 +27,8 @@
     "app-shell"
   ],
   "dependencies": {
-    "@kolkrabbi/kol-component": "0.10.0",
-    "@kolkrabbi/kol-icons": "0.6.0"
+    "@kolkrabbi/kol-component": "0.11.0",
+    "@kolkrabbi/kol-icons": "0.7.0"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",

package/src/ShellHeader.jsx

@@ -78,7 +78,7 @@ export default function ShellHeader({
                   onClick={onMenuClick}
                   aria-label="Open navigation menu"
                 >
-                  <Icon name="menu" size={18} />
+                  <Icon name="hamburger" size={18} />
                 </button>
               )}
             </div>
@@ -123,7 +123,7 @@ export default function ShellHeader({
                       onClick={onNavToggle}
                       aria-label="Toggle navigation sidebar"
                     >
-                      <Icon name="dock-left" size={18} />
+                      <Icon name="panel-left" size={18} />
                     </button>
                   )}
                   {onTocToggle && (

package/src/SideNav.jsx

@@ -73,7 +73,7 @@ function GroupNode({ group, basePath, activeSectionId, indent, onNavigate, isAct
   return (
     <li>
       <div
-        className={`kol-sidenav-group kol-helper-10 uppercase ${isAncestor ? 'text-emphasis' : 'text-subtle'}`}
+        className={`kol-sidenav-group kol-helper-10 ${isAncestor ? 'text-emphasis' : 'text-subtle'}`}
         style={{ paddingLeft: indent }}
       >
         {group.label}

package/src/SubPageHero.jsx

@@ -6,13 +6,13 @@ export default function SubPageHero({ backTo, backLabel, label, title, lede }) {
       {backTo && (
         <Link
           to={backTo}
-          className="kol-back-link kol-helper-12 uppercase tracking-widest text-body hover:text-emphasis no-underline"
+          className="kol-back-link kol-helper-12 tracking-widest text-body hover:text-emphasis no-underline"
         >
           {backLabel}
         </Link>
       )}
       {label && (
-        <p className="kol-helper-12 uppercase tracking-widest text-meta m-0 mb-4">
+        <p className="kol-helper-12 tracking-widest text-meta m-0 mb-4">
           {label}
         </p>
       )}

package/src/ThemeToggle.jsx

@@ -1,27 +1,5 @@
-import { useEffect, useState } from 'react'
 import { Icon } from '@kolkrabbi/kol-icons'
-
-const STORAGE_KEY = 'kol-theme'
-
-/* An explicit choice is an app-set data-theme attribute or a saved user
- * toggle. Absent both, the DS is light-first and follows the system
- * (prefers-color-scheme) — matching the theme CSS, which only darkens via
- * explicit [data-theme="dark"] or the media query. */
-function getExplicitTheme() {
-  const attr = document.documentElement.dataset.theme
-  if (attr === 'light' || attr === 'dark') return attr
-  try {
-    const saved = localStorage.getItem(STORAGE_KEY)
-    if (saved === 'light' || saved === 'dark') return saved
-  } catch { /* storage blocked */ }
-  return null
-}
-
-function getInitialTheme() {
-  if (typeof document === 'undefined') return 'light'
-  return getExplicitTheme()
-    ?? (window.matchMedia?.('(prefers-color-scheme: dark)')?.matches ? 'dark' : 'light')
-}
+import { useTheme } from './theme.js'
 
 /**
  * Theme toggle — horizontal icon-swap button.
@@ -37,50 +15,18 @@ function getInitialTheme() {
  *              bg, no hover bg). For sidenav rows where the row should read
  *              as plain text + icon, not a button.
  *
- * Self-contained but never imposing: initial state is the app-set
- * `data-theme` attribute, else the user's saved toggle (`kol-theme`), else
- * the system preference. `data-theme` + localStorage are written ONLY on a
- * user toggle — mounting the component leaves the DOM untouched, so an
- * undecided page keeps following prefers-color-scheme via the theme CSS.
+ * 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 animation slides a doubled `mode-toggle-01` (v1 set)
  * horizontally — the split-circle glyph makes the slide itself read as
  * the flip (same-icon slide, per design).
  */
 export default function ThemeToggle({ variant = 'icon', className = '' }) {
-  const [theme, setTheme] = useState(getInitialTheme)
-
-  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). */
-    const attr = document.documentElement.dataset.theme
-    let saved = null
-    try { saved = localStorage.getItem(STORAGE_KEY) } catch { /* storage blocked */ }
-    if (attr !== 'light' && attr !== 'dark') {
-      if (saved === 'light' || saved === 'dark') {
-        document.documentElement.dataset.theme = saved
-        return
-      }
-      /* No explicit choice anywhere — CSS follows the system on its own;
-       * this listener only keeps the toggle's icon in sync with it. */
-      const mq = window.matchMedia?.('(prefers-color-scheme: dark)')
-      if (!mq?.addEventListener) return
-      const onChange = (e) => {
-        try { if (localStorage.getItem(STORAGE_KEY)) return } catch { /* storage blocked */ }
-        setTheme(e.matches ? 'dark' : 'light')
-      }
-      mq.addEventListener('change', onChange)
-      return () => mq.removeEventListener('change', onChange)
-    }
-  }, [])
+  const { isDark, toggle } = useTheme()
 
-  const isDark = theme === 'dark'
   const next = isDark ? 'light' : 'dark'
-  const handleToggle = () => {
-    setTheme(next)
-    document.documentElement.dataset.theme = next
-    try { localStorage.setItem(STORAGE_KEY, next) } catch { /* storage blocked */ }
-  }
+  const handleToggle = toggle
 
   const iconSwap = (size) => (
     <span
@@ -123,16 +69,17 @@ export default function ThemeToggle({ variant = 'icon', className = '' }) {
     )
   }
 
-  // variant === 'icon' (default)
+  // variant === 'icon' (default) — 36×36 button / 20px glyph, the DS reference
+  // (user-verified 2026-07-15; was 32/18, which consumers shimmed via CSS)
   return (
     <button
       type="button"
       onClick={handleToggle}
       aria-label={`Switch to ${next} mode`}
       title={`Switch to ${next} mode`}
-      className={`inline-flex items-center justify-center w-8 h-8 p-0 bg-transparent border-0 cursor-pointer text-emphasis hover:opacity-80 transition-opacity duration-300 ${className}`.trim()}
+      className={`inline-flex items-center justify-center w-9 h-9 p-0 bg-transparent border-0 cursor-pointer text-emphasis hover:opacity-80 transition-opacity duration-300 ${className}`.trim()}
     >
-      {iconSwap(18)}
+      {iconSwap(20)}
     </button>
   )
 }

package/src/index.js

@@ -12,6 +12,7 @@ export { ShellTocContext, ShellTocCollapsedContext } from './AppShell.jsx'
 export { default as SideNav } from './SideNav.jsx'
 export { default as ShellHeader } from './ShellHeader.jsx'
 export { default as ThemeToggle } from './ThemeToggle.jsx'
+export { useTheme, applyTheme, getInitialTheme, THEME_STORAGE_KEY } from './theme.js'
 export { default as Layout } from './Layout.jsx'
 export { default as PageSection } from './PageSection.jsx'
 export { default as PortalFooter } from './PortalFooter.jsx'

package/src/theme.js

@@ -0,0 +1,91 @@
+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 (unchanged from ThemeToggle): the DS is
+ * light-first; an explicit choice is an app-set data-theme attribute or a
+ * saved user toggle, and absent both the page follows prefers-color-scheme
+ * via the theme CSS. `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'
+
+function getExplicitTheme() {
+  const attr = document.documentElement.dataset.theme
+  if (attr === 'light' || attr === 'dark') return attr
+  try {
+    const saved = localStorage.getItem(THEME_STORAGE_KEY)
+    if (saved === 'light' || saved === 'dark') return saved
+  } catch { /* storage blocked */ }
+  return null
+}
+
+export function getInitialTheme() {
+  if (typeof document === 'undefined') return 'light'
+  return getExplicitTheme()
+    ?? (window.matchMedia?.('(prefers-color-scheme: dark)')?.matches ? 'dark' : 'light')
+}
+
+/** Stamp + persist an explicit theme choice. */
+export function applyTheme(theme) {
+  document.documentElement.dataset.theme = theme
+  try { localStorage.setItem(THEME_STORAGE_KEY, theme) } catch { /* storage blocked */ }
+}
+
+/**
+ * useTheme — live theme state, synced across every consumer.
+ *
+ * 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, instances follow the
+ * system preference. Returns { theme, isDark, setTheme, toggle }.
+ */
+export function useTheme() {
+  const [theme, setThemeState] = useState(getInitialTheme)
+
+  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. */
+    const attr = document.documentElement.dataset.theme
+    let saved = null
+    try { saved = localStorage.getItem(THEME_STORAGE_KEY) } catch { /* storage blocked */ }
+    if (attr !== 'light' && attr !== 'dark' && (saved === 'light' || saved === 'dark')) {
+      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)
+    })
+    observer.observe(document.documentElement, { attributes: true, attributeFilter: ['data-theme'] })
+
+    /* No explicit choice anywhere — follow the system, like the theme CSS. */
+    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)
+    }
+  }, [])
+
+  const setTheme = (t) => {
+    setThemeState(t)
+    applyTheme(t)
+  }
+
+  return {
+    theme,
+    isDark: theme === 'dark',
+    setTheme,
+    toggle: () => setTheme(theme === 'dark' ? 'light' : 'dark'),
+  }
+}