@humanforest/slidev-theme 0.1.0

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@humanforest/slidev-theme",
+  "version": "0.1.0",
+  "description": "Forest brand theme for Slidev — the guardrail. Layouts + components wired to @humanforest/tokens, so any deck is on-brand by construction. Do not hand-pick colours/fonts here; everything aliases the engine tokens.",
+  "keywords": [
+    "slidev-theme",
+    "slidev",
+    "theme",
+    "forest"
+  ],
+  "license": "SEE LICENSE IN LICENSE",
+  "scripts": {
+    "test": "vitest run"
+  },
+  "engines": {
+    "node": ">=18.0.0",
+    "slidev": ">=0.50.0"
+  },
+  "slidev": {
+    "colorSchema": "light",
+    "defaults": {
+      "transition": "view-transition",
+      "aspectRatio": "16/9",
+      "canvasWidth": 1920,
+      "fonts": {
+        "sans": "GT Haptik",
+        "mono": "JetBrains Mono",
+        "provider": "none",
+        "local": "GT Haptik,JetBrains Mono,MohrAlt"
+      }
+    }
+  },
+  "dependencies": {
+    "@humanforest/fonts": "^0.1.0",
+    "@humanforest/frames": "^0.1.0",
+    "@humanforest/tokens": "^0.1.0",
+    "@humanforest/ui": "^0.1.0",
+    "@iconify-json/lucide": "^1.2.0",
+    "@iconify-json/vscode-icons": "^1.2.75",
+    "@unovis/ts": "^1.6.7",
+    "@unovis/vue": "^1.6.7",
+    "mapbox-gl": "^3.28.1",
+    "mermaid": "^11.17.2"
+  },
+  "devDependencies": {
+    "@unocss/preset-wind3": "^66.7.5",
+    "unocss": "^66.7.5",
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "unocss": ">=66"
+  },
+  "files": [
+    "layouts",
+    "components",
+    "styles",
+    "setup",
+    "global-top.vue",
+    "slide-top.vue",
+    "slide-bottom.vue",
+    "custom-nav-controls.vue",
+    "confidential-mark.vue",
+    "assetUrl.js",
+    "notch.js",
+    "notchPath.js",
+    "section.js",
+    "useNotchCuts.js",
+    "uno.config.ts",
+    "icons",
+    "endorsements",
+    "manifest",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/section.js

@@ -0,0 +1,110 @@
+// The section pill's logic, split out of slide-top.vue so it is unit-testable at all.
+//
+// packages/slidev-theme's own suite (test/frontmatter.static.test.ts) runs under plain Node, no
+// DOM (see vitest.config.ts: `environment: 'node'`) — there is no @vue/test-utils here and no
+// component ever gets mounted. A computed buried inside slide-top.vue's <script setup> would
+// therefore be unreachable from a test. Pulling the derivation out into a plain, exported function
+// is the same move backgrounds.js already made for the background lookup, and the same shape the
+// suite already tests directly for contrast() (packages/tokens/src/colourEngine.ts) — a pure
+// function, imported and called with plain data, no framework runtime required.
+//
+// A slide's section is the nearest PRECEDING divider's title — not a value the slide carries
+// itself. Two traps, both load-bearing (see task-5-api-notes.md, which this was checked against):
+//
+//   1. Indexing. `useNav()`'s `slides` is a zero-indexed array; `currentPage` is Slidev's own
+//      ONE-based page number. `currentPage - 1` is the current slide's own array index. Walking
+//      back from `currentPage` directly (forgetting the -1) starts one slide too far forward and
+//      lets a divider claim the slide AFTER it as "its own" section — while the divider itself
+//      would report whatever divider preceded IT, or nothing. The walk here starts at
+//      `currentPage - 1` specifically so a divider slide reports ITS OWN title as its section
+//      (there is nothing wrong with a divider naming itself — the audience is looking at "The
+//      seam" while "The seam" is the current slide), and the slide immediately before it must not.
+//   2. Precedence. `frontmatter.section` is the author's explicit override (a plain custom key,
+//      not reserved anywhere in Slidev's frontmatter). `meta.slide.title` is Slidev's OWN
+//      first-heading extraction — reading it is fine, but a layout must never be told to WRITE
+//      `title:` in its own frontmatter to name a section, because `title` is reserved on slide 1
+//      (RESERVED_ON_SLIDE_ONE in test/props.ts) and would silently be dropped there.
+
+/**
+ * The minimal shape this needs out of a `useNav()` slide route — `SlideRoute` from
+ * `@slidev/types`, narrowed to the two fields actually read.
+ * @typedef {{ meta: { slide: { frontmatter: Record<string, any>, title?: string } } }} MinimalSlideRoute
+ */
+
+/**
+ * Derives the section pill's text for the slide at `currentPage` (Slidev's own one-based page
+ * number) by walking backwards through the deck's own slide list to the first slide — inclusive
+ * of the current one — whose `layout` is `'divider'`.
+ *
+ * @param {MinimalSlideRoute[]} slides `useNav()`'s own `slides.value` — zero-indexed.
+ * @param {number} currentPage `useNav()`'s own `currentPage.value` — one-based.
+ * @returns {string} the nearest preceding (or the current) divider's `section:` override, falling
+ *   back to its own extracted title, or `''` when no divider precedes this slide at all — the
+ *   empty string is the caller's own signal to render no pill.
+ *
+ * Three ways to get that empty string on purpose, narrowest first:
+ *   - `section: false` on a SLIDE          — this slide only, chrome otherwise untouched
+ *   - `section: false` on a DIVIDER        — that divider and every slide until the next one
+ *   - `sectionPill: false` in HEADMATTER   — the whole deck, and nothing can out-rank it
+ */
+export const deriveSection = (slides, currentPage) => {
+  /*
+    ★★ `sectionPill: false` — THE DECK-WIDE SWITCH, AND IT IS CHECKED BEFORE EVERYTHING ELSE.
+
+    Read off slide ONE's frontmatter, which in Slidev is the deck's headmatter. Not merged, not
+    inherited: read directly, once, from the only slide that can carry a deck-level statement.
+
+    ★ WHY NOT `defaults: { section: false }`, WHICH ALREADY ALMOST WORKS. Slidev's `defaults:` block
+    merges into every slide's own frontmatter, so it looks like the deck-wide lever and behaves like
+    one until it doesn't: a slide's OWN frontmatter outranks a default, and every divider now
+    declares `section:` because a divider that names nothing takes the pill off every slide behind
+    it (see the walk below, and the gate in test/frontmatter.static.test.ts). So dividers — and only
+    dividers — would out-rank the default and keep their pill.
+
+    Measured before this existed: `defaults: { section: false }` cleaned 224 slides across the two
+    decks and left a pill on three, all of them dividers drawn as SPECIMENS of the divider layout
+    rather than as section openers. That is a rule nobody could predict from the outside, failing on
+    the category hardest to guess. A switch that works by accident of precedence is not a switch.
+
+    This one cannot be out-ranked, because nothing else is consulted once it is set.
+
+    NOT the same key as `section:`, deliberately. `sections` would have been the natural plural and
+    is one keystroke from `section` — a typo that silently changes SCOPE rather than erroring is
+    exactly the class of defect this file's own history is made of.
+  */
+  if (slides[0]?.meta?.slide?.frontmatter?.sectionPill === false) return '';
+
+  /*
+    ★ `section: false` — the PER-SLIDE opt-out, and the only thing a non-divider slide may say about
+    its own section.
+
+    Two levers already existed and neither was per-slide: `section: '…'` on a DIVIDER renames the
+    pill for that whole run of slides, and `chrome: false` removes all the chrome at once, mark
+    included. A slide that wants its band's top-left corner back — and nothing else changed — had no
+    way to ask, because this function only ever read divider frontmatter.
+
+    FALSE, not empty string. `section: ''` on a divider already means "this section has no name",
+    which is a statement about the SECTION; `section: false` on any slide means "not here", which is
+    a statement about the SLIDE. Keeping them distinct matters because the first propagates forward
+    to every slide under that divider and the second does not.
+
+    It composes with the notch for free and that is not a coincidence: the cut is measured from
+    whatever chrome is actually on the panel (../useNotchCuts.js), so a slide that draws no pill
+    simply has no box in that corner and gets its plain --deck-radius-card corner back. Nothing
+    tells the panel; there is nothing to tell.
+  */
+  if (slides[currentPage - 1]?.meta?.slide?.frontmatter?.section === false) return '';
+
+  for (let i = currentPage - 1; i >= 0; i--) {
+    const frontmatter = slides[i]?.meta?.slide?.frontmatter;
+    if (frontmatter?.layout === 'divider') {
+      // A divider may opt its whole section out the same way. Checked explicitly rather than left
+      // to `?? title`, because `false` is not nullish — it would fall through and be returned AS a
+      // boolean, which happens to render as no pill today only because the caller filters falsy
+      // values. Relying on that would be a contract nobody wrote down.
+      if (frontmatter.section === false) return '';
+      return frontmatter.section ?? slides[i].meta.slide.title ?? '';
+    }
+  }
+  return '';
+};