@khanacademy/wonder-blocks-timing 2.0.3 → 2.1.0

package/src/hooks/__tests__/use-timeout.test.js

@@ -1,6 +1,5 @@
 // @flow
-import {renderHook, act} from "@testing-library/react-hooks";
-import {SchedulePolicy, ClearPolicy} from "../../util/policies.js";
+import {renderHook} from "@testing-library/react-hooks";
 
 import {useTimeout} from "../use-timeout.js";
 
@@ -9,328 +8,129 @@ describe("useTimeout", () => {
         jest.useFakeTimers();
     });
 
-    it("should return an ITimeout", () => {
+    it("should not fire if 'active' is false", () => {
         // Arrange
-        const {result} = renderHook(() => useTimeout(() => {}, 1000));
+        const action = jest.fn();
 
         // Act
+        renderHook(() => useTimeout(action, 500, false));
+        jest.advanceTimersByTime(501);
 
         // Assert
-        expect(result.current).toEqual(
-            expect.objectContaining({
-                clear: expect.any(Function),
-                set: expect.any(Function),
-                isSet: expect.any(Boolean),
-            }),
-        );
+        expect(action).not.toHaveBeenCalled();
     });
 
-    it("should default to being immediately set", () => {
+    it("should not fire before the timeout", () => {
         // Arrange
-        const {result} = renderHook(() => useTimeout(() => {}, 1000));
+        const action = jest.fn();
 
         // Act
+        renderHook(() => useTimeout(action, 500, true));
+        jest.advanceTimersByTime(499);
 
         // Assert
-        expect(result.current.isSet).toBe(true);
+        expect(action).not.toHaveBeenCalled();
     });
 
-    describe("SchedulePolicies.Immediately", () => {
-        it("should call the action after the timeout expires", () => {
-            // Arrange
-            const action = jest.fn();
-            renderHook(() => useTimeout(action, 1000));
-
-            // Act
-            act(() => {
-                jest.advanceTimersByTime(1000);
-            });
-
-            // Assert
-            expect(action).toHaveBeenCalled();
-        });
-
-        it("should update isSet to false after the timeout expires", () => {
-            // Arrange
-            const action = jest.fn();
-            const {result} = renderHook(() => useTimeout(action, 1000));
-
-            // Act
-            act(() => {
-                jest.advanceTimersByTime(1000);
-            });
-
-            // Assert
-            expect(result.current.isSet).toBe(false);
-        });
-
-        it("should call the action again if 'set' is called after the action was called", () => {
-            // Arrange
-            const action = jest.fn();
-            const {result} = renderHook(() => useTimeout(action, 1000));
-
-            // Act
-            act(() => {
-                jest.advanceTimersByTime(1001);
-                result.current.set();
-                jest.advanceTimersByTime(1001);
-            });
-
-            // Assert
-            expect(action).toHaveBeenCalledTimes(2);
-        });
-
-        it("should restart the timeout if timeoutMs gets updated", () => {
-            // Arrange
-            const action = jest.fn();
-            const {rerender} = renderHook(
-                ({timeoutMs}) => useTimeout(action, timeoutMs),
-                {
-                    initialProps: {timeoutMs: 1000},
-                },
-            );
-
-            // Act
-            act(() => {
-                jest.advanceTimersByTime(900);
-            });
-            rerender({timeoutMs: 500});
-            act(() => {
-                jest.advanceTimersByTime(100);
-            });
-
-            // Assert
-            expect(action).not.toHaveBeenCalled();
-            act(() => jest.advanceTimersByTime(500));
-            expect(action).toHaveBeenCalled();
-        });
-
-        it("should should timeout after the new timeoutMs if it gets updated", () => {
-            // Arrange
-            const action = jest.fn();
-            const {rerender} = renderHook(
-                ({timeoutMs}) => useTimeout(action, timeoutMs),
-                {
-                    initialProps: {timeoutMs: 1000},
-                },
-            );
-
-            // Act
-            rerender({timeoutMs: 500});
-            act(() => {
-                jest.advanceTimersByTime(500);
-            });
-
-            // Assert
-            expect(action).toHaveBeenCalled();
-        });
-
-        it("should call the new action after re-rendering with a new action", () => {
-            // Arrange
-            const action1 = jest.fn();
-            const action2 = jest.fn();
-            const {rerender} = renderHook(
-                ({action}) => useTimeout(action, 1000),
-                {
-                    initialProps: {action: action1},
-                },
-            );
-
-            // Act
-            rerender({action: action2});
-            act(() => {
-                jest.advanceTimersByTime(1000);
-            });
-
-            // Assert
-            expect(action2).toHaveBeenCalled();
-        });
-
-        it("should not call the original action after re-rendering with a new action", () => {
-            // Arrange
-            const action1 = jest.fn();
-            const action2 = jest.fn();
-            const {rerender} = renderHook(
-                ({action}) => useTimeout(action, 1000),
-                {
-                    initialProps: {action: action1},
-                },
-            );
-
-            // Act
-            rerender({action: action2});
-            act(() => {
-                jest.advanceTimersByTime(1000);
-            });
-
-            // Assert
-            expect(action1).not.toHaveBeenCalled();
-        });
-
-        it("should not call the action if the timeout is cleared", () => {
-            // Arrange
-            const action = jest.fn();
-            const {result} = renderHook(() => useTimeout(action, 1000));
-
-            // Act
-            act(() => {
-                result.current.clear();
-                jest.advanceTimersByTime(1000);
-            });
-
-            // Assert
-            expect(action).not.toHaveBeenCalled();
-        });
-
-        it("should call the action when the timeout is cleared when passing ClearPolicies.Resolve to clear()", () => {
-            // Arrange
-            const action = jest.fn();
-            const {result} = renderHook(() => useTimeout(action, 1000));
-
-            // Act
-            act(() => {
-                result.current.clear(ClearPolicy.Resolve);
-            });
-
-            // Assert
-            expect(action).toHaveBeenCalled();
-        });
-
-        it("should call the action when the timeout is cleared when using ClearPolicies.Resolve in options", () => {
-            // Arrange
-            const action = jest.fn();
-            const {result} = renderHook(() =>
-                useTimeout(action, 1000, {clearPolicy: ClearPolicy.Resolve}),
-            );
-
-            // Act
-            act(() => {
-                result.current.clear();
-            });
-
-            // Assert
-            expect(action).toHaveBeenCalled();
-        });
-
-        it("should call the action on unmount when using ClearPolicies.Resolve in options", () => {
-            // Arrange
-            const action = jest.fn();
-            const {unmount} = renderHook(() =>
-                useTimeout(action, 1000, {clearPolicy: ClearPolicy.Resolve}),
-            );
-
-            // Act
-            unmount();
-
-            // Assert
-            expect(action).toHaveBeenCalled();
-        });
-
-        it("should not call the action on unmount when using the default options", () => {
-            // Arrange
-            const action = jest.fn();
-            const {unmount} = renderHook(() => useTimeout(action, 1000));
+    it("should fire after the timeout", () => {
+        // Arrange
+        const action = jest.fn();
 
-            // Act
-            unmount();
+        // Act
+        renderHook(() => useTimeout(action, 500, true));
+        jest.advanceTimersByTime(501);
 
-            // Assert
-            expect(action).not.toHaveBeenCalled();
-        });
+        // Assert
+        expect(action).toHaveBeenCalledTimes(1);
     });
 
-    describe("SchedulePolicies.OnDemand", () => {
-        it("should not set the timer on creation", () => {
-            // Arrange
-            const {result} = renderHook(() =>
-                useTimeout(() => {}, 1000, {
-                    schedulePolicy: SchedulePolicy.OnDemand,
-                }),
-            );
+    it("should fire after time after 'active' changes to true", () => {
+        // Arrange
+        const action = jest.fn();
+        const {rerender} = renderHook(
+            ({active}) => useTimeout(action, 500, active),
+            {initialProps: {active: false}},
+        );
 
-            // Act
+        // Act
+        rerender({active: true});
+        jest.advanceTimersByTime(501);
 
-            // Assert
-            expect(result.current.isSet).toBe(false);
-        });
+        // Assert
+        expect(action).toHaveBeenCalled();
+    });
 
-        it("should not call action after timeoutMs if the timer hasn't been set", () => {
-            // Arrange
-            const action = jest.fn();
-            renderHook(() =>
-                useTimeout(action, 1000, {
-                    schedulePolicy: SchedulePolicy.OnDemand,
-                }),
-            );
+    it("should not fire after the timeout if 'active' changes to false", () => {
+        // Arrange
+        const action = jest.fn();
+        const {rerender} = renderHook(
+            ({active}) => useTimeout(action, 500, active),
+            {initialProps: {active: true}},
+        );
 
-            // Act
-            act(() => {
-                jest.advanceTimersByTime(1000);
-            });
+        // Act
+        rerender({active: false});
+        jest.advanceTimersByTime(501);
 
-            // Assert
-            expect(action).not.toHaveBeenCalled();
-        });
+        // Assert
+        expect(action).not.toHaveBeenCalled();
+    });
 
-        it("should call action after timeoutMs if the timer has been set", () => {
-            // Arrange
-            const action = jest.fn();
-            const {result} = renderHook(() =>
-                useTimeout(action, 1000, {
-                    schedulePolicy: SchedulePolicy.OnDemand,
-                }),
-            );
+    it("should reset the timeout if 'timeoutMs' is changes", () => {
+        // Arrange
+        const action = jest.fn();
 
-            // Act
-            act(() => {
-                result.current.set();
-                jest.advanceTimersByTime(1000);
-            });
+        // Act
+        const {rerender} = renderHook(
+            ({timeoutMs}) => useTimeout(action, timeoutMs, true),
+            {initialProps: {timeoutMs: 500}},
+        );
+        rerender({timeoutMs: 1000});
+        jest.advanceTimersByTime(501);
 
-            // Assert
-            expect(action).toHaveBeenCalled();
-        });
+        // Assert
+        expect(action).not.toHaveBeenCalled();
+        jest.advanceTimersByTime(1001);
+        expect(action).toHaveBeenCalled();
+    });
 
-        it("should reset the timer after calling set() again", () => {
-            // Arrange
-            const action = jest.fn();
-            const {result} = renderHook(() =>
-                useTimeout(action, 1000, {
-                    schedulePolicy: SchedulePolicy.OnDemand,
-                }),
-            );
+    it("should not reset the timeout if 'action' changes", () => {
+        // Arrange
+        const action1 = jest.fn();
+        const action2 = jest.fn();
+        const timeoutSpy = jest.spyOn(window, "setTimeout");
 
-            // Act
-            act(() => {
-                result.current.set();
-                jest.advanceTimersByTime(500);
-                result.current.set();
-                jest.advanceTimersByTime(500);
-            });
+        // Act
+        const {rerender} = renderHook(
+            ({action}) => useTimeout(action, 500, true),
+            {initialProps: {action: action1}},
+        );
+        // NOTE: For some reason setTimeout is called twice by the time we get
+        // here.  I've verified that it only gets called once inside the hook
+        // so something else must be calling it.
+        const callCount = timeoutSpy.mock.calls.length;
+        rerender({action: action2});
+        jest.advanceTimersByTime(501);
 
-            // Assert
-            expect(action).not.toHaveBeenCalled();
-        });
+        // Assert
+        expect(timeoutSpy).toHaveBeenCalledTimes(callCount);
+    });
 
-        it("should call the action after calling set() again", () => {
-            // Arrange
-            const action = jest.fn();
-            const {result} = renderHook(() =>
-                useTimeout(action, 1000, {
-                    schedulePolicy: SchedulePolicy.OnDemand,
-                }),
-            );
+    it("should fire the current action if 'action' changes", () => {
+        // Arrange
+        const action1 = jest.fn();
+        const action2 = jest.fn();
 
-            // Act
-            act(() => {
-                result.current.set();
-                jest.advanceTimersByTime(500);
-                result.current.set();
-                jest.advanceTimersByTime(1000);
-            });
+        // Act
+        const {rerender} = renderHook(
+            ({action}) => useTimeout(action, 500, true),
+            {initialProps: {action: action1}},
+        );
+        rerender({action: action2});
+        jest.advanceTimersByTime(501);
 
-            // Assert
-            expect(action).toHaveBeenCalled();
-        });
+        // Assert
+        expect(action1).not.toHaveBeenCalledWith();
+        expect(action2).toHaveBeenCalledWith();
     });
 });

package/src/hooks/internal/use-updating-ref.js

@@ -0,0 +1,20 @@
+// @flow
+import {useEffect, useRef} from "react";
+
+/**
+ * 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}}
+ */
+export const useUpdatingRef = <T>(value: T): {|current: T|} => {
+    const ref = useRef<T>(value);
+    useEffect(() => {
+        ref.current = value;
+    }, [value]);
+    return ref;
+};

package/src/hooks/use-interval.js

@@ -0,0 +1,37 @@
+// @flow
+import {useEffect} from "react";
+
+import {useUpdatingRef} from "./internal/use-updating-ref.js";
+
+/**
+ * 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
+ */
+export function useInterval(
+    action: () => mixed,
+    intervalMs: number,
+    active: boolean,
+) {
+    // 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]);
+}

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

@@ -0,0 +1,80 @@
+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 {useInterval} from "./use-interval.js";
+
+<Meta
+    title="Timing/useInterval"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# `useInterval`
+
+`useInterval` is a hook that provides a simple API for using intervals safely.
+It is defined as follows:
+
+```ts
+function useInterval(
+    action: () => mixed,
+    intervalMs: number,
+    active: boolean,
+): void;
+```
+
+Notes:
+
+-   Setting `active` to `true` will start the interval and setting it to `false`
+    will stop it
+-   Changing the value of `timeoutMs` will reset the interval, changing `action`
+    will not.
+
+export const BasicUsage = () => {
+    const [callCount, setCallCount] = React.useState(0);
+    const [active, setActive] = React.useState(false);
+    const callback = React.useCallback(() => {
+        setCallCount((callCount) => callCount + 1);
+    }, []);
+    useInterval(callback, 1000, active);
+    return (
+        <View>
+            <View>callCount = {callCount}</View>
+            <View>active = {active.toString()}</View>
+            <Button onClick={() => setActive(!active)} style={{width: 200}}>
+                Toggle active
+            </Button>
+        </View>
+    );
+};
+
+<Canvas>
+    <Story name="BasicUsage">
+        <BasicUsage />
+    </Story>
+</Canvas>
+
+```jsx
+export const BasicUsage = () => {
+    const [callCount, setCallCount] = React.useState(0);
+    const [active, setActive] = React.useState(false);
+    const callback = React.useCallback(() => {
+        setCallCount((callCount) => callCount + 1);
+    }, []);
+    useInterval(callback, 1000, active);
+    return (
+        <View>
+            <View>callCount = {callCount}</View>
+            <View>active = {active.toString()}</View>
+            <Button onClick={() => setActive(!active)} style={{width: 200}}>
+                Toggle active
+            </Button>
+        </View>
+    );
+};
+```

package/src/hooks/use-scheduled-interval.js

@@ -0,0 +1,73 @@
+// @flow
+import {useEffect, useState, useCallback} from "react";
+
+import {
+    SchedulePolicy as SchedulePolicies,
+    ClearPolicy as ClearPolicies,
+} from "../util/policies.js";
+import type {IInterval, ClearPolicy, Options} from "../util/types.js";
+
+import {useUpdatingRef} from "./internal/use-updating-ref.js";
+import {useInterval} from "./use-interval.js";
+
+export function useScheduledInterval(
+    action: () => mixed,
+    intervalMs: number,
+    options?: Options,
+): IInterval {
+    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?.schedulePolicy ?? SchedulePolicies.Immediately;
+
+    const [isSet, setIsSet] = useState(
+        schedulePolicy === SchedulePolicies.Immediately,
+    );
+
+    const set = useCallback(() => setIsSet(true), []);
+
+    const actionRef = useUpdatingRef(action);
+
+    const clear = useCallback(
+        (policy?: ClearPolicy) => {
+            policy = policy ?? options?.clearPolicy;
+            if (isSet && policy === ClearPolicies.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?.clearPolicy],
+    );
+
+    const runOnUnmountRef = useUpdatingRef(
+        isSet && options?.clearPolicy === ClearPolicies.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};
+}