@kolkrabbi/kol-workshop 0.1.0

package/src/docs/DocumentationReader.jsx

@@ -0,0 +1,417 @@
+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 { 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 { renderInlineTokens } from './render-tokens.jsx'
+
+const SidebarSection = ({ sectionKey, label, collapsedSections, toggleSection, children }) => (
+  <div>
+    <button
+      type="button"
+      className="shell-sidebar-toggle shell-sidebar-label"
+      onClick={() => toggleSection(sectionKey)}
+    >
+      {label}
+    </button>
+    {!collapsedSections[sectionKey] && children}
+  </div>
+)
+
+const DocReaderSidebar = ({ toc, allTags, docId, docsIndexHref, componentsHref, docFilePath }) => {
+  const navigate = useNavigate()
+  const { openTagMode } = useTagMode()
+  const [collapsedSections, setCollapsedSections] = useState({})
+  const toggleSection = (key) => setCollapsedSections(prev => ({ ...prev, [key]: !prev[key] }))
+
+  return (
+    <div className="space-y-6">
+      <SidebarSection
+        sectionKey="toc"
+        label="On this page"
+        collapsedSections={collapsedSections}
+        toggleSection={toggleSection}
+      >
+        <DocsToc toc={toc} />
+      </SidebarSection>
+
+      <SidebarSection
+        sectionKey="actions"
+        label="Quick actions"
+        collapsedSections={collapsedSections}
+        toggleSection={toggleSection}
+      >
+        <div className="space-y-1">
+          <button
+            type="button"
+            className="shell-sidebar-action"
+            onClick={() => navigate(-1)}
+          >
+            <Icon name="arrow-left" size={14} />
+            Back
+          </button>
+          <Link to={docsIndexHref} className="shell-sidebar-action">
+            <Icon name="book-open" size={14} />
+            All documentation
+          </Link>
+          <Link to={componentsHref} className="shell-sidebar-action">
+            <Icon name="grid" size={14} />
+            View components
+          </Link>
+          <button
+            type="button"
+            className="shell-sidebar-action"
+            onClick={() => navigator.clipboard.writeText(docFilePath(docId))}
+            title="Copy file path to clipboard"
+          >
+            <Icon name="copy" size={14} />
+            Copy path
+          </button>
+        </div>
+      </SidebarSection>
+
+      {allTags.length > 0 && (
+        <SidebarSection
+          sectionKey="tags"
+          label="Tags"
+          collapsedSections={collapsedSections}
+          toggleSection={toggleSection}
+        >
+          <div className="flex flex-col gap-1.5 items-start min-w-0 w-full">
+            {allTags.map((tag) => (
+              <Tag
+                key={tag}
+                variant="naked"
+                size="lg"
+                color={getTagColor(tag)}
+                onClick={() => openTagMode(tag)}
+                className="max-w-full overflow-hidden text-ellipsis"
+              >
+                {tag}
+              </Tag>
+            ))}
+          </div>
+        </SidebarSection>
+      )}
+    </div>
+  )
+}
+
+/**
+ * DocumentationReader — the docs render surface, decoupled from Vite.
+ *
+ * The monorepo original re-declared its own `import.meta.glob('@docs/…')` and
+ * hardcoded `/workshop/*` routes. Both are lifted OUT here: the raw markdown
+ * modules + the inventory arrive as props, and every route is derived from
+ * `docHref` / `routes`, so this package stays bundler- and route-agnostic.
+ *
+ * @param {Object}   props
+ * @param {Array}    props.inventory  Doc inventory (was `documentationInventory`).
+ * @param {Object}   props.modules    Map of `path -> raw markdown string` (was the
+ *                                    `import.meta.glob` result). The consuming app
+ *                                    supplies its own glob.
+ * @param {Function} props.docHref    (id) => route for a single doc. Default
+ *                                    `(id) => \`/docs/${id}\``.
+ * @param {Object}   props.routes     Config for the remaining routes/paths:
+ *   @param {string}   routes.docsIndex   "all documentation" link (default `/docs`).
+ *   @param {string}   routes.components  "view components" link (default `/components`).
+ *   @param {Function} routes.tagHref     (tag) => href for hashtag pills
+ *                                        (default `/docs?tag=…`).
+ *   @param {Function} routes.docFilePath (id) => on-disk path copied to clipboard
+ *                                        (default `docs/documentation/${id}.md`).
+ */
+const DocumentationReader = ({
+  inventory = [],
+  modules = {},
+  docHref = (id) => `/docs/${id}`,
+  routes = {}
+}) => {
+  const {
+    docsIndex = '/docs',
+    components = '/components',
+    tagHref = (tag) => `/docs?tag=${encodeURIComponent(tag)}`,
+    docFilePath = (id) => `docs/documentation/${id}.md`
+  } = routes
+
+  const { docId } = useParams()
+  const setTocContent = useContext(ShellTocContext)
+
+  // Build a Set of known doc IDs for fast lookup
+  const knownDocIds = useMemo(
+    () => new Set(inventory.map((d) => d.id)),
+    [inventory]
+  )
+
+  /**
+   * Resolve a .md link URL to an app route, or null if not a known doc.
+   * Extracts the doc ID from the filename portion of the URL.
+   */
+  const resolveDocLink = (url) => {
+    if (!url || !url.includes('.md')) return null
+    // Strip anchor fragment
+    const [pathPart, anchor] = url.split('#')
+    const basename = pathPart.split('/').pop().replace(/\.md$/, '')
+    if (knownDocIds.has(basename)) {
+      const route = docHref(basename)
+      return anchor ? `${route}#${anchor}` : route
+    }
+    return null
+  }
+
+  // Bind the resolved link + tag helpers so call sites stay terse.
+  const renderTokens = (tokens, tokenKey) =>
+    renderInlineTokens(tokens, tokenKey, resolveDocLink, tagHref)
+
+  const doc = useMemo(() => {
+    return inventory.find((d) => d.id === docId)
+  }, [inventory, docId])
+
+  const rawMarkdown = useMemo(() => {
+    if (!doc) return null
+    // For index files, the docId is like "00-metadata-index" but the file is "index.md"
+    // For regular files, docId matches the filename (e.g., "0.0.1-writing-guidelines")
+    const path = Object.keys(modules).find((p) => {
+      if (isIndexFile(docId)) {
+        // Match index.md files by checking if the path ends with /index.md
+        // and the parent folder matches the docId prefix
+        const folderMatch = docId.match(/^(\d+-[a-z-]+)-index$/)
+        const nestedMatch = docId.match(/^([a-z]+)-index$/)
+        if (folderMatch) {
+          // e.g., "00-metadata-index" → look for "00-metadata/index.md"
+          return p.includes(`/${folderMatch[1]}/index.md`)
+        } else if (nestedMatch) {
+          // e.g., "foundry-index" → look for "foundry/index.md"
+          return p.includes(`/${nestedMatch[1]}/index.md`)
+        }
+      }
+      return p.endsWith(`${docId}.md`)
+    })
+    return path ? modules[path] : null
+  }, [doc, docId, modules])
+
+  const { sections, toc, introBlocks, inlineTags } = useMemo(() => {
+    if (!rawMarkdown) return { sections: [], toc: [], introBlocks: [], inlineTags: [] }
+    const parsed = parseDocsMarkdown(rawMarkdown)
+    return { sections: parsed.sections, toc: parsed.toc, introBlocks: parsed.introBlocks, inlineTags: parsed.inlineTags }
+  }, [rawMarkdown])
+
+  // Combine frontmatter tags with inline hashtags
+  const allTags = useMemo(() => {
+    const frontmatterTags = doc?.metadata?.tags || []
+    return [...new Set([...frontmatterTags, ...inlineTags])]
+  }, [doc, inlineTags])
+
+  // Extract H1 title from introBlocks
+  const docTitle = useMemo(() => {
+    const h1Block = introBlocks.find((block) => block.type === 'heading1')
+    return h1Block?.content || null
+  }, [introBlocks])
+
+  useEffect(() => {
+    setTocContent(
+      <DocReaderSidebar
+        key={docId}
+        toc={toc}
+        allTags={allTags}
+        docId={docId}
+        docsIndexHref={docsIndex}
+        componentsHref={components}
+        docFilePath={docFilePath}
+      />
+    )
+    return () => setTocContent(null)
+  }, [setTocContent, docId, toc, allTags, docsIndex, components, docFilePath])
+
+  if (!doc) {
+    return (
+      <div className="max-w-[1400px] mx-auto px-10 py-16">
+        <DocsHeader title="Document Not Found" subtitle={`Could not find document: ${docId}`} />
+        <p className="kol-mono-12 mt-6">
+          <Link to={docsIndex} className="text-accent-primary">
+            ← Back to documentation
+          </Link>
+        </p>
+      </div>
+    )
+  }
+
+  return (
+    <DocsArticle>
+        <DocsFrontmatter metadata={doc.metadata} docId={docId} />
+        {docTitle && (
+          <h1 className="docs-title">{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
+          }
+        })}
+
+        {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>
+        ))}
+      </DocsArticle>
+  )
+}
+
+export default DocumentationReader

