@kolkrabbi/kol-workshop 0.3.6 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.3.6",
+  "version": "0.5.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-brand": "^0.1.2",
-    "@kolkrabbi/kol-component": "0.14.1",
     "@kolkrabbi/kol-icons": "0.8.11",
+    "@kolkrabbi/kol-component": "0.14.3",
+    "@kolkrabbi/kol-brand": "^0.1.2",
     "@kolkrabbi/kol-theme": "0.13.3",
-    "@kolkrabbi/kol-framework": "0.8.1"
+    "@kolkrabbi/kol-framework": "0.9.1"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",

package/src/compositions/WorkshopDefaultSidebar.jsx

@@ -33,7 +33,7 @@ const WorkshopDefaultSidebar = ({ routes = [], basePath = '/workshop' }) => {
               <Link
                 key={child.id}
                 to={`${basePath}/${child.path}`}
-                className={`shell-sidebar-link block kol-mono-14 ${
+                className={`shell-nav-item block kol-mono-14 ${
                   location.pathname === `${basePath}/${child.path}` ? 'text-emphasis' : 'text-body'
                 }`}
               >
@@ -47,15 +47,15 @@ const WorkshopDefaultSidebar = ({ routes = [], basePath = '/workshop' }) => {
       {links && (
         <div>
           <div className="shell-sidebar-label kol-doc-eyebrow">Repository</div>
-          <div className="space-y-1">
+          <div>
             {links.live && (
-              <a href={links.live} target="_blank" rel="noopener noreferrer" className="shell-sidebar-action kol-mono-14 text-body">
+              <a href={links.live} target="_blank" rel="noopener noreferrer" className="shell-nav-item flex items-center gap-2 kol-mono-14 text-body transition-colors hover:text-emphasis">
                 <Icon name="external-link" size={14} />
                 Live site
               </a>
             )}
             {links.repo && (
-              <a href={links.repo} target="_blank" rel="noopener noreferrer" className="shell-sidebar-action kol-mono-14 text-body">
+              <a href={links.repo} target="_blank" rel="noopener noreferrer" className="shell-nav-item flex items-center gap-2 kol-mono-14 text-body transition-colors hover:text-emphasis">
                 <Icon name="external-link" size={14} />
                 GitHub
               </a>
@@ -66,14 +66,14 @@ const WorkshopDefaultSidebar = ({ routes = [], basePath = '/workshop' }) => {
 
       <div>
         <div className="shell-sidebar-label kol-doc-eyebrow">Quick actions</div>
-        <div className="space-y-1">
-          <Link to={basePath} className="shell-sidebar-action kol-mono-14 text-body">
+        <div>
+          <Link to={basePath} className="shell-nav-item flex items-center gap-2 kol-mono-14 text-body transition-colors hover:text-emphasis">
             <Icon name="layout" size={14} />
             Workshop home
           </Link>
           <button
             type="button"
-            className="shell-sidebar-action kol-mono-14 text-body"
+            className="shell-nav-item flex items-center gap-2 kol-mono-14 text-body transition-colors hover:text-emphasis"
             onClick={() => navigator.clipboard.writeText(window.location.pathname)}
             title="Copy page path to clipboard"
           >

package/src/compositions/WorkshopSidebar.jsx

@@ -96,7 +96,7 @@ const DocsSidebar = ({ inventory = [], docHref, basePath, onNavigate, collapsed,
               <div key={major} className="shell-nav-group">
                 <button
                   type="button"
-                  className="shell-nav-group-header w-full text-left kol-helper-14 text-body"
+                  className="shell-nav-group-header w-full text-left kol-mono-14 text-body"
                   onClick={() => toggleGroup(major)}
                 >
                   <span className="flex items-center gap-2">
@@ -107,7 +107,7 @@ const DocsSidebar = ({ inventory = [], docHref, basePath, onNavigate, collapsed,
                     />
                     {categoryLabels[major] || 'Other'}
                   </span>
-                  <span className="kol-helper-12 text-subtle">({docs.length})</span>
+                  <span className="kol-mono-14 text-subtle">({docs.length})</span>
                 </button>
                 {!isCollapsed && (
                   <div className="shell-nav-items">
@@ -121,7 +121,7 @@ const DocsSidebar = ({ inventory = [], docHref, basePath, onNavigate, collapsed,
                           onClick={onNavigate}
                         >
                           <span className="shell-nav-item-title">{cleanTitle(d.title, d.id)}</span>
-                          <span className="shell-nav-item-id kol-helper-10 text-subtle">{extractDocNumber(d.id)}</span>
+                          <span className="shell-nav-item-id kol-mono-14 text-subtle">{extractDocNumber(d.id)}</span>
                         </Link>
                       )
                     })}

package/src/docs/DocsFrontmatter.jsx

@@ -5,16 +5,59 @@ import { useTagMode } from '../tags'
 const FIELD_ICONS = {
   file: 'file',
   title: null,
+  type: 'folder',
+  status: 'check',
+  updated: null,
+  created: null,
+  verified: null,
+  description: null,
+  audience: null,
+  aliases: null,
   version: 'hash-01',
+  /* legacy dialect (workshop-sample docs) — kept so those still render */
   date: null,
-  status: 'check',
-  'content-type': null,
   category: 'folder',
   tags: null,
-  modified: null
+  modified: null,
+}
+
+/* Reading ORDER, not an allowlist. The kol-docs contract first
+ * (`.kol/docs-framework/01-conventions.md`: required title/type/status/updated/
+ * tags, then recommended description/aliases, then optional), legacy
+ * sample-dialect keys after, and ANY key not named here after that — so a field
+ * can never be silently dropped for being unknown.
+ *
+ * This was a filter over ['title','category','date','tags','modified'] — the
+ * workshop-SAMPLE dialect. No kol-docs document carries category/date/modified,
+ * so it admitted title + tags and discarded the seven fields the parser had
+ * already handed it. The panel wasn't missing data; it was screening for the
+ * wrong schema, and screening is now the thing it doesn't do.
+ *
+ * `related` is the one deliberate omission — the rail renders it as live links,
+ * so printing the raw wikilinks here would be the same thing twice. */
+const FIELD_ORDER = [
+  'title', 'type', 'status', 'updated', 'tags',
+  'description', 'aliases',
+  'created', 'verified', 'audience', 'superseded_by', 'drift',
+  'category', 'date', 'modified', 'version',
+]
+
+const HIDDEN = new Set(['related'])
+
+/** Contract order first, then anything else the doc carries, alphabetically. */
+const orderFields = (metadata) => {
+  const present = Object.keys(metadata).filter(
+    (k) => !HIDDEN.has(k) && metadata[k] != null && metadata[k] !== '' &&
+      !(Array.isArray(metadata[k]) && metadata[k].length === 0)
+  )
+  const known = FIELD_ORDER.filter((k) => present.includes(k))
+  const rest = present.filter((k) => !FIELD_ORDER.includes(k)).sort()
+  return [...known, ...rest]
 }
 
-const FIELD_ORDER = ['title', 'category', 'date', 'tags', 'modified']
+/* Every field rendered as a date. `updated`/`created`/`verified` are the
+ * kol-docs names; `date`/`modified` are the sample dialect's. */
+const DATE_FIELDS = new Set(['updated', 'created', 'verified', 'date', 'modified'])
 
 const formatDate = (dateStr) => {
   if (!dateStr) return null
@@ -27,7 +70,7 @@ 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] !== '')
+  const fields = orderFields(metadata)
 
   if (fields.length === 0) return null
 
@@ -58,8 +101,10 @@ const DocsFrontmatter = ({ metadata, docId }) => {
                     </Tag>
                   ))}
                 </span>
-              ) : key === 'date' || key === 'modified' ? (
+              ) : DATE_FIELDS.has(key) ? (
                 formatDate(String(value))
+              ) : Array.isArray(value) ? (
+                value.join(' · ')
               ) : (
                 String(value)
               )}

package/src/docs/DocumentationReader.jsx

@@ -10,18 +10,41 @@ import DocsFrontmatter from './DocsFrontmatter.jsx'
 import { DocSection } from './DocKit.jsx'
 import { renderInlineTokens } from './render-tokens.jsx'
 
-const SidebarSection = ({ sectionKey, label, collapsedSections, toggleSection, children }) => (
-  <div>
-    <button
-      type="button"
-      className="shell-sidebar-toggle shell-sidebar-label kol-doc-eyebrow"
-      onClick={() => toggleSection(sectionKey)}
-    >
-      {label}
-    </button>
-    {!collapsedSections[sectionKey] && children}
-  </div>
-)
+/**
+ * A rail section header. Same anatomy as the LEFT tree's group header — a
+ * rotating chevron, the label, and the item count pushed right — because the
+ * two rails are one system and a reader shouldn't have to learn each side
+ * separately.
+ *
+ * These were bare text. They collapsed on click with no chevron, no count and
+ * no hover, so the only way to discover they were interactive was to click
+ * something that looked inert and watch the panel vanish. An affordance that
+ * only announces itself after you've used it isn't one.
+ */
+const SidebarSection = ({ sectionKey, label, count, collapsedSections, toggleSection, children }) => {
+  const isOpen = !collapsedSections[sectionKey]
+  return (
+    <div>
+      <button
+        type="button"
+        className="shell-nav-group-header w-full text-left shell-sidebar-label kol-doc-eyebrow"
+        onClick={() => toggleSection(sectionKey)}
+        aria-expanded={isOpen}
+      >
+        <span className="flex items-center gap-2">
+          <Icon
+            name="chevron-right"
+            size={12}
+            className={`transition-transform ${isOpen ? 'rotate-90' : ''}`}
+          />
+          {label}
+        </span>
+        {count > 0 && <span className="kol-mono-14 text-subtle">({count})</span>}
+      </button>
+      {isOpen && children}
+    </div>
+  )
+}
 
 const DocReaderSidebar = ({ toc, allTags, related, docId, docsIndexHref, componentsHref, docFilePath }) => {
   const navigate = useNavigate()
@@ -34,6 +57,7 @@ const DocReaderSidebar = ({ toc, allTags, related, docId, docsIndexHref, compone
       <SidebarSection
         sectionKey="toc"
         label="On this page"
+        count={toc?.length}
         collapsedSections={collapsedSections}
         toggleSection={toggleSection}
       >
@@ -44,6 +68,7 @@ const DocReaderSidebar = ({ toc, allTags, related, docId, docsIndexHref, compone
         <SidebarSection
           sectionKey="related"
           label="Related"
+          count={related.length}
           collapsedSections={collapsedSections}
           toggleSection={toggleSection}
         >
@@ -64,26 +89,30 @@ const DocReaderSidebar = ({ toc, allTags, related, docId, docsIndexHref, compone
         collapsedSections={collapsedSections}
         toggleSection={toggleSection}
       >
-        <div className="space-y-1">
+        {/* Quick actions wear the SAME row as On-this-page and Related. They
+          * were `.shell-sidebar-action`, a third geometry with no left indent,
+          * so this rail carried three different row idioms — under the
+          * "ONE rail voice" comment above. */}
+        <div>
           <button
             type="button"
-            className="shell-sidebar-action kol-mono-14 text-body"
+            className="shell-nav-item flex items-center gap-2 kol-mono-14 text-body transition-colors hover:text-emphasis"
             onClick={() => navigate(-1)}
           >
             <Icon name="arrow-left" size={14} />
             Back
           </button>
-          <Link to={docsIndexHref} className="shell-sidebar-action kol-mono-14 text-body">
+          <Link to={docsIndexHref} className="shell-nav-item flex items-center gap-2 kol-mono-14 text-body transition-colors hover:text-emphasis">
             <Icon name="book-open" size={14} />
             All documentation
           </Link>
-          <Link to={componentsHref} className="shell-sidebar-action kol-mono-14 text-body">
+          <Link to={componentsHref} className="shell-nav-item flex items-center gap-2 kol-mono-14 text-body transition-colors hover:text-emphasis">
             <Icon name="grid" size={14} />
             View components
           </Link>
           <button
             type="button"
-            className="shell-sidebar-action kol-mono-14 text-body"
+            className="shell-nav-item flex items-center gap-2 kol-mono-14 text-body transition-colors hover:text-emphasis"
             onClick={() => navigator.clipboard.writeText(docFilePath(docId))}
             title="Copy file path to clipboard"
           >
@@ -96,6 +125,7 @@ const DocReaderSidebar = ({ toc, allTags, related, docId, docsIndexHref, compone
       {allTags.length > 0 && (
         <SidebarSection
           sectionKey="tags"
+          count={allTags?.length}
           label="Tags"
           collapsedSections={collapsedSections}
           toggleSection={toggleSection}
@@ -376,7 +406,9 @@ const DocumentationReader = ({
 
   if (!doc) {
     return (
-      <div className="max-w-[1400px] mx-auto px-10 py-16">
+      /* framed to a 1400px tier that was removed from the scale at theme
+       * 0.11.22 and left behind here — a width nothing else still uses */
+      <div className="mx-auto max-w-[var(--kol-content-panel)] py-16">
         <DocsHeader title="Document Not Found" subtitle={`Could not find document: ${docId}`} />
         <p className="kol-mono-12 mt-6">
           <Link to={docsIndex} className="text-accent-primary">

package/src/engine/doc-helpers.js

@@ -85,14 +85,41 @@ export const cleanTitle = (title, id) => {
 
 const TAG_COLORS = ['blue', 'teal', 'green', 'yellow', 'red', 'orange', 'purple', 'dark']
 
-export const getTagColor = (tag) => {
+/* Colour BY NAMESPACE, from the closed taxonomy in `.kol/docs-framework/
+ * 03-tag-taxonomy.md`. Ten top-level namespaces, ten stable assignments —
+ * so `domain/*` is always one colour and the eye can group by prefix.
+ *
+ * This used to hash the whole tag string into TAG_COLORS. That made the colour
+ * a function of spelling rather than meaning: `#domain/design-system` and
+ * `#domain/iconography` landed on different hues for no reason a reader could
+ * see, and renaming a tag silently recoloured it. The taxonomy existed the
+ * whole time and nothing consulted it. */
+const NAMESPACE_COLORS = {
+  domain: 'blue',
+  pattern: 'purple',
+  provider: 'orange',
+  integration: 'teal',
+  project: 'green',
+  audience: 'yellow',
+  brand: 'red',
+  editor: 'teal',
+  framework: 'dark',
+  archive: 'dark',
+}
+
+/** Stable fallback for tags outside the taxonomy — still deterministic, but
+ *  only reached when a tag carries no known namespace. */
+const hashColor = (s) => {
   let hash = 0
-  for (let i = 0; i < tag.length; i++) {
-    hash = ((hash << 5) - hash + tag.charCodeAt(i)) | 0
-  }
+  for (let i = 0; i < s.length; i++) hash = ((hash << 5) - hash + s.charCodeAt(i)) | 0
   return TAG_COLORS[Math.abs(hash) % TAG_COLORS.length]
 }
 
+export const getTagColor = (tag) => {
+  const namespace = String(tag).replace(/^#/, '').split('/')[0]
+  return NAMESPACE_COLORS[namespace] ?? hashColor(namespace)
+}
+
 /** Group docs by major version number.
  *
  * Three id dialects are grouped: dotted (`0.0.1-slug`), folder-index

package/src/shell/ShellLayout.jsx

@@ -44,8 +44,14 @@ const MainColumn = ({ children, fullHeight }) => (
   </main>
 )
 
+/* `xl`, not `lg` — the grid only declares a third column at xl (gridCols
+ * below). Rendering this at lg put THREE children in a TWO-column grid between
+ * 1024 and 1279px: the rail wrapped to an implicit second row and `h-full`
+ * split the height between them, so main got ~373px of a 900px window and the
+ * page read as empty. The breakpoint here and the one in gridCols are one
+ * decision and must not be stated twice differently. */
 const TocColumn = ({ children }) => (
-  <aside aria-label="Table of contents" className="shell-sidebar-sticky hidden lg:block shrink-0 h-full min-h-0 overflow-y-auto overflow-x-hidden overscroll-none pt-6 md:pt-6 lg:pt-8 pb-8">
+  <aside aria-label="Table of contents" className="shell-sidebar-sticky hidden xl:block shrink-0 h-full min-h-0 overflow-y-auto overflow-x-hidden overscroll-none pt-6 md:pt-6 lg:pt-8 pb-8">
     {children}
   </aside>
 )
@@ -76,6 +82,14 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
   }, [])
 
   const effectiveTocContent = tocContent ?? defaultTocContent
+  /* KNOWN, deliberately not fixed here: an element is always truthy, so
+   * `<AutoToc/>` reserves a rail even on pages where it renders null. The
+   * obvious fix — measure the mounted column — deadlocks: once the column
+   * unmounts the probe is gone and can never report content again. The real
+   * fix is a consumer-side signal (a render-prop returning null, or an
+   * explicit `hasToc` prop), which is an API change. Filed, not improvised.
+   * The bug this caused — a half-height main column at 1024–1279px — was the
+   * `lg` vs `xl` mismatch on TocColumn above, and that IS fixed. */
   const hasToc = Boolean(effectiveTocContent)
   const showNav = !navCollapsed
   const showToc = hasToc && !tocCollapsed
@@ -183,7 +197,17 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
             * main scrolls unless a page locks it (ShellFullHeightContext — embeds).
             * overscroll-none stops chaining between regions and the edge bounce. */}
           <div className="flex-1 overflow-hidden">
