@kolkrabbi/kol-shell 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.24.0",
+  "version": "0.25.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.133.0",
+    "@kolkrabbi/kol-component": "^0.135.0",
     "@kolkrabbi/kol-icons": "^0.25.0",
     "@kolkrabbi/kol-framework": "^0.35.0",
-    "@kolkrabbi/kol-theme": "^0.97.0"
+    "@kolkrabbi/kol-theme": "^0.99.0"
   },
   "files": [
     "src",

package/src/AppShell.jsx

@@ -1,4 +1,4 @@
-import { useEffect, useState } from 'react'
+import { useCallback, useEffect, useRef, useState } from 'react'
 import NavRail from './NavRail.jsx'
 import { NavHiddenContext } from './navHidden.js'
 import TouchDeviceOverlay, { useTouchPrimary } from './TouchDeviceOverlay.jsx'
@@ -62,6 +62,14 @@ import TouchDeviceOverlay, { useTouchPrimary } from './TouchDeviceOverlay.jsx'
  *                                        content wrapper, so a page root that is not `PageShell` reads it too.
  *                                        Default none — unset renders exactly as before. A prop, not a token
  *                                        an app binds, because fxr's stylesheet is imports-only by rule.
+ * @param {string}  props.settingsPath  a destination the shell TOGGLES rather than navigates to
+ *                                        (SettingsToggleGesture, user 2026-08-30): pressing the key or
+ *                                        picking its rail row again returns you where you were, instead of
+ *                                        stranding you on the page. Three repos had built this each for
+ *                                        themselves. Unset = every destination behaves exactly as before.
+ * @param {string}  props.settingsKey   the key that toggles `settingsPath` — `','` in the apps that asked.
+ *                                        Bare and with ⌥, ignored while typing in a field. Needs
+ *                                        `settingsPath`; alone it does nothing.
  */
 export default function AppShell({
   items,
@@ -76,11 +84,58 @@ export default function AppShell({
   appName,
   pageWash,
   navKeys = false,
+  settingsPath,
+  settingsKey,
   children,
 }) {
   const [navHidden, setNavHidden] = useState(false)
   const coarse = useTouchPrimary()
 
+  /* 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
+   * of the same kind, and it was about to be written three times — fxr, mirror
+   * and monitor all render this page.
+   *
+   * The only new state is WHERE YOU CAME FROM. Navigation stays the consumer's
+   * (`onNavigate`); the shell just decides which path to hand back. `useRef`,
+   * not state: the return path must not re-render anything when it changes. */
+  const returnPath = useRef(null)
+  const toggleSettings = useCallback(() => {
+    if (!settingsPath) return
+    if (currentPath === settingsPath) {
+      /* nothing remembered (deep link straight onto /settings) → the mark, which
+       * is where the rail's first row goes anyway. Never a dead key. */
+      onNavigate?.(returnPath.current ?? '/')
+      returnPath.current = null
+    } else {
+      returnPath.current = currentPath
+      onNavigate?.(settingsPath)
+    }
+  }, [settingsPath, currentPath, onNavigate])
+
+  useEffect(() => {
+    if (!settingsKey || !settingsPath) return undefined
+    const onKey = (e) => {
+      if (e.key !== settingsKey || e.metaKey || e.ctrlKey) return
+      const t = e.target
+      if (t?.isContentEditable || /^(INPUT|TEXTAREA|SELECT)$/.test(t?.tagName)) return
+      e.preventDefault()
+      toggleSettings()
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [settingsKey, settingsPath, toggleSettings])
+
+  /* the rail row for that path toggles too — one gesture, two ways to reach it */
+  const navigate = useCallback(
+    (path, ...rest) => {
+      if (settingsPath && path === settingsPath) return toggleSettings()
+      return onNavigate?.(path, ...rest)
+    },
+    [settingsPath, toggleSettings, onNavigate],
+  )
+
   /* the rail comes back on every route change */
   useEffect(() => { setNavHidden(false) }, [currentPath])
   /* one key toggles the rail — never while typing in a field */
@@ -122,11 +177,11 @@ export default function AppShell({
       const path = navPaths[Number(m[1]) - 1]
       if (!path) return
       e.preventDefault()
-      onNavigate?.(path)
+      navigate(path)
     }
     window.addEventListener('keydown', onKey)
     return () => window.removeEventListener('keydown', onKey)
-  }, [navKeys, navPaths.join('\u0000'), onNavigate]) // eslint-disable-line react-hooks/exhaustive-deps
+  }, [navKeys, navPaths.join('\u0000'), navigate]) // eslint-disable-line react-hooks/exhaustive-deps
 
   let wantsDesktop = false
   try { wantsDesktop = typeof localStorage !== 'undefined' && localStorage.getItem('kol-desktop') === '1' } catch { /* storage blocked */ }
@@ -150,7 +205,8 @@ export default function AppShell({
           bottomItems={bottomItems}
           logomark={logomark}
           currentPath={currentPath}
-          onNavigate={onNavigate}
+          /* the rail routes through `navigate`, so its settings row toggles like the key */
+          onNavigate={navigate}
           iconComponent={iconComponent}
         />
       )}