@kolkrabbi/kol-workshop 0.34.0 → 0.36.0

package/src/shell/ShellLayout.jsx

@@ -1,5 +1,5 @@
 import { createContext, useContext, useMemo, useRef, useState, useEffect, Suspense } from 'react'
-import { Outlet, Link, useLocation, useNavigate } from 'react-router-dom'
+import { Outlet, Link, useLocation, useNavigate, useNavigationType } from 'react-router-dom'
 import { ShellHeader } from '@kolkrabbi/kol-framework'
 import ShellSidebar, { RAIL_FOLD_EVENT } from './ShellSidebar.jsx'
 import { IconFrame, ShellDrawer, ShellSearchOverlay, ShortcutsOverlay, SettingsPanel, SettingsSections, SettingsSwitch, Tooltip, useDragResize } from '@kolkrabbi/kol-component'
@@ -99,7 +99,7 @@ const useRailGrab = (token, side, hide) => {
 }
 
 const NavColumn = ({ children, grip, railRef }) => (
-  <aside ref={railRef} aria-label="Navigation" className="shell-rail shell-rail--nav shell-sidebar-sticky hidden lg:block pt-6 md:pt-6 lg:pt-8 pb-8">
+  <aside ref={railRef} aria-label="Navigation" className="shell-rail shell-rail--nav shell-sidebar-sticky hidden lg:block pt-6 md:pt-6 lg:pt-8 pb-14">
     {children}
     {grip}
   </aside>
@@ -139,7 +139,7 @@ const MainColumn = ({ children, fullHeight, width = 'canvas', padStart, padEnd }
  * below). The breakpoint here and the one in gridCols are one decision and
  * must not be stated twice differently. */
 const TocColumn = ({ children, grip, railRef }) => (
-  <aside ref={railRef} aria-label="Table of contents" className="shell-rail shell-rail--toc shell-sidebar-sticky hidden xl:block pt-6 md:pt-6 lg:pt-8 pb-8">
+  <aside ref={railRef} aria-label="Table of contents" className="shell-rail shell-rail--toc shell-sidebar-sticky hidden xl:block pt-6 md:pt-6 lg:pt-8 pb-14">
     {grip}
     {/* The width is the grid track (--kol-shell-toc-w). An empty rail still
       * holds its column (user ruling 2026-08-01): a rail that disappears
@@ -231,28 +231,58 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
 
   /* a new page starts at the top of the one scroll region; a hash is the
    * browser's to resolve */
+  /* BACK RETURNS TO WHERE YOU WERE (2026-10-01 — user: "'back' loses the place vertically in the
+   * scroll … now I have to scroll and find my place"). Each history entry remembers its own
+   * scroll offset; Back/Forward (POP) restores it, a fresh navigation still starts at the top.
+   * The page may still be laying out when the entry returns (lazy walls, async demos), so the
+   * restore is retried for a moment until the region is tall enough to reach the offset. */
+  const navigationType = useNavigationType()
+  const scrollMemory = useRef(new Map())
   useEffect(() => {
-    if (location.hash) return
-    document.getElementById('shell-scroll')?.scrollTo(0, 0)
-  }, [location.pathname, location.hash])
+    const el = document.getElementById('shell-scroll')
+    if (!el) return undefined
+    const key = location.key
+    const save = () => scrollMemory.current.set(key, el.scrollTop)
+    el.addEventListener('scroll', save, { passive: true })
+    return () => el.removeEventListener('scroll', save)
+  }, [location.key])
+  useEffect(() => {
+    if (location.hash) return undefined
+    const el = document.getElementById('shell-scroll')
+    if (!el) return undefined
+    const saved = navigationType === 'POP' ? scrollMemory.current.get(location.key) : 0
+    if (!saved) { el.scrollTo(0, 0); return undefined }
+    let frame
+    let tries = 60
+    const restore = () => {
+      el.scrollTo(0, saved)
+      if (Math.abs(el.scrollTop - saved) > 1 && tries-- > 0) frame = requestAnimationFrame(restore)
+    }
+    restore()
+    return () => cancelAnimationFrame(frame)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [location.pathname, location.hash, location.key])
 
   /* THE shortcut map. One list, rendered by the `S` sheet AND bound by the
    * handler below — a shortcut that isn't in this array doesn't exist, so the
    * sheet can never drift from the bindings. The sheet is kol-component's
    * ShortcutsOverlay (2026-09-28): the same sheet, on the same key, as every
    * app — it was a `?` sheet of its own here. `?` still opens it. */
+  /* FEWEST WORDS (the showcase review W16, 2026-09-30 — user: "shortcuts overlay, too wordy"):
+   * a label names the thing the key does, nothing more. `\\` hides or shows both rails at once. */
   const SHORTCUTS = [
     { section: 'Search', items: [
-      { id: 'k', label: 'Search everything', combo: '⌘ K , /' },
-      { id: 'enter', label: 'All results, on the search page', combo: '↵' },
+      { id: 'k', label: 'Search', combo: '⌘ K , /' },
+      { id: 'enter', label: 'All results', combo: '↵' },
     ] },
     { section: 'Shell', items: [
-      { id: 'sheet', label: 'This sheet', combo: 'S' },
+      { id: 'sheet', label: 'Shortcuts', combo: 'S' },
       { id: 'settings', label: 'Settings', combo: ',' },
       { id: 'nav', label: 'Left rail', combo: '[' },
       { id: 'toc', label: 'Right rail', combo: ']' },
-      { id: 'fold', label: 'Fold or open every chapter', combo: 'C' },
-      { id: 'esc', label: 'Close what is open', combo: 'Esc' },
+      { id: 'rails', label: 'Both rails', combo: '\\' },
+      { id: 'fold', label: 'Fold all', combo: 'C' },
+      { id: 'esc', label: 'Close', combo: 'Esc' },
     ] },
     ...(shortcuts.length ? [{ section: 'Page', items: shortcuts.map(({ id, label, combo }) => ({ id, label, combo })) }] : []),
   ]
@@ -288,6 +318,14 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
       } else if (e.key === ']') {
         e.preventDefault()
         setTocCollapsed((v) => { writeSettings({ ...readSettings(), tocHidden: !v }); return !v })
+      } else if (e.key === '\\') {
+        /* BOTH RAILS (W16): any rail showing → hide both; both hidden → show both */
+        e.preventDefault()
+        const s = readSettings()
+        const hide = !(s.navHidden && s.tocHidden)
+        setNavCollapsed(hide)
+        setTocCollapsed(hide)
+        writeSettings({ ...s, navHidden: hide, tocHidden: hide })
       } else if (e.key === 'c' || e.key === 'C') {
         e.preventDefault()
         foldedRef.current = !foldedRef.current
@@ -437,7 +475,7 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
       { id: 'toc', label: 'Right rail', render: () => <SettingsSwitch on={!tocCollapsed} onChange={(on) => { setTocCollapsed(!on); setPref('tocHidden', !on) }} /> },
     ] },
     { label: 'Search', rows: [
-      { id: 'scope', label: 'Quick search in this space only', render: () => <SettingsSwitch on={!!prefs.limitToSpace} onChange={(on) => setPref('limitToSpace', on)} /> },
+      { id: 'scope', label: 'This space only', render: () => <SettingsSwitch on={!!prefs.limitToSpace} onChange={(on) => setPref('limitToSpace', on)} /> },
     ] },
     ...settings,
     { label: 'Keys', rowGap: 1, rows: SHORTCUTS.flatMap((sec) => sec.items).map((k) => ({
@@ -549,6 +587,10 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
              * it. Without a `searchPath` Enter keeps the older in-place browser. */
             onExpand={searchPath ? openResultsPage : () => tagMode.setExpanded?.(true)}
             enterLabel={searchPath ? `All results for “${searchQuery.trim()}”` : undefined}
+            /* ⌘ENTER AND THE FOOTER LINK open the results page (2026-10-01); plain Enter opens
+             * the highlighted row and only falls through to the page when nothing matched. */
+            onOpenResults={searchPath ? openResultsPage : undefined}
+            resultsLabel={`All results for “${searchQuery.trim()}”`}
             chips={tagMode.isProvided ? tagMode.activeTags : []}
             onRemoveChip={tagMode.removeTag}
             placeholder="Search…"

package/src/shell/ShellSidebar.jsx

@@ -39,16 +39,44 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
 
   /* THE RAIL FOLLOWS YOU — INTO A CHILD ONLY (2026-09-30, reversing the 2026-09-28 "open the
    * group you are in" on its landing page too). Landing on a page INSIDE a chapter opens that
-   * chapter and folds the rest; a chapter's own home opens nothing. Every other chapter starts
+   * chapter and folds the rest; a chapter's own home keeps that chapter open (2026-10-01, see
+   * `chainTo`). Every other chapter starts
    * folded — including ones this rail has never seen (a Group-by switch hands it new ids, and an
-   * unknown id used to read as open, so every chapter sprang open). */
-  const holdsPage = (route) => (route.children ?? []).some((c) => {
-    const cp = getChildPath(c, basePath).replace(/\/$/, '')
+   * unknown id used to read as open, so every chapter sprang open).
+   *
+   * ANY DEPTH (2026-09-30, the showcase review W1 — user: Library › Composition › Components ›
+   * Atoms › Button). A chapter may hold chapters; every group at every depth is a fold of its own,
+   * and the chain down to where you are opens and everything off it folds. */
+  const isHere = (route) => {
+    /* a pathless group is not a place — without this its basePath fallback matched every URL */
+    if (!route.path) return false
+    const cp = getChildPath(route, basePath).replace(/\/$/, '')
     return normalizedPath === cp || normalizedPath.startsWith(cp + '/')
-  })
+  }
+  const groupsOf = (list) => list.flatMap((r) => (r.children?.length ? [r, ...groupsOf(r.children)] : []))
+  /* ONE PLACE YOU ARE (W4, 2026-09-30). A page can sit in more than one group — Button is an
+   * atom AND a member of every set that uses it — and opening every group that holds it would
+   * unfold half the rail. The first place in tree order wins: its chain opens, the rest fold. */
+  const chainTo = (list, trail = []) => {
+    for (const r of list) {
+      if (!r.children?.length) continue
+      /* deepest first: `/sets` holds `/sets/app-shell` by prefix, but the set's own row is the place */
+      const deeper = chainTo(r.children, [...trail, r])
+      if (deeper) return deeper
+      if (r.children.some(isHere)) return [...trail, r]
+      /* A GROUP'S OWN HOME KEEPS IT OPEN (user 2026-10-01: *"I dont want to collapse the list
+       * like that when I just want to go to atoms home and still see the atoms list"* — reverses
+       * the 2026-09-30 "a chapter's own home opens nothing"). The label is a link; only the
+       * chevron folds. */
+      if (r.path && getChildPath(r, basePath).replace(/\/$/, '') === normalizedPath) return [...trail, r]
+    }
+    return null
+  }
   const followed = () => {
-    const hit = routes.find(holdsPage)
-    return hit ? Object.fromEntries(routes.map((r) => [r.id, r !== hit])) : null
+    const chain = chainTo(routes)
+    if (!chain) return null
+    const open = new Set(chain.map((g) => g.id))
+    return Object.fromEntries(groupsOf(routes).map((g) => [g.id, !open.has(g.id)]))
   }
   const [collapsedSections, setCollapsedSections] = useState(() => followed() ?? {})
   useEffect(() => {
@@ -61,7 +89,7 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
   /* FOLD ALL (2026-09-30, the names audit: *"shortcut collapse/expand the categories"*). The
    * shell's `C` key broadcasts one target state; every rail's chapters take it. */
   useEffect(() => {
-    const onFold = (e) => setCollapsedSections(Object.fromEntries(routes.map((r) => [r.id, !!e.detail?.collapsed])))
+    const onFold = (e) => setCollapsedSections(Object.fromEntries(groupsOf(routes).map((r) => [r.id, !!e.detail?.collapsed])))
     window.addEventListener(RAIL_FOLD_EVENT, onFold)
     return () => window.removeEventListener(RAIL_FOLD_EVENT, onFold)
   }, [routes])
@@ -71,8 +99,37 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
   }
 
   /* The L1 count is every leaf row under it — RailSection shows it only while
-   * the section is folded (2026-09-28). */
-  const leafCount = routes.reduce((n, r) => n + (r.children?.length ? r.children.length : 1), 0)
+   * the section is folded (2026-09-28). At any depth: leaves, not groups. */
+  const leavesOf = (list) => list.reduce((n, r) => n + (r.children?.length ? leavesOf(r.children) : 1), 0)
+  const leafCount = leavesOf(routes)
+
+  /* ONE GROUP, AT ANY DEPTH. A chapter's child with children of its own is a chapter again — the
+   * same RailSection rung, the same count and chevron, stepped in one row-indent by `.shell-nav-nest`
+   * so its caret sits on its siblings' text edge. A leaf is a RailRow wherever it lands. */
+  const renderGroup = (route) => (
+    <RailSection
+      level={2}
+      label={route.label}
+      count={route.children.length}
+      /* THE HEADER ALWAYS LINKS (2026-08-02): the label opens the chapter's home,
+       * the chevron folds. */
+      to={route.path ?? getSectionRootPath(route, basePath)}
+      collapsed={isFolded(route)}
+      onToggle={() => handleSectionClick(route)}
+      onNavigate={onNavigate}
+      icon={Icon}
+    >
+      <nav className="shell-nav-items">
+        {route.children.map((child) => (child.children?.length ? (
+          <div key={child.id} className="shell-nav-nest">{renderGroup(child)}</div>
+        ) : (
+          <RailRow key={child.id} to={getChildPath(child, basePath)} onNavigate={onNavigate}>
+            {child.label}
+          </RailRow>
+        )))}
+      </nav>
+    </RailSection>
+  )
   return (
     /* One rail layout, one class (2026-08-01). This was `space-y-4` against the
      * right rail's `space-y-6` against the outer `flex flex-col gap-6` — three
@@ -90,55 +147,30 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
         icon={Icon}
       >
         <div className="shell-rail-stack-inner">
-          {routes.map((route) => {
-            /* A group with no children is not a group — it is a link. It used
-             * to render as a header anyway: a chevron that rotated over an
-             * empty body, no count, and no navigation, so clicking "Icons" or
-             * "Components" in the tree did nothing at all while looking like
-             * it should. `collapsible` is what that distinction is now. */
-            const hasChildren = route.children?.length > 0
-
+          {/* LOOSE ROWS SHARE ONE LIST (the showcase review W12, 2026-09-30 — user: "the spaces are
+            * incorrect in the left sidebar"). Each childless entry rendered its own <nav>, and the
+            * stack's 16px gap landed between every pair, so a rail of four rows (Search) read 46px
+            * apart instead of a list's 26. Consecutive rows are one run now; a chapter breaks it. */}
+          {routes.reduce((runs, route) => {
+            const last = runs[runs.length - 1]
+            if (!route.children?.length && last && !last.group) last.rows.push(route)
+            else runs.push(route.children?.length ? { group: route } : { rows: [route] })
+            return runs
+          }, []).map((run) => (run.group ? (
+            <div key={run.group.id} className="shell-nav-group">
+              {renderGroup(run.group)}
+            </div>
+          ) : (
             /* A CHILDLESS ENTRY IS A ROW, not a chapter (2026-09-30): drawn at L2 it read as an
              * empty category with a blank caret slot. */
-            if (!hasChildren) {
-              return (
-                <nav key={route.id} className="shell-nav-items">
-                  <RailRow to={route.path ?? getSectionRootPath(route, basePath)} onNavigate={onNavigate}>
-                    {route.label}
-                  </RailRow>
-                </nav>
-              )
-            }
-
-            return (
-              <div key={route.id} className="shell-nav-group">
-                <RailSection
-                  level={2}
-                  label={route.label}
-                  count={route.children.length}
-                  /* THE HEADER ALWAYS LINKS (2026-08-02): the label opens the chapter's home,
-                   * the chevron folds. */
-                  to={route.path ?? getSectionRootPath(route, basePath)}
-                  collapsed={isFolded(route)}
-                  onToggle={() => handleSectionClick(route)}
-                  onNavigate={onNavigate}
-                  icon={Icon}
-                >
-                  <nav className="shell-nav-items">
-                    {route.children.map((child) => (
-                      <RailRow
-                        key={child.id}
-                        to={getChildPath(child, basePath)}
-                        onNavigate={onNavigate}
-                      >
-                        {child.label}
-                      </RailRow>
-                    ))}
-                  </nav>
-                </RailSection>
-              </div>
-            )
-          })}
+            <nav key={run.rows[0].id} className="shell-nav-items">
+              {run.rows.map((route) => (
+                <RailRow key={route.id} to={route.path ?? getSectionRootPath(route, basePath)} onNavigate={onNavigate}>
+                  {route.label}
+                </RailRow>
+              ))}
+            </nav>
+          )))}
         </div>
       </RailSection>
     </div>