@khanacademy/wonder-blocks-button 2.9.13 → 2.10.2

package/src/components/__docs__/best-practices.stories.mdx

@@ -0,0 +1,107 @@
+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/Best practices"
+    component={Button}
+    parameters={{
+        previewTabs: {
+            canvas: {hidden: true},
+        },
+        viewMode: "docs",
+        chromatic: {
+            // Disables chromatic testing for these stories.
+            disableSnapshot: true,
+        },
+    }}
+/>
+
+## Best Practices
+
+### Layout
+
+In vertical layouts, buttons will stretch horizontally to fill the available
+space. This is probably not what you want unless you're on a very narrow
+screen.
+
+<Canvas>
+    <Story name="Full-bleed button">
+        <View>
+            <Button>Label</Button>
+        </View>
+    </Story>
+</Canvas>
+
+This can be corrected by applying appropriate flex styles to the container.
+
+<Canvas>
+    <Story name="Buttons in rows">
+        <View>
+            <View style={styles.row}>
+                <Button>Button in a row</Button>
+            </View>
+            <View style={styles.gap} />
+            <View style={styles.column}>
+                <Button>Button in a column</Button>
+            </View>
+        </View>
+    </Story>
+</Canvas>
+
+### Usign minWidth for internationalization
+
+Layouts often specify a specific width of button. When implementing such designs use `minWidth` instead of `width`. `minWidth` allows the button to resize to fit the content whereas `width` does not. This is important for international sites since sometimes strings for UI elements can be much longer in other languages. Both of the buttons below have a "natural" width of `144px`. The one on the right is wider but it accommodates the full string instead of wrapping it.
+
+<Canvas>
+    <Story name="Using minWidth">
+        <View style={styles.row}>
+            <Button style={styles.buttonMinWidth} kind="secondary">
+                label
+            </Button>
+            <Button style={styles.buttonMinWidth}>
+                label in a different language
+            </Button>
+        </View>
+    </Story>
+</Canvas>
+
+### Truncating text
+
+If the parent container of the button doesn't have enough room to accommodate
+the width of the button, the text will truncate. This should ideally never
+happen, but it's sometimes a necessary fallback.
+
+<Canvas>
+    <Story name="Truncating text">
+        <View style={{flexDirection: "row", width: 300}}>
+            <Button style={styles.buttonMinWidth} kind="secondary">
+                label
+            </Button>
+            <Button style={styles.buttonMinWidth}>
+                label too long for the parent container
+            </Button>
+        </View>
+    </Story>
+</Canvas>
+
+export const styles = StyleSheet.create({
+    column: {
+        alignItems: "flex-start",
+    },
+    row: {
+        flexDirection: "row",
+    },
+    gap: {
+        height: 16,
+    },
+    button: {
+        marginRight: 10,
+    },
+    buttonMinWidth: {
+        marginRight: 10,
+        minWidth: 144,
+    },
+});

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