-            <div className="h-full w-full px-4 md:px-5 lg:px-6">
+            {/* THE frame (kol-theme "Content widths"): ONE cap at the shell
+              * token, centred, on the framework padding ramp. This wrapper
+              * carried `w-full px-4 md:px-5 lg:px-6` — no cap at all, and
+              * Tailwind's 16/20/24 steps instead of the ramp's 20/32/48 — so
+              * every consumer page inherited the raw viewport (measured 2152px
+              * of frame at a 2200px window against an 1800px law). Every
+              * page-level width fix is downstream of this line. */}
+            <div
+              className="mx-auto h-full w-full max-w-[var(--kol-content-shell)]"
+              style={{ paddingInline: 'var(--kol-pad-section-x)' }}
+            >
               {/* gap lives in .shell-content-grid (theme) — a gap-8 utility here
                 * outranks the layered theme rule at every width and killed the
                 * 48px wide step (ARCHITECTURE §5: component geometry in its own

package/src/shell/ShellSidebar.jsx

@@ -75,7 +75,12 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
             {label}
           </Link>
         ) : (
-          <button type="button" className="kol-helper-10 text-meta" onClick={handleToggle}>{label}</button>
+          /* Same voice as the labelTo branch. This read `kol-helper-10
+           * text-meta`, so the one rail mounted without a labelTo (the vault's
+           * "Documentation") rendered its label at a different size and colour
+           * from its two siblings — a type fork caused purely by which props
+           * the consumer happened to pass. */
+          <button type="button" className="shell-sidebar-label kol-doc-eyebrow" onClick={handleToggle}>{label}</button>
         )}
         <Tooltip label={navCollapsed ? `Expand ${label}` : `Collapse ${label}`}>
           <button
