@kolkrabbi/kol-workshop 0.32.0 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "private": false,
   "description": "KOL workshop/docs system — a handrolled markdown engine, search, tag system (incl. a d3 tag graph), docs viewer, and docs shell. Sits above @kolkrabbi/kol-{theme,icons,component,framework}; content is consumer-injected (the package never globs docs).",
   "license": "MIT",
@@ -13,12 +13,12 @@
   },
   "dependencies": {
     "d3": "^7.9.0",
-    "@kolkrabbi/kol-brand": "^0.1.3",
     "@kolkrabbi/kol-markdown": "^0.1.2",
-    "@kolkrabbi/kol-search": "^0.2.0"
+    "@kolkrabbi/kol-search": "^0.2.0",
+    "@kolkrabbi/kol-brand": "^0.1.3"
   },
   "peerDependencies": {
-    "@kolkrabbi/kol-component": ">=0.228.0",
+    "@kolkrabbi/kol-component": ">=0.231.0",
     "@kolkrabbi/kol-framework": ">=0.45.0",
     "@kolkrabbi/kol-theme": ">=0.155.0",
     "@kolkrabbi/kol-icons": ">=0.18.0",
@@ -27,10 +27,10 @@
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.230.0",
-    "@kolkrabbi/kol-icons": "^0.30.0",
-    "@kolkrabbi/kol-theme": "^0.158.0",
-    "@kolkrabbi/kol-framework": "^0.47.0"
+    "@kolkrabbi/kol-icons": "^0.31.0",
+    "@kolkrabbi/kol-component": "^0.231.0",
+    "@kolkrabbi/kol-theme": "^0.159.0",
+    "@kolkrabbi/kol-framework": "^0.48.0"
   },
   "files": [
     "src",

package/src/docs/DocumentationReader.jsx

@@ -85,6 +85,9 @@ const DocumentationReader = ({
   routes = {},
   docId: docIdProp,
   showFrontmatter = true,
+  /* false → render the article only and leave the right rail to the page (a HOME sits on top of
+   * a page whose sections the rail must list — 2026-09-30, "This page (0)" on every home) */
+  rail = true,
 }) => {
   const {
     docsIndex = '/docs',
@@ -309,7 +312,7 @@ const DocumentationReader = ({
    * ShellTocContext then defaults to null, so calling it unguarded threw.
    * No shell → no right rail, and the reader just renders its article. */
   useEffect(() => {
-    if (!setTocContent) return undefined
+    if (!setTocContent || !rail) return undefined
     setTocContent(
       <DocReaderSidebar
         key={docId}
@@ -324,7 +327,7 @@ const DocumentationReader = ({
       />
     )
     return () => setTocContent(null)
-  }, [setTocContent, docId, toc, allTags, topTags, related, docsIndex, components, docFilePath])
+  }, [rail, setTocContent, docId, toc, allTags, topTags, related, docsIndex, components, docFilePath])
 
   if (!doc) {
     return (

package/src/shell/RailSection.jsx

@@ -1,5 +1,6 @@
 import { useState } from 'react'
 import { Link } from 'react-router-dom'
+import { Icon } from '@kolkrabbi/kol-component'
 
 /**
  * RailSection — THE rail ladder. One component owns every rail header, at
@@ -70,7 +71,7 @@ export default function RailSection({
   onToggle,
   defaultCollapsed = false,
   onNavigate,
-  icon: IconComponent,
+  icon: IconComponent = Icon,
   children,
 }) {
   const [internal, setInternal] = useState(defaultCollapsed)
@@ -120,14 +121,16 @@ export default function RailSection({
    * the eyebrow felt expand-only. A category's door lives in the header tabs.
    * L2 keeps the split (2026-08-02 ruling): its label is a chapter's only
    * door to the landing page, and the chevron marks the toggle. */
-  const labelNode = to && level === 2 ? (
+  /* L1 JOINS L2 (2026-09-30, user: every label opens its home — *"components from the top and
+   * components go to the same components home"*; reverses the 2026-08-09 pure-toggle eyebrow). */
+  const labelNode = to ? (
     /* The label navigates; the rest of the row toggles. stopPropagation keeps
      * one click from doing both. */
     <Link
       to={to}
       onClick={(e) => {
+        /* the label opens the page, the chevron folds (audit § Homes) */
         e.stopPropagation()
-        if (isCollapsed && toggle) toggle()
         if (onNavigate) onNavigate(e)
       }}
     >

package/src/shell/ShellLayout.jsx

@@ -2,7 +2,7 @@ import { createContext, useContext, useMemo, useRef, useState, useEffect, Suspen
 import { Outlet, Link, useLocation, useNavigate } from 'react-router-dom'
 import { ShellHeader } from '@kolkrabbi/kol-framework'
 import ShellSidebar, { RAIL_FOLD_EVENT } from './ShellSidebar.jsx'
-import { IconFrame, ShellDrawer, ShellSearchOverlay, ShortcutsOverlay, SettingsSections, SettingsSwitch, Tooltip } from '@kolkrabbi/kol-component'
+import { IconFrame, ShellDrawer, ShellSearchOverlay, ShortcutsOverlay, SettingsPanel, SettingsSections, SettingsSwitch, Tooltip, useDragResize } from '@kolkrabbi/kol-component'
 import { createIndex, search } from '@kolkrabbi/kol-search'
 import { useTagMode } from '../tags/TagModeContext.jsx'
 import TagModeOverlay from '../tags/TagModeOverlay.jsx'
@@ -79,37 +79,27 @@ export const SHELL_SCROLL_ROOT = '#shell-scroll'
  * overflow (`.shell-rail`, kol-components-workshop.css): exactly one region
  * tall, a seam toward the page, the chrome inset inside the seam.
  * overflow-x-hidden (2026-07-30): long tree rows must not scroll sideways. */
-/* RESIZABLE RAILS (2026-09-30, the names audit; Round 3 Q3 — decided on the recommendation, the
- * user asleep, for review). A 6px grab strip on the edge facing the page: drag to set the width
- * (200–420, remembered), double-click to reset to the shell's 256. The width is the shell's own
- * token, `--kol-shell-nav-w` / `--kol-shell-toc-w`, set on the shell root, so the grid tracks and
- * the rail's own box follow it. */
-const RAIL_MIN = 200
-const RAIL_MAX = 420
-const RailGrip = ({ side, width, onChange }) => {
-  const start = (e) => {
-    e.preventDefault()
-    const x0 = e.clientX
-    const w0 = width
-    const move = (m) => onChange(Math.round(Math.min(RAIL_MAX, Math.max(RAIL_MIN, w0 + (side === 'end' ? m.clientX - x0 : x0 - m.clientX)))))
-    const up = () => { window.removeEventListener('pointermove', move); window.removeEventListener('pointerup', up) }
-    window.addEventListener('pointermove', move)
-    window.addEventListener('pointerup', up)
-  }
-  return (
-    <div
-      role="separator"
-      aria-orientation="vertical"
-      aria-label="Resize rail"
-      onPointerDown={start}
-      onDoubleClick={() => onChange(null)}
-      className={`absolute top-0 hidden h-full w-1.5 cursor-col-resize hover:bg-oq-08 lg:block ${side === 'end' ? 'right-0' : 'left-0'}`}
-    />
-  )
+/* RESIZABLE RAILS (2026-09-30) — THE DS GESTURE, not a local one: `useDragResize` (the grab edge
+ * SideNav and EditorShell wear — drag resizes, a click or a drag under the snap collapses, arrows
+ * step, release near the default snaps back) and the `.kol-rail-grab` pill. Each rail has its own
+ * token family (`kol-shell-nav` · `kol-shell-toc`, tokens in kol-framework.css) so the two never
+ * drag together; width lasts the session (persistWidth off, the 2026-09-03 ruling). A collapse
+ * from the grab is the shell's own "hide the rail" — the same state `[` / `]` toggle. */
+const useRailGrab = (token, side, hide) => {
+  const ref = useRef(null)
+  const { collapsed, toggleCollapsed, grabProps } = useDragResize(ref, { token, side })
+  useEffect(() => {
+    if (!collapsed) return
+    hide()
+    toggleCollapsed() // un-stamp the hook's collapse — the shell's own state now holds it
+    document.documentElement.style.removeProperty(`--${token}-w`) // it returns at the stylesheet width
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [collapsed])
+  return { ref, grab: <div {...grabProps} className={`kol-rail-grab kol-rail-grab--${side} hidden lg:block`} /> }
 }
 
-const NavColumn = ({ children, grip }) => (
-  <aside 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">
+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">
     {children}
     {grip}
   </aside>
@@ -148,8 +138,8 @@ const MainColumn = ({ children, fullHeight, width = 'canvas', padStart, padEnd }
 /* `xl`, not `lg` — the grid only declares a third column at xl (gridCols
  * below). The breakpoint here and the one in gridCols are one decision and
  * must not be stated twice differently. */
-const TocColumn = ({ children, grip }) => (
-  <aside 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">
+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">
     {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
@@ -195,11 +185,10 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
   const [prefs, setPrefs] = useState(readSettings)
   const setPref = (key, value) => setPrefs((p) => { const next = { ...p, [key]: value }; writeSettings(next); return next })
   const [navCollapsed, setNavCollapsed] = useState(() => readSettings().navHidden === true)
-  /* rail widths — null = the shell's token; a number is the viewer's own (remembered) */
-  const [navW, setNavW] = useState(() => readSettings().navW ?? null)
-  const [tocW, setTocW] = useState(() => readSettings().tocW ?? null)
-  const setRailW = (key, set) => (w) => { set(w); writeSettings({ ...readSettings(), [key]: w }) }
+
   const [tocCollapsed, setTocCollapsed] = useState(() => readSettings().tocHidden === true)
+  const navGrab = useRailGrab('kol-shell-nav', 'left', () => { setNavCollapsed(true); writeSettings({ ...readSettings(), navHidden: true }) })
+  const tocGrab = useRailGrab('kol-shell-toc', 'right', () => { setTocCollapsed(true); writeSettings({ ...readSettings(), tocHidden: true }) })
   const [isSettingsOpen, setIsSettingsOpen] = useState(false)
   /* ONE QUERY (user ruling 2026-08-01). The palette's text used to live here
    * while tags lived in TagModeContext — two states, and therefore two
@@ -254,8 +243,7 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
    * app — it was a `?` sheet of its own here. `?` still opens it. */
   const SHORTCUTS = [
     { section: 'Search', items: [
-      { id: 'k', label: 'Search everything', combo: '⌘ K' },
-      { id: 'slash', label: 'Search everything', combo: '/' },
+      { id: 'k', label: 'Search everything', combo: '⌘ K , /' },
       { id: 'enter', label: 'All results, on the search page', combo: '↵' },
     ] },
     { section: 'Shell', items: [
@@ -465,10 +453,7 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
         <ShellContentWidthContext.Provider value={setContentWidth}>
         <ShellTocCollapsedContext.Provider value={setTocCollapsed}>
         <ShellNavCollapsedContext.Provider value={setNavCollapsed}>
-        <div
-          className="fixed inset-0 flex flex-col bg-surface-primary text-auto"
-          style={{ ...(navW ? { '--kol-shell-nav-w': `${navW}px` } : {}), ...(tocW ? { '--kol-shell-toc-w': `${tocW}px` } : {}) }}
-        >
+        <div className="fixed inset-0 flex flex-col bg-surface-primary text-auto">
           <ShellHeader
             brand={brand}
             nav={navItems}
@@ -503,7 +488,7 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
           >
               <div className={`shell-content-grid grid ${gridCols}`} data-layout={layoutType} style={{ paddingInline: 'var(--kol-pad-chrome-x)' }}>
                   {showNav && (
-                    <NavColumn grip={<RailGrip side="end" width={navW ?? 256} onChange={setRailW('navW', setNavW)} />}>
+                    <NavColumn railRef={navGrab.ref} grip={navGrab.grab}>
                       {renderSidebar ? renderSidebar({ activeRoute }) : <ShellSidebar routes={routes} basePath={basePath} />}
                     </NavColumn>
                   )}
@@ -521,7 +506,7 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
                     * the grid's third track so main keeps one width across
                     * every route (user ruling 2026-08-01). */}
                   {showToc && (
-                    <TocColumn grip={<RailGrip side="start" width={tocW ?? 256} onChange={setRailW('tocW', setTocW)} />}>
+                    <TocColumn railRef={tocGrab.ref} grip={tocGrab.grab}>
                       {effectiveTocContent}
                     </TocColumn>
                   )}
@@ -550,6 +535,8 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
             query={searchQuery}
             onQueryChange={setSearchQuery}
             results={searchResults}
+            /* an empty palette opens on the space table, not a blank box */
+            suggestions={navItems.map((n) => ({ id: `space:${n.href}`, label: n.label, href: n.href, icon: 'arrow-right', group: 'Spaces' }))}
             /* THE EXPANDED BODY (user ruling 2026-08-01). The tag browser is
              * not a sibling overlay — it is this palette's second state. Enter
              * commits the query and swaps the result rows for the full body;
@@ -588,13 +575,12 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
             * settings page or settings sidebar … to offload some functional
             * settings, search settings, sidenav settings"). A right drawer over
             * the page, the same rows the apps' settings use (SettingsSections). */}
-          <ShellDrawer open={isSettingsOpen} onClose={() => setIsSettingsOpen(false)} side="right" width={360}>
-            {/* the drawer draws its own close — no second one here */}
-            <div className="flex flex-col gap-6 p-6">
-              <span className="kol-doc-eyebrow">Settings</span>
-              <SettingsSections sections={settingsSections} labelWidth="auto" />
-            </div>
-          </ShellDrawer>
+          {/* THE APPROVED DRAWER (2026-09-30): kol-component's `SettingsPanel` — the composition locked
+            * 2026-08-27 that media's Display settings and Trash already wear: title header, divided
+            * sections. This was a hand-built ShellDrawer + eyebrow + undivided sections. */}
+          <SettingsPanel open={isSettingsOpen} variant="drawer" title="Settings" onClose={() => setIsSettingsOpen(false)}>
+            <SettingsSections sections={settingsSections} divided />
+          </SettingsPanel>
         </div>
         </ShellNavCollapsedContext.Provider>
         </ShellTocCollapsedContext.Provider>

package/src/shell/ShellSidebar.jsx

@@ -37,39 +37,26 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
   const navCollapsed = isControlled ? collapsed : internalCollapsed
   const handleToggle = isControlled ? onToggle : () => setInternalCollapsed(prev => !prev)
 
-  const [collapsedSections, setCollapsedSections] = useState(() => {
-    const initial = {}
-    routes.forEach((route) => {
-      const sectionPath = getSectionRootPath(route, basePath)
-      const isActive =
-        sectionPath === basePath
-          ? normalizedPath === basePath
-          : normalizedPath === sectionPath || normalizedPath.startsWith(sectionPath + '/')
-      initial[route.id] = !isActive
-    })
-    return initial
+  /* 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
+   * 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(/\/$/, '')
+    return normalizedPath === cp || normalizedPath.startsWith(cp + '/')
   })
-
-  /* THE RAIL FOLLOWS YOU (2026-09-28, user: "the sidebar doesnt highlight that
-   * part, which it probably should by closing/collapsing other categories").
-   * Arriving in a group opens it AND folds its siblings, so the open group is
-   * the one you are in. Opening another by hand still works until you move. */
-  const isRouteActive = (route) => {
-    const sectionPath = getSectionRootPath(route, basePath)
-    const own = sectionPath === basePath
-      ? normalizedPath === basePath
-      : normalizedPath === sectionPath || normalizedPath.startsWith(sectionPath + '/')
-    return own || (route.children ?? []).some((c) => {
-      const cp = getChildPath(c, basePath).replace(/\/$/, '')
-      return normalizedPath === cp || normalizedPath.startsWith(cp + '/')
-    })
+  const followed = () => {
+    const hit = routes.find(holdsPage)
+    return hit ? Object.fromEntries(routes.map((r) => [r.id, r !== hit])) : null
   }
+  const [collapsedSections, setCollapsedSections] = useState(() => followed() ?? {})
   useEffect(() => {
-    const active = routes.filter(isRouteActive)
-    if (!active.length) return
-    setCollapsedSections(Object.fromEntries(routes.map((r) => [r.id, !active.includes(r)])))
+    const next = followed()
+    if (next) setCollapsedSections(next)
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [normalizedPath, routes, basePath])
+  const isFolded = (route) => collapsedSections[route.id] ?? true
 
   /* 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. */
@@ -80,7 +67,7 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
   }, [routes])
 
   const handleSectionClick = (route) => {
-    setCollapsedSections((prev) => ({ ...prev, [route.id]: !prev[route.id] }))
+    setCollapsedSections((prev) => ({ ...prev, [route.id]: !(prev[route.id] ?? true) }))
   }
 
   /* The L1 count is every leaf row under it — RailSection shows it only while
@@ -111,27 +98,34 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
              * it should. `collapsible` is what that distinction is now. */
             const hasChildren = route.children?.length > 0
 
+            /* 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={hasChildren ? route.children.length : undefined}
-                  /* THE HEADER ALWAYS LINKS (2026-08-02). It used to link only
-                   * when the group had NO children, so a chapter with pages had
-                   * a dead header and its index had to ride as a row inside
-                   * itself. RailSection already separates the two gestures —
-                   * the label navigates, the rest of the row toggles — so a
-                   * group can open its landing page and still collapse. */
+                  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)}
-                  collapsible={hasChildren}
-                  collapsed={!!collapsedSections[route.id]}
+                  collapsed={isFolded(route)}
                   onToggle={() => handleSectionClick(route)}
                   onNavigate={onNavigate}
                   icon={Icon}
                 >
                   <nav className="shell-nav-items">
-                    {(route.children ?? []).map((child) => (
+                    {route.children.map((child) => (
                       <RailRow
                         key={child.id}
                         to={getChildPath(child, basePath)}