@kolkrabbi/kol-styleguide 0.11.0 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-styleguide",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "private": false,
   "description": "Brand guide components and the brand tool",
   "license": "MIT",
@@ -20,10 +20,10 @@
     "react-dom": "^18.3.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-framework": "^0.57.0",
+    "@kolkrabbi/kol-theme": "^0.194.0",
     "@kolkrabbi/kol-component": "^0.307.0",
-    "@kolkrabbi/kol-icons": "^0.47.0",
-    "@kolkrabbi/kol-theme": "^0.192.0"
+    "@kolkrabbi/kol-framework": "^0.59.0",
+    "@kolkrabbi/kol-icons": "^0.49.0"
   },
   "files": [
     "src",

package/src/BrandGuide.jsx

@@ -115,13 +115,16 @@ function Spec({ spec }) {
   return <Table variant="simple" caption={spec.caption ?? 'Specification'} columns={columns} rows={rows} className="mt-8" />
 }
 
-/* The contents: every indexed chapter as a row, its eyebrow carrying the number; grouped by `part` when the list has parts. */
-function Contents({ index }) {
+/* The contents: every indexed chapter as a row, its eyebrow carrying the number; grouped by `part` when the list has parts.
+ * A row with `to` is a route, opened through `onNavigate` (a plain link otherwise); without one it is an in-page anchor
+ * — apps/document's index reads it this way (plan-2026-10-28-document W3.3). */
+export function Contents({ index, onNavigate }) {
   if (!index.length) return null
   const parts = [...new Set(index.map((s) => s.part ?? ''))]
+  const go = (to) => (e) => { if (!onNavigate || e.metaKey || e.ctrlKey || e.shiftKey || e.button !== 0) return; e.preventDefault(); onNavigate(to) }
   const row = (s) => (
-    <li key={s.id}>
-      <IndexCard href={`#${s.id}`} onClick={scrollToAnchor} label={s.label} title={s.title ?? s.nav} />
+    <li key={s.to ?? s.id}>
+      <IndexCard href={s.href ?? s.to ?? `#${s.id}`} onClick={s.onClick ?? (s.to ? go(s.to) : scrollToAnchor)} label={s.label} title={s.title ?? s.nav} meta={s.meta} />
     </li>
   )
   return (

package/src/DocumentIndex.jsx

@@ -0,0 +1,45 @@
+import { useState } from 'react'
+import { FullscreenOverlay, KindPreview, PageHeader, QuickLookFrame, KIND_LABEL } from '@kolkrabbi/kol-component'
+import { Contents } from './BrandGuide.jsx'
+
+/* DOCUMENT INDEX — a folder's pages as the brand book's contents cards (BrandGuide's `Contents`, routed), grouped by
+ * `part` (plan-2026-10-28-document W3.3; home here since W5.2). A compact page header, never a hero: the cards are the page.
+ *
+ * A FILE IS A CARD TOO (DocumentIndexFilesAndIcons049, kol-website 2026-10-28 — a point of the MarkdownPage ticket: *"a
+ * folder may also hold PDFs and images; the contents index lists them beside the md pages and opens them in the DS
+ * QuickLook, not as pages"*): a row with `file` sits in its part like a page, its kind on the card's small line, and
+ * opens in the DS Quick Look window (`QuickLookFrame` over the dimmed page, `KindPreview` as the body — a PDF page by
+ * page, an image at its size), paging through the folder's files with ‹ ›. `documentFiles(glob)` in kol-framework makes
+ * the rows.
+ *
+ *   rows      [{ id, to, label?, title, part, meta? }] — a page: label is the card's eyebrow (an entry's parent), part the group
+ *             [{ id, file, title, part, ext?, kind? }]  — a file: the served URL; kind from the DS's `kindOf` when not given
+ *   title · lede   the header, when the index is a page of its own (Reviews); a folder's index sits under its document
+ *   onNavigate(to) the app's router */
+const fileLabel = (r) => KIND_LABEL[r.kind] ?? (r.ext ? r.ext.toUpperCase() : 'File')
+
+export default function DocumentIndex({ rows, title, lede, onNavigate }) {
+  const files = rows.filter((r) => r.file)
+  const [open, setOpen] = useState(null)   // index into `files`
+  const index = rows.map((r) => (r.file
+    ? { ...r, href: r.file, meta: r.meta ?? fileLabel(r), onClick: (e) => { if (e.metaKey || e.ctrlKey || e.shiftKey || e.button !== 0) return; e.preventDefault(); setOpen(files.indexOf(r)) } }
+    : r))
+  const cur = open === null ? null : files[open]
+  const step = (d) => setOpen((i) => (i + d + files.length) % files.length)
+  return (
+    <div className="kol-page flex flex-col gap-6">
+      {title && <PageHeader title={title} subtitle={lede} size="sm" voice="mono" />}
+      <Contents index={index} onNavigate={onNavigate} />
+      {cur && (
+        /* QUICK LOOK DIMS, it does not black out — the list stays in view (MediaLibraryPages' rule) */
+        <FullscreenOverlay open onClose={() => setOpen(null)} closeButton={false} scrim>
+          <QuickLookFrame title={cur.title} meta={fileLabel(cur)} onClose={() => setOpen(null)} nav={files.length > 1 ? { index: open, total: files.length, onPrev: () => step(-1), onNext: () => step(1) } : undefined}>
+            {cur.kind === 'image' || /^(png|jpe?g|webp|gif|svg|avif)$/i.test(cur.ext ?? '')
+              ? <img src={cur.file} alt={cur.title} className="kol-quicklook-media" />
+              : <KindPreview key={cur.file} o={{ key: cur.file.split('?')[0], url: cur.file }} fit="sheet" urlOf={(x) => x.url} />}
+          </QuickLookFrame>
+        </FullscreenOverlay>
+      )}
+    </div>
+  )
+}

package/src/index.js

@@ -25,6 +25,8 @@ export { generatePalette, fgOn, hexToHsl, hslToHex, GENERATION_MODES } from './c
 // The brand-book set the two brand apps were both maintaining locally
 // (brand-book-mocks-two-consumers, 2026-09-03).
 export { default as AssetCard } from './AssetCard.jsx'
+/* a folder's pages as the brand book's contents cards (plan-2026-10-28-document W5.2) */
+export { default as DocumentIndex } from './DocumentIndex.jsx'
 export { default as Swatch } from './Swatch.jsx'
 export {
   PostPhoto, PostType, PostProduct, PostEditorial, StoryPhoto, StoryType, BrandAvatar, ProfileAvatar,