@khanacademy/wonder-blocks-timing 1.2.3 → 2.0.3

package/dist/es/index.js

@@ -1,5 +1,14 @@
 import _extends from '@babel/runtime/helpers/extends';
-import { Component, forwardRef, createElement } from 'react';
+import { Component, forwardRef, createElement, useState, useRef, useEffect, useCallback } from 'react';
+
+const SchedulePolicy = {
+  Immediately: "schedule-immediately",
+  OnDemand: "schedule-on-demand"
+};
+const ClearPolicy = {
+  Resolve: "resolve-on-clear",
+  Cancel: "cancel-on-clear"
+};
 
 /**
  * Encapsulates everything associated with calling setTimeout/clearTimeout, and
@@ -18,12 +27,13 @@ class Timeout {
    * @param {() => mixed} action The action to be invoked when the timeout
    * period has passed.
    * @param {number} timeoutMs The timeout period.
-   * @param {boolean} [autoSchedule] When true, the timer is set immediately on
-   * instanstiation; otherwise, `set` must be called to set the timeout.
-   * Defaults to `true`.
+   * @param {SchedulePolicy} [schedulePolicy] When SchedulePolicy.Immediately,
+   * the timer is set immediately on instantiation; otherwise, `set` must be
+   * called to set the timeout.
+   * Defaults to `SchedulePolicy.Immediately`.
    * @memberof Timeout
    */
