@humanforest/slidev-theme 0.1.0

package/components/Carousel.vue

@@ -0,0 +1,266 @@
+<script setup>
+/*
+  One card at a time, advanced by the presenter's own clicks, with the room always told which of how
+  many it is looking at.
+
+  ★ WHY THIS IS NOT JUST `v-switch`, which Slidev already ships and which does the swapping part.
+  Two things are missing from it for a deck read across a room, and both are the whole reason a
+  presenter reaches for a carousel instead of N slides:
+
+    · THE POSITION INDICATOR. `v-switch` shows item 3 with nothing on screen saying it is the third
+      of five. On a slide the page number does that job; inside a slide nothing does, and an
+      audience that cannot see how many are left stops tracking the argument and starts waiting.
+    · A FIXED BOX. `v-switch` sizes to whatever is currently in it, so the surrounding layout jumps
+      every time the presenter clicks — headings shift, the card grows, and the room's eye is
+      dragged back to the top of the slide. Here every item is laid out in the same grid cell and
+      the box is the size of the LARGEST, so only the content changes.
+
+  ★★ AND WHY IT IS NOT AUTOMATIC. A web carousel advances on a timer. A presenting one must not:
+  the presenter is talking to item 2 and the deck must not move to item 3 until they say so. So this
+  spends CLICKS, exactly as `v-click` does, which also means the presenter's notes, the progress
+  bar, the slide's click count and the export all understand it for free.
+
+  The click plumbing mirrors @slidev/client's own VSwitch.ts — `calculateSince` to reserve a range,
+  `register` so the slide knows how many clicks it owns, `currentOffset` to read the position. It is
+  the documented shape; the only thing not copied is `makeId`, which is internal, and a module
+  counter is what it is anyway.
+*/
+import { computed, onMounted, onUnmounted, ref, watchEffect } from 'vue';
+import { useSlideContext } from '@slidev/client';
+import { assetUrl } from '../assetUrl.js';
+
+const props = defineProps({
+  /**
+   * The cards, in order. Each is `{ title, body?, image? }`.
+   *
+   * `image` is a URL, drawn full-bleed above the title at a fixed 16:9 — every card shares one grid
+   * cell and therefore one width, so the ratio resolves to the same height for all of them and no
+   * card's crop can move the stage. The picture is decorative here; the card's own title carries the
+   * meaning, so it takes an empty alt rather than a duplicated one.
+   */
+  items: {
+    type: Array,
+    required: true,
+    validator: (v) =>
+      Array.isArray(v) &&
+      v.length > 0 &&
+      v.every((i) => i && typeof i.title === 'string' && (i.image === undefined || typeof i.image === 'string')),
+  },
+  /** Where the first card lands in the slide's click sequence — Slidev's own `at` vocabulary
+   *  ('+1' means "after whatever came before me"). */
+  at: { type: [Number, String], default: '+1' },
+  /**
+   * Maximum width of the device, in px. 0 (the default) lets it fill its column.
+   *
+   * A carousel shows ONE card at a time, so at full slide width a card with three lines of text is
+   * a very wide, very short box — the reading line runs past the measure and the picture above it
+   * has to be enormous to keep the proportion. Capping the width is what makes it read as a card
+   * rather than as a band. It stays left-aligned: the slide's own `align` decides where content
+   * sits, and a component that centred itself would fight it.
+   */
+  width: { type: Number, default: 0 },
+});
+
+let nextId = 0;
+const id = `deck-carousel-${nextId++}`;
+const offset = ref(0);
+const { $clicksContext: clicks } = useSlideContext();
+
+/*
+  A carousel of n items spends n-1 clicks: the first card is already showing when the slide arrives,
+  so only the MOVES between cards cost anything. Getting this wrong by one is not a visual bug — it
+  silently changes the slide's total click count, and the presenter's "next" at the end either
+  sticks or skips to the following slide a beat early.
+*/
+const steps = computed(() => Math.max(0, props.items.length - 1));
+
+onMounted(() => {
+  const info = clicks?.calculateSince(props.at, steps.value);
+  // No clicks context, or none left to reserve — an overview thumbnail or a print pass. Showing the
+  // first card is the right resting state, and it is the same one reduced motion lands on.
+  if (!info) return;
+  clicks.register(id, info);
+  // ★ `currentOffset` is a REF, and reading it inside watchEffect is what makes this track. It
+  // counts from -1 before this component's first click, so +1 lands index 0 on arrival; clamped
+  // because the slide's offset keeps climbing once later components spend their own clicks.
+  watchEffect(() => {
+    offset.value = Math.min(steps.value, Math.max(0, info.currentOffset.value + 1));
+  });
+});
+
+onUnmounted(() => {
+  clicks?.unregister(id);
+});
+
+const current = computed(() => Math.min(props.items.length - 1, Math.max(0, offset.value)));
+</script>
+
+<template>
+  <div class="deck-carousel" :style="width ? { maxWidth: `${width}px` } : undefined">
+    <div class="deck-carousel-stage">
+      <!-- Every item is drawn in the SAME grid cell, so the stage is the height of the tallest and
+           nothing below it moves when the presenter clicks. `visibility` rather than `v-if`: a
+           removed item takes its height with it, which is the jump this exists to stop.
+
+           `--carousel-slot` is the card's position RELATIVE to the current one — -1 is the card
+           just left, +1 the card just right — which is what lets the stylesheet lay the whole reel
+           out on one axis without this component tracking a direction. Advancing raises `current`,
+           every slot drops by one, and the reel moves left because the arithmetic says so. -->
+      <div
+        v-for="(item, i) in items"
+        :key="i"
+        class="deck-carousel-item"
+        :class="{ 'is-current': i === current }"
+        :aria-hidden="i !== current"
+        :style="{ '--carousel-slot': i - current }"
+      >
+        <img v-if="item.image" class="deck-carousel-image" :src="assetUrl(item.image)" alt="" decoding="async" >
+        <p class="deck-carousel-title">{{ item.title }}</p>
+        <p v-if="item.body" class="deck-carousel-body">{{ item.body }}</p>
+      </div>
+    </div>
+    <!-- The indicator. Aria-hidden because it restates the position the cards already carry, and a
+         screen reader reading "1 of 5" as five bullet characters helps nobody. -->
+    <div class="deck-carousel-dots" aria-hidden="true">
+      <span
+        v-for="(item, i) in items"
+        :key="i"
+        class="deck-carousel-dot"
+        :class="{ 'is-current': i === current }"
+      />
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.deck-carousel {
+  display: grid;
+  gap: var(--deck-space-4);
+}
+
+.deck-carousel-stage {
+  display: grid;
+  /* The reel is wider than the window onto it: cards sit a full width apart on either side and are
+     clipped until it is their turn. Without this a card in transit is seen sliding across whatever
+     the slide has beside the carousel. */
+  overflow: hidden;
+}
+/* ── HOW IT MOVES ──────────────────────────────────────────────────────────────────────────────
+   Cards are laid on one horizontal reel and the reel slides. Card `n` sits `n - current` widths to
+   the side, so the current one is at 0 and its neighbours are parked a full width plus a gap out,
+   where the stage clips them. Nothing here knows which way the presenter went: advancing raises
+   `current`, every slot drops by one, and the whole reel translates left.
+
+   ★★ THIS USED TO CROSS-FADE, and the comment defending that said a positional animation "would be
+   stripped" by the reduced-motion floor. Stripped is exactly what should happen — and it is not
+   breakage. The floor rewrites `transition-property` to a colour/opacity allow-list, so under
+   reduced motion `transform` is not transitioned and the card simply ARRIVES at its slot. Same
+   resting frame, no movement. The old reasoning conflated two different things: the STAGE must
+   never move, which is what the shared grid cell guarantees, with the CARDS never moving, which is
+   the entire device.
+
+   ★★ VISIBILITY IS DELAYED OUT AND IMMEDIATE IN, and that pair is load-bearing twice over. It is
+   what lets a leaving card stay on screen for the length of its own exit instead of vanishing on
+   the first frame; and it is what keeps the RESTING state exactly what it was before — every
+   non-current card `visibility: hidden` once the motion ends. That second half matters beyond
+   tidiness: scripts/deckAudit.ts measures a settled page and fails text that is painted but not
+   visible, so cards parked off-stage and left visible would read as a real defect on every carousel
+   slide. `0s linear var(--motion-base)` is a DELAY, not a duration — visibility cannot tween, it
+   flips, and the delay is what holds the flip until the slide is over. */
+.deck-carousel-item {
+  /* All items stacked in one cell — the stage takes the height of the tallest. */
+  grid-area: 1 / 1;
+  background: var(--deck-surface);
+  border: 1px solid var(--deck-border);
+  border-radius: var(--deck-radius-card);
+  overflow: hidden;
+  padding: var(--deck-card-pad);
+  visibility: hidden;
+  opacity: 0;
+  transform: translateX(calc(var(--carousel-slot, 0) * (100% + var(--deck-space-4))));
+  transition:
+    transform var(--motion-base) var(--motion-ease-out),
+    opacity var(--motion-base) var(--motion-ease-out),
+    visibility 0s linear var(--motion-base);
+}
+.deck-carousel-item.is-current {
+  visibility: visible;
+  opacity: 1;
+  /* No delay on the way IN — the arriving card has to be visible for the whole of its travel. */
+  transition:
+    transform var(--motion-base) var(--motion-ease-out),
+    opacity var(--motion-base) var(--motion-ease-out),
+    visibility 0s;
+}
+
+/* AN ASPECT RATIO, and it is safe here for a reason worth stating: every card is laid out in the
+   SAME grid cell, so every card is the same width, so a ratio resolves to the same height for all
+   of them. The stage cannot be made to jump by one card's crop — which is the objection that would
+   otherwise force a fixed pixel height, and it does not apply. A ratio is the better answer because
+   it keeps its proportion when `width` changes; a pinned height would go letterbox on a narrow card
+   and postage-stamp on a wide one.
+
+   FULL BLEED to the card's edges: the picture is cancelled out of the card's own padding with a
+   negative margin on three sides, and takes the card's radius on the two corners it now owns. The
+   card clips (`overflow: hidden` on the item), or the image's square bottom corners would paint
+   over the rounded ones underneath. */
+.deck-carousel-image {
+  display: block;
+  width: calc(100% + var(--deck-card-pad) * 2);
+  /* ★★ WITHOUT THIS THE BLEED SILENTLY DOES NOT HAPPEN. Slidev's preflight ships
+     `img, video { max-width: 100% }`, which clamps the width above straight back to the card's
+     CONTENT box — the computed width came out as exactly the content width, so the picture sat
+     flush on the left (where the negative margin still applied) and short by 2x the padding on the
+     right. Nothing errors; it just looks like a mistake. */
+  max-width: none;
+  aspect-ratio: 16 / 9;
+  object-fit: cover;
+  margin: calc(-1 * var(--deck-card-pad)) calc(-1 * var(--deck-card-pad)) var(--deck-card-pad);
+  border-radius: var(--deck-radius-card) var(--deck-radius-card) 0 0;
+  /* The card's own fill shows through while a remote image is still in flight, rather than a
+     transparent gap that reads as a broken card in the one second that matters most. */
+  background: var(--deck-surface-strong);
+}
+
+.deck-carousel-title {
+  font-family: var(--type-deck-title-family);
+  font-size: var(--type-deck-title-size);
+  font-weight: var(--type-deck-title-weight);
+  line-height: var(--type-deck-title-line-height);
+  color: var(--deck-fg);
+  margin: 0;
+  max-width: none;
+}
+.deck-carousel-body {
+  font-size: var(--type-deck-body-sm-size);
+  line-height: var(--type-deck-body-sm-line-height);
+  color: var(--deck-fg-muted);
+  margin: var(--deck-space-2) 0 0 0;
+  max-width: none;
+}
+
+.deck-carousel-dots {
+  display: flex;
+  gap: var(--deck-space-2);
+  justify-content: center;
+}
+/* A bar rather than a circle, and the current one is WIDER rather than merely darker. Read across a
+   room a filled circle and an outlined one of the same size are one shape at two weights; a
+   different LENGTH survives the distance. */
+.deck-carousel-dot {
+  width: var(--deck-space-4);
+  height: var(--deck-space-1);
+  border-radius: var(--deck-radius-full);
+  background: var(--deck-border-strong);
+  /* `width` travels with the reel rather than snapping while the card is still moving. It is
+     outside the reduced-motion allow-list, like `transform`, so it lands instantly there — the
+     indicator and the card agree in both registers. */
+  transition:
+    background-color var(--motion-base) var(--motion-ease-out),
+    width var(--motion-base) var(--motion-ease-out);
+}
+.deck-carousel-dot.is-current {
+  width: var(--deck-space-7);
+  background: var(--deck-accent);
+}
+</style>