presently 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 806fa6100505250fcb875b1d751bd96df78108d835bb60ad65c0484e0850e296
-  data.tar.gz: 723cdf3db680519971054969cff462752b85b7df67cab51c0bc50f8585c00890
+  metadata.gz: e5c00d36415375cd15afef5fbc6b2669200b981ebb8744ccd5f04d770ea71877
+  data.tar.gz: b154f921b651b3572b307b529cc6b630601ccabce70a8a06e089bada66a211e8
 SHA512:
-  metadata.gz: 12e369d511548176c671fbd42718cd136d3d628f173d0c6901f36c805fa87612067765ca1a29d808ec806b223c11ce2f2ea0c59d879b6eb97fa13e27828fd935
-  data.tar.gz: 10b3df45c9ed1e72e2dd01bae21daef286cea851e2f5630f7684b0de32771295bbce64a05ee81a028d20992ccb5235151277d2c3515df8cb469253d78d5b2a30
+  metadata.gz: b28384ce74c14c486da7fa1d80a81fd6b2b3a386f8ceac6e2a0ffbf6f6a5aa39325a31550badf722446a772ebf2cc11071eec354ec0d33b8f5bc1912b518726c
+  data.tar.gz: c555c644843daa56b0366575d14c3d85e7dd358bfa897654c47fd3b291c8a6ae14f0764af13139d54af4fced6cb46acc2aa38fd74bd3ee5f0b62ab377b242606

data/lib/presently/version.rb

@@ -5,5 +5,5 @@
 
 # @namespace
 module Presently
-	VERSION = "0.6.0"
+	VERSION = "0.7.0"
 end

data/public/_static/index.css

@@ -423,7 +423,7 @@ html[data-transition="morph"]::view-transition-new(slide-container) {
 }
 
 /* Fade */
