@kolkrabbi/kol-framework 0.11.1 → 0.14.0

package/kol-framework.css

@@ -35,6 +35,14 @@ body {
      grid track that had to line up with it read 256, so the shell header's
      brand block sat 4 off the sidebar column it exists to align to. */
   --kol-sidenav-w: 16rem;
+  /* Grab-edge gesture (lobby: SideNavGrabResize, 2026-08-09). Minted HERE —
+     no --kol-* token carried these before (checked: only -w, -w-collapsed,
+     -dot-left shipped). kol-mirror carried them as bare literals, the
+     consumer-app slack the brief bans copying; both widths reference the
+     spacing ladder (the mirror strip's width lands on the ladder's first rung). */
+  --kol-sidenav-grab-w: var(--kol-spacing-1);  /* the strip's hit width */
+  --kol-sidenav-snap: 12rem;                   /* drag under this snaps to -w-collapsed */
+  --kol-sidenav-step: var(--kol-spacing-4);    /* keyboard resize increment */
   --kol-sidenav-w-collapsed: 56px;
   /* The workshop shell's RIGHT rail. EQUAL TO THE LEFT (user ruling
      2026-08-01) — the two rails frame the same content and a lopsided frame is
@@ -104,10 +112,36 @@ body {
  * said 1800 — same element, two answers (lobby/WidthSystemContradictions). */
 @media (min-width: 1920px) { :root { --kol-container-max: var(--kol-content-shell, 1800px); } }
 
-/* :root[data-sidenav="collapsed"] removed 2026-07-29 — the manual collapse
- * feature died with the editor's exit (brand ruling); the responsive rail
- * below 1024px is the surviving narrow mode. --kol-sidenav-w-collapsed stays:
- * the rail still uses it. */
+/* :root[data-sidenav="collapsed"] — the manual collapse, rebuilt DELIBERATELY
+ * 2026-08-09 (lobby: SideNavGrabResize) after the 2026-07-29 removal of the
+ * renderer-less stamp. SideNav's grab edge (useDragResize.js) owns the state
+ * now; these rules mirror the narrow mode below, so "collapsed" is that same
+ * rail — one look, two triggers. */
+:root[data-sidenav="collapsed"] .kol-brand-layout { grid-template-columns: var(--kol-sidenav-w-collapsed) minmax(0, 1fr); }
+:root[data-sidenav="collapsed"] .kol-sidenav-hops { padding: 0 0 var(--kol-spacing-4); margin-bottom: var(--kol-spacing-4); }
+:root[data-sidenav="collapsed"] .kol-sidenav-hop { padding: var(--kol-spacing-2) 0; justify-content: center; gap: 0; }
+:root[data-sidenav="collapsed"] .kol-sidenav-hop-label { display: none; }
+:root[data-sidenav="collapsed"] .kol-sidenav-body { display: none; }
+:root[data-sidenav="collapsed"] .kol-sidenav-hop-count,
+:root[data-sidenav="collapsed"] .kol-sidenav-section-toggle { display: none; }
+
+/* The grab edge itself — invisible by spec (col-resize cursor is the pointer
+ * affordance, the focus ring the keyboard one — recipe from
+ * .kol-btn:focus-visible, offset pulled inside because the strip hugs the
+ * layout edge). Positioning utilities ride inline in SideNav.jsx; the narrow
+ * mode hides the strip in its own block further down. */
+.kol-sidenav-grab {
+  width: var(--kol-sidenav-grab-w);
+  cursor: col-resize;
+}
+.kol-sidenav-grab:focus-visible {
+  outline: 2px solid var(--kol-focus-ring);
+  outline-offset: -2px;
+}
+/* Live drag writes --kol-sidenav-w per pointermove — the grid's ease below
+ * would render the rail a frame behind the pointer, so the drag suspends it
+ * (useDragResize stamps the attribute for the drag's duration). */
+:root[data-sidenav-dragging] .kol-brand-layout { transition: none; }
 
 /* ───── Brand doc layout (sidebar + content) ─────
    The grid lives in CSS for its dynamic --kol-sidenav-w + transition. */
@@ -123,10 +157,12 @@ body {
      User's localStorage expand preference is overridden while viewport is narrow;
      restored once they cross back over the threshold. */
   .kol-brand-layout { grid-template-columns: var(--kol-sidenav-w-collapsed) minmax(0, 1fr); }
-  .kol-sidenav-hops { padding: 0 0 16px; margin-bottom: 16px; }
-  .kol-sidenav-hop { padding: 8px 0; justify-content: center; gap: 0; }
+  .kol-sidenav-hops { padding: 0 0 var(--kol-spacing-4); margin-bottom: var(--kol-spacing-4); }
+  .kol-sidenav-hop { padding: var(--kol-spacing-2) 0; justify-content: center; gap: 0; }
   .kol-sidenav-hop-label { display: none; }
   .kol-sidenav-body { display: none; }
+  /* forced narrow / drawer modes own the rail below lg — no resize here */
+  .kol-sidenav-grab { display: none; }
 }
 
 @media (max-width: 767px) {
@@ -700,6 +736,10 @@ body {
   .kol-brand-layout[data-toc="true"] {
     grid-template-columns: var(--kol-sidenav-w) minmax(0, 1fr) var(--kol-toc-w);
   }
+  /* collapsed + TOC: the third column survives; only the rail track narrows */
+  :root[data-sidenav="collapsed"] .kol-brand-layout[data-toc="true"] {
+    grid-template-columns: var(--kol-sidenav-w-collapsed) minmax(0, 1fr) var(--kol-toc-w);
+  }
 }
 
 /* SideNav collapsibleSections chrome — inert unless that mode renders.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-framework",
-  "version": "0.11.1",
+  "version": "0.14.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.19.0",
-    "@kolkrabbi/kol-icons": "0.8.11"
+    "@kolkrabbi/kol-component": "0.24.0",
+    "@kolkrabbi/kol-icons": "0.10.0"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",

package/src/ShellHeader.jsx

@@ -1,5 +1,5 @@
 import { Icon } from '@kolkrabbi/kol-icons'
-import { SearchInput, Tooltip } from '@kolkrabbi/kol-component'
+import { IconFrame, SearchInput, Tooltip, glyphSize } from '@kolkrabbi/kol-component'
 import ThemeToggle from './ThemeToggle.jsx'
 
 /**
@@ -45,12 +45,32 @@ import ThemeToggle from './ThemeToggle.jsx'
 /* ONE header-action glyph size (user 2026-08-01: "icon in navbar is small and
  * wrong"). The row mixed sizes: the ThemeToggle draws its solo glyph at 24 on
  * the `lg` rung while search, GitHub and the hamburger sat at 18 — four
- * controls, two scales, in a row eight inches wide. Named once here so a new
- * control cannot pick its own. */
+ * controls, two scales, in a row eight inches wide.
+ *
+ * It is NOT an independent number. Every header control is a `lg` rung, and
+ * `SOLO.lg` (hooks/glyphLadders.js) is 24 — this constant is that ladder rung
+ * under a name the chrome can import. Naming it once was not enough on its own:
+ * it shipped exported and the two rail toggles still hardcoded 18 three rows
+ * below it, which is the whole reason the row looked wrong after the fix. The
+ * durable answer is that no header control writes a glyph size at all — it
+ * writes `size="lg"` and the ladder resolves it.
+ *
+ * @deprecated 2026-08-01 — **zero consumers as of this change.** Every header
+ * control now names its rung and takes the glyph from `SOLO`. Kept exported
+ * because it is public API of a published package (breaking an export needs a
+ * changeset + major bump); a consumer still importing it gets the right number,
+ * it is just no longer how the chrome decides. Passing it as `iconSize` is the
+ * anti-pattern this whole change removes: it pins the glyph while leaving the
+ * SQUARE on whatever rung the call site forgot to set, which is precisely how
+ * the search trigger ended up drawing an lg glyph in an md box. */
 export const HEADER_ICON = 24
 
-const iconBtnCls =
-  'flex h-9 w-9 items-center justify-center rounded p-0 bg-transparent border-0 cursor-pointer transition-colors hover:bg-fg-08 hover:text-emphasis'
+/* `iconBtnCls` lived here — a private class string re-implementing the icon
+ * button box (h-9 w-9, rounded, transparent, hover wash) on three call sites,
+ * with a near-duplicate of it hand-written in the showcase's GitHub link. Four
+ * containers, one job. Deleted 2026-08-01: the box has an owner, and it is
+ * `Button variant="ghost" quiet iconOnly` — the shape the search trigger in
+ * ShellLayout had been calling correctly the entire time. */
 
 export default function ShellHeader({
   brand,
@@ -93,19 +113,24 @@ export default function ShellHeader({
                     * quiet square = button geometry + fill none + no label
                     * (was the old `icon` variant default). */}
                   <span className="hidden lg:inline-flex"><ThemeToggle fill="none" label={false} size="lg" /></span>
-                  <span className="lg:hidden"><ThemeToggle fill="none" label={false} /></span>
+                  <span className="lg:hidden"><ThemeToggle fill="none" label={false} size="lg" /></span>
                 </Tooltip>
               )}
               {onMenuClick && (
                 <Tooltip label="Open navigation menu">
-                  <button
-                    type="button"
-                    className={`${iconBtnCls} text-fg-64`}
+                  {/* IconFrame, not Button (user ruling 2026-08-01). Header
+                    * chrome takes a click but must not light up; the frame has
+                    * no state rules at all, which is the property Button can
+                    * only approximate by dropping its own. `nav` rests at
+                    * oq-64 — the `text-fg-64` this control hand-wrote for
+                    * months. */}
+                  <IconFrame
+                    name="hamburger"
+                    variant="nav"
+                    size="lg"
                     onClick={onMenuClick}
                     aria-label="Open navigation menu"
-                  >
-                    <Icon name="hamburger" size={HEADER_ICON} />
-                  </button>
+                  />
                 </Tooltip>
               )}
             </div>
@@ -129,7 +154,12 @@ export default function ShellHeader({
                       aria-current={active ? 'page' : undefined}
                       onClick={onNavigate ? (event) => onNavigate(event, item) : undefined}
                     >
-                      {item.icon && <Icon name={item.icon} size={14} />}
+                      {/* The ladder, not a literal (2026-08-01). This hardcoded
+                        * 14 — the same value ADJACENT.sm carries, but written
+                        * out, so the tab could not follow the rule it was
+                        * meant to. The tab's own type is 14/18, which is that
+                        * rung. */}
+                      {item.icon && <Icon name={item.icon} size={glyphSize('sm')} />}
                       {item.label}
                     </a>
                   )
@@ -146,28 +176,32 @@ export default function ShellHeader({
                 <div className="hidden lg:flex items-center gap-1 pb-2">
                   {onNavToggle && (
                     <Tooltip label="Toggle navigation sidebar">
-                      <button
-                        type="button"
-                        className={`${iconBtnCls} ${navCollapsed ? 'text-fg-32' : 'text-fg-64'}`}
+                      {/* The collapsed tint is a VARIANT SWAP, not a state:
+                        * `ghost` rests at oq-48, `nav` at oq-64, and both are
+                        * static classes with no rules to fire. That is the only
+                        * honest way to express it on a frame — Button's `quiet`
+                        * is an opacity transition, i.e. exactly the kind of
+                        * behaviour this control was ruled out of. */}
+                      <IconFrame
+                        name="panel-left"
+                        variant={navCollapsed ? 'ghost' : 'nav'}
+                        size="sm"
                         onClick={onNavToggle}
                         aria-label="Toggle navigation sidebar"
                         aria-pressed={!navCollapsed}
-                      >
-                        <Icon name="panel-left" size={18} />
-                      </button>
+                      />
                     </Tooltip>
                   )}
                   {onTocToggle && (
                     <Tooltip label="Toggle table of contents sidebar">
-                      <button
-                        type="button"
-                        className={`${iconBtnCls} ${tocCollapsed ? 'text-fg-32' : 'text-fg-64'}`}
+                      <IconFrame
+                        name="panel-right"
+                        variant={tocCollapsed ? 'ghost' : 'nav'}
+                        size="sm"
                         onClick={onTocToggle}
                         aria-label="Toggle table of contents sidebar"
                         aria-pressed={!tocCollapsed}
-                      >
-                        <Icon name="panel-right" size={18} />
-                      </button>
+                      />
                     </Tooltip>
                   )}
                 </div>

package/src/SideNav.jsx

@@ -1,7 +1,8 @@
-import { useEffect, useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import { Link, NavLink, useLocation } from 'react-router-dom'
 import { Icon } from '@kolkrabbi/kol-icons'
 import ThemeToggle from './ThemeToggle'
+import useDragResize from './useDragResize'
 import { useScrollSpy } from '@kolkrabbi/kol-component'
 
 /* Walk the active page's children and return all leaf section ids (for scroll-spy). */
@@ -144,15 +145,14 @@ export default function SideNav({
   const onPageRoot = activePage && pathname === activePage.to
   const activeSectionId = useScrollSpy(onPageRoot ? sectionIds : [])
 
-  /* 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. */
+  /* Collapse, rebuilt DELIBERATELY 2026-08-09 (lobby: SideNavGrabResize) —
+   * the 2026-07-29/30 removals killed a stamp with no renderer; the grab edge
+   * below reinstates BOTH halves. useDragResize owns the state, stamps
+   * :root[data-sidenav="collapsed"], and kol-framework.css renders it again.
+   * `collapsed` / `onToggle` remain ACCEPTED-but-inert — the gesture is
+   * self-contained, so call sites still don't break. */
+  const asideRef = useRef(null)
+  const { grabProps } = useDragResize(asideRef)
 
   /* Per-page section expand/collapse (opt-in via collapsibleSections).
    * The section containing the active route auto-expands on every
@@ -171,16 +171,14 @@ export default function SideNav({
 
   return (
     <aside
+      ref={asideRef}
       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' : ''}`}
     >
-      {/* 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. */}
+      {/* The collapse chevron Button was REMOVED 2026-07-30 (lobby ruling,
+        * finding #3) as a control with no renderer. The grab edge at the end
+        * of this aside is its deliberate 2026-08-09 replacement — pointer-drag
+        * resizes, drag under --kol-sidenav-snap collapses, double-click and
+        * Home reset, arrows resize from the keyboard. See useDragResize.js. */}
 
       <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]">
@@ -267,6 +265,10 @@ export default function SideNav({
           <span className="text-meta group-hover:text-emphasis"> · {new Date().getFullYear()}</span>
         </a>
       </div>
+
+      {/* Grab edge — width/cursor/focus chrome in kol-framework.css
+        * (.kol-sidenav-grab); hidden below lg by the narrow-mode block. */}
+      <div className="kol-sidenav-grab absolute top-0 right-0 bottom-0 z-[1]" {...grabProps} />
     </aside>
   )
 }

package/src/useDragResize.js

@@ -0,0 +1,176 @@
+import { useEffect, useRef, useState } from 'react'
+
+/* Grab-edge resize + snap-collapse for SideNav (lobby: SideNavGrabResize).
+ * Mechanics are kol-mirror's MirrorPlayground.jsx#L21-L76 — pointerdown on the
+ * strip, window-level move/up, body cursor + userSelect held for the drag,
+ * double-click resets. What the DS adds on top of that prior art:
+ *   - live width goes to --kol-sidenav-w on :root, so the layout grid, the
+ *     shell-header brand block and the aside all follow one number
+ *   - dragging under --kol-sidenav-snap stamps :root[data-sidenav="collapsed"]
+ *     (rendered again in kol-framework.css since 2026-08-09); back out re-expands
+ *   - width + state survive reload. 'kol-sidenav' keeps the consumers' existing
+ *     'collapsed'|'expanded' schema; width lives under its own key so the
+ *     brand app's reader of that value never breaks
+ * Keyboard path (a11y is not optional per the brief): the strip is a focusable
+ * separator — arrows resize by --kol-sidenav-step, ArrowLeft past the snap
+ * collapses, ArrowRight re-expands, Home resets to the stylesheet default.
+ * Every value the gesture needs is a --kol-sidenav-* token in kol-framework.css
+ * — no literals here, so a missing token (framework CSS not loaded) leaves the
+ * gesture inert rather than improvising numbers. */
+
+const STATE_KEY = 'kol-sidenav'
+const WIDTH_KEY = 'kol-sidenav-w'
+
+const root = () => document.documentElement
+
+/* Resolve a length token to px, or null when it is absent/unparsable. */
+function readVarPx(name) {
+  const raw = getComputedStyle(root()).getPropertyValue(name).trim()
+  const n = parseFloat(raw)
+  if (!raw || Number.isNaN(n)) return null
+  return raw.endsWith('rem') ? n * parseFloat(getComputedStyle(root()).fontSize) : n
+}
+
+/* Imperative DOM writes — pointermove must never re-render the nav tree.
+ * React state syncs from the DOM at rest (drag end / key press / reset). */
+const stampCollapsed = (on) => {
+  if (on) root().setAttribute('data-sidenav', 'collapsed')
+  else root().removeAttribute('data-sidenav')
+}
+const writeWidth = (px) => {
+  if (px == null) root().style.removeProperty('--kol-sidenav-w')
+  else root().style.setProperty('--kol-sidenav-w', `${px}px`)
+}
+const readBack = () => {
+  const inline = parseFloat(root().style.getPropertyValue('--kol-sidenav-w'))
+  return {
+    collapsed: root().getAttribute('data-sidenav') === 'collapsed',
+    widthPx: Number.isNaN(inline) ? null : inline,
+  }
+}
+
+export default function useDragResize(asideRef) {
+  const drag = useRef(null) // { startX, startW, snapPx, maxPx } during a drag
+  const defaultPx = useRef(null)
+  const collapsedPx = useRef(null)
+  const [collapsed, setCollapsed] = useState(false)
+  const [widthPx, setWidthPx] = useState(null) // null = stylesheet default
+
+  const syncAndPersist = () => {
+    const { collapsed: c, widthPx: w } = readBack()
+    setCollapsed(c)
+    setWidthPx(w)
+    try {
+      localStorage.setItem(STATE_KEY, c ? 'collapsed' : 'expanded')
+      if (w == null) localStorage.removeItem(WIDTH_KEY)
+      else localStorage.setItem(WIDTH_KEY, String(Math.round(w)))
+    } catch { /* storage blocked */ }
+  }
+
+  /* Boot: capture the stylesheet defaults BEFORE any inline override lands,
+   * then restore the persisted width/state. */
+  useEffect(() => {
+    defaultPx.current = readVarPx('--kol-sidenav-w')
+    collapsedPx.current = readVarPx('--kol-sidenav-w-collapsed')
+    let w = null
+    let c = false
+    try {
+      w = parseFloat(localStorage.getItem(WIDTH_KEY)) || null
+      c = localStorage.getItem(STATE_KEY) === 'collapsed'
+    } catch { /* storage blocked */ }
+    if (w) { writeWidth(w); setWidthPx(w) }
+    if (c) { stampCollapsed(true); setCollapsed(true) }
+  }, [])
+
+  useEffect(() => {
+    const onMove = (e) => {
+      if (!drag.current) return
+      const { startX, startW, snapPx, maxPx } = drag.current
+      const next = startW + (e.clientX - startX)
+      if (next < snapPx) {
+        stampCollapsed(true)
+      } else {
+        stampCollapsed(false)
+        writeWidth(Math.min(next, maxPx))
+      }
+    }
+    const onUp = () => {
+      if (!drag.current) return
+      drag.current = null
+      root().removeAttribute('data-sidenav-dragging')
+      document.body.style.cursor = ''
+      document.body.style.userSelect = ''
+      syncAndPersist()
+    }
+    window.addEventListener('pointermove', onMove)
+    window.addEventListener('pointerup', onUp)
+    return () => {
+      window.removeEventListener('pointermove', onMove)
+      window.removeEventListener('pointerup', onUp)
+    }
+  }, [])
+
+  const onPointerDown = (e) => {
+    const snapPx = readVarPx('--kol-sidenav-snap')
+    if (defaultPx.current == null || snapPx == null) return // tokens absent → inert
+    e.preventDefault()
+    drag.current = {
+      startX: e.clientX,
+      startW: asideRef.current?.getBoundingClientRect().width ?? defaultPx.current,
+      snapPx,
+      /* mirror's ceiling (default × 3), resolved from the token not hardcoded */
+      maxPx: defaultPx.current * 3,
+    }
+    /* the grid's 180ms grid-template-columns ease would trail the pointer —
+     * kol-framework.css suspends it while this attribute is stamped */
+    root().setAttribute('data-sidenav-dragging', '')
+    document.body.style.cursor = 'col-resize'
+    document.body.style.userSelect = 'none'
+  }
+
+  const onDoubleClick = () => {
+    stampCollapsed(false)
+    writeWidth(null)
+    syncAndPersist()
+  }
+
+  const onKeyDown = (e) => {
+    const snapPx = readVarPx('--kol-sidenav-snap')
+    const stepPx = readVarPx('--kol-sidenav-step')
+    if (defaultPx.current == null || snapPx == null || stepPx == null) return
+    const { collapsed: c, widthPx: w } = readBack()
+    const current = w ?? defaultPx.current
+    if (e.key === 'ArrowRight') {
+      e.preventDefault()
+      if (c) stampCollapsed(false)
+      else writeWidth(Math.min(current + stepPx, defaultPx.current * 3))
+      syncAndPersist()
+    } else if (e.key === 'ArrowLeft') {
+      e.preventDefault()
+      if (c) return
+      const next = current - stepPx
+      if (next < snapPx) stampCollapsed(true)
+      else writeWidth(next)
+      syncAndPersist()
+    } else if (e.key === 'Home') {
+      e.preventDefault()
+      onDoubleClick()
+    }
+  }
+
+  return {
+    collapsed,
+    grabProps: {
+      role: 'separator',
+      'aria-orientation': 'vertical',
+      'aria-label': 'Resize navigation',
+      'aria-valuenow': Math.round(collapsed ? collapsedPx.current : (widthPx ?? defaultPx.current)) || undefined,
+      'aria-valuemin': collapsedPx.current == null ? undefined : Math.round(collapsedPx.current),
+      'aria-valuemax': defaultPx.current == null ? undefined : Math.round(defaultPx.current * 3),
+      tabIndex: 0,
+      onPointerDown,
+      onDoubleClick,
+      onKeyDown,
+    },
+  }
+}