@kolkrabbi/kol-framework 0.22.0 → 0.24.0

package/kol-framework.css

@@ -150,8 +150,37 @@ body {
   gap: 0.125rem;
   margin-bottom: 0.5rem;
 }
+/* A nested route GROUP's header (sidenav-nested-groups, kol-studio
+ * 2026-08-26): a non-routing label sitting where a leaf sits, its rows one
+ * step further in. Type and colour ride the element as utilities
+ * (kol-helper-10; text-subtle, text-emphasis when a leaf beneath it is the
+ * route); the box lives here. No text-transform — the retired fork's
+ * `uppercase` does not return (type law: only the display voice carries one). */
+.kol-sidenav-group {
+  display: block;
+  padding: 0.25rem 1.5rem 0.25rem 3.5rem;
+}
 .kol-sidenav-footer { padding-inline: 1.5rem 1rem; }
 
+/* The aside's OWN box (SideNavMobilePosition, kol-website 2026-08-25) — the
+ * hop's law above, one element up. `sticky top-0 self-start h-dvh flex
+ * flex-col z-20` rode the className, and a utility outranks every rule in
+ * this layer — so the 767px drawer block below (`position: fixed`) never won:
+ * the aside stayed IN FLOW, the one-column grid handed it an 852px row, and
+ * every consumer page opened one viewport down on phones (probe: aside
+ * `sticky`, content top=852 at 393; the consumer's stopgap was one media rule
+ * re-stating `fixed`). Declared here, the drawer rule beats it by source
+ * order — which is how it was written to work. */
+.kol-sidenav {
+  position: sticky;
+  top: 0;
+  align-self: start;
+  height: 100dvh;
+  display: flex;
+  flex-direction: column;
+  z-index: var(--kol-z-sticky);
+}
+
 /* :root[data-sidenav="collapsed"] — the manual collapse, rebuilt DELIBERATELY
  * 2026-08-09 (lobby: SideNavGrabResize) after the 2026-07-29 removal of the
  * renderer-less stamp. SideNav's grab edge (useDragResize.js) owns the state
@@ -894,7 +923,15 @@ body {
   }
 }
 
-/* Tab strip — horizontally scrollable, scrollbar hidden. */
+/* Tab strip — horizontally scrollable, scrollbar hidden.
+ * Snaps to a tab's start on a flick (WorkshopShellMobile, kol-website
+ * 2026-08-25): the strip measured 613px of tabs in a 345px viewport and did
+ * scroll, but a swipe could settle on half a label. `proximity`, not
+ * `mandatory` — the last tabs can never reach a start position, and mandatory
+ * would refuse to show them. ShellHeader.jsx scrolls the active tab into view
+ * on load, to the same start edge, so the two never fight. NO edge fade: the
+ * 2026-07-28 ruling bans scroll-edge paint (the table wrapper's cover
+ * gradients died for it 2026-08-09). */
 .kol-shell-header-tabs {
   display: flex;
   flex-wrap: nowrap;
@@ -903,6 +940,7 @@ body {
   padding-top: 8px;
   scrollbar-width: none;
   -ms-overflow-style: none;
+  scroll-snap-type: x proximity;
 }
 
 .kol-shell-header-tabs::-webkit-scrollbar {
@@ -931,6 +969,7 @@ body {
   border-bottom: 2px solid transparent;
   transition: color 0.2s ease, border-color 0.2s ease;
   text-decoration: none;
+  scroll-snap-align: start;
 }
 
 .kol-shell-header-tab:hover {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-framework",
-  "version": "0.22.0",
+  "version": "0.24.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",
@@ -28,8 +28,8 @@
     "app-shell"
   ],
   "dependencies": {
-    "@kolkrabbi/kol-component": "^0.46.0",
-    "@kolkrabbi/kol-icons": "^0.17.0"
+    "@kolkrabbi/kol-component": "^0.68.1",
+    "@kolkrabbi/kol-icons": "^0.18.0"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",

package/src/ShellHeader.jsx

@@ -1,3 +1,4 @@
+import { useLayoutEffect, useRef } from 'react'
 import { Icon } from '@kolkrabbi/kol-icons'
 import { IconFrame, SearchInput, Tooltip, glyphSize } from '@kolkrabbi/kol-component'
 import ThemeToggle from './ThemeToggle.jsx'
@@ -89,6 +90,26 @@ export default function ShellHeader({
 }) {
   const hasTabRow = nav.length > 0 || Boolean(search) || Boolean(onNavToggle) || Boolean(onTocToggle)
 
+  /* The current tab must be ON SCREEN (WorkshopShellMobile, kol-website
+   * 2026-08-25). The strip scrolls (.kol-shell-header-tabs) — but on a phone
+   * the active tab measured x=347–445 in a 345px strip: "Dashboard" was the
+   * page you were on and the one tab you could not see. Scrolled to the
+   * strip's start edge (the snap position), and ONLY when it is out of view,
+   * so a wide viewport never moves. Keyed on the active href, not `nav` —
+   * consumers rebuild that array every render. Layout effect: before paint,
+   * so a route change never flashes the wrong tab. */
+  const tabsRef = useRef(null)
+  const activeHref = nav.find((item) => (isActive ? isActive(item.href) : false))?.href
+  useLayoutEffect(() => {
+    const strip = tabsRef.current
+    const tab = strip?.querySelector('[aria-current="page"]')
+    if (!strip || !tab) return
+    const s = strip.getBoundingClientRect()
+    const t = tab.getBoundingClientRect()
+    if (t.left >= s.left && t.right <= s.right) return
+    strip.scrollLeft += t.left - s.left
+  }, [activeHref])
+
   return (
     <header className={`kol-shell-header sticky top-0 z-50 shrink-0 bg-surface-primary ${className}`.trim()}>
       {/* Row 1: brand block + controls */}
@@ -139,7 +160,7 @@ export default function ShellHeader({
       {hasTabRow && (
         <div className="border-b border-fg-08">
           <div className="w-full" style={{ paddingInline: 'var(--kol-pad-chrome-x)' }}>
-            <div className="kol-shell-header-tabs">
+            <div className="kol-shell-header-tabs" ref={tabsRef}>
               <nav className="flex flex-1 gap-6" aria-label="Sections">
                 {nav.map((item) => {
                   const active = isActive ? isActive(item.href) : false

package/src/SideNav.jsx

@@ -13,14 +13,26 @@ import useDragResize from './useDragResize'
  * 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.
+ * A category is a grouping LABEL — a disclosure <button> with a trailing
+ * caret, no route. A page is a route. 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.)
+ * The 2026-08-01 "TWO LEVELS ONLY" ruling was the BRAND APP's, about its
+ * scroll-spied `#anchor` section layer — that layer stays dead (an `{ id }`
+ * leaf is dropped). It was inscribed here as a law for every consumer, and
+ * kol-studio lost two groups and six routes from its rail on adopting 0.23.0.
+ * User, 2026-08-26, verbatim: "ok that is such a problem, sometimes Im
+ * talking about a specific thing and it gets applied as a literal fit-all
+ * rule, which isnt the case. its very hard to work in such uncertainty."
+ * Re-scoped (sidenav-nested-groups, 0.24.0): nested ROUTE groups are
+ * supported. A `{ label, children }` node inside a category renders as a
+ * non-routing group header with its rows indented one step under it,
+ * recursively. The tree shape is the opt-in — there is no prop — and a tree
+ * with no group nodes renders byte-for-byte as before.
+ *
+ * navTree: [{ id, label, icon, to?, pages?: [{ label, to } | { label, children }] }]
+ * (legacy `children` on a category is read as `pages`; section anchors are not.)
  *
  * Collapse: the pill-marked grab edge is THE single control (user build
  * order 2026-08-09, completing SideNavGrabResize — the chip Button is gone
@@ -47,9 +59,17 @@ const pageStyle = { '--kol-sidenav-dot-left': '2.625rem' }
 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) ?? []
+/* 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 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]))
+/* A nested row sits one --kol-spacing-3 step further in per depth. Inline,
+ * not a rule: `pl-14` rides the leaf as a utility and outranks anything in
+ * 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({
   drawerOpen = false,
@@ -61,7 +81,7 @@ export default function SideNav({
 }) {
   const { pathname } = useLocation()
   const isPageActive = (to) => (isActive ? isActive(to) : pathname === to)
-  const isActiveCat = (cat) => pagesOf(cat).some((p) => isPageActive(p.to))
+  const isActiveCat = (cat) => leavesOf(pagesOf(cat)).some((p) => isPageActive(p.to))
 
   /* Every navigation closes the mobile drawer — the prop sat accepted-but-
    * unread until the kol-website session flagged it (2026-08-09) — and, from
@@ -90,10 +110,49 @@ export default function SideNav({
   const asideRef = useRef(null)
   const { collapsed, toggleCollapsed, grabProps } = useDragResize(asideRef)
 
+  /* 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))
+      return (
+        <li key={row.id ?? `${row.label}-${i}`}>
+          <div
+            className={`kol-sidenav-group kol-helper-10${lit ? ' text-emphasis' : ' text-subtle'}`}
+            style={depth ? { paddingLeft: indentOf(depth) } : undefined}
+          >
+            {row.label}
+          </div>
+          <ul className="kol-sidenav-list">{renderRows(rowsOf(row.children), depth + 1)}</ul>
+        </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}
+        >
+          {row.label}
+        </NavLink>
+      </li>
+    )
+  })
+
   return (
     <aside
       ref={asideRef}
-      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' : ''}`}
+      /* 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 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
@@ -169,21 +228,7 @@ export default function SideNav({
                   ) : head}
 
                   {!isLink && isOpen && (
-                    <ul className="kol-sidenav-list">
-                      {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={handleNavigate}
-                          >
-                            {page.label}
-                          </NavLink>
-                        </li>
-                      ))}
-                    </ul>
+                    <ul className="kol-sidenav-list">{renderRows(pages, 0)}</ul>
                   )}
                 </li>
               )