@miragon/slidev-toolkit 1.5.0 → 1.6.0

package/components/Agenda.vue

@@ -1,32 +1,23 @@
 <script setup lang="ts">
 /**
- * Agenda — the red thread at the chapter level (STATIC world, no shader).
+ * Agenda — a clickable chapter stepper over the live deck.
  *
- * A clickable stepper across the deck's chapters (numbered dots strung on one
- * continuous line, chapter labels centred above each dot); below it, the slides
- * of the selected chapter render as LIVE miniature previews (the same mechanism
- * the Slidev overview uses, not iframes or screenshots) and auto-fit the
- * remaining space, shrinking as a chapter holds more slides. Clicking a chapter
- * switches the preview; clicking a mini jumps to that slide. Because chapters
- * and slides are read from the live deck, the agenda updates itself.
+ * Chapters are discovered automatically: every `layout: section` slide opens a
+ * chapter, the slides up to the next section belong to it. Up to six chapters the
+ * rail is one row with each chapter's slides as live miniature previews below.
+ * Past six the rail WRAPS into balanced rows and drops the previews, becoming a
+ * static, top-aligned overview.
  *
- * Chapters are discovered automatically: every `layout: section` slide starts a
- * chapter, and the slides up to the next section belong to it.
- *
- * Frontmatter / props:
- *   eyebrow — uppercase kicker (default "Agenda")
- *   title   — optional h2-level title
- *   accent  — "blue" | "green" | "mixed" (default mixed)
+ * Props: eyebrow (kicker, default "Agenda"), title (h2), accent (blue|green|mixed).
  */
 import { computed, ref, watch } from 'vue'
 import { useElementSize } from '@vueuse/core'
 import { useNav } from '@slidev/client'
-// The `.ts` extension is required for Vite to resolve these deep imports (the
-// @slidev/client `exports` map is `"./*": "./*"`, which adds no extension), but
-// tsc/Volar reject it without `allowImportingTsExtensions`; suppress there.
-// @ts-ignore - .ts extension needed for Vite resolution, not for type-checking
+// The `.ts` extension is required for Vite to resolve these deep imports, but
+// tsc/Volar reject it without `allowImportingTsExtensions`, so suppress there.
+// @ts-ignore
 import { createFixedClicks } from '@slidev/client/composables/useClicks.ts'
-// @ts-ignore - .ts extension needed for Vite resolution, not for type-checking
+// @ts-ignore
 import { CLICKS_MAX } from '@slidev/client/constants.ts'
 import SlideContainer from '@slidev/client/internals/SlideContainer.vue'
 import SlideWrapper from '@slidev/client/internals/SlideWrapper.vue'
@@ -59,13 +50,8 @@ interface Chapter {
   routes: any[]
 }
 