package/src/docs/index.js

@@ -0,0 +1,14 @@
+/**
+ * @kolkrabbi/kol-workshop — docs viewer (render layer).
+ *
+ * Lifted from the monorepo's `apps/web` docs surface and decoupled from Vite:
+ * the reader takes its markdown `modules` + `inventory` as props and derives all
+ * routes from `docHref` / `routes` (no `import.meta.glob`, no hardcoded
+ * `/workshop/*` paths). The pure parser lives in `../engine`; tag mode in
+ * `../tags`; the shell TOC injection context in `../shell`.
+ */
+export { default as DocumentationReader } from './DocumentationReader.jsx'
+export { default as DocsArticle } from './DocsArticle.jsx'
+export { default as DocsHeader } from './DocsHeader.jsx'
+export { default as DocsFrontmatter } from './DocsFrontmatter.jsx'
+export { renderInlineTokens } from './render-tokens.jsx'

package/src/docs/render-tokens.jsx

@@ -0,0 +1,98 @@
+import { Link } from 'react-router-dom'
+
+/**
+ * React render layer for inline markdown tokens.
+ *
+ * The PURE token producer (`processInlineMarkdown` / `parseDocsMarkdown`) lives
+ * in `../engine/parse-markdown.js` with zero React/router deps. This module is
+ * the render half that was split off from it — it needs react-router `Link`, so
+ * it can't live in the engine.
+ *
+ * @param {Array}    tokens        Inline token array from parseDocsMarkdown.
+ * @param {string}   key           Key prefix for the emitted React nodes.
+ * @param {Function} resolveDocLink (url) => route|null for `.md` cross-links.
+ * @param {Function} tagHref       (tag) => href for `#hashtag` pills. Default
+ *                                 keeps hashtags route-agnostic (`/docs?tag=…`);
+ *                                 the reader passes a configured href in.
+ */
+export const renderInlineTokens = (
+  tokens,
+  key = '',
+  resolveDocLink = null,
+  tagHref = (tag) => `/docs?tag=${encodeURIComponent(tag)}`
+) => {
+  if (!Array.isArray(tokens)) return null
+
+  return tokens.map((token, index) => {
+    const tokenKey = `${key}-${index}`
+
+    switch (token.type) {
+      case 'text':
+        return token.content
+
+      case 'bold':
+        return <strong key={tokenKey}>{token.content}</strong>
+
+      case 'italic':
+        return <em key={tokenKey}>{token.content}</em>
+
+      case 'code':
+        return <code key={tokenKey}>{token.content}</code>
+
+      case 'link': {
+        // 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">
+                {token.text}
+              </Link>
+            )
+          }
+          // Dead .md link — render as plain text
+          return token.text
+        }
+        return (
+          <a key={tokenKey} href={token.url} className="docs-link">
+            {token.text}
+          </a>
+        )
+      }
+
+      case 'image':
+        return (
+          <img
+            key={tokenKey}
+            src={token.src}
+            alt={token.alt}
+            className="docs-image"
+          />
+        )
+
+      case 'colorswatch':
+        return (
+          <code key={tokenKey} className="docs-color-swatch">
+            <span className="docs-color-swatch-dot" style={{ background: token.color }} />
+            {token.color}
+          </code>
+        )
+
+      case 'hashtag':
+        return (
+          <Link
+            key={tokenKey}
+            to={tagHref(token.tag)}
+            className="inline-tag-pill"
+          >
+            #{token.tag}
+          </Link>
+        )
+
+      default:
+        return null
+    }
+  })
+}
+
+export default renderInlineTokens

