@kolkrabbi/kol-workshop 0.35.0 → 0.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "private": false,
   "description": "Docs viewer, shell and tag system",
   "license": "MIT",
@@ -13,14 +13,14 @@
   },
   "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.234.0",
+    "@kolkrabbi/kol-component": ">=0.235.0",
     "@kolkrabbi/kol-framework": ">=0.45.0",
-    "@kolkrabbi/kol-theme": ">=0.161.0",
+    "@kolkrabbi/kol-theme": ">=0.162.0",
     "@kolkrabbi/kol-icons": ">=0.18.0",
     "gsap": "^3.13.0",
     "react": "^18.3.0 || ^19.0.0",
@@ -28,10 +28,10 @@
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.234.0",
-    "@kolkrabbi/kol-icons": "^0.32.0",
+    "@kolkrabbi/kol-component": "^0.235.0",
+    "@kolkrabbi/kol-theme": "^0.162.0",
     "@kolkrabbi/kol-framework": "^0.48.0",
-    "@kolkrabbi/kol-theme": "^0.161.0"
+    "@kolkrabbi/kol-icons": "^0.32.0"
   },
   "files": [
     "src",

package/src/docs/DocumentationReader.jsx

@@ -331,7 +331,9 @@ const DocumentationReader = ({
     setTocContent(
       <DocReaderSidebar
         key={docId}
-        toc={toc}
+        /* THE TITLE LEADS THE OUTLINE (2026-10-01 — user: "something is always on this page"): a
+         * chapter index with no h2 used to hand the rail an empty list */
+        toc={docTitle ? [{ id: 'page-top', label: docTitle }, ...toc] : toc}
         allTags={allTags}
         topTags={topTags}
         related={related}
@@ -342,7 +344,7 @@ const DocumentationReader = ({
       />
     )
     return () => setTocContent(null)
-  }, [rail, setTocContent, docId, toc, allTags, topTags, related, docsIndex, components, docFilePath])
+  }, [rail, setTocContent, docId, docTitle, toc, allTags, topTags, related, docsIndex, components, docFilePath])
 
   if (!doc) {
     return (
@@ -365,7 +367,7 @@ const DocumentationReader = ({
     <DocsArticle>
         {showFrontmatter && <DocsFrontmatter metadata={doc.metadata} docId={docId} />}
         {docTitle && (
-          <h1 className="kol-doc-heading">{docTitle}</h1>
+          <h1 id="page-top" className="kol-doc-heading scroll-mt-20">{docTitle}</h1>
         )}
         {/* Render intro blocks (excluding H1 which is docTitle) */}
         {introBlocks.filter(b => b.type !== 'heading1').map((block, index) =>

package/src/search/SearchPage.jsx

@@ -1,10 +1,9 @@
-import { Fragment, useMemo, useState } from 'react'
+import { Fragment, useEffect, useMemo, useRef, useState } from 'react'
 import { getTagColor } from '@kolkrabbi/kol-markdown'
-import { useSearchParams } from 'react-router-dom'
-import { EmptyState, Input, TabsRow, Tag } from '@kolkrabbi/kol-component'
+import { useNavigate, useSearchParams } from 'react-router-dom'
+import { EmptyState, Input, Tag } from '@kolkrabbi/kol-component'
 import ResultRow from './ResultRow.jsx'
 import { createIndex, search, parseQuery } from '@kolkrabbi/kol-search'
-import { DocHeader, DocSection } from '../docs/DocKit.jsx'
 
 /**
  * SearchPage — The search results page. THE results page (2026-09-28). Enter in the shell's palette
@@ -20,8 +19,10 @@ import { DocHeader, DocSection } from '../docs/DocKit.jsx'
  *
  * @param {Array}  items   kol-search items: { id, title, href, kind?, space?, category?, tags?, headings?, keywords?, description?, date? }
  * @param {Array}  [spaces] the scope row, `[{ value, label }]` in header order — `value` is an item's `space`
- * @param {Array}  [facets] `[[field, label]]` shown as filter rows (default kind · category · tags)
+ * @param {Array}  [facets] `[[field, label]]` — the FIRST is the visible filter row, the rest fold behind `+`
+ *                          with the scope and the read-as line (default kind · category · tags)
  * @param {number} [limit=60]
+ * @param {string} [resultsPath] the route that shows results, when this box can also sit on another page
  */
 const DEFAULT_FACETS = [['kind', 'Kind'], ['category', 'Category'], ['tags', 'Tags']]
 const PREFIX = { space: 'in', kind: 'kind', category: 'cat', tags: 'tag' }
@@ -46,13 +47,18 @@ 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, rowVariant = 'underline' }) {
+export default function SearchPage({ items = [], spaces = [], facets = DEFAULT_FACETS, limit = 60, rowVariant = 'underline', resultsPath }) {
   const [params, setParams] = useSearchParams()
+  const navigate = useNavigate()
   const q = params.get('q') ?? ''
   const index = useMemo(() => createIndex(items), [items])
   const out = useMemo(() => search(index, q, { limit }), [index, q, limit])
 
-  const setQ = (next) => setParams(next.trim() ? { q: next } : {}, { replace: true })
+  /* `resultsPath`: the query is written to THAT route — a box on a search home sends its first
+   * keystroke straight to the results page instead of filtering in place */
+  const setQ = (next) => (resultsPath
+    ? navigate(next.trim() ? `${resultsPath}?q=${encodeURIComponent(next)}` : resultsPath, { replace: true })
+    : setParams(next.trim() ? { q: next } : {}, { replace: true }))
   /* a pick adds its token; picking it again takes the token back out */
   const toggleToken = (field, value) => {
     const tok = token(field, value)
@@ -61,29 +67,48 @@ export default function SearchPage({ items = [], spaces = [], facets = DEFAULT_F
     setQ((has ? parts.filter((p) => p !== tok) : [...parts, tok]).join(' '))
   }
   const removeToken = (raw) => setQ(q.split(/\s+/).filter((p) => p && p !== raw).join(' '))
+  /* THE BOX OWNS ITS TEXT (2026-10-01). The URL is still the state, but a navigation lands a beat
+   * after the keystroke, and an input controlled by the URL alone dropped the letter typed in
+   * between ("tag" arrived as "tg"). The box shows what was typed; the URL follows; a query that
+   * changes from OUTSIDE (a chip, Back, a link) is read back into the box. */
+  const [text, setText] = useState(q)
+  const pushed = useRef(q)
+  useEffect(() => {
+    if (q !== pushed.current) { pushed.current = q; setText(q) }
+  }, [q])
+  const type = (next) => { pushed.current = next.trim() ? next : ''; setText(next); setQ(next) }
   const inSpace = parseQuery(q).filters.space ?? []
 
-  /* THE FACETS ARE TABS (the showcase review W11, 2026-09-30 — user: "could kind category and tags be
-   * folded into tabs? … if you are searching something and press enter, why do you need to scroll
-   * million kilometers down to get to the actual link"). Three facet sections sat between the box and
-   * the results; now one tab strip picks which facet's chips show, and the results follow it. */
-  const shown = facets.filter(([field]) => (out.facets[field] ?? []).length)
-  const [facetTab, setFacetTab] = useState(facets[0]?.[0])
-  const activeFacet = shown.find(([f]) => f === facetTab) ?? shown[0]
+  /* ONE FILTER ROW (2026-10-01 — user: "why are there so many categories and options, is it relevant
+   * to the results we are seeking as a 'searcher'"; ruled: kind stays, the rest folds behind a `+`).
+   * The page was a scope row, a "read as" row, a tab strip and its chips before the first result.
+   * Now: the box, one row of kind chips, the results. Scope · read-as · category · tags are the
+   * same controls, behind the `+` — and open by themselves while one of them is narrowing the list,
+   * so an active filter is never hidden. Reverses W11's tab strip (2026-09-30). */
+  const [first, ...rest] = facets.filter(([field]) => (out.facets[field] ?? []).length)
+  const tokens = out.query.tokens
+  const narrowed = inSpace.length > 0 || tokens.some((t) => t.kind !== 'term' && t.field !== first?.[0])
+  const [more, setMore] = useState(false)
+  const open = more || narrowed
+  const chips = ([field]) => (out.facets[field] ?? []).slice(0, 24).map((f) => (
+    <Tag key={f.value} hash={field === 'tags'} color={field === 'tags' ? getTagColor(f.value) : undefined} active={f.selected} onClick={() => toggleToken(field, f.value)}>
+      {f.value}<span className="ml-1.5 text-subtle">{f.count}</span>
+    </Tag>
+  ))
 
   return (
-    <div className="flex flex-col gap-10">
-      <DocHeader
-        eyebrow="Search"
-        title="Search"
-        lede={q ? `${out.total} result${out.total === 1 ? '' : 's'} for “${q}”.` : 'Every page on the site.'}
-      />
+    <div className="flex flex-col gap-6">
+      {/* ONE LINE, AND ONLY ONCE THERE IS A QUERY (2026-10-01 — user: "section is search and the title
+        * is search, seems like redundant noise"): the eyebrow, the title and the count were three
+        * lines, and the count was printed again on the results heading. Without a query the page is
+        * its home's (the consumer renders it above) and this is just the box. */}
+      {q && <h1 className="kol-doc-section-title">{`${out.total} result${out.total === 1 ? '' : 's'} for “${q}”.`}</h1>}
 
-      <div className="flex flex-col gap-4">
+      <div className="flex flex-col gap-3">
         {/* md, the ladder's default — lg towered over the page (W11) */}
         <Input
-          value={q}
-          onChange={(e) => setQ(e.target.value)}
+          value={text}
+          onChange={(e) => type(e.target.value)}
           placeholder="Search — try atom, tag:pattern/input, in:docs, -legacy"
           iconLeft="search"
           size="md"
@@ -91,57 +116,63 @@ export default function SearchPage({ items = [], spaces = [], facets = DEFAULT_F
           autoFocus
         />
         {/* every chip on the page is THE Tag, one size (W11 — they were ghost Buttons and md Pills) */}
-        {spaces.length > 0 && (
-          <div className="flex flex-wrap items-center gap-2" role="group" aria-label="Scope">
-            <Tag hash={false} active={!inSpace.length} onClick={() => setQ(q.split(/\s+/).filter((p) => p && !/^in:/.test(p)).join(' '))}>Everything</Tag>
-            {spaces.map((sp) => (
-              <Tag key={sp.value} hash={false} active={inSpace.includes(sp.value)} onClick={() => toggleToken('space', sp.value)}>{sp.label}</Tag>
-            ))}
+        {q && (first || spaces.length > 0) && (
+          <div className="flex flex-wrap items-center gap-2" role="group" aria-label={first?.[1] ?? 'Filters'}>
+            {first && chips(first)}
+            <Tag hash={false} variant="secondary" active={open} onClick={() => setMore((m) => !m)} aria-expanded={open} aria-label="More filters">{open ? '−' : '+'}</Tag>
           </div>
         )}
-        {out.query.tokens.length > 0 && (
-          <div className="flex flex-wrap items-center gap-2">
-            <span className="kol-doc-eyebrow">Read as</span>
-            {out.query.tokens.map((t, i) => (
-              <Tag key={`${t.raw}-${i}`} hash={false} variant="secondary" onRemove={() => removeToken(t.raw)} aria-label={`Remove ${t.raw}`}>{readToken(t)}</Tag>
+        {q && open && (
+          <div className="flex flex-col gap-3">
+            {spaces.length > 0 && (
+              <div className="flex flex-wrap items-center gap-2" role="group" aria-label="Scope">
+                <span className="kol-doc-eyebrow">Scope</span>
+                <Tag hash={false} active={!inSpace.length} onClick={() => setQ(q.split(/\s+/).filter((p) => p && !/^in:/.test(p)).join(' '))}>Everything</Tag>
+                {spaces.map((sp) => (
+                  <Tag key={sp.value} hash={false} active={inSpace.includes(sp.value)} onClick={() => toggleToken('space', sp.value)}>{sp.label}</Tag>
+                ))}
+              </div>
+            )}
+            {rest.map((facet) => (
+              <div key={facet[0]} className="flex flex-wrap items-center gap-2" role="group" aria-label={facet[1]}>
+                <span className="kol-doc-eyebrow">{facet[1]}</span>
+                {chips(facet)}
+              </div>
             ))}
+            {tokens.length > 0 && (
+              <div className="flex flex-wrap items-center gap-2">
+                <span className="kol-doc-eyebrow">Read as</span>
+                {tokens.map((t, i) => (
+                  <Tag key={`${t.raw}-${i}`} hash={false} variant="secondary" onRemove={() => removeToken(t.raw)} aria-label={`Remove ${t.raw}`}>{readToken(t)}</Tag>
+                ))}
+              </div>
+            )}
           </div>
         )}
       </div>
 
-      {activeFacet && (
-        <div className="flex flex-col gap-4">
-          <TabsRow tabs={shown.map(([field, label]) => ({ id: field, label }))} value={activeFacet[0]} onChange={setFacetTab} />
-          <div className="flex flex-wrap gap-2">
-            {(out.facets[activeFacet[0]] ?? []).slice(0, 24).map((f) => (
-              <Tag key={f.value} hash={activeFacet[0] === 'tags'} color={activeFacet[0] === 'tags' ? getTagColor(f.value) : undefined} active={f.selected} onClick={() => toggleToken(activeFacet[0], f.value)}>
-                {f.value}<span className="ml-1.5 text-subtle">{f.count}</span>
-              </Tag>
-            ))}
-          </div>
-        </div>
+      {q && (
+        <section id="results" className="flex flex-col gap-4 scroll-mt-20">
+          {out.results.length === 0 ? (
+            <EmptyState eyebrow="No results" title="Nothing matches." body="Remove a token above, or try fewer words." />
+          ) : (
+            <ol className="flex flex-col border-t border-fg-08">
+              {out.results.map((r) => (
+                <li key={r.item.id} className="border-t border-fg-08 first:border-t-0">
+                  <ResultRow
+                    to={r.item.href}
+                    variant={rowVariant}
+                    title={<Highlight text={r.item.title} ranges={r.highlights.title} />}
+                    meta={[r.item.kind, r.item.category, r.item.space, r.item.date].filter(Boolean).join(' · ')}
+                    description={r.item.description}
+                  />
+                </li>
+              ))}
+            </ol>
+          )}
+          {out.total > out.results.length && <p className="kol-helper-12 text-meta">{out.total - out.results.length} more — narrow the query.</p>}
+        </section>
       )}
-
-      <DocSection id="results" title={`Results (${out.total})`}>
-        {out.results.length === 0 ? (
-          <EmptyState eyebrow={q ? 'No results' : 'Search'} title={q ? 'Nothing matches.' : 'Type to search.'} body={q ? 'Remove a token above, or try fewer words.' : undefined} />
-        ) : (
-          <ol className="flex flex-col">
-            {out.results.map((r) => (
-              <li key={r.item.id} className="border-t border-fg-08 first:border-t-0">
-                <ResultRow
-                  to={r.item.href}
-                  variant={rowVariant}
-                  title={<Highlight text={r.item.title} ranges={r.highlights.title} />}
-                  meta={[r.item.kind, r.item.category, r.item.space, r.item.date].filter(Boolean).join(' · ')}
-                  description={r.item.description}
-                />
-              </li>
-            ))}
-          </ol>
-        )}
-        {out.total > out.results.length && <p className="kol-helper-12 text-meta">{out.total - out.results.length} more — narrow the query.</p>}
-      </DocSection>
     </div>
   )
 }

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,10 +231,37 @@ 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
@@ -560,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,7 +39,8 @@ 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).
    *
@@ -63,6 +64,11 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
       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
   }