@wandelbots/wandelbots-js-react-components 2.36.0 → 2.37.0-pr.feature-states-for-cycle-timer.379.4ca80c1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wandelbots/wandelbots-js-react-components",
-  "version": "2.36.0",
+  "version": "2.37.0-pr.feature-states-for-cycle-timer.379.4ca80c1",
   "description": "React UI toolkit for building applications on top of the Wandelbots platform",
   "type": "module",
   "sideEffects": false,

package/src/components/AppHeader.tsx

@@ -85,7 +85,7 @@ export const AppHeader = externalizeComponent(
             ...sx,
           }}
         >
-          <Toolbar sx={{ minHeight: "64px !important" }}>
+          <Toolbar sx={{ minHeight: "62px !important" }}>
             {/* App Icon */}
             <Box sx={{ mr: 2, display: "flex", alignItems: "center" }}>
               {appIcon}

package/src/components/CycleTimer/CycleTimer.ts

@@ -0,0 +1,6 @@
+export { CycleTimer } from "./index"
+export type {
+  CycleTimerControls,
+  CycleTimerProps,
+  CycleTimerState,
+} from "./types"

package/src/components/CycleTimer/DefaultVariant.tsx

@@ -0,0 +1,272 @@
+import { Box, Fade, Typography, useTheme } from "@mui/material"
+import { Gauge } from "@mui/x-charts/Gauge"
+import { useTranslation } from "react-i18next"
+import type { AnimationState, TimerState } from "./types"
+import { formatTime } from "./utils"
+
+interface DefaultVariantProps {
+  timerState: TimerState
+  animationState: AnimationState
+  hasError: boolean
+  className?: string
+}
+
+export const DefaultVariant = ({
+  timerState,
+  animationState,
+  hasError,
+  className,
+}: DefaultVariantProps) => {
+  const { t } = useTranslation()
+  const theme = useTheme()
+  const { currentState, remainingTime, maxTime, currentProgress } = timerState
+  const {
+    showErrorAnimation,
+    showPauseAnimation,
+    showPulsatingText,
+    pulsatingFinished,
+    showLabels,
+    showMainText,
+  } = animationState
+
+  return (
+    <Box
+      className={className}
+      sx={{
+        position: "relative",
+        width: 264,
+        height: 264,
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+      }}
+    >
+      <Gauge
+        width={264}
+        height={264}
+        value={currentState === "idle" ? 0 : currentProgress}
+        valueMin={0}
+        valueMax={100}
+        innerRadius={currentState === "idle" ? "75%" : "76%"}
+        outerRadius="90%"
+        skipAnimation={true}
+        text={() => ""}
+        sx={{
+          opacity: showPauseAnimation || showErrorAnimation ? 0.6 : 1,
+          transition: "opacity 0.5s ease-out",
+          [`& .MuiGauge-valueArc`]: {
+            fill: hasError
+              ? theme.palette.error.light
+              : theme.palette.success.main,
+            transition: "fill 0.5s ease-out",
+          },
+          [`& .MuiGauge-referenceArc`]: {
+            fill: currentState === "idle" ? "#292B3F" : "white",
+            stroke: currentState === "idle" ? "#181927" : "transparent",
+            strokeWidth: currentState === "idle" ? 2 : 0,
+            transition:
+              "fill 0.5s ease-out, stroke 0.5s ease-out, stroke-width 0.5s ease-out",
+          },
+          [`& .MuiGauge-valueText`]: {
+            display: "none",
+          },
+          [`& .MuiGauge-text`]: {
+            display: "none",
+          },
+        }}
+      />
+
+      {/* Center content overlay */}
+      <Box
+        sx={{
+          position: "absolute",
+          top: "50%",
+          left: "50%",
+          transform: "translate(-50%, -50%)",
+          width: 200,
+          height: 200,
+          borderRadius: "50%",
+          display: "flex",
+          flexDirection: "column",
+          alignItems: "center",
+          justifyContent: "center",
+          textAlign: "center",
+          gap: 1,
+          transition: "background-color 0.5s ease-out",
+        }}
+      >
+        {/* Top label */}
+        <Box
+          sx={{
+            height: "16px",
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            marginBottom: 0.5,
+          }}
+        >
+          <Fade
+            in={
+              showLabels &&
+              !hasError &&
+              currentState !== "idle" &&
+              currentState !== "countup" &&
+              currentState !== "success"
+            }
+            timeout={200}
+          >
+            <Typography
+              variant="body2"
+              sx={{
+                fontSize: "12px",
+                color:
+                  currentState === "measured"
+                    ? pulsatingFinished
+                      ? theme.palette.text.secondary
+                      : showPulsatingText
+                        ? theme.palette.success.main
+                        : theme.palette.text.secondary
+                    : theme.palette.text.secondary,
+                transition: "color 0.8s ease-in-out",
+              }}
+            >
+              {currentState === "measuring"
+                ? t("CycleTimer.CycleTime.lb", "Cycle Time")
+                : currentState === "measured"
+                  ? t("CycleTimer.CycleTime.lb", "Cycle Time")
+                  : currentState === "countdown"
+                    ? t("CycleTimer.RemainingTime.lb", "Remaining Time")
+                    : ""}
+            </Typography>
+          </Fade>
+        </Box>
+
+        {/* Main display */}
+        <Box
+          sx={{
+            position: "relative",
+            height: "48px",
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            marginBottom: 0.5,
+          }}
+        >
+          {/* Idle state text */}
+          <Fade
+            in={showMainText && currentState === "idle" && !hasError}
+            timeout={200}
+          >
+            <Typography
+              variant="body2"
+              sx={{
+                position: "absolute",
+                fontSize: "12px",
+                fontWeight: 400,
+                color: "rgba(255, 255, 255, 0.7)",
+                lineHeight: "166%",
+                letterSpacing: "0.17px",
+                textAlign: "center",
+                width: "150px",
+                height: "20px",
+              }}
+            >
+              {t("CycleTimer.WaitingForCycle.lb", "Waiting for program cycle")}
+            </Typography>
+          </Fade>
+
+          {/* Error text */}
+          <Fade in={showMainText && hasError} timeout={200}>
+            <Typography
+              variant="h3"
+              sx={{
+                position: "absolute",
+                fontSize: "40px",
+                fontWeight: 400,
+                color: "#FFFFFF",
+                lineHeight: "116.7%",
+              }}
+            >
+              {t("CycleTimer.Error.lb", "Error")}
+            </Typography>
+          </Fade>
+
+          {/* Normal timer text */}
+          <Fade
+            in={
+              showMainText &&
+              !hasError &&
+              currentState !== "idle" &&
+              currentState !== "success"
+            }
+            timeout={200}
+          >
+            <Typography
+              variant="h1"
+              sx={{
+                position: "absolute",
+                fontSize: "48px",
+                fontWeight: 500,
+                color:
+                  currentState === "measured"
+                    ? theme.palette.text.primary
+                    : theme.palette.text.primary,
+                lineHeight: 1,
+                transition: "color 0.5s ease-out",
+              }}
+            >
+              {formatTime(remainingTime)}
+            </Typography>
+          </Fade>
+        </Box>
+
+        {/* Bottom label */}
+        <Box
+          sx={{
+            height: "16px",
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+          }}
+        >
+          <Fade
+            in={
+              showLabels &&
+              !hasError &&
+              currentState !== "idle" &&
+              currentState !== "countup" &&
+              currentState !== "success"
+            }
+            timeout={200}
+          >
+            <Typography
+              variant="body2"
+              sx={{
+                fontSize: "12px",
+                color:
+                  currentState === "measured"
+                    ? pulsatingFinished
+                      ? theme.palette.text.secondary
+                      : showPulsatingText
+                        ? theme.palette.success.main
+                        : theme.palette.text.secondary
+                    : theme.palette.text.secondary,
+                transition: "color 0.8s ease-in-out",
+              }}
+            >
+              {currentState === "measuring"
+                ? t("CycleTimer.Measuring.lb", "measuring...")
+                : currentState === "measured"
+                  ? t("CycleTimer.Determined.lb", "determined")
+                  : currentState === "countdown" && maxTime !== null
+                    ? t("CycleTimer.OfTime.lb", {
+                        time: formatTime(maxTime),
+                      })
+                    : ""}
+            </Typography>
+          </Fade>
+        </Box>
+      </Box>
+    </Box>
+  )
+}

