@kolkrabbi/kol-workshop 0.3.3 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.3.3",
+  "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",
@@ -15,9 +15,9 @@
     "d3": "^7.9.0",
     "@kolkrabbi/kol-brand": "^0.1.2",
     "@kolkrabbi/kol-component": "0.14.1",
-    "@kolkrabbi/kol-icons": "0.8.10",
-    "@kolkrabbi/kol-framework": "0.7.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/DocsArticle.jsx

@@ -1,7 +1,13 @@
 const join = (...classes) => classes.filter(Boolean).join(' ')
 
+/* NOT .kol-prose (wave-4 retype, 2026-07-30 — user law: one layout = one style
+ * system; prose is the blog/CMS voice, never docs surfaces). Every element the
+ * reader renders is typed explicitly through the kol-doc-* roles, mirroring
+ * showcase/src/lib/mdx-components.jsx — the SAME dialect MDX pages speak.
+ * Vertical rhythm comes from the flex gap (the MdxDoc content idiom), not
+ * prose margins. */
 const DocsArticle = ({ children, className }) => (
-  <article className={join('docs-article kol-prose', className)}>{children}</article>
+  <article className={join('docs-article flex w-full min-w-0 flex-col gap-6', className)}>{children}</article>
 )
 
 export default DocsArticle

package/src/docs/DocsHeader.jsx

@@ -1,9 +1,13 @@
 const join = (...classes) => classes.filter(Boolean).join(' ')
 
