@khanacademy/wonder-blocks-timing 1.2.3 → 2.0.3

package/src/hooks/use-timeout.stories.mdx

@@ -0,0 +1,152 @@
+import {Meta, Story, Source, Canvas} from "@storybook/addon-docs";
+
+import {Body, HeadingSmall} from "@khanacademy/wonder-blocks-typography";
+import {View} from "@khanacademy/wonder-blocks-core";
+import Button from "@khanacademy/wonder-blocks-button";
+
+import {ClearPolicy, SchedulePolicy} from "../util/policies.js";
+import {useTimeout} from "./use-timeout.js";
+
+<Meta
+    title="Timing/useTimeout"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# `useTimeout`
+
+`useTimeout` is a hook that provides a convenient API for setting and clearing
+a timeout. It is defined as follows:
+
+```ts
+function useTimeout(
+    action: () => mixed,
+    timeoutMs: number,
+    options?: {|
+        schedulePolicy?: "schedule-immediately" | "schedule-on-demand",
+        clearPolicy?: "resolve-on-clear" | "cancel-on-clear",
+    |},
+): ITimeout;
+
+interface ITimeout {
+    get isSet(): boolean;
+    set(): void;
+    clear(policy?: ClearPolicy): void;
+}
+```
+
+By default the timeout will be set immediately up creation. The `options` parameter can
+be used to control when when the timeout is schedule and whether or not `action` should be
+called when the timeout is cleared.
+
+Notes:
+
+-   Because `clear` takes a param, it's import that you don't pass it directly to an event handler,
+    e.g. `<Button onClick={clear} />` will not work as expected.
+-   Calling `set` after the timeout has expired will restart the timeout.
+-   Updating the second paramter, `timeoutMs`, will also restart the timeout.
+-   When the component using this hooks is unmounted, the timeout will automatically be cleared.
+-   Calling `set` after the timeout is set but before it expires means that the timeout will be
+    reset and will call `action`, `timeoutMs` after the most recent call to `set` was made.
+
+export const Immediately = () => {
+    const [callCount, setCallCount] = React.useState(0);
+    const callback = React.useCallback(() => {
+        setCallCount((callCount) => callCount + 1);
+    }, []);
+    const {isSet, set, clear} = useTimeout(callback, 1000);
+    return (
+        <View>
+            <View>isSet = {isSet.toString()}</View>
+            <View>callCount = {callCount}</View>
+            <View style={{flexDirection: "row"}}>
+                <Button onClick={set}>Set timeout</Button>
+                <Button onClick={clear}>Clear timeout</Button>
+            </View>
+        </View>
+    );
+};
+
+<Canvas>
+    <Story name="Immediately">
+        <Immediately />
+    </Story>
+</Canvas>
+
+```jsx
+const Immediately = () => {
+    const [callCount, setCallCount] = React.useState(0);
+    const callback = React.useCallback(() => {
+        setCallCount((callCount) => callCount + 1);
+    }, []);
+    const {isSet, set, clear} = useTimeout(callback, 1000);
+    return (
+        <View>
+            <View>isSet = {isSet.toString()}</View>
+            <View>callCount = {callCount}</View>
+            <View style={{flexDirection: "row"}}>
+                <Button onClick={() => set()}>Set timeout</Button>
+                <Button onClick={() => clear()}>Clear timeout</Button>
+            </View>
+        </View>
+    );
+};
+```
+
+export const OnDemandAndResolveOnClear = () => {
+    const [callCount, setCallCount] = React.useState(0);
+    const callback = React.useCallback(() => {
+        console.log("action called");
+        setCallCount((callCount) => callCount + 1);
+    }, []);
+    const {isSet, set, clear} = useTimeout(callback, 1000, {
+        clearPolicy: ClearPolicy.Resolve,
+        schedulePolicy: SchedulePolicy.OnDemand,
+    });
+    return (
+        <View>
+            <View>isSet = {isSet.toString()}</View>
+            <View>callCount = {callCount}</View>
+            <View style={{flexDirection: "row"}}>
+                <Button onClick={() => set()}>Set timeout</Button>
+                <Button onClick={() => clear()}>Clear timeout</Button>
+            </View>
+        </View>
+    );
+};
+
+<Canvas>
+    <Story name="OnDemandAndResolveOnClear">
+        <OnDemandAndResolveOnClear />
+    </Story>
+</Canvas>
+
+```jsx
+const OnDemandAndResolveOnClear = () => {
+    const [callCount, setCallCount] = React.useState(0);
+    const callback = React.useCallback(() => {
+        setCallCount((callCount) => callCount + 1);
+    }, []);
+    const {isSet, set, clear} = useTimeout(
+        callback,
+        1000,
+        {
+            clearPolicy: ClearPolicy.Resolve,
+            schedulePolicy: SchedulePolicy.OnDemand,
+        },
+    );
+    return (
+        <View>
+            <View>isSet = {isSet.toString()}</View>
+            <View>callCount = {callCount}</View>
+            <View style={{flexDirection: "row"}}>
+                <Button onClick={() => set()}>Set timeout</Button>
+                <Button onClick={() => clear()}>Clear timeout</Button>
+            </View>
+        </View>
+    );
+};
+```

