@kolkrabbi/kol-workshop 0.29.0 → 0.30.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.29.0",
+  "version": "0.30.1",
   "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,22 +13,24 @@
   },
   "dependencies": {
     "d3": "^7.9.0",
+    "@kolkrabbi/kol-search": "^0.2.0",
+    "@kolkrabbi/kol-markdown": "^0.1.1",
     "@kolkrabbi/kol-brand": "^0.1.3"
   },
   "peerDependencies": {
-    "@kolkrabbi/kol-component": ">=0.68.1",
-    "@kolkrabbi/kol-framework": ">=0.23.0",
-    "@kolkrabbi/kol-theme": ">=0.51.0",
+    "@kolkrabbi/kol-component": ">=0.228.0",
+    "@kolkrabbi/kol-framework": ">=0.45.0",
+    "@kolkrabbi/kol-theme": ">=0.155.0",
     "@kolkrabbi/kol-icons": ">=0.18.0",
     "react": "^18.3.0 || ^19.0.0",
     "react-dom": "^18.3.0 || ^19.0.0",
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.220.0",
-    "@kolkrabbi/kol-icons": "^0.27.1",
-    "@kolkrabbi/kol-framework": "^0.44.0",
-    "@kolkrabbi/kol-theme": "^0.148.0"
+    "@kolkrabbi/kol-component": "^0.229.0",
+    "@kolkrabbi/kol-icons": "^0.29.0",
+    "@kolkrabbi/kol-theme": "^0.156.0",
+    "@kolkrabbi/kol-framework": "^0.45.0"
   },
   "files": [
     "src",

package/src/docs/DocKit.jsx

@@ -12,7 +12,7 @@
 
 import { Table } from '@kolkrabbi/kol-component'
 import { renderInlineTokens } from './render-tokens.jsx'
-import { processInlineMarkdown } from '../engine/parse-markdown.js'
+import { processInlineMarkdown } from '@kolkrabbi/kol-markdown'
 
 export function DocHeader({ eyebrow, title, lede, children }) {
   return (

package/src/docs/DocumentationReader.jsx

@@ -1,12 +1,12 @@
 import { useContext, useEffect, useMemo, useState } from 'react'
 import { useParams, Link, useNavigate } from 'react-router-dom'
 import { CodeBlock, Divider, Icon, Table, useScrollSpy } from '@kolkrabbi/kol-component'
-import { ShellTocContext, RightRail } from '../shell'
+import { ShellTocContext, RightRail, SHELL_SCROLL_ROOT } from '../shell'
 import { useTagMode } from '../tags'
 import TagPath from '../tags/TagPath.jsx'
-import { parseDocsMarkdown, isIndexFile } from '../engine'
-import { buildTagCounts } from '../engine/tags.js'
-import { fileLabel } from '../engine/doc-helpers.js'
+import { parseDocsMarkdown, isIndexFile } from '@kolkrabbi/kol-markdown'
+import { buildTagCounts } from '@kolkrabbi/kol-markdown'
+import { fileLabel } from '@kolkrabbi/kol-markdown'
 import DocsHeader from './DocsHeader.jsx'
 import DocsArticle from './DocsArticle.jsx'
 import DocsFrontmatter from './DocsFrontmatter.jsx'
@@ -22,10 +22,10 @@ import { renderInlineTokens } from './render-tokens.jsx'
 const DocReaderSidebar = ({ toc, allTags, related, docId, docsIndexHref, componentsHref, docFilePath, topTags = [] }) => {
   const navigate = useNavigate()
   const { openTagMode } = useTagMode()
-  /* `#main` is the scroll container — the shell is `fixed inset-0` with its own
-   * scroll regions, so a viewport-rooted observer never fires. Same call the
+  /* The shell's one scroll region is the observer root — the shell is `fixed inset-0` with its own
+   * scroll region, so a viewport-rooted observer never fires. Same call the
    * other rail makes; the rail is handed the answer, never a second observer. */
-  const activeId = useScrollSpy((toc ?? []).map((h) => h.id), { root: '#main' })
+  const activeId = useScrollSpy((toc ?? []).map((h) => h.id), { root: SHELL_SCROLL_ROOT })
 
   const actions = [
     { id: 'back', label: 'Back', icon: <Icon name="arrow-left" size={14} />, onClick: () => navigate(-1) },

package/src/engine/index.js

@@ -1,21 +1,8 @@
 /**
- * The pure docs engine — zero dependencies, no React, no Vite.
- * Everything here is a plain function over strings/data.
+ * `@kolkrabbi/kol-workshop/engine` — kept as a re-export since 0.30.0. The engine moved to the
+ * engine tier: the markdown half is `@kolkrabbi/kol-markdown`, the matcher `@kolkrabbi/kol-search`.
+ * Import from those; this subpath and the root barrel's engine names stay so kolkrabbi.io
+ * resolves until it moves.
  */
-export { parseDocsMarkdown, extractHashtags, processInlineMarkdown } from './parse-markdown.js'
-export { parseFrontmatter } from './frontmatter.js'
-export { buildInventory, buildInventoryCounts } from './build-inventory.js'
-export { matchSearchItems } from './search.js'
-export { buildTagCounts, buildTagCooccurrence } from './tags.js'
-export {
-  capitalise,
-  isIndexFile,
-  extractDocNumber,
-  kolkrabbiPages,
-  subsectionPrefixes,
-  categoryLabels,
-  cleanTitle,
-  fileLabel,
-  getTagColor,
-  groupDocsByMajor,
-} from './doc-helpers.js'
+export * from '@kolkrabbi/kol-markdown'
+export { matchSearchItems } from '@kolkrabbi/kol-search'

package/src/exhibit/ExhibitSidebar.jsx

@@ -79,7 +79,6 @@ export default function ExhibitSidebar({
               type="button"
               className="shell-sidebar-action kol-mono-14 text-body"
               onClick={() => navigator.clipboard?.writeText(window.location.pathname)}
-              title="Copy page path to clipboard"
             >
               <Icon name="copy" size={14} />
               Copy path

package/src/index.js

@@ -13,4 +13,5 @@ export * from './docs/index.js'
 export * from './tags/index.js'
 export * from './exhibit/index.js'
 export * from './compositions/index.js'
+export * from './search/index.js'
 export * from './engine/index.js'

package/src/search/SearchPage.jsx

@@ -0,0 +1,140 @@
+import { Fragment, useMemo } from 'react'
+import { Link, useSearchParams } from 'react-router-dom'
+import { Button, Input, Pill } from '@kolkrabbi/kol-component'
+import { createIndex, search, parseQuery } from '@kolkrabbi/kol-search'
+import { DocHeader, DocSection } from '../docs/DocKit.jsx'
+
+/**
+ * SearchPage — THE results page (2026-09-28). Enter in the shell's palette
+ * lands here with `?q=`; so does a tag clicked anywhere (`#tag`). The WHOLE
+ * state is the query string in the URL — scope and facet picks are written back
+ * into it as `in:` · `kind:` · `cat:` · `tag:` tokens — so Back returns to the
+ * same results, a result link is an ordinary navigation, and a search can be
+ * shared as a link.
+ *
+ * It replaced two surfaces that each did half the job: the palette's in-place
+ * tag browser and a page whose groups were whatever `sectionLabel` each
+ * source happened to emit.
+ *
+ * @param {Array}  items   kol-search items: { id, title, href, kind?, space?, category?, tags?, headings?, keywords?, description?, date? }
+ * @param {Array}  [spaces] the scope row, `[{ value, label }]` in header order — `value` is an item's `space`
+ * @param {Array}  [facets] `[[field, label]]` shown as filter rows (default kind · category · tags)
+ * @param {number} [limit=60]
+ */
+const DEFAULT_FACETS = [['kind', 'Kind'], ['category', 'Category'], ['tags', 'Tags']]
+const PREFIX = { space: 'in', kind: 'kind', category: 'cat', tags: 'tag' }
+const token = (field, value) => `${PREFIX[field] ?? field}:${/\s/.test(value) ? `"${value}"` : value}`
+
+function Highlight({ text, ranges }) {
+  if (!ranges?.length) return text
+  const out = []
+  let at = 0
+  ranges.forEach(([s, e], i) => {
+    if (s > at) out.push(<Fragment key={`t${i}`}>{text.slice(at, s)}</Fragment>)
+    out.push(<span key={`m${i}`} className="underline decoration-2 underline-offset-4">{text.slice(s, e)}</span>)
+    at = e
+  })
+  if (at < text.length) out.push(<Fragment key="rest">{text.slice(at)}</Fragment>)
+  return out
+}
+
+const readToken = (t) => (t.kind === 'term'
+  ? `${t.negate ? 'not ' : ''}“${t.value}”`
+  : t.kind === 'date'
+    ? `${t.field} ${t.value}`
+    : `${t.negate ? 'not ' : ''}${t.field === 'tags' ? 'tag' : t.field}: ${t.value}${t.via === 'smart' ? ' (from the word)' : ''}`)
+
+export default function SearchPage({ items = [], spaces = [], facets = DEFAULT_FACETS, limit = 60 }) {
+  const [params, setParams] = useSearchParams()
+  const q = params.get('q') ?? ''
+  const index = useMemo(() => createIndex(items), [items])
+  const out = useMemo(() => search(index, q, { limit }), [index, q, limit])
+
+  const setQ = (next) => setParams(next.trim() ? { q: next } : {}, { replace: true })
+  /* a pick adds its token; picking it again takes the token back out */
+  const toggleToken = (field, value) => {
+    const tok = token(field, value)
+    const parts = q.split(/\s+/).filter(Boolean)
+    const has = parts.includes(tok)
+    setQ((has ? parts.filter((p) => p !== tok) : [...parts, tok]).join(' '))
+  }
+  const removeToken = (raw) => setQ(q.split(/\s+/).filter((p) => p && p !== raw).join(' '))
+  const inSpace = parseQuery(q).filters.space ?? []
+
+  return (
+    <div className="flex flex-col gap-10">
+      <DocHeader
+        eyebrow="Search"
+        title="Search"
+        lede={q ? `${out.total} result${out.total === 1 ? '' : 's'} for “${q}”.` : 'Everything in the site — components, docs, blocks, sets.'}
+      />
+
+      <div className="flex flex-col gap-4">
+        <Input
+          value={q}
+          onChange={(e) => setQ(e.target.value)}
+          placeholder="Search — try atom, tag:pattern/input, in:docs, -legacy"
+          iconLeft="search"
+          size="lg"
+          aria-label="Search query"
+          autoFocus
+        />
+        {spaces.length > 0 && (
+          <div className="flex flex-wrap items-center gap-2" role="group" aria-label="Scope">
+            <Button variant="ghost" size="sm" pressed={!inSpace.length} onClick={() => setQ(q.split(/\s+/).filter((p) => p && !/^in:/.test(p)).join(' '))}>Everything</Button>
+            {spaces.map((sp) => (
+              <Button key={sp.value} variant="ghost" size="sm" pressed={inSpace.includes(sp.value)} onClick={() => toggleToken('space', sp.value)}>
+                {sp.label}
+              </Button>
+            ))}
+          </div>
+        )}
+        {out.query.tokens.length > 0 && (
+          <div className="flex flex-wrap items-center gap-2">
+            <span className="kol-doc-eyebrow">Read as</span>
+            {out.query.tokens.map((t, i) => (
+              <button key={`${t.raw}-${i}`} type="button" onClick={() => removeToken(t.raw)} aria-label={`Remove ${t.raw}`} className="cursor-pointer">
+                <Pill variant={t.kind === 'term' ? 'secondary' : 'primary'} size="md">{readToken(t)} ×</Pill>
+              </button>
+            ))}
+          </div>
+        )}
+      </div>
+
+      {facets.map(([field, label]) => {
+        const values = (out.facets[field] ?? []).slice(0, 16)
+        if (!values.length) return null
+        return (
+          <DocSection key={field} id={`facet-${field}`} title={label}>
+            <div className="flex flex-wrap gap-2">
+              {values.map((f) => (
+                <Button key={f.value} variant="ghost" size="sm" pressed={f.selected} onClick={() => toggleToken(field, f.value)}>
+                  {f.value}<span className="ml-1.5 opacity-60">{f.count}</span>
+                </Button>
+              ))}
+            </div>
+          </DocSection>
+        )
+      })}
+
+      <DocSection id="results" title={`Results (${out.total})`}>
+        {out.results.length === 0 ? (
+          <p className="kol-doc-body">{q ? 'Nothing matches. Remove a token above, or try fewer words.' : 'Type to search.'}</p>
+        ) : (
+          <ol className="flex flex-col">
+            {out.results.map((r) => (
+              <li key={r.item.id} className="border-t border-fg-08 first:border-t-0">
+                <Link to={r.item.href} className="flex flex-col gap-1 py-3 hover:bg-fg-04">
+                  <span className="kol-doc-body text-emphasis"><Highlight text={r.item.title} ranges={r.highlights.title} /></span>
+                  <span className="kol-helper-12 text-subtle">{[r.item.kind, r.item.category, r.item.space, r.item.date].filter(Boolean).join(' · ')}</span>
+                  {r.item.description && <span className="kol-doc-body">{r.item.description}</span>}
+                </Link>
+              </li>
+            ))}
+          </ol>
+        )}
+        {out.total > out.results.length && <p className="kol-helper-12 text-subtle">{out.total - out.results.length} more — narrow the query.</p>}
+      </DocSection>
+    </div>
+  )
+}

package/src/search/index.js

@@ -0,0 +1 @@
+export { default as SearchPage } from './SearchPage.jsx'

package/src/shell/RailSection.jsx

@@ -18,7 +18,7 @@ import { Link } from 'react-router-dom'
  *
  * THE LADDER
  *
- *   L1  section  `.shell-sidebar-toggle` + kol-doc-eyebrow    quiet, no chevron
+ *   L1  section  `.shell-sidebar-toggle` + kol-doc-eyebrow    quiet, state glyph at the end
  *   L2  group    `.shell-nav-group-header` + kol-mono-14      louder, chevron
  *
  * L2 carries NO colour class: `.shell-nav-group-header` owns weight 500 and
@@ -33,9 +33,12 @@ import { Link } from 'react-router-dom'
  *     either rail is literally the same string.
  *   - The COUNT is placed by the rung, not by the caller. You cannot put it in
  *     the wrong place because you never write the span.
- *   - No chevron at L1 (user ruling 2026-08-01) — the section still collapses
- *     and expands on click, the glyph is simply not drawn. L2 keeps its
- *     chevron: it is the rung where a caret means "there is a subtree here".
+ *   - L1 SAYS WHETHER IT IS FOLDED (2026-09-28, reversing the 2026-08-01 "no
+ *     chevron at L1"): a collapsed eyebrow read as an EMPTY category — "it just
+ *     has an interaction, but no states or indicator of folded content". The
+ *     state glyph sits at the row's END (the eyebrow's text keeps the rail's
+ *     left edge), and a collapsed L1 shows how much it is hiding. L2 keeps its
+ *     leading chevron: the rung where a caret means "there is a subtree here".
  *   - The box (padding + margin) belongs to the rung class alone. Nothing here
  *     sets y-spacing inline; see the eyebrow-box law in kol-components-workshop.css.
  *
@@ -97,14 +100,19 @@ export default function RailSection({
     />
   ) : null
 
-  /* THE COUNT IS AN L2 AFFORDANCE (user ruling 2026-08-01): "dont list counter
-   * next to eyebrow category, just inside". A category eyebrow names a body of
-   * material; the tally belongs to the groups inside it, not to the label over
-   * them. So L1 drops a `count` on the floor rather than rendering it — the
-   * rung refuses it, so no call site can put one back. */
-  const countNode = level === 2 && count !== undefined && count !== null
+  /* THE COUNT. L2 always carries its own. L1 carries one ONLY while folded
+   * (2026-09-28): open, the groups inside show their tallies and a second one
+   * on the eyebrow is noise (the 2026-08-01 ruling's point, kept); folded,
+   * there is nothing else on screen to say the category holds anything. */
+  const hasCount = count !== undefined && count !== null
+  const countNode = level === 2 && hasCount
     ? <span className="kol-mono-14 text-subtle">({count})</span>
-    : null
+    : level === 1 && collapsible && isCollapsed && hasCount
+      ? <span className="text-subtle">({count})</span>
+      : null
+  const l1State = level === 1 && collapsible && IconComponent ? (
+    <IconComponent name="chevron-right" size={12} className={`transition-transform text-subtle ${isCollapsed ? '' : 'rotate-90'}`} />
+  ) : null
 
   /* L1 EYEBROW IS ONE GESTURE (user ruling 2026-08-09, repealing the
    * 2026-08-01 label-door at L1): the whole row toggles BOTH ways — a label
@@ -138,7 +146,10 @@ export default function RailSection({
         {level === 2 && !chevron && <span aria-hidden="true" style={{ width: 12 }} />}
         {labelNode}
       </span>
-      {countNode}
+      <span className="flex items-center gap-2">
+        {countNode}
+        {l1State}
+      </span>
     </>
   )