@khanacademy/wonder-blocks-timing 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -0,0 +1,11 @@
+# @khanacademy/wonder-blocks-timing
+
+## 2.1.0
+### Minor Changes
+
+- 029b4810: Adds `useInterval()` hook that mimics the behavior of `ActionScheduler`'s
+  `interval()` method.
+- c57cd770: Rename `useInterval` and `useTimeout` to `useScheduledInterval`
+  and `useScheduledTimeout` respectively.
+- 29766c8e: Add `useInterval` and `useTimeout` hooks to provide a simple API for
+  using intervals and timeouts.

package/dist/es/index.js

@@ -1,5 +1,6 @@
 import _extends from '@babel/runtime/helpers/extends';
-import { Component, forwardRef, createElement } from 'react';
+import * as React from 'react';
+import { useRef, useEffect, useState, useCallback } from 'react';
 
 const SchedulePolicy = {
   Immediately: "schedule-immediately",
@@ -395,7 +396,7 @@ ActionScheduler.NoopAction = {
  * </ActionSchedulerProvider>
  * ```
  */
-class ActionSchedulerProvider extends Component {
+class ActionSchedulerProvider extends React.Component {
   constructor(...args) {
     super(...args);
     this._actionScheduler = new ActionScheduler();
@@ -424,10 +425,193 @@ class ActionSchedulerProvider extends Component {
  * these props use the `WithActionScheduler` type.
  */
 function withActionScheduler(WrappedComponent) {
-  return /*#__PURE__*/forwardRef((props, ref) => /*#__PURE__*/createElement(ActionSchedulerProvider, null, schedule => /*#__PURE__*/createElement(WrappedComponent, _extends({}, props, {
+  return /*#__PURE__*/React.forwardRef((props, ref) => /*#__PURE__*/React.createElement(ActionSchedulerProvider, null, schedule => /*#__PURE__*/React.createElement(WrappedComponent, _extends({}, props, {
     ref: ref,
     schedule: schedule
   }))));
 }
 
-export { ClearPolicy, SchedulePolicy, withActionScheduler };
+/**
+ * Returns a ref whose .current value is updated whenever
+ * the `value` passed to this hook changes.
+ *
+ * this is great for values that you want to reference from
+ * within a useCallback or useEffect event listener, without
+ * re-triggering the effect when the value changes
+ *
+ * @returns {{current: T}}
+ */
+
+const useUpdatingRef = value => {
+  const ref = useRef(value);
+  useEffect(() => {
+    ref.current = value;
+  }, [value]);
+  return ref;
+};
+
+/**
+ * A simple hook for using `setInterval`.
+ *
+ * @param action called every `intervalMs` when `active` is true
+ * @param intervalMs the duration between calls to `action`
+ * @param active whether or not the interval is active
+ */
+
+function useInterval(action, intervalMs, active) {
+  // We using a ref instead of a callback for `action` to avoid resetting
+  // the interval whenever the `action` changes.
+  const actionRef = useUpdatingRef(action);
+  useEffect(() => {
+    if (active) {
+      const intervalId = setInterval(() => {
+        actionRef.current();
+      }, intervalMs);
+      return () => {
+        clearInterval(intervalId);
+      };
+    } // actionRef isn't actually required, but react-hooks/exhaustive-deps
+    // doesn't recognize it as a ref and thus complains if it isn't in the
+    // deps list.  It isn't a big deal though since the value ofactionRef
+    // never changes (only its contents do).
+
+  }, [intervalMs, active, actionRef]);
+}
+
+/**
+ * A simple hook for using `setTimeout`.
+ *
+ * @param action called after `timeoutMs` when `active` is true
+ * @param timeoutMs the duration after which `action` is called
+ * @param active whether or not the interval is active
+ */
+
+function useTimeout(action, timeoutMs, active) {
+  // We using a ref instead of a callback for `action` to avoid resetting
+  // the interval whenever the `action` changes.
+  const actionRef = useUpdatingRef(action);
+  useEffect(() => {
+    if (active) {
+      const timeoutId = setTimeout(() => {
+        actionRef.current();
+      }, timeoutMs);
+      return () => {
+        clearTimeout(timeoutId);
+      };
+    } // actionRef isn't actually required, but react-hooks/exhaustive-deps
+    // doesn't recognize it as a ref and thus complains if it isn't in the
+    // deps list.  It isn't a big deal though since the value ofactionRef
+    // never changes (only its contents do).
+
+  }, [timeoutMs, active, actionRef]);
+}
+
+function useScheduledInterval(action, intervalMs, options) {
+  var _options$schedulePoli;
+
+  if (typeof action !== "function") {
+    throw new Error("Action must be a function");
+  }
+
+  if (intervalMs < 1) {
+    throw new Error("Interval period must be >= 1");
+  }
+
+  const schedulePolicy = (_options$schedulePoli = options == null ? void 0 : options.schedulePolicy) != null ? _options$schedulePoli : SchedulePolicy.Immediately;
+  const [isSet, setIsSet] = useState(schedulePolicy === SchedulePolicy.Immediately);
+  const set = useCallback(() => setIsSet(true), []);
+  const actionRef = useUpdatingRef(action);
+  const clear = useCallback(policy => {
+    var _policy;
+
+    policy = (_policy = policy) != null ? _policy : options == null ? void 0 : options.clearPolicy;
+
+    if (isSet && policy === ClearPolicy.Resolve) {
+      actionRef.current();
+    }
+
+    setIsSet(false);
+  }, // react-hooks/exhaustive-deps doesn't require refs to be
+  // listed in the deps array.  Unfortunately, in this situation
+  // it doesn't recognized actionRef as a ref.
+  [actionRef, isSet, options == null ? void 0 : options.clearPolicy]);
+  const runOnUnmountRef = useUpdatingRef(isSet && (options == null ? void 0 : options.clearPolicy) === ClearPolicy.Resolve);
+  useEffect(() => {
+    return () => {
+      // This code will only run with the component using this
+      // hook is unmounted.
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      if (runOnUnmountRef.current) {
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        actionRef.current();
+      }
+    }; // This eslint rule doesn't realize actionRef and runOnUnmountRef
+    // a both refs and thus do not have to be listed as deps.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  useInterval(action, intervalMs, isSet);
+  return {
+    isSet,
+    set,
+    clear
+  };
+}
+
+function useScheduledTimeout(action, timeoutMs, options) {
+  var _options$schedulePoli;
+
+  if (typeof action !== "function") {
+    throw new Error("Action must be a function");
+  }
+
+  if (timeoutMs < 0) {
+    throw new Error("Timeout period must be >= 0");
+  }
+
+  const schedulePolicy = (_options$schedulePoli = options == null ? void 0 : options.schedulePolicy) != null ? _options$schedulePoli : SchedulePolicy.Immediately;
+  const [isSet, setIsSet] = useState(schedulePolicy === SchedulePolicy.Immediately);
+  const set = useCallback(() => setIsSet(true), []); // This wrapper isn't present in useScheduledInterval because we
+  // don't need to update `isSet` in that situations.
+
+  const wrappedAction = useCallback(() => {
+    setIsSet(false);
+    action();
+  }, [action]);
+  const actionRef = useUpdatingRef(wrappedAction);
+  const clear = useCallback(policy => {
+    var _policy;
+
+    policy = (_policy = policy) != null ? _policy : options == null ? void 0 : options.clearPolicy;
+
+    if (isSet && policy === ClearPolicy.Resolve) {
+      actionRef.current();
+    }
+
+    setIsSet(false);
+  }, // react-hooks/exhaustive-deps doesn't require refs to be
+  // listed in the deps array.  Unfortunately, in this situation
+  // it doesn't recognized actionRef as a ref.
+  [actionRef, isSet, options == null ? void 0 : options.clearPolicy]);
+  const runOnUnmountRef = useUpdatingRef(isSet && (options == null ? void 0 : options.clearPolicy) === ClearPolicy.Resolve);
+  useEffect(() => {
+    return () => {
+      // This code will only run with the component using this
+      // hook is unmounted.
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      if (runOnUnmountRef.current) {
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+        actionRef.current();
+      }
+    }; // This eslint rule doesn't realize actionRef and runOnUnmountRef
+    // a both refs and thus do not have to be listed as deps.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+  useTimeout(wrappedAction, timeoutMs, isSet);
+  return {
+    isSet,
+    set,
+    clear
+  };
+}
+
+export { ClearPolicy, SchedulePolicy, useInterval, useScheduledInterval, useScheduledTimeout, useTimeout, withActionScheduler };