@kolkrabbi/kol-shell 0.27.0 → 0.29.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.27.0",
+  "version": "0.29.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.136.0",
+    "@kolkrabbi/kol-component": "^0.138.0",
     "@kolkrabbi/kol-icons": "^0.25.0",
     "@kolkrabbi/kol-framework": "^0.35.0",
-    "@kolkrabbi/kol-theme": "^0.106.0"
+    "@kolkrabbi/kol-theme": "^0.111.0"
   },
   "files": [
     "src",

package/src/AppShell.jsx

@@ -155,6 +155,20 @@ export default function AppShell({
 
   /* the rail comes back on every route change */
   useEffect(() => { setNavHidden(false) }, [currentPath])
+
+  /* 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
+   * not: `.kol-dd-panel` renders at document.body, so it read the fallback
+   * `transparent` while its own trigger, inside the shell, took the wash. The
+   * two halves of one connected control rendered at different values, which is
+   * exactly what the user saw. Anything floating over the page is still ON the
+   * page as far as this film is concerned. */
+  useEffect(() => {
+    const root = document.documentElement
+    if (pageWash == null) { root.style.removeProperty('--kol-shell-page-wash'); return undefined }
+    root.style.setProperty('--kol-shell-page-wash', pageWash)
+    return () => root.style.removeProperty('--kol-shell-page-wash')
+  }, [pageWash])
   /* one key toggles the rail — never while typing in a field */
   useEffect(() => {
     if (!railToggleKey) return undefined

package/src/NavRail.jsx

@@ -119,7 +119,7 @@ function useGrabEdge(ref) {
  * 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 +129,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 +166,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 +177,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 +215,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 +288,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