@wandelbots/wandelbots-js-react-components 2.37.0 → 2.38.0

package/src/components/CycleTimer/index.tsx

@@ -0,0 +1,157 @@
+import { observer } from "mobx-react-lite"
+import { useEffect, useRef } from "react"
+import { externalizeComponent } from "../../externalizeComponent"
+import { DefaultVariant } from "./DefaultVariant"
+import { SmallVariant } from "./SmallVariant"
+import type { CycleTimerProps } from "./types"
+import { useAnimations } from "./useAnimations"
+import { useTimerLogic } from "./useTimerLogic"
+
+/**
+ * A circular gauge timer component that shows the remaining time of a cycle or counts up
+ *
+ * Features:
+ * - Custom SVG circular gauge with 264px diameter and 40px thickness
+ * - Multiple states: idle, measuring, measured, countdown, countup, success
+ * - Idle state: shows "Waiting for program cycle" with transparent inner circle
+ * - Measuring state: counts up with "Cycle Time" / "measuring..." labels
+ * - Measured state: shows final time with "Cycle Time" / "determined" labels in pulsating green
+ * - Countdown mode: shows remaining time prominently, counts down to zero
+ * - Count-up mode: shows elapsed time without special labels
+ * - Success state: brief green flash after cycle completion
+ * - Displays appropriate labels based on state
+ * - Automatically counts down/up and triggers callback when reaching zero (countdown only)
+ * - Full timer control: start, pause, resume functionality
+ * - Support for starting with elapsed time (resume mid-cycle)
+ * - Error state support: pauses timer and shows error styling (red color)
+ * - Smooth fade transitions between different text states
+ * - Pulsating text animation for completed measuring state
+ * - Fully localized with i18next
+ * - Material-UI theming integration
+ * - Small variant with animated progress icon (gauge border only) next to text or simple text-only mode
+ */
+export const CycleTimer = externalizeComponent(
+  observer(
+    ({
+      onCycleComplete,
+      onCycleEnd,
+      onMeasuringComplete,
+      autoStart = true,
+      variant = "default",
+      compact = false,
+      className,
+      hasError = false,
+    }: CycleTimerProps) => {
+      const prevStateRef = useRef<string | undefined>(undefined)
+
+      // Initialize animation hooks
+      const {
+        animationState,
+        triggerPauseAnimation,
+        triggerErrorAnimation,
+        clearErrorAnimation,
+        startPulsatingAnimation,
+        stopPulsatingAnimation,
+        startIdleAnimations,
+        stopIdleAnimations,
+        triggerFadeTransition,
+        setInitialAnimationState,
+        cleanup,
+      } = useAnimations()
+
+      // Initialize timer logic
+      const { timerState, controls } = useTimerLogic({
+        autoStart,
+        onCycleEnd,
+        onMeasuringComplete,
+        hasError,
+        onPauseAnimation: triggerPauseAnimation,
+        onErrorAnimation: triggerErrorAnimation,
+        onClearErrorAnimation: clearErrorAnimation,
+        onStartPulsating: startPulsatingAnimation,
+      })
+
+      // Handle state changes with fade transitions
+      useEffect(() => {
+        const prevState = prevStateRef.current
+
+        if (
+          prevStateRef.current !== undefined &&
+          prevState !== timerState.currentState
+        ) {
+          // Stop pulsating animation if leaving measured state
+          if (prevState === "measured") {
+            stopPulsatingAnimation()
+          }
+
+          // Stop idle animations if leaving idle state
+          if (prevState === "idle") {
+            stopIdleAnimations()
+          }
+
+          // Trigger fade transition
+          triggerFadeTransition()
+        } else {
+          // No state change or first time - set initial state
+          setInitialAnimationState()
+        }
+
+        // Start idle animations if entering idle state
+        if (timerState.currentState === "idle") {
+          startIdleAnimations()
+        }
+
+        prevStateRef.current = timerState.currentState
+      }, [
+        timerState.currentState,
+        stopPulsatingAnimation,
+        stopIdleAnimations,
+        startIdleAnimations,
+        triggerFadeTransition,
+        setInitialAnimationState,
+      ])
+
+      // Provide controls to parent component
+      useEffect(() => {
+        let isMounted = true
+        const timeoutId = setTimeout(() => {
+          if (isMounted) {
+            onCycleComplete(controls)
+          }
+        }, 0)
+
+        return () => {
+          isMounted = false
+          clearTimeout(timeoutId)
+        }
+      }, [onCycleComplete, controls])
+
+      // Cleanup on unmount
+      useEffect(() => {
+        return cleanup
+      }, [cleanup])
+
+      // Render appropriate variant
+      if (variant === "small") {
+        return (
+          <SmallVariant
+            timerState={timerState}
+            animationState={animationState}
+            hasError={hasError}
+            compact={compact}
+            className={className}
+          />
+        )
+      }
+
+      return (
+        <DefaultVariant
+          timerState={timerState}
+          animationState={animationState}
+          hasError={hasError}
+          className={className}
+        />
+      )
+    },
+  ),
+)

