@kolkrabbi/kol-workshop 0.1.11 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.1.11",
+  "version": "0.2.0",
   "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",
@@ -13,11 +13,11 @@
   },
   "dependencies": {
     "d3": "^7.9.0",
+    "@kolkrabbi/kol-component": "0.12.19",
     "@kolkrabbi/kol-brand": "^0.1.2",
-    "@kolkrabbi/kol-icons": "0.8.4",
-    "@kolkrabbi/kol-component": "0.12.5",
-    "@kolkrabbi/kol-framework": "0.5.8",
-    "@kolkrabbi/kol-theme": "0.11.21"
+    "@kolkrabbi/kol-icons": "0.8.10",
+    "@kolkrabbi/kol-framework": "0.6.2",
+    "@kolkrabbi/kol-theme": "0.12.0"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",

package/src/compositions/WorkshopSidebar.jsx

@@ -1,7 +1,7 @@
 import { useEffect, useMemo, useState } from 'react'
 import { Link, useLocation } from 'react-router-dom'
 import { ShellSidebar } from '../shell'
-import { Icon } from '@kolkrabbi/kol-component'
+import { Icon, Tooltip } from '@kolkrabbi/kol-component'
 import {
   extractDocNumber,
   cleanTitle,
@@ -69,19 +69,22 @@ const DocsSidebar = ({ inventory = [], docHref, basePath, onNavigate, collapsed,
         }}>
           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>
+        <Tooltip label={collapsed ? 'Expand Documentation' : 'Collapse Documentation'}>
+          <button
+            type="button"
+            onClick={onToggle}
+            aria-label={collapsed ? 'Expand Documentation' : 'Collapse Documentation'}
+            aria-expanded={!collapsed}
+            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>
+        </Tooltip>
       </div>
 
       {!collapsed && <div className="space-y-4">

package/src/docs/DocumentationReader.jsx

@@ -211,7 +211,11 @@ const DocumentationReader = ({
     return h1Block?.content || null
   }, [introBlocks])
 
+  /* 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. */
   useEffect(() => {
+    if (!setTocContent) return undefined
     setTocContent(
       <DocReaderSidebar
         key={docId}

package/src/engine/doc-helpers.js

@@ -93,18 +93,30 @@ export const getTagColor = (tag) => {
   return TAG_COLORS[Math.abs(hash) % TAG_COLORS.length]
 }
 
-/** Group docs by major version number. */
+/** 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]+-index$/)
+    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) {

package/src/shell/ShellLayout.jsx

@@ -1,9 +1,9 @@
 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'
+import { Button, ShellDrawer, ShellSearchOverlay, Tooltip } from '@kolkrabbi/kol-component'
+import { matchSearchItems } from '../engine/search.js'
 import { Asset } from '@kolkrabbi/kol-brand/svg'
 
 // Pages can register right-rail TOC content via this context.
@@ -22,13 +22,14 @@ export const ShellFullHeightContext = createContext(null)
 export const ShellTocCollapsedContext = createContext(null)
 
 const NavColumn = ({ children }) => (
-  <aside className="shell-sidebar-sticky hidden lg:block shrink-0 h-full min-h-0 overflow-y-auto overscroll-none pt-6 md:pt-6 lg:pt-8 pb-8">
+  <aside aria-label="Navigation" className="shell-sidebar-sticky hidden lg:block shrink-0 h-full min-h-0 overflow-y-auto overscroll-none pt-6 md:pt-6 lg:pt-8 pb-8">
     {children}
   </aside>
 )
 
 const MainColumn = ({ children, fullHeight }) => (
   <main
+    id="main"
     className={`w-full min-w-0 h-full min-h-0 ${fullHeight ? 'overflow-hidden flex flex-col' : 'overflow-y-auto overscroll-none'}`}
     style={fullHeight ? undefined : { scrollbarGutter: 'stable' }}
   >
@@ -40,7 +41,7 @@ const MainColumn = ({ children, fullHeight }) => (
 )
 
 const TocColumn = ({ children }) => (
-  <aside className="shell-sidebar-sticky hidden lg:block shrink-0 h-full min-h-0 overflow-y-auto overscroll-none pt-6 md:pt-6 lg:pt-8 pb-8">
+  <aside aria-label="Table of contents" className="shell-sidebar-sticky hidden lg:block shrink-0 h-full min-h-0 overflow-y-auto overscroll-none pt-6 md:pt-6 lg:pt-8 pb-8">
     {children}
   </aside>
 )
@@ -50,6 +51,7 @@ const ShellLayout = ({ routes = [], basePath = '/', brandLogoSrc, brandLogoAlt =
   const [navCollapsed, setNavCollapsed] = useState(false)
   const [tocCollapsed, setTocCollapsed] = useState(false)
   const [isSearchOpen, setIsSearchOpen] = useState(false)
+  const [searchQuery, setSearchQuery] = useState('')
   const [tocContent, setTocContent] = useState(null)
   const [isFullHeight, setIsFullHeight] = useState(false)
   const location = useLocation()
@@ -105,25 +107,34 @@ const ShellLayout = ({ routes = [], basePath = '/', brandLogoSrc, brandLogoAlt =
     </Link>
   ) : (
     // Two separate wordmarks: KOLKRABBI holds the logo slot (reserves the 256px
-    // nav column at lg+), WORKSHOP falls at the content-column edge. Both h-6.
+    // nav column at lg+) and links to the SITE home; WORKSHOP falls at the
+    // content-column edge and links to the shell root. Both h-6.
     <>
-      <Link to={basePath} className="shell-header-logo hidden md:flex shrink-0 items-center text-emphasis lg:w-64">
+      <Link to="/" className="shell-header-logo hidden md:flex shrink-0 items-center text-emphasis lg:w-64">
         <Asset name="kol-wordmark" title="Kolkrabbi" className="inline-flex [&>svg]:h-6 [&>svg]:w-auto" />
       </Link>
-      <Asset name="wordmark-workshop" title="Workshop" className="inline-flex text-emphasis [&>svg]:h-6 [&>svg]:w-auto" />
+      <Link to={basePath} className="shell-header-logo flex items-center text-emphasis">
+        <Asset name="wordmark-workshop" title="Workshop" className="inline-flex [&>svg]:h-6 [&>svg]:w-auto" />
+      </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>
+    <Tooltip label="Search">
+      <Button variant="ghost" quiet iconOnly="search" iconSize={18} onClick={() => setIsSearchOpen(true)} aria-label="Search" />
+    </Tooltip>
   )
 
+  /* searchItems ({ id, label, href, sectionLabel?, tags?, headings?, keywords? })
+   * → the overlay's row shape ({ id, label, group?, hint? }), matched by the
+   * engine. hint surfaces WHY a row matched when the label didn't. */
+  const searchResults = matchSearchItems(searchItems ?? [], searchQuery).map((item, i) => ({
+    id: item.id ?? item.href ?? `${item.label}-${i}`,
+    label: item.label,
+    group: item.sectionLabel ?? item.group,
+    hint: item.matchedHeading ?? item.matchedKeyword ?? item.hint,
+    href: item.href,
+  }))
+
   return (
     <ShellTocContext.Provider value={setTocContent}>
       <ShellFullHeightContext.Provider value={setIsFullHeight}>
@@ -137,8 +148,12 @@ const ShellLayout = ({ routes = [], basePath = '/', brandLogoSrc, brandLogoAlt =
             actions={searchTrigger}
             onMenuClick={() => {
               if (window.matchMedia('(min-width: 1024px)').matches) {
-                setNavCollapsed((p) => !p)
-                setTocCollapsed((p) => !p)
+                /* Both rails to ONE target state — independent `!p` flips made
+                 * them oppose each other once the dock buttons had diverged
+                 * them. Collapse if anything is open, else reopen both. */
+                const collapse = !navCollapsed || !tocCollapsed
+                setNavCollapsed(collapse)
+                setTocCollapsed(collapse)
               } else {
                 setIsNavDrawerOpen(true)
               }
@@ -178,8 +193,10 @@ const ShellLayout = ({ routes = [], basePath = '/', brandLogoSrc, brandLogoAlt =
               </div>
             </div>
 
+          {/* `open`, not `isOpen` — the old prop name silently kept the drawer
+            * shut, so there was no navigation at all below lg. */}
           <ShellDrawer
-            isOpen={isNavDrawerOpen}
+            open={isNavDrawerOpen}
             onClose={() => setIsNavDrawerOpen(false)}
           >
             {renderSidebar
@@ -188,12 +205,22 @@ const ShellLayout = ({ routes = [], basePath = '/', brandLogoSrc, brandLogoAlt =
             }
           </ShellDrawer>
 
+          {/* The overlay owns no filtering — the shell holds the query and
+            * feeds it results (the pre-0.12 API `isOpen/routes/items` matched
+            * nothing, so ⌘K rendered an empty box and searchItems was dead).
+            * Selecting routes to item.href; matchSearchItems is the engine's. */}
           <ShellSearchOverlay
-            isOpen={isSearchOpen}
-            onClose={() => setIsSearchOpen(false)}
-            routes={routes}
-            basePath={basePath}
-            items={searchItems}
+            open={isSearchOpen}
+            onClose={() => { setIsSearchOpen(false); setSearchQuery('') }}
+            query={searchQuery}
+            onQueryChange={setSearchQuery}
+            results={searchResults}
+            onSelect={(item) => {
+              setIsSearchOpen(false)
+              setSearchQuery('')
+              if (item?.href) navigate(item.href)
+            }}
+            placeholder="Search…"
           />
         </div>
         </ShellTocCollapsedContext.Provider>

package/src/shell/ShellSidebar.jsx

@@ -1,6 +1,6 @@
 import { useState, useEffect } from 'react'
 import { NavLink, Link, useLocation } from 'react-router-dom'
-import { Icon } from '@kolkrabbi/kol-component'
+import { Icon, Tooltip } from '@kolkrabbi/kol-component'
 
 const getSectionRootPath = (route, basePath) => {
   if (route.path !== undefined && route.path !== null) {
@@ -77,19 +77,22 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
         ) : (
           <button type="button" className="kol-helper-10 text-meta" 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>
+        <Tooltip label={navCollapsed ? `Expand ${label}` : `Collapse ${label}`}>
+          <button
+            type="button"
+            onClick={handleToggle}
+            aria-label={navCollapsed ? `Expand ${label}` : `Collapse ${label}`}
+            aria-expanded={!navCollapsed}
+            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>
+        </Tooltip>
       </div>
 
       {!navCollapsed && <div className="space-y-4">

package/src/tags/TagModeOverlay.jsx

@@ -1,6 +1,6 @@
 import { useMemo, useState } from 'react'
 import { Link } from 'react-router-dom'
-import { Input, Tag, Button } from '@kolkrabbi/kol-component'
+import { Input, Tag, Button, Tooltip } from '@kolkrabbi/kol-component'
 import { useTagMode } from './TagModeContext.jsx'
 import TagGraph from './TagGraph.jsx'
 import { extractDocNumber, cleanTitle, getTagColor } from '../engine/index.js'
@@ -37,29 +37,34 @@ const TagModeOverlay = () => {
       <div className="max-w-[864px] mx-auto">
         <div className="flex items-center justify-start gap-1 mb-3">
           {hasFilters && (
+            <Tooltip label={viewMode === 'graph' ? 'List view' : 'Graph view'}>
+              <Button
+                variant="outline"
+                quiet
+                size="sm"
+                iconOnly={viewMode === 'graph' ? 'view-list' : 'polygon'}
+                onClick={() => setViewMode(viewMode === 'graph' ? 'list' : 'graph')}
+                aria-label={viewMode === 'graph' ? 'List view' : 'Graph view'}
+              />
+            </Tooltip>
+          )}
+          <Tooltip label="Close tag mode">
             <Button
               variant="outline"
               quiet
               size="sm"
-              iconOnly={viewMode === 'graph' ? 'view-list' : 'polygon'}
-              onClick={() => setViewMode(viewMode === 'graph' ? 'list' : 'graph')}
-              aria-label={viewMode === 'graph' ? 'List view' : 'Graph view'}
+              iconOnly="x"
+              onClick={closeTagMode}
+              aria-label="Close tag mode"
             />
-          )}
-          <Button
-            variant="outline"
-            quiet
-            size="sm"
-            iconOnly="x"
-            onClick={closeTagMode}
-            aria-label="Close tag mode"
-          />
+          </Tooltip>
         </div>
 
         <div className="dash-card flex flex-col gap-8 -mt-4">
           <div className="flex items-center gap-2" style={{ width: '100%', alignSelf: 'stretch' }}>
             <Input
               type="text"
+              aria-label="Search tags"
               placeholder="Search tags…"
               value={search}
               onChange={(e) => setSearch(e.target.value)}
@@ -75,14 +80,16 @@ const TagModeOverlay = () => {
               autoFocus
             />
             {search && (
-              <Button
-                variant="outline"
-                quiet
-                size="sm"
-                iconOnly="x"
-                onClick={() => setSearch('')}
-                aria-label="Clear search"
-              />
+              <Tooltip label="Clear search">
+                <Button
+                  variant="outline"
+                  quiet
+                  size="sm"
+                  iconOnly="x"
+                  onClick={() => setSearch('')}
+                  aria-label="Clear search"
+                />
+              </Tooltip>
             )}
           </div>