feat(Spinner): add support for synchronized animations

.changeset/afraid-buckets-build.md

@@ -0,0 +1,5 @@
+---
+'@primer/react': minor
+---
+
+Add feature flag to control whether Spinner animations are synchronized

packages/react/src/FeatureFlags/DefaultFeatureFlags.ts

@@ -7,4 +7,5 @@ export const DefaultFeatureFlags = FeatureFlagScope.create({
   primer_react_select_panel_fullscreen_on_narrow: false,
   primer_react_select_panel_order_selected_at_top: false,
   primer_react_select_panel_remove_active_descendant: false,
+  primer_react_spinner_synchronize_animations: false,
 })

packages/react/src/Spinner/Spinner.examples.stories.tsx

@@ -1,4 +1,4 @@
-import React from 'react'
+import React, {useEffect, useState} from 'react'
 import type {Meta} from '@storybook/react-vite'
 import Spinner from './Spinner'
 import {Button} from '..'
@@ -95,3 +95,32 @@ export const FullLifecycleVisibleLoadingText = () => {
     </div>
   )
 }
+
+export const SynchronizedSpinners = () => (
+  <>
+    <Spinner />
+    <Delay ms={250}>
+      <Spinner />
+    </Delay>
+    <Delay ms={750}>
+      <Spinner />
+    </Delay>
+    <Delay ms={1500}>
+      <Spinner />
+    </Delay>
+    <Delay ms={2350}>
+      <Spinner />
+    </Delay>
+  </>
+)
+
+function Delay({children, ms}: {children: React.ReactNode; ms: number}) {
+  const [show, setShow] = useState(false)
+
+  useEffect(() => {
+    const timeout = setTimeout(() => setShow(true), ms)
+    return () => clearTimeout(timeout)
+  }, [ms])
+
+  return show ? <>{children}</> : null
+}

packages/react/src/Spinner/Spinner.tsx

@@ -1,10 +1,12 @@
+import {clsx} from 'clsx'
 import type React from 'react'
-import {useState, useEffect} from 'react'
+import {useCallback, useEffect, useRef, useState, useSyncExternalStore} from 'react'
 import {VisuallyHidden} from '../VisuallyHidden'
 import type {HTMLDataAttributes} from '../internal/internal-types'
 import {useId} from '../hooks'
 import classes from './Spinner.module.css'
-import {clsx} from 'clsx'
+import {useMedia} from '../hooks/useMedia'
+import {useFeatureFlag} from '../FeatureFlags'
 
 const sizeMap = {
   small: '16px',
@@ -34,6 +36,8 @@ function Spinner({
   delay = false,
   ...props
 }: SpinnerProps) {
+  const syncAnimationsEnabled = useFeatureFlag('primer_react_spinner_synchronize_animations')
+  const animationRef = useSpinnerAnimation()
   const size = sizeMap[sizeKey]
   const hasHiddenLabel = srText !== null && ariaLabel === undefined
   const labelId = useId()
@@ -58,6 +62,7 @@ function Spinner({
     /* inline-flex removes the extra line height */
     <span className={classes.Box}>
       <svg
+        ref={syncAnimationsEnabled ? animationRef : undefined}
         height={size}
         width={size}
         viewBox="0 0 16 16"
@@ -93,4 +98,127 @@ function Spinner({
 
 Spinner.displayName = 'Spinner'
 
+type Subscriber = () => void
+
+type AnimationTimingValue = {
+  startTime: CSSNumberish | null
+}
+
+type AnimationTimingStore = {
+  subscribers: Set<Subscriber>
+  value: AnimationTimingValue
+  update(startTime: CSSNumberish): void
+  subscribe(subscriber: Subscriber): () => void
+  getSnapshot(): AnimationTimingValue
+  getServerSnapshot(): AnimationTimingValue
+}
+
+const animationTimingStore: AnimationTimingStore = {
+  subscribers: new Set<() => void>(),
+  value: {
+    startTime: null,
+  },
+  update(startTime) {
+    const value = {
+      startTime,
+    }
+    animationTimingStore.value = value
+    for (const subscriber of animationTimingStore.subscribers) {
+      subscriber()
+    }
+  },
+  subscribe(subscriber) {
+    animationTimingStore.subscribers.add(subscriber)
+    return () => {
+      animationTimingStore.subscribers.delete(subscriber)
+    }
+  },
+  getSnapshot() {
+    return animationTimingStore.value
+  },
+  getServerSnapshot() {
+    return animationTimingStore.value
+  },
+}
+
+/**
+ * A utility hook for reading a common `startTime` value so that all animations
+ * are in sync. This is a global value and is coordinated through `useSyncExternalStore`.
+ */
+function useAnimationTiming() {
+  return useSyncExternalStore(
+    animationTimingStore.subscribe,
+    animationTimingStore.getSnapshot,
+    animationTimingStore.getServerSnapshot,
+  )
+}
+
+/**
+ * Uses a technique from Spectrum to coordinate animations:
+ * @see https://github.com/adobe/react-spectrum/blob/ab5e6f3dba4235dafab9f81f8b5c506ce5f11230/packages/%40react-spectrum/s2/src/Skeleton.tsx#L21
+ */
+function useSpinnerAnimation() {
+  const ref = useRef<Animation | null>(null)
+  const noMotionPreference = useMedia('(prefers-reduced-motion: no-preference)', false)
+  const animationTiming = useAnimationTiming()
+  return useCallback(
+    (element: HTMLElement | SVGSVGElement | null) => {
+      if (!element) {
+        return
+      }
+
+      if (ref.current !== null) {
+        return
+      }
+
+      if (noMotionPreference) {
+        const cssAnimation = element.getAnimations().find((animation): animation is CSSAnimation => {
+          if (animation instanceof CSSAnimation) {
+            return animation.animationName.startsWith('Spinner') && animation.animationName.endsWith('rotate-keyframes')
+          }
+          return false
+        })
+        // If we can find a CSS Animation, pause it and we will use the Web
+        // Animations API to pick up from where it left off
+        cssAnimation?.pause()
+
+        ref.current = element.animate(
+          [
+            {
+              transform: 'rotate(0deg)',
+            },
+            {
+              transform: 'rotate(360deg)',
+            },
+          ],
+          {
+            // var(--base-duration-1000)
+            duration: 1000,
+            // var(--base-easing-linear)
+            easing: 'cubic-bezier(0,0,1,1)',
+            iterations: Infinity,
+          },
+        )
+
+        // When the `startTime` value from `animationTimingStore` is `null` we
+        // are currently hydrating on the client. In this case, the first
+        // spinner to mount will set the `startTime` for all other spinners.
+        if (animationTiming.startTime === null) {
+          const startTime = cssAnimation?.startTime ?? 0
+
+          animationTimingStore.update(startTime)
+
+          // We use `startTime` to sync different animations. When all animations
+          // have the same startTime they will be in sync.
+          // @see https://developer.mozilla.org/en-US/docs/Web/API/Animation/startTime#syncing_different_animations
+          ref.current.startTime = startTime
+        } else {
+          ref.current.startTime = animationTiming.startTime
+        }
+      }
+    },
+    [noMotionPreference, animationTiming],
+  )
+}
+
 export default Spinner