@@ -0,0 +1,231 @@
+// @flow
+import {icons} from "@khanacademy/wonder-blocks-icon";
+
+export default {
+    children: {
+        description: "Text to appear on the button.",
+        type: {required: true},
+    },
+    icon: {
+        description: "An icon, displayed to the left of the title.",
+        type: {required: false},
+        control: {type: "select"},
+        options: (Object.keys(icons): Array<string>),
+        mapping: icons,
+        table: {
+            category: "Layout",
+            type: {summary: "IconAsset"},
+        },
+    },
+    spinner: {
+        description: "If true, replaces the contents with a spinner.",
+        control: {type: "boolean"},
+        table: {
+            category: "Layout",
+            type: {
+                summary: "boolean",
+                detail: "Setting this prop to `true` will disable the button.",
+            },
+        },
+    },
+    color: {
+        description: "The color of the button, either blue or red.",
+        options: ["default", "destructive"],
+        control: {type: "radio"},
+        table: {
+            category: "Theming",
+            type: {
+                summary: `"default" | "destructive"`,
+            },
+        },
+    },
+    kind: {
+        description:
+            "The kind of the button, either primary, secondary, or tertiary.",
+        options: ["primary", "secondary", "tertiary"],
+        control: {type: "select"},
+        table: {
+            type: {summary: "primary | secondary | tertiary"},
+            defaultValue: {
+                detail: `
+                - Primary buttons have background colors.\n- Secondary buttons have a border and no background color.\n- Tertiary buttons have no background or border.
+                `,
+            },
+        },
+    },
+    light: {
+        description: "Whether the button is on a dark/colored background.",
+        control: {type: "boolean"},
+        table: {
+            category: "Theming",
+            type: {
+                summary: "boolean",
+                detail: "Sets primary button background color to white, and secondary and tertiary button title to color.",
+            },
+        },
+    },
+    size: {
+        description: "The size of the button.",
+        options: ["small", "medium", "xlarge"],
+        control: {type: "select"},
+        table: {
+            category: "Layout",
+            defaultValue: {
+                detail: `"medium" = height: 40; "small" = height: 32; "xlarge" = height: 60;`,
+            },
+            type: {
+                summary: `"medium" | "small" | "xlarge"`,
+            },
+        },
+    },
+    disabled: {
+        description: "Whether the button is disabled.",
+        table: {
+            type: {
+                summary: "boolean",
+            },
+        },
+    },
+    id: {
+        description: "An optional id attribute.",
+        control: {type: "text"},
+        table: {
+            type: {
+                summary: "string",
+            },
+        },
+    },
+    testId: {
+        description: "Test ID used for e2e testing.",
+        control: {type: "text"},
+        table: {
+            type: {
+                summary: "string",
+            },
+        },
+    },
+
+    tabIndex: {
+        description: "Set the tabindex attribute on the rendered element.",
+        control: {type: "number", min: -1},
+        table: {
+            type: {
+                summary: "number",
+            },
+        },
+    },
+    style: {
+        description: "Optional custom styles.",
+        table: {
+            category: "Layout",
+            type: {
+                summary: "StyleType",
+            },
+        },
+    },
+    className: {
+        description: "Adds CSS classes to the Button.",
+        control: {type: "text"},
+        table: {
+            category: "Layout",
+            type: {
+                summary: "string",
+            },
+        },
+    },
+    /**
+     * Events
+     */
+    onClick: {
+        action: "clicked",
+        description: `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.
+        `,
+        table: {
+            category: "Events",
+            type: {
+                summary: "(e: SyntheticEvent<>) => mixed",
+                detail: `onClick is optional if href is present, but must be defined if
+                    * href is not`,
+            },
+        },
+    },
+    /**
+     * Navigation
+     */
+    skipClientNav: {
+        description: `Whether to avoid using client-side navigation. If the URL passed to href is local to the client-side, e.g. /math/algebra/eval-exprs, then it tries to use react-router-dom's Link component which handles the client-side navigation. You can set "skipClientNav" to true avoid using client-side nav entirely.`,
+        control: {type: "boolean"},
+        table: {
+            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.",
+            },
+        },
+    },
+    rel: {
+        description: `Specifies the type of relationship between the current document and the linked document. Should only be used when "href" is specified. This defaults to "noopener noreferrer" when target="_blank", but can be overridden by setting this prop to something else.`,
+        control: {type: "text"},
+        table: {
+            category: "Navigation",
+            type: {
+                summary: "string",
+            },
+        },
+    },
+    target: {
+        description: `A target destination window for a link to open in. Should only be used
+        * when "href" is specified.`,
+        control: {type: "text"},
+        table: {
+            category: "Navigation",
+            type: {
+                summary: "string",
+            },
+        },
+    },
+    href: {
+        description: "URL to navigate to.",
+        control: {type: "text"},
+        table: {
+            category: "Navigation",
+            type: {
+                summary: "string",
+                detail: "URL is required when we use `safeWithNav`",
+            },
+        },
+    },
+    beforeNav: {
+        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>",
+            },
+        },
+    },
+    safeWithNav: {
+        description: `Run async code in the background while client-side navigating. If the browser does a full page load navigation, the callback promise must be settled before the navigation will occur. Errors are ignored so that navigation is guaranteed to succeed.`,
+        table: {
+            category: "Navigation",
+            type: {
+                summary: "() => Promise<mixed>",
+            },
+        },
+    },
+    /**
+     * Accessibility
+     */
+    ariaLabel: {
+        name: "aria-label",
+        description: "A label for the button.",
+        table: {
+            category: "Accessibility",
+            type: {
+                summary: "string",
+                detail: `aria-label should be used when spinner={true} to let people using screen readers that the action taken by clicking the button will take some time to complete.`,
+            },
+        },
+    },
+};

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/__tests__/button.test.js