package/src/components/CycleTimer/types.ts

@@ -0,0 +1,60 @@
+export type CycleTimerState =
+  | "idle" // Initial state showing "Waiting for program cycle"
+  | "measuring" // Counting up without max time, showing "Cycle Time" / "measuring..."
+  | "measured" // Completed measuring state showing "Cycle Time" / "determined" with pulsating green text
+  | "countdown" // Counting down with max time
+  | "countup" // Simple count up without special text
+  | "success" // Brief success state after cycle completion
+
+export interface CycleTimerControls {
+  startNewCycle: (maxTimeSeconds?: number, elapsedSeconds?: number) => void
+  startMeasuring: (elapsedSeconds?: number) => void
+  startCountUp: (elapsedSeconds?: number) => void
+  setIdle: () => void
+  completeMeasuring: () => void
+  pause: () => void
+  resume: () => void
+  isPaused: () => boolean
+}
+
+export interface CycleTimerProps {
+  /**
+   * Callback that receives the timer control functions
+   */
+  onCycleComplete: (controls: CycleTimerControls) => void
+  /** Callback fired when a cycle actually completes (reaches zero) */
+  onCycleEnd?: () => void
+  /** Callback fired when measuring cycle completes */
+  onMeasuringComplete?: () => void
+  /** Whether the timer should start automatically when maxTime is set */
+  autoStart?: boolean
+  /** Visual variant of the timer */
+  variant?: "default" | "small"
+  /** For small variant: whether to show remaining time details (compact hides them) */
+  compact?: boolean
+  /** Additional CSS classes */
+  className?: string
+  /** Whether the timer is in an error state (pauses timer and shows error styling) */
+  hasError?: boolean
+}
+
+export interface TimerState {
+  currentState: CycleTimerState
+  remainingTime: number
+  maxTime: number | null
+  isRunning: boolean
+  isPausedState: boolean
+  currentProgress: number
+  wasRunningBeforeError: boolean
+}
+
+export interface AnimationState {
+  showPauseAnimation: boolean
+  showErrorAnimation: boolean
+  showPulsatingText: boolean
+  pulsatingFinished: boolean
+  showLabels: boolean
+  showMainText: boolean
+  showIdlePulsating: boolean
+  idleDotsCount: number
+}

package/src/components/CycleTimer/useAnimations.ts

