@coinbase/cds-common 8.41.0 → 8.43.0

package/CHANGELOG.md

@@ -8,6 +8,16 @@ All notable changes to this project will be documented in this file.
 
 <!-- template-start -->
 
+## 8.43.0 (2/6/2026 PST)
+
+#### 🚀 Updates
+
+- Carousel autoplay. [[#361](https://github.com/coinbase/cds/pull/361)]
+
+## 8.42.0 ((2/4/2026, 01:51 PM PST))
+
+This is an artificial version bump with no new change.
+
 ## 8.41.0 ((2/4/2026, 09:22 AM PST))
 
 This is an artificial version bump with no new change.

package/dts/carousel/index.d.ts

@@ -0,0 +1,2 @@
+export * from './useCarouselAutoplay';
+//# sourceMappingURL=index.d.ts.map

package/dts/carousel/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/carousel/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC"}

package/dts/carousel/useCarouselAutoplay.d.ts

@@ -0,0 +1,83 @@
+export type CarouselAutoplayOptions = {
+  /**
+   * Whether autoplay is enabled.
+   */
+  enabled: boolean;
+  /**
+   * The interval in milliseconds between auto-advances.
+   */
+  interval: number;
+  /**
+   * Callback fired when autoplay starts.
+   */
+  onStart?: () => void;
+  /**
+   * Callback fired when autoplay stops.
+   */
+  onStop?: () => void;
+};
+export type CarouselAutoplayState = {
+  /**
+   * Whether autoplay is actively running (enabled AND not stopped AND not paused).
+   */
+  isPlaying: boolean;
+  /**
+   * Whether autoplay has been stopped by the user.
+   */
+  isStopped: boolean;
+  /**
+   * Whether autoplay is temporarily paused due to user interaction (hover/touch).
+   */
+  isPaused: boolean;
+};
+export type CarouselAutoplayApi = {
+  /**
+   * Start autoplay. Resumes from paused progress if available.
+   */
+  start: () => void;
+  /**
+   * Stop autoplay. Preserves current progress for resuming later.
+   */
+  stop: () => void;
+  /**
+   * Toggle autoplay on/off.
+   */
+  toggle: () => void;
+  /**
+   * Reset the autoplay timer (e.g., after manual navigation).
+   */
+  reset: () => void;
+  /**
+   * Temporarily pause autoplay (e.g., on hover/touch). Does not change isStopped state.
+   * Progress is preserved and will resume from where it left off.
+   */
+  pause: () => void;
+  /**
+   * Resume autoplay after interaction pause. Only resumes if not user-stopped.
+   */
+  resume: () => void;
+  /**
+   * Get the current remaining time. Useful for calculating progress in platform-native animations.
+   */
+  getRemainingTime: () => number;
+  /**
+   * Add a listener to be called when the autoplay timer completes.
+   * Returns an unsubscribe function.
+   */
+  addCompletionListener: (callback: () => void) => () => void;
+};
+/**
+ * Combined state and API returned by useCarouselAutoplay.
+ */
+export type CarouselAutoplay = CarouselAutoplayState & CarouselAutoplayApi;
+/**
+ * A hook for managing carousel autoplay state and timing.
+ * Provides controls for starting, stopping, and resetting autoplay.
+ */
+export declare const useCarouselAutoplay: ({
+  enabled,
+  interval,
+  onStart,
+  onStop,
+}: CarouselAutoplayOptions) => CarouselAutoplay;
+//# sourceMappingURL=useCarouselAutoplay.d.ts.map

package/dts/carousel/useCarouselAutoplay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCarouselAutoplay.d.ts","sourceRoot":"","sources":["../../src/carousel/useCarouselAutoplay.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,uBAAuB,GAAG;IACpC;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,qBAAqB,GAAG;IAClC;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;OAEG;IACH,QAAQ,EAAE,OAAO,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC;;OAEG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB;;OAEG;IACH,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB;;OAEG;IACH,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB;;OAEG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB;;;OAGG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB;;OAEG;IACH,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB;;OAEG;IACH,gBAAgB,EAAE,MAAM,MAAM,CAAC;IAC/B;;;OAGG;IACH,qBAAqB,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAC;CAC7D,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,qBAAqB,GAAG,mBAAmB,CAAC;AAE3E;;;GAGG;AACH,eAAO,MAAM,mBAAmB,GAAI,yCAKjC,uBAAuB,KAAG,gBAqK5B,CAAC"}

package/dts/hooks/useTimer.d.ts

@@ -3,5 +3,7 @@ export declare const useTimer: () => {
   clear: () => void;
   pause: () => number;
   resume: () => void;
+  getRemainingTime: () => number;
+  reset: () => void;
 };
 //# sourceMappingURL=useTimer.d.ts.map

package/dts/hooks/useTimer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useTimer.d.ts","sourceRoot":"","sources":["../../src/hooks/useTimer.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,QAAQ;sBAgBN,MAAM,IAAI,YAAY,MAAM;;;;CA4C1C,CAAC"}
+{"version":3,"file":"useTimer.d.ts","sourceRoot":"","sources":["../../src/hooks/useTimer.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,QAAQ;sBAgBN,MAAM,IAAI,YAAY,MAAM;;;;;;CAgE1C,CAAC"}

package/dts/index.d.ts

@@ -1,3 +1,4 @@
+export * from './carousel';
 export * from './core/theme';
 export * from './hooks/useToggler';
 export * from './lottie/lottieUtils';

package/dts/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mCAAmC,CAAC;AAClD,cAAc,SAAS,CAAC;AACxB,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mCAAmC,CAAC;AAClD,cAAc,SAAS,CAAC;AACxB,cAAc,sBAAsB,CAAC;AACrC,cAAc,cAAc,CAAC"}

package/esm/carousel/index.js

@@ -0,0 +1 @@
+export * from './useCarouselAutoplay';

package/esm/carousel/useCarouselAutoplay.js

@@ -0,0 +1,150 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useTimer } from '../hooks/useTimer';
+
+/**
+ * Combined state and API returned by useCarouselAutoplay.
+ */
+
+/**
+ * A hook for managing carousel autoplay state and timing.
+ * Provides controls for starting, stopping, and resetting autoplay.
+ */
+export const useCarouselAutoplay = _ref => {
+  let {
+    enabled,
+    interval,
+    onStart,
+    onStop
+  } = _ref;
+  const timer = useTimer();
+  const [isStopped, setIsStopped] = useState(false);
+  const [isPaused, setIsPaused] = useState(false);
+
+  // Use refs for synchronous checks to avoid stale closure issues
+  const isPlayingRef = useRef(false);
+  const isPausedRef = useRef(false);
+  const isStoppedRef = useRef(false);
+
+  // Listeners for timer completion
+  const listenersRef = useRef(new Set());
+  const notifyListeners = useCallback(() => {
+    // Snapshot listeners to avoid issues when Set is modified during iteration
+    const listeners = [...listenersRef.current];
+    listeners.forEach(listener => listener());
+  }, []);
+  const addCompletionListener = useCallback(callback => {
+    listenersRef.current.add(callback);
+    return () => {
+      listenersRef.current.delete(callback);
+    };
+  }, []);
+  const isPlaying = enabled && !isStopped && !isPaused;
+  const getRemainingTime = useCallback(() => {
+    return timer.getRemainingTime();
+  }, [timer]);
+  const startAutoplay = useCallback(fromPausedProgress => {
+    if (!enabled || isStoppedRef.current || isPausedRef.current) return;
+    const advance = () => {
+      if (!isPlayingRef.current) return;
+      notifyListeners();
+    };
+    if (fromPausedProgress) {
+      timer.resume();
+    } else {
+      timer.start(advance, interval);
+    }
+    if (!isPlayingRef.current) {
+      isPlayingRef.current = true;
+      onStart === null || onStart === void 0 || onStart();
+    }
+  }, [enabled, interval, timer, onStart, notifyListeners]);
+  const start = useCallback(() => {
+    isStoppedRef.current = false;
+    setIsStopped(false);
+    // Start timer synchronously if not paused
+    if (!isPausedRef.current && enabled) {
+      startAutoplay(false);
+    }
+  }, [enabled, startAutoplay]);
+  const stop = useCallback(() => {
+    timer.pause();
+    isStoppedRef.current = true;
+    setIsStopped(true);
+    if (isPlayingRef.current) {
+      isPlayingRef.current = false;
+      onStop === null || onStop === void 0 || onStop();
+    }
+  }, [timer, onStop]);
+  const toggle = useCallback(() => {
+    if (isStoppedRef.current) {
+      start();
+    } else {
+      stop();
+    }
+  }, [start, stop]);
+  const reset = useCallback(() => {
+    timer.reset();
+
+    // Start a fresh timer with the full interval
+    const advance = () => {
+      if (!isPlayingRef.current) return;
+      notifyListeners();
+    };
+    timer.start(advance, interval);
+
+    // If paused, immediately pause the timer so getRemainingTime() returns the full interval
+    if (isPausedRef.current) {
+      timer.pause();
+    }
+  }, [timer, interval, notifyListeners]);
+  const pause = useCallback(() => {
+    if (!isPlayingRef.current) return;
+    timer.pause();
+    isPausedRef.current = true;
+    setIsPaused(true);
+  }, [timer]);
+  const resume = useCallback(() => {
+    if (isStoppedRef.current) return;
+    // Update ref synchronously BEFORE starting timer
+    isPausedRef.current = false;
+    setIsPaused(false);
+    // Start timer synchronously so getRemainingTime() returns correct value
+    if (enabled) {
+      const hasRemainingTime = timer.getRemainingTime() > 0;
+      startAutoplay(hasRemainingTime);
+    }
+  }, [enabled, timer, startAutoplay]);
+
+  // Handle initial mount and enabled changes
+  // This runs on mount when enabled=true to start autoplay initially
+  useEffect(() => {
+    if (enabled && !isStoppedRef.current && !isPausedRef.current) {
+      // Only start if not already playing (avoid double-start)
+      if (!isPlayingRef.current) {
+        startAutoplay(false);
+      }
+    }
+    // Keep isPlayingRef in sync with derived state
+    isPlayingRef.current = isPlaying;
+  }, [enabled, isPlaying, startAutoplay]);
+
+  // Cleanup timer on unmount
+  useEffect(() => {
+    return () => {
+      timer.clear();
+    };
+  }, [timer]);
+  return useMemo(() => ({
+    isPlaying,
+    isStopped,
+    isPaused,
+    start,
+    stop,
+    toggle,
+    reset,
+    pause,
+    resume,
+    getRemainingTime,
+    addCompletionListener
+  }), [isPlaying, isStopped, isPaused, start, stop, toggle, reset, pause, resume, getRemainingTime, addCompletionListener]);
+};

package/esm/hooks/useTimer.js

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useMemo, useRef } from 'react';
 
-// timer for single execution
+// Timer for single execution
 export const useTimer = () => {
   const timerRef = useRef();
   const startTimeRef = useRef(0);
@@ -11,11 +11,11 @@ export const useTimer = () => {
     if (timerRef.current) {
       clearTimeout(timerRef.current);
       timerRef.current = undefined;
-      isPausedRef.current = false;
     }
+    isPausedRef.current = false;
   }, []);
   const start = useCallback((callback, duration) => {
-    // clear existing timer
+    // Clear existing timer
     clear();
     timerRef.current = setTimeout(callback, duration);
     callbackRef.current = callback;
@@ -37,6 +37,22 @@ export const useTimer = () => {
       isPausedRef.current = false;
     }
   }, [start]);
+  const getRemainingTime = useCallback(() => {
+    if (isPausedRef.current) {
+      return remainingTimeRef.current;
+    }
+    if (!timerRef.current) {
+      return 0;
+    }
+    const elapsed = Date.now() - startTimeRef.current;
+    return Math.max(0, remainingTimeRef.current - elapsed);
+  }, []);
+  const reset = useCallback(() => {
+    clear();
+    remainingTimeRef.current = 0;
+    callbackRef.current = undefined;
+    isPausedRef.current = false;
+  }, [clear]);
   useEffect(() => {
     return () => {
       clear();
@@ -46,6 +62,8 @@ export const useTimer = () => {
     start,
     clear,
     pause,
-    resume
-  }), [start, clear, pause, resume]);
+    resume,
+    getRemainingTime,
+    reset
+  }), [start, clear, pause, resume, getRemainingTime, reset]);
 };

package/esm/index.js

@@ -1,3 +1,4 @@
+export * from './carousel';
 export * from './core/theme';
 export * from './hooks/useToggler';
 export * from './lottie/lottieUtils';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinbase/cds-common",
-  "version": "8.41.0",
+  "version": "8.43.0",
   "description": "Coinbase Design System - Common",
   "repository": {
     "type": "git",
@@ -38,9 +38,9 @@
     "react-dom": "^18.3.1"
   },
   "dependencies": {
-    "@coinbase/cds-icons": "^5.10.0",
+    "@coinbase/cds-icons": "^5.11.0",
     "@coinbase/cds-illustrations": "^4.31.0",
-    "@coinbase/cds-mcp-server": "^8.41.0",
+    "@coinbase/cds-mcp-server": "^8.43.0",
     "@coinbase/cds-utils": "^2.3.5",
     "@modelcontextprotocol/sdk": "^1.13.1",
     "d3-array": "^3.2.4",