@humanforest/slidev-theme 0.1.0

package/layouts/statement.vue

@@ -0,0 +1,67 @@
+<script setup>
+/*
+  One sentence, the whole slide. The tier below a section divider: still a shout, but on the
+  deck's own ground rather than a full-bleed field, so it can carry a real claim instead of a
+  chapter name. Bold the part that matters — `strong` is the accent.
+*/
+defineProps({
+  /** Optional kicker line rendered above the slide's one claim, e.g. a chapter or context label. */
+  eyebrow: { type: String, default: '' },
+  /** Horizontal position of the claim: ragged left (default), centred, or ragged right. */
+  align: { type: String, default: 'start', validator: (a) => ['start', 'center', 'end'].includes(a) },
+  /** Vertical position of the claim on the slide: top, optically centred (default), or bottom. */
+  valign: { type: String, default: 'center', validator: (v) => ['start', 'center', 'end'].includes(v) },
+})
+</script>
+
+<template>
+  <div
+    class="slidev-layout statement h-full flex flex-col"
+    :class="[`is-h-${align}`, `is-v-${valign}`]"
+  >
+    <p v-if="eyebrow" class="deck-eyebrow">{{ eyebrow }}</p>
+    <slot />
+  </div>
+</template>
+
+<style scoped>
+/* The beat margin — see cover.vue's own note. Both edges, not just the left: the left-only version
+   this replaces rendered a 120px left margin against a 90px right one on every divider and closer,
+   with nothing in any file explaining the asymmetry. */
+.statement {
+  padding-left: var(--deck-inset-display);
+  padding-right: var(--deck-inset-display);
+}
+/*
+  Nine positions, as three classes on each axis rather than one `is-center` special case. The old
+  rule styled only 'center' so that an unstyled 'start' stayed pixel-identical; with a third value
+  on each axis that trick stops paying, because `end` needs a rule of its own either way and two
+  half-specified axes are harder to read than six explicit ones.
+
+  ★ THE TEXT ALIGNMENT HAS TO FOLLOW THE BOX. `align-items` moves the h1's BOX, and the h1 carries
+  `max-width: 14em` — so an end-aligned box whose text is still ragged-left puts the claim on the
+  right of the slide with its short last line hanging off the left of its own column. The two are
+  one decision, not two.
+*/
+.statement.is-h-start { align-items: flex-start; text-align: left; }
+.statement.is-h-center { align-items: center; text-align: center; }
+.statement.is-h-end { align-items: flex-end; text-align: right; }
+
+/* Vertical. `center` is the historical hard-coded `justify-center`, kept as the default so every
+   existing statement slide renders exactly as it did. */
+.statement.is-v-start { justify-content: flex-start; }
+.statement.is-v-center { justify-content: center; }
+.statement.is-v-end { justify-content: flex-end; }
+/* Statement is a beat slide — Mohr uppercase, not the layout-default working voice. */
+.statement :deep(h1) {
+  font-family: var(--type-deck-display-family);
+  font-weight: var(--type-deck-display-weight);
+  text-transform: uppercase;
+  font-size: var(--type-deck-text-8xl); /* 6rem / 96px — ramp 8xl */
+  line-height: 0.95;
+  max-width: 14em; /* ≈20 characters of Mohr uppercase */
+}
+.statement :deep(strong) {
+  color: var(--deck-accent);
+}
+</style>

package/manifest/chrome.ts

