@kolkrabbi/kol-workshop 0.1.0

package/README.md

@@ -0,0 +1,38 @@
+# @kolkrabbi/kol-workshop
+
+The KOL **workshop / docs system**, lifted from the monorepo `apps/web` into the design system.
+
+A handrolled documentation engine — no `remark`, no `gray-matter`, no `fuse.js` — plus (in later phases) the docs shell, search, and a tag system including a d3 tag graph. Sits above the other four UI packages and consumes them.
+
+## Status
+
+**Phase 1 — the pure engine (this release).** React-free, zero-dependency:
+
+| Import | What |
+| --- | --- |
+| `parseDocsMarkdown(md)` | block + inline markdown → `{ sections, toc, introBlocks, inlineTags }` |
+| `parseFrontmatter(raw)` | YAML-subset frontmatter → object (inline arrays + block lists) |
+| `buildInventory(modules)` | a raw-markdown module map → a doc inventory (see the seam below) |
+| `buildInventoryCounts(inv)` | status / category / content-type tallies |
+| `getTagColor`, `extractDocNumber`, `cleanTitle`, `groupDocsByMajor`, … | doc/tag helpers |
+
+```js
+import { parseDocsMarkdown, buildInventory } from '@kolkrabbi/kol-workshop/engine'
+```
+
+### Content-injection seam
+
+The package is **Vite-agnostic** — it never globs your docs. The consumer supplies the raw-markdown module map:
+
+```js
+const modules = import.meta.glob('/docs/**/*.md', { eager: true, query: '?raw', import: 'default' })
+const inventory = buildInventory(modules)
+```
+
+## Roadmap
+
+- **Phase 2** — the shell + docs viewer + tag-mode components, KOL-conformed (Button / Icon-v1 / no text-transform), chrome CSS moved into `@kolkrabbi/kol-theme`.
+- **Phase 3** — content-injection seam extended to route + search config.
+- **Phase 4** — flip `private` off, publish, repoint the monorepo `apps/web` onto it, delete the local copies.
+
+Self-check: `node src/engine/__check.mjs`.

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kolkrabbi/kol-workshop",
+  "version": "0.1.0",
+  "private": false,
+  "description": "KOL workshop/docs system — handrolled markdown engine, search, tag system, and the docs shell. Sits above @kolkrabbi/kol-{theme,icons,component,framework}. Private until the conformance sweep (Phase 4) ships it.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./engine": "./src/engine/index.js"
+  },
+  "dependencies": {
+    "d3": "^7.9.0",
+    "@kolkrabbi/kol-component": "0.7.0",
+    "@kolkrabbi/kol-framework": "0.3.2",
+    "@kolkrabbi/kol-icons": "0.5.0",
+    "@kolkrabbi/kol-theme": "0.7.0"
+  },
+  "peerDependencies": {
+    "react": "^18.3.0 || ^19.0.0",
+    "react-dom": "^18.3.0 || ^19.0.0",
+    "react-router-dom": "^6.0.0 || ^7.0.0"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "keywords": [
+    "kol",
+    "kolkrabbi",
+    "design-system",
+    "docs",
+    "markdown",
+    "workshop"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Tor-Grimsson/kol-ds.git",
+    "directory": "packages/workshop"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/compositions/WorkshopDefaultSidebar.jsx

@@ -0,0 +1,89 @@
+import { useLocation, Link } from 'react-router-dom'
+import { Icon } from '@kolkrabbi/kol-component'
+
+/**
+ * WorkshopDefaultSidebar — EXAMPLE composition. The contextual right rail:
+ * given the current route it shows sibling pages, the section's repo links, and
+ * quick actions. Decoupled from app singletons via props:
+ *
+ *   routes   — nav tree (was `WORKSHOP_ROUTES`): [{ id, label, path, children }],
+ *              where a child may carry `links: { live, repo }`.
+ *   basePath — mount point of the workshop (drives route matching + hrefs).
+ */
+
+const WorkshopDefaultSidebar = ({ routes = [], basePath = '/workshop' }) => {
+  const location = useLocation()
+  const stripped = location.pathname.startsWith(basePath)
+    ? location.pathname.slice(basePath.length).replace(/^\//, '')
+    : location.pathname
+  const firstSegment = stripped.split('/')[0]
+
+  const parentRoute = routes.find(r => r.path === firstSegment)
+  const siblings = parentRoute?.children || []
+  const currentChild = siblings.find(c => `${basePath}/${c.path}` === location.pathname)
+  const links = currentChild?.links
+
+  return (
+    <div className="space-y-4">
+      {siblings.length > 1 && (
+        <div>
+          <div className="shell-sidebar-label">{parentRoute.label}</div>
+          <nav className="space-y-0">
+            {siblings.map(child => (
+              <Link
+                key={child.id}
+                to={`${basePath}/${child.path}`}
+                className={`shell-sidebar-link block ${
+                  location.pathname === `${basePath}/${child.path}` ? 'active' : ''
+                }`}
+              >
+                {child.label}
+              </Link>
+            ))}
+          </nav>
+        </div>
+      )}
+
+      {links && (
+        <div>
+          <div className="shell-sidebar-label">Repository</div>
+          <div className="space-y-1">
+            {links.live && (
+              <a href={links.live} target="_blank" rel="noopener noreferrer" className="shell-sidebar-action">
+                <Icon name="external-link" size={14} />
+                Live site
+              </a>
+            )}
+            {links.repo && (
+              <a href={links.repo} target="_blank" rel="noopener noreferrer" className="shell-sidebar-action">
+                <Icon name="external-link" size={14} />
+                GitHub
+              </a>
+            )}
+          </div>
+        </div>
+      )}
+
+      <div>
+        <div className="shell-sidebar-label">Quick actions</div>
+        <div className="space-y-1">
+          <Link to={basePath} className="shell-sidebar-action">
+            <Icon name="layout" size={14} />
+            Workshop home
+          </Link>
+          <button
+            type="button"
+            className="shell-sidebar-action"
+            onClick={() => navigator.clipboard.writeText(window.location.pathname)}
+            title="Copy page path to clipboard"
+          >
+            <Icon name="copy" size={14} />
+            Copy path
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+export default WorkshopDefaultSidebar

package/src/compositions/WorkshopSidebar.jsx

@@ -0,0 +1,180 @@
+import { useEffect, useMemo, useState } from 'react'
+import { Link, useLocation } from 'react-router-dom'
+import { ShellSidebar } from '../shell'
+import { Icon } from '@kolkrabbi/kol-component'
+import {
+  extractDocNumber,
+  cleanTitle,
+  categoryLabels,
+  groupDocsByMajor,
+} from '../engine'
+
+/**
+ * WorkshopSidebar — EXAMPLE composition. This is the app-specific glue that
+ * wires the KOL shell + docs engine into a product's primary navigation.
+ * Consumers copy this file and adapt it; it is intentionally decoupled from
+ * any app singleton via props:
+ *
+ *   routes    — nav tree (was `WORKSHOP_ROUTES`): [{ id, label, path, children }]
+ *   inventory — parsed docs (was `documentationInventory`): [{ id, title, ... }]
+ *   basePath  — mount point of the workshop (drives active-route detection)
+ *   docHref   — builds a doc URL: docHref(id) → doc page; docHref() → docs index.
+ *               Assumes docs are mounted under `${basePath}/docs/`.
+ */
+
+const DocsSidebar = ({ inventory = [], docHref, basePath, onNavigate, collapsed, onToggle }) => {
+  const location = useLocation()
+  const activeDocId = useMemo(() => {
+    const prefix = `${basePath}/docs/`
+    if (!location.pathname.startsWith(prefix)) return null
+    const rest = location.pathname.slice(prefix.length)
+    return rest.length > 0 ? rest : null
+  }, [location.pathname, basePath])
+
+  const groupedDocs = useMemo(() => groupDocsByMajor(inventory), [inventory])
+
+  const [collapsedGroups, setCollapsedGroups] = useState(() => {
+    const initialState = {}
+    Object.keys(groupedDocs).forEach((major) => {
+      initialState[major] = true
+    })
+    return initialState
+  })
+
+  // Auto-expand the group containing the active doc
+  useEffect(() => {
+    if (!activeDocId) return
+    for (const [major, docs] of Object.entries(groupedDocs)) {
+      if (docs.some(d => d.id === activeDocId)) {
+        setCollapsedGroups(prev => ({ ...prev, [major]: false }))
+        break
+      }
+    }
+  }, [activeDocId, groupedDocs])
+
+  const toggleGroup = (major) => {
+    setCollapsedGroups(prev => ({
+      ...prev,
+      [major]: !prev[major]
+    }))
+  }
+
+  return (
+    <div className="space-y-4">
+      <div className="shell-sidebar-toggle shell-sidebar-label" style={{ justifyContent: 'space-between', paddingRight: '4px' }}>
+        <Link to={docHref()} className="shell-sidebar-label" onClick={(e) => {
+          if (collapsed && onToggle) onToggle()
+          if (onNavigate) onNavigate(e)
+        }}>
+          Documentation
+        </Link>
+        <button
+          type="button"
+          onClick={onToggle}
+          aria-label={collapsed ? 'Expand Documentation' : 'Collapse Documentation'}
+          className="flex items-center justify-center"
+          style={{ height: '16.5px', marginBottom: '8px' }}
+        >
+          <Icon
+            name="chevron-down"
+            size={10}
+            className={`stroke-[2.5] transition-transform ${collapsed ? '' : 'rotate-180'}`}
+          />
+        </button>
+      </div>
+
+      {!collapsed && <div className="space-y-4">
+        {Object.entries(groupedDocs)
+          .sort(([a], [b]) => a.localeCompare(b))
+          .map(([major, docs]) => {
+            const isCollapsed = collapsedGroups[major]
+            return (
+              <div key={major} className="shell-nav-group">
+                <button
+                  type="button"
+                  className="shell-nav-group-header w-full text-left"
+                  onClick={() => toggleGroup(major)}
+                >
+                  <span className="flex items-center gap-2">
+                    <Icon
+                      name="chevron-right"
+                      size={12}
+                      className={`h-3 w-3 transition-transform ${isCollapsed ? '' : 'rotate-90'}`}
+                    />
+                    {categoryLabels[major] || 'Other'}
+                  </span>
+                  <span className="shell-nav-group-count">({docs.length})</span>
+                </button>
+                {!isCollapsed && (
+                  <div className="shell-nav-items">
+                    {docs.map((d) => {
+                      const isActive = d.id === activeDocId
+                      return (
+                        <Link
+                          key={d.id}
+                          to={docHref(d.id)}
+                          className={`shell-nav-item shell-nav-item-doc ${isActive ? 'active' : ''}`}
+                          onClick={onNavigate}
+                        >
+                          <span className="shell-nav-item-title">{cleanTitle(d.title, d.id)}</span>
+                          <span className="shell-nav-item-id">{extractDocNumber(d.id)}</span>
+                        </Link>
+                      )
+                    })}
+                  </div>
+                )}
+              </div>
+            )
+          })}
+      </div>}
+    </div>
+  )
+}
+
+const WorkshopSidebar = ({
+  routes = [],
+  inventory = [],
+  basePath = '/workshop',
+  docHref = (id) => (id ? `${basePath}/docs/${id}` : `${basePath}/docs`),
+  onNavigate,
+}) => {
+  const location = useLocation()
+  const [workshopCollapsed, setWorkshopCollapsed] = useState(false)
+  const [docsCollapsed, setDocsCollapsed] = useState(true)
+
+  // Auto-expand Documentation section when on a docs route
+  useEffect(() => {
+    if (location.pathname.startsWith(`${basePath}/docs`)) {
+      setDocsCollapsed(false)
+    }
+  }, [location.pathname, basePath])
+
+  const workshopRoutes = useMemo(
+    () => routes.filter(r => r.id !== 'docs'),
+    [routes]
+  )
+
+  return (
+    <div className="space-y-6">
+      <ShellSidebar
+        routes={workshopRoutes}
+        basePath={basePath}
+        onNavigate={onNavigate}
+        label="Workshop"
+        labelTo={basePath}
+        collapsed={workshopCollapsed}
+        onToggle={() => setWorkshopCollapsed(p => !p)}
+      />
+      <DocsSidebar
+        inventory={inventory}
+        docHref={docHref}
+        basePath={basePath}
+        onNavigate={onNavigate}
+        collapsed={docsCollapsed}
+        onToggle={() => setDocsCollapsed(p => !p)}
+      />
+    </div>
+  )
+}
+
+export default WorkshopSidebar

package/src/compositions/index.js

@@ -0,0 +1,8 @@
+/**
+ * Example compositions — the app-specific glue that wires the KOL shell + docs
+ * engine into a product's navigation. These are reference implementations meant
+ * to be copied and adapted; they take app data (routes, inventory) and href
+ * helpers (basePath, docHref) as props rather than importing any singleton.
+ */
+export { default as WorkshopSidebar } from './WorkshopSidebar.jsx'
+export { default as WorkshopDefaultSidebar } from './WorkshopDefaultSidebar.jsx'

package/src/docs/DocsArticle.jsx

@@ -0,0 +1,7 @@
+const join = (...classes) => classes.filter(Boolean).join(' ')
+
+const DocsArticle = ({ children, className }) => (
+  <article className={join('docs-article', className)}>{children}</article>
+)
+
+export default DocsArticle

package/src/docs/DocsFrontmatter.jsx

@@ -0,0 +1,74 @@
+import { Icon, Tag } from '@kolkrabbi/kol-component'
+import { getTagColor } from '../engine'
+import { useTagMode } from '../tags'
+
+const FIELD_ICONS = {
+  file: 'file',
+  title: null,
+  version: 'hash-01',
+  date: null,
+  status: 'check',
+  'content-type': null,
+  category: 'folder',
+  tags: null,
+  modified: null
+}
+
+const FIELD_ORDER = ['title', 'category', 'date', 'tags', 'modified']
+
+const formatDate = (dateStr) => {
+  if (!dateStr) return null
+  const d = new Date(dateStr)
+  if (isNaN(d)) return dateStr
+  return d.toLocaleDateString('en-GB', { day: '2-digit', month: '2-digit', year: 'numeric' }).replace(/\//g, '.')
+}
+
+const DocsFrontmatter = ({ metadata, docId }) => {
+  const { openTagMode } = useTagMode()
+  if (!metadata || Object.keys(metadata).length === 0) return null
+
+  const fields = FIELD_ORDER.filter(key => metadata[key] != null && metadata[key] !== '')
+
+  if (fields.length === 0) return null
+
+  return (
+    <div className="docs-frontmatter">
+      <p className="shell-sidebar-label">Frontmatter</p>
+      {fields.map((key) => {
+        const value = metadata[key]
+        const icon = FIELD_ICONS[key]
+
+        return (
+          <div key={key} className="docs-frontmatter-row">
+            <span className="docs-frontmatter-key">
+              {icon && <Icon name={icon} size={14} />}
+              {key}
+            </span>
+            <span className="docs-frontmatter-value">
+              {key === 'tags' && Array.isArray(value) ? (
+                <span className="flex flex-wrap gap-1.5">
+                  {value.map((tag) => (
+                    <Tag
+                      key={tag}
+                      size="sm"
+                      color={getTagColor(tag)}
+                      onClick={() => openTagMode(tag)}
+                    >
+                      {tag}
+                    </Tag>
+                  ))}
+                </span>
+              ) : key === 'date' || key === 'modified' ? (
+                formatDate(String(value))
+              ) : (
+                String(value)
+              )}
+            </span>
+          </div>
+        )
+      })}
+    </div>
+  )
+}
+
+export default DocsFrontmatter

package/src/docs/DocsHeader.jsx

@@ -0,0 +1,19 @@
+const join = (...classes) => classes.filter(Boolean).join(' ')
+
+const DocsHeader = ({ title, subtitle, meta = [], className }) => (
+  <header className={join('docs-header', className)}>
+    {title ? <h1 className="docs-title">{title}</h1> : null}
+    {subtitle ? <p className="docs-subtitle">{subtitle}</p> : null}
+    {Array.isArray(meta) && meta.length > 0 ? (
+      <div className="docs-meta">
+        {meta.map(({ label, value }) => (
+          <span key={label}>
+            <strong>{label}</strong> {value}
+          </span>
+        ))}
+      </div>
+    ) : null}
+  </header>
+)
+
+export default DocsHeader