@khanacademy/wonder-blocks-button 2.10.1 → 2.10.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanacademy/wonder-blocks-button",
-  "version": "2.10.1",
+  "version": "2.10.2",
   "design": "v1",
   "publishConfig": {
     "access": "public"
@@ -15,14 +15,14 @@
   "author": "",
   "license": "MIT",
   "dependencies": {
-    "@babel/runtime": "^7.13.10",
-    "@khanacademy/wonder-blocks-clickable": "^2.2.0",
-    "@khanacademy/wonder-blocks-color": "^1.1.19",
-    "@khanacademy/wonder-blocks-core": "^3.2.0",
-    "@khanacademy/wonder-blocks-icon": "^1.2.23",
-    "@khanacademy/wonder-blocks-progress-spinner": "^1.1.27",
-    "@khanacademy/wonder-blocks-spacing": "^3.0.4",
-    "@khanacademy/wonder-blocks-typography": "^1.1.27"
+    "@babel/runtime": "^7.16.3",
+    "@khanacademy/wonder-blocks-clickable": "^2.2.1",
+    "@khanacademy/wonder-blocks-color": "^1.1.20",
+    "@khanacademy/wonder-blocks-core": "^4.0.0",
+    "@khanacademy/wonder-blocks-icon": "^1.2.24",
+    "@khanacademy/wonder-blocks-progress-spinner": "^1.1.28",
+    "@khanacademy/wonder-blocks-spacing": "^3.0.5",
+    "@khanacademy/wonder-blocks-typography": "^1.1.28"
   },
   "peerDependencies": {
     "aphrodite": "^1.2.5",
@@ -31,7 +31,7 @@
     "react-router-dom": "5.3.0"
   },
   "devDependencies": {
-    "wb-dev-build-settings": "^0.1.2"
+    "wb-dev-build-settings": "^0.2.0"
   },
-  "gitHead": "61090a61b6e9d2a735976d5fd53a15d06f10c853"
+  "gitHead": "9ebea88533e702011165072f090a377e02fa3f0f"
 }

package/src/__tests__/__snapshots__/generated-snapshot.test.js.snap

@@ -2850,7 +2850,7 @@ exports[`wonder-blocks-button example 9 1`] = `
         }
       }
     >
-      Async action, client-side nav
+      beforeNav, client-side nav
     </span>
   </a>
   <a
@@ -2918,7 +2918,7 @@ exports[`wonder-blocks-button example 9 1`] = `
         }
       }
     >
-      Async action, server-side nav
+      beforeNav, server-side nav
     </span>
   </a>
   <a
@@ -2987,7 +2987,7 @@ exports[`wonder-blocks-button example 9 1`] = `
         }
       }
     >
-      Async action, open URL in new tab
+      beforeNav, open URL in new tab
     </span>
   </a>
 </div>
@@ -3078,13 +3078,242 @@ exports[`wonder-blocks-button example 10 1`] = `
         }
       }
     >
