@flamingo-stack/openframe-frontend-core 0.0.733 → 0.0.735

package/src/components/ui/snap-carousel.tsx

@@ -3,6 +3,7 @@
 import { type ReactNode, useCallback, useEffect, useRef, useState } from 'react';
 import { useAutoplay } from '../../hooks/ui/use-autoplay';
 import { useInView } from '../../hooks/ui/use-in-view';
+import { useResumableTimeout } from '../../hooks/ui/use-resumable-timeout';
 import { cn } from '../../utils/cn';
 import { Chevron02LeftIcon } from '../icons-v2-generated/arrows/chevron-02-left-icon';
 import { Chevron02RightIcon } from '../icons-v2-generated/arrows/chevron-02-right-icon';
@@ -39,20 +40,31 @@ export interface SnapCarouselProps<T> {
 const GAP_PX = 12;
 
 /**
- * The active dot filling up while the carousel waits to advance. A transition,
- * not a keyframe animation: it mounts empty and is told to be full one frame
- * later, taking the whole interval to get there.
+ * The active dot's fill: how much of the slide's wait has been run. It starts
+ * from where the wait stands (`ranMs`, nothing for a new slide) and runs to
+ * full over what is LEFT of it. While the carousel is not advancing it stands
+ * still at that point; it never empties because the carousel left the screen.
  */
-function DotFill({ durationMs }: { durationMs: number }) {
-  const [full, setFull] = useState(false);
+function DotFill({ durationMs, ranMs, running }: { durationMs: number; ranMs: number; running: boolean }) {
+  // One frame at the starting point, so the browser has it to run from.
+  const [going, setGoing] = useState(false);
   useEffect(() => {
-    const frame = requestAnimationFrame(() => setFull(true));
-    return () => cancelAnimationFrame(frame);
-  }, []);
+    if (!running) return undefined;
+    const frame = requestAnimationFrame(() => setGoing(true));
+    return () => {
+      cancelAnimationFrame(frame);
+      setGoing(false);
+    };
+  }, [running]);
+  const moving = running && going;
   return (
     <span
-      className="absolute inset-0 origin-left bg-ods-text-primary transition-transform ease-linear"
-      style={{ transform: full ? 'scaleX(1)' : 'scaleX(0)', transitionDuration: `${durationMs}ms` }}
+      className="absolute inset-0 origin-left bg-ods-text-primary ease-linear"
+      style={{
+        transform: `scaleX(${moving ? 1 : durationMs > 0 ? ranMs / durationMs : 0})`,
+        transitionProperty: moving ? 'transform' : 'none',
+        transitionDuration: `${Math.max(0, durationMs - ranMs)}ms`,
+      }}
     />
   );
 }
