@kolkrabbi/kol-workshop 0.1.0

package/src/shell/ShellLayout.jsx

@@ -0,0 +1,197 @@
+import { createContext, useState, useEffect, Suspense } from 'react'
+import { Outlet, Link, useLocation, useNavigate } from 'react-router-dom'
+import { Icon } from '@kolkrabbi/kol-icons'
+import { ShellHeader } from '@kolkrabbi/kol-framework'
+import ShellSidebar from './ShellSidebar.jsx'
+import { ShellDrawer, ShellSearchOverlay } from '@kolkrabbi/kol-component'
+
+// Pages can register right-rail TOC content via this context.
+// Usage: const setTocContent = useContext(ShellTocContext)
+// useLayoutEffect(() => { setTocContent(<MyToc />) ; return () => setTocContent(null) }, [])
+export const ShellTocContext = createContext(null)
+
+// Pages that need to fill the viewport (e.g. iframe embeds) can opt into full-height mode.
+// Usage: const setFullHeight = useContext(ShellFullHeightContext)
+// useLayoutEffect(() => { setFullHeight(true) ; return () => setFullHeight(false) }, [setFullHeight])
+export const ShellFullHeightContext = createContext(null)
+
+// Pages can request the right sidebar to start collapsed.
+// Usage: const setTocCollapsed = useContext(ShellTocCollapsedContext)
+// useLayoutEffect(() => { setTocCollapsed(true) ; return () => setTocCollapsed(false) }, [setTocCollapsed])
+export const ShellTocCollapsedContext = createContext(null)
+
+const NavColumn = ({ children }) => (
+  <aside className="hidden lg:block shrink-0 pt-6 md:pt-6 lg:pt-8">
+    <div className="shell-sidebar-sticky sticky top-8 max-h-[calc(100vh-8rem)] overflow-y-auto">
+      {children}
+    </div>
+  </aside>
+)
+
+const MainColumn = ({ children, fullHeight }) => (
+  <main className={`w-full min-w-0${fullHeight ? ' h-full flex flex-col' : ''}`}>
+    {fullHeight
+      ? children
+      : <div className="pt-6 md:pt-6 lg:pt-8 pb-8">{children}</div>
+    }
+  </main>
+)
+
+const TocColumn = ({ children }) => (
+  <aside className="hidden lg:block shrink-0 pt-6 md:pt-6 lg:pt-8">
+    <div className="sticky top-8 max-h-[calc(100vh-8rem)] overflow-y-auto">
+      {children}
+    </div>
+  </aside>
+)
+
+const ShellLayout = ({ routes = [], basePath = '/', brandLogoSrc, brandLogoAlt = '', renderSidebar, searchItems, defaultTocContent }) => {
+  const [isNavDrawerOpen, setIsNavDrawerOpen] = useState(false)
+  const [navCollapsed, setNavCollapsed] = useState(false)
+  const [tocCollapsed, setTocCollapsed] = useState(false)
+  const [isSearchOpen, setIsSearchOpen] = useState(false)
+  const [tocContent, setTocContent] = useState(null)
+  const [isFullHeight, setIsFullHeight] = useState(false)
+  const location = useLocation()
+  const navigate = useNavigate()
+
+  useEffect(() => {
+    const handleKeyDown = (e) => {
+      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
+        e.preventDefault()
+        setIsSearchOpen(true)
+      } else if ((e.altKey) && e.key === 'b') {
+        e.preventDefault()
+        setIsSearchOpen(true)
+      }
+    }
+    window.addEventListener('keydown', handleKeyDown)
+    return () => window.removeEventListener('keydown', handleKeyDown)
+  }, [])
+
+  const effectiveTocContent = tocContent ?? defaultTocContent
+  const hasToc = Boolean(effectiveTocContent)
+  const showNav = !navCollapsed
+  const showToc = hasToc && !tocCollapsed
+
+  const layoutType = showNav && showToc ? 'nav-toc' : showNav ? 'nav' : showToc ? 'toc' : 'none'
+
+  const gridCols = showNav
+    ? showToc
+      ? 'lg:grid-cols-[256px_minmax(0,1fr)] xl:grid-cols-[256px_minmax(0,1fr)_224px]'
+      : 'lg:grid-cols-[256px_minmax(0,1fr)]'
+    : showToc
+      ? 'xl:grid-cols-[minmax(0,1fr)_224px]'
+      : ''
+
+  // Adapt the old flat `routes` + callbacks to the DS ShellHeader API
+  // (brand node · nav[{label,href,icon}] · isActive · onNavigate · actions slot).
+  const joinPath = (p) => `${basePath.replace(/\/$/, '')}/${String(p ?? '').replace(/^\//, '')}`
+  const navItems = routes.map((r) => ({
+    label: r.label,
+    href: r.path ? joinPath(r.path) : basePath,
+    icon: r.icon,
+  }))
+  const isActive = (href) => location.pathname === href || location.pathname.startsWith(`${href}/`)
+  const handleNavigate = (event, item) => {
+    if (item.href) {
+      event.preventDefault()
+      navigate(item.href)
+    }
+  }
+  const brand = (
+    <Link to={basePath} className="shell-header-logo flex items-center gap-2">
+      {brandLogoSrc
+        ? <img src={brandLogoSrc} alt={brandLogoAlt} className="h-6 w-auto" />
+        : <span className="kol-helper-12 text-emphasis">{brandLogoAlt || 'Workshop'}</span>}
+    </Link>
+  )
+  const searchTrigger = (
+    <button
+      type="button"
+      onClick={() => setIsSearchOpen(true)}
+      aria-label="Search"
+      className="flex h-9 w-9 items-center justify-center rounded p-0 bg-transparent border-0 cursor-pointer transition-colors text-fg-64 hover:bg-fg-08 hover:text-emphasis"
+    >
+      <Icon name="search" size={18} />
+    </button>
+  )
+
+  return (
+    <ShellTocContext.Provider value={setTocContent}>
+      <ShellFullHeightContext.Provider value={setIsFullHeight}>
+        <ShellTocCollapsedContext.Provider value={setTocCollapsed}>
+        <div className="fixed inset-0 flex flex-col bg-surface-primary text-auto">
+          <ShellHeader
+            brand={brand}
+            nav={navItems}
+            isActive={isActive}
+            onNavigate={handleNavigate}
+            actions={searchTrigger}
+            onMenuClick={() => {
+              if (window.matchMedia('(min-width: 1024px)').matches) {
+                setNavCollapsed((p) => !p)
+                setTocCollapsed((p) => !p)
+              } else {
+                setIsNavDrawerOpen(true)
+              }
+            }}
+            onNavToggle={() => setNavCollapsed((p) => !p)}
+            onTocToggle={hasToc ? () => setTocCollapsed((p) => !p) : null}
+            navCollapsed={navCollapsed}
+            tocCollapsed={tocCollapsed}
+          />
+
+          <div className="flex-1 overflow-hidden">
+            <div className={`h-full ${isFullHeight ? 'overflow-hidden' : 'overflow-y-auto'}`} style={{ scrollbarGutter: 'stable' }}>
+              <div className={`w-full px-4 md:px-5 lg:px-6${isFullHeight ? ' h-full' : ' pb-16'}`}>
+                <div className={`shell-content-grid grid gap-8 ${gridCols}${isFullHeight ? ' h-full' : ''}`} data-layout={layoutType}>
+                  {showNav && (
+                    <NavColumn>
+                      {renderSidebar ? renderSidebar({}) : <ShellSidebar routes={routes} basePath={basePath} />}
+                    </NavColumn>
+                  )}
+
+                  <MainColumn fullHeight={isFullHeight}>
+                    <div className={isFullHeight ? 'flex flex-col flex-1 min-h-0 [&>*]:flex-1 [&>*]:flex [&>*]:flex-col [&>*]:min-h-0' : ''}>
+                      <Suspense fallback={<div className="flex items-center justify-center p-12 text-fg-48">Loading…</div>}>
+                        <Outlet />
+                      </Suspense>
+                    </div>
+                  </MainColumn>
+
+                  {showToc && (
+                    <TocColumn>
+                      {effectiveTocContent}
+                    </TocColumn>
+                  )}
+                </div>
+              </div>
+            </div>
+          </div>
+
+          <ShellDrawer
+            isOpen={isNavDrawerOpen}
+            onClose={() => setIsNavDrawerOpen(false)}
+          >
+            {renderSidebar
+              ? renderSidebar({ onNavigate: () => setIsNavDrawerOpen(false) })
+              : <ShellSidebar routes={routes} basePath={basePath} onNavigate={() => setIsNavDrawerOpen(false)} />
+            }
+          </ShellDrawer>
+
+          <ShellSearchOverlay
+            isOpen={isSearchOpen}
+            onClose={() => setIsSearchOpen(false)}
+            routes={routes}
+            basePath={basePath}
+            items={searchItems}
+          />
+        </div>
+        </ShellTocCollapsedContext.Provider>
+      </ShellFullHeightContext.Provider>
+    </ShellTocContext.Provider>
+  )
+}
+
+export default ShellLayout

