@kolkrabbi/kol-workshop 0.38.0 → 0.40.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "private": false,
   "description": "Docs viewer, shell and tag system",
   "license": "MIT",
@@ -13,12 +13,12 @@
   },
   "dependencies": {
     "d3": "^7.9.0",
-    "@kolkrabbi/kol-markdown": "^0.1.3",
     "@kolkrabbi/kol-search": "^0.3.0",
+    "@kolkrabbi/kol-markdown": "^0.1.3",
     "@kolkrabbi/kol-brand": "^0.1.3"
   },
   "peerDependencies": {
-    "@kolkrabbi/kol-component": ">=0.237.0",
+    "@kolkrabbi/kol-component": ">=0.266.0",
     "@kolkrabbi/kol-framework": ">=0.45.0",
     "@kolkrabbi/kol-theme": ">=0.165.0",
     "@kolkrabbi/kol-icons": ">=0.18.0",
@@ -28,10 +28,10 @@
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-component": "^0.239.0",
-    "@kolkrabbi/kol-icons": "^0.33.0",
-    "@kolkrabbi/kol-theme": "^0.165.0",
-    "@kolkrabbi/kol-framework": "^0.49.0"
+    "@kolkrabbi/kol-framework": "^0.50.0",
+    "@kolkrabbi/kol-icons": "^0.39.0",
+    "@kolkrabbi/kol-component": "^0.266.0",
+    "@kolkrabbi/kol-theme": "^0.174.0"
   },
   "files": [
     "src",

package/src/docs/DocsFrontmatter.jsx

@@ -137,17 +137,34 @@ const CASED_VALUE_FIELDS = new Set(['type', 'status'])
 /* a doc's lifecycle on Badge's status tones (W17): live reads success, in progress warning, gone error */
 const STATUS_TONE = { active: 'success', canonical: 'info', draft: 'warning', archived: 'error', superseded: 'error', deprecated: 'error' }
 
-/** Contract order first, then anything else the doc carries, alphabetically. */
-const orderFields = (metadata) => {
+/** Contract order first, then anything else the doc carries, alphabetically. A consumer's
+ * `fields[key].order` places a key at that index of the list; `hidden` drops it. */
+const orderFields = (metadata, fields = {}) => {
   const present = Object.keys(metadata).filter(
-    (k) => !HIDDEN.has(k) && metadata[k] != null && metadata[k] !== '' &&
+    (k) => !(fields[k]?.hidden ?? 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 placed = present.filter((k) => Number.isFinite(fields[k]?.order))
+  const known = FIELD_ORDER.filter((k) => present.includes(k) && !placed.includes(k))
+  const rest = present.filter((k) => !FIELD_ORDER.includes(k) && !placed.includes(k)).sort()
+  const list = [...known, ...rest]
+  for (const k of placed.sort((a, b) => fields[a].order - fields[b].order)) list.splice(Math.min(fields[k].order, list.length), 0, k)
+  return list
 }
 
+/* A VALUE THAT IS A URL IS A LINK (reader-takes-field-config-and-page-actions, kol-website
+ * 2026-10-05): `url`/`repo` printed as plain text. Printed without the protocol, in the body's
+ * link idiom, opening a new tab as the body's external links do (render-tokens). */
+const URL_RE = /^https?:\/\//
+const LINK_CLS = 'text-emphasis underline decoration-fg-16 underline-offset-2 hover:decoration-current break-all'
+const printValue = (v) => {
+  const s = String(v)
+  return URL_RE.test(s) ? <a href={s} target="_blank" rel="noreferrer" className={LINK_CLS}>{s.replace(URL_RE, '').replace(/\/$/, '')}</a> : s
+}
+/* …and a key with no icon entry takes this one, so the label column keeps one left edge whatever
+ * a document carries (the 2026-08-01 rule above, made true for keys this file has never seen) */
+const DEFAULT_ICON = 'hash-01'
+
 /* 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'])
@@ -159,7 +176,13 @@ const formatDate = (dateStr) => {
   return d.toLocaleDateString('en-GB', { day: '2-digit', month: '2-digit', year: 'numeric' }).replace(/\//g, '.')
 }
 
-const DocsFrontmatter = ({ metadata, docId }) => {
+/**
+ * @param {Object} [fields]  per-key config from the consumer, merged over this file's tables:
+ *                           `{ [key]: { label, icon, order, hidden, render(value, metadata) } }`
+ *                           (2026-10-05, kol-website /workshop). No config is the output as before,
+ *                           apart from URL values as links and the default icon.
+ */
+const DocsFrontmatter = ({ metadata, docId, fields: config = {} }) => {
   const { openTagMode } = useTagMode()
   /* THE PANEL COLLAPSES, THE PAGE SCROLLS (user call 2026-08-09). A long
    * frontmatter (Dropdown: classes + reuses + tokens) made the panel the
@@ -170,7 +193,7 @@ const DocsFrontmatter = ({ metadata, docId }) => {
   const [expanded, setExpanded] = useState(false)
   const [overflowing, setOverflowing] = useState(false)
 
-  const fields = metadata ? orderFields(metadata) : []
+  const fields = metadata ? orderFields(metadata, config) : []
 
   useLayoutEffect(() => {
     const el = bodyRef.current
@@ -190,16 +213,17 @@ const DocsFrontmatter = ({ metadata, docId }) => {
       >
       {fields.map((key) => {
         const value = metadata[key]
-        const icon = FIELD_ICONS[key]
+        const cfg = config[key] ?? {}
+        const icon = cfg.icon ?? FIELD_ICONS[key] ?? DEFAULT_ICON
 
         return (
           <div key={key} className="docs-frontmatter-row">
             <span className="docs-frontmatter-key kol-helper-12 text-meta">
               {icon && <Icon name={icon} size={14} className="text-oq-48" />}
-              {FIELD_LABELS[key] ?? humanise(key)}
+              {cfg.label ?? FIELD_LABELS[key] ?? humanise(key)}
             </span>
             <span className="docs-frontmatter-value kol-mono-12 text-strong">
-              {key === 'tags' && Array.isArray(value) ? (
+              {cfg.render ? cfg.render(value, metadata) : 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
@@ -248,11 +272,11 @@ const DocsFrontmatter = ({ metadata, docId }) => {
                  * 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 key={i} className="break-all">{printValue(item)}</span>
                   ))}
                 </span>
               ) : (
-                String(value)
+                printValue(value)
               )}
             </span>
           </div>

package/src/docs/DocumentationReader.jsx

@@ -77,6 +77,11 @@ const DocReaderSidebar = ({ toc, allTags, related, docId, docsIndexHref, compone
  *                                        (2026-09-30, the names audit: every level has a home).
  * @param {boolean}  [props.showFrontmatter=true]  the frontmatter panel; a home hides it by
  *                                        default and the consumer toggles it.
+ * @param {Object}   [props.fields]       per-key frontmatter config, handed to DocsFrontmatter:
+ *                                        `{ [key]: { label, icon, order, hidden, render } }`
+ * @param {node}     [props.actions]      the page's own actions (a button to the live app),
+ *                                        rendered under the title and before the intro; absent,
+ *                                        nothing (2026-10-05, kol-website /workshop)
  */
 const DocumentationReader = ({
   inventory = [],
@@ -85,6 +90,8 @@ const DocumentationReader = ({
   routes = {},
   docId: docIdProp,
   showFrontmatter = true,
+  fields,
+  actions,
   /* false → render the article only and leave the right rail to the page (a HOME sits on top of
    * a page whose sections the rail must list — 2026-09-30, "This page (0)" on every home) */
   rail = true,
@@ -365,10 +372,11 @@ const DocumentationReader = ({
 
   return (
     <DocsArticle>
-        {showFrontmatter && <DocsFrontmatter metadata={doc.metadata} docId={docId} />}
+        {showFrontmatter && <DocsFrontmatter metadata={doc.metadata} docId={docId} fields={fields} />}
         {docTitle && (
           <h1 id="page-top" className="kol-doc-heading scroll-mt-20">{docTitle}</h1>
         )}
+        {actions && <div className="flex flex-wrap items-center gap-2">{actions}</div>}
         {/* Render intro blocks (excluding H1 which is docTitle) */}
         {introBlocks.filter(b => b.type !== 'heading1').map((block, index) =>
           renderBlock(block, `intro-${block.type}-${index}`)

package/src/shell/RailRow.jsx

@@ -31,7 +31,7 @@ import { Link, NavLink } from 'react-router-dom'
  * @param {string}   [to]       route → NavLink, active resolved by the router. A `to` carrying a `#` is a
  *                              SECTION of a page (2026-10-01): the router would light every section of
  *                              the open page at once, so it is a plain Link and `active` decides
- * @param {string}   [href]     plain anchor (hash links: on-this-page)
+ * @param {string}   [href]     plain anchor (hash links: on-this-page); an `http(s)` href opens a new tab
  * @param {Function} [onClick]  no `to`/`href` → a <button>
  * @param {boolean}  [active]   forced active state (hash links, buttons)
  * @param {node}     [icon]     leading glyph
@@ -80,8 +80,11 @@ export default function RailRow({
     )
   }
   if (href) {
+    /* a link that leaves the site opens a new tab, as the body's do (render-tokens, 2026-10-02);
+       hash and same-site links stay in it (2026-10-05, kol-website) */
+    const external = /^https?:\/\//.test(href) ? { target: '_blank', rel: 'noreferrer' } : null
     return (
-      <a href={href} className={cls(active)} onClick={onNavigate}>
+      <a href={href} className={cls(active)} onClick={onNavigate} {...external}>
         {inner}
       </a>
     )

package/src/shell/RightRail.jsx

@@ -60,7 +60,7 @@ const hueOf = (tag) => { const c = getTagColor(tag); return c === 'dark' ? undef
  *                                the scroll spy; both rails must agree on it)
  * @param {Array}    related      [{ id, href, label }] — label is the target's
  *                                own SHORT title, never a wikilink display text
- * @param {Array}    actions      [{ id, label, icon, to?, onClick? }]
+ * @param {Array}    actions      [{ id, label, icon, to?, href?, onClick? }] — `href` for an action that leaves the site
  * @param {Array}    topTags      [{ tag, count }] — the way in, not a dump
  * @param {Array}    tags         [string] — this page's own tags
  * @param {Function} renderTag    (tag) => node — the chip renderer, injected so
@@ -179,7 +179,7 @@ export default function RightRail({
 
           {group('actions', 'Quick actions', allActions.length,
             allActions.map((a) => (
-              <RailRow key={a.id} to={a.to} onClick={a.onClick} icon={a.icon}>
+              <RailRow key={a.id} to={a.to} href={a.href} onClick={a.onClick} icon={a.icon}>
                 {a.label}
               </RailRow>
             ))
@@ -203,7 +203,7 @@ export default function RightRail({
             {tagViews.length > 0 && (
               <nav className="shell-nav-items">
                 {tagViews.map((a) => (
-                  <RailRow key={a.id} to={a.to} onClick={a.onClick} icon={a.icon}>{a.label}</RailRow>
+                  <RailRow key={a.id} to={a.to} href={a.href} onClick={a.onClick} icon={a.icon}>{a.label}</RailRow>
                 ))}
               </nav>
             )}

package/src/shell/ShellLayout.jsx

@@ -2,7 +2,7 @@ import { createContext, useContext, useMemo, useRef, useState, useEffect, Suspen
 import { Outlet, Link, useLocation, useNavigate, useNavigationType } from 'react-router-dom'
 import { ShellHeader } from '@kolkrabbi/kol-framework'
 import ShellSidebar, { RAIL_FOLD_EVENT, ShellRailModeContext } from './ShellSidebar.jsx'
-import { FullscreenOverlay, IconFrame, ShellDrawer, ShellSearchOverlay, ShortcutsOverlay, SettingsPanel, SettingsSections, SettingsSwitch, Tooltip, useDragResize } from '@kolkrabbi/kol-component'
+import { FullscreenOverlay, IconFrame, Rail, CommandOverlay, ShortcutsOverlay, SettingsPanel, SettingsSections, SettingsSwitch, Tooltip, useDragResize } from '@kolkrabbi/kol-component'
 import { createIndex, search } from '@kolkrabbi/kol-search'
 import { useTagMode } from '../tags/TagModeContext.jsx'
 import TagModeOverlay from '../tags/TagModeOverlay.jsx'
@@ -602,7 +602,7 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
 
           {/* `open`, not `isOpen` — the old prop name silently kept the drawer
             * shut, so there was no navigation at all below lg. */}
-          <ShellDrawer
+          <Rail
             open={isNavDrawerOpen}
             onClose={() => setIsNavDrawerOpen(false)}
           >
@@ -610,13 +610,13 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
               ? renderSidebar({ activeRoute, onNavigate: () => setIsNavDrawerOpen(false) })
               : <ShellSidebar routes={routes} basePath={basePath} onNavigate={() => setIsNavDrawerOpen(false)} />
             }
-          </ShellDrawer>
+          </Rail>
 
           {/* 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
+          <CommandOverlay
             open={isSearchOpen}
             onClose={closeSearch}
             query={searchQuery}
@@ -658,7 +658,7 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
             }}
           >
             {tagMode.isProvided && tagMode.expanded ? <TagModeOverlay /> : null}
-          </ShellSearchOverlay>
+          </CommandOverlay>
 
           {isShortcutsOpen && <ShortcutsOverlay shortcuts={SHORTCUTS} onClose={() => setIsShortcutsOpen(false)} />}