@kolkrabbi/kol-shell 0.16.1 → 0.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.16.1",
+  "version": "0.17.1",
   "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",
@@ -12,7 +12,7 @@
     "./src/*": "./src/*"
   },
   "peerDependencies": {
-    "@kolkrabbi/kol-component": ">=0.126.0",
+    "@kolkrabbi/kol-component": ">=0.127.0",
     "@kolkrabbi/kol-icons": ">=0.16.0",
     "@kolkrabbi/kol-theme": ">=0.84.0",
     "gsap": "^3.13.0",
@@ -20,9 +20,9 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.126.0",
-    "@kolkrabbi/kol-icons": "^0.24.0",
     "@kolkrabbi/kol-framework": "^0.35.0",
+    "@kolkrabbi/kol-component": "^0.127.0",
+    "@kolkrabbi/kol-icons": "^0.24.0",
     "@kolkrabbi/kol-theme": "^0.88.0"
   },
   "files": [

package/src/AppShell.jsx

@@ -21,6 +21,12 @@ import TouchDeviceOverlay, { useTouchPrimary } from './TouchDeviceOverlay.jsx'
  * `kol-framework.css` is no longer required by the shell (it was, for one
  * grid rule, 0.13–0.15).
  *
+ * `railComponent` (RailTwoLevelSections, kol-fxr 2026-08-28) — the rail is
+ * rendered directly here, so proving a rail change in a consumer meant forking
+ * BOTH this file and `NavRail`. Pass a component with `NavRail`'s props to
+ * render your own; default is `NavRail`. A seam for experiments, not an
+ * invitation to keep a fork.
+ *
  * @param {Array}  props.items         nav items `{ icon, path, label }`
  * @param {Array}  props.bottomItems   items pinned below the theme toggle
  * @param {Object} props.logomark      `{ svgUrl, title }` — the rail's header mark, at the top in both states, navigates to '/'
@@ -62,6 +68,7 @@ export default function AppShell({
   currentPath,
   onNavigate,
   iconComponent,
+  railComponent: Rail = NavRail,
   railToggleKey,
   touch = 'shell',
   appName,
@@ -122,7 +129,7 @@ export default function AppShell({
       >
       {touch === 'overlay' && <TouchDeviceOverlay appName={appName} />}
       {!navHidden && (
-        <NavRail
+        <Rail
           items={items}
           bottomItems={bottomItems}
           logomark={logomark}

package/src/NavRail.jsx

@@ -34,7 +34,30 @@ import Logomark from './Logomark.jsx'
  * has animation and gsap") — `.kol-rail-grab` in kol-theme's kol-animation.css,
  * its pointer numbers in kol-component's `utilities/motion` (`GRAB`).
  *
- * @param {Array}  items        `{ icon, path, label, sub?: [{ path, label }] }`
+ * TWO LEVELS (RailTwoLevelSections, kol-fxr 2026-08-28 — user: "the NAV has 20px
+ * icons in 32px containers, maybe level below has 12px icons in 20px container
+ * aligned to right? … you expand you see that they have main 56 items each, which
+ * you won't be aware of until you actually open labs, which should not happen
+ * automatically"). An item with `sub` is a SECTION: the same L1 row, plus a caret.
+ * Its rows are L2 — a 12px glyph in a 20px box, indented so its glyph column sits
+ * to the RIGHT of L1's (glyph x 14 → 30), resting a rung quieter at `oq-64` and
+ * going `oq-96` when it is the route. fxr's labs chrome is ~44 rows across four
+ * method sections; on one level they flatten into an icon column built for five
+ * destinations and the section names have nowhere to render at all.
+ *
+ * L2 is NOT a `Button`: the icon-button ladder is sm 28 / md 32 / lg 36 and this
+ * rung is 20 — there is nothing below sm, and adding one is a change to that
+ * ladder's law, which is the user's call and not this ticket's. The row is
+ * written directly and keys `aria-current`, so kol-theme's
+ * `.kol-shell-rail .kol-btn-nav` active rules still reach it. A sub row with no
+ * `icon` renders label-only, as it did before this level existed.
+ *
+ * NOTHING AUTO-EXPANDS. An L2 row is behind BOTH the rail's clipped width and its
+ * section's own disclosure, and `open` starts `false` with no prop to get it
+ * wrong — arriving on a route reveals nothing, by construction rather than by a
+ * flag a consumer has to remember.
+ *
+ * @param {Array}  items        `{ icon, path, label, sub?: [{ icon?, path, label }] }`
  * @param {Array}  bottomItems  pinned below the rule (Settings)
  * @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"
@@ -58,7 +81,8 @@ const openWidth = () => {
  * it lands, so it's not constantly jerking"): it targets the pointer's own
  * position and re-targets only once the pointer is `GRAB.stick` px away, so it
  * lands on you, holds while you move inside the radius, then travels to where you
- * are now. One window listener, rAF-throttled. */
+ * 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
@@ -73,7 +97,9 @@ function useGrabEdge(ref) {
         const near = dist <= GRAB.near || (h.classList.contains('is-near') && dist <= GRAB.sleep)
         h.classList.toggle('is-near', near)
         if (!near) return
-        const along = Math.min(Math.max(clientY - r.top, 0), r.height)
+        /* 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` }
@@ -138,6 +164,12 @@ function useRailDrag(railRef, grabRef, onSnap) {
 
 /* one row: the rung exactly where the closed rail had it, then the label and
  * (with `sub`) the chevron — the row clips to the rail's width */
+/* the L2 glyph goes through the same injection seam Button gives L1 */
+function IconAt({ name, size, component }) {
+  const Cmp = component || Icon
+  return <Cmp name={name} size={size} />
+}
+
 function RailItem({ icon, path, label, sub, currentPath, onNavigate, iconComponent, railOpen }) {
   const [open, setOpen] = useState(false)
   const active = path === '/' ? currentPath === '/' : currentPath.startsWith(path)
@@ -184,16 +216,37 @@ function RailItem({ icon, path, label, sub, currentPath, onNavigate, iconCompone
           />
         )}
       </div>
-      {railOpen && open && sub.map((s) => (
-        <div key={s.path} className="flex items-center w-full overflow-hidden shrink-0 pl-11">
-          <span
-            className="kol-helper-12 uppercase text-oq-64 hover:text-oq-96 truncate cursor-pointer"
+      {railOpen && open && sub.map((s) => {
+        const on = s.path === '/' ? currentPath === '/' : currentPath.startsWith(s.path)
+        return (
+          <div
+            key={s.path}
+            /* 18px of gutter puts the 20px box at x 26, so its 12px glyph starts
+             * at 30 — one step right of L1's 20-in-32 at 14 (measured in fxr) */
+            className="flex items-center gap-3 w-full overflow-hidden shrink-0 cursor-pointer"
+            style={{ paddingLeft: 18 }}
             onClick={() => onNavigate?.(s.path)}
+            aria-current={on ? 'page' : undefined}
+            title={s.label}
           >
-            {s.label}
-          </span>
-        </div>
-      ))}
+            {s.icon && (
+              <span
+                className="w-5 h-5 shrink-0 inline-flex items-center justify-center"
+                style={{ color: on ? 'var(--kol-oq-96)' : 'var(--kol-oq-64)' }}
+                aria-hidden="true"
+              >
+                <IconAt name={s.icon} size={12} component={iconComponent} />
+              </span>
+            )}
+            <span
+              className="kol-helper-12 uppercase flex-1 min-w-0 truncate"
+              style={{ color: on ? 'var(--kol-oq-96)' : 'var(--kol-oq-64)' }}
+            >
+              {s.label}
+            </span>
+          </div>
+        )
+      })}
     </>
   )
 }