-      This button prevent navigation.
+      safeWithNav, client-side nav
+    </span>
+  </a>
+  <a
+    className=""
+    href="/foo"
+    onBlur={[Function]}
+    onClick={[Function]}
+    onDragStart={[Function]}
+    onFocus={[Function]}
+    onKeyDown={[Function]}
+    onKeyUp={[Function]}
+    onMouseDown={[Function]}
+    onMouseEnter={[Function]}
+    onMouseLeave={[Function]}
+    onMouseUp={[Function]}
+    onTouchCancel={[Function]}
+    onTouchEnd={[Function]}
+    onTouchStart={[Function]}
+    role="button"
+    style={
+      Object {
+        ":focus": Object {
+          "WebkitTapHighlightColor": "rgba(0,0,0,0)",
+        },
+        "alignItems": "center",
+        "background": "#1865f2",
+        "border": "none",
+        "borderRadius": 4,
+        "boxSizing": "border-box",
+        "color": "#ffffff",
+        "cursor": "pointer",
+        "display": "inline-flex",
+        "height": 40,
+        "justifyContent": "center",
+        "marginRight": 10,
+        "outline": "none",
+        "paddingBottom": 0,
+        "paddingLeft": 16,
+        "paddingRight": 16,
+        "paddingTop": 0,
+        "position": "relative",
+        "textDecoration": "none",
+        "touchAction": "manipulation",
+        "userSelect": "none",
+      }
+    }
+    tabIndex={0}
+  >
+    <span
+      className=""
+      style={
+        Object {
+          "MozOsxFontSmoothing": "grayscale",
+          "WebkitFontSmoothing": "antialiased",
+          "alignItems": "center",
+          "display": "inline-block",
+          "fontFamily": "Lato, \\"Noto Sans\\", sans-serif",
+          "fontSize": 16,
+          "fontWeight": "bold",
+          "lineHeight": "20px",
+          "overflow": "hidden",
+          "pointerEvents": "none",
+          "textOverflow": "ellipsis",
+          "whiteSpace": "nowrap",
+        }
+      }
+    >
+      safeWithNav, server-side nav
+    </span>
+  </a>
+  <a
+    className=""
+    href="https://google.com"
+    onBlur={[Function]}
+    onClick={[Function]}
+    onDragStart={[Function]}
+    onFocus={[Function]}
+    onKeyDown={[Function]}
+    onKeyUp={[Function]}
+    onMouseDown={[Function]}
+    onMouseEnter={[Function]}
+    onMouseLeave={[Function]}
+    onMouseUp={[Function]}
+    onTouchCancel={[Function]}
+    onTouchEnd={[Function]}
+    onTouchStart={[Function]}
+    rel="noopener noreferrer"
+    role="button"
+    style={
+      Object {
+        ":focus": Object {
+          "WebkitTapHighlightColor": "rgba(0,0,0,0)",
+        },
+        "alignItems": "center",
+        "background": "#1865f2",
+        "border": "none",
+        "borderRadius": 4,
+        "boxSizing": "border-box",
+        "color": "#ffffff",
+        "cursor": "pointer",
+        "display": "inline-flex",
+        "height": 40,
+        "justifyContent": "center",
+        "marginRight": 10,
+        "outline": "none",
+        "paddingBottom": 0,
+        "paddingLeft": 16,
+        "paddingRight": 16,
+        "paddingTop": 0,
+        "position": "relative",
+        "textDecoration": "none",
+        "touchAction": "manipulation",
+        "userSelect": "none",
+      }
+    }
+    tabIndex={0}
+    target="_blank"
+  >
+    <span
+      className=""
+      style={
+        Object {
+          "MozOsxFontSmoothing": "grayscale",
+          "WebkitFontSmoothing": "antialiased",
+          "alignItems": "center",
+          "display": "inline-block",
+          "fontFamily": "Lato, \\"Noto Sans\\", sans-serif",
+          "fontSize": 16,
+          "fontWeight": "bold",
+          "lineHeight": "20px",
+          "overflow": "hidden",
+          "pointerEvents": "none",
+          "textOverflow": "ellipsis",
+          "whiteSpace": "nowrap",
+        }
+      }
+    >
+      safeWithNav, open URL in new tab
     </span>
   </a>
 </div>
 `;
 
 exports[`wonder-blocks-button example 11 1`] = `
