@khanacademy/wonder-blocks-timing 2.0.3 → 2.1.0

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

@@ -0,0 +1,147 @@
+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 {useScheduledInterval} from "./use-scheduled-interval.js";
+
+<Meta
+    title="Timing/useScheduledInterval"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# `useScheduledInterval`
+
+`useScheduledInterval` is a hook that provides a convenient API for setting and clearing
+an interval. It is defined as follows:
+
+```ts
+function useScheduledInterval(
+    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 interval will be set immediately up creation. The `options` parameter can
+be used to control when when the interval is schedule and whether or not `action` should be
+called when the interval 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 interval has been cleared will restart the interval.
+-   Updating the second paramter, `timeoutMs`, will also restart the interval.
+-   When the component using this hooks is unmounted, the interval will automatically be cleared.
+-   Calling `set` after the interval is already set does nothing.
+
+export const Immediately = () => {
+    const [callCount, setCallCount] = React.useState(0);
+    const callback = React.useCallback(() => {
+        setCallCount((callCount) => callCount + 1);
+    }, []);
+    const interval = useScheduledInterval(callback, 1000);
+    return (
+        <View>
+            <View>isSet = {interval.isSet.toString()}</View>
+            <View>callCount = {callCount}</View>
+            <View style={{flexDirection: "row"}}>
+                <Button onClick={() => interval.set()}>Set interval</Button>
+                <Button onClick={() => interval.clear()}>Clear interval</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 interval = useScheduledInterval(callback, 1000);
+    return (
+        <View>
+            <View>isSet = {interval.isSet.toString()}</View>
+            <View>callCount = {callCount}</View>
+            <View style={{flexDirection: "row"}}>
+                <Button onClick={() => interval.set()}>Set interval</Button>
+                <Button onClick={() => interval.clear()}>Clear interval</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 interval = useScheduledInterval(callback, 1000, {
+        clearPolicy: ClearPolicy.Resolve,
+        schedulePolicy: SchedulePolicy.OnDemand,
+    });
+    return (
+        <View>
+            <View>isSet = {interval.isSet.toString()}</View>
+            <View>callCount = {callCount}</View>
+            <View style={{flexDirection: "row"}}>
+                <Button onClick={() => interval.set()}>Set interval</Button>
+                <Button onClick={() => interval.clear()}>Clear interval</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 interval = useScheduledInterval(callback, 1000, {
+        clearPolicy: ClearPolicy.Resolve,
+        schedulePolicy: SchedulePolicy.OnDemand,
+    });
+    return (
+        <View>
+            <View>isSet = {interval.isSet.toString()}</View>
+            <View>callCount = {callCount}</View>
+            <View style={{flexDirection: "row"}}>
+                <Button onClick={() => interval.set()}>Set interval</Button>
+                <Button onClick={() => interval.clear()}>Clear interval</Button>
+            </View>
+        </View>
+    );
+};
+```

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

@@ -0,0 +1,80 @@
+// @flow
+import {useEffect, useState, useCallback} from "react";
+
+import {
+    SchedulePolicy as SchedulePolicies,
+    ClearPolicy as ClearPolicies,
+} from "../util/policies.js";
+import type {ITimeout, ClearPolicy, Options} from "../util/types.js";
+
+import {useUpdatingRef} from "./internal/use-updating-ref.js";
+import {useTimeout} from "./use-timeout.js";
+
+export function useScheduledTimeout(
+    action: () => mixed,
+    timeoutMs: number,
+    options?: Options,
+): ITimeout {
+    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?.schedulePolicy ?? SchedulePolicies.Immediately;
+
+    const [isSet, setIsSet] = useState(
+        schedulePolicy === SchedulePolicies.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?: 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
+    }, []);
+
+    useTimeout(wrappedAction, timeoutMs, isSet);
+
+    return {isSet, set, clear};
+}

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