package/src/index.js

@@ -19,4 +19,6 @@ export type {
     WithoutActionScheduler,
 };
 
+export {SchedulePolicy, ClearPolicy} from "./util/policies.js";
 export {default as withActionScheduler} from "./components/with-action-scheduler.js";
+export {useTimeout} from "./hooks/use-timeout.js";

package/src/util/__tests__/action-scheduler.test.js

@@ -3,6 +3,7 @@ import ActionScheduler from "../action-scheduler.js";
 import Timeout from "../timeout.js";
 import Interval from "../interval.js";
 import AnimationFrame from "../animation-frame.js";
+import {SchedulePolicy, ClearPolicy} from "../policies.js";
 
 jest.mock("../timeout.js");
 jest.mock("../interval.js");
@@ -38,55 +39,54 @@ describe("ActionScheduler", () => {
             expect(result).toBeDefined();
         });
 
-        it("should pass arguments to Timeout", () => {
+        it("should pass schedule policy to Timeout", () => {
             // Arrange
             const actionScheduler = new ActionScheduler();
             const action = jest.fn();
+            const options = {
+                schedulePolicy: SchedulePolicy.Immediately,
+            };
 
             // Act
-            actionScheduler.timeout(action, 42, true);
+            actionScheduler.timeout(action, 42, options);
 
             // Assert
-            expect(Timeout).toHaveBeenCalledWith(action, 42, true);
+            expect(Timeout).toHaveBeenCalledWith(
+                action,
+                42,
+                SchedulePolicy.Immediately,
+            );
         });
 
-        describe("clearOnResolve", () => {
-            it("when true, should call timeout.clear(true) on clearAll", () => {
-                // Arrange
-                const actionScheduler = new ActionScheduler();
-                const action = jest.fn();
-                const testTimeout = actionScheduler.timeout(
-                    action,
-                    42,
-                    false,
-                    true,
-                );
+        it("should pass clear policy to timeout.clear on clearAll", () => {
+            // Arrange
+            const actionScheduler = new ActionScheduler();
+            const action = jest.fn();
+            const options = {
+                clearPolicy: ClearPolicy.Resolve,
+            };
+            const testTimeout = actionScheduler.timeout(action, 42, options);
 
-                // Act
-                actionScheduler.clearAll();
+            // Act
+            actionScheduler.clearAll();
 
-                // Assert
-                // $FlowIgnore[method-unbinding]
-                expect(testTimeout.clear).toHaveBeenCalledWith(true);
-            });
+            // Assert
+            // $FlowIgnore[method-unbinding]
+            expect(testTimeout.clear).toHaveBeenCalledWith(ClearPolicy.Resolve);
+        });
 
-            it("when falsy, should call timeout.clear() on clearAll", () => {
+        describe("when scheduler is disabled", () => {
+            it("should return a noop timeout", () => {
                 // Arrange
                 const actionScheduler = new ActionScheduler();
                 const action = jest.fn();
-                const testTimeout = actionScheduler.timeout(
-                    action,
-                    42,
-                    false,
-                    false,
-                );
 
                 // Act
-                actionScheduler.clearAll();
+                actionScheduler.disable();
+                const result = actionScheduler.timeout(action, 42);
 
                 // Assert
-                // $FlowIgnore[method-unbinding]
-                expect(testTimeout.clear).toHaveBeenCalledWith(false);
+                expect(result).toBe(ActionScheduler.NoopAction);
             });
         });
     });
@@ -104,55 +104,56 @@ describe("ActionScheduler", () => {
             expect(result).toBeDefined();
         });
 
-        it("should pass arguments to Interval", () => {
+        it("should pass schedule policy to Interval", () => {
             // Arrange
             const actionScheduler = new ActionScheduler();
             const action = jest.fn();
+            const options = {
+                schedulePolicy: SchedulePolicy.Immediately,
+            };
 
             // Act
-            actionScheduler.interval(action, 42, true);
+            actionScheduler.interval(action, 42, options);
 
             // Assert
-            expect(Interval).toHaveBeenCalledWith(action, 42, true);
+            expect(Interval).toHaveBeenCalledWith(
+                action,
+                42,
+                SchedulePolicy.Immediately,
+            );
         });
 
-        describe("clearOnResolve", () => {
-            it("when true, should call interval.clear(true) on clearAll", () => {
-                // Arrange
-                const actionScheduler = new ActionScheduler();
-                const action = jest.fn();
-                const testInterval = actionScheduler.interval(
-                    action,
-                    42,
-                    false,
-                    true,
-                );
+        it("should pass clear policy to interval.clear on clearAll", () => {
+            // Arrange
+            const actionScheduler = new ActionScheduler();
+            const action = jest.fn();
+            const options = {
+                clearPolicy: ClearPolicy.Resolve,
+            };
+            const testInterval = actionScheduler.interval(action, 42, options);
 
-                // Act
-                actionScheduler.clearAll();
+            // Act
+            actionScheduler.clearAll();
 
-                // Assert
-                // $FlowIgnore[method-unbinding]
-                expect(testInterval.clear).toHaveBeenCalledWith(true);
-            });
+            // Assert
+            // $FlowIgnore[method-unbinding]
+            expect(testInterval.clear).toHaveBeenCalledWith(
+                ClearPolicy.Resolve,
+            );
+        });
 
-            it("when falsy, should call interval.clear() on clearAll", () => {
+        describe("when scheduler is disabled", () => {
+            it("should return a noop interval", () => {
                 // Arrange
                 const actionScheduler = new ActionScheduler();
                 const action = jest.fn();
-                const testInterval = actionScheduler.interval(
-                    action,
-                    42,
-                    false,
-                    false,
-                );
 
                 // Act
-                actionScheduler.clearAll();
+                actionScheduler.disable();
+                const result = actionScheduler.interval(action, 42);
 
                 // Assert
-                // $FlowIgnore[method-unbinding]
-                expect(testInterval.clear).toHaveBeenCalledWith(false);
+                expect(result).toBe(ActionScheduler.NoopAction);
             });
         });
     });
@@ -170,53 +171,53 @@ describe("ActionScheduler", () => {
             expect(result).toBeDefined();
         });
 
-        it("should pass arguments to AnimationFrame", () => {
+        it("should pass schedule policy to AnimationFrame", () => {
             // Arrange
             const actionScheduler = new ActionScheduler();
             const action = jest.fn();
+            const options = {
+                schedulePolicy: SchedulePolicy.Immediately,
+            };
 
             // Act
-            actionScheduler.animationFrame(action, true);
+            actionScheduler.animationFrame(action, options);
 
             // Assert
-            expect(AnimationFrame).toHaveBeenCalledWith(action, true);
+            expect(AnimationFrame).toHaveBeenCalledWith(
+                action,
+                SchedulePolicy.Immediately,
+            );
         });
 
-        describe("clearOnResolve", () => {
-            it("when true, should call animationFrame.clear(true) on clearAll", () => {
-                // Arrange
-                const actionScheduler = new ActionScheduler();
-                const action = jest.fn();
-                const testFrame = actionScheduler.animationFrame(
-                    action,
-                    false,
-                    true,
-                );
+        it("should pass clear policy to animationFrame.clear on clearAll", () => {
+            // Arrange
+            const actionScheduler = new ActionScheduler();
+            const action = jest.fn();
+            const options = {
+                clearPolicy: ClearPolicy.Resolve,
+            };
+            const testFrame = actionScheduler.animationFrame(action, options);
 
-                // Act
-                actionScheduler.clearAll();
+            // Act
+            actionScheduler.clearAll();
 
-                // Assert
-                // $FlowIgnore[method-unbinding]
-                expect(testFrame.clear).toHaveBeenCalledWith(true);
-            });
+            // Assert
+            // $FlowIgnore[method-unbinding]
+            expect(testFrame.clear).toHaveBeenCalledWith(ClearPolicy.Resolve);
+        });
 
-            it("when falsy, should call animationFrame.clear() on clearAll", () => {
+        describe("when scheduler is disabled", () => {
+            it("should return a noop interval", () => {
                 // Arrange
                 const actionScheduler = new ActionScheduler();
                 const action = jest.fn();
-                const testFrame = actionScheduler.animationFrame(
-                    action,
-                    false,
-                    false,
-                );
 
                 // Act
-                actionScheduler.clearAll();
+                actionScheduler.disable();
+                const result = actionScheduler.animationFrame(action);
 
                 // Assert
-                // $FlowIgnore[method-unbinding]
-                expect(testFrame.clear).toHaveBeenCalledWith(false);
+                expect(result).toBe(ActionScheduler.NoopAction);
             });
         });
     });
@@ -263,4 +264,18 @@ describe("ActionScheduler", () => {
             expect(animationFrame.clear).toHaveBeenCalledTimes(1);
         });
     });
+
+    describe("#disable", () => {
+        it("should clear all scheduled actions", () => {
+            // Arrange
+            const actionScheduler = new ActionScheduler();
+            const clearAllSpy = jest.spyOn(actionScheduler, "clearAll");
+
+            // Act
+            actionScheduler.disable();
+
+            // Assert
+            expect(clearAllSpy).toHaveBeenCalledTimes(1);
+        });
+    });
 });

package/src/util/__tests__/animation-frame.test.js

@@ -1,5 +1,6 @@
 // @flow
 import AnimationFrame from "../animation-frame.js";
+import {SchedulePolicy, ClearPolicy} from "../policies.js";
 
 describe("AnimationFrame", () => {
     beforeEach(() => {
@@ -8,14 +9,12 @@ describe("AnimationFrame", () => {
         // Jest doesn't fake out the animation frame API, so we're going to do
         // it here and map it to timeouts, that way we can use the fake timer
         // API to test our animation frame things.
-        jest.spyOn(
-            global,
-            "requestAnimationFrame",
-        ).mockImplementation((fn, ...args) => setTimeout(fn, 0));
-        jest.spyOn(
-            global,
-            "cancelAnimationFrame",
-        ).mockImplementation((id, ...args) => clearTimeout(id));
+        jest.spyOn(global, "requestAnimationFrame").mockImplementation(
+            (fn, ...args) => setTimeout(fn, 0),
+        );
+        jest.spyOn(global, "cancelAnimationFrame").mockImplementation(
+            (id, ...args) => clearTimeout(id),
+        );
     });
 
     afterEach(() => {
@@ -45,12 +44,12 @@ describe("AnimationFrame", () => {
             );
         });
 
-        it("requests an animation frame when autoSchedule is true", () => {
+        it("requests an animation frame when schedule policy is SchedulePolicy.Immediately", () => {
             // Arrange
 
             // Act
             // eslint-disable-next-line no-new
-            new AnimationFrame(() => {}, true);
+            new AnimationFrame(() => {}, SchedulePolicy.Immediately);
 
             // Assert
             expect(requestAnimationFrame).toHaveBeenCalledTimes(1);
@@ -60,7 +59,8 @@ describe("AnimationFrame", () => {
     describe("isSet", () => {
         it("is false when the request has not been set", () => {
             // Arrange
-            const animationFrame = new AnimationFrame(() => {}, false);
+            const animationFrame = new AnimationFrame(() => {},
+            SchedulePolicy.OnDemand);
 
             // Act
             const result = animationFrame.isSet;
@@ -144,7 +144,10 @@ describe("AnimationFrame", () => {
         it("should set the timeout again if it has already executed", () => {
             // Arrange
             const action = jest.fn();
-            const animationFrame = new AnimationFrame(action, false);
+            const animationFrame = new AnimationFrame(
+                action,
+                SchedulePolicy.OnDemand,
+            );
             animationFrame.set();
             jest.runOnlyPendingTimers();
 
@@ -171,7 +174,7 @@ describe("AnimationFrame", () => {
             expect(action).not.toHaveBeenCalled();
         });
 
-        it("should invoke the action if resolve is true", () => {
+        it("should invoke the action if clear policy is ClearPolicy.Resolve", () => {
             // Arrange
             jest.spyOn(performance, "now").mockReturnValue(42);
             const action = jest.fn();
@@ -179,7 +182,7 @@ describe("AnimationFrame", () => {
             animationFrame.set();
 
             // Act
-            animationFrame.clear(true);
+            animationFrame.clear(ClearPolicy.Resolve);
             jest.runOnlyPendingTimers();
 
             // Assert
@@ -187,26 +190,32 @@ describe("AnimationFrame", () => {
             expect(action).toHaveBeenCalledWith(42);
         });
 
-        it("should not invoke the action if resolve is false", () => {
+        it("should not invoke the action if clear policy is ClearPolicy.Cancel", () => {
             // Arrange
             const action = jest.fn();
-            const animationFrame = new AnimationFrame(action, true);
+            const animationFrame = new AnimationFrame(
+                action,
+                SchedulePolicy.Immediately,
+            );
 
             // Act
-            animationFrame.clear(false);
+            animationFrame.clear(ClearPolicy.Cancel);
             jest.runOnlyPendingTimers();
 
             // Assert
             expect(action).not.toHaveBeenCalled();
         });
 
-        it("should not invoke the action if timeout is not pending", () => {
+        it("should not invoke the action if timeout is not pending and clear policy is ClearPolicy.Resolve", () => {
             // Arrange
             const action = jest.fn();
-            const animationFrame = new AnimationFrame(action, false);
+            const animationFrame = new AnimationFrame(
+                action,
+                SchedulePolicy.OnDemand,
+            );
 
             // Act
-            animationFrame.clear(true);
+            animationFrame.clear(ClearPolicy.Resolve);
             jest.runOnlyPendingTimers();
 
             // Assert