@kolkrabbi/kol-workshop 0.21.0 → 0.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.21.0",
+  "version": "0.22.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.34.0",
-    "@kolkrabbi/kol-icons": "^0.14.0",
-    "@kolkrabbi/kol-framework": "^0.18.0",
-    "@kolkrabbi/kol-theme": "^0.34.0"
+    "@kolkrabbi/kol-component": "^0.39.0",
+    "@kolkrabbi/kol-icons": "^0.16.0",
+    "@kolkrabbi/kol-framework": "^0.20.0",
+    "@kolkrabbi/kol-theme": "^0.41.0",
+    "@kolkrabbi/kol-brand": "^0.1.2"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",

package/src/exhibit/ExhibitCard.jsx

@@ -0,0 +1,29 @@
+/**
+ * ExhibitCard — the specimen header inside an exhibit section: what this
+ * variant is called, what it does, and (optionally) its technical line and its
+ * prop signature. Recreated from kol-website's local `DesCard` (37L), which
+ * every showcase page in that repo imported by relative path.
+ *
+ * Card-level hierarchy, one rung under the section's own PageSection title:
+ * name `kol-card-value` · description `kol-mono-12` · details/code `kol-mono-10`.
+ * The type comes from the role classes, never from a utility stack at the call
+ * site — the 2026-07-30 law that a component's type lives in its own rule.
+ *
+ * @param {string} name         variant name — ".text-auto", "Default state"
+ * @param {string} [description] one line on what the variant is for
+ * @param {string} [details]    technical line — variant trigger, classes used
+ * @param {string} [code]       the prop signature, rendered as code
+ */
+export default function ExhibitCard({ name, description, details, code }) {
+  return (
+    <div>
+      <h4 className="kol-card-value">{name}</h4>
+
+      {description && <p className="kol-mono-12 text-fg-64 mt-2">{description}</p>}
+
+      {details && <p className="kol-mono-10 text-fg-48 mt-1">{details}</p>}
+
+      {code && <code className="block kol-mono-10 text-fg-48 mt-2">{code}</code>}
+    </div>
+  )
+}

package/src/exhibit/ExhibitLinkCard.jsx

@@ -0,0 +1,69 @@
+import { Link } from 'react-router-dom'
+import { Icon } from '@kolkrabbi/kol-component'
+
+/**
+ * ExhibitLinkCard — the card an exhibit's landing page uses for each child
+ * page. Recreated from kol-website's `OverviewCard`, which carried a standing
+ * note on itself: *"vendored verbatim from elder @kol/ui (no DS twin as of
+ * kol-dashboards 0.2.0); lobby to the DS or fold into kol-dashboards if a
+ * second consumer app appears."* This is that lobby arriving.
+ *
+ * Internal hrefs render as a router `<Link>`, external ones as a plain anchor —
+ * an exhibit's landing grid routinely mixes both (a sub-page beside the live
+ * production instance it documents).
+ *
+ * @param {string} label        card title
+ * @param {string} [subtitle]   one line under the title
+ * @param {string} [description] footer line, clamped to one row
+ * @param {string} icon         glyph name — the corner mark and the empty-state fill
+ * @param {string} [image]      cover image; replaces the oversized glyph
+ * @param {string} href         internal path ("/workshop/…") or an absolute URL
+ */
+export default function ExhibitLinkCard({
+  label,
+  subtitle,
+  description,
+  icon,
+  image,
+  href,
+  target,
+  rel,
+  className = '',
+}) {
+  const internal = href?.startsWith('/')
+  const Tag = internal ? Link : 'a'
+  const linkProps = internal ? { to: href } : { href, target, rel }
+
+  return (
+    <Tag
+      {...linkProps}
+      className={`group flex aspect-[4/3] flex-col gap-3 rounded bg-surface-inverse p-4 ${className}`}
+    >
+      <div className="flex items-start justify-between">
+        <div>
+          <h3 className="kol-card-kicker">{label}</h3>
+          {subtitle && <p className="kol-mono-10 mt-1 italic text-fg-64">{subtitle}</p>}
+        </div>
+        <Icon name={icon} size={16} />
+      </div>
+
+      <div className="flex flex-1 items-center justify-center overflow-hidden rounded border border-fg-08">
+        {image ? (
+          <img
+            src={image}
+            alt={label}
+            className="h-full w-full scale-100 object-cover object-center transition-transform duration-300 group-hover:scale-105"
+          />
+        ) : (
+          <Icon
+            name={icon}
+            size={64}
+            className="text-auto transition-transform duration-300 group-hover:scale-105"
+          />
+        )}
+      </div>
+
+      {description && <p className="kol-card-tag line-clamp-1 text-fg-48">{description}</p>}
+    </Tag>
+  )
+}

