@kolkrabbi/kol-framework 0.16.1 → 0.18.0

package/kol-framework.css

@@ -40,9 +40,10 @@ body {
      -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-grab-w: var(--kol-spacing-2);  /* the strip's hit width (doubled 2026-08-09 — the pill made it a click target) */
   --kol-sidenav-snap: 12rem;                   /* drag under this snaps to -w-collapsed */
   --kol-sidenav-step: var(--kol-spacing-4);    /* keyboard resize increment */
+  --kol-sidenav-snap-default: var(--kol-sidenav-step); /* release within this of the default clears the override */
   --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
@@ -175,6 +176,25 @@ body {
   width: var(--kol-sidenav-grab-w);
   cursor: col-resize;
 }
+/* THE PILL (user build order 2026-08-09): the edge's rest-visible indicator —
+ * a vertical rounded bar centred mid-height, dim at rest, full ink on
+ * hover/focus. Same law as the record grip: affordances visible at rest. */
+.kol-sidenav-grab::before {
+  content: '';
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  translate: -50% -50%;
+  width: 0.1875rem;
+  height: 2rem;
+  border-radius: var(--kol-radius-full);
+  background: var(--kol-fg-24);
+  transition: background-color 150ms ease;
+}
+.kol-sidenav-grab:hover::before,
+.kol-sidenav-grab:focus-visible::before {
+  background: var(--kol-fg-64);
+}
 .kol-sidenav-grab:focus-visible {
   outline: 2px solid var(--kol-focus-ring);
   outline-offset: -2px;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-framework",
-  "version": "0.16.1",
+  "version": "0.18.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.32.1",
-    "@kolkrabbi/kol-icons": "^0.12.1"
+    "@kolkrabbi/kol-component": "^0.34.0",
+    "@kolkrabbi/kol-icons": "^0.14.0"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",

package/src/ShellHeader.jsx

@@ -108,12 +108,10 @@ export default function ShellHeader({
               {actions}
               {showThemeToggle && (
                 <Tooltip label="Toggle theme">
-                  {/* one rung up at lg+ — the bar has room, and the toggle is
-                    * the most-used control in the row. New spec API (0.9.0):
-                    * 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} size="lg" /></span>
+                  {/* md at every width (user re-rule 2026-08-09: the whole
+                    * header glyph row rides md, full ink — the earlier lg-at-lg+
+                    * split is repealed, which also collapsed the two spans). */}
+                  <ThemeToggle fill="none" label={false} size="md" />
                 </Tooltip>
               )}
               {onMenuClick && (
@@ -121,13 +119,12 @@ export default function ShellHeader({
                   {/* 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. */}
+                    * only approximate by dropping its own. `nav` rests at FULL
+                    * ink since the 2026-08-09 re-rule (was oq-64). */}
                   <IconFrame
                     name="hamburger"
                     variant="nav"
-                    size="lg"
+                    size="md"
                     onClick={onMenuClick}
                     aria-label="Open navigation menu"
                   />

package/src/SideNav.jsx

@@ -1,7 +1,7 @@
 import { NavLink, useLocation } from 'react-router-dom'
 import { useRef, useState } from 'react'
 import { Icon } from '@kolkrabbi/kol-icons'
-import { Button, Tooltip } from '@kolkrabbi/kol-component'
+import { Tooltip } from '@kolkrabbi/kol-component'
 import ThemeToggle from './ThemeToggle'
 import useDragResize from './useDragResize'
 
@@ -22,12 +22,13 @@ import useDragResize from './useDragResize'
  * navTree: [{ id, label, icon, to?, pages?: [{ label, to }] }]
  * (legacy `children` route leaves are read as `pages`; section anchors are not.)
  *
- * Collapse: BOTH affordances share one contract —
- * `:root[data-sidenav="collapsed"]` + the `kol-sidenav` storage schema, owned
- * by useDragResize. The round chip Button (elder A/B, closed 2026-08-01) is
- * the one-click toggle; the grab edge (lobby: SideNavGrabResize, 2026-08-09)
- * resizes, snap-collapses, and carries the keyboard path. Collapsed rows get
- * a DS Tooltip — the glyph is otherwise the only thing naming them.
+ * Collapse: the pill-marked grab edge is THE single control (user build
+ * order 2026-08-09, completing SideNavGrabResize — the chip Button is gone
+ * in both states). Click toggles expand↔collapse, drag resizes with
+ * snap-collapse and snap-to-default, keyboard on the separator: arrows /
+ * Home / Enter / Space. One contract: `:root[data-sidenav="collapsed"]` +
+ * the `kol-sidenav` storage schema, owned by useDragResize. Collapsed rows
+ * get a DS Tooltip — the glyph is otherwise the only thing naming them.
  *
  * `background` (2026-08-09, prop): `true` (default) paints the rail surface +
  * right hairline; `false` renders chromeless so the rail can float over a
@@ -94,25 +95,10 @@ export default function SideNav({
       ref={asideRef}
       className={`kol-sidenav sticky top-0 self-start h-dvh flex flex-col z-20${background ? ' bg-surface-primary border-r border-fg-08' : ''}${collapsed ? ' is-collapsed' : ''}${drawerOpen ? ' is-drawer-open' : ''}`}
     >
-      {/* The elder A/B (closed 2026-08-01): the DS Button IS the collapse
-        * control — EXPANDED ONLY (user ruling 2026-08-09, verbatim: "REMOVE
-        * chevron from collapsed view … from collapsed view pressing any icon
-        * would expand the sidebar!"). The collapsed rail's expand affordance
-        * is the rows themselves. Offset is half the pinned sm square,
-        * centring it on the rail's edge. */}
-      {!collapsed && (
-        <Button
-          variant="primary"
-          size="sm"
-          radius="full"
-          iconOnly="chevron-left"
-          aria-label="Collapse sidebar"
-          aria-expanded
-          title="Collapse"
-          onClick={toggleCollapsed}
-          className="kol-sidenav-toggle absolute top-5 right-[-0.875rem] z-[2]"
-        />
-      )}
+      {/* NO chip Button in either state (user build order 2026-08-09 — "MAKE
+        * IT"; supersedes the elder A/B): the pill-marked grab edge below is
+        * THE single collapse/resize control — click toggles, drag resizes,
+        * snap-to-default on release, Home/Enter/Space on the keyboard. */}
 
       <div className="kol-sidenav-scroll flex-1 flex flex-col justify-between overflow-y-auto pt-4 pb-4 [scrollbar-width:thin]">
         <nav aria-label="Sections">

package/src/useDragResize.js

@@ -1,25 +1,35 @@
 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. */
+/* Grab-edge resize + collapse for SideNav — THE single control since 0.17.0
+ * (user build order 2026-08-09, completing the SideNavGrabResize brief: the
+ * chip Button is gone in both states; the pill-marked edge does everything).
+ * Logic lifted from the hand-tested brand proto (kol-website _tmp
+ * useDragResizeProto.js), which forked this hook's 0.16.0 form.
+ *
+ *  - CLICK TOGGLES expand↔collapse: pointerup with < 3px of travel is a
+ *    click, never a resize — drags only start past the slop, so toggle
+ *    presses can't jitter the rail.
+ *  - DRAG resizes; live width goes to --kol-sidenav-w on :root so the grid,
+ *    shell-header brand block and aside follow one number. Dragging under
+ *    --kol-sidenav-snap stamps :root[data-sidenav="collapsed"].
+ *  - SNAP-TO-DEFAULT: releasing within --kol-sidenav-snap-default of the
+ *    stylesheet default clears the override — you land exactly on default,
+ *    never 249px or 263px.
+ *  - DOUBLE-CLICK RESET IS GONE — it cannot coexist with click-toggle (two
+ *    clicks would toggle-toggle-reset). Home keeps the reset; the snap band
+ *    covers pointer users.
+ *  - Keyboard on the focused separator: arrows resize by --kol-sidenav-step
+ *    (ArrowLeft past the snap collapses), Home resets, Enter/Space toggle.
+ *  - Width + state survive reload ('kol-sidenav' keeps the consumers'
+ *    existing 'collapsed'|'expanded' schema; width under its own key).
+ *
+ * Every value the gesture needs is a --kol-sidenav-* token in
+ * kol-framework.css — no literals here except the click slop, which is a
+ * gesture constant, not chrome. Missing tokens leave the gesture inert. */
 
 const STATE_KEY = 'kol-sidenav'
 const WIDTH_KEY = 'kol-sidenav-w'
+const CLICK_SLOP_PX = 3
 
 const root = () => document.documentElement
 
@@ -32,7 +42,7 @@ function readVarPx(name) {
 }
 
 /* Imperative DOM writes — pointermove must never re-render the nav tree.
- * React state syncs from the DOM at rest (drag end / key press / reset). */
+ * React state syncs from the DOM at rest (release / key press / reset). */
 const stampCollapsed = (on) => {
   if (on) root().setAttribute('data-sidenav', 'collapsed')
   else root().removeAttribute('data-sidenav')
@@ -50,7 +60,7 @@ const readBack = () => {
 }
 
 export default function useDragResize(asideRef) {
-  const drag = useRef(null) // { startX, startW, snapPx, maxPx } during a drag
+  const drag = useRef(null) // { startX, startW, snapPx, maxPx, moved } during a drag
   const defaultPx = useRef(null)
   const collapsedPx = useRef(null)
   const [collapsed, setCollapsed] = useState(false)
@@ -67,6 +77,12 @@ export default function useDragResize(asideRef) {
     } catch { /* storage blocked */ }
   }
 
+  const toggleCollapsed = () => {
+    const { collapsed: c } = readBack()
+    stampCollapsed(!c)
+    syncAndPersist()
+  }
+
   /* Boot: capture the stylesheet defaults BEFORE any inline override lands,
    * then restore the persisted width/state. */
   useEffect(() => {
@@ -85,21 +101,37 @@ export default function useDragResize(asideRef) {
   useEffect(() => {
     const onMove = (e) => {
       if (!drag.current) return
-      const { startX, startW, snapPx, maxPx } = drag.current
-      const next = startW + (e.clientX - startX)
-      if (next < snapPx) {
+      const d = drag.current
+      const dx = e.clientX - d.startX
+      /* Below the slop the pointer is still a CLICK — resizing from the
+       * first pixel would jitter the rail on every toggle press. */
+      if (!d.moved) {
+        if (Math.abs(dx) < CLICK_SLOP_PX) return
+        d.moved = true
+      }
+      const next = d.startW + dx
+      if (next < d.snapPx) {
         stampCollapsed(true)
       } else {
         stampCollapsed(false)
-        writeWidth(Math.min(next, maxPx))
+        writeWidth(Math.min(next, d.maxPx))
       }
     }
     const onUp = () => {
       if (!drag.current) return
+      const { moved } = drag.current
       drag.current = null
       root().removeAttribute('data-sidenav-dragging')
       document.body.style.cursor = ''
       document.body.style.userSelect = ''
+      if (!moved) { toggleCollapsed(); return } // a click, not a drag
+      /* Snap-to-default: release near the stylesheet default clears the
+       * override entirely. */
+      const { collapsed: c, widthPx: w } = readBack()
+      const band = readVarPx('--kol-sidenav-snap-default') ?? readVarPx('--kol-sidenav-step') ?? 16
+      if (!c && w != null && defaultPx.current != null && Math.abs(w - defaultPx.current) <= band) {
+        writeWidth(null)
+      }
       syncAndPersist()
     }
     window.addEventListener('pointermove', onMove)
@@ -120,29 +152,21 @@ export default function useDragResize(asideRef) {
       snapPx,
       /* mirror's ceiling (default × 3), resolved from the token not hardcoded */
       maxPx: defaultPx.current * 3,
+      moved: false,
     }
-    /* the grid's 180ms grid-template-columns ease would trail the pointer —
+    /* the grid's 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 = () => {
+  const resetToDefault = () => {
     stampCollapsed(false)
     writeWidth(null)
     syncAndPersist()
   }
 
-  /* One-click toggle for the chip Button (elder A/B, folded back 2026-08-09)
-   * — same stamp, same storage schema, so the chip and the grab edge can
-   * never disagree about the state. */
-  const toggleCollapsed = () => {
-    const { collapsed: c } = readBack()
-    stampCollapsed(!c)
-    syncAndPersist()
-  }
-
   const onKeyDown = (e) => {
     const snapPx = readVarPx('--kol-sidenav-snap')
     const stepPx = readVarPx('--kol-sidenav-step')
@@ -163,7 +187,10 @@ export default function useDragResize(asideRef) {
       syncAndPersist()
     } else if (e.key === 'Home') {
       e.preventDefault()
-      onDoubleClick()
+      resetToDefault()
+    } else if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault()
+      toggleCollapsed()
     }
   }
 
@@ -179,7 +206,6 @@ export default function useDragResize(asideRef) {
       'aria-valuemax': defaultPx.current == null ? undefined : Math.round(defaultPx.current * 3),
       tabIndex: 0,
       onPointerDown,
-      onDoubleClick,
       onKeyDown,
     },
   }