-::view-transition-new(.build-fade) {
+.build-fade {
 	animation: vt-fade-in 0.4s ease;
 }
 
@@ -433,7 +433,7 @@ html[data-transition="morph"]::view-transition-new(slide-container) {
 	to { transform: translateX(0); opacity: 1; }
 }
 
-::view-transition-new(.build-fly-left) {
+.build-fly-left {
 	animation: build-fly-in-left 0.4s ease;
 }
 
@@ -443,7 +443,7 @@ html[data-transition="morph"]::view-transition-new(slide-container) {
 	to { transform: translateX(0); opacity: 1; }
 }
 
-::view-transition-new(.build-fly-right) {
+.build-fly-right {
 	animation: build-fly-in-right 0.4s ease;
 }
 
@@ -453,7 +453,7 @@ html[data-transition="morph"]::view-transition-new(slide-container) {
 	to { transform: translateY(0); opacity: 1; }
 }
 
-::view-transition-new(.build-fly-up) {
+.build-fly-up {
 	animation: build-fly-in-up 0.4s ease;
 }
 
@@ -463,7 +463,7 @@ html[data-transition="morph"]::view-transition-new(slide-container) {
 	to { transform: translateY(0); opacity: 1; }
 }
 
-::view-transition-new(.build-fly-down) {
+.build-fly-down {
 	animation: build-fly-in-down 0.4s ease;
 }
 
@@ -473,7 +473,7 @@ html[data-transition="morph"]::view-transition-new(slide-container) {
 	to { transform: scale(1); opacity: 1; }
 }
 
-::view-transition-new(.build-scale) {
+.build-scale {
 	animation: build-scale-in 0.4s ease;
 }
 

data/public/application.js

@@ -68,23 +68,28 @@ function applyCodeFocus() {
 
 // Run the script for a single slide element.
 // Wrapped in try/catch so syntax errors don't crash the presentation.
+// Passes a tracked setTimeout so pending timeouts can be cancelled on slide change.
 function runScript(slideEl) {
 	const scriptEl = slideEl.querySelector('script[type="text/slide-script"]');
 	if (!scriptEl) return;
 
 	const container = slideEl.querySelector('.slide-body') ?? slideEl;
 	const slide = new Slide(container);
+	currentSlides.push(slide);
 
 	try {
-		const fn = new Function('slide', scriptEl.textContent);
-		fn(slide);
+		const fn = new Function('slide', 'setTimeout', scriptEl.textContent);
+		fn(slide, slide.setTimeout.bind(slide));
 	} catch (error) {
 		console.error('Slide script error:', error);
 	}
 }
 
 // Run scripts for all slide elements currently in the DOM.
+// Cancels any pending timeouts from the previous slide's scripts first.
 function runSlideScripts() {
+	currentSlides.forEach(slide => slide.cancelTimeouts());
+	currentSlides = [];
 	document.querySelectorAll('.slide').forEach(runScript);
 }
 
@@ -98,6 +103,9 @@ function detectTransition(html) {
 // Track the active view transition so we can skip overlapping ones.
 let activeTransition = null;
 
+// Track Slide instances from the current scripts so we can cancel their timeouts on slide change.
+let currentSlides = [];
+
 // Wrap Live's update method to support view transitions.
 const originalUpdate = live.update.bind(live);
 live.update = function(id, html, options) {

data/public/slide.js

@@ -1,44 +1,178 @@
-// Represents a collection of elements within a slide to be revealed sequentially.
-// Has no side effects until build() is called.
-export class SlideElements {
-	constructor(elements) {
-		this._elements = elements;
+// Stateful builder for a set of slide elements.
+// Wraps a raw element array with a cached position so callers can use next()
+// instead of tracking count manually. Created via SlideElements#builder(options).
+export class SlideBuilder {
+	#elements;
+	#prefix;
+	#defaultEffect;
+	#slide;
+	#step = 0;
+
+	constructor(slide, elements, options = {}) {
+		this.#slide = slide;
+		this.#elements = elements;
+		this.#prefix = options.group || 'build';
+		this.#defaultEffect = options.effect || null;
 	}
 
-	// Show the first n elements and hide the rest.
-	// Assigns view-transition-names and applies build visibility in one step.
-	// @parameter n [Integer] Number of elements to show.
-	// @parameter options [Object]
-	//   group: prefix for view-transition-name (default: "build")
-	//   effect: "fade", "fly-up", "fly-down", "fly-left", "fly-right", "scale"
-	build(n, options = {}) {
-		const prefix = options.group || 'build';
+	// Reveal elements up to `count`, using the default effect unless overridden.
+	// Assigns view-transition-names, sets visibility, and applies entry animation.
+	// @parameter count [Integer] Number of elements to show.
+	// @parameter overrides [Object] Option overrides for this step (e.g. a different effect).
+	// @returns [Promise] Resolves when the animation completes (or immediately if no effect).
+	show(count, overrides = {}) {
+		const effect = overrides.effect !== undefined ? overrides.effect : this.#defaultEffect;
+		let revealedElement = null;
 
-		this._elements.forEach((element, index) => {
-			element.style.viewTransitionName = `${prefix}-${index + 1}`;
+		this.#elements.forEach((element, index) => {
+			element.style.viewTransitionName = `${this.#prefix}-${index + 1}`;
 
-			if (index < n) {
+			if (index < count) {
 				element.style.visibility = 'visible';
-				// Newly revealed element: apply the enter effect.
-				// Already-visible elements: clear any class so they morph normally.
-				element.style.viewTransitionClass = (index === n - 1 && options.effect)
-					? `build-${options.effect}`
-					: '';
+				element.style.viewTransitionClass = '';
+
+				if (index === count - 1 && effect) {
+					element.classList.add(`build-${effect}`);
+					revealedElement = element;
+				}
 			} else {
 				element.style.visibility = 'hidden';
-				// Hidden elements: suppress both pseudo-elements so they don't
-				// crossfade in or out during the transition.
+				// Keep viewTransitionClass set so morph transitions can suppress
+				// crossfading on hidden elements when called inside startViewTransition.
 				element.style.viewTransitionClass = 'build-hidden';
 			}
 		});
+
+		this.#step = count;
+
+		if (revealedElement) {
+			const animationClass = `build-${effect}`;
+			return new Promise((resolve) => {
+				revealedElement.addEventListener('animationend', () => {
+					revealedElement.classList.remove(animationClass);
+					resolve();
+				}, {once: true});
+			});
+		}
+
+		return Promise.resolve();
+	}
+
+	// Reveal the next element. Only touches the single newly revealed element —
+	// all others are already in the correct state from the previous call.
+	// @parameter overrides [Object] Option overrides for this step.
+	// @returns [Promise]
+	next(overrides = {}) {
+		if (this.finished) return Promise.resolve();
+
+		const effect = overrides.effect !== undefined ? overrides.effect : this.#defaultEffect;
+		const element = this.#elements[this.#step];
+
+		element.style.viewTransitionName = `${this.#prefix}-${this.#step + 1}`;
+		element.style.visibility = 'visible';
+		element.style.viewTransitionClass = '';
+
+		this.#step += 1;
+
+		if (effect) {
+			const animationClass = `build-${effect}`;
+			element.classList.add(animationClass);
+			return new Promise((resolve) => {
+				element.addEventListener('animationend', () => {
+					element.classList.remove(animationClass);
+					resolve();
+				}, {once: true});
+			});
+		}
+
+		return Promise.resolve();
+	}
+
+	// Reveal all remaining elements in sequence, with `interval` milliseconds between each.
+	// An optional callback is invoked after each reveal — if it returns false, playback stops.
+	// Requires the builder to have been created via slide.find(...).builder() so that
+	// the timeouts are tracked and cancelled on slide change.
+	// @parameter interval [Number] Delay in milliseconds between each reveal.
+	// @parameter callback [Function | null] Optional. Receives the builder after each next().
+	//   Return false to stop playback early.
+	play(interval, callback = null) {
+		if (this.finished) return;
+
+		const playNext = () => {
+			this.next();
+			const shouldContinue = callback ? callback(this) !== false : true;
+			if (!this.finished && shouldContinue) {
+				this.#slide.setTimeout(playNext, interval);
+			}
+		};
+
+		this.#slide.setTimeout(playNext, interval);
+	}
+
+	// Returns true when all elements have been revealed.
+	get finished() {
+		return this.#step >= this.#elements.length;
+	}
+}
+
+// Represents a collection of elements within a slide to be revealed sequentially.
+// Has no side effects until show() is called.
+export class SlideElements {
+	#elements;
+	#slide;
+
+	constructor(slide, elements) {
+		this.#slide = slide;
+		this.#elements = elements;
+	}
+
+	// Create a stateful SlideBuilder for this element collection with default options.
+	// @parameter options [Object] Default options applied to every show() / next() call.
+	//   group: prefix for view-transition-name (default: "build")
+	//   effect: "fade", "fly-up", "fly-down", "fly-left", "fly-right", "scale"
+	// @returns [SlideBuilder]
+	builder(options = {}) {
+		return new SlideBuilder(this.#slide, this.#elements, options);
+	}
+
+	// Show the first `count` elements and hide the rest.
+	// Delegates to SlideBuilder for the actual implementation.
+	// @parameter count [Integer] Number of elements to show.
+	// @parameter options [Object]
+	//   group: prefix for view-transition-name (default: "build")
+	//   effect: "fade", "fly-up", "fly-down", "fly-left", "fly-right", "scale"
+	// @returns [Promise] Resolves when the animation completes (or immediately if no effect).
+	show(count, options = {}) {
+		return new SlideBuilder(this.#slide, this.#elements, options).show(count);
+	}
+}
+
+// Returned by Slide#after to enable relative delay chaining.
+// Each .after(delay, callback) fires that many milliseconds after the previous step.
+class SlideChain {
+	#slide;
+	#elapsed;
+
+	constructor(slide, elapsed) {
+		this.#slide = slide;
+		this.#elapsed = elapsed;
+	}
+
+	after(delay, callback) {
+		this.#elapsed += delay;
+		this.#slide.setTimeout(callback, this.#elapsed);
+		return this;
 	}
 }
 
 // The scripting context passed to each slide's javascript block.
 // Scopes element queries to the slide body.
 export class Slide {
+	#container;
+	#timeouts = [];
+
 	constructor(container) {
-		this._container = container;
+		this.#container = container;
 	}
 
 	// Find elements within this slide matching the given CSS selector.
@@ -46,7 +180,35 @@ export class Slide {
 	// @parameter selector [String] A CSS selector scoped to the slide body.
 	// @returns [SlideElements]
 	find(selector) {
-		const elements = Array.from(this._container.querySelectorAll(selector));
-		return new SlideElements(elements);
+		const elements = Array.from(this.#container.querySelectorAll(selector));
+		return new SlideElements(this, elements);
+	}
+
+	// Tracked setTimeout — use this in slide scripts instead of the global.
+	// Registered timeouts are automatically cancelled when the slide changes.
+	// @parameter callback [Function] The function to call after the delay.
+	// @parameter delay [Number] Delay in milliseconds.
+	// @returns [Number] The timeout ID.
+	setTimeout(callback, delay) {
+		const timeoutId = window.setTimeout(callback, delay);
+		this.#timeouts.push(timeoutId);
+		return timeoutId;
+	}
+
+	// Schedule a callback after a delay, returning a chainable object so
+	// subsequent .after(delay) calls are relative to the previous step.
+	// All timeouts are tracked and cancelled automatically on slide change.
+	// @parameter delay [Number] Delay in milliseconds from now (or previous step).
+	// @parameter callback [Function] The function to call after the delay.
+	// @returns [SlideChain]
+	after(delay, callback) {
+		this.setTimeout(callback, delay);
+		return new SlideChain(this, delay);
+	}
+
+	// Cancel all pending timeouts registered by this slide's script.
+	cancelTimeouts() {
+		this.#timeouts.forEach(timeoutId => clearTimeout(timeoutId));
+		this.#timeouts = [];
 	}
 }

data/readme.md

@@ -29,6 +29,19 @@ Please see the [project documentation](https://socketry.github.io/presently/) fo
 
 Please see the [project releases](https://socketry.github.io/presently/releases/index) for all releases.
 
+### v0.7.0
+
+  - Rework build effects to use direct CSS class animation rather than `view-transition-class`. `build-fade`, `build-fly-up`, etc. are now regular `@keyframes` classes applied to the revealed element, rather than view transition pseudo-element selectors. This decouples in-slide sequential animation from slide-level morph transitions.
+  - Rename `SlideElements#build` to `SlideElements#show` for clarity — `boxes.show(0)` / `boxes.show(3)` more clearly describes the outcome from the audience's perspective.
+  - Add `SlideElements#builder(options)` — returns a `SlideBuilder` with default options (group, effect) and a cached position, so callers can use `next()` instead of tracking the step count manually.
+  - Add `SlideBuilder#show(count, overrides)` — set visibility state to an arbitrary position. Returns a `Promise` that resolves when the reveal animation completes (or immediately when no effect is given).
+  - Add `SlideBuilder#next(overrides)` — reveal the next element with the builder's default effect, optionally overridden per call. O(1): only touches the single newly revealed element. Returns a `Promise`.
+  - Add `SlideBuilder#play(interval, callback)` — reveals all remaining elements in sequence with `interval` milliseconds between each. An optional callback is invoked after each reveal; return `false` to stop playback early. Requires the builder to be created via `slide.find(...).builder()` so timeouts are tracked and cancelled on slide change.
+  - Add `SlideBuilder#finished` getter — returns `true` when all elements have been revealed.
+  - Add `Slide#after(delay, callback)` — schedules a callback after a delay in milliseconds and returns a `SlideChain`. Subsequent `.after(delay, callback)` calls on the chain fire relative to the previous step, making sequential reveal timing easy to read and adjust.
+  - Add `Slide#setTimeout(callback, delay)` — a tracked replacement for the global `setTimeout`. All timeouts registered this way are automatically cancelled when the slide changes, preventing stale callbacks from firing after navigation. The global `setTimeout` in slide scripts is shadowed by this method automatically.
+  - Add `Slide#cancelTimeouts()` — cancels all pending timeouts registered by the slide's script. Called automatically by the presentation engine on every slide change.
+
 ### v0.6.0
 
   - Add `bake presently:slides:speakers` task to print a timing breakdown grouped by speaker. Each speaker's slides are listed in presentation order with individual and total durations, making it easy to balance talk time in multi-speaker presentations. Slides without a `speaker` key are grouped under `(no speaker)`.

data/releases.md

@@ -1,5 +1,18 @@
 # Releases
 
+## v0.7.0
+
+  - Rework build effects to use direct CSS class animation rather than `view-transition-class`. `build-fade`, `build-fly-up`, etc. are now regular `@keyframes` classes applied to the revealed element, rather than view transition pseudo-element selectors. This decouples in-slide sequential animation from slide-level morph transitions.
+  - Rename `SlideElements#build` to `SlideElements#show` for clarity — `boxes.show(0)` / `boxes.show(3)` more clearly describes the outcome from the audience's perspective.
+  - Add `SlideElements#builder(options)` — returns a `SlideBuilder` with default options (group, effect) and a cached position, so callers can use `next()` instead of tracking the step count manually.
+  - Add `SlideBuilder#show(count, overrides)` — set visibility state to an arbitrary position. Returns a `Promise` that resolves when the reveal animation completes (or immediately when no effect is given).
+  - Add `SlideBuilder#next(overrides)` — reveal the next element with the builder's default effect, optionally overridden per call. O(1): only touches the single newly revealed element. Returns a `Promise`.
+  - Add `SlideBuilder#play(interval, callback)` — reveals all remaining elements in sequence with `interval` milliseconds between each. An optional callback is invoked after each reveal; return `false` to stop playback early. Requires the builder to be created via `slide.find(...).builder()` so timeouts are tracked and cancelled on slide change.
+  - Add `SlideBuilder#finished` getter — returns `true` when all elements have been revealed.
+  - Add `Slide#after(delay, callback)` — schedules a callback after a delay in milliseconds and returns a `SlideChain`. Subsequent `.after(delay, callback)` calls on the chain fire relative to the previous step, making sequential reveal timing easy to read and adjust.
+  - Add `Slide#setTimeout(callback, delay)` — a tracked replacement for the global `setTimeout`. All timeouts registered this way are automatically cancelled when the slide changes, preventing stale callbacks from firing after navigation. The global `setTimeout` in slide scripts is shadowed by this method automatically.
+  - Add `Slide#cancelTimeouts()` — cancels all pending timeouts registered by the slide's script. Called automatically by the presentation engine on every slide change.
+
 ## v0.6.0
 
   - Add `bake presently:slides:speakers` task to print a timing breakdown grouped by speaker. Each speaker's slides are listed in presentation order with individual and total durations, making it easy to balance talk time in multi-speaker presentations. Slides without a `speaker` key are grouped under `(no speaker)`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: presently
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Samuel Williams