@kolkrabbi/kol-framework 0.32.0 → 0.34.0

package/kol-framework.css

@@ -146,6 +146,21 @@ body {
   position: relative;
   padding: 0.5rem 2.5rem 0.5rem 1.5rem;
 }
+/* THE HEADER SLOT (RailLogomarkAtTop, kol-fxr 2026-08-28 — user, on the
+ * raven in the footer: "why did you move the logo from top to bottom?"): the
+ * `header` node sits ABOVE the tree, outside the scroll region, in the hop's
+ * own horizontal geometry — its `.kol-sidenav-hop-icon` centres on the icon
+ * column collapsed and left-aligns to it expanded, its `.kol-sidenav-hop-label`
+ * hides with the labels. 1rem above it; the scroll region's own top pad is the
+ * gap to the first row, so the first tree glyph's y is one number in every
+ * consumer that passes the same header. */
+.kol-sidenav-header {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  width: 100%;
+  padding: 1rem 2.5rem 0 1.5rem;
+}
 /* the caret rides a PLAIN span (Icon stamps inline-flex on its own element,
  * which would outrank the collapsed display:none) */
 .kol-sidenav-hop-caret {
@@ -208,6 +223,7 @@ body {
 :root[data-sidenav="collapsed"] .kol-brand-layout { grid-template-columns: var(--kol-sidenav-w-collapsed) minmax(0, 1fr); }
 :root[data-sidenav="collapsed"] .kol-sidenav-hops { padding: 0 0 var(--kol-spacing-4); margin-bottom: var(--kol-spacing-4); }
 :root[data-sidenav="collapsed"] .kol-sidenav-hop { padding: var(--kol-spacing-2) 0; justify-content: center; gap: 0; }
+:root[data-sidenav="collapsed"] .kol-sidenav-header { padding: 1rem 0 0; justify-content: center; gap: 0; }
 :root[data-sidenav="collapsed"] .kol-sidenav-hop-label { display: none; }
 :root[data-sidenav="collapsed"] .kol-sidenav-body { display: none; }
 :root[data-sidenav="collapsed"] .kol-sidenav-hop-count,
@@ -281,6 +297,7 @@ body {
   .kol-brand-layout { grid-template-columns: var(--kol-sidenav-w-collapsed) minmax(0, 1fr); }
   .kol-sidenav-hops { padding: 0 0 var(--kol-spacing-4); margin-bottom: var(--kol-spacing-4); }
   .kol-sidenav-hop { padding: var(--kol-spacing-2) 0; justify-content: center; gap: 0; }
+  .kol-sidenav-header { padding: 1rem 0 0; justify-content: center; gap: 0; }
   .kol-sidenav-hop-label { display: none; }
   .kol-sidenav-section { display: none; }
   .kol-sidenav-body { display: none; }
@@ -303,6 +320,7 @@ body {
   .kol-sidenav.is-drawer-open { transform: translateX(0); }
   /* Restore expanded labels + body inside the open drawer (override the rail rules above). */
   .kol-sidenav.is-drawer-open .kol-sidenav-hop { padding: 8px 0; justify-content: flex-start; gap: 12px; }
+  .kol-sidenav.is-drawer-open .kol-sidenav-header { padding: 1rem 2.5rem 0 1.5rem; justify-content: flex-start; gap: 12px; }
   .kol-sidenav.is-drawer-open .kol-sidenav-hop-label { display: inline; }
   .kol-sidenav.is-drawer-open .kol-sidenav-section { display: block; }
   .kol-sidenav.is-drawer-open .kol-sidenav-body { display: block; }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-framework",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "KOL app shell — sidenav, layout, theme toggle, footer, heroes + brand color layer. SideNav takes nav data as props so the tree stays app-local.",
   "license": "MIT",
   "type": "module",
@@ -20,8 +20,8 @@
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.118.3",
-    "@kolkrabbi/kol-icons": "^0.24.0"
+    "@kolkrabbi/kol-icons": "^0.24.0",
+    "@kolkrabbi/kol-component": "^0.119.0"
   },
   "files": [
     "src",

package/src/SideNav.jsx

@@ -1,5 +1,6 @@
 import { NavLink, useLocation } from 'react-router-dom'
-import { useRef, useState } from 'react'
+import { useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { createPortal } from 'react-dom'
 import { Icon } from '@kolkrabbi/kol-icons'
 import { Tooltip } from '@kolkrabbi/kol-component'
 import ThemeToggle from './ThemeToggle'
@@ -71,6 +72,26 @@ import useDragResize from './useDragResize'
  * pixel (fxr measured 48 vs 56 wide, 20 vs 16px glyphs, 40 vs 38 pitch, first
  * glyph at y 76 vs 26 between the old NavRail and this rail collapsed). The
  * seams the shell needed, all opt-in, a tree with none of them renders as before:
+ *   `header`           a node ABOVE the tree, outside the scroll region, in the
+ *                      hop's geometry (`.kol-sidenav-header`, kol-framework.css)
+ *                      — the app's logomark (RailLogomarkAtTop, 2026-08-28 —
+ *                      user: "why did you move the logo from top to bottom?").
+ *                      Give it a `.kol-sidenav-hop-icon` span (20px mark on the
+ *                      icon column) and, optionally, a `.kol-sidenav-hop-label`;
+ *                      both follow the collapse. Same node in every consumer =
+ *                      the first tree glyph at one y — the parity contract
+ *   PANEL LEAF        `{ id, label, icon, panel }` — a top-level node (tree or
+ *                      `bottomItems`) whose row is a DISCLOSURE: click opens,
+ *                      click again closes, lit while open (RailSettingsDisclosure,
+ *                      kol-fxr 2026-08-28 — user: "sidebar setting should open
+ *                      close on click and click again" · "put the theme toggle in
+ *                      the settings and out of the sidebar"). `panel` is a node or
+ *                      `({ collapsed, close }) => node`, PORTALLED to <body>
+ *                      directly above the row at the rail's own width (left/width
+ *                      from the aside, bottom = viewport − the row's top,
+ *                      `--kol-z-tooltip`), so it works collapsed (icon column)
+ *                      and expanded (rows) alike. Escape closes; any navigation
+ *                      or dispatch closes. fxr's RailSettings.jsx, promoted.
  *   `bottomItems`      top-level nodes pinned BELOW the theme slot, above the
  *                      footer (the shell pins theme → Settings; a Settings row in
  *                      the tree landed above the theme instead — "same rail, two
@@ -143,6 +164,7 @@ function SideNavInner({
    * name; a rail floating over media and a rail without a line are different
    * choices. */
   hairline = false,
+  header,
   bottomItems = [],
   footer,
   themeToggle = true,
@@ -163,12 +185,14 @@ function SideNavInner({
   const handleNavigate = (e, to) => {
     onNavigate?.(e, to)
     onCloseDrawer?.()
+    setOpenPanel(null)
     if (collapsed && expandOnSelect) toggleCollapsed()
   }
   /* an action leaf dispatches — same drawer / rail behaviour as a navigation */
   const handleSelect = (e, row) => {
     row.onSelect(e)
     onCloseDrawer?.()
+    setOpenPanel(null)
     if (collapsed && expandOnSelect) toggleCollapsed()
   }
   /* the route leaf: NavLink under a router, `<a href>` on the agnostic seam */
@@ -182,6 +206,9 @@ function SideNavInner({
    * 2026-08-01) — arriving somewhere must not silently close wherever you
    * were. Loads closed, in-memory only (elder ruling 2026-08-06). */
   const [openCats, setOpenCats] = useState(() => new Set())
+  /* the ONE open panel leaf (by id) and where its panel sits */
+  const [openPanel, setOpenPanel] = useState(null)
+  const [panelBox, setPanelBox] = useState(null)
   const toggleCat = (id) => setOpenCats((prev) => {
     const next = new Set(prev)
     next.has(id) ? next.delete(id) : next.add(id)
@@ -195,6 +222,29 @@ function SideNavInner({
   const asideRef = useRef(null)
   const { collapsed, toggleCollapsed, grabProps } = useDragResize(asideRef, { defaultCollapsed })
 
+  /* the panel's anchor: its row — the panel's bottom edge meets the row's top
+   * edge, its width is the rail's; re-placed on resize and on collapse */
+  useLayoutEffect(() => {
+    if (!openPanel) { setPanelBox(null); return undefined }
+    const place = () => {
+      const rail = asideRef.current
+      const row = rail?.querySelector(`[data-panel-trigger="${CSS.escape(String(openPanel))}"]`)
+      if (!rail || !row) return
+      const rr = rail.getBoundingClientRect(), tr = row.getBoundingClientRect()
+      setPanelBox({ left: rr.left, width: rr.width, bottom: window.innerHeight - tr.top })
+    }
+    place()
+    window.addEventListener('resize', place)
+    return () => window.removeEventListener('resize', place)
+  }, [openPanel, collapsed])
+  useEffect(() => {
+    if (!openPanel) return undefined
+    const onKey = (e) => { if (e.key === 'Escape') setOpenPanel(null) }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [openPanel])
+  const panelNode = openPanel != null ? [...navTree, ...bottomItems].find((c) => c.id === openPanel) : null
+
   /* Rows under a category: a leaf is a NavLink; a group is a non-routing
    * header over its own rows, one step further in (recursive). A group lights
    * up the way a category does — when one of its leaves is the current route. */
@@ -244,11 +294,12 @@ function SideNavInner({
               const pages = pagesOf(cat)
               const isOpen = openCats.has(cat.id)
               const isLink = !pages.length && cat.to
-              const isAction = !pages.length && !cat.to && cat.onSelect
+              const isPanel = !pages.length && !cat.to && !!cat.panel
+              const isAction = !pages.length && !cat.to && !isPanel && cat.onSelect
               /* THE COLLAPSE RULE: no icon, no route, no action = a LABEL over
                * its rows, not a row — `.kol-sidenav-section` hides on collapse
                * and the icon rows beneath it stay */
-              if (!cat.icon && !cat.to && !cat.onSelect) {
+              if (!cat.icon && !cat.to && !cat.onSelect && !cat.panel) {
                 return (
                   <li key={cat.id ?? `${cat.label}-${ci}`} className="relative">
                     <div className="kol-sidenav-section kol-eyebrow text-strong">{cat.label}</div>
@@ -273,6 +324,17 @@ function SideNavInner({
                   {glyph}
                   <span className="kol-sidenav-hop-label flex-1 min-w-0">{cat.label}</span>
                 </RouteLeaf>
+              ) : isPanel ? (
+                <button
+                  type="button"
+                  data-panel-trigger={cat.id}
+                  className={`${rowCls} bg-transparent border-0 cursor-pointer text-left${openPanel === cat.id ? ' is-active' : ''}`}
+                  aria-expanded={openPanel === cat.id}
+                  onClick={() => setOpenPanel((o) => (o === cat.id ? null : cat.id))}
+                >
+                  {glyph}
+                  <span className="kol-sidenav-hop-label flex-1 min-w-0">{cat.label}</span>
+                </button>
               ) : isAction ? (
                 <button
                   type="button"
@@ -322,7 +384,7 @@ function SideNavInner({
                     </Tooltip>
                   ) : head}
 
-                  {!isLink && !isAction && isOpen && (
+                  {!isLink && !isAction && !isPanel && isOpen && (
                     <ul className="kol-sidenav-list">{renderRows(pages, 0)}</ul>
                   )}
                 </li>
@@ -344,6 +406,8 @@ function SideNavInner({
         * THE single collapse/resize control — click toggles, drag resizes,
         * snap-to-default on release, Home/Enter/Space on the keyboard. */}
 
+      {header && <div className="kol-sidenav-header">{header}</div>}
+
       {/* ONLY the tree scrolls (fxr's re-measure, 2026-08-28): the theme slot
         * and the pinned rows used to sit inside this region, so on a 26-row
         * collapsed tree they scrolled off below the footer — "pinned" only
@@ -396,6 +460,17 @@ function SideNavInner({
         </div>
       )}
 
+      {/* the open panel leaf's panel — a portal above its row, the rail's width */}
+      {panelNode && panelBox && createPortal(
+        <div
+          className="kol-sidenav-panel fixed flex flex-col gap-[2px] py-2 bg-surface-primary border-t border-r border-fg-08"
+          style={{ left: panelBox.left, width: panelBox.width, bottom: panelBox.bottom, zIndex: 'var(--kol-z-tooltip)' }}
+        >
+          {typeof panelNode.panel === 'function' ? panelNode.panel({ collapsed, close: () => setOpenPanel(null) }) : panelNode.panel}
+        </div>,
+        document.body,
+      )}
+
       {/* Grab edge — width/cursor/focus chrome in kol-framework.css
         * (.kol-sidenav-grab); hidden below lg by the narrow-mode block. */}
       <div className="kol-sidenav-grab absolute top-0 right-0 bottom-0 z-[1]" {...grabProps} />