+/* Doc voice (wave-4 retype, 2026-07-30): title/subtitle ride the DocHeader
+ * contract roles (kol-doc-heading / kol-doc-lede) instead of the old
+ * kol-sans-heading-02 + kol-mono-14 pair — one header voice across the
+ * reader, MDX pages and the Doc* kit. */
 const DocsHeader = ({ title, subtitle, meta = [], className }) => (
-  <header className={join('docs-header', className)}>
-    {title ? <h1 className="kol-sans-heading-02 text-strong">{title}</h1> : null}
-    {subtitle ? <p className="kol-mono-14 text-meta">{subtitle}</p> : null}
+  <header className={join('docs-header flex flex-col gap-3', className)}>
+    {title ? <h1 className="kol-doc-heading">{title}</h1> : null}
+    {subtitle ? <p className="kol-doc-lede">{subtitle}</p> : null}
     {Array.isArray(meta) && meta.length > 0 ? (
       <div className="docs-meta kol-helper-10 text-body">
         {meta.map(({ label, value }) => (

package/src/docs/DocumentationReader.jsx

@@ -1,12 +1,13 @@
 import { useContext, useEffect, useMemo, useState } from 'react'
 import { useParams, Link, useNavigate } from 'react-router-dom'
-import { CodeBlock, Divider, DocsToc, Icon, Tag } from '@kolkrabbi/kol-component'
+import { CodeBlock, Divider, DocsToc, Icon, Table, Tag } from '@kolkrabbi/kol-component'
 import { ShellTocContext } from '../shell'
 import { useTagMode } from '../tags'
 import { parseDocsMarkdown, isIndexFile, getTagColor } from '../engine'
 import DocsHeader from './DocsHeader.jsx'
 import DocsArticle from './DocsArticle.jsx'
 import DocsFrontmatter from './DocsFrontmatter.jsx'
+import { DocSection } from './DocKit.jsx'
 import { renderInlineTokens } from './render-tokens.jsx'
 
 const SidebarSection = ({ sectionKey, label, collapsedSections, toggleSection, children }) => (
@@ -22,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({})
@@ -39,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"
@@ -139,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(
@@ -162,9 +182,87 @@ 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
+   * the kol-doc-* dialect of showcase mdx-components.jsx: doc-body running
+   * text (self-caps at the measure), heading-05 h3/h4 (h4 = weight 400, the
+   * prose-h4 precedent), panel-capped furniture (width law: tables/code cap
+   * at --kol-content-panel), markdown tables through THE kol-component Table
+   * as a dynamic-column DocTable sibling (no parallel table markup). */
+  const renderBlock = (block, blockKey) => {
+    switch (block.type) {
+      case 'paragraph':
+        return (
+          <p key={blockKey} className="kol-doc-body">
+            {block.tokens ? renderTokens(block.tokens, blockKey) : block.content}
+          </p>
+        )
+      case 'heading3':
+        return (
+          <h3 key={blockKey} id={block.id} className="kol-sans-heading-05 text-emphasis scroll-mt-20 mt-2">
+            {block.content}
+          </h3>
+        )
+      case 'heading4':
+        return (
+          <h4 key={blockKey} id={block.id} className="kol-sans-heading-05 font-normal text-emphasis scroll-mt-20">
+            {block.content}
+          </h4>
+        )
+      case 'list': {
+        const ListComponent = block.ordered ? 'ol' : 'ul'
+        const listClass = `flex ${block.ordered ? 'list-decimal' : 'list-disc'} flex-col gap-2 pl-5 kol-doc-body`
+        return block.items ? (
+          <ListComponent key={blockKey} className={listClass}>
+            {block.items.map((item, itemIndex) => (
+              <li key={itemIndex}>
+                {item.tokens ? renderTokens(item.tokens, `${blockKey}-item-${itemIndex}`) : item.content || item}
+              </li>
+            ))}
+          </ListComponent>
+        ) : null
+      }
+      case 'blockquote':
+        return (
+          <blockquote key={blockKey} className="docs-callout kol-doc-body">
+            {block.tokens ? renderTokens(block.tokens, blockKey) : block.content}
+          </blockquote>
+        )
+      case 'divider':
+        return <Divider key={blockKey} className="docs-divider" opacity="12" />
+      case 'code':
+        return (
+          <div key={blockKey} className="max-w-[var(--kol-content-panel)]">
+            <CodeBlock code={block.lines.join('\n')} language={block.lang} />
+          </div>
+        )
+      case 'table':
+        return (
+          <div key={blockKey} className="max-w-[var(--kol-content-panel)]">
+            <Table
+              variant="simple"
+              columns={block.headers.map((header, i) => ({ accessor: `c${i}`, header }))}
+              rows={block.rows.map((row, rowIndex) => ({
+                id: rowIndex,
+                ...Object.fromEntries(row.map((cell, cellIndex) => [
+                  `c${cellIndex}`,
+                  cell.tokens ? renderTokens(cell.tokens, `${blockKey}-row-${rowIndex}-cell-${cellIndex}`) : cell.content,
+                ])),
+              }))}
+              className="kol-doc-table"
+            />
+          </div>
+        )
+      default:
+        return null
+    }
+  }
 
   const doc = useMemo(() => {
     return inventory.find((d) => d.id === docId)
@@ -218,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. */
@@ -228,6 +355,7 @@ const DocumentationReader = ({
         key={docId}
         toc={toc}
         allTags={allTags}
+        related={related}
         docId={docId}
         docsIndexHref={docsIndex}
         componentsHref={components}
@@ -235,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 (
@@ -254,172 +382,19 @@ const DocumentationReader = ({
     <DocsArticle>
         <DocsFrontmatter metadata={doc.metadata} docId={docId} />
         {docTitle && (
-          <h1>{docTitle}</h1>
+          <h1 className="kol-doc-heading">{docTitle}</h1>
         )}
         {/* Render intro blocks (excluding H1 which is docTitle) */}
-        {introBlocks.filter(b => b.type !== 'heading1').map((block, index) => {
-          const blockKey = `intro-${block.type}-${index}`
-          switch (block.type) {
-            case 'paragraph':
-              return (
-                <p key={blockKey}>
-                  {block.tokens ? renderTokens(block.tokens, blockKey) : block.content}
-                </p>
-              )
-            case 'heading3':
-              return (
-                <h3 key={blockKey} id={block.id}>
-                  {block.content}
-                </h3>
-              )
-            case 'heading4':
-              return (
-                <h4 key={blockKey} id={block.id}>
-                  {block.content}
-                </h4>
-              )
-            case 'list':
-              return block.items ? (
-                <ul key={blockKey} className="docs-list tight">
-                  {block.items.map((item, i) => (
-                    <li key={i}>
-                      {item.tokens ? renderTokens(item.tokens, `${blockKey}-item-${i}`) : item.content}
-                    </li>
-                  ))}
-                </ul>
-              ) : null
-            case 'blockquote':
-              return (
-                <blockquote key={blockKey} className="docs-callout">
-                  {block.tokens ? renderTokens(block.tokens, blockKey) : block.content}
-                </blockquote>
-              )
-            case 'divider':
-              return <Divider key={blockKey} className="docs-divider" opacity="12" />
-            case 'code':
-              return (
-                <CodeBlock
-                  key={blockKey}
-                  code={block.lines.join('\n')}
-                  language={block.lang}
-                />
-              )
-            case 'table':
-              return (
-                <div key={blockKey} className="kol-table-wrapper kol-table--simple">
-                  <table className="kol-table">
-                    <thead className="kol-table-thead">
-                      <tr>
-                        {block.headers.map((header, headerIndex) => (
-                          <th key={headerIndex} className="kol-table-cell-title">{header}</th>
-                        ))}
-                      </tr>
-                    </thead>
-                    <tbody>
-                      {block.rows.map((row, rowIndex) => (
-                        <tr key={rowIndex} className="kol-table-row">
-                          {row.map((cell, cellIndex) => (
-                            <td key={cellIndex} className="kol-table-cell-text">
-                              {cell.tokens ? renderTokens(cell.tokens, `${blockKey}-row-${rowIndex}-cell-${cellIndex}`) : cell.content}
-                            </td>
-                          ))}
-                        </tr>
-                      ))}
-                    </tbody>
-                  </table>
-                </div>
-              )
-            default:
-              return null
-          }
-        })}
+        {introBlocks.filter(b => b.type !== 'heading1').map((block, index) =>
+          renderBlock(block, `intro-${block.type}-${index}`)
+        )}
 
+        {/* Sections through the packaged DocSection — the same anchored
+          * rule + h2 contract MDX pages compose with. */}
         {sections.map(({ heading, id, blocks }) => (
-          <section key={id} id={id} className="space-y-6 scroll-mt-32">
-            <h2>{heading}</h2>
-            {blocks.map((block, index) => {
-              const blockKey = `${id}-${block.type}-${index}`
-
-              switch (block.type) {
-                case 'heading3':
-                  return (
-                    <h3 key={blockKey} id={block.id}>
-                      {block.content}
-                    </h3>
-                  )
-                case 'heading4':
-                  return (
-                    <h4 key={blockKey} id={block.id}>
-                      {block.content}
-                    </h4>
-                  )
-                case 'paragraph':
-                  return (
-                    <p key={blockKey}>
-                      {block.tokens ? renderTokens(block.tokens, blockKey) : block.content}
-                    </p>
-                  )
-                case 'list': {
-                  const listClass = block.ordered
-                    ? 'docs-list docs-list--ordered tight'
-                    : 'docs-list tight'
-                  const ListComponent = block.ordered ? 'ol' : 'ul'
-                  return (
-                    <ListComponent key={blockKey} className={listClass}>
-                      {block.items.map((item, itemIndex) => (
-                        <li key={itemIndex}>
-                          {item.tokens ? renderTokens(item.tokens, `${blockKey}-item-${itemIndex}`) : item.content || item}
-                        </li>
-                      ))}
-                    </ListComponent>
-                  )
-                }
-                case 'code':
-                  return (
-                    <CodeBlock
-                      key={blockKey}
-                      code={block.lines.join('\n')}
-                      language={block.lang}
-                    />
-                  )
-                case 'blockquote':
-                  return (
-                    <blockquote key={blockKey} className="docs-callout">
-                      {block.tokens ? renderTokens(block.tokens, blockKey) : block.content}
-                    </blockquote>
-                  )
-                case 'divider':
-                  return <Divider key={blockKey} className="docs-divider" opacity="12" />
-                case 'table':
-                  return (
-                    <div key={blockKey} className="kol-table-wrapper kol-table--simple">
-                      <table className="kol-table">
-                        <thead className="kol-table-thead">
-                          <tr>
-                            {block.headers.map((header, headerIndex) => (
-                              <th key={headerIndex} className="kol-table-cell-title">{header}</th>
-                            ))}
-                          </tr>
-                        </thead>
-                        <tbody>
-                          {block.rows.map((row, rowIndex) => (
-                            <tr key={rowIndex} className="kol-table-row">
-                              {row.map((cell, cellIndex) => (
-                                <td key={cellIndex} className="kol-table-cell-text">
-                                  {cell.tokens ? renderTokens(cell.tokens, `${blockKey}-row-${rowIndex}-cell-${cellIndex}`) : cell.content}
-                                </td>
-                              ))}
-                            </tr>
-                          ))}
-                        </tbody>
-                      </table>
-                    </div>
-                  )
-                default:
-                  return null
-              }
-            })}
-          </section>
+          <DocSection key={id} id={id} title={heading}>
+            {blocks.map((block, index) => renderBlock(block, `${id}-${block.type}-${index}`))}
+          </DocSection>
         ))}
       </DocsArticle>
   )

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
 
@@ -37,15 +42,19 @@ export const renderInlineTokens = (
         return <em key={tokenKey}>{token.content}</em>
 
       case 'code':
-        return <code key={tokenKey}>{token.content}</code>
+        return <code key={tokenKey} className="kol-doc-code-inline">{token.content}</code>
 
       case 'link': {
+        /* One link idiom across doc surfaces (wave-4 retype): the anchor
+         * treatment from showcase mdx-components.jsx — colorless per the
+         * link law, emphasis + quiet underline. */
+        const linkCls = 'text-emphasis underline decoration-fg-16 underline-offset-2 hover:decoration-current'
         // For .md links, try to resolve to an app route
         if (resolveDocLink && token.url.includes('.md')) {
           const route = resolveDocLink(token.url)
           if (route) {
             return (
-              <Link key={tokenKey} to={route} className="docs-link">
+              <Link key={tokenKey} to={route} className={linkCls}>
                 {token.text}
               </Link>
             )
@@ -54,7 +63,7 @@ export const renderInlineTokens = (
           return token.text
         }
         return (
-          <a key={tokenKey} href={token.url} className="docs-link">
+          <a key={tokenKey} href={token.url} className={linkCls}>
             {token.text}
           </a>
         )
@@ -78,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