@@ -122,12 +134,15 @@ export function SnapCarousel<T>({
   const canAutoAdvance = autoAdvanceMs > 0 && count > 1;
   const playing = auto.playing && canAutoAdvance;
 
-  // Restarts on every slide change, so a swipe or an arrow is followed by a full interval.
-  useEffect(() => {
-    if (!playing) return undefined;
-    const timer = setTimeout(() => goTo(index >= count - 1 ? 0 : index + 1), autoAdvanceMs);
-    return () => clearTimeout(timer);
-  }, [playing, index, count, autoAdvanceMs, goTo]);
+  // A new slide starts a whole interval (a swipe or an arrow is followed by a
+  // full one); an interruption (off screen, a hold, another tab) only pauses it.
+  const ranMs = useResumableTimeout({
+    running: playing,
+    durationMs: autoAdvanceMs,
+    resetKey: index,
+    onElapsed: () => goTo(index >= count - 1 ? 0 : index + 1),
+  });
+  const showsWait = canAutoAdvance && !auto.reducedMotion;
 
   const setRefs = useCallback(
     (node: HTMLDivElement | null) => {
@@ -172,12 +187,13 @@ export function SnapCarousel<T>({
               className={cn(
                 'relative h-1.5 overflow-hidden rounded-full transition-[width] duration-200 motion-reduce:transition-none',
                 dotIndex === index ? 'w-6' : 'w-1.5',
-                dotIndex === index && !playing ? 'bg-ods-text-primary' : 'bg-ods-border',
+                // A carousel that never advances by itself marks its slide with a whole dot.
+                dotIndex === index && !showsWait ? 'bg-ods-text-primary' : 'bg-ods-border',
               )}
             >
-              {dotIndex === index && playing && (
-                // Re-keyed per slide so the fill restarts from empty.
-                <DotFill key={index} durationMs={autoAdvanceMs} />
+              {dotIndex === index && showsWait && (
+                // Re-keyed per slide so a NEW slide starts from empty; a pause keeps its place.
+                <DotFill key={index} durationMs={autoAdvanceMs} ranMs={ranMs} running={playing} />
               )}
             </span>
           ))}

package/src/hooks/ui/index.ts

@@ -35,3 +35,4 @@ export * from './use-autoplay';
 export * from './use-active-section';
 export * from './use-nav-menus';
 export * from './use-visitor-os';
+export * from './use-resumable-timeout';

package/src/hooks/ui/use-resumable-timeout.ts

@@ -0,0 +1,55 @@
+'use client';
+
+import { useEffect, useRef, useState } from 'react';
+
+export interface UseResumableTimeoutOptions {
+  /** The wait counts down only while this is true. */
+  running: boolean;
+  /** How long the whole wait is. */
+  durationMs: number;
+  /** A new value starts the wait over from nothing (the slide changed). */
+  resetKey: string | number;
+  /** Called once the whole wait has been run. */
+  onElapsed: () => void;
+}
+
+/**
+ * A wait that PAUSES instead of starting over: `durationMs` of time spent
+ * `running`, however many times it is interrupted. A carousel that scrolls off
+ * screen half-way through a slide comes back with half a slide left, not a
+ * whole one, and the bar that shows the wait picks up where it stopped.
+ *
+ * Returns how much of the wait had been run at the last stop (0 after a
+ * reset), which is what a progress bar draws while it is not running and
+ * where it resumes from.
+ */
+export function useResumableTimeout({ running, durationMs, resetKey, onElapsed }: UseResumableTimeoutOptions): number {
+  // What has been run so far, for the key it was run under. The ref is the
+  // clock's own memory (read when a stretch starts); the state is the same
+  // figure for whoever draws it.
+  const banked = useRef({ key: resetKey, ms: 0 });
+  const [shown, setShown] = useState({ key: resetKey, ms: 0 });
+
+  const onElapsedRef = useRef(onElapsed);
+  useEffect(() => {
+    onElapsedRef.current = onElapsed;
+  }, [onElapsed]);
+
+  useEffect(() => {
+    // A new key: the wait starts over.
+    if (banked.current.key !== resetKey) banked.current = { key: resetKey, ms: 0 };
+    if (!running) return undefined;
+    const startedAt = Date.now();
+    const timer = setTimeout(() => onElapsedRef.current(), Math.max(0, durationMs - banked.current.ms));
+    return () => {
+      clearTimeout(timer);
+      // Bank what this stretch ran.
+      const ms = Math.min(durationMs, banked.current.ms + (Date.now() - startedAt));
+      banked.current = { key: resetKey, ms };
+      setShown({ key: resetKey, ms });
+    };
+  }, [running, durationMs, resetKey]);
+
+  // Under another key (the slide changed) nothing has been run yet.
+  return shown.key === resetKey ? shown.ms : 0;
+}

package/src/hooks/use-scenario-player.ts

@@ -1,7 +1,8 @@
 'use client';
 
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useState } from 'react';
 import { type AutoplayHoldProps, useAutoplay } from './ui/use-autoplay';
+import { useResumableTimeout } from './ui/use-resumable-timeout';
 
 /**
  * How soon the first step follows the moment the demo becomes playable (it
@@ -78,9 +79,10 @@ export interface UseScenarioPlayerResult {
  * not held by the visitor, motion allowed. Under reduced motion it parks on the last step
  * of the current scenario, and every scenario can still be read by choosing it.
  *
- * The moment it becomes playable, and at the top of every scenario (the
- * rotation moved on, or a tab was chosen), its first step follows within
- * `START_MS`, not a whole step later; from there every step takes `stepMs`.
+ * A step is `stepMs` of time spent playing: an interruption pauses it and it
+ * resumes with what was left (`useResumableTimeout`, the one clock every timed
+ * thing here runs on). At the top of a scenario whose first step is the empty
+ * stage, that step is left within `START_MS`.
  *
  * A visitor's own choice (`go`, `setStep`) moves the clock there and lets go of
  * any hold; the rotation carries on from that point.
@@ -110,34 +112,28 @@ export function useScenarioPlayer({
   const [started, setStarted] = useState(false);
   if (playing && !started) setStarted(true);
 
-  // True from the moment it becomes playable until its first tick has been scheduled.
-  const starting = useRef(false);
-  const wasPlaying = useRef(false);
-  useEffect(() => {
-    if (playing && !wasPlaying.current) starting.current = true;
-    wasPlaying.current = playing;
-    if (!playing) return undefined;
-    const atEnd = rawStep >= lastStep;
-    // The first step comes quickly, both after it becomes playable and at the
-    // top of every scenario whose step 0 is the empty stage (the rotation
-    // moved on, or the visitor chose a tab): a stage that sits empty for a
-    // whole step after a tap reads as not responding. A finished scenario still
-    // holds its full time: it is there to be read.
-    const quickStart = emptyFirstStep && (starting.current || rawStep === 0) && !atEnd;
-    starting.current = false;
-    const timer = setTimeout(
-      () => {
-        if (atEnd) {
-          setScenario(current => (current + 1) % scenarioCount);
-          setRawStep(0);
-        } else {
-          setRawStep(current => Math.min(current, lastStep) + 1);
-        }
-      },
-      atEnd ? holdMs : quickStart ? Math.min(START_MS, stepMs) : stepMs,
-    );
-    return () => clearTimeout(timer);
-  }, [playing, rawStep, lastStep, stepMs, holdMs, scenario, scenarioCount, emptyFirstStep]);
+  // ONE clock for everything that waits and moves on (`useResumableTimeout`,
+  // the carousel's too): a step is `stepMs` of time spent PLAYING. Interrupted
+  // (off screen, held, another tab), it comes back with what was left of the
+  // step, never a whole new one and never a skipped one.
+  const atEnd = rawStep >= lastStep;
+  // Step 0 of a scenario whose first step is the empty stage is left at once:
+  // a stage that sits empty for a whole step after a tap reads as not
+  // responding. A finished scenario holds its full time: it is there to be read.
+  const leavesAtOnce = emptyFirstStep && rawStep === 0 && !atEnd;
+  useResumableTimeout({
+    running: playing,
+    durationMs: atEnd ? holdMs : leavesAtOnce ? Math.min(START_MS, stepMs) : stepMs,
+    resetKey: `${scenario}:${Math.min(rawStep, lastStep)}`,
+    onElapsed: () => {
+      if (atEnd) {
+        setScenario(current => (current + 1) % scenarioCount);
+        setRawStep(0);
+      } else {
+        setRawStep(current => Math.min(current, lastStep) + 1);
+      }
+    },
+  });
 
   // A visitor's choice is an instruction to play from there: it lets go of any hold.
   const setStep = useCallback(