package/src/engine/__check.mjs

@@ -0,0 +1,72 @@
+/**
+ * Runnable self-check for the pure engine.  `node src/engine/__check.mjs`
+ * Asserts the parser, frontmatter, inventory seam, and helpers hold.
+ */
+import assert from 'node:assert'
+import {
+  parseDocsMarkdown,
+  parseFrontmatter,
+  buildInventory,
+  buildInventoryCounts,
+  getTagColor,
+  extractDocNumber,
+} from './index.js'
+
+const md = `---
+title: Demo
+status: draft
+tags: [alpha, beta]
+---
+# Title
+Intro paragraph with a #gamma tag.
+## Section One
+- item one
+- item two
+## Section Two
+| A | B |
+|---|---|
+| 1 | 2 |
+`
+
+// --- parser ---
+const parsed = parseDocsMarkdown(md)
+assert.equal(parsed.toc.length, 2, 'two H2 sections in toc')
+assert.equal(parsed.toc[0].id, 'section-one')
+assert.ok(parsed.inlineTags.includes('gamma'), 'harvests inline #gamma')
+assert.equal(parsed.introBlocks[0].type, 'heading1')
+const s1 = parsed.sections[0]
+assert.equal(s1.blocks[0].type, 'list')
+assert.equal(s1.blocks[0].items.length, 2)
+const s2 = parsed.sections[1]
+assert.equal(s2.blocks[0].type, 'table')
+assert.deepEqual(s2.blocks[0].headers, ['A', 'B'])
+assert.equal(s2.blocks[0].rows.length, 1)
+
+// --- frontmatter ---
+const fm = parseFrontmatter(md)
+assert.deepEqual(fm.tags, ['alpha', 'beta'], 'inline array tags')
+assert.equal(fm.title, 'Demo')
+assert.equal(fm.status, 'draft')
+
+// --- inventory seam (module map, no Vite glob) ---
+const inv = buildInventory({
+  '/x/docs/documentation/03-components/3.0.1-button.md': '---\ntags: [ui]\nstatus: stable\n---\n# Button\n',
+  '/x/docs/documentation/00-docs/index.md': '---\nstatus: stable\n---\n# Intro\n',
+})
+assert.equal(inv.length, 2)
+const btn = inv.find((d) => d.id === '3.0.1-button')
+assert.ok(btn, 'button doc discovered')
+assert.equal(btn.title, 'Button')
+assert.deepEqual(btn.metadata.tags, ['ui'])
+assert.equal(inv.find((d) => d.file.endsWith('00-docs/index.md')).id, '00-docs-index', 'index.md id gets folder prefix')
+const counts = buildInventoryCounts(inv)
+assert.equal(counts.total, 2)
+assert.equal(counts.statuses.stable, 2)
+
+// --- helpers ---
+assert.equal(extractDocNumber('0.0.1-writing'), '0.0.1')
+assert.equal(extractDocNumber('04-pages-index'), '4.0.0')
+assert.ok(['blue', 'teal', 'green', 'yellow', 'red', 'orange', 'purple', 'dark'].includes(getTagColor('ui')))
+assert.equal(getTagColor('ui'), getTagColor('ui'), 'deterministic')
+
+console.log('kol-workshop engine self-check: OK')

