@kolkrabbi/kol-framework 0.33.0 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-framework",
-  "version": "0.33.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'
@@ -79,6 +80,18 @@ import useDragResize from './useDragResize'
  *                      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
@@ -172,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 */
@@ -191,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)
@@ -204,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. */
@@ -253,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>
@@ -282,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"
@@ -331,7 +384,7 @@ function SideNavInner({
                     </Tooltip>
                   ) : head}
 
-                  {!isLink && !isAction && isOpen && (
+                  {!isLink && !isAction && !isPanel && isOpen && (
                     <ul className="kol-sidenav-list">{renderRows(pages, 0)}</ul>
                   )}
                 </li>
@@ -407,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} />