@kolkrabbi/kol-shell 0.24.0 → 0.26.0

package/package.json

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

package/src/AppShell.jsx

@@ -1,6 +1,7 @@
-import { useEffect, useState } from 'react'
+import { useCallback, useEffect, useRef, useState } from 'react'
 import NavRail from './NavRail.jsx'
 import { NavHiddenContext } from './navHidden.js'
+import { SettingsToggleContext } from './settingsToggle.js'
 import TouchDeviceOverlay, { useTouchPrimary } from './TouchDeviceOverlay.jsx'
 
 /**
@@ -62,7 +63,23 @@ 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.
  */
+/* the physical-key name for a bound character. Only the keys people actually
+ * bind — a full layout table would be a lie about coverage. */
+const CODE_FOR_KEY = {
+  ',': 'Comma', '.': 'Period', '/': 'Slash', ';': 'Semicolon', "'": 'Quote',
+  '[': 'BracketLeft', ']': 'BracketRight', '\\': 'Backslash', '`': 'Backquote',
+  '-': 'Minus', '=': 'Equal',
+}
+
 export default function AppShell({
   items,
   bottomItems,
@@ -76,11 +93,66 @@ 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) => {
+      /* MATCH THE PHYSICAL KEY (SettingsToggleGestureConsumerSeam, kol-fxr
+       * 2026-08-30). Option rewrites `e.key` on macOS — **the chord for `,` is
+       * `≤`** — so an `e.key` comparison silently drops it while the bare key
+       * works, which is the worst way to fail. `e.code` is the same physical key
+       * either way; it is why the Option-digit handler above reads `Digit1…`
+       * rather than `¡ ™ £`. `e.key` still matches too, so a character with no
+       * entry in the table below is unaffected. */
+      const wanted = CODE_FOR_KEY[settingsKey]
+      if (!(e.key === settingsKey || (wanted && e.code === wanted)) || 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 +194,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 */ }
@@ -136,6 +208,7 @@ export default function AppShell({
 
   return (
     <NavHiddenContext.Provider value={{ navHidden, setNavHidden }}>
+      <SettingsToggleContext.Provider value={toggleSettings}>
       {/* `kol-app-shell` = the app tier: neutral ::selection (kol-theme).
         * A hidden rail zeroes the live width token, so the content's own
         * margin closes with it — one variable, both sides. */}
@@ -150,7 +223,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}
         />
       )}
@@ -162,6 +236,7 @@ export default function AppShell({
         {children}
       </div>
       </div>
+      </SettingsToggleContext.Provider>
     </NavHiddenContext.Provider>
   )
 }

package/src/index.js

@@ -12,6 +12,7 @@
  */
 export { default as AppShell } from './AppShell.jsx'
 export { NavHiddenContext, useNavHidden } from './navHidden.js'
+export { SettingsToggleContext, useSettingsToggle } from './settingsToggle.js'
 export { default as NavRail } from './NavRail.jsx'
 export { default as PageShell, PageBleed } from './PageShell.jsx'
 export { default as PageHeader } from './PageHeader.jsx'

package/src/settingsToggle.js

@@ -0,0 +1,22 @@
+import { createContext, useContext } from 'react'
+
+/* Settings-toggle context — own file so AppShell exports only components
+ * (the react-refresh constraint `navHidden.js` was split out for).
+ *
+ * WHY A HOOK AND NOT JUST THE PROPS (SettingsToggleGestureConsumerSeam, kol-fxr
+ * 2026-08-30). `settingsKey` navigates unconditionally, and that is wrong for an
+ * app whose settings are sometimes a DRAWER: on kol-fxr's `/editor`, `,` opens
+ * the panel in place and must not leave the canvas. Its rule is "open whatever
+ * settings is available", which only the app can know.
+ *
+ * So the shell keeps what is genuinely shared — the return path, and the rail
+ * row toggling — and hands out the toggle for a consumer that owns the gesture.
+ * Without this, fxr had to keep its whole local copy (a `lastPage` ref and a
+ * branch in `onNavigate`) to keep one line of app-specific routing, which is
+ * the duplication `settingsPath` exists to end.
+ *
+ * No-op when `settingsPath` is unset, and safe outside an AppShell — a hook
+ * that throws on a missing provider would make it unusable in exactly the
+ * conditional places it is for. */
+export const SettingsToggleContext = createContext(null)
+export const useSettingsToggle = () => useContext(SettingsToggleContext) ?? (() => {})