@kolkrabbi/kol-shell 0.29.0 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.29.0",
+  "version": "0.31.0",
   "private": false,
   "description": "KOL application shell — fixed 48px NavRail + AppShell layout root, PageShell/PageHeader scaffolds, ContentFilters catalog organism, GridCard, SettingsScaffold, WalkthroughPanel, ShortcutsOverlay. App chrome (kol-framework owns site chrome). Nav items, content, shortcuts and settings are consumer-injected. Sits above @kolkrabbi/kol-{theme,component,framework}.",
   "license": "MIT",
@@ -20,10 +20,10 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.138.0",
+    "@kolkrabbi/kol-component": "^0.145.0",
     "@kolkrabbi/kol-icons": "^0.25.0",
-    "@kolkrabbi/kol-framework": "^0.35.0",
-    "@kolkrabbi/kol-theme": "^0.111.0"
+    "@kolkrabbi/kol-theme": "^0.112.0",
+    "@kolkrabbi/kol-framework": "^0.36.0"
   },
   "files": [
     "src",

package/src/AppShell.jsx

@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useRef, useState } from 'react'
+import { Button } from '@kolkrabbi/kol-component'
 import NavRail from './NavRail.jsx'
 import { NavHiddenContext } from './navHidden.js'
 import { SettingsToggleContext } from './settingsToggle.js'
@@ -41,7 +42,17 @@ import TouchDeviceOverlay, { useTouchPrimary } from './TouchDeviceOverlay.jsx'
  * toggle lives on the settings page, not in the rail (user, 2026-08-28).
  * @param {string}  props.railToggleKey  a key that toggles the rail (e.g. '\\') — ignored while typing in a field;
  *                                        the rail comes back on every `currentPath` change (ShellHomeSystem, 2026-08-27)
