@kolkrabbi/kol-workshop 0.3.3 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "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,9 +14,9 @@
   "dependencies": {
     "d3": "^7.9.0",
     "@kolkrabbi/kol-brand": "^0.1.2",
+    "@kolkrabbi/kol-icons": "0.8.11",
     "@kolkrabbi/kol-component": "0.14.1",
-    "@kolkrabbi/kol-icons": "0.8.10",
-    "@kolkrabbi/kol-framework": "0.7.0",
+    "@kolkrabbi/kol-framework": "0.8.0",
     "@kolkrabbi/kol-theme": "0.13.2"
   },
   "peerDependencies": {

package/src/docs/DocsArticle.jsx

@@ -1,7 +1,13 @@
 const join = (...classes) => classes.filter(Boolean).join(' ')
 
+/* NOT .kol-prose (wave-4 retype, 2026-07-30 — user law: one layout = one style
+ * system; prose is the blog/CMS voice, never docs surfaces). Every element the
+ * reader renders is typed explicitly through the kol-doc-* roles, mirroring
+ * showcase/src/lib/mdx-components.jsx — the SAME dialect MDX pages speak.
+ * Vertical rhythm comes from the flex gap (the MdxDoc content idiom), not
+ * prose margins. */
 const DocsArticle = ({ children, className }) => (
-  <article className={join('docs-article kol-prose', className)}>{children}</article>
+  <article className={join('docs-article flex w-full min-w-0 flex-col gap-6', className)}>{children}</article>
 )
 
 export default DocsArticle

package/src/docs/DocsHeader.jsx

@@ -1,9 +1,13 @@
 const join = (...classes) => classes.filter(Boolean).join(' ')
 
+/* Doc voice (wave-4 retype, 2026-07-30): title/subtitle ride the DocHeader
+ * contract roles (kol-doc-heading / kol-doc-lede) instead of the old
+ * kol-sans-heading-02 + kol-mono-14 pair — one header voice across the
+ * reader, MDX pages and the Doc* kit. */
 const DocsHeader = ({ title, subtitle, meta = [], className }) => (
-  <header className={join('docs-header', className)}>
-    {title ? <h1 className="kol-sans-heading-02 text-strong">{title}</h1> : null}
-    {subtitle ? <p className="kol-mono-14 text-meta">{subtitle}</p> : null}
+  <header className={join('docs-header flex flex-col gap-3', className)}>
+    {title ? <h1 className="kol-doc-heading">{title}</h1> : null}
+    {subtitle ? <p className="kol-doc-lede">{subtitle}</p> : null}
     {Array.isArray(meta) && meta.length > 0 ? (
       <div className="docs-meta kol-helper-10 text-body">
         {meta.map(({ label, value }) => (

package/src/docs/DocumentationReader.jsx

@@ -1,12 +1,13 @@
 import { useContext, useEffect, useMemo, useState } from 'react'
 import { useParams, Link, useNavigate } from 'react-router-dom'
-import { CodeBlock, Divider, DocsToc, Icon, Tag } from '@kolkrabbi/kol-component'
+import { CodeBlock, Divider, DocsToc, Icon, Table, Tag } from '@kolkrabbi/kol-component'
 import { ShellTocContext } from '../shell'
 import { useTagMode } from '../tags'
 import { parseDocsMarkdown, isIndexFile, getTagColor } from '../engine'
 import DocsHeader from './DocsHeader.jsx'
 import DocsArticle from './DocsArticle.jsx'
 import DocsFrontmatter from './DocsFrontmatter.jsx'
+import { DocSection } from './DocKit.jsx'
 import { renderInlineTokens } from './render-tokens.jsx'
 
 const SidebarSection = ({ sectionKey, label, collapsedSections, toggleSection, children }) => (
@@ -166,6 +167,82 @@ const DocumentationReader = ({
   const renderTokens = (tokens, tokenKey) =>
     renderInlineTokens(tokens, tokenKey, resolveDocLink, tagHref)
 
+  /* ONE block renderer for intro + section content (wave-4 retype, 2026-07-30
+   * — the two switches had already drifted). Every element is typed through
+   * the kol-doc-* dialect of showcase mdx-components.jsx: doc-body running
+   * text (self-caps at the measure), heading-05 h3/h4 (h4 = weight 400, the
+   * prose-h4 precedent), panel-capped furniture (width law: tables/code cap
+   * at --kol-content-panel), markdown tables through THE kol-component Table
+   * as a dynamic-column DocTable sibling (no parallel table markup). */
+  const renderBlock = (block, blockKey) => {
+    switch (block.type) {
+      case 'paragraph':
+        return (
+          <p key={blockKey} className="kol-doc-body">
+            {block.tokens ? renderTokens(block.tokens, blockKey) : block.content}
+          </p>
+        )
+      case 'heading3':
+        return (
+          <h3 key={blockKey} id={block.id} className="kol-sans-heading-05 text-emphasis scroll-mt-20 mt-2">
+            {block.content}
+          </h3>
+        )
+      case 'heading4':
+        return (
+          <h4 key={blockKey} id={block.id} className="kol-sans-heading-05 font-normal text-emphasis scroll-mt-20">
+            {block.content}
+          </h4>
+        )
+      case 'list': {
+        const ListComponent = block.ordered ? 'ol' : 'ul'
+        const listClass = `flex ${block.ordered ? 'list-decimal' : 'list-disc'} flex-col gap-2 pl-5 kol-doc-body`
+        return block.items ? (
+          <ListComponent key={blockKey} className={listClass}>
+            {block.items.map((item, itemIndex) => (
+              <li key={itemIndex}>
+                {item.tokens ? renderTokens(item.tokens, `${blockKey}-item-${itemIndex}`) : item.content || item}
+              </li>
+            ))}
+          </ListComponent>
+        ) : null
+      }
+      case 'blockquote':
+        return (
+          <blockquote key={blockKey} className="docs-callout kol-doc-body">
+            {block.tokens ? renderTokens(block.tokens, blockKey) : block.content}
+          </blockquote>
+        )
+      case 'divider':
+        return <Divider key={blockKey} className="docs-divider" opacity="12" />
+      case 'code':
+        return (
+          <div key={blockKey} className="max-w-[var(--kol-content-panel)]">
+            <CodeBlock code={block.lines.join('\n')} language={block.lang} />
+          </div>
+        )
+      case 'table':
+        return (
+          <div key={blockKey} className="max-w-[var(--kol-content-panel)]">
+            <Table
+              variant="simple"
+              columns={block.headers.map((header, i) => ({ accessor: `c${i}`, header }))}
+              rows={block.rows.map((row, rowIndex) => ({
+                id: rowIndex,
+                ...Object.fromEntries(row.map((cell, cellIndex) => [
+                  `c${cellIndex}`,
+                  cell.tokens ? renderTokens(cell.tokens, `${blockKey}-row-${rowIndex}-cell-${cellIndex}`) : cell.content,
+                ])),
+              }))}
+              className="kol-doc-table"
+            />
+          </div>
+        )
+      default:
+        return null
+    }
+  }
+
   const doc = useMemo(() => {
     return inventory.find((d) => d.id === docId)
   }, [inventory, docId])
@@ -254,172 +331,19 @@ const DocumentationReader = ({
     <DocsArticle>
         <DocsFrontmatter metadata={doc.metadata} docId={docId} />
         {docTitle && (
-          <h1>{docTitle}</h1>
+          <h1 className="kol-doc-heading">{docTitle}</h1>
         )}
         {/* Render intro blocks (excluding H1 which is docTitle) */}
-        {introBlocks.filter(b => b.type !== 'heading1').map((block, index) => {
-          const blockKey = `intro-${block.type}-${index}`
-          switch (block.type) {
-            case 'paragraph':
-              return (
-                <p key={blockKey}>
-                  {block.tokens ? renderTokens(block.tokens, blockKey) : block.content}
-                </p>
-              )
-            case 'heading3':
-              return (
-                <h3 key={blockKey} id={block.id}>
-                  {block.content}
-                </h3>
-              )
-            case 'heading4':
-              return (
-                <h4 key={blockKey} id={block.id}>
-                  {block.content}
-                </h4>
-              )
-            case 'list':
-              return block.items ? (
-                <ul key={blockKey} className="docs-list tight">
-                  {block.items.map((item, i) => (
-                    <li key={i}>
-                      {item.tokens ? renderTokens(item.tokens, `${blockKey}-item-${i}`) : item.content}
-                    </li>
-                  ))}
-                </ul>
-              ) : null
-            case 'blockquote':
-              return (
-                <blockquote key={blockKey} className="docs-callout">
-                  {block.tokens ? renderTokens(block.tokens, blockKey) : block.content}
-                </blockquote>
-              )
-            case 'divider':
-              return <Divider key={blockKey} className="docs-divider" opacity="12" />
-            case 'code':
-              return (
-                <CodeBlock
-                  key={blockKey}
-                  code={block.lines.join('\n')}
-                  language={block.lang}
-                />
-              )
-            case 'table':
-              return (
-                <div key={blockKey} className="kol-table-wrapper kol-table--simple">
-                  <table className="kol-table">
-                    <thead className="kol-table-thead">
-                      <tr>
-                        {block.headers.map((header, headerIndex) => (
-                          <th key={headerIndex} className="kol-table-cell-title">{header}</th>
-                        ))}
-                      </tr>
-                    </thead>
-                    <tbody>
-                      {block.rows.map((row, rowIndex) => (
-                        <tr key={rowIndex} className="kol-table-row">
-                          {row.map((cell, cellIndex) => (
-                            <td key={cellIndex} className="kol-table-cell-text">
-                              {cell.tokens ? renderTokens(cell.tokens, `${blockKey}-row-${rowIndex}-cell-${cellIndex}`) : cell.content}
-                            </td>
-                          ))}
-                        </tr>
-                      ))}
-                    </tbody>
-                  </table>
-                </div>
-              )
-            default:
-              return null
-          }
-        })}
+        {introBlocks.filter(b => b.type !== 'heading1').map((block, index) =>
+          renderBlock(block, `intro-${block.type}-${index}`)
+        )}
 
+        {/* Sections through the packaged DocSection — the same anchored
+          * rule + h2 contract MDX pages compose with. */}
         {sections.map(({ heading, id, blocks }) => (
-          <section key={id} id={id} className="space-y-6 scroll-mt-32">
-            <h2>{heading}</h2>
-            {blocks.map((block, index) => {
-              const blockKey = `${id}-${block.type}-${index}`
-
-              switch (block.type) {
-                case 'heading3':
-                  return (
-                    <h3 key={blockKey} id={block.id}>
-                      {block.content}
-                    </h3>
-                  )
-                case 'heading4':
-                  return (
-                    <h4 key={blockKey} id={block.id}>
-                      {block.content}
-                    </h4>
-                  )
-                case 'paragraph':
-                  return (
-                    <p key={blockKey}>
-                      {block.tokens ? renderTokens(block.tokens, blockKey) : block.content}
-                    </p>
-                  )
-                case 'list': {
-                  const listClass = block.ordered
-                    ? 'docs-list docs-list--ordered tight'
-                    : 'docs-list tight'
-                  const ListComponent = block.ordered ? 'ol' : 'ul'
-                  return (
-                    <ListComponent key={blockKey} className={listClass}>
-                      {block.items.map((item, itemIndex) => (
-                        <li key={itemIndex}>
-                          {item.tokens ? renderTokens(item.tokens, `${blockKey}-item-${itemIndex}`) : item.content || item}
-                        </li>
-                      ))}
-                    </ListComponent>
-                  )
-                }
-                case 'code':
-                  return (
-                    <CodeBlock
-                      key={blockKey}
-                      code={block.lines.join('\n')}
-                      language={block.lang}
-                    />
-                  )
-                case 'blockquote':
-                  return (
-                    <blockquote key={blockKey} className="docs-callout">
-                      {block.tokens ? renderTokens(block.tokens, blockKey) : block.content}
-                    </blockquote>
-                  )
-                case 'divider':
-                  return <Divider key={blockKey} className="docs-divider" opacity="12" />
-                case 'table':
-                  return (
-                    <div key={blockKey} className="kol-table-wrapper kol-table--simple">
-                      <table className="kol-table">
-                        <thead className="kol-table-thead">
-                          <tr>
-                            {block.headers.map((header, headerIndex) => (
-                              <th key={headerIndex} className="kol-table-cell-title">{header}</th>
-                            ))}
-                          </tr>
-                        </thead>
-                        <tbody>
-                          {block.rows.map((row, rowIndex) => (
-                            <tr key={rowIndex} className="kol-table-row">
-                              {row.map((cell, cellIndex) => (
-                                <td key={cellIndex} className="kol-table-cell-text">
-                                  {cell.tokens ? renderTokens(cell.tokens, `${blockKey}-row-${rowIndex}-cell-${cellIndex}`) : cell.content}
-                                </td>
-                              ))}
-                            </tr>
-                          ))}
-                        </tbody>
-                      </table>
-                    </div>
-                  )
-                default:
-                  return null
-              }
-            })}
-          </section>
+          <DocSection key={id} id={id} title={heading}>
+            {blocks.map((block, index) => renderBlock(block, `${id}-${block.type}-${index}`))}
+          </DocSection>
         ))}
       </DocsArticle>
   )

package/src/docs/render-tokens.jsx

@@ -37,15 +37,19 @@ export const renderInlineTokens = (
         return <em key={tokenKey}>{token.content}</em>
 
       case 'code':
-        return <code key={tokenKey}>{token.content}</code>
+        return <code key={tokenKey} className="kol-doc-code-inline">{token.content}</code>
 
       case 'link': {
+        /* One link idiom across doc surfaces (wave-4 retype): the anchor
+         * treatment from showcase mdx-components.jsx — colorless per the
+         * link law, emphasis + quiet underline. */
+        const linkCls = 'text-emphasis underline decoration-fg-16 underline-offset-2 hover:decoration-current'
         // For .md links, try to resolve to an app route
         if (resolveDocLink && token.url.includes('.md')) {
           const route = resolveDocLink(token.url)
           if (route) {
             return (
-              <Link key={tokenKey} to={route} className="docs-link">
+              <Link key={tokenKey} to={route} className={linkCls}>
                 {token.text}
               </Link>
             )
@@ -54,7 +58,7 @@ export const renderInlineTokens = (
           return token.text
         }
         return (
-          <a key={tokenKey} href={token.url} className="docs-link">
+          <a key={tokenKey} href={token.url} className={linkCls}>
             {token.text}
           </a>
         )