@wandelbots/wandelbots-js-react-components 2.27.1 → 2.28.0

package/src/components/utils/interpolation.ts

@@ -0,0 +1,379 @@
+import React from "react"
+
+/**
+ * Smooth value interpolation utility using spring physics with tension and friction.
+ * Designed for React Three Fiber applications with smooth, natural animations.
+ *
+ * Features:
+ * - Spring physics with configurable tension and friction
+ * - Frame-rate independent using delta timing
+ * - Handles irregular frame timing and rapid target updates
+ * - Manual update() calls for useFrame integration (no automatic RAF loop)
+ * - Direct mutation for performance
+ *
+ * @example
+ * ```tsx
+ * // Basic spring animation
+ * const interpolator = new ValueInterpolator([0, 0, 0], {
+ *   tension: 120, // Higher = faster, stiffer spring (default: 120)
+ *   friction: 20, // Higher = more damping, less oscillation (default: 20)
+ *   onChange: (values) => {
+ *     robot.joints.forEach((joint, i) => {
+ *       joint.rotation.y = values[i]
+ *     })
+ *   }
+ * })
+ *
+ * interpolator.setTarget([1.5, -0.8, 2.1])
+ *
+ * // React Three Fiber usage
+ * function MyComponent() {
+ *   const [interpolator] = useInterpolation([0, 0, 0])
+ *
+ *   useFrame((state, delta) => {
+ *     interpolator.update(delta)
+ *   })
+ *
+ *   useEffect(() => {
+ *     interpolator.setTarget([1, 2, 3])
+ *   }, [])
+ *
+ *   return <mesh position={interpolator.getCurrentValues()} />
+ * }
+ * ```
+ */
+
+export interface InterpolationOptions {
+  /** Spring tension (higher = faster, stiffer spring) - default: 120 */
+  tension?: number
+  /** Spring friction (higher = more damping, less oscillation) - default: 20 */
+  friction?: number
+  /** Minimum threshold to consider interpolation complete - default: 0.001 */
+  threshold?: number
+  /** Callback when values change during interpolation */
+  onChange?: (values: number[]) => void
+  /** Callback when interpolation reaches target values */
+  onComplete?: (values: number[]) => void
+}
+
+export class ValueInterpolator {
+  private currentValues: number[] = []
+  private targetValues: number[] = []
+  private previousTargetValues: number[] = []
+  private targetUpdateTime: number = 0
+  private animationId: number | null = null
+  private options: Required<InterpolationOptions>
+  private updateCount: number = 0 // Track how many updates have occurred
+
+  // Spring physics state
+  private velocities: number[] = []
+
+  constructor(
+    initialValues: number[] = [],
+    options: InterpolationOptions = {},
+  ) {
+    this.options = {
+      tension: 120,
+      friction: 20,
+      threshold: 0.001,
+      onChange: () => {},
+      onComplete: () => {},
+      ...options,
+    }
+
+    this.currentValues = [...initialValues]
+    this.targetValues = [...initialValues]
+    this.previousTargetValues = [...initialValues]
+    this.velocities = new Array(initialValues.length).fill(0)
+    this.targetUpdateTime = performance.now()
+    this.updateCount = 0
+  }
+
+  /**
+   * Update interpolation using spring physics
+   *
+   * Call this method every frame for smooth animation. In React Three Fiber,
+   * call from within useFrame callback with the provided delta time.
+   *
+   * @param delta - Time elapsed since last update in seconds (e.g., 1/60 ≈ 0.0167 for 60fps)
+   * @returns true when interpolation is complete (all values reached their targets)
+   */
+  update(delta: number = 1 / 60): boolean {
+    let hasChanges = false
+    let isComplete = true
+
+    // Increment update counter for initialization smoothing
+    this.updateCount++
+
+    // Limit delta to prevent physics instability during large frame drops
+    const clampedDelta = Math.min(delta, 1 / 15) // Maximum 66ms frame time allowed
+
+    // Apply gentle ramp-up for the first few frames to prevent initial jumpiness
+    // Only apply reduced force for the very first frame to prevent jarring starts
+    const initializationFactor =
+      this.updateCount === 1
+        ? 0.7 // Slightly reduced force only on the very first frame
+        : 1
+
+    for (let i = 0; i < this.currentValues.length; i++) {
+      const current = this.currentValues[i]
+      const target = this.targetValues[i]
+      const velocity = this.velocities[i]
+
+      // Calculate spring physics forces
+      const displacement = target - current
+      const springForce =
+        displacement * this.options.tension * initializationFactor
+      const dampingForce = velocity * this.options.friction
+
+      // Calculate acceleration from net force (F = ma, assuming mass = 1)
+      const acceleration = springForce - dampingForce
+
+      // Integrate physics using Verlet method for numerical stability
+      const newVelocity = velocity + acceleration * clampedDelta
+      const newValue = current + newVelocity * clampedDelta
+
+      // Determine if this value has settled (close to target with low velocity)
+      const isValueComplete =
+        Math.abs(displacement) < this.options.threshold &&
+        Math.abs(newVelocity) < this.options.threshold * 10
+
+      if (!isValueComplete) {
+        isComplete = false
+        // Continue spring animation
+        this.currentValues[i] = newValue
+        this.velocities[i] = newVelocity
+        hasChanges = true
+      } else {
+        // Snap exactly to target when close enough (prevents endless micro-movements)
+        if (this.currentValues[i] !== target) {
+          this.currentValues[i] = target
+          this.velocities[i] = 0
+          hasChanges = true
+        }
+      }
+    }
+
+    if (hasChanges) {
+      this.options.onChange(this.currentValues)
+    }
+
+    if (isComplete) {
+      this.options.onComplete(this.currentValues)
+    }
+
+    return isComplete
+  }
+
+  /**
+   * Set new target values for the interpolation to move towards
+   *
+   * Includes smart blending for very rapid target updates (faster than 120fps)
+   * to prevent jarring movements when targets change frequently.
+   */
+  setTarget(newValues: number[]): void {
+    const now = performance.now()
+    const timeSinceLastUpdate = now - this.targetUpdateTime
+
+    // Store previous target for smooth transitions
+    this.previousTargetValues = [...this.targetValues]
+    this.targetValues = [...newValues]
+    this.targetUpdateTime = now
+
+    // Reset update counter for smooth initialization when target changes
+    this.updateCount = 0
+
+    // Apply target blending for extremely rapid updates to prevent jarring jumps
+    // Only activates when targets change faster than 120fps (< 8ms between updates)
+    // AND this is not the first target being set (avoid blending initial target with initial values)
+    const isInitialTargetSet = this.previousTargetValues.every(
+      (val, i) => val === this.currentValues[i],
+    )
+
+    if (
+      timeSinceLastUpdate < 8 &&
+      timeSinceLastUpdate > 0 &&
+      this.previousTargetValues.length > 0 &&
+      !isInitialTargetSet // Don't blend if this is the first meaningful target change
+    ) {
+      // Blend between previous and new target based on time elapsed
+      const blendFactor = Math.min(timeSinceLastUpdate / 8, 1) // 0 to 1 over 8ms
+
+      for (let i = 0; i < this.targetValues.length; i++) {
+        const prev = this.previousTargetValues[i] || 0
+        const next = newValues[i] || 0
+
+        // Only blend significant changes to avoid unnecessary smoothing
+        const change = Math.abs(next - prev)
+        if (change > 0.1) {
+          this.targetValues[i] = prev + (next - prev) * blendFactor
+        }
+      }
+    }
+
+    // Ensure value and velocity arrays have matching lengths
+    while (this.currentValues.length < newValues.length) {
+      this.currentValues.push(newValues[this.currentValues.length])
+      this.velocities.push(0) // New values start with zero velocity
+    }
+    if (this.currentValues.length > newValues.length) {
+      this.currentValues = this.currentValues.slice(0, newValues.length)
+      this.velocities = this.velocities.slice(0, newValues.length)
+    }
+
+    // Does not start automatic interpolation - requires manual update() calls
+    // This design prevents conflicts when using with React Three Fiber's useFrame
+  }
+
+  /**
+   * Get a copy of all current interpolated values
+   */
+  getCurrentValues(): number[] {
+    return [...this.currentValues]
+  }
+
+  /**
+   * Get a single interpolated value by its array index
+   */
+  getValue(index: number): number {
+    return this.currentValues[index] ?? 0
+  }
+
+  /**
+   * Check if automatic interpolation is currently running
+   *
+   * This only tracks auto-interpolation started with startAutoInterpolation().
+   * Manual update() calls are not tracked by this method.
+   */
+  isInterpolating(): boolean {
+    return this.animationId !== null
+  }
+
+  /**
+   * Stop automatic interpolation if it's running
+   *
+   * This cancels the internal animation frame loop but does not affect
+   * manual update() calls.
+   */
+  stop(): void {
+    if (this.animationId !== null) {
+      cancelAnimationFrame(this.animationId)
+      this.animationId = null
+    }
+  }
+
+  /**
+   * Instantly set values without interpolation
+   */
+  setImmediate(values: number[]): void {
+    this.stop()
+    this.currentValues = [...values]
+    this.targetValues = [...values]
+    this.previousTargetValues = [...values]
+    this.velocities = new Array(values.length).fill(0) // Reset velocities
+    this.targetUpdateTime = performance.now()
+    this.updateCount = 0 // Reset update counter
+    this.options.onChange(this.currentValues)
+  }
+
+  /**
+   * Update interpolation options
+   */
+  updateOptions(newOptions: Partial<InterpolationOptions>): void {
+    this.options = { ...this.options, ...newOptions }
+  }
+
+  /**
+   * Start automatic interpolation with an animation loop
+   *
+   * This begins a requestAnimationFrame loop that calls update() automatically.
+   * For React Three Fiber components, prefer using manual update() calls
+   * within useFrame hooks instead.
+   */
+  startAutoInterpolation(): void {
+    this.startInterpolation()
+  }
+
+  /**
+   * Clean up all resources and stop any running animations
+   *
+   * This cancels any active animation frames and resets internal state.
+   * Call this when the component unmounts or is no longer needed.
+   */
+  destroy(): void {
+    this.stop()
+  }
+
+  private startInterpolation(): void {
+    if (this.animationId !== null) {
+      return // Already interpolating
+    }
+
+    this.animate()
+  }
+
+  private animate = (): void => {
+    // Use delta timing with a fallback for consistent automatic animations
+    const isComplete = this.update(1 / 60) // Simulate 60fps for auto-interpolation
+
+    if (!isComplete) {
+      this.animationId = requestAnimationFrame(this.animate)
+    } else {
+      this.animationId = null
+    }
+  }
+}
+
+/**
+ * React hook for using the ValueInterpolator with useFrame
+ *
+ * This hook creates a ValueInterpolator that uses spring physics for smooth,
+ * natural animations. Call interpolator.update(delta) in your useFrame callback.
+ *
+ * @example
+ * ```tsx
+ * function AnimatedMesh() {
+ *   const [interpolator] = useInterpolation([0, 0, 0], {
+ *     tension: 120, // Higher = faster spring
+ *     friction: 20  // Higher = more damping
+ *   })
+ *   const meshRef = useRef()
+ *
+ *   useFrame((state, delta) => {
+ *     if (interpolator.update(delta)) {
+ *       // Animation complete
+ *     }
+ *     // Apply current values directly to mesh
+ *     const [x, y, z] = interpolator.getCurrentValues()
+ *     meshRef.current.position.set(x, y, z)
+ *   })
+ *
+ *   return <mesh ref={meshRef} />
+ * }
+ * ```
+ */
+export function useInterpolation(
+  initialValues: number[] = [],
+  options: InterpolationOptions = {},
+): [ValueInterpolator] {
+  const interpolatorRef = React.useRef<ValueInterpolator | null>(null)
+
+  // Initialize interpolator
+  if (!interpolatorRef.current) {
+    interpolatorRef.current = new ValueInterpolator(initialValues, options)
+  }
+
+  // Update options when they change
+  React.useEffect(() => {
+    interpolatorRef.current?.updateOptions(options)
+  }, [options])
+
+  // Cleanup on unmount
+  React.useEffect(() => {
+    return () => {
+      interpolatorRef.current?.destroy()
+    }
+  }, [])
+
+  return [interpolatorRef.current!]
+}

