@kolkrabbi/kol-workshop 0.37.0 → 0.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.37.0",
+  "version": "0.39.0",
   "private": false,
   "description": "Docs viewer, shell and tag system",
   "license": "MIT",
@@ -13,14 +13,14 @@
   },
   "dependencies": {
     "d3": "^7.9.0",
-    "@kolkrabbi/kol-markdown": "^0.1.2",
-    "@kolkrabbi/kol-brand": "^0.1.3",
-    "@kolkrabbi/kol-search": "^0.3.0"
+    "@kolkrabbi/kol-markdown": "^0.1.3",
+    "@kolkrabbi/kol-search": "^0.3.0",
+    "@kolkrabbi/kol-brand": "^0.1.3"
   },
   "peerDependencies": {
     "@kolkrabbi/kol-component": ">=0.237.0",
     "@kolkrabbi/kol-framework": ">=0.45.0",
-    "@kolkrabbi/kol-theme": ">=0.163.0",
+    "@kolkrabbi/kol-theme": ">=0.165.0",
     "@kolkrabbi/kol-icons": ">=0.18.0",
     "gsap": "^3.13.0",
     "react": "^18.3.0 || ^19.0.0",
@@ -28,10 +28,10 @@
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-framework": "^0.48.0",
-    "@kolkrabbi/kol-theme": "^0.163.0",
-    "@kolkrabbi/kol-component": "^0.237.0",
-    "@kolkrabbi/kol-icons": "^0.33.0"
+    "@kolkrabbi/kol-component": "^0.240.0",
+    "@kolkrabbi/kol-framework": "^0.49.0",
+    "@kolkrabbi/kol-theme": "^0.166.0",
+    "@kolkrabbi/kol-icons": "^0.33.1"
   },
   "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/docs/render-tokens.jsx

@@ -63,7 +63,8 @@ export const renderInlineTokens = (
           return token.text
         }
         return (
-          <a key={tokenKey} href={token.url} className={linkCls}>
+          /* a link that leaves the site opens a new tab (2026-10-02); a relative or `#` link stays */
+          <a key={tokenKey} href={token.url} className={linkCls} {...(/^https?:/.test(token.url) ? { target: '_blank', rel: 'noreferrer' } : null)}>
             {token.text}
           </a>
         )

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 { IconFrame, ShellDrawer, ShellSearchOverlay, ShortcutsOverlay, SettingsPanel, SettingsSections, SettingsSwitch, Tooltip, useDragResize } from '@kolkrabbi/kol-component'
+import { FullscreenOverlay, IconFrame, ShellDrawer, ShellSearchOverlay, 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'
@@ -262,6 +262,7 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
   const [isFullHeight, setIsFullHeight] = useState(false)
   const [contentWidth, setContentWidth] = useState('canvas')
   const [isShortcutsOpen, setIsShortcutsOpen] = useState(false)
+  const [isTreeOpen, setIsTreeOpen] = useState(false)
   const location = useLocation()
   const navigate = useNavigate()
 
@@ -318,6 +319,7 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
       { id: 'toc', label: 'Right rail', combo: ']' },
       { id: 'rails', label: 'Both rails', combo: '\\' },
       { id: 'fold', label: 'Fold / expand all', combo: 'C' },
+      { id: 'tree', label: 'Whole tree', combo: 'T' },
       { id: 'esc', label: 'Close', combo: 'Esc' },
     ] },
     ...(shortcuts.length ? [{ section: 'Page', items: shortcuts.map(({ id, label, combo }) => ({ id, label, combo })) }] : []),
@@ -366,6 +368,11 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
         e.preventDefault()
         foldedRef.current = !foldedRef.current
         window.dispatchEvent(new CustomEvent(RAIL_FOLD_EVENT, { detail: { collapsed: foldedRef.current } }))