+<div
+  className=""
+  style={
+    Object {
+      "alignItems": "center",
+      "borderStyle": "solid",
+      "borderWidth": 0,
+      "boxSizing": "border-box",
+      "display": "flex",
+      "flexDirection": "row",
+      "margin": 0,
+      "minHeight": 0,
+      "minWidth": 0,
+      "padding": 0,
+      "position": "relative",
+      "zIndex": 0,
+    }
+  }
+>
+  <a
+    className=""
+    href="/foo"
+    onBlur={[Function]}
+    onClick={[Function]}
+    onDragStart={[Function]}
+    onFocus={[Function]}
+    onKeyDown={[Function]}
+    onKeyUp={[Function]}
+    onMouseDown={[Function]}
+    onMouseEnter={[Function]}
+    onMouseLeave={[Function]}
+    onMouseUp={[Function]}
+    onTouchCancel={[Function]}
+    onTouchEnd={[Function]}
+    onTouchStart={[Function]}
+    role="button"
+    style={
+      Object {
+        ":focus": Object {
+          "WebkitTapHighlightColor": "rgba(0,0,0,0)",
+        },
+        "alignItems": "center",
+        "background": "#1865f2",
+        "border": "none",
+        "borderRadius": 4,
+        "boxSizing": "border-box",
+        "color": "#ffffff",
+        "cursor": "pointer",
+        "display": "inline-flex",
+        "height": 40,
+        "justifyContent": "center",
+        "marginRight": 10,
+        "outline": "none",
+        "paddingBottom": 0,
+        "paddingLeft": 16,
+        "paddingRight": 16,
+        "paddingTop": 0,
+        "position": "relative",
+        "textDecoration": "none",
+        "touchAction": "manipulation",
+        "userSelect": "none",
+      }
+    }
+    tabIndex={0}
+  >
+    <span
+      className=""
+      style={
+        Object {
+          "MozOsxFontSmoothing": "grayscale",
+          "WebkitFontSmoothing": "antialiased",
+          "alignItems": "center",
+          "display": "inline-block",
+          "fontFamily": "Lato, \\"Noto Sans\\", sans-serif",
+          "fontSize": 16,
+          "fontWeight": "bold",
+          "lineHeight": "20px",
+          "overflow": "hidden",
+          "pointerEvents": "none",
+          "textOverflow": "ellipsis",
+          "whiteSpace": "nowrap",
+        }
+      }
+    >
+      This button prevents navigation.
+    </span>
+  </a>
+</div>
+`;
+
+exports[`wonder-blocks-button example 12 1`] = `
 <div
   className=""
   style={
@@ -3718,7 +3947,7 @@ exports[`wonder-blocks-button example 11 1`] = `
 </div>
 `;
 
-exports[`wonder-blocks-button example 12 1`] = `
+exports[`wonder-blocks-button example 13 1`] = `
 <div
   className=""
   style={
@@ -3817,7 +4046,7 @@ exports[`wonder-blocks-button example 12 1`] = `
 </div>
 `;
 
-exports[`wonder-blocks-button example 13 1`] = `
+exports[`wonder-blocks-button example 14 1`] = `
 <div
   className=""
   style={
@@ -3912,7 +4141,7 @@ exports[`wonder-blocks-button example 13 1`] = `
 </div>
 `;
 
-exports[`wonder-blocks-button example 14 1`] = `
+exports[`wonder-blocks-button example 15 1`] = `
 <div
   className=""
   style={
@@ -4139,7 +4368,7 @@ exports[`wonder-blocks-button example 14 1`] = `
 </div>
 `;
 
-exports[`wonder-blocks-button example 15 1`] = `
+exports[`wonder-blocks-button example 16 1`] = `
 <div
   className=""
   style={
@@ -4313,7 +4542,7 @@ exports[`wonder-blocks-button example 15 1`] = `
 </div>
 `;
 
-exports[`wonder-blocks-button example 16 1`] = `
+exports[`wonder-blocks-button example 17 1`] = `
 <div
   className=""
   style={
@@ -4488,7 +4717,7 @@ exports[`wonder-blocks-button example 16 1`] = `
 </div>
 `;
 
-exports[`wonder-blocks-button example 17 1`] = `
+exports[`wonder-blocks-button example 18 1`] = `
 <div
   className=""
   style={
@@ -4677,7 +4906,7 @@ exports[`wonder-blocks-button example 17 1`] = `
 </div>
 `;
 
-exports[`wonder-blocks-button example 18 1`] = `
+exports[`wonder-blocks-button example 19 1`] = `
 <div
   className=""
   style={

package/src/__tests__/generated-snapshot.test.js

@@ -426,7 +426,7 @@ describe("wonder-blocks-button", () => {
                             })
                         }
                     >
-                        Async action, client-side nav
+                        beforeNav, client-side nav
                     </Button>
                     <Button
                         href="/foo"
@@ -438,7 +438,7 @@ describe("wonder-blocks-button", () => {
                             })
                         }
                     >
-                        Async action, server-side nav
+                        beforeNav, server-side nav
                     </Button>
                     <Button
                         href="https://google.com"
@@ -451,7 +451,7 @@ describe("wonder-blocks-button", () => {
                             })
                         }
                     >
-                        Async action, open URL in new tab
+                        beforeNav, open URL in new tab
                     </Button>
                     <Switch>
                         <Route path="/foo">
@@ -482,9 +482,38 @@ describe("wonder-blocks-button", () => {
                     <Button
                         href="/foo"
                         style={styles.button}
-                        onClick={(e) => e.preventDefault()}
+                        safeWithNav={() =>
+                            new Promise((resolve, reject) => {
+                                setTimeout(resolve, 1000);
+                            })
+                        }
+                    >
+                        safeWithNav, client-side nav
+                    </Button>
+                    <Button
+                        href="/foo"
+                        style={styles.button}
+                        skipClientNav={true}
+                        safeWithNav={() =>
+                            new Promise((resolve, reject) => {
+                                setTimeout(resolve, 1000);
+                            })
+                        }
+                    >
+                        safeWithNav, server-side nav
+                    </Button>
+                    <Button
+                        href="https://google.com"
+                        target="_blank"
+                        style={styles.button}
+                        skipClientNav={true}
+                        safeWithNav={() =>
+                            new Promise((resolve, reject) => {
+                                setTimeout(resolve, 1000);
+                            })
+                        }
                     >
-                        This button prevent navigation.
+                        safeWithNav, open URL in new tab
                     </Button>
                     <Switch>
                         <Route path="/foo">
@@ -499,6 +528,39 @@ describe("wonder-blocks-button", () => {
     });
 
     it("example 11", () => {
+        const styles = StyleSheet.create({
+            row: {
+                flexDirection: "row",
+                alignItems: "center",
+            },
+            button: {
+                marginRight: 10,
+            },
+        }); // NOTE: In actual code you would use BrowserRouter instead
+
+        const example = (
+            <MemoryRouter>
+                <View style={styles.row}>
+                    <Button
+                        href="/foo"
+                        style={styles.button}
+                        onClick={(e) => e.preventDefault()}
+                    >
+                        This button prevents navigation.
+                    </Button>
+                    <Switch>
+                        <Route path="/foo">
+                            <View id="foo">Hello, world!</View>
+                        </Route>
+                    </Switch>
+                </View>
+            </MemoryRouter>
+        );
+        const tree = renderer.create(example).toJSON();
+        expect(tree).toMatchSnapshot();
+    });
+
+    it("example 12", () => {
         const styles = StyleSheet.create({
             row: {
                 flexDirection: "row",
@@ -542,7 +604,7 @@ describe("wonder-blocks-button", () => {
         expect(tree).toMatchSnapshot();
     });
 
-    it("example 12", () => {
+    it("example 13", () => {
         const example = (
             <View>
                 <form onSubmit={() => alert("the form was submitted")}>
@@ -554,7 +616,7 @@ describe("wonder-blocks-button", () => {
         expect(tree).toMatchSnapshot();
     });
 
-    it("example 13", () => {
+    it("example 14", () => {
         const example = (
             <View>
                 <Button>Label</Button>
@@ -564,7 +626,7 @@ describe("wonder-blocks-button", () => {
         expect(tree).toMatchSnapshot();
     });
 
-    it("example 14", () => {
+    it("example 15", () => {
         const styles = StyleSheet.create({
             column: {
                 alignItems: "flex-start",
@@ -594,7 +656,7 @@ describe("wonder-blocks-button", () => {
         expect(tree).toMatchSnapshot();
     });
 
-    it("example 15", () => {
+    it("example 16", () => {
         const styles = StyleSheet.create({
             row: {
                 flexDirection: "row",
@@ -621,7 +683,7 @@ describe("wonder-blocks-button", () => {
         expect(tree).toMatchSnapshot();
     });
 
-    it("example 16", () => {
+    it("example 17", () => {
         const styles = StyleSheet.create({
             row: {
                 flexDirection: "row",
@@ -649,7 +711,7 @@ describe("wonder-blocks-button", () => {
         expect(tree).toMatchSnapshot();
     });
 
-    it("example 17", () => {
+    it("example 18", () => {
         const styles = StyleSheet.create({
             row: {
                 flexDirection: "row",
@@ -672,7 +734,7 @@ describe("wonder-blocks-button", () => {
         expect(tree).toMatchSnapshot();
     });
 
-    it("example 18", () => {
+    it("example 19", () => {
         const styles = StyleSheet.create({
             row: {
                 flexDirection: "row",

package/src/components/__docs__/button.argtypes.js

@@ -60,8 +60,7 @@ export default {
             category: "Theming",
             type: {
                 summary: "boolean",
-                detail:
-                    "Sets primary button background color to white, and secondary and tertiary button title to color.",
+                detail: "Sets primary button background color to white, and secondary and tertiary button title to color.",
             },
         },
     },
@@ -161,8 +160,7 @@ export default {
             category: "Navigation",
             type: {
                 summary: "Note",
-                detail:
-                    "All URLs containing a protocol are considered external, e.g. https://khanacademy.org/math/algebra/eval-exprs will trigger a full page reload.",
+                detail: "All URLs containing a protocol are considered external, e.g. https://khanacademy.org/math/algebra/eval-exprs will trigger a full page reload.",
             },
         },
     },
@@ -199,12 +197,11 @@ export default {
         },
     },
     beforeNav: {
-        description: `Run async code before navigating. If the promise returned rejects then navigation will not occur.`,
+        description: `Run async code before navigating. If the promise returned rejects then navigation will not occur. If both safeWithNav and beforeNav are provided, beforeNav will be run first and safeWithNav will only be run if beforeNav does not reject.`,
         table: {
             category: "Navigation",
             type: {
                 summary: "() => Promise<mixed>",
-                detail: `If both safeWithNav and beforeNav are provided, beforeNav will be run first and safeWithNav will only be run if beforeNav does not reject.`,
             },
         },
     },

package/src/components/__docs__/navigation-callbacks.stories.mdx

@@ -0,0 +1,68 @@
+import {Meta, Story, Canvas} from "@storybook/addon-docs";
+import {StyleSheet} from "aphrodite";
+
+import Button from "@khanacademy/wonder-blocks-button";
+import {View} from "@khanacademy/wonder-blocks-core";
+
+<Meta
+    title="Navigation/Button/Navigation Callbacks"
+    component={Button}
+    parameters={{
+        previewTabs: {
+            canvas: {hidden: true},
+        },
+        viewMode: "docs",
+        chromatic: {
+            // Disables chromatic testing for these stories.
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+## Running Callbacks on Navigation
+
+Sometimes you may need to run some code and also navigate when the user
+clicks the button. For example, you might want to send a request to the
+server and also send the user to a different page. You can do this by
+passing in a URL to the `href` prop and also passing in a callback
+function to either the `onClick`, `beforeNav`, or `safeWithNav` prop.
+Which prop you choose depends on your use case.
+
+- `onClick` is guaranteed to run to completion before navigation starts,
+  but it is not async aware, so it should only be used if all of the code
+  in your callback function executes synchronously.
+
+- `beforeNav` is guaranteed to run async operations before navigation
+  starts. You must return a promise from the callback function passed in
+  to this prop, and the navigation will happen after the promise
+  resolves. If the promise rejects, the navigation will not occur.
+  This prop should be used if it's important that the async code
+  completely finishes before the next URL starts loading.
+
+- `safeWithNav` runs async code concurrently with navigation when safe,
+  but delays navigation until the async code is finished when
+  concurrent execution is not safe. You must return a promise from the
+  callback function passed in to this prop, and Wonder Blocks will run
+  the async code in parallel with client-side navigation or while opening
+  a new tab, but will wait until the async code finishes to start a
+  server-side navigation. If the promise rejects the navigation will
+  happen anyway. This prop should be used when it's okay to load
+  the next URL while the async callback code is running.
+
+This table gives an overview of the options:
+
+| Prop        | Async safe? | Completes before navigation? |
+|-------------|-------------|------------------------------|
+| onClick     | no          | yes                          |
+| beforeNav   | yes         | yes                          |
+| safeWithNav | yes         | no                           |
+
+It is possible to use more than one of these props on the same element.
+If multiple props are used, they will run in this order: first `onClick`,
+then `beforeNav`, then `safeWithNav`. If both `beforeNav` and `safeWithNav`
+are used, the `safeWithNav` callback will not be called until the
+`beforeNav` promise resolves successfully. If the `beforeNav` promise
+rejects, `safeWithNav` will not be run.
+
+If the `onClick` handler calls `preventDefault()`, then `beforeNav`
+and `safeWithNav` will still run, but navigation will not occur.

package/src/components/button.js

@@ -139,11 +139,10 @@ export type SharedProps = {|
     /**
      * Function to call when button is clicked.
      *
-     * This callback should be used for things like marking BigBingo
-     * conversions. It should NOT be used to redirect to a different URL or to
-     * prevent navigation via e.preventDefault(). The event passed to this
-     * handler will have its preventDefault() and stopPropagation() methods
-     * stubbed out.
+     * This callback should be used for running synchronous code, like
+     * dispatching a Redux action. For asynchronous code see the
+     * beforeNav and safeWithNav props. It should NOT be used to redirect
+     * to a different URL.
      *
      * Note: onClick is optional if href is present, but must be defined if
      * href is not

package/src/components/button.md

@@ -1,4 +1,4 @@
-#### Example: kind
+### Example: kind
 
 There are three `kind`s of buttons: `"primary"` (default), `"secondary"`, and
 `"tertiary"`:
@@ -40,7 +40,7 @@ const styles = StyleSheet.create({
 </View>
 ```
 
-#### Example: color
+### Example: color
 
 Buttons have a `color` that is either `"default"` (the default, as shown above) or `"destructive"` (as can seen below):
 
@@ -85,7 +85,7 @@ const styles = StyleSheet.create({
 </View>
 ```
 
-#### Example: disabled
+### Example: disabled
 
 Buttons can be `disabled`:
 
@@ -139,7 +139,7 @@ const styles = StyleSheet.create({
 </View>
 ```
 
-#### Example: dark
+### Example: dark
 
 Buttons on a `darkBlue` background should set `light` to `true`.
 ```jsx
@@ -212,7 +212,7 @@ const styles = StyleSheet.create({
 </View>
 ```
 
-#### Example: size
+### Example: size
 
 Buttons have a `size` that's either `"medium"` (default), `"small"`, or `"xlarge"`.
 ```js
@@ -309,7 +309,7 @@ const styles = StyleSheet.create({
 </View>
 ```
 
-#### Example: spinner
+### Example: spinner
 
 Buttons can show a `spinner`.  This is useful when indicating to a user that
 their input has been recognized but that the operation will take some time.
@@ -343,7 +343,7 @@ const styles = StyleSheet.create({
 </View>
 ```
 
-#### Example: Navigation
+### Example: Navigation
 
 ```jsx
 import Button from "@khanacademy/wonder-blocks-button";
@@ -384,7 +384,7 @@ const styles = StyleSheet.create({
 </View>
 ```
 
-#### Example: Navigation with React Router
+### Example: Navigation with React Router
 
 Buttons do client-side navigation by default, if React Router exists:
 ```jsx
@@ -420,12 +420,59 @@ const styles = StyleSheet.create({
     </View>
 </MemoryRouter>
 ```
+### Running callbacks on navigation
+
+Sometimes you may need to run some code and also navigate when the user
+clicks the button. For example, you might want to send a request to the
+server and also send the user to a different page. You can do this by
+passing in a URL to the `href` prop and also passing in a callback
+function to either the `onClick`, `beforeNav`, or `safeWithNav` prop.
+Which prop you choose depends on your use case.
+
+- `onClick` is guaranteed to run to completion before navigation starts,
+  but it is not async aware, so it should only be used if all of the code
+  in your callback function executes synchronously.
+
+- `beforeNav` is guaranteed to run async operations before navigation
+  starts. You must return a promise from the callback function passed in
+  to this prop, and the navigation will happen after the promise
+  resolves. If the promise rejects, the navigation will not occur.
+  This prop should be used if it's important that the async code
+  completely finishes before the next URL starts loading.
+
+- `safeWithNav` runs async code concurrently with navigation when safe,
+  but delays navigation until the async code is finished when
+  concurrent execution is not safe. You must return a promise from the
+  callback function passed in to this prop, and Wonder Blocks will run
+  the async code in parallel with client-side navigation or while opening
+  a new tab, but will wait until the async code finishes to start a
+  server-side navigation. If the promise rejects the navigation will
+  happen anyway. This prop should be used when it's okay to load
+  the next URL while the async callback code is running.
+
+This table gives an overview of the options:
+
+| Prop        | Async safe? | Completes before navigation? |
+|-------------|-------------|------------------------------|
+| onClick     | no          | yes                          |
+| beforeNav   | yes         | yes                          |
+| safeWithNav | yes         | no                           |
+
+It is possible to use more than one of these props on the same element.
+If multiple props are used, they will run in this order: first `onClick`,
+then `beforeNav`, then `safeWithNav`. If both `beforeNav` and `safeWithNav`
+are used, the `safeWithNav` callback will not be called until the
+`beforeNav` promise resolves successfully. If the `beforeNav` promise
+rejects, `safeWithNav` will not be run.
+
+If the `onClick` handler calls `preventDefault()`, then `beforeNav`
+and `safeWithNav` will still run, but navigation will not occur.
+
+### Example: beforeNav callbacks
+
+These buttons always wait until the async callback code completes before
+starting navigation.
 
-#### Example: Navigation with async action
-
-Sometimes you may need to perform an async action either before or during
-navigation.  This can be accomplished with `beforeNav` and `safeWithNav`
-respectively.
 ```jsx
 import Button from "@khanacademy/wonder-blocks-button";
 import {View} from "@khanacademy/wonder-blocks-core";
@@ -452,7 +499,7 @@ const styles = StyleSheet.create({
                 setTimeout(resolve, 1000);
             })}
         >
-            Async action, client-side nav
+            beforeNav, client-side nav
         </Button>
         <Button
             href="/foo"
@@ -462,7 +509,7 @@ const styles = StyleSheet.create({
                 setTimeout(resolve, 1000);
             })}
         >
-            Async action, server-side nav
+            beforeNav, server-side nav
         </Button>
         <Button
             href="https://google.com"
@@ -473,7 +520,71 @@ const styles = StyleSheet.create({
                 setTimeout(resolve, 1000);
             })}
         >
-            Async action, open URL in new tab
+            beforeNav, open URL in new tab
+        </Button>
+        <Switch>
+            <Route path="/foo">
+                <View id="foo">Hello, world!</View>
+            </Route>
+        </Switch>
+    </View>
+</MemoryRouter>
+```
+
+### Example: safeWithNav callbacks
+
+These buttons navigate immediately when doing client-side navigation
+or when opening a new tab, but wait until the async callback code
+completes before starting server-side navigation.
+
+```jsx
+import Button from "@khanacademy/wonder-blocks-button";
+import {View} from "@khanacademy/wonder-blocks-core";
+import {StyleSheet} from "aphrodite";
+import {MemoryRouter, Route, Switch} from "react-router-dom";
+
+const styles = StyleSheet.create({
+    row: {
+        flexDirection: "row",
+        alignItems: "center",
+    },
+    button: {
+        marginRight: 10,
+    }
+});
+
+// NOTE: In actual code you would use BrowserRouter instead
+<MemoryRouter>
+    <View style={styles.row}>
+        <Button
+            href="/foo"
+            style={styles.button}
+            safeWithNav={() => new Promise((resolve, reject) => {
+                setTimeout(resolve, 1000);
+            })}
+        >
+            safeWithNav, client-side nav
+        </Button>
+        <Button
+            href="/foo"
+            style={styles.button}
+            skipClientNav={true}
+            safeWithNav={() => new Promise((resolve, reject) => {
+                setTimeout(resolve, 1000);
+            })}
+        >
+            safeWithNav, server-side nav
+        </Button>
+        <Button
+            href="https://google.com"
+            target="_blank"
+            style={styles.button}
+            skipClientNav={true}
+            safeWithNav={() => new Promise((resolve, reject) => {
+                setTimeout(resolve, 1000);
+            })}
+        >
+            safeWithNav, open URL in new tab
         </Button>
         <Switch>
             <Route path="/foo">
@@ -484,11 +595,11 @@ const styles = StyleSheet.create({
 </MemoryRouter>
 ```
 
-#### Example: Prevent navigation by calling e.preventDefault()
+### Example: Prevent navigation by calling e.preventDefault()
+
+If the `onClick` callback calls `preventDefault()`, then navigation
+will not occur.
 
-Sometimes you may need to perform an async action either before or during
-navigation.  This can be accomplished with `beforeNav` and `safeWithNav`
-respectively.
 ```jsx
 import Button from "@khanacademy/wonder-blocks-button";
 import {View} from "@khanacademy/wonder-blocks-core";
@@ -513,7 +624,7 @@ const styles = StyleSheet.create({
             style={styles.button}
             onClick={e => e.preventDefault()}
         >
-            This button prevent navigation.
+            This button prevents navigation.
         </Button>
         <Switch>
             <Route path="/foo">
@@ -524,7 +635,7 @@ const styles = StyleSheet.create({
 </MemoryRouter>
 ```
 
-#### Example: style
+### Example: style
 
 Buttons can have a `style` props which supports width, position, margin,
 and flex styles.
@@ -582,7 +693,7 @@ const kinds = ["primary", "secondary", "tertiary"];
 </View>
 ```
 
-#### Example: "submit" buttons in forms
+### Example: "submit" buttons in forms
 
 ```jsx
 import Button from "@khanacademy/wonder-blocks-button";

package/src/components/button.stories.js

@@ -48,8 +48,7 @@ DefaultButton.args = {
 DefaultButton.parameters = {
     design: {
         type: "figma",
-        url:
-            "https://www.figma.com/file/VbVu3h2BpBhH80niq101MHHE/Wonder-Blocks-(Web)?node-id=401%3A307",
+        url: "https://www.figma.com/file/VbVu3h2BpBhH80niq101MHHE/Wonder-Blocks-(Web)?node-id=401%3A307",
     },
     chromatic: {
         // We already have screenshots of other stories that cover more of the button states
@@ -353,7 +352,7 @@ ButtonsWithRouter.parameters = {
     },
 };
 
-export const NavigationWithAsyncAction: StoryComponentType = () => (
+export const BeforeNavCallbacks: StoryComponentType = () => (
     <MemoryRouter>
         <View style={styles.row}>
             <Button
@@ -365,7 +364,7 @@ export const NavigationWithAsyncAction: StoryComponentType = () => (
                     })
                 }
             >
-                Async action, client-side nav
+                beforeNav, client-side nav
             </Button>
             <Button
                 href="/foo"
@@ -377,7 +376,7 @@ export const NavigationWithAsyncAction: StoryComponentType = () => (
                     })
                 }
             >
-                Async action, server-side nav
+                beforeNav, server-side nav
             </Button>
             <Button
                 href="https://google.com"
@@ -389,7 +388,7 @@ export const NavigationWithAsyncAction: StoryComponentType = () => (
                     })
                 }
             >
-                Async action, open URL
+                beforeNav, open URL in new tab
             </Button>
             <Switch>
                 <Route path="/foo">
@@ -400,10 +399,71 @@ export const NavigationWithAsyncAction: StoryComponentType = () => (
     </MemoryRouter>
 );
 
-NavigationWithAsyncAction.parameters = {
+BeforeNavCallbacks.storyName = "beforeNav Callbacks";
+
+BeforeNavCallbacks.parameters = {
     docs: {
         storyDescription:
-            "Sometimes you may need to perform an async action either before or during navigation. This can be accomplished with `beforeNav` and `safeWithNav` respectively.",
+            "These buttons always wait until the async callback code completes before starting navigation.",
+    },
+    chromatic: {
+        disableSnapshot: true,
+    },
+};
+
+export const SafeWithNavCallbacks: StoryComponentType = () => (
+    <MemoryRouter>
+        <View style={styles.row}>
+            <Button
+                href="/foo"
+                style={styles.button}
+                safeWithNav={() =>
+                    new Promise((resolve, reject) => {
+                        setTimeout(resolve, 1000);
+                    })
+                }
+            >
+                safeWithNav, client-side nav
+            </Button>
+            <Button
+                href="/foo"
+                style={styles.button}
+                skipClientNav={true}
+                safeWithNav={() =>
+                    new Promise((resolve, reject) => {
+                        setTimeout(resolve, 1000);
+                    })
+                }
+            >
+                safeWithNav, server-side nav
+            </Button>
+            <Button
+                href="https://google.com"
+                style={styles.button}
+                skipClientNav={true}
+                safeWithNav={() =>
+                    new Promise((resolve, reject) => {
+                        setTimeout(resolve, 1000);
+                    })
+                }
+            >
+                safeWithNav, open URL in new tab
+            </Button>
+            <Switch>
+                <Route path="/foo">
+                    <View id="foo">Hello, world!</View>
+                </Route>
+            </Switch>
+        </View>
+    </MemoryRouter>
+);
+
+SafeWithNavCallbacks.storyName = "safeWithNav Callbacks";
+
+SafeWithNavCallbacks.parameters = {
+    docs: {
+        storyDescription:
+            "If the `onClick` callback calls `preventDefault()`, then navigation will not occur.",
     },
     chromatic: {
         disableSnapshot: true,
@@ -421,7 +481,7 @@ export const PreventNavigation: StoryComponentType = () => (
                     e.preventDefault();
                 }}
             >
-                This button prevent navigation.
+                This button prevents navigation.
             </Button>
             <Switch>
                 <Route path="/foo">