@kolkrabbi/kol-framework 0.29.0 → 0.30.0

package/kol-framework.css

@@ -160,6 +160,16 @@ body {
   display: block;
   padding: 0.25rem 1.5rem 0.25rem 3.5rem;
 }
+/* THE COLLAPSE RULE (WorkspaceSidebarGeometry, kol-fxr 2026-08-27 — user: "I
+ * would rather all use the same geometry layout"): a row that can survive
+ * collapse has an icon; one that cannot is not a row, it is a LABEL. A
+ * top-level node with no icon renders this — the eyebrow over its rows — and
+ * it is hidden with the labels when the rail narrows, so the rail reads as one
+ * thing narrowing (the brand sidebar's model) instead of rows vanishing. */
+.kol-sidenav-section {
+  display: block;
+  padding: 0.5rem 1.5rem 0.25rem 1.5rem;
+}
 .kol-sidenav-footer { padding-inline: 1.5rem 1rem; }
 
 /* The aside's OWN box (SideNavMobilePosition, kol-website 2026-08-25) — the
@@ -198,6 +208,7 @@ body {
  * no labels; the theme slot and footer centre; the footer wordmark swaps for
  * its initial — both spans live in one <a>, so the link survives either state. */
 :root[data-sidenav="collapsed"] .kol-sidenav-hop-caret,
+:root[data-sidenav="collapsed"] .kol-sidenav-section,
 :root[data-sidenav="collapsed"] .kol-sidenav-list { display: none; }
 :root[data-sidenav="collapsed"] .kol-sidenav-theme-slot { padding-inline: 0; justify-content: center; }
 :root[data-sidenav="collapsed"] .kol-sidenav-footer { padding-inline: 0; justify-content: center; }
