@kolkrabbi/kol-framework 0.14.0 → 0.15.0

package/kol-framework.css

@@ -124,6 +124,17 @@ body {
 :root[data-sidenav="collapsed"] .kol-sidenav-body { display: none; }
 :root[data-sidenav="collapsed"] .kol-sidenav-hop-count,
 :root[data-sidenav="collapsed"] .kol-sidenav-section-toggle { display: none; }
+/* Folded back from the elder's brand-local sidenav-collapse.css (2026-08-09
+ * port): the disclosure caret and the disclosed list are noise in a rail with
+ * 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-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; }
+.kol-sidenav-footer-mark { display: none; }
+:root[data-sidenav="collapsed"] .kol-sidenav-footer-mark { display: inline; }
+:root[data-sidenav="collapsed"] .kol-sidenav-footer-full { display: none; }
 
 /* The grab edge itself — invisible by spec (col-resize cursor is the pointer
  * affordance, the focus ring the keyboard one — recipe from

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-framework",
-  "version": "0.14.0",
+  "version": "0.15.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",
@@ -27,7 +27,7 @@
     "app-shell"
   ],
   "dependencies": {
-    "@kolkrabbi/kol-component": "0.24.0",
+    "@kolkrabbi/kol-component": "0.27.0",
     "@kolkrabbi/kol-icons": "0.10.0"
   },
   "peerDependencies": {

package/src/AppShell.jsx

@@ -15,7 +15,10 @@ export const ShellTocContext = createContext(null)
  * useLayoutEffect(() => { setTocCollapsed(true); return () => setTocCollapsed(false) }, [setTocCollapsed]) */
 export const ShellTocCollapsedContext = createContext(null)
 
-export default function AppShell({ navTree = [], getActivePage, header, footer, defaultTocContent }) {
+/* `getActivePage` — ACCEPTED-but-inert since the 2026-08-09 SideNav port (the
+ * two-level elder model derives the active category from the route); kept so
+ * no call site breaks. */
+export default function AppShell({ navTree = [], getActivePage: _getActivePage, header, footer, defaultTocContent }) {
   const [drawerOpen, setDrawerOpen] = useState(false)
   const [tocContent, setTocContent] = useState(null)
   const [tocCollapsed, setTocCollapsed] = useState(false)
@@ -58,7 +61,7 @@ export default function AppShell({ navTree = [], getActivePage, header, footer,
               aria-hidden="true"
             />
 
-            <SideNav navTree={navTree} getActivePage={getActivePage} drawerOpen={drawerOpen} onCloseDrawer={() => setDrawerOpen(false)} />
+            <SideNav navTree={navTree} drawerOpen={drawerOpen} onCloseDrawer={() => setDrawerOpen(false)} />
             <div className="min-w-0">
               {header}
               <Outlet />

package/src/SideNav.jsx

@@ -1,256 +1,182 @@
-import { useEffect, useRef, useState } from 'react'
-import { Link, NavLink, useLocation } from 'react-router-dom'
+import { NavLink, useLocation } from 'react-router-dom'
+import { useRef, useState } from 'react'
 import { Icon } from '@kolkrabbi/kol-icons'
+import { Button, Tooltip } from '@kolkrabbi/kol-component'
 import ThemeToggle from './ThemeToggle'
 import useDragResize from './useDragResize'
-import { useScrollSpy } from '@kolkrabbi/kol-component'
 
-/* Walk the active page's children and return all leaf section ids (for scroll-spy). */
-function collectSectionIds(node) {
-  if (!node?.children) return []
-  const ids = []
-  const walk = (children) => {
-    for (const c of children) {
-      if (c.id && !c.to) ids.push(c.id)
-      if (c.children) walk(c.children)
-    }
-  }
-  walk(node.children)
-  return ids
-}
-
-const linkBase = 'kol-sidenav-link kol-helper-10 block relative py-[4px] no-underline transition-colors duration-150'
-const linkCls = `${linkBase} text-body hover:text-emphasis`
-const linkActiveCls = `${linkBase} is-active`
-
-/* Walk the children tree; return true if any leaf matches activeSectionId. */
-function hasActiveDescendant(children, activeSectionId) {
-  if (!activeSectionId) return false
-  for (const c of children ?? []) {
-    if (c.id === activeSectionId) return true
-    if (c.children && hasActiveDescendant(c.children, activeSectionId)) return true
-  }
-  return false
-}
-
-const leafStyle = (indent) => ({
-  paddingLeft: indent,
-  '--kol-sidenav-dot-left': `${indent - 14}px`,
-})
-
-function SectionLeaf({ leaf, basePath, isActive, indent, onNavigate }) {
-  return (
-    <li>
-      <Link
-        to={`${basePath}#${leaf.id}`}
-        className={isActive ? linkActiveCls : linkCls}
-        style={leafStyle(indent)}
-        onClick={onNavigate}
-      >
-        {leaf.label}
-      </Link>
-    </li>
-  )
-}
-
-function RouteLeaf({ leaf, indent, onNavigate, isActiveFn }) {
-  return (
-    <li>
-      <NavLink
-        to={leaf.to}
-        end
-        className={({ isActive }) => ((isActiveFn ? isActiveFn(leaf.to) : isActive) ? linkActiveCls : linkCls)}
-        style={leafStyle(indent)}
-        onClick={onNavigate}
-      >
-        {leaf.label}
-      </NavLink>
-    </li>
-  )
-}
-
-function GroupNode({ group, basePath, activeSectionId, indent, onNavigate, isActiveFn }) {
-  const isAncestor = hasActiveDescendant(group.children, activeSectionId)
-  return (
-    <li>
-      <div
-        className={`kol-sidenav-group kol-helper-10 ${isAncestor ? 'text-emphasis' : 'text-subtle'}`}
-        style={{ paddingLeft: indent }}
-      >
-        {group.label}
-      </div>
-      <ul className="kol-sidenav-list">
-        {group.children.map((child, i) => (
-          <ChildNode
-            key={child.id ?? child.to ?? `g-${i}`}
-            child={child}
-            basePath={basePath}
-            activeSectionId={activeSectionId}
-            indent={indent + 12}
-            onNavigate={onNavigate}
-            isActiveFn={isActiveFn}
-          />
-        ))}
-      </ul>
-    </li>
-  )
-}
-
-function ChildNode({ child, basePath, activeSectionId, indent, onNavigate, isActiveFn }) {
-  if (child.children) {
-    return (
-      <GroupNode
-        group={child}
-        basePath={basePath}
-        activeSectionId={activeSectionId}
-        indent={indent}
-        onNavigate={onNavigate}
-        isActiveFn={isActiveFn}
-      />
-    )
-  }
-  if (child.to) {
-    return <RouteLeaf leaf={child} indent={indent} onNavigate={onNavigate} isActiveFn={isActiveFn} />
-  }
-  if (child.id) {
-    return (
-      <SectionLeaf
-        leaf={child}
-        basePath={basePath}
-        isActive={activeSectionId === child.id}
-        indent={indent}
-        onNavigate={onNavigate}
-      />
-    )
-  }
-  return null
-}
+/**
+ * SideNav — the grouped navigation rail.
+ *
+ * REPLICATED from the elder reference (kol-website/apps/brand
+ * src/components/framework/SideNav.jsx, 2026-08-09 user mandate: "there is a
+ * better version in kol-website apps:brand") — the brand app's evolved fork
+ * folded back into the package, generic seams kept.
+ *
+ * TWO LEVELS ONLY (elder ruling 2026-08-01). A category is a grouping LABEL —
+ * a disclosure <button> with a trailing caret, no route. A page is a route.
+ * The `#anchor` scroll-spied section layer is gone, and with it the
+ * group/section tree walkers. The ONE exception: a category with `to` and no
+ * `pages` (Home) renders as a plain link row — it has nothing to disclose.
+ *
+ * navTree: [{ id, label, icon, to?, pages?: [{ label, to }] }]
+ * (legacy `children` route leaves are read as `pages`; section anchors are not.)
+ *
+ * Collapse: BOTH affordances share one contract —
+ * `:root[data-sidenav="collapsed"]` + the `kol-sidenav` storage schema, owned
+ * by useDragResize. The round chip Button (elder A/B, closed 2026-08-01) is
+ * the one-click toggle; the grab edge (lobby: SideNavGrabResize, 2026-08-09)
+ * resizes, snap-collapses, and carries the keyboard path. Collapsed rows get
+ * a DS Tooltip — the glyph is otherwise the only thing naming them.
+ *
+ * `background` (2026-08-09, prop): `true` (default) paints the rail surface +
+ * right hairline; `false` renders chromeless so the rail can float over a
+ * consumer's media (the brand-hero model — the consumer owns the plane).
+ */
+
+const pageBase =
+  'kol-sidenav-link kol-helper-10 block relative py-[4px] pl-14 pr-6 no-underline transition-colors duration-150'
+
+/* The active-dot pseudo-element is positioned by `--kol-sidenav-dot-left`
+ * (kol-components-atoms.css). The page row indents 3.5rem (pl-14); the dot
+ * sits 0.875rem inside that, in the gutter the icon column leaves. */
+const pageStyle = { '--kol-sidenav-dot-left': '2.625rem' }
+/* Category and page must not share a stop: category `emphasis`, page `strong`
+ * — two rungs of one ladder, so the tree reads as hierarchy (elder ruling). */
+const pageCls = `${pageBase} text-strong hover:text-emphasis`
+const pageActiveCls = `${pageBase} is-active`
+
+/* Legacy DS trees carried `children` (groups + `#anchor` leaves). Route
+ * leaves survive as pages; anchor sections died with the two-level ruling. */
+const pagesOf = (cat) => cat.pages ?? cat.children?.filter((c) => c.to) ?? []
 
 export default function SideNav({
   drawerOpen = false,
   onCloseDrawer,
   navTree = [],
-  getActivePage,
   onNavigate,
-  /* INERT since 0.9.2 — accepted so no call site breaks, but nothing reads
-   * them; the collapse feature they drove has no CSS. See below. */
-  collapsed: _collapsed,
-  onToggle: _onToggle,
-  collapsibleSections = false,
   isActive,
+  background = true,
 }) {
   const { pathname } = useLocation()
-  const activePage = getActivePage?.(pathname)
-  const sectionIds = activePage ? collectSectionIds(activePage) : []
-  const onPageRoot = activePage && pathname === activePage.to
-  const activeSectionId = useScrollSpy(onPageRoot ? sectionIds : [])
-
-  /* Collapse, rebuilt DELIBERATELY 2026-08-09 (lobby: SideNavGrabResize) —
-   * the 2026-07-29/30 removals killed a stamp with no renderer; the grab edge
-   * below reinstates BOTH halves. useDragResize owns the state, stamps
-   * :root[data-sidenav="collapsed"], and kol-framework.css renders it again.
-   * `collapsed` / `onToggle` remain ACCEPTED-but-inert — the gesture is
-   * self-contained, so call sites still don't break. */
+  const isPageActive = (to) => (isActive ? isActive(to) : pathname === to)
+  const isActiveCat = (cat) => pagesOf(cat).some((p) => isPageActive(p.to))
+
+  /* Which categories are disclosed. INDEPENDENT per category (elder ruling
+   * 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())
+  const toggleCat = (id) => setOpenCats((prev) => {
+    const next = new Set(prev)
+    next.has(id) ? next.delete(id) : next.add(id)
+    return next
+  })
+
+  /* One collapse contract, two gestures — the hook owns the stamp, the
+   * storage schema and the state; the chip Button and the grab edge both
+   * drive it. */
   const asideRef = useRef(null)
-  const { grabProps } = useDragResize(asideRef)
-
-  /* Per-page section expand/collapse (opt-in via collapsibleSections).
-   * The section containing the active route auto-expands on every
-   * navigation; manual toggles persist for the session. */
-  const [expandedSections, setExpandedSections] = useState(() =>
-    collapsibleSections && activePage?.id ? { [activePage.id]: true } : {}
-  )
-
-  useEffect(() => {
-    if (!collapsibleSections || !activePage?.id) return
-    setExpandedSections((prev) => (prev[activePage.id] ? prev : { ...prev, [activePage.id]: true }))
-  }, [collapsibleSections, activePage?.id, pathname])
-
-  const toggleSection = (pageId) =>
-    setExpandedSections((prev) => ({ ...prev, [pageId]: !prev[pageId] }))
+  const { collapsed, toggleCollapsed, grabProps } = useDragResize(asideRef)
 
   return (
     <aside
       ref={asideRef}
-      className={`kol-sidenav sticky top-0 self-start h-dvh flex flex-col border-r border-fg-08 z-20 bg-surface-primary${drawerOpen ? ' is-drawer-open' : ''}`}
+      className={`kol-sidenav sticky top-0 self-start h-dvh flex flex-col z-20${background ? ' bg-surface-primary border-r border-fg-08' : ''}${collapsed ? ' is-collapsed' : ''}${drawerOpen ? ' is-drawer-open' : ''}`}
     >
-      {/* The collapse chevron Button was REMOVED 2026-07-30 (lobby ruling,
-        * finding #3) as a control with no renderer. The grab edge at the end
-        * of this aside is its deliberate 2026-08-09 replacement — pointer-drag
-        * resizes, drag under --kol-sidenav-snap collapses, double-click and
-        * Home reset, arrows resize from the keyboard. See useDragResize.js. */}
+      {/* The elder A/B (closed 2026-08-01): the DS Button IS the collapse
+        * control. Offset is half the pinned sm square, centring it on the
+        * rail's edge — the DS hardcodes that square and exposes no token. */}
+      <Button
+        variant="primary"
+        size="sm"
+        radius="full"
+        iconOnly={collapsed ? 'chevron-right' : 'chevron-left'}
+        aria-label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}
+        aria-expanded={!collapsed}
+        title={collapsed ? 'Expand' : 'Collapse'}
+        onClick={toggleCollapsed}
+        className="kol-sidenav-toggle absolute top-5 right-[-0.875rem] z-[2]"
+      />
 
       <div className="kol-sidenav-scroll flex-1 flex flex-col justify-between overflow-y-auto pt-4 pb-4 [scrollbar-width:thin]">
-        <ul className="kol-sidenav-tree flex flex-col gap-[2px]">
-          {navTree.map((page) => {
-            const isActivePage = activePage?.id === page.id
-            const isSectionCollapsible = collapsibleSections && page.children?.length > 0
-            const sectionExpanded = isSectionCollapsible && !!expandedSections[page.id]
-            const hopLink = (
-              <NavLink
-                to={page.to}
-                end={page.to === '/'}
-                className={({ isActive: navActive }) =>
-                  `kol-sidenav-hop kol-helper-12 relative flex items-center gap-3 py-2 pr-10 pl-6 no-underline${(isActive ? isActive(page.to) : navActive) ? ' is-active' : ''}`
-                }
-                onClick={onNavigate}
-              >
+        <nav aria-label="Sections">
+          <ul className="kol-sidenav-tree flex flex-col gap-[2px]">
+            {navTree.map((cat) => {
+              const pages = pagesOf(cat)
+              const isOpen = openCats.has(cat.id)
+              const isLink = !pages.length && cat.to
+              const rowCls = 'kol-sidenav-hop kol-helper-12 text-emphasis w-full relative flex items-center gap-3 py-2 pr-10 pl-6 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={page.icon} size={16} />
+                  <Icon name={cat.icon} size={16} />
                 </span>
-                <span className="kol-sidenav-hop-label flex-1 min-w-0">{page.label}</span>
-                {isSectionCollapsible && (
-                  <span className="kol-sidenav-hop-count kol-helper-10 text-meta shrink-0">
-                    ({page.children.length})
-                  </span>
-                )}
-              </NavLink>
-            )
-            return (
-              <li key={page.id}>
-                {isSectionCollapsible ? (
-                  <div className="relative">
-                    {hopLink}
-                    <button
-                      type="button"
-                      className="kol-sidenav-section-toggle absolute right-3 top-1/2 -translate-y-1/2 z-[1] inline-flex items-center justify-center w-5 h-5 p-0 bg-transparent border-0 cursor-pointer text-meta hover:text-emphasis transition-colors duration-150"
-                      aria-label={sectionExpanded ? `Collapse ${page.label}` : `Expand ${page.label}`}
-                      aria-expanded={sectionExpanded}
-                      onClick={() => toggleSection(page.id)}
-                    >
-                      <Icon
-                        name="chevron-right"
-                        size={12}
-                        className={`transition-transform duration-150${sectionExpanded ? ' rotate-90' : ''}`}
-                      />
-                    </button>
-                  </div>
-                ) : (
-                  hopLink
-                )}
-
-                {page.children && (collapsibleSections ? sectionExpanded : isActivePage) && (
-                  <ul className="kol-sidenav-list mb-2 flex flex-col gap-2">
-                    {page.children.map((child, i) => (
-                      <ChildNode
-                        key={child.id ?? child.to ?? `g-${i}`}
-                        child={child}
-                        basePath={page.to}
-                        activeSectionId={activeSectionId}
-                        indent={56}
-                        onNavigate={onNavigate}
-                        isActiveFn={isActive}
-                      />
-                    ))}
-                  </ul>
-                )}
-              </li>
-            )
-          })}
-        </ul>
-
-        <div className="flex flex-col">
-          <ThemeToggle variant="hop-bare" />
+              )
+              /* 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={onNavigate}
+                >
+                  {glyph}
+                  <span className="kol-sidenav-hop-label flex-1 min-w-0">{cat.label}</span>
+                </NavLink>
+              ) : (
+                <button
+                  type="button"
+                  className={`${rowCls} bg-transparent border-0 cursor-pointer text-left${isActiveCat(cat) ? ' is-active' : ''}`}
+                  aria-expanded={isOpen}
+                  onClick={() => toggleCat(cat.id)}
+                >
+                  {glyph}
+                  <span className="kol-sidenav-hop-label flex-1 min-w-0">{cat.label}</span>
+                  <Icon
+                    name="chevron-down"
+                    size={12}
+                    className={`kol-sidenav-hop-caret absolute top-3 right-3 transition-transform duration-150${isOpen ? '' : ' -rotate-90'}`}
+                  />
+                </button>
+              )
+              return (
+                <li key={cat.id} className="relative">
+                  {/* Collapsed rail hides the label — the tooltip is the only
+                      thing naming the row. Portalled, so overflow can't clip it. */}
+                  {collapsed ? (
+                    <Tooltip label={cat.label} placement="right" triggerClassName="block">
+                      {head}
+                    </Tooltip>
+                  ) : head}
+
+                  {!isLink && isOpen && (
+                    <ul className="kol-sidenav-list mb-2 flex flex-col gap-[2px]">
+                      {pages.map((page) => (
+                        <li key={page.to}>
+                          <NavLink
+                            to={page.to}
+                            end
+                            style={pageStyle}
+                            className={({ isActive: navActive }) => ((isActive ? isActive(page.to) : navActive) ? pageActiveCls : pageCls)}
+                            onClick={onNavigate}
+                          >
+                            {page.label}
+                          </NavLink>
+                        </li>
+                      ))}
+                    </ul>
+                  )}
+                </li>
+              )
+            })}
+          </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>
 
@@ -261,8 +187,14 @@ export default function SideNav({
           rel="noopener"
           className="kol-helper-10 !font-normal no-underline group whitespace-nowrap overflow-hidden text-ellipsis min-w-0"
         >
-          <span className="text-body group-hover:text-emphasis">Kolkrabbi Vinnustofa</span>
-          <span className="text-meta group-hover:text-emphasis"> · {new Date().getFullYear()}</span>
+          {/* 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>
 

package/src/index.js

@@ -2,8 +2,8 @@
  * @kol/framework — shared KOL app shell.
  *
  * Site chrome (sidenav, layout, theme toggle, footer, heroes) consumed across
- * apps. SideNav takes its nav data as props (navTree + getActivePage) so the
- * tree stays app-local. CSS lives in src/styles: kol-framework.css
+ * apps. SideNav takes its nav data as props (navTree) so the tree stays
+ * app-local. CSS lives in src/styles: kol-framework.css
  * and kol-brand-color.css.
  */
 

package/src/useDragResize.js

@@ -134,6 +134,15 @@ export default function useDragResize(asideRef) {
     syncAndPersist()
   }
 
+  /* One-click toggle for the chip Button (elder A/B, folded back 2026-08-09)
+   * — same stamp, same storage schema, so the chip and the grab edge can
+   * never disagree about the state. */
+  const toggleCollapsed = () => {
+    const { collapsed: c } = readBack()
+    stampCollapsed(!c)
+    syncAndPersist()
+  }
+
   const onKeyDown = (e) => {
     const snapPx = readVarPx('--kol-sidenav-snap')
     const stepPx = readVarPx('--kol-sidenav-step')
@@ -160,6 +169,7 @@ export default function useDragResize(asideRef) {
 
   return {
     collapsed,
+    toggleCollapsed,
     grabProps: {
       role: 'separator',
       'aria-orientation': 'vertical',