@kolkrabbi/kol-workshop 0.29.0 → 0.30.1

package/src/shell/ShellSidebar.jsx

@@ -24,13 +24,13 @@ const getChildPath = (child, basePath) => {
   return p.startsWith('/') ? p : `${basePath}/${p}`
 }
 
-const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Navigation', labelTo, collapsed, onToggle }) => {
+const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Navigation', labelTo, collapsed, onToggle, defaultCollapsed = false }) => {
   const location = useLocation()
   const normalizedPath = location.pathname.replace(/\/$/, '')
 
   // Controlled mode: collapsed + onToggle from parent
   // Uncontrolled mode: internal state
-  const [internalCollapsed, setInternalCollapsed] = useState(false)
+  const [internalCollapsed, setInternalCollapsed] = useState(defaultCollapsed)
   const isControlled = collapsed !== undefined
   const navCollapsed = isControlled ? collapsed : internalCollapsed
   const handleToggle = isControlled ? onToggle : () => setInternalCollapsed(prev => !prev)
@@ -48,26 +48,34 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
     return initial
   })
 
-  useEffect(() => {
-    routes.forEach((route) => {
-      const sectionPath = getSectionRootPath(route, basePath)
-      const isActive =
-        sectionPath === basePath
-          ? normalizedPath === basePath
-          : normalizedPath === sectionPath || normalizedPath.startsWith(sectionPath + '/')
-      if (isActive) {
-        setCollapsedSections((prev) => ({ ...prev, [route.id]: false }))
-      }
+  /* THE RAIL FOLLOWS YOU (2026-09-28, user: "the sidebar doesnt highlight that
+   * part, which it probably should by closing/collapsing other categories").
+   * Arriving in a group opens it AND folds its siblings, so the open group is
+   * the one you are in. Opening another by hand still works until you move. */
+  const isRouteActive = (route) => {
+    const sectionPath = getSectionRootPath(route, basePath)
+    const own = sectionPath === basePath
+      ? normalizedPath === basePath
+      : normalizedPath === sectionPath || normalizedPath.startsWith(sectionPath + '/')
+    return own || (route.children ?? []).some((c) => {
+      const cp = getChildPath(c, basePath).replace(/\/$/, '')
+      return normalizedPath === cp || normalizedPath.startsWith(cp + '/')
     })
+  }
+  useEffect(() => {
+    const active = routes.filter(isRouteActive)
+    if (!active.length) return
+    setCollapsedSections(Object.fromEntries(routes.map((r) => [r.id, !active.includes(r)])))
+    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [normalizedPath, routes, basePath])
 
   const handleSectionClick = (route) => {
     setCollapsedSections((prev) => ({ ...prev, [route.id]: !prev[route.id] }))
   }
 
-  /* No count at L1 — the eyebrow names a body of material and the tally lives
-   * on the groups inside it (user ruling 2026-08-01). RailSection refuses one
-   * at this rung, so there is nothing to compute here. */
+  /* The L1 count is every leaf row under it — RailSection shows it only while
+   * the section is folded (2026-09-28). */
+  const leafCount = routes.reduce((n, r) => n + (r.children?.length ? r.children.length : 1), 0)
   return (
     /* One rail layout, one class (2026-08-01). This was `space-y-4` against the
      * right rail's `space-y-6` against the outer `flex flex-col gap-6` — three
@@ -78,9 +86,11 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
         level={1}
         label={label}
         to={labelTo}
+        count={leafCount}
         collapsed={navCollapsed}
         onToggle={handleToggle}
         onNavigate={onNavigate}
+        icon={Icon}
       >
         <div className="shell-rail-stack-inner">
           {routes.map((route) => {

package/src/shell/index.js

@@ -7,7 +7,7 @@
  * against.
  */
 export { default as ShellLayout } from './ShellLayout.jsx'
-export { ShellTocContext, ShellFullHeightContext, ShellTocCollapsedContext, ShellNavCollapsedContext, ShellContentWidthContext } from './ShellLayout.jsx'
+export { ShellTocContext, ShellFullHeightContext, ShellTocCollapsedContext, ShellNavCollapsedContext, ShellContentWidthContext, SHELL_SCROLL_ROOT, usePageMeta, usePageMetaValue } from './ShellLayout.jsx'
 export { default as ShellSidebar } from './ShellSidebar.jsx'
 /* RailSection — THE rail ladder. Every rail header at every rung comes from
  * here, in both rails; see the file header for why a class alone was not

package/src/tags/TagGraph.jsx

@@ -1,8 +1,8 @@
 import { useEffect, useRef, useMemo, useState } from 'react'
 import * as d3 from 'd3'
 import { useNavigate } from 'react-router-dom'
-import { getTagColor } from '../engine/index.js'
-import { buildTagCooccurrence } from '../engine/tags.js'
+import { getTagColor } from '@kolkrabbi/kol-markdown'
+import { tagGraph } from '@kolkrabbi/kol-search'
 
 /**
  * TagGraph - Obsidian-style tag graph
@@ -26,7 +26,8 @@ const TagGraph = ({ docs, activeTag, onTagClick, allDocs, tagHref = defaultTagHr
   const sourceDocs = allDocs || docs
 
   // Compute graph data: ALL tags with connections (pure — see engine/tags.js)
-  const graphData = useMemo(() => buildTagCooccurrence(sourceDocs), [sourceDocs])
+  /* the engine's graph (kol-search `tagGraph`, 2026-09-29) over the docs' tags */
+  const graphData = useMemo(() => tagGraph(sourceDocs.map((d) => ({ id: d.id, tags: d.metadata?.tags ?? [] }))), [sourceDocs])
 
   // Update dimensions on resize
   useEffect(() => {

package/src/tags/TagModeOverlay.jsx

@@ -5,8 +5,9 @@ import TagPath from './TagPath.jsx'
 import { useTagMode } from './TagModeContext.jsx'
 import TagGraph from './TagGraph.jsx'
 import RailRow from '../shell/RailRow.jsx'
-import { extractDocNumber, cleanTitle, matchSearchItems } from '../engine/index.js'
-import { buildTagCounts } from '../engine/tags.js'
+import { extractDocNumber, cleanTitle } from '@kolkrabbi/kol-markdown'
+import { matchSearchItems } from '@kolkrabbi/kol-search'
+import { buildTagCounts } from '@kolkrabbi/kol-markdown'
 
 /**
  * TagModeOverlay - the committed RESULTS view: documents that match, with tags

package/src/engine/__check.mjs

@@ -1,72 +0,0 @@
-/**
- * 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

@@ -1,85 +0,0 @@
-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()
-    /* 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] ?? ''
-    const baseId = filename.replace(/\.md$/, '')
-
-    // Make index.md / INDEX.md IDs unique by prefixing with parent folder
-    const id = baseId.toLowerCase() === 'index' ? `${parentFolder}-${baseId}` : 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, headings, parentFolder }
-  })
-
-  /* Collision safety (2026-07-30): filename-only ids collide across folders in
-   * any real vault (02-icons/01-inventory vs 03-components/01-inventory — the
-   * React dup-key bug from the 07-29 vault experiment). A collided id gains
-   * its parent folder, same convention the index handling already uses. */
-  const counts = inventory.reduce((m, d) => (m[d.id] = (m[d.id] ?? 0) + 1, m), {})
-  for (const d of inventory) {
-    if (counts[d.id] > 1) d.id = `${d.parentFolder}-${d.id}`
-  }
-  for (const d of inventory) delete d.parentFolder
-
-  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: {} }
-  )
-}

package/src/engine/doc-helpers.js

@@ -1,202 +0,0 @@
-/**
- * Shared doc/tag helpers — pure, zero-dependency. Lifted verbatim.
- *
- * These bake in the KOL numbered-doc taxonomy (`categoryLabels`, version
- * conventions, `kolkrabbiPages`). That's correct for a KOL package; a future
- * consumer with a different scheme would parameterize these — not yet needed.
- */
-
-export const capitalise = (value) =>
-  value ? value.charAt(0).toUpperCase() + value.slice(1) : value
-
-/**
- * fileLabel — a rail row's name, taken from the FILENAME (user ruling
- * 2026-08-01).
- *
- * The tree used to label rows from the doc's H1, so `01-tokens.md` (opening
- * `# Foundations — the token system`) rendered as "Foundations" — a row whose
- * name appears nowhere in the folder, and two files whose H1s both began
- * "Foundations" collapsed into two identical rows. A tree that mirrors a
- * folder has to read the folder: what Finder shows is what the sidebar shows.
- *
- *   01-tokens.md             → Tokens
- *   04-layout-breakpoints.md → Layout breakpoints
- *
- * Titles still drive SEARCH and the page header; this is the tree label only.
- */
-export const fileLabel = (file = '') => {
-  const base = file.split('/').pop()?.replace(/\.md$/i, '') ?? ''
-  const named = base.replace(/^\d+(\.\d+)*[-.]?\s*/, '')
-  if (!named) return capitalise(base)
-  return capitalise(named.replace(/[-_]+/g, ' ').trim())
-}
-
-// Index.md files (e.g. "00-metadata-index", "foundry-index") have no version dots
-export const isIndexFile = (id) => id.endsWith('-index') && !id.includes('.')
-
-export const extractDocNumber = (id) => {
-  if (isIndexFile(id)) {
-    // Main section index: "04-pages-index" → "4.0.0"
-    const folderMatch = id.match(/^(\d+)-[a-z-]+-index$/)
-    if (folderMatch) {
-      const major = folderMatch[1].replace(/^0/, '')
-      return `${major}.0.0`
-    }
-    return 'Index'
-  }
-  // "0.0.1-writing-guidelines" → "0.0.1"
-  const match = id.match(/^(\d+\.\d+\.\d+)/)
-  return match ? match[1] : id
-}
-
-// Main site pages that should have "Kolkrabbi" prefix
-export const kolkrabbiPages = ['4.1.0', '4.2.0', '4.3.0', '4.4.0']
-
-// Subsection prefixes based on version range
-export const subsectionPrefixes = {
-  '4.6': 'Collections',
-}
-
-export const categoryLabels = {
-  0: 'Docs',
-  1: 'Foundation',
-  2: 'Design System',
-  3: 'Components',
-  4: 'Pages',
-  5: 'Workshop',
-  6: 'Foundry',
-  7: 'Research',
-  8: 'Operations',
-  9: 'CDN',
-}
-
-export const cleanTitle = (title, id) => {
-  if (isIndexFile(id)) {
-    const folderMatch = id.match(/^(\d+)-([a-z-]+)-index$/)
-    if (folderMatch) {
-      const major = folderMatch[1].replace(/^0/, '')
-      return `${categoryLabels[major] || 'Section'} Index`
-    }
-    return 'Section Index'
-  }
-
-  let cleaned = title.replace(/^\d+\.\d+\.\d+\s*/, '')
-  cleaned = cleaned.replace(/^[A-Za-z\s]+:\s*/, '')
-  /* SUBTITLE OFF (user ruling 2026-08-01): "dont Foundtation - the token
-   * system, just 'foundation'". A doc's `title` is written for the document —
-   * "Type classes — the two families and when to use which" — and a rail row
-   * is not the place to read a sentence: three of eight rows wrapped to two
-   * and three lines. Everything from the em/en dash on is the subtitle, so the
-   * row keeps the name and drops the explanation. The DOC's own title is
-   * untouched; this is the rail's label only.
-   * Spaced dash only — an unspaced one is a compound word, not a separator. */
-  cleaned = cleaned.replace(/\s+[—–]\s+.*$/, '')
-  cleaned = cleaned.trim() || title
-
-  const versionMatch = id.match(/^(\d+\.\d+)\.(\d+)/)
-  if (versionMatch) {
-    const majorMinor = versionMatch[1]
-
-    if (kolkrabbiPages.includes(`${majorMinor}.${versionMatch[2]}`)) {
-      return `Kolkrabbi ${cleaned}`
-    }
-
-    const prefix = subsectionPrefixes[majorMinor]
-    if (prefix) {
-      const prefixPattern = new RegExp(`^(${prefix}|${prefix.replace(/s$/, '')})(\\s+|$)`, 'i')
-      cleaned = cleaned.replace(prefixPattern, '').trim()
-      const suffixPattern = new RegExp(`(\\s+|^)(${prefix}|${prefix.replace(/s$/, '')})$`, 'i')
-      cleaned = cleaned.replace(suffixPattern, '').trim()
-      return `${prefix} ${cleaned}`
-    }
-  }
-
-  return cleaned
-}
-
-const TAG_COLORS = ['blue', 'teal', 'green', 'yellow', 'red', 'orange', 'purple', 'dark']
-
-/* Colour BY NAMESPACE, from the closed taxonomy in `.kol/docs-framework/
- * 03-tag-taxonomy.md`. Ten top-level namespaces, ten stable assignments —
- * so `domain/*` is always one colour and the eye can group by prefix.
- *
- * This used to hash the whole tag string into TAG_COLORS. That made the colour
- * a function of spelling rather than meaning: `#domain/design-system` and
- * `#domain/iconography` landed on different hues for no reason a reader could
- * see, and renaming a tag silently recoloured it. The taxonomy existed the
- * whole time and nothing consulted it. */
-const NAMESPACE_COLORS = {
-  domain: 'blue',
-  pattern: 'purple',
-  provider: 'orange',
-  integration: 'teal',
-  project: 'green',
-  audience: 'yellow',
-  brand: 'red',
-  editor: 'teal',
-  framework: 'dark',
-  archive: 'dark',
-}
-
-/** Stable fallback for tags outside the taxonomy — still deterministic, but
- *  only reached when a tag carries no known namespace. */
-const hashColor = (s) => {
-  let hash = 0
-  for (let i = 0; i < s.length; i++) hash = ((hash << 5) - hash + s.charCodeAt(i)) | 0
-  return TAG_COLORS[Math.abs(hash) % TAG_COLORS.length]
-}
-
-export const getTagColor = (tag) => {
-  const namespace = String(tag).replace(/^#/, '').split('/')[0]
-  return NAMESPACE_COLORS[namespace] ?? hashColor(namespace)
-}
-
-/** Group docs by major version number.
- *
- * Three id dialects are grouped: dotted (`0.0.1-slug`), folder-index
- * (`04-pages-index`), and PLAIN NUMBERED (`04-layout-breakpoints`) — the last
- * one was previously unmatched, so a vault of `NN-slug.md` files produced a
- * tree holding only its INDEX files and every real doc was search-only
- * (fixed 2026-07-30). Multi-word folder names work too: the old
- * `^(\d+)-[a-z]+-index$` rejected any hyphen, silently dropping ids like
- * `09-ds-adoption-index`.
- */
-export const groupDocsByMajor = (docs) => {
-  const groups = {}
-  docs.forEach((d) => {
-    const majorMatch = d.id.match(/^(\d+)\./)
-    const indexMatch = d.id.match(/^(\d+)-[a-z][a-z0-9-]*-index$/)
-    const plainMatch = d.id.match(/^(\d+)-/)
-
-    let major = null
-    if (majorMatch) {
-      major = majorMatch[1]
-    } else if (indexMatch) {
-      major = indexMatch[1].replace(/^0/, '')
-    } else if (plainMatch) {
-      major = plainMatch[1].replace(/^0(?=\d)/, '')
-    } else if (isIndexFile(d.id)) {
-      const titleMatch = d.title.match(/^(\d+)\./)
-      if (titleMatch) {
-        major = titleMatch[1]
-      }
-    }
-
-    if (major !== null) {
-      if (!groups[major]) {
-        groups[major] = []
-      }
-      groups[major].push(d)
-    }
-  })
-
-  Object.keys(groups).forEach((major) => {
-    groups[major].sort((a, b) => {
-      const aNum = extractDocNumber(a.id)
-      const bNum = extractDocNumber(b.id)
-      return aNum.localeCompare(bNum, undefined, { numeric: true })
-    })
-  })
-
-  return groups
-}

package/src/engine/frontmatter.js

@@ -1,41 +0,0 @@
-/**
- * Handrolled YAML-subset frontmatter parser — no gray-matter / js-yaml.
- * Handles `key: value`, block lists (`  - item`), and inline `[a, b]` arrays.
- * Keys are lowercased. Lifted verbatim from the monorepo.
- */
-export const parseFrontmatter = (raw) => {
-  const metadata = {}
-  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---/)
-  if (!match) return metadata
-
-  const lines = match[1].split(/\r?\n/)
-  for (let i = 0; i < lines.length; i++) {
-    const kvMatch = lines[i].match(/^([A-Za-z][A-Za-z0-9 -]*):\s*(.*)$/)
-    if (kvMatch) {
-      const key = kvMatch[1].toLowerCase()
-      const value = kvMatch[2].trim()
-      if (!value) {
-        // YAML block-list continuation lines (  - item)
-        const items = []
-        while (i + 1 < lines.length && lines[i + 1].match(/^\s+-\s+/)) {
-          i++
-          items.push(lines[i].replace(/^\s+-\s+/, '').trim())
-        }
-        metadata[key] = items.length ? items : ''
-      } else {
-        metadata[key] = value
-      }
-    }
-  }
-
-  // Parse tags array from YAML "[foo, bar, baz]" string into JS array
-  if (typeof metadata.tags === 'string' && metadata.tags.startsWith('[')) {
-    metadata.tags = metadata.tags
-      .slice(1, -1)
-      .split(',')
-      .map((t) => t.trim())
-      .filter(Boolean)
-  }
-
-  return metadata
-}