@kolkrabbi/kol-shell 0.30.0 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.30.0",
+  "version": "0.32.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-component": "^0.150.1",
     "@kolkrabbi/kol-icons": "^0.25.0",
-    "@kolkrabbi/kol-framework": "^0.35.0",
-    "@kolkrabbi/kol-theme": "^0.111.0"
+    "@kolkrabbi/kol-framework": "^0.36.0",
+    "@kolkrabbi/kol-theme": "^0.119.0"
   },
   "files": [
     "src",

package/src/AppShell.jsx

@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useRef, useState } from 'react'
+import { Button } from '@kolkrabbi/kol-component'
 import NavRail from './NavRail.jsx'
 import { NavHiddenContext } from './navHidden.js'
 import { SettingsToggleContext } from './settingsToggle.js'
@@ -41,7 +42,17 @@ import TouchDeviceOverlay, { useTouchPrimary } from './TouchDeviceOverlay.jsx'
  * toggle lives on the settings page, not in the rail (user, 2026-08-28).
  * @param {string}  props.railToggleKey  a key that toggles the rail (e.g. '\\') — ignored while typing in a field;
  *                                        the rail comes back on every `currentPath` change (ShellHomeSystem, 2026-08-27)
- * @param {'shell'|'bare'|'overlay'} props.touch  the touch-primary policy (default 'shell' = the rail regardless):
+ * @param {'shell'|'bare'|'overlay'|'drawer'} props.touch  the touch-primary policy (default 'shell' = the rail regardless):
+ *                                        'drawer' takes the rail OFF-CANVAS below `drawerBelow`, hands its width
+ *                                        back to the content, and renders a trigger that brings it in over a scrim.
+ *                                        Tapping a destination closes it. (ShellRailNoDrawerOnMobile, kol-chess
+ *                                        2026-08-31: at 390 the 48px rail is 12.3% of the viewport, and
+ *                                        `railToggleKey` is a KEY — a phone has no keyboard, so on the device where
+ *                                        the rail costs most it could not be dismissed at all. `bare` was the only
+ *                                        other way to reclaim the width and it throws navigation away entirely.)
+ * @param {number} [props.drawerBelow=768]  viewport width under which `touch="drawer"` folds. A width, not a
+ *                                        pointer test: an iPad is coarse and has room, a narrow desktop window is
+ *                                        fine-pointered and does not.
  *                                        `bare` renders the children with NO shell on a coarse-pointer device unless
  *                                        localStorage `kol-desktop` is '1' (fxr's gate); `overlay` keeps the shell and
  *                                        mounts TouchDeviceOverlay once (monitor's)
@@ -95,11 +106,34 @@ export default function AppShell({
   navKeys = false,
   settingsPath,
   settingsKey,
+  drawerBelow = 768,
   children,
 }) {
   const [navHidden, setNavHidden] = useState(false)
   const coarse = useTouchPrimary()
 
+  /* DRAWER MODE. A width query, not a pointer one — see `drawerBelow`. */
+  const [narrow, setNarrow] = useState(
+    () => typeof window !== 'undefined' && window.matchMedia(`(max-width: ${drawerBelow - 1}px)`).matches,
+  )
+  useEffect(() => {
+    if (typeof window === 'undefined') return undefined
+    const mq = window.matchMedia(`(max-width: ${drawerBelow - 1}px)`)
+    const on = (e) => setNarrow(e.matches)
+    setNarrow(mq.matches)
+    mq.addEventListener('change', on)
+    return () => mq.removeEventListener('change', on)
+  }, [drawerBelow])
+  const drawer = touch === 'drawer' && narrow
+  const [drawerOpen, setDrawerOpen] = useState(false)
+  useEffect(() => { if (!drawer) setDrawerOpen(false) }, [drawer])
+  useEffect(() => {
+    if (!drawer || !drawerOpen) return undefined
+    const onKey = (e) => { if (e.key === 'Escape') setDrawerOpen(false) }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [drawer, drawerOpen])
+
   /* TOGGLING A DESTINATION (user 2026-08-30: "comma opens and closes the
    * settings page, and clicking the icon in sidebar opens and clicking again
    * closes"). The shell already owned two keyboard behaviours; this is a third
@@ -153,8 +187,16 @@ export default function AppShell({
     [settingsPath, toggleSettings, onNavigate],
   )
 
-  /* the rail comes back on every route change */
-  useEffect(() => { setNavHidden(false) }, [currentPath])
+  /* THE ROUTE CHANGE MEANS THE OPPOSITE IN EACH MODE. For `railToggleKey` the
+   * rail comes back on every navigation (ShellHomeSystem, 2026-08-27); for a
+   * drawer, tapping a destination must CLOSE it. The old unconditional
+   * `setNavHidden(false)` also made `navHidden` unusable as a consumer seam —
+   * child effects run before parent effects, so a consumer hiding the rail on a
+   * path change was overwritten in the same commit. */
+  useEffect(() => {
+    if (drawer) setDrawerOpen(false)
+    else setNavHidden(false)
+  }, [currentPath, drawer])
 
   /* 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
@@ -228,9 +270,35 @@ export default function AppShell({
         * margin closes with it — one variable, both sides. */}
       <div
         className="kol-app-shell min-h-dvh bg-surface-primary"
-        style={navHidden ? { '--kol-shell-rail-width': '0px' } : undefined}
+        /* A DRAWER ZEROES THE TOKEN TOO. Off-canvas means the content owns the
+         * whole viewport, so the same one variable that closes the content's
+         * margin for `navHidden` closes it here — the rail then takes its own
+         * `--kol-shell-drawer-width` rather than this token. */
+        data-rail-drawer={drawer ? (drawerOpen ? 'open' : 'closed') : undefined}
+        style={navHidden || drawer ? { '--kol-shell-rail-width': '0px' } : undefined}
       >
       {touch === 'overlay' && <TouchDeviceOverlay appName={appName} />}
+      {/* THE TRIGGER SHIPS HERE, not in every consumer's page header — the rail
+        * is the shell's, so the only way to reach it is too. Hamburger closed,
+        * × open; 32px square clears the 24px touch floor. */}
+      {drawer && (
+        <Button
+          variant="nav"
+          iconOnly={drawerOpen ? 'x' : 'hamburger'}
+          iconComponent={iconComponent}
+          aria-label={drawerOpen ? 'Close navigation' : 'Open navigation'}
+          aria-expanded={drawerOpen}
+          className="kol-shell-drawer-trigger"
+          onClick={() => setDrawerOpen((o) => !o)}
+        />
+      )}
+      {drawer && drawerOpen && (
+        <div
+          className="kol-shell-drawer-scrim"
+          onClick={() => setDrawerOpen(false)}
+          aria-hidden="true"
+        />
+      )}
       {!navHidden && (
         <Rail
           items={items}
@@ -240,6 +308,7 @@ export default function AppShell({
           /* the rail routes through `navigate`, so its settings row toggles like the key */
           onNavigate={navigate}
           iconComponent={iconComponent}
+          drawer={drawer}
         />
       )}
       {/* THE BACK OF THE BACK — surface-primary, always, in every app; the

package/src/Logomark.jsx

@@ -5,10 +5,39 @@ import { useState, useEffect } from 'react'
  * <img> renders a currentColor mark black in dark mode (invisible). Ported
  * verbatim from the kol-mirror cut (module-level cache; async resolve even on
  * cache hit — sync setState in an effect cascades renders).
+ *
+ * The fetched markup is SANITIZED before injection — `<style>`/`<script>`
+ * stripped, `on*` attributes dropped (LogomarkInlineStyleLeak, kol-chess
+ * 2026-09-01). An SVG *document* may legitimately carry its own `<style>` — a
+ * theme-aware favicon does — but once inlined, that `<style>` is
+ * DOCUMENT-GLOBAL: kol-chess pointed `svgUrl` at its favicon and every <svg>
+ * in the app took OS-keyed ink and ignored `data-theme`, presenting two
+ * packages away as "the theme toggle is broken". A mark that needs its own
+ * styling inlines it as attributes, not a stylesheet.
  */
 
 const svgCache = new Map()
 
+/* strip what must never escape into the host document: stylesheets (global
+ * once inlined), scripts and event handlers (this is a fetch → innerHTML
+ * boundary). DOMParser is the correct tool; the regex fallback only runs if
+ * the markup does not even parse as SVG. */
+function sanitizeSvg(svg) {
+  try {
+    const doc = new DOMParser().parseFromString(svg, 'image/svg+xml')
+    if (doc.querySelector('parsererror')) throw new Error('unparseable')
+    doc.querySelectorAll('style, script').forEach((el) => el.remove())
+    doc.querySelectorAll('*').forEach((el) => {
+      for (const a of [...el.attributes]) if (/^on/i.test(a.name)) el.removeAttribute(a.name)
+    })
+    return new XMLSerializer().serializeToString(doc)
+  } catch {
+    return svg
+      .replace(/<(style|script)[\s\S]*?<\/\1\s*>/gi, '')
+      .replace(/\son[a-z]+\s*=\s*("[^"]*"|'[^']*')/gi, '')
+  }
+}
+
 export default function Logomark({ svgUrl, size = 20, className = '', ...props }) {
   const [svgContent, setSvgContent] = useState(() => svgCache.get(svgUrl) || null)
 
@@ -16,7 +45,7 @@ export default function Logomark({ svgUrl, size = 20, className = '', ...props }
     if (!svgUrl) return
     let active = true
     Promise.resolve(
-      svgCache.get(svgUrl) ?? fetch(svgUrl).then(res => res.text()).then(svg => { svgCache.set(svgUrl, svg); return svg })
+      svgCache.get(svgUrl) ?? fetch(svgUrl).then(res => res.text()).then(raw => { const svg = sanitizeSvg(raw); svgCache.set(svgUrl, svg); return svg })
     )
       .then(svg => { if (active) setSvgContent(svg) })
       .catch(() => {})

package/src/NavRail.jsx

@@ -67,6 +67,9 @@ import Logomark from './Logomark.jsx'
  * @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"
  * @param {Function} onNavigate `(path) => void` — every click, the mark included
+ * @param {boolean} drawer  off-canvas mode: no grab, no drag, no token writes, rows always
+ *   labelled, and the rail sizes itself from `--kol-shell-drawer-width` (default 240px).
+ *   AppShell sets this from `touch="drawer"` — see ShellRailNoDrawerOnMobile, 2026-08-31.
  */
 const RAIL_W = '--kol-shell-rail-width'
 const CLOSED = 48
@@ -94,9 +97,15 @@ const openWidth = () => {
  * 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, snapRef) {
+function useRailDrag(railRef, grabRef, onSnap, snapRef, enabled = true) {
   useEffect(() => {
     const strip = grabRef.current, rail = railRef.current, root = document.documentElement
+    /* A DRAWER IS NOT A DRAGGABLE RAIL (ShellRailNoDrawerOnMobile, kol-chess
+     * 2026-08-31). In drawer mode the rail is off-canvas at a fixed width and
+     * the content owns the whole viewport, so the drag must not run at all —
+     * it writes `--kol-shell-rail-width` on `:root` per pointermove, which is
+     * exactly the inline token a consumer could not reach without `!important`. */
+    if (!enabled) return undefined
     if (!strip || !rail) return undefined
     gsap.set(root, { [RAIL_W]: `${CLOSED}px` })
     let drag = null
@@ -259,24 +268,29 @@ export default function NavRail({
   onNavigate,
   iconComponent,
   hidden = false,
+  drawer = false,
 }) {
   const railRef = useRef(null)
   const grabRef = useRef(null)
   const [railOpen, setRailOpen] = useState(false)
   const snapOpenRef = useRef(null)
+  /* the grab strip is not rendered in drawer mode, so the hook's ref stays null
+   * and it no-ops on its own — no second argument needed */
   useGrabEdge(grabRef)
-  useRailDrag(railRef, grabRef, setRailOpen, snapOpenRef)
+  useRailDrag(railRef, grabRef, setRailOpen, snapOpenRef, !drawer)
   if (hidden) return null
   const row = (item) => (
-    <RailItem key={item.path} {...item} currentPath={currentPath} onNavigate={onNavigate} iconComponent={iconComponent} railOpen={railOpen} onOpenRail={() => snapOpenRef.current?.()} />
+    <RailItem key={item.path} {...item} currentPath={currentPath} onNavigate={onNavigate} iconComponent={iconComponent} railOpen={drawer || railOpen} onOpenRail={() => snapOpenRef.current?.()} />
   )
   return (
     <div
       ref={railRef}
       className="kol-shell-rail bg-surface-primary border-r border-fg-08 fixed inset-y-0 left-0 flex flex-col items-start pt-4 pb-4 px-2 gap-2"
-      style={{ width: `var(${RAIL_W})` }}
+      /* A drawer takes its own width, NOT the live rail token — that token is
+        * zeroed in drawer mode so the content gets the whole viewport back. */
+      style={{ width: drawer ? 'var(--kol-shell-drawer-width, 240px)' : `var(${RAIL_W})` }}
     >
-      <div ref={grabRef} className="kol-rail-grab" />
+      {!drawer && <div ref={grabRef} className="kol-rail-grab" />}
       {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