@kolkrabbi/kol-framework 0.30.0 → 0.31.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-framework",
-  "version": "0.30.0",
+  "version": "0.31.1",
   "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,7 +20,7 @@
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.118.1",
+    "@kolkrabbi/kol-component": "^0.118.3",
     "@kolkrabbi/kol-icons": "^0.24.0"
   },
   "files": [

package/src/SideNav.jsx

@@ -64,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,
@@ -122,7 +143,14 @@ function SideNavInner({
    * 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 Glyph = iconComponent ?? Icon
   const isPageActive = (to) => (isActive ? isActive(to) : pathname === 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))
@@ -135,13 +163,13 @@ function SideNavInner({
   const handleNavigate = (e, to) => {
     onNavigate?.(e, to)
     onCloseDrawer?.()
-    if (collapsed) toggleCollapsed()
+    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 ? (
@@ -165,7 +193,7 @@ function SideNavInner({
    * 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
@@ -211,25 +239,8 @@ function SideNavInner({
     )
   })
 
-  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, ci) => {
+  /* 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
@@ -251,7 +262,7 @@ function SideNavInner({
               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
@@ -316,35 +327,75 @@ function SideNavInner({
                   )}
                 </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. */}
+
+      {/* 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
+        * held while the tree was shorter than the rail. They are the block
+        * after it now, above the footer, the tree scrolling underneath. */}
+      <div className="kol-sidenav-scroll flex-1 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>
       </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>
+      {/* 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="pb-4">
+          {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>
 
+      {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. */}
       <div className="kol-sidenav-grab absolute top-0 right-0 bottom-0 z-[1]" {...grabProps} />

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) => {