package/src/components/CycleTimer/SmallVariant.tsx

@@ -0,0 +1,190 @@
+import { Box, Typography, useTheme } from "@mui/material"
+import { useTranslation } from "react-i18next"
+import type { AnimationState, TimerState } from "./types"
+import { formatTime } from "./utils"
+
+interface SmallVariantProps {
+  timerState: TimerState
+  animationState: AnimationState
+  hasError: boolean
+  compact: boolean
+  className?: string
+}
+
+export const SmallVariant = ({
+  timerState,
+  animationState,
+  hasError,
+  compact,
+  className,
+}: SmallVariantProps) => {
+  const { t } = useTranslation()
+  const theme = useTheme()
+  const { currentState, remainingTime, maxTime } = timerState
+  const {
+    showErrorAnimation,
+    showPauseAnimation,
+    showPulsatingText,
+    pulsatingFinished,
+  } = animationState
+
+  // Simple text-only mode for compact variant in certain states
+  if (compact && (currentState === "countup" || currentState === "idle")) {
+    return (
+      <Box
+        className={className}
+        sx={{
+          display: "flex",
+          alignItems: "center",
+          m: 0,
+        }}
+      >
+        <Typography
+          variant="body2"
+          sx={{
+            color: hasError
+              ? theme.palette.error.light
+              : theme.palette.text.primary,
+            fontSize: "14px",
+            transition: "color 0.5s ease-out",
+          }}
+        >
+          {hasError
+            ? t("CycleTimer.Error.lb", "Error")
+            : currentState === "idle"
+              ? "0:00"
+              : formatTime(remainingTime)}
+        </Typography>
+      </Box>
+    )
+  }
+
+  return (
+    <Box
+      className={className}
+      sx={{
+        display: "flex",
+        alignItems: "center",
+        m: 0,
+        gap: 1,
+      }}
+    >
+      {/* Animated progress ring icon */}
+      {!(
+        currentState === "countup" ||
+        (currentState === "idle" && compact)
+      ) && (
+        <Box
+          sx={{
+            width: 20,
+            height: 20,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            opacity: showPauseAnimation || showErrorAnimation ? 0.6 : 1,
+            transition: "opacity 0.5s ease-out",
+          }}
+        >
+          <svg
+            width="20"
+            height="20"
+            viewBox="0 0 20 20"
+            style={{ transform: "rotate(-90deg)" }}
+            role="img"
+            aria-label="Timer progress"
+          >
+            {/* Background ring */}
+            <circle
+              cx="10"
+              cy="10"
+              r="8"
+              fill="none"
+              stroke={
+                hasError
+                  ? theme.palette.error.light
+                  : currentState === "measured"
+                    ? pulsatingFinished
+                      ? theme.palette.text.secondary
+                      : showPulsatingText
+                        ? theme.palette.success.main
+                        : theme.palette.text.secondary
+                    : theme.palette.success.main
+              }
+              strokeWidth="2"
+              opacity={0.3}
+              style={{
+                transition: "stroke 0.8s ease-in-out",
+              }}
+            />
+            {/* Progress ring */}
+            <circle
+              cx="10"
+              cy="10"
+              r="8"
+              fill="none"
+              stroke={
+                hasError
+                  ? theme.palette.error.light
+                  : currentState === "measured"
+                    ? pulsatingFinished
+                      ? theme.palette.text.secondary
+                      : showPulsatingText
+                        ? theme.palette.success.main
+                        : theme.palette.text.secondary
+                    : theme.palette.success.main
+              }
+              strokeWidth="2"
+              strokeLinecap="round"
+              strokeDasharray={`${2 * Math.PI * 8}`}
+              strokeDashoffset={`${2 * Math.PI * 8 * (1 - (currentState === "idle" ? 0 : timerState.currentProgress) / 100)}`}
+              style={{
+                transition:
+                  "stroke-dashoffset 0.1s ease-out, stroke 0.8s ease-in-out",
+              }}
+            />
+          </svg>
+        </Box>
+      )}
+
+      {/* Timer text display */}
+      <Typography
+        variant="body2"
+        sx={{
+          color: hasError
+            ? theme.palette.error.light
+            : currentState === "idle"
+              ? "rgba(255, 255, 255, 0.7)"
+              : currentState === "measured"
+                ? pulsatingFinished
+                  ? theme.palette.text.secondary
+                  : showPulsatingText
+                    ? theme.palette.success.main
+                    : theme.palette.text.secondary
+                : theme.palette.text.primary,
+          fontSize: currentState === "idle" ? "12px" : "14px",
+          lineHeight: currentState === "idle" ? "166%" : "normal",
+          letterSpacing: currentState === "idle" ? "0.17px" : "normal",
+          transition: "color 0.8s ease-in-out, font-size 0.3s ease-out",
+        }}
+      >
+        {hasError
+          ? t("CycleTimer.Error.lb", "Error")
+          : currentState === "idle"
+            ? t("CycleTimer.WaitingForCycle.lb", "Waiting for program cycle")
+            : currentState === "measuring"
+              ? compact
+                ? `${formatTime(remainingTime)} ${t("CycleTimer.Time.lb", { time: "" }).replace(/\s*$/, "")}`
+                : `${formatTime(remainingTime)} / ${t("CycleTimer.Measuring.lb", "measuring...")}`
+              : currentState === "measured"
+                ? compact
+                  ? `${formatTime(remainingTime)} ${t("CycleTimer.Time.lb", { time: "" }).replace(/\s*$/, "")}`
+                  : `${formatTime(remainingTime)} / ${t("CycleTimer.Determined.lb", "determined")}`
+                : currentState === "countdown" && maxTime !== null
+                  ? compact
+                    ? `${formatTime(remainingTime)} ${t("CycleTimer.Time.lb", { time: "" }).replace(/\s*$/, "")}`
+                    : `${formatTime(remainingTime)} / ${t("CycleTimer.Time.lb", { time: formatTime(maxTime) })}`
+                  : formatTime(remainingTime)}
+      </Typography>
+    </Box>
+  )
+}

package/src/components/CycleTimer/index.tsx

@@ -0,0 +1,143 @@
+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,
+        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()
+          }
+
+          // Trigger fade transition
+          triggerFadeTransition()
+        } else {
+          // No state change or first time - set initial state
+          setInitialAnimationState()
+        }
+
+        prevStateRef.current = timerState.currentState
+      }, [
+        timerState.currentState,
+        stopPulsatingAnimation,
+        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,58 @@
+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
+}