@@ -0,0 +1,148 @@
+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 {useScheduledTimeout} from "./use-scheduled-timeout.js";
+
+<Meta
+    title="Timing/useScheduledTimeout"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# `useScheduledTimeout`
+
+`useScheduledTimeout` is a hook that provides a convenient API for setting and clearing
+a timeout. It is defined as follows:
+
+```ts
+function useScheduledTimeout(
+    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} = useScheduledTimeout(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} = useScheduledTimeout(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} = useScheduledTimeout(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} = useScheduledTimeout(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/hooks/use-timeout.js

@@ -1,70 +1,37 @@
 // @flow
-import {useEffect, useState, useCallback, useRef} from "react";
+import {useEffect} from "react";
 
-import {
-    SchedulePolicy as SchedulePolicies,
-    ClearPolicy as ClearPolicies,
-} from "../util/policies.js";
-import type {ITimeout, ClearPolicy, Options} from "../util/types.js";
+import {useUpdatingRef} from "./internal/use-updating-ref.js";
 
+/**
+ * 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
+ */
 export function useTimeout(
     action: () => mixed,
     timeoutMs: number,
-    options?: Options,
-): ITimeout {
-    const schedulePolicy =
-        options?.schedulePolicy ?? SchedulePolicies.Immediately;
-    const [isSet, setIsSet] = useState(
-        schedulePolicy === SchedulePolicies.Immediately,
-    );
-    const actionRef = useRef(action);
-    const mountedRef = useRef(false);
+    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(() => {
-        mountedRef.current = true;
-        return () => {
-            mountedRef.current = false;
-        };
-    }, []);
-
-    useEffect(() => {
-        actionRef.current = action;
-    }, [action]);
-
-    const clear = useCallback(
-        (policy?: ClearPolicy) => {
-            if ((policy ?? options?.clearPolicy) === ClearPolicies.Resolve) {
+        if (active) {
+            const timeoutId = setTimeout(() => {
                 actionRef.current();
-            }
-            // This will cause the useEffect below to re-run
-            setIsSet(false);
-        },
-        [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();
-                }
+                clearTimeout(timeoutId);
             };
         }
-    }, [clear, isSet, timeoutMs]);
-
-    return {isSet, set, clear};
+        // 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]);
 }

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

@@ -4,7 +4,6 @@ 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
@@ -18,134 +17,63 @@ import {useTimeout} from "./use-timeout.js";
 
 # `useTimeout`
 
-`useTimeout` is a hook that provides a convenient API for setting and clearing
-a timeout. It is defined as follows:
+`useTimeout` is a hook that provides a simple API for using timers safely.
+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;
-}
+    active: boolean,
+): 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>
-    );
-};
-```
+-   Setting `active` to `true` will start the timeout and setting it to `false`
+    will stop it
+-   Changing the value of `timeoutMs` will reset the timeout, changing `action`
+    will not.
 
-export const OnDemandAndResolveOnClear = () => {
+export const BasicUsage = () => {
     const [callCount, setCallCount] = React.useState(0);
+    const [active, setActive] = React.useState(false);
     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,
-    });
+    useTimeout(callback, 1000, active);
     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>active = {active.toString()}</View>
+            <Button onClick={() => setActive(!active)} style={{width: 200}}>
+                Toggle active
+            </Button>
         </View>
     );
 };
 
 <Canvas>
-    <Story name="OnDemandAndResolveOnClear">
-        <OnDemandAndResolveOnClear />
+    <Story name="BasicUsage">
+        <BasicUsage />
     </Story>
 </Canvas>
 
 ```jsx
-const OnDemandAndResolveOnClear = () => {
+export const BasicUsage = () => {
     const [callCount, setCallCount] = React.useState(0);
+    const [active, setActive] = React.useState(false);
     const callback = React.useCallback(() => {
         setCallCount((callCount) => callCount + 1);
     }, []);
-    const {isSet, set, clear} = useTimeout(
-        callback,
-        1000,
-        {
-            clearPolicy: ClearPolicy.Resolve,
-            schedulePolicy: SchedulePolicy.OnDemand,
-        },
-    );
+    useTimeout(callback, 1000, active);
     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>active = {active.toString()}</View>
+            <Button onClick={() => setActive(!active)} style={{width: 200}}>
+                Toggle active
+            </Button>
         </View>
     );
 };

package/src/index.js

@@ -21,4 +21,7 @@ export type {
 
 export {SchedulePolicy, ClearPolicy} from "./util/policies.js";
 export {default as withActionScheduler} from "./components/with-action-scheduler.js";
+export {useInterval} from "./hooks/use-interval.js";
 export {useTimeout} from "./hooks/use-timeout.js";
+export {useScheduledInterval} from "./hooks/use-scheduled-interval.js";
+export {useScheduledTimeout} from "./hooks/use-scheduled-timeout.js";

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2018 Khan Academy
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.