@kolkrabbi/kol-workshop 0.6.0 → 0.18.1

package/package.json

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

package/src/compositions/WorkshopDefaultSidebar.jsx

@@ -1,5 +1,6 @@
 import { useLocation, Link } from 'react-router-dom'
 import { Icon } from '@kolkrabbi/kol-component'
+import { RailRow } from '../shell'
 
 /**
  * WorkshopDefaultSidebar — EXAMPLE composition. The contextual right rail:
@@ -24,21 +25,13 @@ const WorkshopDefaultSidebar = ({ routes = [], basePath = '/workshop' }) => {
   const links = currentChild?.links
 
   return (
-    <div className="space-y-4">
+    <div className="shell-rail-stack-inner">
       {siblings.length > 1 && (
         <div>
           <div className="shell-sidebar-label kol-doc-eyebrow">{parentRoute.label}</div>
-          <nav className="space-y-0">
+          <nav className="shell-nav-items">
             {siblings.map(child => (
-              <Link
-                key={child.id}
-                to={`${basePath}/${child.path}`}
-                className={`shell-nav-item block kol-mono-14 ${
-                  location.pathname === `${basePath}/${child.path}` ? 'text-emphasis' : 'text-body'
-                }`}
-              >
-                {child.label}
-              </Link>
+              <RailRow key={child.id} to={`${basePath}/${child.path}`}>{child.label}</RailRow>
             ))}
           </nav>
         </div>
@@ -49,16 +42,10 @@ const WorkshopDefaultSidebar = ({ routes = [], basePath = '/workshop' }) => {
           <div className="shell-sidebar-label kol-doc-eyebrow">Repository</div>
           <div>
             {links.live && (
-              <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>
+              <RailRow href={links.live} icon={<Icon name="external-link" size={14} />}>Live site</RailRow>
             )}
             {links.repo && (
-              <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>
+              <RailRow href={links.repo} icon={<Icon name="external-link" size={14} />}>GitHub</RailRow>
             )}
           </div>
         </div>
@@ -67,19 +54,8 @@ const WorkshopDefaultSidebar = ({ routes = [], basePath = '/workshop' }) => {
       <div>
         <div className="shell-sidebar-label kol-doc-eyebrow">Quick actions</div>
         <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-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"
-          >
-            <Icon name="copy" size={14} />
-            Copy path
-          </button>
+          <RailRow to={basePath} icon={<Icon name="layout" size={14} />}>Workshop home</RailRow>
+          <RailRow onClick={() => navigator.clipboard.writeText(window.location.pathname)} icon={<Icon name="copy" size={14} />}>Copy path</RailRow>
         </div>
       </div>
     </div>

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, Tooltip } from '@kolkrabbi/kol-component'
+import { ShellSidebar, RailSection, RailRow } from '../shell'
+import { Icon } from '@kolkrabbi/kol-component'
 import {
   extractDocNumber,
   cleanTitle,
@@ -60,77 +60,52 @@ const DocsSidebar = ({ inventory = [], docHref, basePath, onNavigate, collapsed,
   }
 
   return (
-    <div className="space-y-4">
-      {/* kol-helper-10 types the wrapper box itself (was an untyped 16px box) */}
-      <div className="shell-sidebar-toggle shell-sidebar-label kol-doc-eyebrow" style={{ justifyContent: 'space-between', paddingRight: '4px' }}>
-        <Link to={docHref()} className="shell-sidebar-label kol-doc-eyebrow" onClick={(e) => {
-          if (collapsed && onToggle) onToggle()
-          if (onNavigate) onNavigate(e)
-        }}>
-          Documentation
-        </Link>
-        <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">
+    <div className="shell-rail-stack-inner">
+      {/* L1 from RailSection — the same rung and the same box as every other
+        * rail header. No count: the eyebrow names the material, the groups
+        * inside carry the tally (user ruling 2026-08-01). */}
+      <RailSection
+        level={1}
+        label="Documentation"
+        to={docHref()}
+        collapsed={collapsed}
+        onToggle={onToggle}
+        onNavigate={onNavigate}
+      >
+        <div className="shell-rail-stack-inner">
         {Object.entries(groupedDocs)
           .sort(([a], [b]) => a.localeCompare(b))
           .map(([major, docs]) => {
             const isCollapsed = collapsedGroups[major]
             return (
               <div key={major} className="shell-nav-group">
-                <button
-                  type="button"
-                  className="shell-nav-group-header w-full text-left kol-mono-14 text-body"
-                  onClick={() => toggleGroup(major)}
+                <RailSection
+                  level={2}
+                  label={categoryLabels[major] || 'Other'}
+                  count={docs.length}
+                  collapsed={!!isCollapsed}
+                  onToggle={() => toggleGroup(major)}
+                  icon={Icon}
                 >
-                  <span className="flex items-center gap-2">
-                    <Icon
-                      name="chevron-right"
-                      size={12}
-                      className={`h-3 w-3 transition-transform ${isCollapsed ? '' : 'rotate-90'}`}
-                    />
-                    {categoryLabels[major] || 'Other'}
-                  </span>
-                  <span className="kol-mono-14 text-subtle">({docs.length})</span>
-                </button>
-                {!isCollapsed && (
-                  <div className="shell-nav-items">
-                    {docs.map((d) => {
-                      const isActive = d.id === activeDocId
-                      return (
-                        <Link
-                          key={d.id}
-                          to={docHref(d.id)}
-                          className={`shell-nav-item shell-nav-item-doc kol-mono-14 ${isActive ? 'text-emphasis' : 'text-body'}`}
-                          onClick={onNavigate}
-                        >
-                          <span className="shell-nav-item-title">{cleanTitle(d.title, d.id)}</span>
-                          <span className="shell-nav-item-id kol-mono-14 text-subtle">{extractDocNumber(d.id)}</span>
-                        </Link>
-                      )
-                    })}
-                  </div>
-                )}
+                  <nav className="shell-nav-items">
+                    {docs.map((d) => (
+                      <RailRow
+                        key={d.id}
+                        to={docHref(d.id)}
+                        active={d.id === activeDocId}
+                        trailing={extractDocNumber(d.id)}
+                        onNavigate={onNavigate}
+                      >
+                        {cleanTitle(d.title, d.id)}
+                      </RailRow>
+                    ))}
+                  </nav>
+                </RailSection>
               </div>
             )
           })}