-  constructor(action, timeoutMs, autoSchedule) {
+  constructor(action, timeoutMs, schedulePolicy = SchedulePolicy.Immediately) {
     if (typeof action !== "function") {
       throw new Error("Action must be a function");
     }
@@ -35,7 +45,7 @@ class Timeout {
     this._action = action;
     this._timeoutMs = timeoutMs;
 
-    if (autoSchedule || autoSchedule == null) {
+    if (schedulePolicy === SchedulePolicy.Immediately) {
       this.set();
     }
   }
@@ -64,10 +74,10 @@ class Timeout {
 
   set() {
     if (this.isSet) {
-      this.clear(false);
+      this.clear(ClearPolicy.Cancel);
     }
 
-    this._timeoutId = setTimeout(() => this.clear(true), this._timeoutMs);
+    this._timeoutId = setTimeout(() => this.clear(ClearPolicy.Resolve), this._timeoutMs);
   }
   /**
    * Clear the set timeout.
@@ -75,16 +85,17 @@ class Timeout {
    * If the timeout is pending, this cancels that pending timeout without
    * invoking the action. If no timeout is pending, this does nothing.
    *
-   * @param {boolean} [resolve] When true, if the timeout was set when called,
-   * the timeout action is invoked after cancelling the timeout. Defaults to
-   * false.
+   * @param {ClearPolicy} [policy] When ClearPolicy.Resolve, if the request
+   * was set when called, the request action is invoked after cancelling
+   * the request; otherwise, the pending action is cancelled.
+   * Defaults to `ClearPolicy.Cancel`.
    *
    * @returns {void}
    * @memberof Timeout
    */
 
 
-  clear(resolve) {
+  clear(policy = ClearPolicy.Cancel) {
     const timeoutId = this._timeoutId;
     this._timeoutId = null;
 
@@ -94,7 +105,7 @@ class Timeout {
 
     clearTimeout(timeoutId);
 
-    if (resolve) {
+    if (policy === ClearPolicy.Resolve) {
       this._action();
     }
   }
@@ -118,13 +129,13 @@ class Interval {
    * @param {() => mixed} action The action to be invoked each time the
    * interval period has passed.
    * @param {number} intervalMs The interval period.
-   * @param {boolean} [autoSchedule] When true, the interval is activated
-   * immediately on instanstiation; otherwise, `set` must be called to
-   * activate the interval.
-   * Defaults to `true`.
+   * @param {SchedulePolicy} [schedulePolicy] When SchedulePolicy.Immediately,
+   * the interval is set immediately on instantiation; otherwise, `set` must be
+   * called to set the interval.
+   * Defaults to `SchedulePolicy.Immediately`.
    * @memberof Interval
    */
-  constructor(action, intervalMs, autoSchedule) {
+  constructor(action, intervalMs, schedulePolicy = SchedulePolicy.Immediately) {
     if (typeof action !== "function") {
       throw new Error("Action must be a function");
     }
@@ -136,7 +147,7 @@ class Interval {
     this._action = action;
     this._intervalMs = intervalMs;
 
-    if (autoSchedule || autoSchedule == null) {
+    if (schedulePolicy === SchedulePolicy.Immediately) {
       this.set();
     }
   }
@@ -163,7 +174,7 @@ class Interval {
 
   set() {
     if (this.isSet) {
-      this.clear(false);
+      this.clear(ClearPolicy.Cancel);
     }
 
     this._intervalId = setInterval(() => this._action(), this._intervalMs);
@@ -174,16 +185,17 @@ class Interval {
    * If the interval is active, this cancels that interval. If no interval is
    * pending, this does nothing.
    *
-   * @param {boolean} [resolve] When true, if the interval was active when
-   * called, the interval action is invoked after cancellation. Defaults to
-   * false.
+   * @param {ClearPolicy} [policy] When ClearPolicy.Resolve, if the request
+   * was set when called, the request action is invoked after cancelling
+   * the request; otherwise, the pending action is cancelled.
+   * Defaults to `ClearPolicy.Cancel`.
    *
    * @returns {void}
    * @memberof Interval
    */
 
 
-  clear(resolve) {
+  clear(policy = ClearPolicy.Cancel) {
     const intervalId = this._intervalId;
     this._intervalId = null;
 
@@ -193,7 +205,7 @@ class Interval {
 
     clearInterval(intervalId);
 
-    if (resolve) {
+    if (policy === ClearPolicy.Resolve) {
       this._action();
     }
   }
@@ -215,19 +227,20 @@ class AnimationFrame {
    * The request is not made until set is called.
    *
    * @param {DOMHighResTimeStamp => mixed} action The action to be invoked.
-   * @param {boolean} [autoSchedule] When true, the request is made immediately on
-   * instanstiation; otherwise, `set` must be called to make the request.
-   * Defaults to `true`.
+   * @param {SchedulePolicy} [schedulePolicy] When SchedulePolicy.Immediately,
+   * the interval is set immediately on instantiation; otherwise, `set` must be
+   * called to set the interval.
+   * Defaults to `SchedulePolicy.Immediately`.
    * @memberof AnimationFrame
    */
-  constructor(action, autoSchedule) {
+  constructor(action, schedulePolicy = SchedulePolicy.Immediately) {
     if (typeof action !== "function") {
       throw new Error("Action must be a function");
     }
 
     this._action = action;
 
-    if (autoSchedule || autoSchedule == null) {
+    if (schedulePolicy === SchedulePolicy.Immediately) {
       this.set();
     }
   }
@@ -256,10 +269,10 @@ class AnimationFrame {
 
   set() {
     if (this.isSet) {
-      this.clear(false);
+      this.clear(ClearPolicy.Cancel);
     }
 
-    this._animationFrameId = requestAnimationFrame(time => this.clear(true, time));
+    this._animationFrameId = requestAnimationFrame(time => this.clear(ClearPolicy.Resolve, time));
   }
   /**
    * Clear the pending request.
@@ -267,16 +280,20 @@ class AnimationFrame {
    * If the request is pending, this cancels that pending request without
    * invoking the action. If no request is pending, this does nothing.
    *
-   * @param {boolean} [resolve] When true, if the request was pending when
-   * called, the request action is invoked after cancelling the timeout.
-   * Defaults to false.
+   * @param {ClearPolicy} [policy] When ClearPolicy.Resolve, if the request
+   * was set when called, the request action is invoked after cancelling
+   * the request; otherwise, the pending action is cancelled.
+   * Defaults to `ClearPolicy.Cancel`.
+   * @param {DOMHighResTimeStamp} [time] Timestamp to pass to the action when
+   * ClearPolicy.Resolve is specified. Ignored when ClearPolicy.Cancel is
+   * specified.
    *
    * @returns {void}
    * @memberof AnimationFrame
    */
 
 
-  clear(resolve, time) {
+  clear(policy = ClearPolicy.Cancel, time) {
     const animationFrameId = this._animationFrameId;
     this._animationFrameId = null;
 
@@ -286,7 +303,7 @@ class AnimationFrame {
 
     cancelAnimationFrame(animationFrameId);
 
-    if (resolve) {
+    if (policy === ClearPolicy.Resolve) {
       this._action(time || performance.now());
     }
   }
@@ -301,29 +318,42 @@ class AnimationFrame {
  */
 class ActionScheduler {
   constructor() {
+    this._disabled = false;
     this._registeredActions = [];
   }
 
-  timeout(action, period, autoSchedule, resolveOnClear) {
-    const timeout = new Timeout(action, period, autoSchedule);
+  timeout(action, period, options) {
+    if (this._disabled) {
+      return ActionScheduler.NoopAction;
+    }
+
+    const timeout = new Timeout(action, period, options == null ? void 0 : options.schedulePolicy);
 
-    this._registeredActions.push(() => timeout.clear(resolveOnClear));
+    this._registeredActions.push(() => timeout.clear(options == null ? void 0 : options.clearPolicy));
 
     return timeout;
   }
 
-  interval(action, period, autoSchedule, resolveOnClear) {
-    const interval = new Interval(action, period, autoSchedule);
+  interval(action, period, options) {
+    if (this._disabled) {
+      return ActionScheduler.NoopAction;
+    }
+
+    const interval = new Interval(action, period, options == null ? void 0 : options.schedulePolicy);
 
-    this._registeredActions.push(() => interval.clear(resolveOnClear));
+    this._registeredActions.push(() => interval.clear(options == null ? void 0 : options.clearPolicy));
 
     return interval;
   }
 
-  animationFrame(action, autoSchedule, resolveOnClear) {
-    const animationFrame = new AnimationFrame(action, autoSchedule);
+  animationFrame(action, options) {
+    if (this._disabled) {
+      return ActionScheduler.NoopAction;
+    }
 
-    this._registeredActions.push(() => animationFrame.clear(resolveOnClear));
+    const animationFrame = new AnimationFrame(action, options == null ? void 0 : options.schedulePolicy);
+
+    this._registeredActions.push(() => animationFrame.clear(options == null ? void 0 : options.clearPolicy));
 
     return animationFrame;
   }
@@ -333,8 +363,27 @@ class ActionScheduler {
     this._registeredActions = [];
     registered.forEach(clearFn => clearFn());
   }
+  /**
+   * Prevents this scheduler from creating any additional actions.
+   * This also clears any pending actions.
+   */
+
+
+  disable() {
+    this._disabled = true;
+    this.clearAll();
+  }
 
 }
+ActionScheduler.NoopAction = {
+  set: () => {},
+
+  get isSet() {
+    return false;
+  },
+
+  clear: () => {}
+};
 
 /**
  * A provider component that passes our action scheduling API to its children
@@ -353,7 +402,7 @@ class ActionSchedulerProvider extends Component {
   }
 
   componentWillUnmount() {
-    this._actionScheduler.clearAll();
+    this._actionScheduler.disable();
   }
 
   render() {
@@ -381,4 +430,58 @@ function withActionScheduler(WrappedComponent) {
   }))));
 }
 
-export { withActionScheduler };
+function useTimeout(action, timeoutMs, options) {
+  var _options$schedulePoli;
+
+  const schedulePolicy = (_options$schedulePoli = options == null ? void 0 : options.schedulePolicy) != null ? _options$schedulePoli : SchedulePolicy.Immediately;
+  const [isSet, setIsSet] = useState(schedulePolicy === SchedulePolicy.Immediately);
+  const actionRef = useRef(action);
+  const mountedRef = useRef(false);
+  useEffect(() => {
+    mountedRef.current = true;
+    return () => {
+      mountedRef.current = false;
+    };
+  }, []);
+  useEffect(() => {
+    actionRef.current = action;
+  }, [action]);
+  const clear = useCallback(policy => {
+    if ((policy != null ? policy : options == null ? void 0 : options.clearPolicy) === ClearPolicy.Resolve) {
+      actionRef.current();
+    } // This will cause the useEffect below to re-run
+
+
+    setIsSet(false);
+  }, [options == null ? void 0 : options.clearPolicy]);
+  const set = useCallback(() => {
+    if (isSet) {
+      clear();
+    } // This will cause the useEffect below to re-run
+
+
+    setIsSet(true);
+  }, [clear, isSet]);
+  useEffect(() => {
+    if (isSet && mountedRef.current) {
+      const timeout = window.setTimeout(() => {
+        actionRef.current();
+        setIsSet(false);
+      }, timeoutMs);
+      return () => {
+        window.clearTimeout(timeout);
+
+        if (!mountedRef.current) {
+          clear();
+        }
+      };
+    }
+  }, [clear, isSet, timeoutMs]);
+  return {
+    isSet,
+    set,
+    clear
+  };
+}
+
+export { ClearPolicy, SchedulePolicy, useTimeout, withActionScheduler };