- * @param {'shell'|'bare'|'overlay'} props.touch  the touch-primary policy (default 'shell' = the rail regardless):
+ * @param {'shell'|'bare'|'overlay'|'drawer'} props.touch  the touch-primary policy (default 'shell' = the rail regardless):
+ *                                        'drawer' takes the rail OFF-CANVAS below `drawerBelow`, hands its width
+ *                                        back to the content, and renders a trigger that brings it in over a scrim.
+ *                                        Tapping a destination closes it. (ShellRailNoDrawerOnMobile, kol-chess
+ *                                        2026-08-31: at 390 the 48px rail is 12.3% of the viewport, and
+ *                                        `railToggleKey` is a KEY — a phone has no keyboard, so on the device where
+ *                                        the rail costs most it could not be dismissed at all. `bare` was the only
+ *                                        other way to reclaim the width and it throws navigation away entirely.)
+ * @param {number} [props.drawerBelow=768]  viewport width under which `touch="drawer"` folds. A width, not a
+ *                                        pointer test: an iPad is coarse and has room, a narrow desktop window is
+ *                                        fine-pointered and does not.
  *                                        `bare` renders the children with NO shell on a coarse-pointer device unless
  *                                        localStorage `kol-desktop` is '1' (fxr's gate); `overlay` keeps the shell and
  *                                        mounts TouchDeviceOverlay once (monitor's)
@@ -95,11 +106,34 @@ export default function AppShell({
   navKeys = false,
   settingsPath,
   settingsKey,
+  drawerBelow = 768,
   children,
 }) {
   const [navHidden, setNavHidden] = useState(false)
   const coarse = useTouchPrimary()
 
+  /* DRAWER MODE. A width query, not a pointer one — see `drawerBelow`. */
+  const [narrow, setNarrow] = useState(
+    () => typeof window !== 'undefined' && window.matchMedia(`(max-width: ${drawerBelow - 1}px)`).matches,
+  )
+  useEffect(() => {
+    if (typeof window === 'undefined') return undefined
+    const mq = window.matchMedia(`(max-width: ${drawerBelow - 1}px)`)
+    const on = (e) => setNarrow(e.matches)
+    setNarrow(mq.matches)
+    mq.addEventListener('change', on)
+    return () => mq.removeEventListener('change', on)
+  }, [drawerBelow])
+  const drawer = touch === 'drawer' && narrow
+  const [drawerOpen, setDrawerOpen] = useState(false)
+  useEffect(() => { if (!drawer) setDrawerOpen(false) }, [drawer])
+  useEffect(() => {
+    if (!drawer || !drawerOpen) return undefined
+    const onKey = (e) => { if (e.key === 'Escape') setDrawerOpen(false) }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [drawer, drawerOpen])
+
   /* TOGGLING A DESTINATION (user 2026-08-30: "comma opens and closes the
    * settings page, and clicking the icon in sidebar opens and clicking again
    * closes"). The shell already owned two keyboard behaviours; this is a third
@@ -153,8 +187,16 @@ export default function AppShell({
     [settingsPath, toggleSettings, onNavigate],
   )
 
-  /* the rail comes back on every route change */
-  useEffect(() => { setNavHidden(false) }, [currentPath])
+  /* THE ROUTE CHANGE MEANS THE OPPOSITE IN EACH MODE. For `railToggleKey` the
+   * rail comes back on every navigation (ShellHomeSystem, 2026-08-27); for a
+   * drawer, tapping a destination must CLOSE it. The old unconditional
+   * `setNavHidden(false)` also made `navHidden` unusable as a consumer seam —
+   * child effects run before parent effects, so a consumer hiding the rail on a
+   * path change was overwritten in the same commit. */
+  useEffect(() => {
+    if (drawer) setDrawerOpen(false)
+    else setNavHidden(false)
+  }, [currentPath, drawer])
 
   /* THE WASH ALSO GOES ON THE ROOT (2026-08-30). It is set on the content
    * wrapper below, which every page inherits — but a PORTALLED surface does
@@ -228,9 +270,35 @@ export default function AppShell({
         * margin closes with it — one variable, both sides. */}
       <div
         className="kol-app-shell min-h-dvh bg-surface-primary"
-        style={navHidden ? { '--kol-shell-rail-width': '0px' } : undefined}
+        /* A DRAWER ZEROES THE TOKEN TOO. Off-canvas means the content owns the
+         * whole viewport, so the same one variable that closes the content's
+         * margin for `navHidden` closes it here — the rail then takes its own
+         * `--kol-shell-drawer-width` rather than this token. */
+        data-rail-drawer={drawer ? (drawerOpen ? 'open' : 'closed') : undefined}
+        style={navHidden || drawer ? { '--kol-shell-rail-width': '0px' } : undefined}
       >
       {touch === 'overlay' && <TouchDeviceOverlay appName={appName} />}
+      {/* THE TRIGGER SHIPS HERE, not in every consumer's page header — the rail
+        * is the shell's, so the only way to reach it is too. Hamburger closed,
+        * × open; 32px square clears the 24px touch floor. */}
+      {drawer && (
+        <Button
+          variant="nav"
+          iconOnly={drawerOpen ? 'x' : 'hamburger'}
+          iconComponent={iconComponent}
+          aria-label={drawerOpen ? 'Close navigation' : 'Open navigation'}
+          aria-expanded={drawerOpen}
+          className="kol-shell-drawer-trigger"
+          onClick={() => setDrawerOpen((o) => !o)}
+        />
+      )}
+      {drawer && drawerOpen && (
+        <div
+          className="kol-shell-drawer-scrim"
+          onClick={() => setDrawerOpen(false)}
+          aria-hidden="true"
+        />
+      )}
       {!navHidden && (
         <Rail
           items={items}
@@ -240,6 +308,7 @@ export default function AppShell({
           /* the rail routes through `navigate`, so its settings row toggles like the key */
           onNavigate={navigate}
           iconComponent={iconComponent}
+          drawer={drawer}
         />
       )}
       {/* THE BACK OF THE BACK — surface-primary, always, in every app; the

package/src/NavRail.jsx

@@ -2,6 +2,11 @@ import { useEffect, useRef, useState } from 'react'
 import gsap from 'gsap'
 import { Button } from '@kolkrabbi/kol-component'
 import { GRAB } from '@kolkrabbi/kol-component/utilities/motion'
+/* the grab pill's proximity wake, travel and dwell — ONE implementation, shared
+ * with kol-framework's useDragResize (OneGrabGestureBothRails, kol-fxr
+ * 2026-08-30: two rails on one screen felt different because each package had
+ * built the gesture itself). It lived here until then. */
+import { useGrabEdge } from '@kolkrabbi/kol-component'
 import { Icon } from '@kolkrabbi/kol-icons'
 import Logomark from './Logomark.jsx'
 
@@ -62,6 +67,9 @@ import Logomark from './Logomark.jsx'
  * @param {Object} logomark     `{ svgUrl, title }` — the mark, and the app name beside it when open
  * @param {string} currentPath  active match: '/' exact, else prefix → aria-current="page"
  * @param {Function} onNavigate `(path) => void` — every click, the mark included
+ * @param {boolean} drawer  off-canvas mode: no grab, no drag, no token writes, rows always
+ *   labelled, and the rail sizes itself from `--kol-shell-drawer-width` (default 240px).
+ *   AppShell sets this from `touch="drawer"` — see ShellRailNoDrawerOnMobile, 2026-08-31.
  */
 const RAIL_W = '--kol-shell-rail-width'
 const CLOSED = 48
@@ -83,45 +91,21 @@ const openWidth = () => {
  * lands on you, holds while you move inside the radius, then travels to where you
  * are now — inside `GRAB.range`, the middle band of the edge, so it never rides
  * up beside the logomark. One window listener, rAF-throttled. */
-function useGrabEdge(ref) {
-  useEffect(() => {
-    let raf = 0
-    const onMove = ({ clientX, clientY }) => {
-      if (raf) return
-      raf = requestAnimationFrame(() => {
-        raf = 0
-        const h = ref.current
-        if (!h) return
-        const r = h.getBoundingClientRect()
-        const dist = Math.abs(clientX - (r.left + r.width / 2))
-        const near = dist <= GRAB.near || (h.classList.contains('is-near') && dist <= GRAB.sleep)
-        h.classList.toggle('is-near', near)
-        if (!near) return
-        /* the travel band: bipolar from the middle, GRAB.range of the height */
-        const edge = (r.height * (1 - GRAB.range)) / 2
-        const along = Math.min(Math.max(clientY - r.top, edge), r.height - edge)
-        if (h.dataset.grabSeeded && Math.abs(along - Number(h.dataset.grabTarget)) < GRAB.stick) return
-        h.dataset.grabTarget = String(along)
-        const vars = { '--kol-rail-grab-y': `${along}px` }
-        /* the CSS fallback is 50%, a percentage — nothing to tween from, so the
-         * first sighting sets and every move after tweens */
-        if (h.dataset.grabSeeded) gsap.to(h, { ...vars, ...GRAB.travel, overwrite: 'auto' })
-        else { gsap.set(h, vars); h.dataset.grabSeeded = '1' }
-      })
-    }
-    window.addEventListener('pointermove', onMove)
-    return () => { window.removeEventListener('pointermove', onMove); cancelAnimationFrame(raf) }
-  }, [ref])
-}
 
 /* THE DRAG — hold the pill and the width follows the pointer between closed and
  * open; release snaps to the nearer state, a click (no travel past GRAB.slop)
  * toggles. `onSnap` reports the resting state once — the sub rows render only
  * while open, because closed they would still take their height and push the
  * rungs below them. */
-function useRailDrag(railRef, grabRef, onSnap, snapRef) {
+function useRailDrag(railRef, grabRef, onSnap, snapRef, enabled = true) {
   useEffect(() => {
     const strip = grabRef.current, rail = railRef.current, root = document.documentElement
+    /* A DRAWER IS NOT A DRAGGABLE RAIL (ShellRailNoDrawerOnMobile, kol-chess
+     * 2026-08-31). In drawer mode the rail is off-canvas at a fixed width and
+     * the content owns the whole viewport, so the drag must not run at all —
+     * it writes `--kol-shell-rail-width` on `:root` per pointermove, which is
+     * exactly the inline token a consumer could not reach without `!important`. */
+    if (!enabled) return undefined
     if (!strip || !rail) return undefined
     gsap.set(root, { [RAIL_W]: `${CLOSED}px` })
     let drag = null
@@ -284,24 +268,29 @@ export default function NavRail({
   onNavigate,
   iconComponent,
   hidden = false,
+  drawer = false,
 }) {
   const railRef = useRef(null)
   const grabRef = useRef(null)
   const [railOpen, setRailOpen] = useState(false)
   const snapOpenRef = useRef(null)
+  /* the grab strip is not rendered in drawer mode, so the hook's ref stays null
+   * and it no-ops on its own — no second argument needed */
   useGrabEdge(grabRef)
-  useRailDrag(railRef, grabRef, setRailOpen, snapOpenRef)
+  useRailDrag(railRef, grabRef, setRailOpen, snapOpenRef, !drawer)
   if (hidden) return null
   const row = (item) => (
-    <RailItem key={item.path} {...item} currentPath={currentPath} onNavigate={onNavigate} iconComponent={iconComponent} railOpen={railOpen} onOpenRail={() => snapOpenRef.current?.()} />
+    <RailItem key={item.path} {...item} currentPath={currentPath} onNavigate={onNavigate} iconComponent={iconComponent} railOpen={drawer || railOpen} onOpenRail={() => snapOpenRef.current?.()} />
   )
   return (
     <div
       ref={railRef}
       className="kol-shell-rail bg-surface-primary border-r border-fg-08 fixed inset-y-0 left-0 flex flex-col items-start pt-4 pb-4 px-2 gap-2"
-      style={{ width: `var(${RAIL_W})` }}
+      /* A drawer takes its own width, NOT the live rail token — that token is
+        * zeroed in drawer mode so the content gets the whole viewport back. */
+      style={{ width: drawer ? 'var(--kol-shell-drawer-width, 240px)' : `var(${RAIL_W})` }}
     >
-      <div ref={grabRef} className="kol-rail-grab" />
+      {!drawer && <div ref={grabRef} className="kol-rail-grab" />}
       {logomark && (
         /* the mark, and the app name beside it when open — uppercase like the
          * rows (user 2026-08-28: "uppercase CONSISTENCY"). The `w-8` centring box