package/src/exhibit/ExhibitOverview.jsx

@@ -0,0 +1,69 @@
+import { PageSection } from '@kolkrabbi/kol-framework'
+import ExhibitLinkCard from './ExhibitLinkCard.jsx'
+import useExhibitToc from './useExhibitToc.js'
+
+/**
+ * ExhibitOverview — an exhibit's landing page: what this section is, then every
+ * child page as a card.
+ *
+ * The overview contract kol-website's DashboardOverview implements by hand —
+ * concept in the intro (with room for a single external opt-in, the live
+ * instance the exhibit documents), children as a grid below.
+ *
+ * ```jsx
+ * <ExhibitOverview
+ *   toc={{ links: DOC_LINKS }}
+ *   label="Scope: Dashboard — Overview"
+ *   title="Dashboard"
+ *   body="Modular dashboards, charts and KPI components…"
+ *   action={<Button variant="primary" href="https://kolkrabbi.io/metrics">Open metrics</Button>}
+ *   cards={[{ id: 'setup', label: 'Setup', subtitle: '…', icon: 'book-open', href: '/workshop/dashboard/setup' }]}
+ * />
+ * ```
+ *
+ * @param {string} title · @param {string} label · @param {string} body  the intro section
+ * @param {node}   [action]      one call-to-action under the intro
+ * @param {Array}  cards         child pages: ExhibitLinkCard props, each with an `id`
+ * @param {string} [cardsLabel='Pages'] · @param {string} [cardsTitle='Explore'] · @param {string} [cardsBody]
+ * @param {object} [toc]         ExhibitSidebar props; omit to leave the rail alone
+ * @param {string} [id='overview']  anchor id of the intro section
+ */
+export default function ExhibitOverview({
+  id = 'overview',
+  label,
+  title,
+  body,
+  action,
+  cards = [],
+  cardsId = 'sections',
+  cardsLabel = 'Pages',
+  cardsTitle = 'Explore',
+  cardsBody,
+  toc,
+}) {
+  useExhibitToc(toc ?? {})
+
+  return (
+    <div>
+      <PageSection id={id} label={label} title={title} body={body}>
+        {action && <div className="mt-6">{action}</div>}
+      </PageSection>
+
+      {cards.length > 0 && (
+        <PageSection id={cardsId} label={cardsLabel} title={cardsTitle} body={cardsBody}>
+          {/* auto-fill from a 17.5rem minimum — the reference implementation's
+            * grid, so an exhibit's landing reflows the same everywhere. */}
+          <div className="mt-8 grid gap-6 grid-cols-[repeat(auto-fill,minmax(17.5rem,1fr))]">
+            {cards.map((card) => (
+              <ExhibitLinkCard
+                key={card.id}
+                {...card}
+                description={card.description ?? `Open ${card.label} in the workshop`}
+              />
+            ))}
+          </div>
+        </PageSection>
+      )}
+    </div>
+  )
+}

package/src/exhibit/ExhibitPage.jsx

