@kolkrabbi/kol-workshop 0.33.0 → 0.34.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.33.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-search": "^0.2.0",
     "@kolkrabbi/kol-markdown": "^0.1.2",
+    "@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-icons": "^0.30.0",
-    "@kolkrabbi/kol-framework": "^0.48.0",
+    "@kolkrabbi/kol-icons": "^0.31.0",
+    "@kolkrabbi/kol-component": "^0.231.0",
     "@kolkrabbi/kol-theme": "^0.159.0",
-    "@kolkrabbi/kol-component": "^0.230.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/index.js

@@ -14,6 +14,4 @@ export * from './tags/index.js'
 export * from './exhibit/index.js'
 export * from './compositions/index.js'
 export * from './search/index.js'
-/* retiring — ContentRow replaces it (retirement ledger, 2026-09-30) */
-export { default as ResultRow } from './search/ResultRow.jsx'
 export * from './engine/index.js'

package/src/search/ResultRow.jsx

@@ -1,28 +1,33 @@
-/**
- * @deprecated — use kol-component's `ContentRow` (variant `article`, `media={false}`). ResultRow was
- * minted 2026-09-30 for the search page while the design system already shipped its row; it
- * forwards to ContentRow and drops at 30 days on the retirement ledger. `variant` is ignored.
- */
-
-import { useNavigate } from 'react-router-dom'
-import { ContentRow } from '@kolkrabbi/kol-component'
+import { Link } from 'react-router-dom'
 
 /**
- * @deprecated — use kol-component's `ContentRow` (variant `article`, `media={false}`). ResultRow was
- * minted 2026-09-30 for the search page while the design system already shipped its row; it
- * forwards to ContentRow and drops at 30 days on the retirement ledger. `variant` is ignored.
+ * ResultRow — one search result: a title, a meta line, an optional description, the whole row a
+ * link (2026-09-30, open questions Round 2 — the user: *"I like both, is this a component? if it
+ * is I would just have it available as variants … underline is more appealing currently"*).
+ *
+ * Two variants, each a complete pair — the wash needs its x padding, the underline must not have
+ * one (Round 1: x padding without a wash was drawn wrong):
+ *   `underline` (default) — no ground; the title underlines and the row inks up on hover
+ *   `wash`                — x padding and a ground wash on hover
+ *
+ * @param {string}    to           the route the row opens
+ * @param {ReactNode} title        the result's name (a highlighted node is fine)
+ * @param {string}    [meta]       kind · category · space · date
+ * @param {ReactNode} [description]
+ * @param {'underline'|'wash'} [variant='underline']
  */
-export default function ResultRow({ to, title, meta, description }) {
-  const navigate = useNavigate()
+const VARIANTS = {
+  underline: { row: 'group flex flex-col gap-1 py-3 opacity-80 hover:opacity-100 focus-visible:opacity-100', title: 'group-hover:underline underline-offset-4' },
+  wash: { row: 'flex flex-col gap-1 px-3 py-3 hover:bg-fg-04', title: '' },
+}
+
+export default function ResultRow({ to, title, meta, description, variant = 'underline' }) {
+  const v = VARIANTS[variant] ?? VARIANTS.underline
   return (
-    <ContentRow
-      variant="article"
-      media={false}
-      href={to}
-      onNavigate={(e) => { e.preventDefault(); navigate(to) }}
-      eyebrow={meta}
-      title={title}
-      body={description}
-    />
+    <Link to={to} className={v.row}>
+      <span className={`kol-doc-body text-emphasis ${v.title}`.trim()}>{title}</span>
+      {meta && <span className="kol-helper-12 text-subtle">{meta}</span>}
+      {description && <span className="kol-doc-body">{description}</span>}
+    </Link>
   )
 }

package/src/search/SearchPage.jsx

@@ -1,6 +1,7 @@
 import { Fragment, useMemo } from 'react'
-import { useNavigate, useSearchParams } from 'react-router-dom'
-import { Button, ContentRow, EmptyState, Input, Pill } from '@kolkrabbi/kol-component'
+import { useSearchParams } from 'react-router-dom'
+import { Button, EmptyState, Input, Pill } from '@kolkrabbi/kol-component'
+import ResultRow from './ResultRow.jsx'
 import { createIndex, search, parseQuery } from '@kolkrabbi/kol-search'
 import { DocHeader, DocSection } from '../docs/DocKit.jsx'
 
@@ -44,8 +45,7 @@ const readToken = (t) => (t.kind === 'term'
     ? `${t.field} ${t.value}`
     : `${t.negate ? 'not ' : ''}${t.field === 'tags' ? 'tag' : t.field}: ${t.value}${t.via === 'smart' ? ' (from the word)' : ''}`)
 
-export default function SearchPage({ items = [], spaces = [], facets = DEFAULT_FACETS, limit = 60 }) {
-  const navigate = useNavigate()
+export default function SearchPage({ items = [], spaces = [], facets = DEFAULT_FACETS, limit = 60, rowVariant = 'underline' }) {
   const [params, setParams] = useSearchParams()
   const q = params.get('q') ?? ''
   const index = useMemo(() => createIndex(items), [items])
@@ -125,16 +125,12 @@ export default function SearchPage({ items = [], spaces = [], facets = DEFAULT_F
           <ol className="flex flex-col">
             {out.results.map((r) => (
               <li key={r.item.id} className="border-t border-fg-08 first:border-t-0">
-                {/* THE SHIPPED ROW (2026-09-30): kol-component's ContentRow, the row form of the
-                  * content-card system — not a row minted here. Article form, no cover. */}
-                <ContentRow
-                  variant="article"
-                  media={false}
-                  href={r.item.href}
-                  onNavigate={(e) => { e.preventDefault(); navigate(r.item.href) }}
-                  eyebrow={[r.item.kind, r.item.category, r.item.space, r.item.date].filter(Boolean).join(' · ')}
+                <ResultRow
+                  to={r.item.href}
+                  variant={rowVariant}
                   title={<Highlight text={r.item.title} ranges={r.highlights.title} />}
-                  body={r.item.description}
+                  meta={[r.item.kind, r.item.category, r.item.space, r.item.date].filter(Boolean).join(' · ')}
+                  description={r.item.description}
                 />
               </li>
             ))}

package/src/search/index.js

@@ -1 +1,2 @@
 export { default as SearchPage } from './SearchPage.jsx'
+export { default as ResultRow } from './ResultRow.jsx'

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

@@ -243,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: [
@@ -536,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;

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)}