@kolkrabbi/kol-workshop 0.18.1 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.18.1",
+  "version": "0.20.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",
@@ -14,10 +14,10 @@
   "dependencies": {
     "d3": "^7.9.0",
     "@kolkrabbi/kol-brand": "^0.1.2",
-    "@kolkrabbi/kol-component": "0.24.0",
+    "@kolkrabbi/kol-component": "0.27.0",
     "@kolkrabbi/kol-icons": "0.10.0",
-    "@kolkrabbi/kol-framework": "0.13.0",
-    "@kolkrabbi/kol-theme": "0.30.1"
+    "@kolkrabbi/kol-theme": "0.31.3",
+    "@kolkrabbi/kol-framework": "0.14.0"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",

package/src/docs/DocsFrontmatter.jsx

@@ -1,3 +1,4 @@
+import { useLayoutEffect, useRef, useState } from 'react'
 import { Icon, Tag } from '@kolkrabbi/kol-component'
 import { useTagMode } from '../tags'
 import TagPath from '../tags/TagPath.jsx'
@@ -157,15 +158,33 @@ const formatDate = (dateStr) => {
 
 const DocsFrontmatter = ({ metadata, docId }) => {
   const { openTagMode } = useTagMode()
-  if (!metadata || Object.keys(metadata).length === 0) return null
+  /* THE PANEL COLLAPSES, THE PAGE SCROLLS (user call 2026-08-09). A long
+   * frontmatter (Dropdown: classes + reuses + tokens) made the panel the
+   * page, and its per-field scrollboxes captured the wheel on the way down.
+   * The whole panel now caps behind a fade and expands in normal flow — the
+   * toggle renders only when the content actually overflows the cap. */
+  const bodyRef = useRef(null)
+  const [expanded, setExpanded] = useState(false)
+  const [overflowing, setOverflowing] = useState(false)
 
-  const fields = orderFields(metadata)
+  const fields = metadata ? orderFields(metadata) : []
+
+  useLayoutEffect(() => {
+    const el = bodyRef.current
+    if (el) setOverflowing(el.scrollHeight > el.clientHeight + 1)
+  }, [metadata, expanded])
 
   if (fields.length === 0) return null
 
+  const capped = !expanded
+
   return (
     <div className="docs-frontmatter">
       <p className="shell-sidebar-label kol-doc-eyebrow">Frontmatter</p>
+      <div
+        ref={bodyRef}
+        className={`docs-frontmatter-body${capped ? ' docs-frontmatter-body--capped' : ''}`}
+      >
       {fields.map((key) => {
         const value = metadata[key]
         const icon = FIELD_ICONS[key]
@@ -233,6 +252,18 @@ const DocsFrontmatter = ({ metadata, docId }) => {
           </div>
         )
       })}
+        {capped && overflowing && <div className="docs-frontmatter-fade" aria-hidden="true" />}
+      </div>
+      {(overflowing || expanded) && (
+        <button
+          type="button"
+          className="docs-frontmatter-toggle kol-helper-12 text-meta"
+          onClick={() => setExpanded((v) => !v)}
+        >
+          <Icon name={expanded ? 'chevron-up' : 'chevron-down'} size={14} />
+          {expanded ? 'Collapse' : 'Expand'}
+        </button>
+      )}
     </div>
   )
 }

package/src/shell/RailSection.jsx

@@ -45,7 +45,10 @@ import { Link } from 'react-router-dom'
  * @param {string}   label        header text, rendered verbatim (casing is authored)
  * @param {number}   [count]      leaf rows this section contains — L1 counts the
  *                                whole subtree, L2 counts its own children
- * @param {string}   [to]         make the LABEL a link; the rest of the row still toggles
+ * @param {string}   [to]         L2: make the LABEL a link (the rest of the row
+ *                                still toggles). Non-collapsible rungs: the whole
+ *                                row is the link. Ignored on a collapsible L1 —
+ *                                the eyebrow is a pure two-way toggle (2026-08-09)
  * @param {boolean}  [collapsible=true]  false → a static header, no toggle, no aria
  * @param {boolean}  [collapsed]  controlled state; omit for uncontrolled
  * @param {Function} [onToggle]   required when `collapsed` is passed
@@ -103,12 +106,17 @@ export default function RailSection({
     ? <span className="kol-mono-14 text-subtle">({count})</span>
     : null
 
-  const labelNode = to ? (
+  /* 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
+   * link never collapses, and the text is most of the perceived target, so
+   * the eyebrow felt expand-only. A category's door lives in the header tabs.
+   * L2 keeps the split (2026-08-02 ruling): its label is a chapter's only
+   * door to the landing page, and the chevron marks the toggle. */
+  const labelNode = to && level === 2 ? (
     /* The label navigates; the rest of the row toggles. stopPropagation keeps
      * one click from doing both. */
     <Link
       to={to}
-      className={level === 1 ? 'kol-doc-eyebrow' : undefined}
       onClick={(e) => {
         e.stopPropagation()
         if (isCollapsed && toggle) toggle()