@kolkrabbi/kol-shell 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.11.0",
+  "version": "0.13.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",
@@ -13,17 +13,17 @@
   },
   "peerDependencies": {
     "@kolkrabbi/kol-component": ">=0.108.0",
-    "@kolkrabbi/kol-framework": ">=0.20.0",
+    "@kolkrabbi/kol-framework": ">=0.31.0",
     "@kolkrabbi/kol-icons": ">=0.16.0",
-    "@kolkrabbi/kol-theme": ">=0.68.0",
+    "@kolkrabbi/kol-theme": ">=0.80.0",
     "react": "^18.3.0 || ^19.0.0",
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-icons": "^0.22.0",
-    "@kolkrabbi/kol-component": "^0.110.0",
-    "@kolkrabbi/kol-theme": "^0.72.0",
-    "@kolkrabbi/kol-framework": "^0.28.0"
+    "@kolkrabbi/kol-component": "^0.118.3",
+    "@kolkrabbi/kol-framework": "^0.31.0",
+    "@kolkrabbi/kol-icons": "^0.24.0",
+    "@kolkrabbi/kol-theme": "^0.80.0"
   },
   "files": [
     "src",

package/src/AppShell.jsx

@@ -4,17 +4,25 @@ import { NavHiddenContext } from './navHidden.js'
 import TouchDeviceOverlay, { useTouchPrimary } from './TouchDeviceOverlay.jsx'
 
 /**
- * AppShell — layout root: fixed NavRail + content offset by the rail width.
- * No header, no footer. Router-agnostic: render your router's element (e.g.
- * `<Outlet/>`) as children and wire `currentPath`/`onNavigate` from your
- * router at the call site.
+ * AppShell — layout root: the rail + the content column. No header, no
+ * footer. Router-agnostic: render your router's element (e.g. `<Outlet/>`) as
+ * children and wire `currentPath`/`onNavigate` from your router at the call
+ * site.
  *
- * Rail width is `--kol-shell-rail-width` (kol-theme) — read by both the rail
- * and the offset so they can never disagree.
+ * THE RAIL IS A SIDENAV (RailSideNavPixelParity, kol-fxr 2026-08-28 — user:
+ * "same component both states super nice"): since 0.13.0 the root is the
+ * brand grid, `.kol-brand-layout` (kol-framework.css — `--kol-sidenav-w` ×
+ * `minmax(0, 1fr)`, the collapsed column on the `data-sidenav` stamp, the
+ * ≤1024 forced rail and the ≤767 drawer), and `NavRail` mounts kol-framework's
+ * `SideNav` collapsed in it. The grab edge opens it to the brand sidebar and
+ * the drag is the transition; the content column follows the grid, so the old
+ * fixed rail + `margin-left` offset is gone. `--kol-shell-rail-width`
+ * (kol-theme ≥0.80.0) is LIVE — the sidenav's width in its current state —
+ * for consumers that offset a fixed element by it; hidden rail = `0px`.
  *
  * @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 }` — top mark, navigates to '/'
+ * @param {Object} props.logomark      `{ svgUrl, title }` — the rail's footer mark, navigates to '/'
  * @param {string} props.currentPath   the router's current pathname
  * @param {Function} props.onNavigate  `(path) => void`
  * @param {ElementType} props.iconComponent  icon renderer seam (see Button)
@@ -26,6 +34,13 @@ import TouchDeviceOverlay, { useTouchPrimary } from './TouchDeviceOverlay.jsx'
  *                                        localStorage `kol-desktop` is '1' (fxr's gate); `overlay` keeps the shell and
  *                                        mounts TouchDeviceOverlay once (monitor's)
  * @param {string}  props.appName       TouchDeviceOverlay's subject
+ * @param {boolean} props.navKeys       Option+1…9 navigates to `items[n-1].path` through `onNavigate` — the
+ *                                        rail-order counterpart of `railToggleKey` (AppShellNavKeys, kol-monitor
+ *                                        2026-08-28 — user: "make command or alt 1234 go from home 1 2 3 4 in the
+ *                                        sidenav without clicking"). Option, not Command: ⌘1–9 is the browser's
+ *                                        tab switch. Matched on `e.code` (`Digit1`…) because Opt+digit yields
+ *                                        `¡ ™ £ ¢` as `e.key` on macOS; ignored while typing in a field; only
+ *                                        digits with an item; `preventDefault` on a match. Default off.
  * @param {string}  props.pageWash      a CSS colour painted by `PageShell` OVER the shell's primary back
  *                                        (ShellPageWash, kol-monitor 2026-08-27 — user: "the back of the back
  *                                        should be primary — then you can just add transparent on top to step
@@ -47,6 +62,7 @@ export default function AppShell({
   touch = 'shell',
   appName,
   pageWash,
+  navKeys = false,
   children,
 }) {
   const [navHidden, setNavHidden] = useState(false)
@@ -68,6 +84,23 @@ export default function AppShell({
     return () => window.removeEventListener('keydown', onKey)
   }, [railToggleKey])
 
+  /* Option+digit → the rail item in that position (never while typing) */
+  useEffect(() => {
+    if (!navKeys) return undefined
+    const onKey = (e) => {
+      const m = /^Digit([1-9])$/.exec(e.code)
+      if (!m || !e.altKey || e.metaKey || e.ctrlKey) return
+      const t = e.target
+      if (t?.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(t?.tagName)) return
+      const item = items?.[Number(m[1]) - 1]
+      if (!item?.path) return
+      e.preventDefault()
+      onNavigate?.(item.path)
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [navKeys, items, onNavigate])
+
   let wantsDesktop = false
   try { wantsDesktop = typeof localStorage !== 'undefined' && localStorage.getItem('kol-desktop') === '1' } catch { /* storage blocked */ }
   /* the wash variable rides the bare wrapper too (custom properties inherit
@@ -76,8 +109,13 @@ export default function AppShell({
 
   return (
     <NavHiddenContext.Provider value={{ navHidden, setNavHidden }}>
-      {/* `kol-app-shell` = the app tier: neutral ::selection (kol-theme) */}
-      <div className="kol-app-shell contents">
+      {/* `kol-app-shell` = the app tier: neutral ::selection (kol-theme).
+        * `kol-brand-layout` = the sidenav grid; a hidden rail collapses the
+        * grid to the content column and zeroes the live width token. */}
+      <div
+        className="kol-app-shell kol-brand-layout min-h-dvh bg-surface-primary"
+        style={navHidden ? { gridTemplateColumns: 'minmax(0, 1fr)', '--kol-shell-rail-width': '0px' } : undefined}
+      >
       {touch === 'overlay' && <TouchDeviceOverlay appName={appName} />}
       {!navHidden && (
         <NavRail
@@ -92,7 +130,7 @@ export default function AppShell({
       )}
       {/* THE BACK OF THE BACK — surface-primary, always, in every app; the
         * page paints its wash over it (ShellPageWash). */}
-      <div className="bg-surface-primary" style={{ marginLeft: navHidden ? 0 : 'var(--kol-shell-rail-width)', '--kol-shell-page-wash': pageWash }}>
+      <div className="bg-surface-primary min-w-0" style={{ '--kol-shell-page-wash': pageWash }}>
         {children}
       </div>
       </div>

package/src/NavRail.jsx

@@ -1,35 +1,23 @@
-import { Button } from '@kolkrabbi/kol-component'
-import { ThemeToggle } from '@kolkrabbi/kol-framework'
+import { SideNav } from '@kolkrabbi/kol-framework'
 import Logomark from './Logomark.jsx'
 
 /**
- * NavRail — the fixed 48px icon rail. Geometry/stacking live in kol-theme's
- * `.kol-shell-rail`; surface/border ride the theme utility classes.
+ * NavRail — AppShell's rail, which IS kol-framework's `SideNav`
+ * (RailSideNavPixelParity, kol-fxr 2026-08-28 — user, on the brand sidebar's
+ * drag: "same component both states super nice"). Until 0.13.0 this was its
+ * own fixed 48px icon rail, and the first app to run it beside a collapsed
+ * SideNav on adjacent routes measured every icon moving on the route change
+ * (48 vs 56 wide, 20 vs 16px glyphs, 40 vs 38 pitch, first glyph at y 76 vs
+ * 26). There is no second component now: this file maps the shell's flat
+ * `{ icon, path, label }` items onto the sidenav's tree and mounts it
+ * collapsed — the pill-marked grab edge opens it to the brand sidebar, the
+ * drag is the transition, and it stays a rail while it navigates
+ * (`expandOnSelect={false}`).
  *
- * Items are flat `{ icon, path, label }` — deliberately NOT kol-framework
- * SideNav's two-level navTree; different component, not a variant.
- *
- * Active state (user ruling 2026-08-12, carried natively in kol-theme):
- * ink `--kol-oq-96` in every state, hover = the `--kol-oq-04` wash, active
- * route = that wash held on via `aria-current="page"` — never
- * `selected`/`pressed`; navigation is location, not a toggled tool.
+ * The bottom, specified once: theme slot → `bottomItems` (pinned rows) →
+ * footer. The `logomark` moved from the top of the rail to the footer — the
+ * brand sidebar's mark sits there, and the first glyph's y is the sidenav's.
  */
-
-function RailItem({ icon, path, label, active, onNavigate, iconComponent }) {
-  return (
-    <Button
-      iconOnly={icon}
-      iconSize={20}
-      variant="nav"
-      size="md"
-      aria-current={active ? 'page' : undefined}
-      onClick={() => onNavigate?.(path)}
-      title={label}
-      iconComponent={iconComponent}
-    />
-  )
-}
-
 export default function NavRail({
   items = [],
   bottomItems = [],
@@ -41,42 +29,32 @@ export default function NavRail({
   hidden = false,
 }) {
   if (hidden) return null
-  const isActive = (path) =>
-    path === '/' ? currentPath === '/' : currentPath.startsWith(path)
-
+  const node = (item) => ({ id: item.path, label: item.label, icon: item.icon, to: item.path })
+  /* the shell's route match: '/' exact, anything else by prefix */
+  const isActive = (to) => (to === '/' ? currentPath === '/' : currentPath.startsWith(to))
   return (
-    <div className="kol-shell-rail bg-surface-tertiary border-r border-fg-04">
-      {logomark && (
-        <div
+    <SideNav
+      navTree={items.map(node)}
+      bottomItems={bottomItems.map(node)}
+      currentPath={currentPath}
+      isActive={isActive}
+      onNavigate={(e, to) => onNavigate?.(to)}
+      iconComponent={iconComponent}
+      themeToggle={themeToggle}
+      expandOnSelect={false}
+      defaultCollapsed
+      hairline
+      footer={logomark ? (
+        <button
+          type="button"
+          className="inline-flex items-center bg-transparent border-0 p-0 cursor-pointer text-body hover:text-emphasis"
           onClick={() => onNavigate?.('/')}
-          className="text-oq-96"
-          style={{ cursor: 'pointer', marginBottom: 16, paddingTop: 4 }}
           title={logomark.title}
+          aria-label={logomark.title}
         >
           <Logomark svgUrl={logomark.svgUrl} size={20} />
-        </div>
-      )}
-      {items.map((item) => (
-        <RailItem
-          key={item.path}
-          {...item}
-          active={isActive(item.path)}
-          onNavigate={onNavigate}
-          iconComponent={iconComponent}
-        />
-      ))}
-      <div style={{ flex: 1 }} />
-      {themeToggle && <ThemeToggle label={false} style={{ color: 'var(--kol-oq-96)' }} />}
-      {bottomItems.map((item) => (
-        <RailItem
-          key={item.path}
-          {...item}
-          active={isActive(item.path)}
-          onNavigate={onNavigate}
-          iconComponent={iconComponent}
-        />
-      ))}
-      <div style={{ height: 8 }} />
-    </div>
+        </button>
+      ) : false}
+    />
   )
 }

package/src/index.js

@@ -4,7 +4,8 @@
  * Lifted 2026-08-14 from the hand-copied twins in kol-monitor ("Monitor") and
  * kol-mirror ("Hall of Mirrors") — AppShellSet lobby brief. App chrome, not
  * site chrome: kol-framework's SideNav/footer/heroes are the site register;
- * this is the fixed 48px rail + page scaffolds an application is built from.
+ * this is the rail (a collapsed kol-framework SideNav since 0.13.0 —
+ * RailSideNavPixelParity) + the page scaffolds an application is built from.
  *
  * Router-agnostic: no react-router dependency — pass `currentPath` +
  * `onNavigate` and render your router's element as children.