@kolkrabbi/kol-workshop 0.30.1 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.30.1",
+  "version": "0.31.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",
@@ -14,8 +14,8 @@
   "dependencies": {
     "d3": "^7.9.0",
     "@kolkrabbi/kol-search": "^0.2.0",
-    "@kolkrabbi/kol-markdown": "^0.1.1",
-    "@kolkrabbi/kol-brand": "^0.1.3"
+    "@kolkrabbi/kol-brand": "^0.1.3",
+    "@kolkrabbi/kol-markdown": "^0.1.2"
   },
   "peerDependencies": {
     "@kolkrabbi/kol-component": ">=0.228.0",
@@ -27,10 +27,10 @@
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.229.0",
-    "@kolkrabbi/kol-icons": "^0.29.0",
-    "@kolkrabbi/kol-theme": "^0.156.0",
-    "@kolkrabbi/kol-framework": "^0.45.0"
+    "@kolkrabbi/kol-component": "^0.230.0",
+    "@kolkrabbi/kol-framework": "^0.46.0",
+    "@kolkrabbi/kol-theme": "^0.157.0",
+    "@kolkrabbi/kol-icons": "^0.29.1"
   },
   "files": [
     "src",

package/src/docs/DocsFrontmatter.jsx

@@ -200,13 +200,13 @@ const DocsFrontmatter = ({ metadata, docId }) => {
                 /* `naked`, the SAME Tag rendering the rail's own tag list uses
                  * (DocReaderSidebar). This was the default filled variant, so
                  * the one concept rendered as a solid pill here and as plain
-                 * coloured text six inches to the right.
+                 * colored text six inches to the right.
                  *
                  * NO `color` (user ruling 2026-08-01): passing one swaps the
                  * base class from `tag-control` to `tag tag--{color}`, and
-                 * only `tag-control` has a `:hover` rule — so a coloured Tag
+                 * only `tag-control` has a `:hover` rule — so a colored Tag
                  * silently loses its interaction state. Right component first;
-                 * colour is its own decision, later.
+                 * color is its own decision, later.
                  * `size` is omitted: `sm` is the default and the only size. */
                 <span className="flex flex-wrap gap-1.5">
                   {value.map((tag) => (

package/src/docs/DocumentationReader.jsx

@@ -72,12 +72,19 @@ const DocReaderSidebar = ({ toc, allTags, related, docId, docsIndexHref, compone
  *                                        (default `/docs?tag=…`).
  *   @param {Function} routes.docFilePath (id) => on-disk path copied to clipboard
  *                                        (default `docs/documentation/${id}.md`).
+ * @param {string}   [props.docId]        render this doc instead of the route's `:docId` — a
+ *                                        HOME renders its markdown at the space's own URL
+ *                                        (2026-09-30, the names audit: every level has a home).
+ * @param {boolean}  [props.showFrontmatter=true]  the frontmatter panel; a home hides it by
+ *                                        default and the consumer toggles it.
  */
 const DocumentationReader = ({
   inventory = [],
   modules = {},
   docHref = (id) => `/docs/${id}`,
-  routes = {}
+  routes = {},
+  docId: docIdProp,
+  showFrontmatter = true,
 }) => {
   const {
     docsIndex = '/docs',
@@ -86,7 +93,8 @@ const DocumentationReader = ({
     docFilePath = (id) => `docs/documentation/${id}.md`
   } = routes
 
-  const { docId } = useParams()
+  const { docId: routeDocId } = useParams()
+  const docId = docIdProp ?? routeDocId
   const setTocContent = useContext(ShellTocContext)
   const { openTagMode } = useTagMode()
 
@@ -337,7 +345,7 @@ const DocumentationReader = ({
 
   return (
     <DocsArticle>
-        <DocsFrontmatter metadata={doc.metadata} docId={docId} />
+        {showFrontmatter && <DocsFrontmatter metadata={doc.metadata} docId={docId} />}
         {docTitle && (
           <h1 className="kol-doc-heading">{docTitle}</h1>
         )}

package/src/search/ResultRow.jsx

@@ -0,0 +1,33 @@
+import { Link } from 'react-router-dom'
+
+/**
+ * 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']
+ */
+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 (
+    <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 { Link, useSearchParams } from 'react-router-dom'
-import { Button, 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,7 +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 }) {
+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])
@@ -119,16 +120,18 @@ export default function SearchPage({ items = [], spaces = [], facets = DEFAULT_F
 
       <DocSection id="results" title={`Results (${out.total})`}>
         {out.results.length === 0 ? (
-          <p className="kol-doc-body">{q ? 'Nothing matches. Remove a token above, or try fewer words.' : 'Type to search.'}</p>
+          <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">
-                <Link to={r.item.href} className="flex flex-col gap-1 py-3 hover:bg-fg-04">
-                  <span className="kol-doc-body text-emphasis"><Highlight text={r.item.title} ranges={r.highlights.title} /></span>
-                  <span className="kol-helper-12 text-subtle">{[r.item.kind, r.item.category, r.item.space, r.item.date].filter(Boolean).join(' · ')}</span>
-                  {r.item.description && <span className="kol-doc-body">{r.item.description}</span>}
-                </Link>
+                <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>

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/RailRow.jsx

@@ -19,7 +19,7 @@ import { NavLink } from 'react-router-dom'
  * eyebrow-box failure exactly, one rung further down, which is why the rails
  * kept drifting after RailSection fixed L1 and L2.
  *
- * The look now lives in `.shell-nav-item` (layout, colour, hover, focus,
+ * The look now lives in `.shell-nav-item` (layout, color, hover, focus,
  * active); this component owns the markup. `validate:rails` R4 fails a
  * hand-written `shell-nav-item` anywhere but here.
  *

package/src/shell/RailSection.jsx

@@ -21,7 +21,7 @@ import { Link } from 'react-router-dom'
  *   L1  section  `.shell-sidebar-toggle` + kol-doc-eyebrow    quiet, state glyph at the end
  *   L2  group    `.shell-nav-group-header` + kol-mono-14      louder, chevron
  *
- * L2 carries NO colour class: `.shell-nav-group-header` owns weight 500 and
+ * L2 carries NO color class: `.shell-nav-group-header` owns weight 500 and
  * `--kol-fg-shout` itself (user ruling 2026-08-01). It used to carry
  * `text-body` — a utility that resolved to nothing at the time, and would now
  * fight the rule for the same property. One owner.

package/src/shell/RightRail.jsx

@@ -1,4 +1,5 @@
 import { useState } from 'react'
+import { useLocation } from 'react-router-dom'
 import RailSection from './RailSection.jsx'
 import RailRow from './RailRow.jsx'
 
@@ -63,6 +64,14 @@ import RailRow from './RailRow.jsx'
  *                                this package does not reach into kol-component
  * @param {Function} onTagClick   (tag) => void
  */
+const PINS_KEY = 'kol-rail-pins'
+const readPins = () => {
+  try { return JSON.parse(localStorage.getItem(PINS_KEY) || '[]') } catch { return [] }
+}
+const writePins = (pins) => {
+  try { localStorage.setItem(PINS_KEY, JSON.stringify(pins)) } catch { /* private mode */ }
+}
+
 export default function RightRail({
   toc = [],
   activeId,
@@ -77,16 +86,46 @@ export default function RightRail({
   /* One collapse map, not a useState per section — a section added later must
    * not need a new hook at the top of this function. */
   const [collapsed, setCollapsed] = useState({})
+
+  /* PINNED (2026-09-30, the names audit: *"add to quicklook or favorites … in the right sidebar
+   * … maintain context-important documents during development … accessible until they dont need
+   * to be"*). Any page can be pinned from Quick actions; the pins show on every page until
+   * unpinned. Kept in this browser (localStorage) — a working set, not shared state. */
+  const { pathname } = useLocation()
+  const [pins, setPins] = useState(readPins)
+  const isPinned = pins.some((p) => p.path === pathname)
+  const togglePin = () => {
+    const label = document.querySelector('#main h1, main h1, h1')?.textContent?.trim() || pathname
+    const next = isPinned ? pins.filter((p) => p.path !== pathname) : [...pins, { path: pathname, label }]
+    setPins(next)
+    writePins(next)
+  }
+  const allActions = [
+    ...actions,
+    { id: 'pin', label: isPinned ? 'Unpin' : 'Pin', icon: IconComponent ? <IconComponent name="pushpin" size={14} /> : null, onClick: togglePin },
+  ]
   const toggle = (key) => setCollapsed((c) => ({ ...c, [key]: !c[key] }))
 
-  /* A tag shown as "this page's" must not repeat below as "the system's". */
-  const own = new Set(tags)
-  const otherTags = topTags.filter(({ tag }) => !own.has(tag))
+  /* OWN TAGS ONLY, GROUPED BY NAMESPACE (2026-09-30, the names audit — ruled on the
+   * recommendation). The rail used to follow a page's own tags with the space's top tags, so a
+   * page with none (/docs/menus) still listed ten, none of them its own. The system's most-used
+   * tags are a way IN, and belong on a home and the search page; `topTags` is accepted and
+   * ignored so no consumer breaks. The namespace law stays in the data — the rail prints it once
+   * as a group label and the leaf under it, instead of truncating the full path on every row. */
+  const byNamespace = tags.reduce((m, tag) => {
+    const [ns, ...rest] = String(tag).split('/')
+    const leaf = rest.join('/') || ns
+    ;(m[rest.length ? ns : ''] ||= []).push({ tag, leaf })
+    return m
+  }, {})
+  void topTags
+  void renderTag
 
   /* Every group is described here rather than spelled out in JSX below, so a
    * section cannot be present in one branch and missing in another — the exact
    * defect that split the two rails. */
-  const group = (key, label, count, children) => (
+  /* A chapter with nothing in it does not render (2026-09-30 — `Related (0)`). */
+  const group = (key, label, count, children) => count === 0 ? null : (
     <RailSection
       level={2}
       label={label}
@@ -101,7 +140,8 @@ export default function RightRail({
 
   return (
     <div className="shell-rail-stack">
-      <RailSection level={1} label="This page">
+      {/* A folded category shows its count, the same as the left rail (2026-09-30) */}
+      <RailSection level={1} label="This page" count={toc.length}>
         <div className="shell-rail-stack-inner">
           {group('toc', 'Contents', toc.length,
             toc.map((h) => (
@@ -113,42 +153,40 @@ export default function RightRail({
         </div>
       </RailSection>
 
-      <RailSection level={1} label="Links">
+      <RailSection level={1} label="Links" count={pins.length + allActions.length + tags.length + related.length}>
         <div className="shell-rail-stack-inner">
-          {group('actions', 'Quick actions', actions.length,
-            actions.map((a) => (
+          {group('pinned', 'Pinned', pins.length,
+            pins.map((p) => (
+              <RailRow key={p.path} to={p.path} icon={IconComponent ? <IconComponent name="pushpin" size={14} /> : null}>
+                {p.label}
+              </RailRow>
+            ))
+          )}
+
+          {group('actions', 'Quick actions', allActions.length,
+            allActions.map((a) => (
               <RailRow key={a.id} to={a.to} onClick={a.onClick} icon={a.icon}>
                 {a.label}
               </RailRow>
             ))
           )}
 
-          {/* ONE list, two ranks. This page's tags lead and carry `emphasis`;
-            * the system's most-used follow at the resting stop with their
-            * count. `otherTags` filters out anything already shown above, so a
-            * tag cannot appear twice in one list. */}
-          {group('tags', 'Tags', tags.length + otherTags.length, (
+          {group('tags', 'Tags', tags.length, (
             <>
-              {tags.map((tag) => (
-                <RailRow
-                  key={`own-${tag}`}
-                  onClick={() => onTagClick?.(tag)}
-                  icon={IconComponent ? <IconComponent name="hash-02" size={14} /> : null}
-                  className="shell-nav-item--own"
-                >
-                  {renderTag ? renderTag(tag) : tag}
-                </RailRow>
-              ))}
-              {otherTags.map(({ tag, count }) => (
-                <RailRow
-                  key={`top-${tag}`}
-                  onClick={() => onTagClick?.(tag)}
-                  icon={IconComponent ? <IconComponent name="hash-02" size={14} /> : null}
-                  trailing={count}
-                  className="shell-nav-item--muted"
-                >
-                  {renderTag ? renderTag(tag) : tag}
-                </RailRow>
+              {Object.entries(byNamespace).map(([ns, list]) => (
+                <div key={`ns-${ns}`}>
+                  {ns && <RailRow className="shell-nav-item--muted">{ns.charAt(0).toUpperCase() + ns.slice(1)}</RailRow>}
+                  {list.map(({ tag, leaf }) => (
+                    <RailRow
+                      key={`own-${tag}`}
+                      sub={!!ns}
+                      onClick={() => onTagClick?.(tag)}
+                      icon={IconComponent ? <IconComponent name="hash-02" size={14} /> : null}
+                    >
+                      {leaf}
+                    </RailRow>
+                  ))}
+                </div>
               ))}
             </>
           ))}

package/src/shell/ShellLayout.jsx

@@ -1,7 +1,7 @@
-import { createContext, useContext, useMemo, useState, useEffect, Suspense } from 'react'
+import { createContext, useContext, useMemo, useRef, useState, useEffect, Suspense } from 'react'
 import { Outlet, Link, useLocation, useNavigate } from 'react-router-dom'
 import { ShellHeader } from '@kolkrabbi/kol-framework'
-import ShellSidebar from './ShellSidebar.jsx'
+import ShellSidebar, { RAIL_FOLD_EVENT } from './ShellSidebar.jsx'
 import { IconFrame, ShellDrawer, ShellSearchOverlay, ShortcutsOverlay, SettingsSections, SettingsSwitch, Tooltip } from '@kolkrabbi/kol-component'
 import { createIndex, search } from '@kolkrabbi/kol-search'
 import { useTagMode } from '../tags/TagModeContext.jsx'
@@ -156,8 +156,10 @@ const toSearchItem = (item, i) => ({
  * @param {string|Function} [brandLabel]  a TYPED label in the second wordmark slot instead of
  *                               the drawn WORKSHOP mark — a string, or `({ activeRoute }) => string`
  *                               so it names the space you are in
+ * @param {Array}  [shortcuts]   the consumer's own keys, `{ id, label, combo, key, run }` — listed
+ *                               in the `S` sheet and bound by the same handler (2026-09-30)
  */
-const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoSrc, brandLogoAlt = '', renderSidebar, searchItems, searchPath, settings = [], brandLabel, defaultTocContent, isActive: isActiveProp, actions }) => {
+const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoSrc, brandLogoAlt = '', renderSidebar, searchItems, searchPath, settings = [], brandLabel, defaultTocContent, isActive: isActiveProp, actions, shortcuts = [] }) => {
   const [isNavDrawerOpen, setIsNavDrawerOpen] = useState(false)
   const [prefs, setPrefs] = useState(readSettings)
   const setPref = (key, value) => setPrefs((p) => { const next = { ...p, [key]: value }; writeSettings(next); return next })
@@ -224,9 +226,17 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
     { section: 'Shell', items: [
       { id: 'sheet', label: 'This sheet', 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' },
     ] },
+    ...(shortcuts.length ? [{ section: 'Page', items: shortcuts.map(({ id, label, combo }) => ({ id, label, combo })) }] : []),
   ]
+  /* the handler binds once; the consumer's list and the fold state are read through refs */
+  const shortcutsRef = useRef(shortcuts)
+  shortcutsRef.current = shortcuts
+  const foldedRef = useRef(false)
 
   useEffect(() => {
     const handleKeyDown = (e) => {
@@ -249,6 +259,19 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
       } else if (e.key === ',') {
         e.preventDefault()
         setIsSettingsOpen((v) => !v)
+      } else if (e.key === '[') {
+        e.preventDefault()
+        setNavCollapsed((v) => { writeSettings({ ...readSettings(), navHidden: !v }); return !v })
+      } else if (e.key === ']') {
+        e.preventDefault()
+        setTocCollapsed((v) => { writeSettings({ ...readSettings(), tocHidden: !v }); return !v })
+      } else if (e.key === 'c' || e.key === 'C') {
+        e.preventDefault()
+        foldedRef.current = !foldedRef.current
+        window.dispatchEvent(new CustomEvent(RAIL_FOLD_EVENT, { detail: { collapsed: foldedRef.current } }))
+      } else if (shortcutsRef.current.some((s) => s.key === e.key)) {
+        e.preventDefault()
+        shortcutsRef.current.find((s) => s.key === e.key).run()
       } else if (e.key === 'Escape') {
         setIsShortcutsOpen(false)
       }
@@ -344,13 +367,13 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
   const searchTrigger = (
     <>
       {actions}
-      <Tooltip label="Search · ⌘K or /">
+      <Tooltip label="Search">
         {/* `md` + full-ink nav (user re-rule 2026-08-09; repeals the 2026-08-01
           * lg ruling). The row law is unchanged: every header glyph on ONE
           * rung, one variant — the rung is just md now. */}
         <IconFrame name="search" variant="nav" size="md" onClick={() => setIsSearchOpen(true)} aria-label="Search" />
       </Tooltip>
-      <Tooltip label="Settings · ,">
+      <Tooltip label="Settings">
         <IconFrame name="settings-01" variant="nav" size="md" onClick={() => setIsSettingsOpen(true)} aria-label="Settings" />
       </Tooltip>
     </>

package/src/shell/ShellSidebar.jsx

@@ -24,6 +24,8 @@ const getChildPath = (child, basePath) => {
   return p.startsWith('/') ? p : `${basePath}/${p}`
 }
 
+export const RAIL_FOLD_EVENT = 'kol-rail-fold'
+
 const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Navigation', labelTo, collapsed, onToggle, defaultCollapsed = false }) => {
   const location = useLocation()
   const normalizedPath = location.pathname.replace(/\/$/, '')
@@ -69,6 +71,14 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [normalizedPath, routes, basePath])
 
+  /* 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])))
+    window.addEventListener(RAIL_FOLD_EVENT, onFold)
+    return () => window.removeEventListener(RAIL_FOLD_EVENT, onFold)
+  }, [routes])
+
   const handleSectionClick = (route) => {
     setCollapsedSections((prev) => ({ ...prev, [route.id]: !prev[route.id] }))
   }