@kolkrabbi/kol-framework 0.29.0 → 0.31.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.31.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.3",
+    "@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
@@ -42,6 +64,27 @@ import useDragResize from './useDragResize'
  * the `kol-sidenav` storage schema, owned by useDragResize. Collapsed rows
  * get a DS Tooltip — the glyph is otherwise the only thing naming them.
  *
+ * THE SHELL RAIL IS THIS COMPONENT (RailSideNavPixelParity, kol-fxr 2026-08-28
+ * — user, on the brand sidebar's drag: "same component both states super
+ * nice"): kol-shell's `AppShell` mounts a SideNav — collapsed by default, the
+ * drag opens it — so an app rail and the brand sidebar are one geometry to the
+ * 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:
+ *   `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
+ *                      bottoms")
+ *   `footer`           the footer box's content: undefined = the Kolkrabbi link
+ *                      (K / wordmark, as ever); `false` = no footer; a node =
+ *                      that node (the shell's logomark → '/')
+ *   `themeToggle`      `false` drops the theme slot (default `true`)
+ *   `iconComponent`    the hop glyph's renderer, kol-shell's seam — `(props:
+ *                      { name, size }) => element`; default the DS `Icon`
+ *   `expandOnSelect`   `false` keeps the rail collapsed when a row navigates or
+ *                      dispatches — an app rail stays a rail. Default `true`, the
+ *                      brand ruling ("pressing any icon would expand the sidebar")
+ *   `defaultCollapsed` boots collapsed when nothing is stored (useDragResize)
  * `background` (2026-08-09, prop): `true` (default) paints the rail surface;
  * `false` renders chromeless so the rail can float over a consumer's media
  * (the brand-hero model — the consumer owns the plane). `hairline` (2026-08-26,
@@ -64,7 +107,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 +116,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 = [],
@@ -86,20 +143,40 @@ export default function SideNav({
    * name; a rail floating over media and a rail without a line are different
    * choices. */
   hairline = false,
+  bottomItems = [],
+  footer,
+  themeToggle = true,
+  iconComponent,
+  expandOnSelect = true,
+  defaultCollapsed = false,
 }) {
-  const { pathname } = useLocation()
+  const Glyph = iconComponent ?? Icon
   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 && expandOnSelect) toggleCollapsed()
+  }
+  /* an action leaf dispatches — same drawer / rail behaviour as a navigation */
+  const handleSelect = (e, row) => {
+    row.onSelect(e)
     onCloseDrawer?.()
-    if (collapsed) toggleCollapsed()
+    if (collapsed && expandOnSelect) 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
@@ -116,14 +193,14 @@ export default function SideNav({
    * storage schema and the state; the chip Button and the grab edge both
    * drive it. */
   const asideRef = useRef(null)
-  const { collapsed, toggleCollapsed, grabProps } = useDragResize(asideRef)
+  const { collapsed, toggleCollapsed, grabProps } = useDragResize(asideRef, { defaultCollapsed })
 
   /* 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. */
   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,66 +213,76 @@ 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>
     )
   })
 
-  return (
-    <aside
-      ref={asideRef}
-      /* Box utilities deliberately absent (SideNavMobilePosition, 2026-08-25):
-       * the aside's position/height/stack live in .kol-sidenav
-       * (kol-framework.css). `sticky … h-dvh z-20` here outranked the 767px
-       * drawer rule's `position: fixed`, so every consumer page opened one
-       * viewport down on phones. Only colour utilities ride the element. */
-      className={`kol-sidenav${background ? ' bg-surface-primary' : ''}${hairline ? ' border-r border-fg-08' : ''}${collapsed ? ' is-collapsed' : ''}${drawerOpen ? ' is-drawer-open' : ''}`}
-    >
-      {/* NO chip Button in either state (user build order 2026-08-09 — "MAKE
-        * IT"; supersedes the elder A/B): the pill-marked grab edge below is
-        * THE single collapse/resize control — click toggles, drag resizes,
-        * snap-to-default on release, Home/Enter/Space on the keyboard. */}
-
-      <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) => {
+  /* one renderer for the tree and the pinned rows (RailSideNavPixelParity) */
+  const renderCat = (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). */
               const rowCls = 'kol-sidenav-hop kol-helper-12 text-emphasis no-underline'
               const glyph = (
                 <span className="kol-sidenav-hop-icon inline-flex items-center justify-center w-5 h-5 shrink-0" aria-hidden="true">
-                  <Icon name={cat.icon} size={16} />
+                  <Glyph name={cat.icon} size={16} />
                 </span>
               )
               /* A category is a <button>, not a link — it has no route by
                  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,39 +322,74 @@ export default function SideNav({
                     </Tooltip>
                   ) : head}
 
-                  {!isLink && isOpen && (
+                  {!isLink && !isAction && isOpen && (
                     <ul className="kol-sidenav-list">{renderRows(pages, 0)}</ul>
                   )}
                 </li>
               )
-            })}
+  }
+
+  return (
+    <aside
+      ref={asideRef}
+      /* Box utilities deliberately absent (SideNavMobilePosition, 2026-08-25):
+       * the aside's position/height/stack live in .kol-sidenav
+       * (kol-framework.css). `sticky … h-dvh z-20` here outranked the 767px
+       * drawer rule's `position: fixed`, so every consumer page opened one
+       * viewport down on phones. Only colour utilities ride the element. */
+      className={`kol-sidenav${background ? ' bg-surface-primary' : ''}${hairline ? ' border-r border-fg-08' : ''}${collapsed ? ' is-collapsed' : ''}${drawerOpen ? ' is-drawer-open' : ''}`}
+    >
+      {/* NO chip Button in either state (user build order 2026-08-09 — "MAKE
+        * IT"; supersedes the elder A/B): the pill-marked grab edge below is
+        * THE single collapse/resize control — click toggles, drag resizes,
+        * snap-to-default on release, Home/Enter/Space on the keyboard. */}
+
+      <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(renderCat)}
           </ul>
         </nav>
 
         {/* hop-bare carries its own gutter padding; collapsed falls back to
             `icon` — a full-width label can't sit in the collapsed rail. */}
-        <div className="kol-sidenav-theme-slot flex">
-          <ThemeToggle variant={collapsed ? 'icon' : 'hop-bare'} size="md" />
+        <div>
+          {themeToggle && (
+            <div className="kol-sidenav-theme-slot flex">
+              <ThemeToggle variant={collapsed ? 'icon' : 'hop-bare'} size="md" />
+            </div>
+          )}
+          {/* pinned rows — BELOW the theme, above the footer: the shell's bottom
+            * pair (theme → Settings), specified once */}
+          {bottomItems.length > 0 && (
+            <nav aria-label="Pinned">
+              <ul className="kol-sidenav-tree flex flex-col gap-[2px]">{bottomItems.map(renderCat)}</ul>
+            </nav>
+          )}
         </div>
       </div>
 
-      <div className="kol-sidenav-footer flex items-center h-14 border-t border-fg-08 min-w-0">
-        <a
-          href="https://kolkrabbi.io"
-          target="_blank"
-          rel="noopener"
-          className="kol-helper-10 !font-normal no-underline group whitespace-nowrap overflow-hidden text-ellipsis min-w-0"
-        >
-          {/* Collapsed rail shows the initial alone; the full wordmark
-              overflows it. Both live in one <a> so the link survives either
-              state (CSS swaps them on the data-sidenav stamp). */}
-          <span className="kol-sidenav-footer-mark text-body group-hover:text-emphasis">K</span>
-          <span className="kol-sidenav-footer-full">
-            <span className="text-body group-hover:text-emphasis">Kolkrabbi Vinnustofa</span>
-            <span className="text-meta group-hover:text-emphasis"> · {new Date().getFullYear()}</span>
-          </span>
-        </a>
-      </div>
+      {footer !== false && footer !== null && (
+        <div className="kol-sidenav-footer flex items-center h-14 border-t border-fg-08 min-w-0">
+          {footer !== undefined ? footer : (
+            <a
+              href="https://kolkrabbi.io"
+              target="_blank"
+              rel="noopener"
+              className="kol-helper-10 !font-normal no-underline group whitespace-nowrap overflow-hidden text-ellipsis min-w-0"
+            >
+              {/* Collapsed rail shows the initial alone; the full wordmark
+                  overflows it. Both live in one <a> so the link survives either
+                  state (CSS swaps them on the data-sidenav stamp). */}
+              <span className="kol-sidenav-footer-mark text-body group-hover:text-emphasis">K</span>
+              <span className="kol-sidenav-footer-full">
+                <span className="text-body group-hover:text-emphasis">Kolkrabbi Vinnustofa</span>
+                <span className="text-meta group-hover:text-emphasis"> · {new Date().getFullYear()}</span>
+              </span>
+            </a>
+          )}
+        </div>
+      )}
 
       {/* Grab edge — width/cursor/focus chrome in kol-framework.css
         * (.kol-sidenav-grab); hidden below lg by the narrow-mode block. */}

package/src/useDragResize.js

@@ -96,7 +96,7 @@ const readBack = (n) => {
  *           rightward drag = wider. 'right' inverts both the pointer sign and
  *           the arrow keys. */
 export default function useDragResize(ref, options = {}) {
-  const { token = 'kol-sidenav', side = 'left' } = options
+  const { token = 'kol-sidenav', side = 'left', defaultCollapsed = false } = options
   /* -1 on a right-hand rail: the same rightward pointer travel that widens a
    * left rail must NARROW a right one, because its handle faces the canvas. */
   const dir = side === 'right' ? -1 : 1
@@ -131,14 +131,18 @@ export default function useDragResize(ref, options = {}) {
     defaultPx.current = readVarPx(names.wVar)
     collapsedPx.current = readVarPx(names.collapsedVar)
     let w = null
-    let c = false
+    let stored = null
     try {
       w = parseFloat(localStorage.getItem(names.widthKey)) || null
-      c = localStorage.getItem(names.stateKey) === 'collapsed'
+      stored = localStorage.getItem(names.stateKey)
     } catch { /* storage blocked */ }
+    /* nothing stored → the consumer's boot state (RailSideNavPixelParity,
+     * 2026-08-28): an app rail boots collapsed, the brand sidebar boots open;
+     * the first drag or click persists and the default never speaks again */
+    const c = stored ? stored === 'collapsed' : !!defaultCollapsed
     if (w) { writeWidth(names, w); setWidthPx(w) }
     if (c) { stampCollapsed(names, true); setCollapsed(true) }
-  }, [names])
+  }, [names, defaultCollapsed])
 
   useEffect(() => {
     const onMove = (e) => {