-      </div>}
+        </div>
+      </RailSection>
     </div>
   )
 }
@@ -159,7 +134,7 @@ const WorkshopSidebar = ({
   )
 
   return (
-    <div className="space-y-6">
+    <div className="shell-rail-stack">
       <ShellSidebar
         routes={workshopRoutes}
         basePath={basePath}

package/src/docs/DocKit.jsx

@@ -11,6 +11,8 @@
  */
 
 import { Table } from '@kolkrabbi/kol-component'
+import { renderInlineTokens } from './render-tokens.jsx'
+import { processInlineMarkdown } from '../engine/parse-markdown.js'
 
 export function DocHeader({ eyebrow, title, lede, children }) {
   return (
@@ -38,11 +40,26 @@ export function DocSection({ id, title, lede, children }) {
  * classes through Table's per-column seams, doc chrome via the .kol-doc-table
  * class on Table's wrapper (the descendant rules out-specify Table's cell
  * defaults). Renders UNFRAMED (flush minimal — user ruling: no border). */
+/* CELLS PARSE INLINE MARKDOWN (user ruling 2026-08-01). `type` and `desc`
+ * carry backticked code — "`primary` is the grey fill" — and the cells printed
+ * the string raw, so every prop description showed its own backticks instead of
+ * a code chip. The vault's markdown got this right the whole time because it
+ * runs through `renderInlineTokens`; the props table simply never called it.
+ * `Table` has supported `column.render` all along (Table.jsx:35). Nothing new
+ * was written for this — two existing pieces that had never been introduced. */
+const inline = (v, key) =>
+  typeof v === 'string' && v
+    ? renderInlineTokens(processInlineMarkdown(v), key)
+    : v ?? '—'
+
 const PROPS_COLUMNS = [
-  { accessor: 'prop', header: 'Prop', className: 'kol-doc-table-value text-emphasis' },
-  { accessor: 'type', header: 'Type', className: 'kol-doc-table-value kol-doc-table-value--wrap text-meta' },
-  { accessor: 'def', header: 'Default', className: 'kol-doc-table-value text-meta' },
-  { accessor: 'desc', header: 'Description' },
+  { accessor: 'prop', header: 'Prop', sortable: true, className: 'kol-doc-table-value text-emphasis' },
+  /* type + default are TOKENS, so they wear the token chip (user ruling
+   * 2026-08-01) — .kol-table-token, the same chip the tables already use.
+   * They rendered as bare text while every neighbouring surface chipped them. */
+  { accessor: 'type', header: 'Type', className: 'kol-doc-table-value kol-doc-table-value--wrap text-meta', render: (r) => (r.type ? <code className="kol-table-token">{r.type}</code> : '—') },
+  { accessor: 'def', header: 'Default', className: 'kol-doc-table-value text-meta', render: (r) => (r.def ? <code className="kol-table-token">{r.def}</code> : '—') },
+  { accessor: 'desc', header: 'Description', render: (r) => inline(r.desc, `${r.prop}-desc`) },
 ]
 
 export function DocTable({ rows }) {

package/src/docs/DocsFrontmatter.jsx

@@ -1,24 +1,93 @@
 import { Icon, Tag } from '@kolkrabbi/kol-component'
-import { getTagColor } from '../engine'
 import { useTagMode } from '../tags'
+import TagPath from '../tags/TagPath.jsx'
 
+/* EVERY field carries an icon (user ruling 2026-08-01). Ten of these were
+ * hard-coded `null`, so two rows had a glyph and the rest sat at a ragged left
+ * edge — a column that is sometimes iconned is worse than one that never is.
+ * Every name below is verified present in kol-icon-set-v1. */
 const FIELD_ICONS = {
   file: 'file',
-  title: null,
-  type: 'folder',
+  title: 'type',
+  type: 'library',
   status: 'check',
-  updated: null,
-  created: null,
-  verified: null,
-  description: null,
-  audience: null,
-  aliases: null,
+  updated: 'refresh',
+  created: 'plus',
+  verified: 'shield-check',
+  description: 'message',
+  audience: 'user',
+  aliases: 'repeat',
+  sources: 'code',
+  superseded_by: 'arrow-right',
+  drift: 'alert-triangle',
   version: 'hash-01',
+  tags: 'hash-02',
+  /* 2026-08-01: these three rendered iconless while the rule above promised
+   * every field carries one — the exact ragged edge that rule exists to stop.
+   * All verified present in kol-icon-set-v1. */
+  id: 'hash-01',
+  reuses: 'repeat',
+  slug: 'external-link',
+  /* provenance — folded in from the retired MetaRows panel 2026-08-01 */
+  source: 'code',
+  imported_from: 'arrow-right',
+  type_styles: 'type',
+  classes: 'library',
+  tokens: 'hash-01',
+  composes: 'component-01',
+  in_sets: 'grid',
+  used_in: 'layers',
   /* legacy dialect (workshop-sample docs) — kept so those still render */
-  date: null,
+  date: 'journal',
   category: 'folder',
-  tags: null,
-  modified: null,
+  modified: 'edit',
+}
+
+/* AUTHORED labels, not the raw key (user ruling 2026-08-01). The row printed
+ * `{key}` straight from the frontmatter, so the column read lowercase and
+ * snake_cased. KOL forbids `text-transform` on a component — casing is a
+ * content decision — so the strings are written here in the case they render.
+ * A key with no entry falls back to its own name rather than vanishing. */
+const FIELD_LABELS = {
+  file: 'File',
+  title: 'Title',
+  type: 'Type',
+  status: 'Status',
+  updated: 'Updated',
+  created: 'Created',
+  verified: 'Verified',
+  description: 'Description',
+  audience: 'Audience',
+  aliases: 'Aliases',
+  sources: 'Sources',
+  superseded_by: 'Superseded by',
+  drift: 'Drift',
+  version: 'Version',
+  tags: 'Tags',
+  source: 'Source',
+  imported_from: 'Imported from',
+  type_styles: 'Type styles',
+  classes: 'Classes',
+  tokens: 'Tokens',
+  composes: 'Composes',
+  in_sets: 'In sets',
+  used_in: 'Used in',
+  date: 'Date',
+  category: 'Category',
+  modified: 'Modified',
+}
+
+/* THE FALLBACK IS A LABEL TOO (user ruling 2026-08-01). `FIELD_LABELS[key] ??
+ * key` printed an unnamed key raw, so a doc carrying `imported_from` before it
+ * was listed rendered the row as `imported_from` — snake_case and lowercase, in
+ * a column where every neighbour is sentence case. *"its very amateur that you
+ * cant start a sentence or word with a Capital?"*
+ *
+ * Casing is authored at the data layer, never by CSS (the no-auto-text-transform
+ * law) — so the fallback authors it here, where the string is made. */
+const humanise = (key) => {
+  const words = String(key).replace(/[-_]+/g, ' ').trim()
+  return words.charAt(0).toUpperCase() + words.slice(1)
 }
 
 /* Reading ORDER, not an allowlist. The kol-docs contract first
@@ -36,13 +105,33 @@ const FIELD_ICONS = {
  * `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',
+  /* `created` sits ABOVE `updated` (user ruling 2026-08-01) — a document's age
+   * reads oldest-first, and `updated` on its own says nothing about how long
+   * the thing has existed. */
+  'title', 'type', 'status', 'created', 'updated', 'tags',
+  'description', 'aliases', 'sources',
+  'verified', 'audience', 'superseded_by', 'drift',
   'category', 'date', 'modified', 'version',
 ]
 
-const HIDDEN = new Set(['related'])
+/* `related` — the rail renders it as live links; printing the raw wikilinks
+ * here would be the same thing twice.
+ *
+ * `aliases` — user ruling 2026-08-01: *"why is this a category in frontmatter?
+ * what purpose … its just not relevant"*. It is an OBSIDIAN field, not a tag
+ * and not a document fact: `.kol/docs-framework/01-conventions.md:65` says it
+ * feeds the Quick Switcher and search autocomplete and explicitly does **not**
+ * affect wikilink resolution. Nothing in this app reads it. It stays in the
+ * file for Obsidian and stops taking a row in a panel that renders facts. */
+const HIDDEN = new Set(['related', 'aliases'])
+
+/* VALUES ARE SENTENCE CASE TOO (user ruling 2026-08-01). The labels were fixed
+ * and the values were not, so the panel read `Type  reference` / `Status
+ * active` — a capitalised label pointing at a lowercase word. These two fields
+ * carry closed enums from the kol-docs contract, so the case is authored here
+ * against the key, never with a text-transform. Every other value is content
+ * and is printed exactly as written. */
+const CASED_VALUE_FIELDS = new Set(['type', 'status'])
 
 /** Contract order first, then anything else the doc carries, alphabetically. */
 const orderFields = (metadata) => {
@@ -85,26 +174,58 @@ const DocsFrontmatter = ({ metadata, docId }) => {
           <div key={key} className="docs-frontmatter-row">
             <span className="docs-frontmatter-key kol-helper-12 text-meta">
               {icon && <Icon name={icon} size={14} />}
-              {key}
+              {FIELD_LABELS[key] ?? humanise(key)}
             </span>
-            <span className="kol-mono-12 text-strong">
+            <span className="docs-frontmatter-value kol-mono-12 text-strong">
               {key === 'tags' && Array.isArray(value) ? (
+                /* `naked`, the SAME Tag rendering the rail's own tag list uses
+                 * (DocReaderSidebar). This was the default filled variant, so
+                 * the one concept rendered as a solid pill here and as plain
+                 * coloured text six inches to the right.
+                 *
+                 * NO `color` (user ruling 2026-08-01): passing one swaps the
+                 * base class from `tag-control` to `tag tag--{color}`, and
+                 * only `tag-control` has a `:hover` rule — so a coloured Tag
+                 * silently loses its interaction state. Right component first;
+                 * colour is its own decision, later.
+                 * `size` is omitted: `sm` is the default and the only size. */
                 <span className="flex flex-wrap gap-1.5">
                   {value.map((tag) => (
-                    <Tag
-                      key={tag}
-                      size="sm"
-                      color={getTagColor(tag)}
-                      onClick={() => openTagMode(tag)}
-                    >
-                      {tag}
+                    <Tag key={tag} onClick={() => openTagMode(tag)}>
+                      {/* the path renderer, not the raw string — namespace dims,
+                        * leaf carries. Shared with the tag overlay so the two
+                        * surfaces cannot spell a tag two ways. */}
+                      <TagPath tag={tag} />
                     </Tag>
                   ))}
                 </span>
               ) : DATE_FIELDS.has(key) ? (
                 formatDate(String(value))
+              ) : CASED_VALUE_FIELDS.has(key) ? (
+                humanise(String(value))
               ) : Array.isArray(value) ? (
-                value.join(' · ')
+                /* STACKED, ONE PER LINE (user ruling 2026-08-01). Arrays were
+                 * `value.join(' · ')` — a single run-on string, so `sources`
+                 * with three file paths ran straight off the right edge of the
+                 * panel and the reader could not tell where one path ended and
+                 * the next began. A list of paths IS a list; the dot-join was
+                 * printing it as a sentence.
+                 *
+                 * `break-all` because these are paths, not words: a wrapped
+                 * path must break at the character, never leave a gap and drop
+                 * the whole segment to the next line.
+                 *
+                 * THE LIST SCROLLS PAST ITS CAP (user question 2026-08-01:
+                 * "I just wonder what it will be when the sources are f.e. more
+                 * then 15?"). Unbounded, fifteen paths push the article fifteen
+                 * lines down and the metadata panel becomes the page. No
+                 * file-type icons — a path already ends in its own extension,
+                 * and a glyph restating it is decoration. */
+                <span className="docs-frontmatter-list">
+                  {value.map((item, i) => (
+                    <span key={i} className="break-all">{String(item)}</span>
+                  ))}
+                </span>
               ) : (
                 String(value)
               )}