@@ -0,0 +1,36 @@
+// The chrome half of LAYOUT_ROLES' own doc comment (packages/slidev-theme/manifest/layouts.ts) —
+// read that file first. `slide-top.vue`/`slide-bottom.vue` live at the package ROOT
+// (packages/slidev-theme/), not under layouts/ or components/ — see the re-brief note in
+// scripts/deckCoverage.ts's DIRS for why that split matters and what it cost once already.
+// Keyed by filename without its extension, matching how scripts/deckManifest.ts names every
+// other entry.
+//
+// Neither file declares a prop today (both read frontmatter directly via `inject`, not via
+// `defineProps`), so their manifest entries carry an empty `props` array — that is the
+// "genuinely no props" case scripts/deckManifest.ts's liveness gate is required to tell apart
+// from a parse failure, not a gap in this table.
+//
+// task-6-fix-1.md's ★ MINOR — both files gate their own visibility on the SAME frontmatter key,
+// `chrome: false`, and neither role string named it before this fix: a manifest reader had no way
+// to learn that a slide can suppress the running chrome at all, let alone how. Recorded here, in
+// prose, the same pattern `confidential:` already used in slide-bottom's own role — `chrome:` is
+// not a declared PROP (Vue's prop system has no visibility here at all; both files just `inject`
+// the raw frontmatter object), so it cannot appear in `props` the way a real prop would; naming it
+// in the role text is the only place in this manifest it CAN appear.
+// task-18 — two more frontmatter keys with the same shape as `chrome:` and `confidential:`: read by
+// injection, never declared as props, so prose here is the only place in this manifest they CAN
+// appear. `companion:` widens the running mark into a co-branded lockup (and the notch cut for it
+// follows automatically, because both are computed from one function in
+// packages/slidev-theme/notch.js); `notch: false` is the per-slide escape hatch from the cut.
+export const CHROME_ROLES: Record<string, string> = {
+  'custom-nav-controls': 'The theme\'s own buttons in Slidev\'s nav toolbar — a REVIEWER\'s controls, not deck content. Slidev renders this file automatically (@slidev/client/internals/NavControls.vue imports `#slidev/custom-nav-controls`); a theme without it contributes nothing. Two toggles: hide the confidentiality chip, and draw the layout inset frames (the same flag the `l` shortcut sets). Both are PREVIEW-ONLY OVERRIDES that can only ever subtract — a slide with no `confidential:` cannot be made to show one from here. Neither can reach an exported PDF: `slidev export` launches a separate browser process, so the refs start false in it.',
+  'slide-top': 'Running chrome, mounted per slide — the page-number and section pills top-left, the Forest mark top-right. A slide opts out of both with `chrome: false` in its own frontmatter, or out of the SECTION PILL alone with `section: false` — the notched panel or band on that slide gets its plain corner back automatically, because the cut is measured from whatever chrome is actually on it. `section: \'…\'` on a DIVIDER renames the pill for that whole run of slides instead. CO-BRANDING: `companion: /companion.svg` draws a companion\'s mark beside the Forest one at the same height, at the same size and clipped to the mark\'s own rounded square, whatever the source artwork is, with `companionName:` supplying its alt text — the notched panel or band on the same slide widens its cut to match, with no other change. `notch: false` keeps the running chrome but drops the cut, returning the figure to its full corner.',
+  'slide-bottom': 'Running chrome, mounted per slide — the confidentiality watermark bottom-left, from a slide\'s own `confidential:` frontmatter. A slide opts out with `chrome: false`, the same key `slide-top` reads.',
+  // task-14-brief.md, requirement 6 — mounted ONCE globally (Slidev's `global-top.vue` convention,
+  // not `slide-top`/`slide-bottom`'s per-slide one), because it is not a per-slide, frontmatter-
+  // gated concern the way the other two chrome files are: it draws the same red-line frames on
+  // every slide regardless of that slide's own `chrome:` setting, since the point is to let a
+  // reviewer check ANY slide's geometry, including the ones that hide the running chrome.
+  'confidential-mark': 'The standing confidentiality marking itself — a stroked, unfilled pill in --deck-fg-subtle, drawn by `slide-bottom` from a slide\'s own `confidential:` frontmatter. Chrome rather than a component because an author never places one: a deck sets it once in the headmatter\'s `defaults:` (or a slide declares its own), and it is suppressed with the same `chrome: false` the rest of the running chrome reads. It was `BadgeStrip variant="outline"` until it earned its own file — it paints no background pair, drops the uppercase and the tracking, runs at 0.6 of the overline size, which is what keeps a legal marking quiet without putting it under the reading floor.',
+  'global-top': 'The layout-debug (red-line) overlay — draws the text/media/chrome inset frames and the chrome bands so the two-track spacing system can be checked by eye. OFF by default; toggled with the `l` key (setup/shortcuts.ts), never by frontmatter, and forced off whenever the route is in print/export mode regardless of the toggle. A review tool, not per-slide chrome — see README.md\'s "Debugging layout" section.',
+};

package/manifest/components.ts