package/src/engine/build-inventory.js

@@ -0,0 +1,62 @@
+import { parseFrontmatter } from './frontmatter.js'
+
+/**
+ * The doc inventory + counts, DECOUPLED from Vite.
+ *
+ * The monorepo original ran `import.meta.glob('@docs/...')` at module load,
+ * hard-binding it to Vite and the monorepo `/docs` path. Here the consumer
+ * supplies the raw-markdown module map instead — this is the content-injection
+ * seam that lets the set drop into any repo:
+ *
+ *   const modules = import.meta.glob('/docs/ ** /*.md',
+ *     { eager: true, query: '?raw', import: 'default' })
+ *   const inventory = buildInventory(modules)
+ *
+ * @param {Record<string,string>} modules  path → raw markdown string
+ */
+export function buildInventory(modules) {
+  const inventory = Object.entries(modules).map(([path, raw]) => {
+    const normalisedPath = path.replace(/^.*\/docs\/documentation\//, 'docs/documentation/')
+    const lines = raw.split(/\r?\n/)
+    const headingLine = lines.find((line) => line.startsWith('# ')) ?? ''
+    const title = headingLine.replace(/^#\s+/, '').trim()
+    const metadata = parseFrontmatter(raw)
+    const filename = normalisedPath.split('/').pop() ?? ''
+    const parentFolder = normalisedPath.split('/').slice(-2, -1)[0] ?? ''
+    const baseId = filename.replace(/\.md$/, '')
+
+    // Make index.md IDs unique by prefixing with parent folder
+    const id = baseId === 'index' ? `${parentFolder}-index` : baseId
+
+    const rawTitle = title || metadata.title || id
+    const cleanTitle = rawTitle
+      .replace(/^Design System\s*[-–—:]\s*/i, '')
+      .replace(/\bCheat Sheet\b/i, 'Quicklook')
+
+    return { id, file: normalisedPath, title: cleanTitle, metadata }
+  })
+
+  inventory.sort((a, b) => a.file.localeCompare(b.file))
+  return inventory
+}
+
+/** Tally status / category / content-type across an inventory. */
+export function buildInventoryCounts(inventory) {
+  return inventory.reduce(
+    (acc, doc) => {
+      acc.total += 1
+      const { metadata } = doc
+      if (metadata.status) {
+        acc.statuses[metadata.status] = (acc.statuses[metadata.status] ?? 0) + 1
+      }
+      if (metadata.category) {
+        acc.categories[metadata.category] = (acc.categories[metadata.category] ?? 0) + 1
+      }
+      if (metadata['content-type']) {
+        acc.contentTypes[metadata['content-type']] = (acc.contentTypes[metadata['content-type']] ?? 0) + 1
+      }
+      return acc
+    },
+    { total: 0, statuses: {}, categories: {}, contentTypes: {} }
+  )
+}