package/src/externalizeComponent.tsx

@@ -7,7 +7,7 @@ import { i18n } from "./i18n/config"
  * be provided by the user application; this wrapper ensures
  * they can be used either way.
  */
-export function externalizeComponent<T extends JSX.ElementType>(
+export function externalizeComponent<T extends React.JSX.ElementType>(
   Component: T,
 ): T {
   const WrappedComponent = ((props: T) => (

package/src/index.ts

@@ -16,6 +16,7 @@ export * from "./components/robots/SupportedRobot"
 export * from "./components/safetyBar/SafetyBar"
 export * from "./components/SelectableFab"
 export * from "./components/utils/hooks"
+export * from "./components/utils/interpolation"
 export * from "./components/VelocitySlider"
 export * from "./components/wandelscript-editor/WandelscriptEditor"
 export * from "./i18n/config"

package/src/test/setup.ts

@@ -0,0 +1,111 @@
+import "@testing-library/jest-dom"
+import { beforeAll, vi } from "vitest"
+
+// Mock ResizeObserver
+global.ResizeObserver = vi.fn().mockImplementation(() => ({
+  observe: vi.fn(),
+  unobserve: vi.fn(),
+  disconnect: vi.fn(),
+}))
+
+// Mock IntersectionObserver
+global.IntersectionObserver = vi.fn().mockImplementation(() => ({
+  observe: vi.fn(),
+  unobserve: vi.fn(),
+  disconnect: vi.fn(),
+}))
+
+// Mock matchMedia
+Object.defineProperty(window, "matchMedia", {
+  writable: true,
+  value: vi.fn().mockImplementation((query) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addListener: vi.fn(),
+    removeListener: vi.fn(),
+    addEventListener: vi.fn(),
+    removeEventListener: vi.fn(),
+    dispatchEvent: vi.fn(),
+  })),
+})
+
+// Mock WebGL context for Three.js
+const mockWebGLContext = {
+  getExtension: vi.fn(),
+  getParameter: vi.fn(),
+  createShader: vi.fn(),
+  shaderSource: vi.fn(),
+  compileShader: vi.fn(),
+  createProgram: vi.fn(),
+  attachShader: vi.fn(),
+  linkProgram: vi.fn(),
+  useProgram: vi.fn(),
+  createBuffer: vi.fn(),
+  bindBuffer: vi.fn(),
+  bufferData: vi.fn(),
+  createTexture: vi.fn(),
+  bindTexture: vi.fn(),
+  texImage2D: vi.fn(),
+  texParameteri: vi.fn(),
+  generateMipmap: vi.fn(),
+  viewport: vi.fn(),
+  clearColor: vi.fn(),
+  clear: vi.fn(),
+  drawArrays: vi.fn(),
+  drawElements: vi.fn(),
+  enableVertexAttribArray: vi.fn(),
+  vertexAttribPointer: vi.fn(),
+  uniform1f: vi.fn(),
+  uniform2f: vi.fn(),
+  uniform3f: vi.fn(),
+  uniform4f: vi.fn(),
+  uniformMatrix4fv: vi.fn(),
+  getUniformLocation: vi.fn(),
+  getAttribLocation: vi.fn(),
+  enable: vi.fn(),
+  disable: vi.fn(),
+  depthFunc: vi.fn(),
+  blendFunc: vi.fn(),
+  cullFace: vi.fn(),
+  frontFace: vi.fn(),
+  VERTEX_SHADER: 35633,
+  FRAGMENT_SHADER: 35632,
+  ARRAY_BUFFER: 34962,
+  ELEMENT_ARRAY_BUFFER: 34963,
+  STATIC_DRAW: 35044,
+  DYNAMIC_DRAW: 35048,
+  TEXTURE_2D: 3553,
+  RGBA: 6408,
+  UNSIGNED_BYTE: 5121,
+  TEXTURE_MAG_FILTER: 10240,
+  TEXTURE_MIN_FILTER: 10241,
+  LINEAR: 9729,
+  COLOR_BUFFER_BIT: 16384,
+  DEPTH_BUFFER_BIT: 256,
+  DEPTH_TEST: 2929,
+  BLEND: 3042,
+  SRC_ALPHA: 770,
+  ONE_MINUS_SRC_ALPHA: 771,
+  CULL_FACE: 2884,
+  BACK: 1029,
+  CCW: 2305,
+  FLOAT: 5126,
+  FALSE: 0,
+  TRUE: 1,
+}
+
+HTMLCanvasElement.prototype.getContext = vi
+  .fn()
+  .mockImplementation((contextType) => {
+    if (contextType === "webgl" || contextType === "experimental-webgl") {
+      return mockWebGLContext
+    }
+    return null
+  })
+
+beforeAll(() => {
+  // Suppress console errors in tests
+  vi.spyOn(console, "error").mockImplementation(() => {})
+  vi.spyOn(console, "warn").mockImplementation(() => {})
+})