@@ -18,6 +18,17 @@ const keyCodes = {
 };
 
 describe("Button", () => {
+    const {location} = window;
+
+    beforeAll(() => {
+        delete window.location;
+        window.location = {assign: jest.fn()};
+    });
+
+    afterAll(() => {
+        window.location = location;
+    });
+
     test("client-side navigation", () => {
         // Arrange
         const wrapper = mount(

package/src/components/button-core.js

@@ -2,7 +2,7 @@
 import * as React from "react";
 import {StyleSheet} from "aphrodite";
 import {Link} from "react-router-dom";
-import * as PropTypes from "prop-types";
+import {__RouterContext} from "react-router";
 
 import {LabelLarge, LabelSmall} from "@khanacademy/wonder-blocks-typography";
 import Color, {
@@ -30,18 +30,12 @@ type Props = {|
     type?: "submit",
 |};
 
-type ContextTypes = {|
-    router: $FlowFixMe,
-|};
-
 const StyledAnchor = addStyle<"a">("a");
 const StyledButton = addStyle<"button">("button");
 const StyledLink = addStyle<typeof Link>(Link);
 
 export default class ButtonCore extends React.Component<Props> {
-    static contextTypes: ContextTypes = {router: PropTypes.any};
-
-    render(): React.Node {
+    renderInner(router: any): React.Node {
         const {
             children,
             skipClientNav,
@@ -63,7 +57,6 @@ export default class ButtonCore extends React.Component<Props> {
             waiting: _,
             ...restProps
         } = this.props;
-        const {router} = this.context;
 
         const buttonColor =
             color === "destructive"
@@ -176,6 +169,14 @@ export default class ButtonCore extends React.Component<Props> {
             );
         }
     }
+
+    render(): React.Node {
+        return (
+            <__RouterContext.Consumer>
+                {(router) => this.renderInner(router)}
+            </__RouterContext.Consumer>
+        );
+    }
 }
 
 const sharedStyles = StyleSheet.create({

package/src/components/button.js

@@ -1,6 +1,6 @@
 // @flow
 import * as React from "react";
-import * as PropTypes from "prop-types";
+import {__RouterContext} from "react-router";
 
 import {getClickableBehavior} from "@khanacademy/wonder-blocks-clickable";
 import type {AriaProps, StyleType} from "@khanacademy/wonder-blocks-core";
@@ -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
@@ -222,10 +221,6 @@ type Props =
           safeWithNav: () => Promise<mixed>,
       |};
 
-type ContextTypes = {|
-    router: $FlowFixMe,
-|};
-
 type DefaultProps = {|
     color: $PropertyType<Props, "color">,
     kind: $PropertyType<Props, "kind">,
@@ -243,18 +238,19 @@ type DefaultProps = {|
  * `ButtonCore` is a stateless component which displays the different states
  * the `Button` can take.
  *
- * Example usage:
+ * ### Usage
+ *
  * ```jsx
+ * import Button from "@khanacademy/wonder-blocks-button";
+ *
  * <Button
  *     onClick={(e) => console.log("Hello, world!")}
  * >
- *     Label
+ *     Hello, world!
  * </Button>
  * ```
  */
 export default class Button extends React.Component<Props> {
-    static contextTypes: ContextTypes = {router: PropTypes.any};
-
     static defaultProps: DefaultProps = {
         color: "default",
         kind: "primary",
@@ -264,7 +260,7 @@ export default class Button extends React.Component<Props> {
         spinner: false,
     };
 
-    render(): React.Node {
+    renderClickableBehavior(router: any): React.Node {
         const {
             href = undefined,
             type = undefined,
@@ -284,7 +280,7 @@ export default class Button extends React.Component<Props> {
         const ClickableBehavior = getClickableBehavior(
             href,
             skipClientNav,
-            this.context.router,
+            router,
         );
 
         const renderProp = (
@@ -344,4 +340,12 @@ export default class Button extends React.Component<Props> {
             );
         }
     }
+
+    render(): React.Node {
+        return (
+            <__RouterContext.Consumer>
+                {(router) => this.renderClickableBehavior(router)}
+            </__RouterContext.Consumer>
+        );
+    }
 }