AnimatedNumber component with hook wrapping animateValue

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## Not released
 
-
+- AnimatedNumber component with hook wrapping `animateValue` [#509](https://github.com/CartoDB/carto-react/pull/509)
 
 ## 1.5
 

packages/react-ui/src/custom-components/AnimatedNumber.js

@@ -0,0 +1,43 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import useAnimatedNumber from '../hooks/useAnimatedNumber';
+
+/**
+ * Renders a <AnimatedNumber /> widget
+ * @param {Object} props
+ * @param {boolean} props.enabled
+ * @param {number} props.value
+ * @param {{ duration?: number; animateOnMount?: boolean; initialValue?: number }} [props.options]
+ * @param {(n: number) => React.ReactNode} [props.formatter]
+ */
+function AnimatedNumber({ enabled, value, options, formatter }) {
+  const defaultOptions = {
+    animateOnMount: true,
+    disabled: enabled === false || value === null || value === undefined
+  };
+  const animated = useAnimatedNumber(value, { ...defaultOptions, ...options });
+  return <span>{formatter ? formatter(animated) : animated}</span>;
+}
+
+AnimatedNumber.displayName = 'AnimatedNumber';
+AnimatedNumber.defaultProps = {
+  enabled: true,
+  value: 0,
+  options: {},
+  formatter: null
+};
+
+export const animationOptionsPropTypes = PropTypes.shape({
+  duration: PropTypes.number,
+  animateOnMount: PropTypes.bool,
+  initialValue: PropTypes.number
+});
+
+AnimatedNumber.propTypes = {
+  enabled: PropTypes.bool,
+  value: PropTypes.number.isRequired,
+  options: animationOptionsPropTypes,
+  formatter: PropTypes.func
+};
+
+export default AnimatedNumber;

packages/react-ui/src/hooks/useAnimatedNumber.js

@@ -0,0 +1,39 @@
+import { useEffect, useRef, useState } from "react";
+import { animateValue } from '../widgets/utils/animations';
+
+/**
+ * React hook to handle animating value changes over time, abstracting the necesary state, refs and effects
+ * @param {number} value 
+ * @param {{ disabled?: boolean; duration?: number; animateOnMount?: boolean; initialValue?: number; }} [options] 
+ */
+export default function useAnimatedNumber(value, options = {}) {
+  const { disabled, duration, animateOnMount, initialValue = 0 } = options;
+
+  /** @type {any} */
+  const requestAnimationFrameRef = useRef(); 
+
+  // if we want to run the animation on mount, we set the starting value of the animated number as 0 (or the number in `initialValue`) and animate to the target value from there
+  const [animatedValue, setAnimatedValue] = useState(() => animateOnMount ? initialValue : value);
+
+  useEffect(() => {
+    if (!disabled) {
+      animateValue({
+        start: animatedValue,
+        end: value,
+        duration: duration || 500, // 500ms
+        drawFrame: (val) => setAnimatedValue(val),
+        requestRef: requestAnimationFrameRef
+      });
+    } else {
+      setAnimatedValue(value)
+    }
+
+    return () => {
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      cancelAnimationFrame(requestAnimationFrameRef.current);
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [value, disabled, duration]);
+
+  return animatedValue;
+};

packages/react-ui/src/types.d.ts

@@ -188,3 +188,16 @@ export type LegendRamp = {
     colors?: string | string[] | number[][];
   };
 };
+
+export type AnimationOptions = {
+  duration?: number;
+  animateOnMount?: boolean;
+  initialValue?: number
+};
+
+export type AnimatedNumber = {
+  enabled: boolean;
+  value: number;
+  options?: AnimationOptions;
+  formatter: (n: number) => React.ReactNode;
+};