@@ -0,0 +1,49 @@
+// The component half of LAYOUT_ROLES' own doc comment (packages/slidev-theme/manifest/layouts.ts)
+// — read that file first; everything said there about WHY this table exists, what it must never
+// claim, and what scripts/deckManifest.ts checks it against applies here unchanged.
+//
+// Every entry is a close paraphrase of that component's own top-of-file doc comment in
+// packages/slidev-theme/components/*.vue.
+export const COMPONENT_ROLES: Record<string, string> = {
+  AreaChart: 'An area chart sized for a room — stacked by default, because a stack claims the parts sum to a whole; `overlaid` switches the claim.',
+  BadgeStrip: 'An array-driven row of dark tiles — the deck\'s tag list.',
+  Alert: 'A subtle status panel — a tinted block naming one of four states, with its own lamp. The colour IS the message, which is what separates it from a Callout.',
+  Avatar: 'One person: their face in a ring of the page\'s own ink, their name on a chip riding the ring\'s bottom edge, and what they do under that. Three diameters, and `size` steps the two caption sizes and the space between them along with the circle — from a row of six to one person given the whole slide. With no photograph it falls back to their initials rather than to an empty circle. It draws ONE person: a team is several of these in a `Grid`, which is the component that already owns columns and gutters.',
+  AvatarGroup: 'A row of faces overlapping into one object — how many people, not which ones. It composes `Avatar` with no name and no role, so the circle and its ring are that component\'s; what lives here is the negative gap and the stacking order, at three overlaps from a long row to a crowd. The captioned counterpart is a `Grid` of `Avatar`, which introduces people rather than counting them.',
+  Bars: 'A horizontal bar chart sized for a room: bars start at zero, coloured from the deck\'s own series roles.',
+  BoroughShape: 'A single London borough as a styleable glyph — one outline, framed to itself, filled with currentColor, drawn at one of four heights whose middle step is the natural size.',
+  LondonMap: 'All 33 London boroughs in one frame, in true relative position — the vector counterpart to the dot grid, with any subset lifted into the accent.',
+  CalendarGrid: 'A year of days as a grid of cells shaded by intensity — the mark for seasonality, where the question is which weeks are busy rather than what any one day was.',
+  Contents: 'The deck\'s contents page, derived from the dividers themselves — every `divider` slide with a title becomes an entry, at `rank: section` or nested under the section above it at `rank: subsection`, and `hideInToc` on a divider opts it out. Takes no props: a contents page has nothing to configure, and the deck it belongs to is the only argument it needs.',
+  Endorsement: 'A third-party certification mark — Certified B Corporation today, as B Lab supplies it. Two sanctioned colourways — `positive` (black, for light grounds) and `reverse` (white, for dark grounds and photographs) — and the component SWAPS FILES between them rather than tinting one, because the licence forbids recolouring. There is deliberately no colour prop. Verra is not here: its mark needs written approval, and the docs page renders a placeholder rather than the real thing.',
+  Carousel: 'One card at a time, advanced by the presenter\'s own clicks, in a box the size of the largest so nothing below it moves — with a position indicator, which is what `v-switch` cannot give a room.',
+  Card: 'The deck\'s one container — no fill at all, a quiet fill one step away from the slide ground, or one of the four named backgrounds, which brings its own ink with it; `dark` renders the last two in the dark register, and `border` adds an edge, drawn in the card\'s own ink, which no background carries by default.',
+  ChartFrame: 'The ceremony every deck chart shares: the room-scale Unovis type ramp, the legend and the empty state. Marks stay in the slot.',
+  ChordChart: 'Flows BETWEEN the members of one set, drawn as a ring — where a Sankey shows a quantity moving through stages, this shows it moving among peers.',
+  ComposedChart: 'Bars and a line on one shared x axis — volume as columns with a rate drawn over them, the two-mark slide a single chart type cannot make.',
+  DataTable: 'A table sized for a room — a few rows, a few columns, a header that reads from the back, and figures in the tabular treatment. Rows truncate and say so on the slide; columns refuse past five.',
+  DonutChart: 'Up to five slices of one whole, with the total in the hole — the number a part-to-whole chart cannot show any other way.',
+  DeckMap: 'A live Mapbox GL map on Forest\'s own house style — the real basemap, for a slide that needs streets rather than the dot grid\'s abstraction. Non-interactive by default, and draws an honest panel when the build carries no token.',
+  DottedMap: 'London as a dot grid — the design system\'s own map primitive, sampled from real borough geometry.',
+  GroupedBarChart: 'A cluster of bars per category, every one measured from the same zero — the honest mark for independent series that share an axis.',
+  Grid: 'The deck\'s one grid — a closed set of gutters and columns, optionally driven by an `items` array.',
+  IconTile: 'A single Forest icon on a rounded warm tile.',
+  Kpi: 'A KPI on a slide — one figure, what it is, and optionally how it has moved (arrow = direction, colour = judgement).',
+  LineChart: 'A line chart sized for a room. A line claims the space between its points, so the x axis has to be a real sequence.',
+  Logo: 'The Forest identity, in the four forms the brand ships: mark, wordmark, lockup, lockup-vertical.',
+  MarkPair: 'Forest\'s mark with a partner\'s beside it at one height — the co-branding object. The partner\'s artwork is covered into a square and clipped to the mark\'s own corner with a ring in the inherited ink, and every one of those numbers is a RATIO of `size`, so the pair holds its proportions at the chrome\'s 72 and at a poster\'s 120 alike. With no `src` it is the mark alone, which is what the running chrome draws on a slide with no `companion:`.',
+  Marquee: 'A band of words moving slowly across the slide — the deck\'s one piece of motion that is content rather than transition. Legible standing still, which is the state reduced motion and an export both leave it in.',
+  NestedDonutChart: 'A donut with concentric rings — part-to-whole where the parts themselves break down, with the inner ring naming what the outer one is made of.',
+  AreaBox: 'A named region of a layout, drawn as a filled labelled block — the piece that lets a frame be shown as its areas instead of its content.',
+  BrowserFrame: 'A browser window around a mock — three lights, an address pill and a page area whose `ratio` is the VIEWPORT rather than the window. Drawn entirely from deck tokens: the deck\'s counterpart to the design system\'s FBrowserFrame, which cannot be used here because it is written in Nuxt UI\'s semantic classes.',
+  DeviceFrame: 'A phone drawn around a live screen, at the model\'s true logical points and clipped to the render\'s own aperture. Metrics and art come from `@humanforest/frames`; only the presentation is the deck\'s own. The renders are Wikimedia Commons vectors under CC BY-SA 4.0, so attribution travels with them.',
+  Placeholder: '"An image goes here" — a deliberately obvious placeholder, hatched and dashed rather than iconic, drawn in CSS so overflow measurements stay repeatable.',
+  SankeyChart: 'Flow through stages, where the width of every ribbon IS the quantity — the mark for a total that arrives, splits, and lands somewhere in full.',
+  ScatterChart: 'Two measurements against each other, one dot per observation — the one deck chart whose message is a shape, not a number.',
+  StackedBarChart: 'A column per category, split into the parts that make it up. Bars start at zero; the segments sum to the column.',
+  StatCard: 'A stat inside a card — the deck\'s Kpi figure, framed by the deck\'s one container.',
+  StatusTrack: 'One asset read left to right as a row of equal-width buckets — a bike\'s week, a bay\'s ninety days. `state` colours a condition from the status roles; `intensity` buckets a quantity onto the sequential ramp. The deck\'s re-implementation of packages/charts FStatusTrack.',
+  Timeline: 'A sequence of moments on one rule, horizontal for up to about five stops and vertical when each one has more to say, with a single stop optionally marked as the present.',
+  TimelineChart: 'Labelled rows of bars spanning time — when each thing ran, and against what. The presentational sequence-of-stops on a rule is `Timeline`, a different component entirely.',
+  TreemapChart: 'Part-to-whole where the parts are too many or too uneven for a donut — area is the quantity, and a group can nest inside it.',
+};

