@kolkrabbi/kol-shell 0.28.0 → 0.30.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.28.0",
+  "version": "0.30.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.142.0",
     "@kolkrabbi/kol-icons": "^0.25.0",
-    "@kolkrabbi/kol-component": "^0.137.0",
     "@kolkrabbi/kol-framework": "^0.35.0",
-    "@kolkrabbi/kol-theme": "^0.108.0"
+    "@kolkrabbi/kol-theme": "^0.111.0"
   },
   "files": [
     "src",

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'
 
@@ -83,43 +88,13 @@ 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) {
+function useRailDrag(railRef, grabRef, onSnap, snapRef) {
   useEffect(() => {
     const strip = grabRef.current, rail = railRef.current, root = document.documentElement
     if (!strip || !rail) return undefined
@@ -129,6 +104,13 @@ function useRailDrag(railRef, grabRef, onSnap) {
       gsap.to(root, { [RAIL_W]: `${w}px`, ...GRAB.snap, overwrite: 'auto' })
       onSnap(w !== CLOSED)
     }
+    /* the ONLY way out of this effect (RailSectionPressOpensRail, kol-fxr
+     * 2026-08-30). `snapTo` closes over the animation and the CLOSED/open
+     * ladder, so a section press has to reach it rather than reimplement it —
+     * a consumer setting `--kol-shell-rail-width` from outside widens the rail
+     * but leaves `railOpen` false, and the L2 rows render behind it: a wide,
+     * EMPTY rail, worse than the dead press this fixes. */
+    if (snapRef) snapRef.current = () => snapTo(openWidth())
     const onDown = (e) => {
       strip.setPointerCapture(e.pointerId)
       gsap.killTweensOf(root)
@@ -159,7 +141,7 @@ function useRailDrag(railRef, grabRef, onSnap) {
       strip.removeEventListener('pointerup', onUp)
       strip.removeEventListener('pointercancel', onUp)
     }
-  }, [railRef, grabRef, onSnap])
+  }, [railRef, grabRef, onSnap, snapRef])
 }
 
 /* one row: the rung exactly where the closed rail had it, then the label and
@@ -170,8 +152,26 @@ function IconAt({ name, size, component }) {
   return <Cmp name={name} size={size} />
 }
 
-function RailItem({ icon, path, label, sub, currentPath, onNavigate, iconComponent, railOpen }) {
+function RailItem({ icon, path, label, sub, currentPath, onNavigate, iconComponent, railOpen, onOpenRail }) {
   const [open, setOpen] = useState(false)
+  /* A SECTION ROW IS NOT A DESTINATION (RailSectionPressOpensRail, kol-fxr
+   * 2026-08-30 — user: *"if I press effects from collapsed nav it should maybe
+   * open? currently pressing it does nothing"*).
+   *
+   * Closed, the row clips to 48px and the disclosure caret sits OUTSIDE that
+   * clip, so the only reachable control was the icon — which called
+   * `onNavigate` with a path no consumer dispatches, because a section has no
+   * action. A guaranteed dead press, in the rail's default state.
+   *
+   * Pressing it now opens the rail and expands that section. This is the
+   * behaviour `SideNav` had before the flat-rail reversal. It does not fight
+   * "nothing auto-expands" — that rule is about ARRIVING on a route; this is an
+   * explicit press. */
+  const isSection = sub?.length > 0
+  const press = () => {
+    if (isSection && !railOpen) { onOpenRail?.(); setOpen(true); return }
+    onNavigate?.(path)
+  }
   const active = path === '/' ? currentPath === '/' : currentPath.startsWith(path)
   return (
     <>
@@ -190,13 +190,13 @@ function RailItem({ icon, path, label, sub, currentPath, onNavigate, iconCompone
            * and too dim on an icon rail (user: "make the color .96 on every icon
            * in the rail") */
           style={{ color: 'var(--kol-oq-96)' }}
-          onClick={() => onNavigate?.(path)}
+          onClick={press}
           title={label}
           aria-label={label}
         />
         <span
           className="kol-helper-12 uppercase text-oq-96 flex-1 min-w-0 truncate cursor-pointer"
-          onClick={() => onNavigate?.(path)}
+          onClick={press}
         >
           {label}
         </span>
@@ -263,11 +263,12 @@ export default function NavRail({
   const railRef = useRef(null)
   const grabRef = useRef(null)
   const [railOpen, setRailOpen] = useState(false)
+  const snapOpenRef = useRef(null)
   useGrabEdge(grabRef)
-  useRailDrag(railRef, grabRef, setRailOpen)
+  useRailDrag(railRef, grabRef, setRailOpen, snapOpenRef)
   if (hidden) return null
   const row = (item) => (
-    <RailItem key={item.path} {...item} currentPath={currentPath} onNavigate={onNavigate} iconComponent={iconComponent} railOpen={railOpen} />
+    <RailItem key={item.path} {...item} currentPath={currentPath} onNavigate={onNavigate} iconComponent={iconComponent} railOpen={railOpen} onOpenRail={() => snapOpenRef.current?.()} />
   )
   return (
     <div