@kolkrabbi/kol-shell 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-shell",
-  "version": "0.3.0",
+  "version": "0.4.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-icons": "^0.17.0",
-    "@kolkrabbi/kol-component": "^0.44.0",
-    "@kolkrabbi/kol-theme": "^0.42.2",
-    "@kolkrabbi/kol-framework": "^0.20.1"
+    "@kolkrabbi/kol-component": "^0.46.0",
+    "@kolkrabbi/kol-framework": "^0.22.0",
+    "@kolkrabbi/kol-theme": "^0.43.1",
+    "@kolkrabbi/kol-icons": "^0.17.0"
   },
   "files": [
     "src",

package/src/ShortcutsOverlay.jsx

@@ -2,15 +2,50 @@ import { useEffect } from 'react'
 
 /**
  * ShortcutsOverlay — the keyboard-shortcut sheet: blurred scrim, centred
- * panel, one flat 2-col grid (label · keys), Esc / backdrop-click close.
+ * panel, a 2-col grid (label · keys), Esc / backdrop-click close.
  * Ported from the shared cut (mirror's, "copied from kol-monitor").
  *
  * `shortcuts` is a prop — feed the SAME array your settings page renders
  * (both repos hand-maintained the list twice and both pairs drifted).
  * Stacks at `--kol-z-modal`, above the rail's sticky tier.
  *
- * @param {Array} props.shortcuts - `[{ label, keys }]`
+ * TWO FORMS, DETECTED ON SHAPE (ShortcutsOverlaySections, kol-fxr 2026-08-15):
+ *
+ *   flat       `[{ label, keys }]`                  — one grid, as shipped
+ *   sectioned  `[{ section, items: [{label,keys}] }]` — headings between groups
+ *
+ * The flat form renders EXACTLY as it did before, so no existing caller moves.
+ * The sectioned form exists because a real keymap is grouped — kol-fxr's is
+ * Edit · Selection · Layer · Tools · View, and its `shortcutsBySection()`
+ * already emits this shape — and flattening it to adopt this component would
+ * have lost the grouping. That consumer kept a 99-line local overlay instead,
+ * which is the duplication this component exists to end.
+ *
+ * ONE GRID, NOT NESTED ONES. The headings span both columns
+ * (`gridColumn: 1 / -1`) so every `keys` cell in the sheet stays on the same
+ * axis — nesting a grid per section would let each group compute its own
+ * column width and the keys would stagger down the panel.
+ *
+ * `keys` is a DISPLAY STRING and is never bound — this component shows a
+ * keymap, it does not own one. Formatting a combo (⌘⇧Z) is the consumer's,
+ * next to wherever the binding actually lives.
+ *
+ * @param {Array} props.shortcuts - `[{ label, keys }]` or `[{ section, items }]`
+ * @param {Function} props.onClose
  */
+
+const isSectioned = (list) => Array.isArray(list?.[0]?.items)
+
+/* One row of the shared grid. `contents` keeps the pair on the parent grid
+ * rather than making the wrapper a cell of its own. */
+function Row({ label, keys }) {
+  return (
+    <span className="contents">
+      <span>{label}</span><span className="text-fg-96">{keys}</span>
+    </span>
+  )
+}
+
 export default function ShortcutsOverlay({ shortcuts = [], onClose }) {
   useEffect(() => {
     const onKey = (e) => { if (e.key === 'Escape') onClose?.() }
@@ -18,6 +53,8 @@ export default function ShortcutsOverlay({ shortcuts = [], onClose }) {
     return () => window.removeEventListener('keydown', onKey)
   }, [onClose])
 
+  const sectioned = isSectioned(shortcuts)
+
   return (
     <div
       onClick={onClose}
@@ -25,11 +62,23 @@ export default function ShortcutsOverlay({ shortcuts = [], onClose }) {
       style={{ display: 'grid', placeItems: 'center', backdropFilter: 'blur(2px)', zIndex: 'var(--kol-z-modal)' }}
     >
       <div className="text-fg-64 kol-helper-12 bg-surface-primary border border-fg-16" style={{ display: 'grid', gridTemplateColumns: 'auto auto', gap: '10px 62px', padding: 24, borderRadius: 4 }}>
-        {shortcuts.map(({ label, keys }) => (
-          <span key={label} className="contents">
-            <span>{label}</span><span className="text-fg-96">{keys}</span>
-          </span>
-        ))}
+        {sectioned
+          ? shortcuts.map(({ section, items = [] }, i) => (
+            <span key={section} className="contents">
+              <span
+                className="text-fg-32"
+                style={{ gridColumn: '1 / -1', marginTop: i === 0 ? 0 : 14 }}
+              >
+                {section}
+              </span>
+              {items.map(({ label, keys }) => (
+                <Row key={`${section}:${label}`} label={label} keys={keys} />
+              ))}
+            </span>
+          ))
+          : shortcuts.map(({ label, keys }) => (
+            <Row key={label} label={label} keys={keys} />
+          ))}
       </div>
     </div>
   )