@kolkrabbi/kol-workshop 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-workshop",
-  "version": "0.4.0",
+  "version": "0.5.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-icons": "0.8.11",
-    "@kolkrabbi/kol-framework": "0.9.1",
+    "@kolkrabbi/kol-component": "0.14.3",
+    "@kolkrabbi/kol-brand": "^0.1.2",
     "@kolkrabbi/kol-theme": "0.13.3",
-    "@kolkrabbi/kol-component": "0.14.2"
+    "@kolkrabbi/kol-framework": "0.9.1"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",

package/src/docs/DocsFrontmatter.jsx

@@ -21,22 +21,40 @@ const FIELD_ICONS = {
   modified: null,
 }
 
-/* THE kol-docs contract, in reading order — `.kol/docs-framework/01-conventions.md`:
- * required (title/type/status/updated/tags) then recommended (description,
- * aliases). `related` is excluded on purpose: the rail renders it as links.
+/* Reading ORDER, not an allowlist. The kol-docs contract first
+ * (`.kol/docs-framework/01-conventions.md`: required title/type/status/updated/
+ * tags, then recommended description/aliases, then optional), legacy
+ * sample-dialect keys after, and ANY key not named here after that — so a field
+ * can never be silently dropped for being unknown.
  *
- * This list read ['title','category','date','tags','modified'] — the
+ * This was a filter over ['title','category','date','tags','modified'] — the
  * workshop-SAMPLE dialect. No kol-docs document carries category/date/modified,
- * so the filter below admitted title + tags and silently dropped the other
- * seven fields the parser had already handed it. The panel wasn't missing data;
- * it was screening for the wrong schema. Sample-dialect keys stay at the tail
- * so those docs keep rendering. */
+ * so it admitted title + tags and discarded the seven fields the parser had
+ * already handed it. The panel wasn't missing data; it was screening for the
+ * wrong schema, and screening is now the thing it doesn't do.
+ *
+ * `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', 'created', 'verified',
-  'description', 'audience', 'aliases', 'tags',
-  'category', 'date', 'modified',
+  'title', 'type', 'status', 'updated', 'tags',
+  'description', 'aliases',
+  'created', 'verified', 'audience', 'superseded_by', 'drift',
+  'category', 'date', 'modified', 'version',
 ]
 
+const HIDDEN = new Set(['related'])
+
+/** Contract order first, then anything else the doc carries, alphabetically. */
+const orderFields = (metadata) => {
+  const present = Object.keys(metadata).filter(
+    (k) => !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]
+}
+
 /* 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'])
@@ -52,7 +70,7 @@ const DocsFrontmatter = ({ metadata, docId }) => {
   const { openTagMode } = useTagMode()
   if (!metadata || Object.keys(metadata).length === 0) return null
 
-  const fields = FIELD_ORDER.filter(key => metadata[key] != null && metadata[key] !== '')
+  const fields = orderFields(metadata)
 
   if (fields.length === 0) return null
 

package/src/docs/DocumentationReader.jsx

@@ -10,18 +10,41 @@ import DocsFrontmatter from './DocsFrontmatter.jsx'
 import { DocSection } from './DocKit.jsx'
 import { renderInlineTokens } from './render-tokens.jsx'
 
-const SidebarSection = ({ sectionKey, label, collapsedSections, toggleSection, children }) => (
-  <div>
-    <button
-      type="button"
-      className="shell-sidebar-toggle shell-sidebar-label kol-doc-eyebrow"
-      onClick={() => toggleSection(sectionKey)}
-    >
-      {label}
-    </button>
-    {!collapsedSections[sectionKey] && children}
-  </div>
-)
+/**
+ * A rail section header. Same anatomy as the LEFT tree's group header — a
+ * rotating chevron, the label, and the item count pushed right — because the
+ * two rails are one system and a reader shouldn't have to learn each side
+ * separately.
+ *
+ * These were bare text. They collapsed on click with no chevron, no count and
+ * no hover, so the only way to discover they were interactive was to click
+ * something that looked inert and watch the panel vanish. An affordance that
+ * only announces itself after you've used it isn't one.
+ */
+const SidebarSection = ({ sectionKey, label, count, collapsedSections, toggleSection, children }) => {
+  const isOpen = !collapsedSections[sectionKey]
+  return (
+    <div>
+      <button
+        type="button"
+        className="shell-nav-group-header w-full text-left shell-sidebar-label kol-doc-eyebrow"
+        onClick={() => toggleSection(sectionKey)}
+        aria-expanded={isOpen}
+      >
+        <span className="flex items-center gap-2">
+          <Icon
+            name="chevron-right"
+            size={12}
+            className={`transition-transform ${isOpen ? 'rotate-90' : ''}`}
+          />
+          {label}
+        </span>
+        {count > 0 && <span className="kol-mono-14 text-subtle">({count})</span>}
+      </button>
+      {isOpen && children}
+    </div>
+  )
+}
 
 const DocReaderSidebar = ({ toc, allTags, related, docId, docsIndexHref, componentsHref, docFilePath }) => {
   const navigate = useNavigate()
@@ -34,6 +57,7 @@ const DocReaderSidebar = ({ toc, allTags, related, docId, docsIndexHref, compone
       <SidebarSection
         sectionKey="toc"
         label="On this page"
+        count={toc?.length}
         collapsedSections={collapsedSections}
         toggleSection={toggleSection}
       >
@@ -44,6 +68,7 @@ const DocReaderSidebar = ({ toc, allTags, related, docId, docsIndexHref, compone
         <SidebarSection
           sectionKey="related"
           label="Related"
+          count={related.length}
           collapsedSections={collapsedSections}
           toggleSection={toggleSection}
         >
@@ -100,6 +125,7 @@ const DocReaderSidebar = ({ toc, allTags, related, docId, docsIndexHref, compone
       {allTags.length > 0 && (
         <SidebarSection
           sectionKey="tags"
+          count={allTags?.length}
           label="Tags"
           collapsedSections={collapsedSections}
           toggleSection={toggleSection}