@kolkrabbi/kol-framework 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-framework",
-  "version": "0.9.0",
+  "version": "0.10.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,7 +27,7 @@
     "app-shell"
   ],
   "dependencies": {
-    "@kolkrabbi/kol-component": "0.14.1",
+    "@kolkrabbi/kol-component": "0.14.3",
     "@kolkrabbi/kol-icons": "0.8.11"
   },
   "peerDependencies": {

package/src/PageSection.jsx

@@ -12,7 +12,10 @@ export default function PageSection({ id, label, title, body, children, classNam
     <section id={id} className={cls}>
       {divider && <Divider className="kol-page-section-divider" />}
       {hasHead && (
-        <header className={fullbleed ? 'max-w-[960px]' : 'max-w-[720px]'}>
+        /* head widths read the scale instead of transcribing it. `960px` was
+         * exactly the panel token; `720px` was an improvised near-miss and
+         * becomes the column token — 768px, so section heads widen by 48px. */
+        <header className={fullbleed ? 'max-w-[var(--kol-content-panel)]' : 'max-w-[var(--kol-content-column)]'}>
           {label && <p  className="kol-prose-label">{label}</p>}
           {title && <h2 className="kol-prose-title">{title}</h2>}
           {body  && <p  className="kol-prose-lede">{body}</p>}

package/src/SideNav.jsx

@@ -131,8 +131,10 @@ export default function SideNav({
   navTree = [],
   getActivePage,
   onNavigate,
-  collapsed: collapsedProp,
-  onToggle,
+  /* INERT since 0.9.2 — accepted so no call site breaks, but nothing reads
+   * them; the collapse feature they drove has no CSS. See below. */
+  collapsed: _collapsed,
+  onToggle: _onToggle,
   collapsibleSections = false,
   isActive,
 }) {
@@ -142,26 +144,15 @@ export default function SideNav({
   const onPageRoot = activePage && pathname === activePage.to
   const activeSectionId = useScrollSpy(onPageRoot ? sectionIds : [])
 
-  /* Root collapse: controlled when `collapsed` is defined (pair with
-   * onToggle), otherwise internal state. */
-  const isEditor = pathname.startsWith('/editor/')
-  const [internalCollapsed, setInternalCollapsed] = useState(isEditor)
-  const isControlled = collapsedProp !== undefined
-  const collapsed = isControlled ? collapsedProp : internalCollapsed
-  const handleToggle = isControlled ? onToggle : () => setInternalCollapsed((v) => !v)
-
-  useEffect(() => {
-    const root = document.documentElement
-    if (collapsed) root.setAttribute('data-sidenav', 'collapsed')
-    else root.removeAttribute('data-sidenav')
-  }, [collapsed])
-
-  /* /editor → collapsed. Anywhere else → expanded. Manual chevron toggle
-   * works for the session but doesn't persist across navigation.
-   * Skipped in controlled mode — the parent owns collapse. */
-  useEffect(() => {
-    if (!isControlled) setInternalCollapsed(isEditor)
-  }, [isEditor, isControlled])
+  /* The collapse state machine went with the button (finding #3). It stamped
+   * `data-sidenav="collapsed"` on <html> and an `is-collapsed` class on the
+   * aside, neither of which any stylesheet has read since 2026-07-29 — state
+   * with no renderer is just a lie the component tells itself.
+   *
+   * `collapsed` / `onToggle` are still ACCEPTED so no consumer's call site
+   * breaks; they are inert, and the prop docs say so. A consumer that wants a
+   * collapsing rail owns it locally (kol-website's apps/brand does exactly
+   * that) until the feature is deliberately rebuilt here. */
 
   /* Per-page section expand/collapse (opt-in via collapsibleSections).
    * The section containing the active route auto-expands on every
@@ -180,17 +171,16 @@ export default function SideNav({
 
   return (
     <aside
-      className={`kol-sidenav sticky top-0 self-start h-dvh flex flex-col border-r border-fg-08 z-20 bg-surface-primary${collapsed ? ' is-collapsed' : ''}${drawerOpen ? ' is-drawer-open' : ''}`}
+      className={`kol-sidenav sticky top-0 self-start h-dvh flex flex-col border-r border-fg-08 z-20 bg-surface-primary${drawerOpen ? ' is-drawer-open' : ''}`}
     >
-      <button
-        type="button"
-        className="kol-sidenav-toggle absolute top-5 right-[-12px] z-[2] w-6 h-6 inline-flex items-center justify-center bg-[var(--kol-surface-primary)] border border-[var(--kol-border-default)] rounded-full p-0 cursor-pointer kol-helper-14 transition-colors duration-150 text-meta hover:text-emphasis hover:border-fg-24"
-        aria-label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}
-        title={collapsed ? 'Expand' : 'Collapse'}
-        onClick={handleToggle}
-      >
-        <Icon name={collapsed ? 'chevron-right' : 'chevron-left'} size={12} />
-      </button>
+      {/* The collapse chevron was REMOVED 2026-07-30 (lobby ruling, finding
+        * #3). Its CSS — `:root[data-sidenav="collapsed"]` — was deleted
+        * 2026-07-29 when the manual-collapse feature was ruled dead, but the
+        * button, the `data-sidenav` stamp and the `is-collapsed` class all
+        * kept shipping, so every consumer of the package got a control that
+        * did nothing at all. Nothing styles any of it (see the tombstone at
+        * kol-framework.css:85). The surviving narrow mode is the responsive
+        * ≤1024px rail, which needs no control. */}
 
       <div className="kol-sidenav-scroll flex-1 flex flex-col justify-between overflow-y-auto pt-4 pb-4 [scrollbar-width:thin]">
         <ul className="kol-sidenav-tree flex flex-col gap-[2px]">

package/src/ThemeToggle.jsx

@@ -2,25 +2,29 @@ import { Icon } from '@kolkrabbi/kol-icons'
 import { useTheme } from './theme.js'
 
 /**
- * Theme toggle — tri-state glyph-roll button (0.9.0, the approved 2-variant spec).
+ * Theme toggle — two-position glyph-roll button (the approved 2-variant spec).
  *
- * 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 > light).
+ * Clicking cycles **light ↔ dark**. `system` is not a position — see the
+ * ruling above MODE_LABEL. Alt- or shift-click clears the choice and hands the
+ * page back to the OS (USER law: explicit choice > system > light).
  *
- * ONE glyph, ever (user ruling 2026-07-30): every position in the roll strip
- * is `mode-toggle-01`, the split circle — the system state wears it too, told
- * apart by the label / tooltip, never by a third glyph. The strip rolls like
- * a coin: rotation ACCUMULATES −180° per slot on the same 500ms clock as the
- * travel, so one lap shows both directions.
+ * ONE glyph, ever (user ruling 2026-07-30): both positions in the roll strip
+ * are `mode-toggle-01`, the split circle, told apart by the label / tooltip,
+ * never by a second glyph. The strip rolls like a coin: rotation ACCUMULATES
+ * −180° per slot on the same 500ms clock as the travel.
  *
  * THE SPEC (approved 2026-07-30 — variants are container GEOMETRY only;
  * everything else is a prop):
  *
  *   variant "button" — padded rung + corner radius (THE button container)
- *     fill       'subtle' | 'none'   the one bg element — subtle = grey fill
- *                                    (brand sidebar) · none = the invisible
- *                                    container (nav-bar chrome)
+ *     fill       'none' (default) | 'subtle'   the one bg element — none = the
+ *                                    invisible container (nav rows, sidebars,
+ *                                    chrome) · subtle = the grey filled rung,
+ *                                    for a toggle that IS a button on a page.
+ *                                    The old default was 'subtle' and its
+ *                                    docstring claimed the filled rung suited
+ *                                    the brand sidebar; the ruling withdrew
+ *                                    that — a sidebar row is not a button.
  *     iconRight  bool                glyph right of the text (left default)
  *     label      bool                text on/off — off pins the square box
  *                                    per rung (28/32/36; icon-only is a
@@ -44,30 +48,51 @@ import { useTheme } from './theme.js'
  * Theme state lives in useTheme (./theme.js); 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' }
-const SLOT = { dark: 0, light: 1, system: 2 }
+/* TWO positions (user ruling 2026-07-30, lobby/ThemeToggleSystemState.md):
+ *   "I see three states… dark mode system light mode, why the fuck is system
+ *    there, that is not a state."
+ *
+ * `system` is the ABSENCE of a choice — theme.js says so in its own words — so
+ * it can never be a labelled rung a click walks into. Promoting it made the
+ * control lie twice: it claimed a mode called "System", and it stopped being
+ * able to tell you what the next click would do, because from system the
+ * result depends on the OS.
+ *
+ * What ships now: the toggle cycles light ↔ dark and LABELS WHAT RENDERS. When
+ * the page is unset, the label reads the resolved theme (which is what the eye
+ * sees) and one click commits it. The reset lives behind a modifier — alt- or
+ * shift-click — which is the "separate affordance" the ruling allows, with no
+ * new chrome and no third stop. */
+const MODE_LABEL = { light: 'Light mode', dark: 'Dark mode' }
+const SLOT = { dark: 0, light: 1 }
 
 export default function ThemeToggle({
   variant = 'button',
-  fill = 'subtle',
+  /* DEFAULT FLIPPED subtle → none (user ruling 2026-07-30, finding #2): a bare
+   * <ThemeToggle /> was taking the grey filled rung, which is why the brand
+   * sidebar rendered a filled button nobody asked for. `none` is the quiet
+   * container — identical geometry, hover wash, no box. Consumers that want
+   * the fill now say so. */
+  fill = 'none',
   size = 'md',
   label = true,
   iconRight = false,
   fullWidth = false,
   className = '',
 }) {
-  const { mode, cycle } = useTheme()
+  const { theme, mode, cycle, clear } = useTheme()
 
-  const next = NEXT_MODE[mode]
-  const nextLabel = next === 'system' ? 'system theme' : `${next} mode`
+  /* Label and slot follow the RESOLVED theme, not the stored choice: when the
+   * page is unset, what the user is looking at is the OS's answer, and the
+   * button must describe that or it can't say what the next click does. */
+  const shown = theme === 'dark' ? 'dark' : 'light'
+  const next = shown === 'dark' ? 'light' : 'dark'
 
-  /* The ROLL — wheel mechanics (2026-07-30, one-glyph ruling): three copies
-   * of the split circle; rotation accumulates with the slot (−180° per
-   * glyph-width) on the same 500ms/ease clock as the strip's translateX.
-   * light→dark rolls one way, dark→system rolls back two half-turns,
-   * system→light forward again — both directions in one lap. */
-  const slot = SLOT[mode]
+  /* The ROLL — wheel mechanics (2026-07-30, one-glyph ruling): two copies of
+   * the split circle; rotation accumulates with the slot (−180° per
+   * glyph-width) on the same 500ms/ease clock as the strip's translateX, so
+   * light→dark rolls one way and dark→light rolls back. */
+  const slot = SLOT[shown]
   const iconSwap = (px) => (
     <span
       className="relative inline-block overflow-hidden"
@@ -76,9 +101,9 @@ export default function ThemeToggle({
     >
       <span
         className="flex transition-transform duration-500 ease-in-out"
-        style={{ width: px * 3, transform: `translateX(-${slot * px}px)` }}
+        style={{ width: px * 2, transform: `translateX(-${slot * px}px)` }}
       >
-        {[0, 1, 2].map((i) => (
+        {[0, 1].map((i) => (
           <span
             key={i}
             className="inline-flex transition-transform duration-500 ease-in-out"
@@ -97,11 +122,17 @@ export default function ThemeToggle({
   const glyphWithText = size === 'sm' ? 14 : size === 'lg' ? 18 : 16
   const glyphSolo = size === 'sm' ? 16 : size === 'lg' ? 24 : 20
 
+  /* alt/shift-click = the reset. A modifier, not a rung — the ruling's
+   * "separate affordance", costing no chrome and no third stop. Announced in
+   * the title so it's discoverable without being in the way. */
+  const onClick = (e) => (e.altKey || e.shiftKey ? clear() : cycle())
+  const resetHint = mode === 'system' ? ' · following your system' : ' · alt-click to follow your system'
+
   const shared = {
     type: 'button',
-    onClick: cycle,
-    'aria-label': `Switch to ${nextLabel}`,
-    title: `Switch to ${nextLabel}`,
+    onClick,
+    'aria-label': `Switch to ${next} mode`,
+    title: `Switch to ${next} mode${resetHint}`,
   }
 
   /* ── DEPRECATED aliases — old chrome verbatim (0.6.x) ── */
@@ -123,7 +154,7 @@ export default function ThemeToggle({
           {iconSwap(glyphSolo)}
         </span>
         <span className="kol-sidenav-hop-label flex-1 min-w-0 text-left">
-          {MODE_LABEL[mode]}
+          {MODE_LABEL[shown]}
         </span>
       </button>
     )
@@ -138,7 +169,7 @@ export default function ThemeToggle({
     return (
       <button {...shared} className={cls.replace(/\s+/g, ' ').trim()}>
         {!iconRight && iconSwap(glyph)}
-        {label && <span className={fullWidth ? 'flex-1 min-w-0 text-left' : ''}>{MODE_LABEL[mode]}</span>}
+        {label && <span className={fullWidth ? 'flex-1 min-w-0 text-left' : ''}>{MODE_LABEL[shown]}</span>}
         {iconRight && iconSwap(glyph)}
       </button>
     )
@@ -159,7 +190,7 @@ export default function ThemeToggle({
   return (
     <button {...shared} className={`kol-btn ${fillCls} kol-btn-${size} ${mono} gap-2 ${width} ${className}`.replace(/\s+/g, ' ').trim()}>
       {!iconRight && iconSwap(glyphWithText)}
-      <span className={fullWidth ? 'flex-1 min-w-0 text-left' : ''}>{MODE_LABEL[mode]}</span>
+      <span className={fullWidth ? 'flex-1 min-w-0 text-left' : ''}>{MODE_LABEL[shown]}</span>
       {iconRight && iconSwap(glyphWithText)}
     </button>
   )

package/src/theme.js

@@ -65,7 +65,8 @@ export function applyTheme(theme) {
  *   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)
+ *   cycle  — light ↔ dark (two positions; see the ruling at the call site)
+ *   clear  — hand the page back to the OS (what 'system' actually is)
  */
 export function useTheme() {
   const [state, setState] = useState(() =>
@@ -113,6 +114,14 @@ export function useTheme() {
     mode: state.mode,
     setTheme,
     toggle: () => setTheme(state.theme === 'dark' ? 'light' : 'dark'),
-    cycle: () => setTheme(state.mode === 'light' ? 'dark' : state.mode === 'dark' ? 'system' : 'light'),
+    /* light ↔ dark, TWO positions (user ruling 2026-07-30: "system … that is
+     * not a state"). `system` is the absence of a choice, so a click can land
+     * ON it only by resetting — never by cycling INTO it. From system, cycling
+     * commits the value the OS is currently resolving to, which is the one
+     * thing a user can predict from what they're looking at. */
+    cycle: () => setTheme(state.theme === 'dark' ? 'light' : 'dark'),
+    /* the reset — hands the page back to the OS. Kept as its own verb, not a
+     * rung, so no single click can walk into it. */
+    clear: () => setTheme('system'),
   }
 }