@kolkrabbi/kol-workshop 0.3.4 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "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,10 +14,10 @@
   "dependencies": {
     "d3": "^7.9.0",
     "@kolkrabbi/kol-brand": "^0.1.2",
-    "@kolkrabbi/kol-icons": "0.8.11",
     "@kolkrabbi/kol-component": "0.14.1",
-    "@kolkrabbi/kol-framework": "0.8.0",
-    "@kolkrabbi/kol-theme": "0.13.2"
+    "@kolkrabbi/kol-icons": "0.8.11",
+    "@kolkrabbi/kol-framework": "0.8.1",
+    "@kolkrabbi/kol-theme": "0.13.3"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",

package/src/docs/DocumentationReader.jsx

@@ -23,7 +23,7 @@ const SidebarSection = ({ sectionKey, label, collapsedSections, toggleSection, c
   </div>
 )
 
-const DocReaderSidebar = ({ toc, allTags, docId, docsIndexHref, componentsHref, docFilePath }) => {
+const DocReaderSidebar = ({ toc, allTags, related, docId, docsIndexHref, componentsHref, docFilePath }) => {
   const navigate = useNavigate()
   const { openTagMode } = useTagMode()
   const [collapsedSections, setCollapsedSections] = useState({})
@@ -40,6 +40,24 @@ const DocReaderSidebar = ({ toc, allTags, docId, docsIndexHref, componentsHref,
         <DocsToc toc={toc} />
       </SidebarSection>
 
+      {related.length > 0 && (
+        <SidebarSection
+          sectionKey="related"
+          label="Related"
+          collapsedSections={collapsedSections}
+          toggleSection={toggleSection}
+        >
+          {/* ONE rail voice (user law): rows = the shell-nav-item idiom. */}
+          <nav className="flex flex-col">
+            {related.map((r) => (
+              <Link key={r.id} to={r.href} className="shell-nav-item block kol-mono-14 text-body transition-colors hover:text-emphasis">
+                {r.label}
+              </Link>
+            ))}
+          </nav>
+        </SidebarSection>
+      )}
+
       <SidebarSection
         sectionKey="actions"
         label="Quick actions"
@@ -140,6 +158,7 @@ const DocumentationReader = ({
 
   const { docId } = useParams()
   const setTocContent = useContext(ShellTocContext)
+  const { openTagMode } = useTagMode()
 
   // Build a Set of known doc IDs for fast lookup
   const knownDocIds = useMemo(
@@ -163,9 +182,11 @@ const DocumentationReader = ({
     return null
   }
 
-  // Bind the resolved link + tag helpers so call sites stay terse.
+  // Bind the resolved link + tag helpers so call sites stay terse. Hashtag
+  // pills open TAG MODE (wave-4 parity) — the tagHref Link was a dead route
+  // in any consumer without a ?tag= index page.
   const renderTokens = (tokens, tokenKey) =>
-    renderInlineTokens(tokens, tokenKey, resolveDocLink, tagHref)
+    renderInlineTokens(tokens, tokenKey, resolveDocLink, tagHref, openTagMode)
 
   /* ONE block renderer for intro + section content (wave-4 retype, 2026-07-30
    * — the two switches had already drifted). Every element is typed through
@@ -295,6 +316,35 @@ const DocumentationReader = ({
     return h1Block?.content || null
   }, [introBlocks])
 
+  /* Cross-references (wave-4 parity): frontmatter `related:` entries are
+   * wikilinks — `[[target|display]]`, target relative to the doc's own
+   * folder. Resolved against the inventory by full path first (handles
+   * `../INDEX`-style hops), then by bare basename id as the fallback for
+   * hand-typed targets. Unresolvable entries are dropped, not rendered dead. */
+  const related = useMemo(() => {
+    const entries = doc?.metadata?.related
+    if (!Array.isArray(entries) || !doc?.file) return []
+    return entries
+      .map((entry) => {
+        const m = /\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/.exec(String(entry))
+        const target = (m ? m[1] : String(entry)).trim()
+        const display = (m?.[2] || target.split('/').pop().replace(/\.md$/, '')).trim()
+        const segs = doc.file.split('/').slice(0, -1)
+        for (const seg of target.replace(/\.md$/, '').split('/')) {
+          if (seg === '..') segs.pop()
+          else if (seg && seg !== '.') segs.push(seg)
+        }
+        const full = segs.join('/')
+        const basename = target.split('/').pop().replace(/\.md$/, '')
+        const hit =
+          inventory.find((d) => d.file.replace(/\.md$/, '') === full) ??
+          inventory.find((d) => d.file.replace(/\.md$/, '').toLowerCase() === `${full}/index`.toLowerCase()) ??
+          inventory.find((d) => d.id === basename)
+        return hit ? { id: hit.id, href: docHref(hit.id), label: display } : null
+      })
+      .filter(Boolean)
+  }, [doc, inventory, docHref])
+
   /* The reader is usable OUTSIDE a ShellLayout (a plain page, a lobby route):
    * ShellTocContext then defaults to null, so calling it unguarded threw.
    * No shell → no right rail, and the reader just renders its article. */
@@ -305,6 +355,7 @@ const DocumentationReader = ({
         key={docId}
         toc={toc}
         allTags={allTags}
+        related={related}
         docId={docId}
         docsIndexHref={docsIndex}
         componentsHref={components}
@@ -312,7 +363,7 @@ const DocumentationReader = ({
       />
     )
     return () => setTocContent(null)
-  }, [setTocContent, docId, toc, allTags, docsIndex, components, docFilePath])
+  }, [setTocContent, docId, toc, allTags, related, docsIndex, components, docFilePath])
 
   if (!doc) {
     return (

package/src/docs/render-tokens.jsx

@@ -14,12 +14,17 @@ import { Link } from 'react-router-dom'
  * @param {Function} tagHref       (tag) => href for `#hashtag` pills. Default
  *                                 keeps hashtags route-agnostic (`/docs?tag=…`);
  *                                 the reader passes a configured href in.
+ * @param {Function} onTagClick    (tag) => void — when provided, hashtag pills
+ *                                 render as buttons (tag mode) instead of Links;
+ *                                 a consumer without a tag route stops shipping
+ *                                 dead `/docs?tag=…` links (wave-4 parity).
  */
 export const renderInlineTokens = (
   tokens,
   key = '',
   resolveDocLink = null,
-  tagHref = (tag) => `/docs?tag=${encodeURIComponent(tag)}`
+  tagHref = (tag) => `/docs?tag=${encodeURIComponent(tag)}`,
+  onTagClick = null
 ) => {
   if (!Array.isArray(tokens)) return null
 
@@ -82,16 +87,26 @@ export const renderInlineTokens = (
           </code>
         )
 
-      case 'hashtag':
+      case 'hashtag': {
+        const pillCls = 'inline-tag-pill kol-helper-12 bg-fg-08 text-strong'
+        if (onTagClick) {
+          return (
+            <button
+              key={tokenKey}
+              type="button"
+              className={pillCls}
+              onClick={() => onTagClick(token.tag)}
+            >
+              #{token.tag}
+            </button>
+          )
+        }
         return (
-          <Link
-            key={tokenKey}
-            to={tagHref(token.tag)}
-            className="inline-tag-pill kol-helper-12 bg-fg-08 text-strong"
-          >
+          <Link key={tokenKey} to={tagHref(token.tag)} className={pillCls}>
             #{token.tag}
           </Link>
         )
+      }
 
       default:
         return null

package/src/engine/build-inventory.js

@@ -20,6 +20,19 @@ export function buildInventory(modules) {
     const lines = raw.split(/\r?\n/)
     const headingLine = lines.find((line) => line.startsWith('# ')) ?? ''
     const title = headingLine.replace(/^#\s+/, '').trim()
+    /* Section headings (## / ###) ride the inventory so search can match a
+     * doc by its CONTENT, not just title/tags — the workshop reference
+     * behavior (matchSearchItems already takes `headings`; consumers shipped
+     * it empty because nothing extracted them — wave-4 parity, 2026-07-30). */
+    const headings = []
+    let inFence = false
+    for (const line of lines) {
+      if (/^\s*```/.test(line)) { inFence = !inFence; continue }
+      if (!inFence && /^#{2,3}\s/.test(line)) {
+        const text = line.replace(/^#{2,3}\s+/, '').trim()
+        if (text) headings.push(text)
+      }
+    }
     const metadata = parseFrontmatter(raw)
     const filename = normalisedPath.split('/').pop() ?? ''
     const parentFolder = normalisedPath.split('/').slice(-2, -1)[0] ?? ''
@@ -33,7 +46,7 @@ export function buildInventory(modules) {
       .replace(/^Design System\s*[-–—:]\s*/i, '')
       .replace(/\bCheat Sheet\b/i, 'Quicklook')
 
-    return { id, file: normalisedPath, title: cleanTitle, metadata, parentFolder }
+    return { id, file: normalisedPath, title: cleanTitle, metadata, headings, parentFolder }
   })
 
   /* Collision safety (2026-07-30): filename-only ids collide across folders in