package/src/shell/ShellSidebar.jsx

@@ -0,0 +1,146 @@
+import { useState, useEffect } from 'react'
+import { NavLink, Link, useLocation } from 'react-router-dom'
+import { Icon } from '@kolkrabbi/kol-component'
+
+const getSectionRootPath = (route, basePath) => {
+  if (route.path !== undefined && route.path !== null) {
+    const p = route.path
+    if (!p) return basePath
+    return p.startsWith('/') ? p : `${basePath}/${p}`
+  }
+  if (route.children?.length > 0) {
+    const cp = route.children[0].path
+    if (!cp) return basePath
+    return cp.startsWith('/') ? cp : `${basePath}/${cp}`
+  }
+  return basePath
+}
+
+const getChildPath = (child, basePath) => {
+  const p = child.path
+  if (p === undefined || p === null || p === '') return basePath
+  return p.startsWith('/') ? p : `${basePath}/${p}`
+}
+
+const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Navigation', labelTo, collapsed, onToggle }) => {
+  const location = useLocation()
+  const normalizedPath = location.pathname.replace(/\/$/, '')
+
+  // Controlled mode: collapsed + onToggle from parent
+  // Uncontrolled mode: internal state
+  const [internalCollapsed, setInternalCollapsed] = useState(false)
+  const isControlled = collapsed !== undefined
+  const navCollapsed = isControlled ? collapsed : internalCollapsed
+  const handleToggle = isControlled ? onToggle : () => setInternalCollapsed(prev => !prev)
+
+  const [collapsedSections, setCollapsedSections] = useState(() => {
+    const initial = {}
+    routes.forEach((route) => {
+      const sectionPath = getSectionRootPath(route, basePath)
+      const isActive =
+        sectionPath === basePath
+          ? normalizedPath === basePath
+          : normalizedPath === sectionPath || normalizedPath.startsWith(sectionPath + '/')
+      initial[route.id] = !isActive
+    })
+    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 }))
+      }
+    })
+  }, [normalizedPath, routes, basePath])
+
+  const handleSectionClick = (route) => {
+    setCollapsedSections((prev) => ({ ...prev, [route.id]: !prev[route.id] }))
+  }
+
+  return (
+    <div className="space-y-4">
+      <div className="shell-sidebar-toggle shell-sidebar-label" style={{ justifyContent: 'space-between', paddingRight: '4px' }}>
+        {labelTo ? (
+          <Link to={labelTo} className="shell-sidebar-label" onClick={(e) => {
+            if (navCollapsed && handleToggle) handleToggle()
+            if (onNavigate) onNavigate(e)
+          }}>
+            {label}
+          </Link>
+        ) : (
+          <button type="button" onClick={handleToggle}>{label}</button>
+        )}
+        <button
+          type="button"
+          onClick={handleToggle}
+          aria-label={navCollapsed ? `Expand ${label}` : `Collapse ${label}`}
+          className="flex items-center justify-center"
+          style={{ height: '16.5px', marginBottom: '8px' }}
+        >
+          <Icon
+            name="chevron-down"
+            size={10}
+            className={`stroke-[2.5] transition-transform ${navCollapsed ? '' : 'rotate-180'}`}
+          />
+        </button>
+      </div>
+
+      {!navCollapsed && <div className="space-y-4">
+        {routes.map((route) => {
+          const isExpanded = !collapsedSections[route.id]
+
+          return (
+            <div key={route.id} className="shell-nav-group">
+              <button
+                type="button"
+                className="shell-nav-group-header w-full text-left"
+                onClick={() => handleSectionClick(route)}
+              >
+                <span className="flex items-center gap-2">
+                  <Icon
+                    name="chevron-right"
+                    size={12}
+                    className={`transition-transform ${isExpanded ? 'rotate-90' : ''}`}
+                  />
+                  {route.label}
+                </span>
+                {route.children?.length > 0 && (
+                  <span className="shell-nav-group-count">({route.children.length})</span>
+                )}
+              </button>
+
+              {isExpanded && route.children?.length > 0 && (
+                <div className="shell-nav-items">
+                  {route.children.map((child) => {
+                    const childPath = getChildPath(child, basePath)
+                    return (
+                      <NavLink
+                        key={child.id}
+                        to={childPath}
+                        end
+                        className={({ isActive }) =>
+                          `shell-nav-item${isActive ? ' active' : ''}`
+                        }
+                        onClick={onNavigate}
+                      >
+                        <span className="shell-nav-item-title">{child.label}</span>
+                      </NavLink>
+                    )
+                  })}
+                </div>
+              )}
+            </div>
+          )
+        })}
+      </div>}
+    </div>
+  )
+}
+
+export default ShellSidebar