package/manifest/index.ts

@@ -0,0 +1,57 @@
+// The manifest package's public surface — the one module scripts/deckManifest.ts (the generator)
+// and packages/slidev-theme/test/manifest.static.test.ts (its tests) both import from, rather than
+// each reaching into layouts.ts/components.ts/chrome.ts/presets.ts separately. Also where the
+// shared TypeScript shapes for a generated manifest.json live, so the generator and its tests
+// agree on the shape by construction rather than by convention.
+export { LAYOUT_ROLES } from './layouts';
+export { COMPONENT_ROLES } from './components';
+export { CHROME_ROLES } from './chrome';
+export { PRESETS, validatePreset, type Preset } from './presets';
+
+/**
+ * One prop, as it appears inside a layout/component/chrome manifest entry. Mirrors `PropDetail`
+ * from packages/slidev-theme/test/props.ts minus `enumRef`, which is resolved to real values (or
+ * fails the build) before a manifest entry exists at all — see scripts/deckManifest.ts.
+ *
+ * FIX ROUND 1, IMPORTANT 3 — `required` is carried through explicitly rather than folded into
+ * `default === null`: several real props (Bars.vue's `max`, Kpi.vue's `precision`/`delta`) declare
+ * a genuine `null`/`undefined` default and are NOT required, so `default === null` alone cannot
+ * tell "no default was ever declared" apart from "the default really is null" — `required` is the
+ * field that can. `default` is now a real value of the JSON type it represents (see `PropDetail`'s
+ * own doc comment for the defect this fixes and the measured blast radius), never quoted source
+ * text; `hasDynamicDefault`/`defaultSource` carry the cases `default` cannot represent.
+ */
+export type ManifestProp = {
+  name: string;
+  type: string | null;
+  enum: string[] | null;
+  /** A real value of the JSON type it represents. `null` means EITHER "no default was declared"
+   * (check `required`) OR "the default genuinely is null/undefined" — see `hasDynamicDefault`
+   * before trusting either reading, and never treat `default === null` alone as "required". */
+  default: string | number | boolean | null;
+  /** True when `default` could not represent the real default (an arrow function or factory) —
+   * `default` is always `null` when this is `true`. Check this BEFORE reading `default` as "the
+   * default is null". */
+  hasDynamicDefault: boolean;
+  /** The raw declared-default source text, verbatim, for a human reading the manifest — never a
+   * value to assign. `null` only when there is no `default:` key in source at all. */
+  defaultSource: string | null;
+  required: boolean;
+  description: string;
+};
+
+/** One layout, component, or chrome file. */
+export type ManifestEntry = {
+  name: string;
+  role: string;
+  props: ManifestProp[];
+  slots: string[];
+};
+
+export type Manifest = {
+  $generated: string;
+  layouts: ManifestEntry[];
+  components: ManifestEntry[];
+  chrome: ManifestEntry[];
+  presets: import('./presets').Preset[];
+};

