@kolkrabbi/kol-shell 0.37.0 → 0.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.37.0",
+  "version": "0.38.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.154.1",
+    "@kolkrabbi/kol-theme": "^0.123.0",
     "@kolkrabbi/kol-icons": "^0.25.0",
-    "@kolkrabbi/kol-framework": "^0.36.0",
-    "@kolkrabbi/kol-theme": "^0.122.0"
+    "@kolkrabbi/kol-component": "^0.156.0",
+    "@kolkrabbi/kol-framework": "^0.36.0"
   },
   "files": [
     "src",

package/src/AppShell.jsx

@@ -99,6 +99,13 @@ const CODE_FOR_KEY = {
   '-': 'Minus', '=': 'Equal',
 }
 
+/* A STABLE DEFAULT (ShellDrawerOpenOnUnstableDep, kol-mirror 2026-09-01 —
+ * found by the user on his phone): `drawerOpenOn = []` in the signature was a
+ * fresh array every render, and it sat in an effect's deps, so the route effect
+ * re-ran on every render and closed the drawer straight after every tap. The
+ * trigger did nothing on every consumer taking the default. */
+const NO_PATHS = []
+
 export default function AppShell({
   items,
   bottomItems,
@@ -115,7 +122,7 @@ export default function AppShell({
   settingsPath,
   settingsKey,
   drawerBelow = 768,
-  drawerOpenOn = [],
+  drawerOpenOn = NO_PATHS,
   children,
 }) {
   const [navHidden, setNavHidden] = useState(false)
@@ -205,10 +212,14 @@ export default function AppShell({
   /* …unless the destination is one where nav IS the page (`drawerOpenOn`):
    * there the entry OPENS it. Runs on mount, on the fold and on navigation
    * alike — `drawer` is a dep — so a phone arriving on home gets the rail. */
+  /* Keyed on the BOOLEAN, not the array: a consumer's inline `['/']` is a new
+   * identity every render too (the showcase set passes one), and the effect
+   * must fire on route entry only — never on a re-render, or it undoes the tap. */
+  const opensHere = drawerOpenOn.some((p) => (p === '/' ? currentPath === '/' : currentPath.startsWith(p)))
   useEffect(() => {
-    if (drawer) setDrawerOpen(drawerOpenOn.some((p) => (p === '/' ? currentPath === '/' : currentPath.startsWith(p))))
+    if (drawer) setDrawerOpen(opensHere)
     else setNavHidden(false)
-  }, [currentPath, drawer, drawerOpenOn])
+  }, [currentPath, drawer, opensHere])
 
   /* 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

package/src/NavRail.jsx

@@ -119,7 +119,9 @@ function useRailDrag(railRef, grabRef, onSnap, snapRef, enabled = true) {
      * 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())
+    /* `(false)` closes, anything else opens — the same seam the L2 rows use
+     * to open, now also the tap opener's toggle */
+    if (snapRef) snapRef.current = (open = true) => snapTo(open === false ? CLOSED : openWidth())
     const onDown = (e) => {
       strip.setPointerCapture(e.pointerId)
       gsap.killTweensOf(root)
@@ -295,7 +297,32 @@ export default function NavRail({
         * zeroed in drawer mode so the content gets the whole viewport back. */
       style={{ width: drawer ? 'var(--kol-shell-drawer-width, 240px)' : `var(${RAIL_W})` }}
     >
-      {!drawer && <div ref={grabRef} className="kol-rail-grab" />}
+      {!drawer && (
+        /* A BUTTON, with a glyph a thumb can find (ShellRailCollapsedWithTapOpen,
+         * kol-mirror 2026-09-01 — user: "i means collapsed variant not
+         * expanded"): `touch="shell"` is the only mode that keeps the 48px rail
+         * visible, and its only opener was this 8px strip, invisible until a
+         * pointer HOVERED near it — a thumb never does, so on a phone the rail
+         * could not be opened at all. The strip already toggled on a click (a
+         * press with no travel); it just had no affordance and no hit area on
+         * touch. Under `(pointer: coarse)` the theme shows `.kol-rail-grab-tap`
+         * — a 24px disc on the line — and widens the strip to it; on a fine
+         * pointer nothing changes, the ruled grab stays. The drag hook binds
+         * pointer events, so a button works exactly as the div did, and it now
+         * says what it is. Enter/Space toggle for the keyboard. */
+        <button
+          type="button"
+          ref={grabRef}
+          className="kol-rail-grab"
+          aria-label={railOpen ? 'Collapse navigation' : 'Expand navigation'}
+          aria-expanded={railOpen}
+          onKeyDown={(e) => { if (e.key === 'Enter' || e.key === ' ') { e.preventDefault(); snapOpenRef.current?.(!railOpen) } }}
+        >
+          <span className="kol-rail-grab-tap" aria-hidden="true">
+            <IconAt name={railOpen ? 'chevron-left' : 'chevron-right'} size={12} component={iconComponent} />
+          </span>
+        </button>
+      )}
       {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