package/src/shell/index.js

@@ -0,0 +1,11 @@
+/**
+ * @kolkrabbi/kol-workshop — shell.
+ *
+ * The docs-system shell: two-row header, collapsible nav sidebar, mobile
+ * drawer, and the layout shell that wires them to react-router. ShellLayout
+ * owns the TOC / full-height / TOC-collapsed contexts that pages register
+ * against.
+ */
+export { default as ShellLayout } from './ShellLayout.jsx'
+export { ShellTocContext, ShellFullHeightContext, ShellTocCollapsedContext } from './ShellLayout.jsx'
+export { default as ShellSidebar } from './ShellSidebar.jsx'

package/src/tags/TagGraph.jsx

@@ -0,0 +1,243 @@
+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'
+
+/**
+ * TagGraph - Obsidian-style tag graph
+ * All tags shown as interconnected nodes with force-directed layout
+ * Lines connect tags that share common docs
+ * Draggable nodes, click to navigate
+ *
+ * `tagHref(tag)` builds the navigation target when no `onTagClick` is provided
+ * (route-decoupled — no hardcoded workshop paths here).
+ */
+const defaultTagHref = (tag) => `/workshop/design-system/documentation?tag=${encodeURIComponent(tag)}`
+
+const TagGraph = ({ docs, activeTag, onTagClick, allDocs, tagHref = defaultTagHref }) => {
+  const svgRef = useRef(null)
+  const containerRef = useRef(null)
+  const navigate = useNavigate()
+  const [dimensions, setDimensions] = useState({ width: 300, height: 300 })
+  const [hoveredNode, setHoveredNode] = useState(null)
+
+  // Use allDocs if provided, otherwise fall back to docs
+  const sourceDocs = allDocs || docs
+
+  // Compute graph data: ALL tags with connections (pure — see engine/tags.js)
+  const graphData = useMemo(() => buildTagCooccurrence(sourceDocs), [sourceDocs])
+
+  // Update dimensions on resize
+  useEffect(() => {
+    const updateDimensions = () => {
+      if (containerRef.current) {
+        const { width } = containerRef.current.getBoundingClientRect()
+        const size = Math.max(250, width)
+        setDimensions({ width: size, height: size })
+      }
+    }
+    updateDimensions()
+    const resizeObserver = new ResizeObserver(updateDimensions)
+    if (containerRef.current) {
+      resizeObserver.observe(containerRef.current)
+    }
+    return () => resizeObserver.disconnect()
+  }, [])
+
+  // Render the force-directed graph
+  useEffect(() => {
+    if (!svgRef.current || graphData.nodes.length === 0) return
+
+    const { width, height } = dimensions
+
+    // Clear previous
+    const svg = d3.select(svgRef.current)
+    svg.selectAll('*').remove()
+
+    // Create container group
+    const g = svg.append('g')
+
+    // Create zoom behavior
+    const zoom = d3.zoom()
+      .scaleExtent([0.3, 3])
+      .on('zoom', (event) => {
+        g.attr('transform', event.transform)
+      })
+    svg.call(zoom)
+
+    // Prepare data with D3-friendly structure
+    const nodes = graphData.nodes.map(d => ({ ...d }))
+    const links = graphData.edges.map(d => ({ ...d }))
+
+    // Create force simulation
+    const simulation = d3.forceSimulation(nodes)
+      .force('link', d3.forceLink(links).id(d => d.id).distance(60).strength(0.5))
+      .force('charge', d3.forceManyBody().strength(-150))
+      .force('center', d3.forceCenter(width / 2, height / 2))
+      .force('collision', d3.forceCollide().radius(30))
+
+    // Draw edges
+    const link = g.append('g')
+      .attr('class', 'links')
+      .selectAll('line')
+      .data(links)
+      .enter()
+      .append('line')
+      .attr('stroke', d => {
+        // Highlight edges connected to active tag
+        if (activeTag && (d.source.id === activeTag || d.target.id === activeTag)) {
+          return 'var(--kol-accent-primary)'
+        }
+        return 'color-mix(in srgb, var(--kol-surface-on-primary) 20%, transparent)'
+      })
+      .attr('stroke-width', d => {
+        if (activeTag && (d.source.id === activeTag || d.target.id === activeTag)) {
+          return 2
+        }
+        return Math.min(2, d.weight * 0.5)
+      })
+      .attr('opacity', d => {
+        if (!activeTag) return 0.6
+        return (d.source.id === activeTag || d.target.id === activeTag) ? 1 : 0.2
+      })
+
+    // Draw nodes
+    const node = g.append('g')
+      .attr('class', 'nodes')
+      .selectAll('g')
+      .data(nodes)
+      .enter()
+      .append('g')
+      .attr('class', 'node')
+      .style('cursor', 'pointer')
+      .call(d3.drag()
+        .on('start', dragstarted)
+        .on('drag', dragged)
+        .on('end', dragended))
+
+    // Node circles
+    node.append('circle')
+      .attr('r', d => Math.max(8, Math.min(16, 6 + d.count * 2)))
+      .attr('fill', d => {
+        const colorMap = {
+          blue: '#3740D3',
+          teal: '#49a0a2',
+          green: '#66a44c',
+          yellow: '#ffe32e',
+          red: '#ce4646',
+          orange: '#db8000',
+          purple: '#9437FF',
+          dark: '#3a3a40'
+        }
+        return colorMap[getTagColor(d.id)] || '#49a0a2'
+      })
+      .attr('opacity', d => activeTag && d.id !== activeTag ? 0.4 : 0.9)
+      .attr('stroke', d => d.id === activeTag ? 'var(--kol-accent-primary)' : 'none')
+      .attr('stroke-width', d => d.id === activeTag ? 2 : 0)
+
+    // Node labels
+    node.append('text')
+      .text(d => `#${d.id}`)
+      .attr('dy', d => Math.max(8, Math.min(16, 6 + d.count * 2)) + 12)
+      .attr('text-anchor', 'middle')
+      .attr('fill', 'color-mix(in srgb, var(--kol-surface-on-primary) 64%, transparent)')
+      .attr('font-family', 'var(--kol-font-family-mono)')
+      .attr('font-size', '9px')
+      .attr('pointer-events', 'none')
+
+    // Node interactions
+    node
+      .on('click', (event, d) => {
+        event.stopPropagation()
+        if (onTagClick) {
+          onTagClick(d.id)
+        } else {
+          navigate(tagHref(d.id))
+        }
+      })
+      .on('mouseenter', (event, d) => {
+        setHoveredNode(d)
+        // Highlight connected edges
+        link
+          .attr('opacity', l => l.source.id === d.id || l.target.id === d.id ? 1 : 0.15)
+          .attr('stroke', l => l.source.id === d.id || l.target.id === d.id
+            ? 'var(--kol-accent-primary)'
+            : 'color-mix(in srgb, var(--kol-surface-on-primary) 20%, transparent)')
+      })
+      .on('mouseleave', () => {
+        setHoveredNode(null)
+        link
+          .attr('opacity', d => {
+            if (!activeTag) return 0.6
+            return (d.source.id === activeTag || d.target.id === activeTag) ? 1 : 0.2
+          })
+          .attr('stroke', d => {
+            if (activeTag && (d.source.id === activeTag || d.target.id === activeTag)) {
+              return 'var(--kol-accent-primary)'
+            }
+            return 'color-mix(in srgb, var(--kol-surface-on-primary) 20%, transparent)'
+          })
+      })
+
+    // Simulation tick
+    simulation.on('tick', () => {
+      link
+        .attr('x1', d => d.source.x)
+        .attr('y1', d => d.source.y)
+        .attr('x2', d => d.target.x)
+        .attr('y2', d => d.target.y)
+
+      node.attr('transform', d => `translate(${d.x}, ${d.y})`)
+    })
+
+    // Drag functions
+    function dragstarted(event, d) {
+      if (!event.active) simulation.alphaTarget(0.3).restart()
+      d.fx = d.x
+      d.fy = d.y
+    }
+
+    function dragged(event, d) {
+      d.fx = event.x
+      d.fy = event.y
+    }
+
+    function dragended(event, d) {
+      if (!event.active) simulation.alphaTarget(0)
+      d.fx = null
+      d.fy = null
+    }
+
+    // Cleanup
+    return () => {
+      simulation.stop()
+    }
+  }, [graphData, dimensions, activeTag, navigate, onTagClick, tagHref])
+
+  if (graphData.nodes.length === 0) {
+    return (
+      <div className="text-fg-48 kol-mono-xs py-4 px-2">
+        No tags found.
+      </div>
+    )
+  }
+
+  return (
+    <div ref={containerRef} className="tag-graph-sidebar">
+      <svg
+        ref={svgRef}
+        width={dimensions.width}
+        height={dimensions.height}
+        className="tag-graph-svg"
+      />
+      {hoveredNode && (
+        <div className="tag-graph-tooltip">
+          #{hoveredNode.id} ({hoveredNode.count} {hoveredNode.count === 1 ? 'doc' : 'docs'})
+        </div>
+      )}
+    </div>
+  )
+}
+
+export default TagGraph