package/manifest/layouts.ts

@@ -0,0 +1,37 @@
+// The one thing about a layout the source itself cannot mechanically hand over: a short,
+// human-facing statement of what it's FOR. Everything else in a layout's manifest entry — its
+// props, their types/enums/defaults/descriptions, its slots — is derived straight from
+// packages/slidev-theme/layouts/*.vue by scripts/deckManifest.ts (via
+// packages/slidev-theme/test/props.ts's shared parser). This table is the one place role text is
+// hand-authored, and it exists for the same reason scripts/docsCoverage.ts's own HOMES map is
+// hand-written rather than derived: which layout is "the opener" versus "the workhorse" is an
+// editorial judgement no glob can infer.
+//
+// Every entry below is a close paraphrase of that layout's own top-of-file doc comment in
+// packages/slidev-theme/layouts/*.vue — never an independent claim about behaviour the source
+// doesn't already make. scripts/deckManifest.ts fails the build if a layout exists on disk with
+// no entry here (a new layout landing without a role, silently emitting `role: ''` into the
+// manifest, is exactly the kind of gap this project keeps re-discovering the hard way) and,
+// separately, if an entry here names a layout that no longer exists on disk (dead metadata,
+// pointing Task 8's showcase generator at nothing).
+// task-6-fix-1.md's ★ MINOR — `chrome: false` (a frontmatter key the running chrome reads, see
+// packages/slidev-theme/manifest/chrome.ts) appeared nowhere in the manifest, so a reader had no
+// way to learn that the retired template deck paired it with six of these eight
+// layouts EVERY time it uses them: cover, divider, bleed, quote, statement and end all carry
+// `chrome: false` on every single occurrence in that deck (measured: 6/6 each); `default` and
+// `split` carry it on NONE of theirs (0/10, 0/4). That is a real, consistent convention — these
+// six all take over the WHOLE field for one claim or one piece of media, which is exactly what the
+// running chrome's quiet corners would visually compete with — not a mechanical fact the layout
+// component itself enforces (`chrome:` is read by the two chrome files, not by any layout, and a
+// `default`/`split` slide is free to set it too). Recorded as a convention note, not a rule.
+export const LAYOUT_ROLES: Record<string, string> = {
+  bleed: 'Full-bleed media with content laid over it — the only layout that escapes the slide\'s padding. Commonly paired with `chrome: false`.',
+  cover: 'The opener. Light ground, one Mohr shout at the top of the ramp, the full lockup signing it. Commonly paired with `chrome: false`.',
+  default: 'The workhorse. A bare content slide, plus the optional eyebrow → shout → content rhythm from frontmatter.',
+  divider: 'The deck\'s punctuation — the one place a slide takes over the whole field. `rank` says what it opens, and the ground, the headline and the rule step down together. Commonly paired with `chrome: false`.',
+  end: 'The closer, in four shapes: the closing line over the lockup, two display words split around one of the brand\'s own renders, the wordmark alone at display scale, or a photograph edge to edge under a scrim. Takes the same two grounds an opener does, so a deck that states neither opens and closes on the same colour. Carries no certification — a sign-off ends on the brand, not on somebody else\'s mark. Commonly paired with `chrome: false`.',
+  quote: 'A pull quote — the one slide where the sans face runs large, because a quote is somebody else speaking. Commonly paired with `chrome: false`.',
+  split: 'The other workhorse. Content on one side, a figure on the other.',
+  stack: 'The horizontal counterpart of `split` — a hero band across the top, the title demoted to a strip below it. The one arrangement where the figure leads and the title captions it.',
+  statement: 'One sentence, the whole slide — a shout on the deck\'s own ground, one tier below a section divider. Commonly paired with `chrome: false`.',
+};