@@ -259,6 +270,7 @@ body {
   .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-hop-label { display: none; }
+  .kol-sidenav-section { display: none; }
   .kol-sidenav-body { display: none; }
   /* forced narrow / drawer modes own the rail below lg — no resize here */
   .kol-sidenav-grab { display: none; }
@@ -280,6 +292,7 @@ body {
   /* 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-hop-label { display: inline; }
+  .kol-sidenav.is-drawer-open .kol-sidenav-section { display: block; }
   .kol-sidenav.is-drawer-open .kol-sidenav-body { display: block; }
   .kol-brand-layout[data-drawer-open="true"] .kol-sidenav-backdrop {
     opacity: 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-framework",
-  "version": "0.29.0",
+  "version": "0.30.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.114.0",
-    "@kolkrabbi/kol-icons": "^0.23.0"
+    "@kolkrabbi/kol-component": "^0.118.1",
+    "@kolkrabbi/kol-icons": "^0.24.0"
   },
   "files": [
     "src",

package/src/SideNav.jsx

@@ -34,6 +34,28 @@ import useDragResize from './useDragResize'
  * navTree: [{ id, label, icon, to?, pages?: [{ label, to } | { label, children }] }]
  * (legacy `children` on a category is read as `pages`; section anchors are not.)
  *
+ * WORKSPACE RAILS (WorkspaceSidebarGeometry, kol-fxr 2026-08-27 — user: "I see
+ * these 3 as very similar things … I would rather all use the same geometry
+ * layout"; three forks, ~1,370 lines, wearing this component's classes):
+ *
+ *   ACTION LEAVES — `{ label, onSelect, active? }` beside `{ label, to }`, at
+ *   any depth and as a category (`{ id, label, icon, onSelect, active? }`): a
+ *   rail that DISPATCHES (labs swaps an effect, monitor picks a module, mirror
+ *   selects a surface) instead of navigating. A <button>, lit by `active`;
+ *   never a route, so no history is walked (labs' `?preset=` replace-not-push
+ *   stays what it is).
+ *
+ *   ROUTER-AGNOSTIC — pass `currentPath` and the component never touches
+ *   react-router: route leaves render `<a href>` and call `onNavigate(event,
+ *   to)` (kol-shell's contract); a router-free app can mount it. Without
+ *   `currentPath` it is the NavLink rail it always was.
+ *
+ *   THE COLLAPSE RULE — a row that can survive collapse HAS AN ICON; one that
+ *   cannot is not a row, it is a LABEL. A top-level node with no `icon` (and no
+ *   `to` / `onSelect`) renders `.kol-sidenav-section` — the eyebrow voice, hidden
+ *   on collapse — over its `pages`; the icon rows beneath stay, so the rail
+ *   reads as one thing narrowing, the brand sidebar's model.
+ *
  * Collapse: the pill-marked grab edge is THE single control (user build
  * order 2026-08-09, completing SideNavGrabResize — the chip Button is gone
  * in both states). Click toggles expand↔collapse, drag resizes with
@@ -64,7 +86,7 @@ const pageActiveCls = `${pageBase} is-active`
 /* A category's rows: route leaves (`to`) and route groups (`children`).
  * `#anchor` leaves (`id` only) are dropped — that layer died with the brand
  * app's 2026-08-01 ruling and is not reopened here. */
-const rowsOf = (nodes) => nodes.filter((c) => c.to || c.children)
+const rowsOf = (nodes) => nodes.filter((c) => c.to || c.children || c.onSelect)
 const pagesOf = (cat) => rowsOf(cat.pages ?? cat.children ?? [])
 /* Every route leaf under a set of rows, through any depth of groups. */
 const leavesOf = (rows) => rows.flatMap((r) => (r.children ? leavesOf(rowsOf(r.children)) : [r]))
@@ -73,7 +95,21 @@ const leavesOf = (rows) => rows.flatMap((r) => (r.children ? leavesOf(rowsOf(r.c
  * this layer. Depth 0 carries no indent so a flat tree renders unchanged. */
 const indentOf = (depth) => `calc(3.5rem + ${depth} * var(--kol-spacing-3))`
 
-export default function SideNav({
+/* Router-agnostic seam: with `currentPath` the rail never calls react-router
+ * (a hook cannot be conditional, so the router read lives in its own wrapper
+ * that mounts only when the prop is absent). */
+export default function SideNav(props) {
+  if (props.currentPath != null) return <SideNavInner {...props} pathname={props.currentPath} router={false} />
+  return <RouterSideNav {...props} />
+}
+function RouterSideNav(props) {
+  const { pathname } = useLocation()
+  return <SideNavInner {...props} pathname={pathname} router />
+}
+
+function SideNavInner({
+  pathname,
+  router,
   drawerOpen = false,
   onCloseDrawer,
   navTree = [],
@@ -87,19 +123,32 @@ export default function SideNav({
    * choices. */
   hairline = false,
 }) {
-  const { pathname } = useLocation()
   const isPageActive = (to) => (isActive ? isActive(to) : pathname === to)
-  const isActiveCat = (cat) => leavesOf(pagesOf(cat)).some((p) => isPageActive(p.to))
+  /* a leaf is lit by its route, or — an action leaf — by its own `active` */
+  const isLeafActive = (leaf) => (leaf.onSelect ? !!leaf.active : isPageActive(leaf.to))
+  const isActiveCat = (cat) => (cat.onSelect ? !!cat.active : leavesOf(pagesOf(cat)).some(isLeafActive))
 
   /* Every navigation closes the mobile drawer — the prop sat accepted-but-
    * unread until the kol-website session flagged it (2026-08-09) — and, from
    * the collapsed rail, expands the sidebar ("pressing any icon would expand
    * the sidebar", same ruling as the chip removal). */
-  const handleNavigate = (e) => {
-    onNavigate?.(e)
+  const handleNavigate = (e, to) => {
+    onNavigate?.(e, to)
+    onCloseDrawer?.()
+    if (collapsed) toggleCollapsed()
+  }
+  /* an action leaf dispatches — same drawer / rail behaviour as a navigation */
+  const handleSelect = (e, row) => {
+    row.onSelect(e)
     onCloseDrawer?.()
     if (collapsed) toggleCollapsed()
   }
+  /* the route leaf: NavLink under a router, `<a href>` on the agnostic seam */
+  const RouteLeaf = ({ to, className, style, children }) => router ? (
+    <NavLink to={to} end style={style} className={({ isActive: navActive }) => className(isActive ? isActive(to) : navActive)} onClick={(e) => handleNavigate(e, to)}>{children}</NavLink>
+  ) : (
+    <a href={to} style={style} className={className(isPageActive(to))} onClick={(e) => { e.preventDefault(); handleNavigate(e, to) }}>{children}</a>
+  )
 
   /* Which categories are disclosed. INDEPENDENT per category (elder ruling
    * 2026-08-01) — arriving somewhere must not silently close wherever you
@@ -123,7 +172,7 @@ export default function SideNav({
    * up the way a category does — when one of its leaves is the current route. */
   const renderRows = (rows, depth) => rows.map((row, i) => {
     if (row.children) {
-      const lit = leavesOf(rowsOf(row.children)).some((l) => isPageActive(l.to))
+      const lit = leavesOf(rowsOf(row.children)).some(isLeafActive)
       return (
         <li key={row.id ?? `${row.label}-${i}`}>
           <div
@@ -136,18 +185,28 @@ export default function SideNav({
         </li>
       )
     }
+    /* the dot keeps its 0.875rem lead on the text at every depth */
+    const leafStyle = depth ? { paddingLeft: indentOf(depth), '--kol-sidenav-dot-left': `calc(2.625rem + ${depth} * var(--kol-spacing-3))` } : pageStyle
+    if (row.onSelect) {
+      return (
+        <li key={row.id ?? `${row.label}-${i}`}>
+          <button
+            type="button"
+            style={leafStyle}
+            className={`${row.active ? pageActiveCls : pageCls} w-full bg-transparent border-0 cursor-pointer text-left truncate`}
+            aria-pressed={!!row.active}
+            onClick={(e) => handleSelect(e, row)}
+          >
+            {row.label}
+          </button>
+        </li>
+      )
+    }
     return (
       <li key={row.to}>
-        <NavLink
-          to={row.to}
-          end
-          /* the dot keeps its 0.875rem lead on the text at every depth */
-          style={depth ? { paddingLeft: indentOf(depth), '--kol-sidenav-dot-left': `calc(2.625rem + ${depth} * var(--kol-spacing-3))` } : pageStyle}
-          className={({ isActive: navActive }) => ((isActive ? isActive(row.to) : navActive) ? pageActiveCls : pageCls)}
-          onClick={handleNavigate}
-        >
+        <RouteLeaf to={row.to} style={leafStyle} className={(active) => (active ? pageActiveCls : pageCls)}>
           {row.label}
-        </NavLink>
+        </RouteLeaf>
       </li>
     )
   })
@@ -170,10 +229,22 @@ export default function SideNav({
       <div className="kol-sidenav-scroll flex-1 flex flex-col justify-between overflow-y-auto pt-4 pb-4 [scrollbar-width:thin]">
         <nav aria-label="Sections">
           <ul className="kol-sidenav-tree flex flex-col gap-[2px]">
-            {navTree.map((cat) => {
+            {navTree.map((cat, ci) => {
               const pages = pagesOf(cat)
               const isOpen = openCats.has(cat.id)
               const isLink = !pages.length && cat.to
+              const isAction = !pages.length && !cat.to && 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) {
+                return (
+                  <li key={cat.id ?? `${cat.label}-${ci}`} className="relative">
+                    <div className="kol-sidenav-section kol-eyebrow text-strong">{cat.label}</div>
+                    {pages.length > 0 && <ul className="kol-sidenav-list">{renderRows(pages, 0)}</ul>}
+                  </li>
+                )
+              }
               /* Box utilities deliberately absent — the hop's layout lives in
                * .kol-sidenav-hop (kol-framework.css): a utility here would
                * outrank the collapsed-state overrides (2026-08-09 defect). */
@@ -187,15 +258,20 @@ export default function SideNav({
                  definition, and an <a href> would promise a page that does
                  not exist. Clicking it discloses its pages. */
               const head = isLink ? (
-                <NavLink
-                  to={cat.to}
-                  end
-                  className={({ isActive: navActive }) => `${rowCls}${(isActive ? isActive(cat.to) : navActive) ? ' is-active' : ''}`}
-                  onClick={handleNavigate}
+                <RouteLeaf to={cat.to} className={(active) => `${rowCls}${active ? ' is-active' : ''}`}>
+                  {glyph}
+                  <span className="kol-sidenav-hop-label flex-1 min-w-0">{cat.label}</span>
+                </RouteLeaf>
+              ) : isAction ? (
+                <button
+                  type="button"
+                  className={`${rowCls} bg-transparent border-0 cursor-pointer text-left${cat.active ? ' is-active' : ''}`}
+                  aria-pressed={!!cat.active}
+                  onClick={(e) => handleSelect(e, cat)}
                 >
                   {glyph}
                   <span className="kol-sidenav-hop-label flex-1 min-w-0">{cat.label}</span>
-                </NavLink>
+                </button>
               ) : (
                 <button
                   type="button"
@@ -235,7 +311,7 @@ export default function SideNav({
                     </Tooltip>
                   ) : head}
 
-                  {!isLink && isOpen && (
+                  {!isLink && !isAction && isOpen && (
                     <ul className="kol-sidenav-list">{renderRows(pages, 0)}</ul>
                   )}
                 </li>