@@ -0,0 +1,202 @@
+import { useCallback, useRef, useState } from "react"
+import type { AnimationState } from "./types"
+
+export const useAnimations = () => {
+  const [animationState, setAnimationState] = useState<AnimationState>({
+    showPauseAnimation: false,
+    showErrorAnimation: false,
+    showPulsatingText: false,
+    pulsatingFinished: false,
+    showLabels: true,
+    showMainText: true,
+    showIdlePulsating: false,
+    idleDotsCount: 0,
+  })
+
+  // Refs for managing timeouts and intervals
+  const pauseAnimationTimeoutRef = useRef<NodeJS.Timeout | null>(null)
+  const errorAnimationTimeoutRef = useRef<NodeJS.Timeout | null>(null)
+  const pulsatingIntervalRef = useRef<NodeJS.Timeout | null>(null)
+  const fadeTimeoutRef = useRef<NodeJS.Timeout | null>(null)
+  const pulseCountRef = useRef<number>(0)
+  const idlePulsatingIntervalRef = useRef<NodeJS.Timeout | null>(null)
+  const idleDotsIntervalRef = useRef<NodeJS.Timeout | null>(null)
+
+  const triggerPauseAnimation = useCallback(() => {
+    setAnimationState((prev) => ({ ...prev, showPauseAnimation: true }))
+
+    if (pauseAnimationTimeoutRef.current) {
+      clearTimeout(pauseAnimationTimeoutRef.current)
+    }
+
+    pauseAnimationTimeoutRef.current = setTimeout(() => {
+      setAnimationState((prev) => ({ ...prev, showPauseAnimation: false }))
+    }, 800)
+  }, [])
+
+  const triggerErrorAnimation = useCallback(() => {
+    setAnimationState((prev) => ({ ...prev, showErrorAnimation: true }))
+
+    if (errorAnimationTimeoutRef.current) {
+      clearTimeout(errorAnimationTimeoutRef.current)
+    }
+
+    errorAnimationTimeoutRef.current = setTimeout(() => {
+      setAnimationState((prev) => ({ ...prev, showErrorAnimation: false }))
+    }, 600)
+  }, [])
+
+  const clearErrorAnimation = useCallback(() => {
+    setAnimationState((prev) => ({ ...prev, showErrorAnimation: false }))
+    if (errorAnimationTimeoutRef.current) {
+      clearTimeout(errorAnimationTimeoutRef.current)
+    }
+  }, [])
+
+  const startPulsatingAnimation = useCallback((onComplete?: () => void) => {
+    pulseCountRef.current = 0
+    // Start with fade to success color
+    setAnimationState((prev) => ({
+      ...prev,
+      showPulsatingText: true,
+      pulsatingFinished: false,
+    }))
+
+    // After initial success color fade, start slow pulsating like idle
+    setTimeout(() => {
+      setAnimationState((prev) => ({
+        ...prev,
+        pulsatingFinished: true, // This will keep the success color and start slow pulsating
+      }))
+
+      // Start slow pulsating animation similar to idle
+      pulsatingIntervalRef.current = setInterval(() => {
+        setAnimationState((prev) => ({
+          ...prev,
+          showPulsatingText: !prev.showPulsatingText,
+        }))
+      }, 2000) // Same slow timing as idle pulsating
+
+      if (onComplete) {
+        onComplete()
+      }
+    }, 800) // Initial success color display duration
+  }, [])
+
+  const stopPulsatingAnimation = useCallback(() => {
+    if (pulsatingIntervalRef.current) {
+      clearInterval(pulsatingIntervalRef.current)
+      pulsatingIntervalRef.current = null
+    }
+    // Reset all pulsating states to ensure colors are reset
+    setAnimationState((prev) => ({
+      ...prev,
+      showPulsatingText: false,
+      pulsatingFinished: false,
+    }))
+    pulseCountRef.current = 0
+  }, [])
+
+  const startIdleAnimations = useCallback(() => {
+    // Start pulsating animation for the text
+    setAnimationState((prev) => ({
+      ...prev,
+      showIdlePulsating: true,
+    }))
+
+    idlePulsatingIntervalRef.current = setInterval(() => {
+      setAnimationState((prev) => ({
+        ...prev,
+        showIdlePulsating: !prev.showIdlePulsating,
+      }))
+    }, 2000) // Slower pulsate every 2 seconds
+
+    // Start animated dots
+    idleDotsIntervalRef.current = setInterval(() => {
+      setAnimationState((prev) => ({
+        ...prev,
+        idleDotsCount: (prev.idleDotsCount + 1) % 4, // Cycle through 0, 1, 2, 3
+      }))
+    }, 800) // Change dots every 800ms
+  }, [])
+
+  const stopIdleAnimations = useCallback(() => {
+    if (idlePulsatingIntervalRef.current) {
+      clearInterval(idlePulsatingIntervalRef.current)
+      idlePulsatingIntervalRef.current = null
+    }
+    if (idleDotsIntervalRef.current) {
+      clearInterval(idleDotsIntervalRef.current)
+      idleDotsIntervalRef.current = null
+    }
+    setAnimationState((prev) => ({
+      ...prev,
+      showIdlePulsating: false,
+      idleDotsCount: 0,
+    }))
+  }, [])
+
+  const triggerFadeTransition = useCallback(() => {
+    setAnimationState((prev) => ({
+      ...prev,
+      showLabels: false,
+      showMainText: false,
+    }))
+
+    if (fadeTimeoutRef.current) {
+      clearTimeout(fadeTimeoutRef.current)
+    }
+
+    fadeTimeoutRef.current = setTimeout(() => {
+      setAnimationState((prev) => ({
+        ...prev,
+        showLabels: true,
+        showMainText: true,
+      }))
+    }, 200)
+  }, [])
+
+  const setInitialAnimationState = useCallback(() => {
+    setAnimationState((prev) => ({
+      ...prev,
+      showLabels: true,
+      showMainText: true,
+    }))
+  }, [])
+
+  // Cleanup function
+  const cleanup = useCallback(() => {
+    if (pauseAnimationTimeoutRef.current) {
+      clearTimeout(pauseAnimationTimeoutRef.current)
+    }
+    if (errorAnimationTimeoutRef.current) {
+      clearTimeout(errorAnimationTimeoutRef.current)
+    }
+    if (fadeTimeoutRef.current) {
+      clearTimeout(fadeTimeoutRef.current)
+    }
+    if (pulsatingIntervalRef.current) {
+      clearInterval(pulsatingIntervalRef.current)
+    }
+    if (idlePulsatingIntervalRef.current) {
+      clearInterval(idlePulsatingIntervalRef.current)
+    }
+    if (idleDotsIntervalRef.current) {
+      clearInterval(idleDotsIntervalRef.current)
+    }
+  }, [])
+
+  return {
+    animationState,
+    triggerPauseAnimation,
+    triggerErrorAnimation,
+    clearErrorAnimation,
+    startPulsatingAnimation,
+    stopPulsatingAnimation,
+    startIdleAnimations,
+    stopIdleAnimations,
+    triggerFadeTransition,
+    setInitialAnimationState,
+    cleanup,
+  }
+}