@khanacademy/wonder-blocks-timing 2.1.1 → 2.1.2

package/src/components/__docs__/with-action-scheduler.stories.mdx

@@ -1,218 +0,0 @@
-import {Meta, Story, Subtitle, Canvas} from "@storybook/addon-docs";
-import {IDProvider, View} from "@khanacademy/wonder-blocks-core";
-
-import {
-    Unmounter,
-    MyGoodComponentWithScheduler,
-    MyNaughtyComponent,
-} from "./with-action-scheduler-examples.js";
-import ComponentInfo from "../../../../../.storybook/components/component-info.js";
-import {name, version} from "../../../package.json";
-
-<Meta
-    title="Timing / withActionScheduler"
-    parameters={{
-        previewTabs: {
-            canvas: {hidden: true},
-        },
-        viewMode: "docs",
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-    decorators={[
-        (Story) => (
-            <View>{Story()}</View>
-        ),
-    ]}
-/>
-
-# withActionSceduler
-
-<Subtitle>
-    <ComponentInfo name={name} version={version} />
-</Subtitle>
-
-This is a higher order component (HOC) that attaches the given component to an
-[`IScheduleActions`](#ischeduleactions) instance. Any actions scheduled will automatically be
-cleared on unmount. This allows for "set it and forget it" behavior that won't
-leave timers dangling when the component's lifecycle ends.
-
-For more details on using this component and the [`IScheduleActions`](#ischeduleactions) interface,
-see the [API overview](#timing-api-overview).
-
-## Flow Types
-If you are using Flow typing, you can use the `WithActionSchedulerProps` type
-to build the props for the component that you will pass to the `withActionScheduler`
-function by spreading the type into your component's `Props` type.
-
-The added `schedule` prop is of type [`IScheduleActions`](#ischeduleactions). This is what the
-`withActionScheduler` function injects to your component.
-
-The returned value from `withActionScheduler` is a React component with props of
-type `TProps`.
-
-Access to the [timing API](/docs/timing-types-ischeduleactions--page) is provided via the `withActionScheduler` higher order
-component.
-
-## Usage
-
-### Incorrect Usage
-
-The following component, `MyNaughtyComponent`, will keep spamming our pretend
-log even after it was unmounted.
-
-export const IncorrectUsage = () => (
-    <IDProvider id="incorrect">
-        {(id) => (
-            <View>
-                <Unmounter>
-                    <MyNaughtyComponent targetId={id} />
-                </Unmounter>
-                <View id={id} />
-            </View>
-        )}
-    </IDProvider>
-);
-
-<Canvas>
-    <Story name="IncorrectUsage">
-        <IncorrectUsage />
-    </Story>
-</Canvas>
-
-```jsx
-function Unmounter(props: {|children: React.Node|}): React.Node {
-    const [mountKids, setMountKids] = React.useState(true);
-
-    const maybeRenderKids = () => {
-        if (!mountKids) {
-            return "Children unmounted";
-        }
-
-        return (
-            <>
-                <Button
-                    onClick={() => {
-                        setMountKids(false);
-                    }}
-                >
-                    Unmount
-                </Button>
-                {props.children}
-            </>
-        );
-    };
-
-    return <View>{maybeRenderKids()}</View>;
-}
-
-class MyNaughtyComponent extends React.Component<{|targetId: string|}> {
-    componentDidMount() {
-        const {targetId} = this.props;
-        let counter = 0;
-        const domElement: HTMLElement = (document.getElementById(
-            targetId,
-        ): any);
-
-        setInterval(() => {
-            domElement.innerText = "Naughty interval logged: " + counter++;
-        }, 200);
-    }
-
-    render(): React.Node {
-        return <View>NaughtyComponent here</View>;
-    }
-}
-
- const IncorrectUsage = () => (
-    <IDProvider id="incorrect">
-        {(id) => (
-            <View>
-                <Unmounter>
-                    <MyNaughtyComponent targetId={id} />
-                </Unmounter>
-                <View id={id} />
-            </View>
-        )}
-    </IDProvider>
-);
-```
-
-### Correct Usage
-
-But if we use `withActionScheduler` and the `interval` method, everything is
-fine. Unmount the component, and the logging stops.
-
-export const CorrectUsage = () => (
-    <IDProvider id="correct">
-        {(id) => (
-            <View>
-                <Unmounter>
-                    <MyGoodComponentWithScheduler targetId={id} />
-                </Unmounter>
-                <View id={id} />
-            </View>
-        )}
-    </IDProvider>
-);
-
-<Canvas>
-    <Story name="CorrectUsage">
-        <CorrectUsage />
-    </Story>
-</Canvas>
-
-```jsx
-import {withActionScheduler} from "@khanacademy/wonder-blocks-timing";
-import type {
-    WithActionSchedulerProps,
-    WithoutActionScheduler,
-} from "@khanacademy/wonder-blocks-timing";
-
-type Props = {|
-    ...WithActionSchedulerProps,
-    targetId: string,
-|};
-
-class MyGoodComponent extends React.Component<Props> {
-    componentDidMount() {
-        const {targetId, schedule} = this.props;
-        let counter = 0;
-        const domElement: HTMLElement = (document.getElementById(
-            targetId,
-        ): any);
-
-        schedule.interval(() => {
-            domElement.innerText = "Naughty interval logged: " + counter++;
-        }, 200);
-    }
-
-    render(): React.Node {
-        return <View>GoodComponent here</View>;
-    }
-}
-
-const MyGoodComponentWithScheduler: React.AbstractComponent<
-    WithoutActionScheduler<React.ElementConfig<typeof MyGoodComponent>>,
-    MyGoodComponent,
-> = withActionScheduler(MyGoodComponent);
-
-// This is the same as the previous example
-function Unmounter(props: {|children: React.Node|}): React.Node {
-    ...
-}
-
-const CorrectUsage = () => (
-    <IDProvider id="correct">
-        {(id) => (
-            <View>
-                <Unmounter>
-                    <MyGoodComponentWithScheduler targetId={id} />
-                </Unmounter>
-                <View id={id} />
-            </View>
-        )}
-    </IDProvider>
-);
-```

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

@@ -1,80 +0,0 @@
-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 "@khanacademy/wonder-blocks-timing";
-
-<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/__docs__/use-scheduled-interval.stories.mdx

@@ -1,147 +0,0 @@
-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 "@khanacademy/wonder-blocks-timing";
-
-<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/__docs__/use-scheduled-timeout.stories.mdx

@@ -1,148 +0,0 @@
-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 "@khanacademy/wonder-blocks-timing";
-
-<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/__docs__/use-timeout.stories.mdx

@@ -1,80 +0,0 @@
-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 {useTimeout}  from "@khanacademy/wonder-blocks-timing";
-
-<Meta
-    title="Timing/useTimeout"
-    parameters={{
-        chromatic: {
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# `useTimeout`
-
-`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,
-    active: boolean,
-): void;
-```
-
-Notes:
-
--   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 BasicUsage = () => {
-    const [callCount, setCallCount] = React.useState(0);
-    const [active, setActive] = React.useState(false);
-    const callback = React.useCallback(() => {
-        setCallCount((callCount) => callCount + 1);
-    }, []);
-    useTimeout(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);
-    }, []);
-    useTimeout(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>
-    );
-};
-```