@@ -0,0 +1,80 @@
+import { PageSection } from '@kolkrabbi/kol-framework'
+import ExhibitCard from './ExhibitCard.jsx'
+import useExhibitToc from './useExhibitToc.js'
+
+/**
+ * ExhibitPage — an exhibit's inner page, declared as CONTENT.
+ *
+ * The two page shapes kol-website hand-built per section collapse into one
+ * component, because they were never structurally different: a showcase page is
+ * a list of PageSections whose bodies are specimen grids, and a prose companion
+ * is a list of PageSections whose bodies are paragraphs. A section picks its
+ * body by which field it carries.
+ *
+ * ```jsx
+ * <ExhibitPage
+ *   toc={{ links: DOC_LINKS }}
+ *   sections={[
+ *     { id: 'intro', label: 'Dashboard', title: 'Dashboard components',
+ *       body: 'Cards for metrics, charts and data.' },
+ *
+ *     { id: 'metric-cards', label: 'Metric cards', title: 'DashMetricCard',
+ *       body: 'Label, value, delta.',
+ *       specimens: [
+ *         { name: 'KPI variant', description: 'Left border accent.',
+ *           details: 'Variant: borderColor present', code: 'label value delta borderColor',
+ *           demo: <DashMetricCard label="GAMES" value="2,847" borderColor="…" /> },
+ *       ] },
+ *
+ *     { id: 'tracking', label: 'Tracking', title: 'Umami', prose: true,
+ *       children: <><p>…</p><p>…</p></> },
+ *   ]}
+ * />
+ * ```
+ *
+ * @param {Array}  sections  the page, in order. Each: `{ id, label, title, body }`
+ *   plus at most one body shape — `specimens` (a grid of ExhibitCard-headed
+ *   demos), or `children` (anything), optionally with `prose: true` for the
+ *   reading measure. `columns` overrides the specimen grid width (default 2).
+ * @param {object} [toc]  ExhibitSidebar props — `{ links, sections, basePath, docHref }`.
+ *   Omit entirely to leave the shell's rail alone.
+ */
+export default function ExhibitPage({ sections = [], toc }) {
+  useExhibitToc(toc ?? {})
+
+  return (
+    <div>
+      {sections.map(({ id, label, title, body, specimens, children, prose, columns = 2 }) => (
+        <PageSection key={id} id={id} label={label} title={title} body={body}>
+          {specimens?.length > 0 && (
+            <div
+              className="mt-8 grid gap-6 items-start"
+              style={{ gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))` }}
+            >
+              {specimens.map((s) => (
+                <div key={s.name} className="space-y-4">
+                  <ExhibitCard
+                    name={s.name}
+                    description={s.description}
+                    details={s.details}
+                    code={s.code}
+                  />
+                  {s.demo}
+                </div>
+              ))}
+            </div>
+          )}
+
+          {/* The reading measure is the reference implementation's, kept
+            * verbatim — kol-website's prose companions all wrap at 60ch on the
+            * body-02 rung. */}
+          {children && (
+            <div className={prose ? 'mt-8 max-w-[60ch] space-y-6 kol-sans-body-02' : 'mt-8'}>
+              {children}
+            </div>
+          )}
+        </PageSection>
+      ))}
+    </div>
+  )
+}

package/src/exhibit/ExhibitSidebar.jsx

@@ -0,0 +1,92 @@
+import { Link, useNavigate } from 'react-router-dom'
+import { DocsToc, Icon } from '@kolkrabbi/kol-component'
+import RailSection from '../shell/RailSection.jsx'
+import RailRow from '../shell/RailRow.jsx'
+
+/**
+ * ExhibitSidebar — the rail block an exhibit page registers into the shell's
+ * TOC slot: on-this-page, the section's documentation links, and quick actions.
+ * Recreated from kol-website's local `WorkshopSidebarContent`.
+ *
+ * THE DRIFT FIXED ON RECREATION. The source hand-rolled its own collapsible
+ * section: `.shell-sidebar-toggle` AND `.shell-sidebar-label` stacked on one
+ * element, inline `paddingRight`/`paddingBottom`/`justifyContent`, and its own
+ * chevron at L1. Every one of those is something RailSection exists to prevent
+ * — the eyebrow-box law in kol-components-workshop.css says an eyebrow wears
+ * ONE box class and sets no y-spacing inline, and the 2026-08-01 ruling says L1
+ * draws no chevron (it still collapses; the glyph is simply not there). The
+ * rungs come from RailSection now, so this block cannot drift from either rail.
+ * `pnpm validate:rails` R3 + R4 assert both halves.
+ *
+ * Router-agnostic in the same way as WorkshopSidebar: hrefs are built from
+ * `basePath`/`docHref`, never from an app singleton.
+ *
+ * @param {Array}  [sections] on-this-page entries for DocsToc: [{ id, title, level }]
+ * @param {Array}  [links]    documentation links: [{ id, label }]
+ * @param {string} [basePath] workshop mount point — drives the quick-action hrefs
+ * @param {Function} [docHref] `(id) => url`; omit for `${basePath}/docs/${id}`
+ * @param {boolean} [actions=true] render the quick-actions rung
+ */
+export default function ExhibitSidebar({
+  sections = [],
+  links = [],
+  basePath = '/workshop',
+  docHref = (id) => (id ? `${basePath}/docs/${id}` : `${basePath}/docs`),
+  actions = true,
+}) {
+  const navigate = useNavigate()
+
+  return (
+    <div className="shell-rail-stack-inner">
+      {sections.length > 0 && (
+        <RailSection level={1} label="On this page" icon={Icon}>
+          <DocsToc toc={sections} />
+        </RailSection>
+      )}
+
+      {links.length > 0 && (
+        <RailSection level={1} label="Documentation" icon={Icon}>
+          <nav className="shell-nav-items">
+            {links.map(({ id, label }) => (
+              <RailRow key={id} to={docHref(id)}>
+                {label}
+              </RailRow>
+            ))}
+          </nav>
+        </RailSection>
+      )}
+
+      {actions && (
+        <RailSection level={1} label="Quick actions" icon={Icon}>
+          <div className="space-y-1">
+            <button
+              type="button"
+              className="shell-sidebar-action kol-mono-14 text-body"
+              onClick={() => navigate(-1)}
+            >
+              <Icon name="arrow-left" size={14} />
+              Back
+            </button>
+            <Link to={docHref()} className="shell-sidebar-action kol-mono-14 text-body">
+              <Icon name="book-open" size={14} />
+              All documentation
+            </Link>
+            <Link to={basePath} className="shell-sidebar-action kol-mono-14 text-body">
+              <Icon name="layout" size={14} />
+              Workshop home
+            </Link>
+            <button
+              type="button"
+              className="shell-sidebar-action kol-mono-14 text-body"
+              onClick={() => navigator.clipboard?.writeText(window.location.pathname)}
+              title="Copy page path to clipboard"
+            >
+              <Icon name="copy" size={14} />
+              Copy path
+            </button>
+          </div>
+        </RailSection>
+      )}
+    </div>
+  )
+}

package/src/exhibit/index.js

@@ -0,0 +1,24 @@
+/**
+ * @kolkrabbi/kol-workshop — exhibit sections.
+ *
+ * The scaffold an exhibit section is built from, so adding the NEXT one is
+ * content and nothing else. The shell was already shared; the sections above it
+ * were not, and every consumer rebuilt the same landing page, the same
+ * specimen-grid page, the same prose companion and the same rail block by hand.
+ *
+ *   ExhibitOverview  the landing — concept, one opt-in action, children as cards
+ *   ExhibitPage      an inner page — sections of specimen grids and/or prose
+ *   ExhibitSidebar   the rail block: on-this-page · doc links · quick actions
+ *   useExhibitToc    registers that block into the shell's TOC slot
+ *   ExhibitCard      the specimen header inside a section
+ *   ExhibitLinkCard  the child-page card on a landing grid
+ *
+ * Content is consumer-injected, like everything else in this package — the
+ * exhibit declares cards, specimens and doc links; the package renders them.
+ */
+export { default as ExhibitOverview } from './ExhibitOverview.jsx'
+export { default as ExhibitPage } from './ExhibitPage.jsx'
+export { default as ExhibitSidebar } from './ExhibitSidebar.jsx'
+export { default as ExhibitCard } from './ExhibitCard.jsx'
+export { default as ExhibitLinkCard } from './ExhibitLinkCard.jsx'
+export { default as useExhibitToc } from './useExhibitToc.js'

package/src/exhibit/useExhibitToc.js

@@ -0,0 +1,32 @@
+import { createElement, useContext, useLayoutEffect } from 'react'
+import { ShellTocContext } from '../shell/ShellLayout.jsx'
+import ExhibitSidebar from './ExhibitSidebar.jsx'
+
+/**
+ * useExhibitToc — registers an ExhibitSidebar into the shell's TOC slot for as
+ * long as the page is mounted, and clears it on the way out.
+ *
+ * This is the six-line `useContext` + `useLayoutEffect` block that every exhibit
+ * page in kol-website copied verbatim. It takes DATA, not a node, on purpose:
+ * a caller passing `<Sidebar links={LINKS} />` hands over a fresh element every
+ * render, and an effect keyed on that identity would set shell state in a loop.
+ * Keying on the CONTENT of the props closes that, so a page can pass an inline
+ * array literal — which is what every one of them does.
+ *
+ * @param {object} props — ExhibitSidebar props: { sections, links, basePath, docHref, actions }
+ */
+export default function useExhibitToc(props = {}) {
+  const setTocContent = useContext(ShellTocContext)
+
+  /* Content, not identity — see the note above. */
+  const key = JSON.stringify([props.sections ?? [], props.links ?? [], props.basePath, props.actions])
+
+  useLayoutEffect(() => {
+    /* Outside a ShellLayout the context defaults to null; a page rendered
+     * standalone (a test, a preview route) must not throw over its rail. */
+    if (!setTocContent) return undefined
+    setTocContent(createElement(ExhibitSidebar, props))
+    return () => setTocContent(null)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [setTocContent, key])
+}

package/src/index.js

@@ -3,13 +3,14 @@
  *
  * Aggregates everything the package now owns: the shell composition
  * (ShellLayout + ShellSidebar + their contexts), the docs viewer, the tag
- * system, the example compositions, and the pure React-free engine. Duplicated
- * chrome (ShellHeader, ShellDrawer, SearchInput, ShellSearchOverlay, DocsToc)
- * ships from @kolkrabbi/kol-framework + @kolkrabbi/kol-component — consume it
- * from there, not from here.
+ * system, the exhibit-section scaffold, the example compositions, and the pure
+ * React-free engine. Duplicated chrome (ShellHeader, ShellDrawer, SearchInput,
+ * ShellSearchOverlay, DocsToc) ships from @kolkrabbi/kol-framework +
+ * @kolkrabbi/kol-component — consume it from there, not from here.
  */
 export * from './shell/index.js'
 export * from './docs/index.js'
 export * from './tags/index.js'
+export * from './exhibit/index.js'
 export * from './compositions/index.js'
 export * from './engine/index.js'