+      } else if (e.key === 't' || e.key === 'T') {
+        /* THE WHOLE TREE (user 2026-10-02: *"C … is just about the visual tree per space, I was
+         * talking about a shortcut to get the entire tree in any given view"*) */
+        e.preventDefault()
+        setIsTreeOpen((v) => !v)
       } else if (shortcutsRef.current.some((s) => s.key === e.key)) {
         e.preventDefault()
         shortcutsRef.current.find((s) => s.key === e.key).run()
@@ -655,6 +662,25 @@ const ShellLayout = ({ routes = [], basePath = '/', brand: brandProp, brandLogoS
 
           {isShortcutsOpen && <ShortcutsOverlay shortcuts={SHORTCUTS} onClose={() => setIsShortcutsOpen(false)} />}
 
+          {/* THE WHOLE TREE, FROM ANY PAGE (`T`, 2026-10-02): every space's rail side by side, every
+            * fold open, over the page like the search modal. Each column is the consumer's own rail
+            * for that space (`renderSidebar`) drawn in the `full` rail mode, so it cannot list
+            * anything the rails do not. A row closes the sheet and goes there. */}
+          <FullscreenOverlay open={isTreeOpen} onClose={() => setIsTreeOpen(false)} scrim>
+            <div className="shell-tree bg-surface-primary">
+              {routes.map((route) => (
+                <section key={route.id ?? route.path} className="shell-tree-space">
+                  <Link to={route.path?.startsWith('/') ? route.path : `${basePath}/${route.path ?? ''}`} className="kol-doc-eyebrow text-emphasis" onClick={() => setIsTreeOpen(false)}>{route.label}</Link>
+                  <ShellRailModeContext.Provider value="full">
+                    {renderSidebar
+                      ? renderSidebar({ activeRoute: route, onNavigate: () => setIsTreeOpen(false), mode: 'full' })
+                      : <ShellSidebar routes={route.children ?? []} basePath={basePath} label={null} onNavigate={() => setIsTreeOpen(false)} />}
+                  </ShellRailModeContext.Provider>
+                </section>
+              ))}
+            </div>
+          </FullscreenOverlay>
+
           {/* THE SHELL'S SETTINGS (2026-09-28, user: "might we also want to utilize a
             * settings page or settings sidebar … to offload some functional
             * settings, search settings, sidenav settings"). A right drawer over

package/src/shell/ShellSidebar.jsx

@@ -30,7 +30,8 @@ export const RAIL_FOLD_EVENT = 'kol-rail-fold'
  * we dont use it, I want to see it"*). Beside visible and hidden: `icons` — the rail is a narrow
  * strip, one glyph per group, and opens on hover. The column that holds the rail (`ShellNavColumn`)
  * provides the state; every ShellSidebar inside it reads it, so a consumer's rail takes the state
- * without passing a prop. Outside a provider a rail is `open`, as it always was. */
+ * without passing a prop. Outside a provider a rail is `open`, as it always was. A third value,
+ * `full`, is the whole-tree sheet's: an open rail with every fold open. */
 export const ShellRailModeContext = createContext('open')
 
 const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Navigation', labelTo, collapsed, onToggle, defaultCollapsed = false }) => {
@@ -48,8 +49,8 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
 
   /* THE RAIL FOLLOWS YOU — INTO A CHILD ONLY (2026-09-30, reversing the 2026-09-28 "open the
    * group you are in" on its landing page too). Landing on a page INSIDE a chapter opens that
-   * chapter and folds the rest; a chapter's own home keeps that chapter open (2026-10-01, see
-   * `chainTo`). Every other chapter starts
+   * chapter and folds the rest; a chapter's own home leaves that chapter's fold alone (2026-10-02,
+   * see `chainTo`). Every other chapter starts
    * folded — including ones this rail has never seen (a Group-by switch hands it new ids, and an
    * unknown id used to read as open, so every chapter sprang open).
    *
@@ -72,28 +73,32 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
       /* deepest first: `/sets` holds `/sets/app-shell` by prefix, but the set's own row is the place */
       const deeper = chainTo(r.children, [...trail, r])
       if (deeper) return deeper
-      if (r.children.some(isHere)) return [...trail, r]
-      /* A GROUP'S OWN HOME KEEPS IT OPEN (user 2026-10-01: *"I dont want to collapse the list
-       * like that when I just want to go to atoms home and still see the atoms list"* — reverses
-       * the 2026-09-30 "a chapter's own home opens nothing"). The label is a link; only the
-       * chevron folds. */
-      if (r.path && getChildPath(r, basePath).replace(/\/$/, '') === normalizedPath) return [...trail, r]
+      /* A GROUP'S OWN HOME LEAVES ITS FOLD AS IT WAS (user 2026-10-02, said many times: *"just
+       * clicking a title opens the home, if I want to expand then I fucking click the expand
+       * chevron"*). The 2026-10-01 reading opened the group on its own home, so a title click
+       * expanded its children; the 2026-09-30 one folded it. Neither: the way down to it opens,
+       * the group itself stays as the chevron left it — open stays open, folded stays folded.
+       * Checked BEFORE the children: a vault chapter's home is also its `About` row, and reading
+       * that as "a child is here" opened every Docs chapter on a title click.
+       * `validate:rail-pages` P5 holds it. */
+      if (r.path && getChildPath(r, basePath).replace(/\/$/, '') === normalizedPath) return { open: trail, keep: r.id }
+      if (r.children.some(isHere)) return { open: [...trail, r] }
     }
     return null
   }
-  const followed = () => {
-    const chain = chainTo(routes)
-    if (!chain) return null
-    const open = new Set(chain.map((g) => g.id))
-    return Object.fromEntries(groupsOf(routes).map((g) => [g.id, !open.has(g.id)]))
+  const followed = (prev = {}) => {
+    const at = chainTo(routes)
+    if (!at) return null
+    const open = new Set(at.open.map((g) => g.id))
+    return Object.fromEntries(groupsOf(routes).map((g) => [g.id, g.id === at.keep ? (prev[g.id] ?? true) : !open.has(g.id)]))
   }
   const [collapsedSections, setCollapsedSections] = useState(() => followed() ?? {})
   useEffect(() => {
-    const next = followed()
-    if (next) setCollapsedSections(next)
+    setCollapsedSections((prev) => followed(prev) ?? prev)
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [normalizedPath, routes, basePath])
-  const isFolded = (route) => collapsedSections[route.id] ?? true
+  /* `full` — the whole-tree sheet (`T`, 2026-10-02): every fold open, nothing to follow */
+  const isFolded = (route) => (mode === 'full' ? false : collapsedSections[route.id] ?? true)
 
   /* FOLD ALL (2026-09-30, the names audit: *"shortcut collapse/expand the categories"*). The
    * shell's `C` key broadcasts one target state; every rail's chapters take it. */
@@ -210,7 +215,7 @@ const ShellSidebar = ({ routes = [], basePath = '/', onNavigate, label = 'Naviga
           label={label}
           to={labelTo}
           count={leafCount}
-          collapsed={navCollapsed}
+          collapsed={mode === 'full' ? false : navCollapsed}
           onToggle={handleToggle}
           onNavigate={onNavigate}
           icon={Icon}