@escape-game-over/atlas 0.1.30 → 0.1.31

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.30",
+    "version": "0.1.31",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/astro/carousel.ts

@@ -62,6 +62,17 @@ export interface CarouselOptions {
      * renders, and calling would make a project write the first position twice.
      */
     readonly onChange: (index: number) => void;
+    /**
+     * Called with `autoplayMs` whenever a countdown to the next automatic
+     * advance begins, and with `null` when autoplay stops.
+     *
+     * For a progress bar. A countdown begins on attach, after every tick and
+     * after every manual move, and each one starts from zero — so the bar
+     * restarts on every number and stops on `null`, and never has to know why.
+     * A hold (hover, focus, a hidden tab, `pause`) and a detach report `null`
+     * once, not once per reason.
+     */
+    readonly onCountdown?: (ms: number | null) => void;
 }
 
 export interface Carousel {
@@ -107,6 +118,7 @@ export function carousel(options: CarouselOptions): Carousel {
         swipeThreshold = 10,
         lockMs = 500,
         onChange,
+        onCountdown,
     } = options;
 
     /**
@@ -143,9 +155,19 @@ export function carousel(options: CarouselOptions): Carousel {
      */
     const holds = new Set<string>();
 
+    /** Whether a countdown is running, so `null` is reported once per stop. */
+    let counting = false;
+
+    const stopAutoplay = (): void => {
+        clearInterval(autoplayTimer);
+        if (!counting) return;
+        counting = false;
+        onCountdown?.(null);
+    };
+
     const hold = (reason: string): void => {
         holds.add(reason);
-        clearInterval(autoplayTimer);
+        stopAutoplay();
     };
 
     const release = (reason: string): void => {
@@ -171,16 +193,28 @@ export function carousel(options: CarouselOptions): Carousel {
     };
 
     const restartAutoplay = (): void => {
-        clearInterval(autoplayTimer);
         // Nothing to rotate through, nobody watching, or no autoplay asked
         // for — in each case, nothing to schedule.
-        if (autoplayMs === undefined || !canMove || !attached) return;
-        if (holds.size > 0) return;
+        if (
+            autoplayMs === undefined ||
+            !canMove ||
+            !attached ||
+            holds.size > 0
+        ) {
+            stopAutoplay();
+            return;
+        }
+        clearInterval(autoplayTimer);
         autoplayTimer = setInterval(() => {
             // No `restartAutoplay` here: the interval already paces itself, and
             // resetting it from inside its own tick would only churn timers.
             if (claim()) move(index + 1);
+            // Reported even when the lock refused the move: the next tick is
+            // still `autoplayMs` away either way.
+            onCountdown?.(autoplayMs);
         }, autoplayMs);
+        counting = true;
+        onCountdown?.(autoplayMs);
     };
 
     /** The only place `index` changes. `at` may be out of range or negative. */
@@ -326,7 +360,7 @@ export function carousel(options: CarouselOptions): Carousel {
             return () => {
                 listeners.abort();
                 attached = false;
-                clearInterval(autoplayTimer);
+                stopAutoplay();
 
                 // The automatic holds belong to this attachment: an element
                 // detached while hovered would otherwise keep "hover" forever,