@kolkrabbi/kol-framework 0.13.0 → 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.13.0",
+  "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",

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,
+    },
+  }
+}