@@ -99,25 +104,49 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
         {routes.map((route) => {
           const isExpanded = !collapsedSections[route.id]
 
+          /* A group with no children is not a group — it is a link. It used to
+           * render as a header anyway: a chevron that rotated over an empty
+           * body, no count, and no navigation, so clicking "Icons" or
+           * "Components" in the tree did nothing at all while looking like it
+           * should. Now the chevron and the toggle only appear when there is
+           * something to expand, and a childless row goes where it says. */
+          const hasChildren = route.children?.length > 0
+          const headerClass = 'shell-nav-group-header w-full text-left kol-mono-14 text-body'
+
           return (
             <div key={route.id} className="shell-nav-group">
-              <button
-                type="button"
-                className="shell-nav-group-header w-full text-left kol-helper-14 text-body"
-                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="kol-helper-12 text-subtle">({route.children.length})</span>
-                )}
-              </button>
+              {hasChildren ? (
+                <button
+                  type="button"
+                  className={headerClass}
+                  onClick={() => handleSectionClick(route)}
+                  aria-expanded={isExpanded}
+                >
+                  <span className="flex items-center gap-2">
+                    <Icon
+                      name="chevron-right"
+                      size={12}
+                      className={`transition-transform ${isExpanded ? 'rotate-90' : ''}`}
+                    />
+                    {route.label}
+                  </span>
+                  <span className="kol-mono-14 text-subtle">({route.children.length})</span>
+                </button>
+              ) : (
+                <Link
+                  to={getSectionRootPath(route, basePath)}
+                  className={headerClass}
+                  onClick={onNavigate}
+                >
+                  {/* aligned with the expandable rows' label column — the
+                    * chevron's width, kept as space so the two kinds of row
+                    * share a left edge */}
+                  <span className="flex items-center gap-2">
+                    <span aria-hidden="true" style={{ width: 12 }} />
+                    {route.label}
+                  </span>
+                </Link>
+              )}
 
               {isExpanded && route.children?.length > 0 && (
                 <div className="shell-nav-items">

package/src/tags/TagGraph.jsx

@@ -119,18 +119,18 @@ const TagGraph = ({ docs, activeTag, onTagClick, allDocs, tagHref = defaultTagHr
     // Node circles
     node.append('circle')
       .attr('r', d => Math.max(8, Math.min(16, 6 + d.count * 2)))
+      /* Palette tokens, not copies. This held eight hardcoded hexes that were
+       * transcriptions of --kol-palette-* (#3740D3 IS palette-blue) — correct
+       * the day they were typed and frozen ever since, so a retuned palette
+       * would move every chip and leave the graph behind. The chip rules in
+       * kol-components-molecules.css resolve the variables; the graph now
+       * reads the same ones. `dark` has no palette entry — it is a surface
+       * role — so it falls back rather than emitting an invalid var(). */
       .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'
+        const key = getTagColor(d.id)
+        return key === 'dark'
+          ? 'var(--kol-surface-on-primary)'
+          : `var(--kol-palette-${key}, var(--kol-palette-teal))`
       })
       .attr('opacity', d => activeTag && d.id !== activeTag ? 0.4 : 0.9)
       .attr('stroke', d => d.id === activeTag ? 'var(--kol-accent-primary)' : 'none')

package/src/tags/TagModeOverlay.jsx

@@ -34,7 +34,9 @@ const TagModeOverlay = () => {
 
   return (
     <article className="docs-article">
-      <div className="max-w-[864px] mx-auto">
+      {/* was max-w-[864px] — an improvised value in the ~900–1200 band the
+        * panel token exists to settle (kol-theme "Content widths"). */}
+      <div className="mx-auto max-w-[var(--kol-content-panel)]">
         <div className="flex items-center justify-start gap-1 mb-3">
           {hasFilters && (
             <Tooltip label={viewMode === 'graph' ? 'List view' : 'Graph view'}>