-// Walk the deck once: each `layout: section` slide opens a chapter, every slide
-// after it (until the next section) belongs to that chapter. Slides before the
-// first section (cover, this agenda) are intentionally ignored.
 const chapters = computed<Chapter[]>(() => {
   const out: Chapter[] = []
-  // slides.value is typed loosely (SlideRoute's deep types don't resolve in the
-  // editor), so annotate as any[] to read .meta/.no without TS2339.
   for (const route of slides.value as any[]) {
     const fm = route.meta?.slide?.frontmatter ?? {}
     if (fm.layout === 'section') {
@@ -85,8 +71,7 @@ const chapters = computed<Chapter[]>(() => {
 
 const selected = ref(0)
 
-// Keep the selection valid and follow the live position: if the deck is on a
-// slide that lives inside a chapter, preselect that chapter.
+// Follow the live position: preselect the chapter holding the current slide.
 watch(
   [chapters, currentPage],
   ([chs, page]) => {
@@ -101,35 +86,59 @@ watch(
 
 const activeChapter = computed(() => chapters.value[selected.value])
 
-// A chapter of up to MAX_MINIS slides renders cleanly in the available height.
-// ALL slides are always rendered, but the mini size is computed as if the
-// chapter held at most MAX_MINIS: so the frame size never shrinks below the
-// clean 21-slide size, and any slides past that simply extend below the fold,
-// reachable by scrolling the preview.
+// Mini size is computed as if a chapter held at most this many slides, so the
+// frame never shrinks below the clean size; extra slides scroll below the fold.
 const MAX_MINIS = 21
 
-// Above five chapters the single row of labels crowds. Stagger them above/below
-// the line (chapter 1 above, 2 below, ...) so each label only neighbours the one
-// two steps away, which roughly doubles its horizontal breathing room.
+// Above five chapters one label row crowds, so stagger labels above/below the line.
 const alternate = computed(() => chapters.value.length > 5)
 
-// Geometry of the connecting thread: dots are centred in their equal columns,
-// so the line runs from the first dot centre to the last, and the coloured fill
-// reaches the selected dot.
+// Past six chapters the labels no longer fit one row: wrap the dots into balanced
+// rows (max five each) and drop the previews for a static, top-aligned overview.
+const WRAP_THRESHOLD = 6
+const MAX_PER_ROW = 5
+const wrap = computed(() => chapters.value.length > WRAP_THRESHOLD)
+
+interface StepRow { items: Chapter[]; start: number; cols: number }
+// Balanced rows sharing one column count so dots align into a grid: 8->4+4, 7->4+3.
+const rows = computed<StepRow[]>(() => {
+  const chs = chapters.value
+  const rowCount = Math.max(1, Math.ceil(chs.length / MAX_PER_ROW))
+  const cols = Math.max(1, Math.ceil(chs.length / rowCount))
+  const out: StepRow[] = []
+  for (let i = 0; i < chs.length; i += cols) out.push({ items: chs.slice(i, i + cols), start: i, cols })
+  return out
+})
+
+// The chapter holding the current slide (-1 before the first chapter).
+const currentIndex = computed(() =>
+  chapters.value.findIndex(
+    (c, i) =>
+      currentPage.value >= c.no &&
+      (i === chapters.value.length - 1 || currentPage.value < chapters.value[i + 1].no),
+  ),
+)
+
+// Per-row thread geometry: line through the row's dot centres, fill up to current.
+function rowTrackLeft(row: StepRow) { return `${50 / row.cols}%` }
+function rowTrackWidth(row: StepRow) { return `${((row.items.length - 1) * 100) / row.cols}%` }
+function rowFillWidth(row: StepRow) {
+  const seg = Math.max(0, Math.min(currentIndex.value - row.start, row.items.length - 1))
+  return `${(seg * 100) / row.cols}%`
+}
+
+// Single-row thread geometry: line from first to last dot centre, fill to selected.
 const trackLeft = computed(() => `${50 / chapters.value.length}%`)
 const trackWidth = computed(() => `${((chapters.value.length - 1) * 100) / chapters.value.length}%`)
 const fillWidth = computed(() => `${(selected.value * 100) / chapters.value.length}%`)
 
-// A mini renders at fixed clicks (fully revealed). Cache one context per route.
 const clicksCtx = new WeakMap<object, ReturnType<typeof createFixedClicks>>()
 function ctxFor(route: any) {
   if (!clicksCtx.has(route)) clicksCtx.set(route, createFixedClicks(route, CLICKS_MAX))
   return clicksCtx.get(route)!
 }
 
-// Auto-fit the minis into whatever space is left below the stepper: measure the
-// stage, then pick the largest mini width whose grid (N items, 16:9) still fits
-// both the width and the remaining height. More slides => more rows => smaller.
+// Pick the largest mini width whose grid (N items, 16:9) fits the leftover space.
 const stage = ref<HTMLElement | null>(null)
 const { width: stageW, height: stageH } = useElementSize(stage)
 const GAP = 16
@@ -137,8 +146,6 @@ const ASPECT = 16 / 9
 const MAX_W = 320
 
 const miniWidth = computed(() => {
-  // Size as if the chapter held at most MAX_MINIS slides, so the frame never
-  // shrinks below the clean 21-slide size; extra slides scroll below the fold.
   const n = Math.min(activeChapter.value?.routes.length ?? 0, MAX_MINIS)
   const W = stageW.value
   const H = stageH.value
@@ -150,13 +157,11 @@ const miniWidth = computed(() => {
     const totalH = rows * (w / ASPECT) + (rows - 1) * GAP
     if (totalH <= H && w > best) best = w
   }
-  if (!best) best = (W - (n - 1) * GAP) / n // never larger than one row across
+  if (!best) best = (W - (n - 1) * GAP) / n
   return Math.max(96, Math.min(best, MAX_W))
 })
 
-// After a click, drop focus off the <button> back to the document, otherwise the
-// focused button swallows Slidev's arrow-key navigation and the next-slide key
-// stops working until the user clicks the slide again.
+// Blur after a click so the button stops swallowing Slidev's arrow-key navigation.
 function selectChapter(i: number, ev: MouseEvent) {
   selected.value = i
   ;(ev.currentTarget as HTMLElement | null)?.blur()
@@ -176,8 +181,30 @@ function openSlide(no: number, ev: MouseEvent) {
         <h2 v-if="title" class="agenda-title">{{ title }}</h2>
       </header>
 
-      <!-- Stepper: labels centred above numbered dots strung on one line. -->
-      <nav class="agenda-stepper" :class="{ 'is-alternating': alternate }" aria-label="Chapters">
+      <!-- Many chapters: wrapped rows, top-aligned, static (no previews to navigate). -->
+      <nav v-if="wrap" class="agenda-stepper is-wrap" aria-label="Chapters">
+        <div v-for="(row, r) in rows" :key="r" class="stepper-row" :style="{ '--cols': row.cols }">
+          <div class="track" aria-hidden="true">
+            <span class="track-line" :style="{ left: rowTrackLeft(row), width: rowTrackWidth(row) }"></span>
+            <span class="track-fill" :style="{ left: rowTrackLeft(row), width: rowFillWidth(row) }"></span>
+          </div>
+          <div
+            v-for="(ch, i) in row.items"
+            :key="ch.no"
+            class="step is-static"
+            :class="{ 'is-active': row.start + i === currentIndex, 'is-done': row.start + i < currentIndex }"
+          >
+            <span class="step-meta">
+              <span class="step-eyebrow">{{ ch.eyebrow }}</span>
+              <span class="step-label">{{ ch.title }}</span>
+            </span>
+            <span class="step-dot"><span class="step-num">{{ row.start + i + 1 }}</span></span>
+          </div>
+        </div>
+      </nav>
+
+      <!-- Up to six chapters: one clickable row that drives the previews below. -->
+      <nav v-else class="agenda-stepper" :class="{ 'is-alternating': alternate }" aria-label="Chapters">
         <div class="track" aria-hidden="true">
           <span class="track-line" :style="{ left: trackLeft, width: trackWidth }"></span>
           <span class="track-fill" :style="{ left: trackLeft, width: fillWidth }"></span>
@@ -198,8 +225,7 @@ function openSlide(no: number, ev: MouseEvent) {
         </button>
       </nav>
 
-      <!-- Preview: the selected chapter's slides as live miniatures, auto-fit. -->
-      <div class="agenda-preview">
+      <div v-if="!wrap" class="agenda-preview">
         <div ref="stage" class="preview-stage">
           <transition name="fade-preview" mode="out-in">
             <div :key="selected" class="preview-row">
@@ -227,8 +253,7 @@ function openSlide(no: number, ev: MouseEvent) {
 
 <style scoped>
 .agenda-layout {
-  /* Declared so the custom properties resolve statically (linter + fallback);
-     the inline :style binding on this element overrides them at runtime. */
+  /* Fallback for the linter; the inline :style binding overrides at runtime. */
   --ag-grad: var(--miragon-gradient-mixed);
   --ag-accent: var(--miragon-blue);
   position: absolute;
@@ -290,7 +315,6 @@ function openSlide(no: number, ev: MouseEvent) {
   align-items: end;
   margin-bottom: 1.5rem;
 }
-/* the one continuous thread, drawn through the dot centres */
 .track {
   position: absolute;
   left: 0;
@@ -374,9 +398,7 @@ function openSlide(no: number, ev: MouseEvent) {
 }
 .step.is-done .step-dot { border-color: var(--ag-accent); }
 .step.is-done .step-num { color: var(--ag-accent); }
-/* Solid accent fill, not the mixed gradient: on a small circle the blue->green
-   gradient muddies into an ugly green corner. Flat fill, border matches the fill
-   so no inner ring (no inset sheen) shows through. */
+/* Flat accent fill (a gradient muddies into green on a small circle). */
 .step.is-active .step-dot {
   background: var(--ag-accent);
   border-color: var(--ag-accent);
@@ -385,20 +407,13 @@ function openSlide(no: number, ev: MouseEvent) {
 }
 .step.is-active .step-num { color: var(--miragon-white); }
 
-/* ---- Alternating labels (only above five chapters) ---------------------- */
-/* One label row crowds past five chapters, so stagger labels above/below the
-   line. Each step becomes a grid with FIXED, EQUAL top and bottom zones and the
-   dot in the centre row, so every dot lands dead centre on the one line no
-   matter which side carries the label. Labels are single-line (nowrap), so a
-   fixed zone always fits eyebrow + title. */
+/* ---- Alternating labels (above five chapters) --------------------------- */
+/* Dot stays in flow so columns stay equal; each label is absolute and centred on
+   its dot, above for odd chapters and below for even, so a wide label can't widen
+   its column. Labels are single-line, so the fixed zone always fits them. */
 .agenda-stepper.is-alternating {
   align-items: stretch;
 }
-/* Only the dot stays in flow (a fixed 2.2rem, far under a 1fr column), so the
-   columns remain strictly equal and the dots are evenly spaced. Each label is
-   taken OUT of flow (absolute) and centred on its own dot, above for odd
-   chapters and below for even ones, so a wide label can never widen its column
-   and throw the spacing off. */
 .agenda-stepper.is-alternating .step {
   position: relative;
   min-width: 0;
@@ -419,23 +434,55 @@ function openSlide(no: number, ev: MouseEvent) {
 .agenda-stepper.is-alternating .step.label-below .step-meta {
   top: calc(50% + 1.7rem);
   bottom: auto;
-  /* Flip eyebrow/title so the title sits next to the line and "Kapitel 0X" stays
-     on the outer edge, mirroring the row above. */
   flex-direction: column-reverse;
 }
-/* Labels are centred on their dot and same-level neighbours are two steps apart,
-   so show them at full width instead of clipping to one column. */
 .agenda-stepper.is-alternating .step-label {
   overflow: visible;
   text-overflow: clip;
   max-width: none;
 }
-/* The thread runs through the vertically centred dots. */
 .agenda-stepper.is-alternating .track {
   top: 50%;
   bottom: auto;
 }
 
+/* ---- Wrapping rail (above six chapters, no previews) -------------------- */
+/* Each row is its own grid with its own thread, so the line never bridges a wrap.
+   Top-aligned to hug the head instead of floating in whitespace. */
+.agenda-stepper.is-wrap {
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  justify-content: flex-start;
+  gap: 2.8rem;
+  flex: 1 1 auto;
+  min-height: 0;
+  margin-bottom: 0;
+}
+.is-wrap .step.is-static { cursor: default; }
+.stepper-row {
+  position: relative;
+  display: grid;
+  grid-template-columns: repeat(var(--cols), 1fr);
+  align-items: end;
+}
+/* Reserved height so two-line labels bottom-align and every dot lands on the line. */
+.is-wrap .step-meta {
+  min-height: 3.4rem;
+  justify-content: flex-end;
+}
+.is-wrap .step-label {
+  white-space: normal;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  line-clamp: 2;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  max-width: 100%;
+  line-height: 1.2;
+}
+
 /* ---- Preview ------------------------------------------------------------ */
 .agenda-preview {
   flex: 1 1 auto;
@@ -446,18 +493,13 @@ function openSlide(no: number, ev: MouseEvent) {
 .preview-stage {
   flex: 1 1 auto;
   min-height: 0;
-  /* Safety net: minis are sized to fit up to MAX_MINIS within this height, but
-     if a capped chapter still overflows (short viewport), scroll to reach the
-     rest rather than clip or shrink them further. */
-  overflow-y: auto;
+  overflow-y: auto; /* scroll to reach the rest if a capped chapter overflows */
 }
 .preview-row {
   min-height: 100%;
   display: flex;
   flex-wrap: wrap;
-  /* `safe` centers when the minis fit, but falls back to top-alignment once the
-     chapter overflows, so the first row never lands above the scroll origin
-     (where it would be unreachable). */
+  /* `safe` centers when minis fit, else top-aligns so the first row stays reachable. */
   align-content: safe center;
   justify-content: center;
   gap: 16px;

package/components/Card.vue

@@ -90,17 +90,37 @@ const ACCENTS: Record<string, string> = {
   line-height: 1.55;
   color: #4b5563;
 }
-/* Wrapping the body in blank lines (required for inline Markdown — `code`, **bold**,
-   links — to render inside the slot; see the slides skill) makes Markdown emit a
-   <p>. Left alone it would inherit Slidev's larger prose paragraph size and default
-   margins, so a block-form card would look different from a tight one. Normalise it:
-   inherit the card body size, no outer margins, even spacing between paragraphs. */
+/* Blank-line-wrapped inline Markdown emits a <p>; normalise it to the card body size (no prose bloat). */
 .mg-card__body :deep(p) {
   margin: 0;
   font-size: inherit;
   line-height: inherit;
 }
 .mg-card__body :deep(p + p) { margin-top: 0.6em; }
+/* Same for bullet lists: normalise to the body size with a small blue square marker (like the content layout). */
+.mg-card__body :deep(ul) {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+.mg-card__body :deep(li) {
+  position: relative;
+  font-size: inherit;
+  line-height: inherit;
+  padding-left: 1.1rem;
+  margin: 0;
+}
+.mg-card__body :deep(li + li) { margin-top: 0.4em; }
+.mg-card__body :deep(li)::before {
+  content: '';
+  position: absolute;
+  left: 0;
+  top: 0.55em;
+  width: 0.4rem;
+  height: 0.4rem;
+  border-radius: 0.1rem;
+  background: var(--miragon-blue);
+}
 .mg-card--compact .mg-card__body { flex: 1 1 auto; display: flex; flex-direction: column; }
 /* A trailing diagram (<Figure src>) docks at the card bottom, so the image sits at
    the same position in every card of a stretched grid regardless of text length. */

package/components/Step.vue

@@ -1,6 +1,8 @@
 <script setup lang="ts">
 /**
- * Step — eine Zeile in einer <StepList>: fett gesetztes Label + Fließtext.
+ * Step — eine Zeile in einer <StepList>: nummeriertes Badge + fett gesetztes
+ * Label + Fließtext. Die Nummer kommt aus einem CSS-Counter, den die StepList
+ * zurücksetzt und jeder Step erhöht (kein index-Prop nötig).
  * Das Label nutzt die primäre Textfarbe, der Body erbt die Farbe der StepList.
  *   <Step label="Client">ruft … auf</Step>
  */
@@ -8,10 +10,35 @@ defineProps<{ label?: string }>()
 </script>
 
 <template>
-  <div class="step"><strong v-if="label" class="step__label">{{ label }}:</strong> <slot /></div>
+  <div class="step">
+    <span class="step__marker" aria-hidden="true"></span>
+    <span class="step__body"><strong v-if="label" class="step__label">{{ label }}:</strong> <slot /></span>
+  </div>
 </template>
 
 <style scoped>
+.step {
+  display: flex;
+  align-items: baseline;
+  gap: 0.6rem;
+  counter-increment: miragon-step;
+}
+.step__marker {
+  flex: 0 0 auto;
+  align-self: flex-start;
+  width: 1.5rem;
+  height: 1.5rem;
+  border-radius: 50%;
+  background: var(--miragon-blue);
+  color: #fff;
+  font-size: 0.75rem;
+  font-weight: 700;
+  line-height: 1.5rem;
+  text-align: center;
+}
+.step__marker::before {
+  content: counter(miragon-step);
+}
 .step__label {
   font-weight: 700;
   color: var(--miragon-text-primary);

package/components/StepList.vue

@@ -20,9 +20,10 @@
 .step-list {
   display: flex;
   flex-direction: column;
-  gap: 0.65rem;
-  font-size: 0.8rem;
-  line-height: 1.4;
+  gap: 0.95rem;
+  font-size: 1.2rem;
+  line-height: 1.5;
   color: var(--miragon-text-secondary);
+  counter-reset: miragon-step;
 }
 </style>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@miragon/slidev-toolkit",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "Miragon Slidev toolkit: the brand theme, the layout archetypes, the reusable components (Card, CardGrid, StepList, Figure, SplitView) and the BrandMeshBackground animation. Single source of design truth, consumed by the reference deck in this repo.",
   "keywords": [
     "slidev-theme",
@@ -20,7 +20,10 @@
     "slidev": ">=0.48.0"
   },
   "dependencies": {
-    "@paper-design/shaders": "0.0.77"
+    "@paper-design/shaders": "0.0.78"
+  },
+  "devDependencies": {
+    "@slidev/types": "52.18.0"
   },
   "peerDependencies": {
     "vue": "^3.5.0"
@@ -31,6 +34,7 @@
     "styles",
     "assets",
     "global",
+    "setup",
     "global-top.vue",
     "global-bottom.vue"
   ],

package/setup/mermaid.ts

@@ -0,0 +1,32 @@
+import { defineMermaidSetup } from '@slidev/types'
+
+// Brand-styles every ```mermaid diagram with the Miragon palette and Geist, so
+// text-generated diagrams stay on-brand. Slidev collects setup/* from every root
+// (theme included), so shipping this in the theme package means every deck that
+// sets `theme: '@miragon/slidev-toolkit'` inherits it with zero config. A deck can
+// still override by adding its own setup/mermaid.ts, but never has to.
+// The hex values mirror the tokens in ../styles/theme.css; they live here (config),
+// never in slide markdown, so the "no hardcoded hex in markdown" rule stays intact.
+// Excalidraw remains the default for diagrams; Mermaid is for text-generated flows.
+export default defineMermaidSetup(() => ({
+  theme: 'base',
+  themeVariables: {
+    // Nodes: light-blue fill, Miragon-blue border, black label text
+    primaryColor: '#F0F4FF', // --miragon-blue-light
+    primaryBorderColor: '#335DE5', // --miragon-blue
+    primaryTextColor: '#000000', // --miragon-text-primary
+
+    // Edges and their labels
+    lineColor: '#335DE5', // --miragon-blue
+    edgeLabelBackground: '#F5F7FF', // --miragon-blue-soft
+
+    // Secondary / tertiary surfaces (sequence actor boxes, alt-blocks, notes)
+    secondaryColor: '#F5F7FF', // --miragon-blue-soft
+    secondaryBorderColor: '#2B4ACB', // --miragon-blue-mid
+    tertiaryColor: '#FFFFFF',
+    tertiaryBorderColor: '#335DE5',
+
+    // Typography: Geist, matching the theme's body font
+    fontFamily: "'Geist', 'Inter', 'Helvetica Neue', Arial, sans-serif",
+  },
+}))