@khanacademy/wonder-blocks-timing 2.0.3 → 2.1.1

package/dist/index.js.flow

@@ -1,2 +1,2 @@
 // @flow
-export * from "../src/index.js";
+export * from "../src/index";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@khanacademy/wonder-blocks-timing",
   "private": false,
-  "version": "2.0.3",
+  "version": "2.1.1",
   "design": "v1",
   "publishConfig": {
     "access": "public"
@@ -17,9 +17,8 @@
     "react": "16.14.0"
   },
   "devDependencies": {
-    "wb-dev-build-settings": "^0.2.0"
+    "wb-dev-build-settings": "^0.7.1"
   },
   "author": "",
-  "license": "MIT",
-  "gitHead": "9ebea88533e702011165072f090a377e02fa3f0f"
+  "license": "MIT"
 }

package/src/__docs__/_overview_.stories.mdx

@@ -0,0 +1,17 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Timing / Overview"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# Timing
+
+`wonder-blocks-timing` provides abstractions for common timing APIs like
+`setTimeout`, `setInterval` and `requestAnimationFrame` that are aware of React
+component lifecycles, ensuring that scheduled timer actions are not unexpectedly
+dangling after a component unmounts.

package/src/components/__docs__/migration.stories.mdx

@@ -0,0 +1,112 @@
+import {Meta} from "@storybook/addon-docs";
+
+<Meta
+    title="Timing / withActionScheduler / Migration from standard API"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+# withActionSceduler
+
+## Migration from standard API
+
+Migrating from the standard API can be done by:
+
+1. Wrapping your component with the `withActionScheduler` HOC (and, if using Flow, using the `WithActionSchedulerProps` type to extend your components props by spreading the type into
+ your component's `Props` type)
+2. Using the new `schedule` prop in your component instead of `setTimeout`, `setInterval` and `requestAnimationFrame`
+
+### Migration Example
+
+Let's imagine we have a component that uses `setTimeout` like this:
+
+```js static
+type Props = {||};
+
+type State = {
+    timerFired: boolean,
+}
+
+class MyLegacyComponent extends React.Component<Props, State> {
+    _timeoutID: TimeoutID;
+
+    state: State = {
+        timerFired: false;
+    };
+
+    componentDidMount() {
+        this.timeoutID = setTimeout(
+            () => this.setState({timerFired: true}),
+            2000,
+        );
+    }
+
+    componentWillUnmount() {
+        /* 0 is a valid ID for a timeout */
+        if (this.timeoutID != null) {
+            clearTimeout(this.timeoutID);
+        }
+    }
+
+    renderState() {
+        const {timerFired} = this.state;
+        if (timerFired) {
+            return "...fired!";
+        }
+        return "pending...";
+    }
+
+    render() {
+        return <View>Legacy Component {this.renderState()}</View>;
+    }
+}
+```
+
+We can rewrite it to use the Wonder Blocks Timing API like this:
+
+```js static
+type Props = {|
+    /**
+     * These props will be injected into your component.  They won't appear
+     * as part of the public props of the component since `withActionSceduler`
+     * will excluding them from the props of the component it returns.
+     */
+    ...withActionSchedulerProps
+|};
+
+type State = {
+    timerFired: boolean,
+}
+
+class MyWonderBlocksComponentImpl extends React.Component<Props, State> {
+    state: State = {
+        timerFired: false;
+    };
+
+    componentDidMount() {
+        const {schedule} = this.props;
+        schedule.timeout(() => this.setState({timerFired: true}), 2000);
+    }
+
+    renderState() {
+        const {timerFired} = this.state;
+        if (timerFired) {
+            return "...fired!";
+        }
+        return "pending...";
+    }
+
+    render() {
+        return <View>Wonder Blocks Component {this.renderState()}</View>;
+    }
+}
+
+/**
+ * The component that you would export as a drop-in replacement for your
+ * legacy component.
+ */
+const MyWonderBlocksComponent = withActionScheduler(MyWonderBlocksComponentImpl);
+```

package/{docs.md → src/components/__docs__/types.ischedule-actions.stories.mdx}

@@ -1,164 +1,15 @@
-Abstractions for common timing APIs like `setTimeout`, `setInterval` and
-`requestAnimationFrame` that are aware of React component lifecycles, ensuring
-that scheduled timer actions are not unexpectedly dangling after a component
-unmounts.
-
-Access to the timing API is provided via the `withActionScheduler` higher order
-component.
-
-### Timing API Usage Example
-
-The following component, `MyNaughtyComponent`, will keep spamming our pretend
-log even after it was unmounted.
-
-```jsx
-import Button from "@khanacademy/wonder-blocks-button";
-import {IDProvider, View} from "@khanacademy/wonder-blocks-core";
-
-class Unmounter extends React.Component {
-    constructor() {
-        super();
-        this.state = {
-            mountKids: true,
-        };
-    }
-
-    maybeRenderKids() {
-        if (this.state.mountKids) {
-            return (
-                <React.Fragment>
-                    <Button onClick={() => this.onClick()}>Unmount</Button>
-                    {this.props.children}
-                </React.Fragment>
-            );
-        } else {
-            return "Children unmounted";
-        }
-    }
-
-    onClick() {
-        this.setState({mountKids: false});
-    }
-
-    render() {
-        return (
-            <View>
-                {this.maybeRenderKids()}
-            </View>
-        );
-    }
-}
-
-class MyNaughtyComponent extends React.Component {
-    componentDidMount() {
-        const {targetId} = this.props;
-        let counter = 0;
-        const domElement = document.getElementById(targetId);
-        setInterval(() => {
-            domElement.innerText = "Naughty interval logged: " + counter++;
-        }, 200);
-    }
-
-    render() {
-        return <View>NaughtyComponent here</View>;
-    }
-}
-
-
-<IDProvider>
-    {id => (
-        <View>
-            <Unmounter>
-                <MyNaughtyComponent targetId={id} />
-            </Unmounter>
-            <View>
-                <View id={id}></View>
-            </View>
-        </View>
-    )}
-</IDProvider>
-```
-
-But if we use `withActionScheduler` and the `interval` method, everything is
-fine. Unmount the component, and the logging stops.
-
-```jsx
-import {withActionScheduler} from "@khanacademy/wonder-blocks-timing";
-import Button from "@khanacademy/wonder-blocks-button";
-import {IDProvider, View} from "@khanacademy/wonder-blocks-core";
-
-class Unmounter extends React.Component {
-    constructor() {
-        super();
-        this.state = {
-            mountKids: true,
-        };
-    }
-
-    maybeRenderKids() {
-        if (this.state.mountKids) {
-            return (
-                <React.Fragment>
-                    <Button onClick={() => this.onClick()}>Unmount</Button>
-                    {this.props.children}
-                </React.Fragment>
-            );
-        } else {
-            return "Children unmounted";
-        }
-    }
-
-    onClick() {
-        this.setState({mountKids: false});
-    }
-
-    render() {
-        return (
-            <View>
-                {this.maybeRenderKids()}
-            </View>
-        );
-    }
-}
+import {Meta} from "@storybook/addon-docs";
 
-class MyGoodComponent extends React.Component {
-    componentDidMount() {
-        const {targetId, schedule} = this.props;
-        let counter = 0;
-        const domElement = document.getElementById(targetId);
-        schedule.interval(() => {
-            domElement.innerText = "Naughty interval logged: " + counter++;
-        }, 200);
-    }
-
-    render() {
-        return <View>GoodComponent here</View>;
-    }
-}
-
-const MyGoodComponentWithScheduler = withActionScheduler(MyGoodComponent);
-
-<IDProvider>
-    {id => (
-        <View>
-            <Unmounter>
-                <MyGoodComponentWithScheduler targetId={id} />
-            </Unmounter>
-            <View>
-                <View id={id}></View>
-            </View>
-        </View>
-    )}
-</IDProvider>
-```
-
-<!-- Styleguidist doesn't support the extended syntax for custom header IDs.
-     If that ever changes, this should be:
-         `### API Overiview {#timing-api-overview}`
--->
-<h3 id="timing-api-overview">API Overview</h3>
+<Meta
+    title="Timing / withActionScheduler / Types / IScheduleActions"
+    parameters={{
+        chromatic: {
+            disableSnapshot: true,
+        },
+    }}
+/>
 
-#### IScheduleActions
+# IScheduleActions
 
 The `IScheduleActions` interface provides 4 (four) different functions:
 
@@ -303,104 +154,4 @@ The `IAnimationFrame` interface provides additional calls to manipulate an anima
 | --- | --- | --- |
 | `isSet` | `boolean` | A read-only property for determining if the request is set (aka pending). Returns `true` if the animation frame is set, otherwise `false`. |
 | `set` | `()`&nbsp;`=>`&nbsp;`void` | If the request is pending, this cancels that pending request and starts a request afresh. If the request is not pending, this starts the request. Can be used to re-request an already invokd or cleared request. |
-| `clear` | `(clearPolicy?:`&nbsp;`ClearPolicy)`&nbsp;`=>`&nbsp;`void` | If the request is pending, this cancels that pending request. If no request is pending, this does nothing. When the optional `clearPolicy` argument is `ClearPolicy.Resolve`, and the request was in the set state when called, the associated action is invoked after cancelling the requst. The `clearPolicy` parameter defaults to `ClearPolicy.Cancel`. This call does nothing if there was no pending request (i.e. when `isSet` is `false`). |
-
-### Migration from standard API
-
-Migrating from the standard API can be done by:
-
-1. Wrapping your component with the `withActionScheduler` HOC (and, if using Flow, using the `WithActionSchedulerProps` type to extend your components props by spreading the type into
- your component's `Props` type)
-2. Using the new `schedule` prop in your component instead of `setTimeout`, `setInterval` and `requestAnimationFrame`
-
-#### Migration Example
-
-Let's imagine we have a component that uses `setTimeout` like this:
-
-```js static
-type Props = {||};
-
-type State = {
-    timerFired: boolean,
-}
-
-class MyLegacyComponent extends React.Component<Props, State> {
-    _timeoutID: TimeoutID;
-
-    state: State = {
-        timerFired: false;
-    };
-
-    componentDidMount() {
-        this.timeoutID = setTimeout(
-            () => this.setState({timerFired: true}),
-            2000,
-        );
-    }
-
-    componentWillUnmount() {
-        /* 0 is a valid ID for a timeout */
-        if (this.timeoutID != null) {
-            clearTimeout(this.timeoutID);
-        }
-    }
-
-    renderState() {
-        const {timerFired} = this.state;
-        if (timerFired) {
-            return "...fired!";
-        }
-        return "pending...";
-    }
-
-    render() {
-        return <View>Legacy Component {this.renderState()}</View>;
-    }
-}
-```
-
-We can rewrite it to use the Wonder Blocks Timing API like this:
-
-```js static
-type Props = {|
-    /**
-     * These props will be injected into your component.  They won't appear
-     * as part of the public props of the component since `withActionSceduler`
-     * will excluding them from the props of the component it returns.
-     */
-    ...withActionSchedulerProps
-|};
-
-type State = {
-    timerFired: boolean,
-}
-
-class MyWonderBlocksComponentImpl extends React.Component<Props, State> {
-    state: State = {
-        timerFired: false;
-    };
-
-    componentDidMount() {
-        const {schedule} = this.props;
-        schedule.timeout(() => this.setState({timerFired: true}), 2000);
-    }
-
-    renderState() {
-        const {timerFired} = this.state;
-        if (timerFired) {
-            return "...fired!";
-        }
-        return "pending...";
-    }
-
-    render() {
-        return <View>Wonder Blocks Component {this.renderState()}</View>;
-    }
-}
-
-/**
- * The component that you would export as a drop-in replacement for your
- * legacy component.
- */
-const MyWonderBlocksComponent = withActionScheduler(MyWonderBlocksComponentImpl);
-```
+| `clear` | `(clearPolicy?:`&nbsp;`ClearPolicy)`&nbsp;`=>`&nbsp;`void` | If the request is pending, this cancels that pending request. If no request is pending, this does nothing. When the optional `clearPolicy` argument is `ClearPolicy.Resolve`, and the request was in the set state when called, the associated action is invoked after cancelling the requst. The `clearPolicy` parameter defaults to `ClearPolicy.Cancel`. This call does nothing if there was no pending request (i.e. when `isSet` is `false`). |

package/src/components/__docs__/with-action-scheduler-examples.js

@@ -0,0 +1,80 @@
+// @flow
+import * as React from "react";
+import Button from "@khanacademy/wonder-blocks-button";
+import {View} from "@khanacademy/wonder-blocks-core";
+import {withActionScheduler} from "@khanacademy/wonder-blocks-timing";
+import type {
+    WithActionSchedulerProps,
+    WithoutActionScheduler,
+} from "@khanacademy/wonder-blocks-timing";
+
+export 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>;
+}
+
+export 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>;
+    }
+}
+
+type Props = {|
+    ...WithActionSchedulerProps,
+    targetId: string,
+|};
+
+export 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>;
+    }
+}
+
+export const MyGoodComponentWithScheduler: React.AbstractComponent<
+    WithoutActionScheduler<React.ElementConfig<typeof MyGoodComponent>>,
+    MyGoodComponent,
+> = withActionScheduler(MyGoodComponent);