@khanacademy/wonder-blocks-button 2.11.7 → 3.0.2

package/src/components/button.md

@@ -1,921 +1,5 @@
-### Example: kind
+Documentation for `@khanacademy/wonder-blocks-button` is now in Storybook.
 
-There are three `kind`s of buttons: `"primary"` (default), `"secondary"`, and
-`"tertiary"`:
-```jsx
-import Button from "@khanacademy/wonder-blocks-button";
-import {View} from "@khanacademy/wonder-blocks-core";
-import {StyleSheet} from "aphrodite";
-
-const styles = StyleSheet.create({
-    row: {
-        flexDirection: "row",
-    },
-    button: {
-        marginRight: 10,
-    }
-});
-
-<View style={styles.row}>
-    <Button
-        style={styles.button}
-        onClick={(e) => window.alert("Hello, world!")}
-    >
-        Primary
-    </Button>
-    <Button
-        style={styles.button}
-        onClick={(e) => window.alert("Hello, world!")}
-        kind="secondary"
-    >
-        Secondary
-    </Button>
-    <Button
-        style={styles.button}
-        onClick={(e) => window.alert("Hello, world!")}
-        kind="tertiary"
-    >
-        Tertiary
-    </Button>
-</View>
-```
-
-### Example: color
-
-Buttons have a `color` that is either `"default"` (the default, as shown above) or `"destructive"` (as can seen below):
-
-```jsx
-import Button from "@khanacademy/wonder-blocks-button";
-import {View} from "@khanacademy/wonder-blocks-core";
-import {StyleSheet} from "aphrodite";
-
-const styles = StyleSheet.create({
-    row: {
-        flexDirection: "row",
-    },
-    button: {
-        marginRight: 10,
-    }
-});
-
-<View style={styles.row}>
-    <Button
-        style={styles.button}
-        onClick={(e) => window.alert("Hello, world!")}
-        color="destructive"
-    >
-        Primary
-    </Button>
-    <Button
-        style={styles.button}
-        onClick={(e) => window.alert("Hello, world!")}
-        kind="secondary"
-        color="destructive"
-    >
-        Secondary
-    </Button>
-    <Button
-        style={styles.button}
-        onClick={(e) => window.alert("Hello, world!")}
-        kind="tertiary"
-        color="destructive"
-    >
-        Tertiary
-    </Button>
-</View>
-```
-
-### Example: disabled
-
-Buttons can be `disabled`:
-
-⚠️ Buttons do not need an `aria-disabled` attribute, if it also has a `disabled` attribute.
-Users operating the web page through a screen reader may not be able to fully evaluate the implied
-behaviors of the button element itself.
-
-Links:
-- [Implicit ARIA semantics](https://www.w3.org/TR/wai-aria-1.1/#implicit_semantics)
-- [Document conformance requirements](https://www.w3.org/TR/html-aria/#document-conformance-requirements-for-use-of-aria-attributes-in-html)
-
-
-```jsx
-import Button from "@khanacademy/wonder-blocks-button";
-import {View} from "@khanacademy/wonder-blocks-core";
-import {StyleSheet} from "aphrodite";
-
-const styles = StyleSheet.create({
-    row: {
-        flexDirection: "row",
-    },
-    button: {
-        marginRight: 10,
-    }
-});
-
-<View style={styles.row}>
-    <Button
-        style={styles.button}
-        onClick={(e) => window.alert("Hello, world!")}
-        disabled={true}
-    >
-        Primary
-    </Button>
-    <Button
-        style={styles.button}
-        href={"/foo"}
-        kind="secondary"
-        disabled={true}
-    >
-        Secondary
-    </Button>
-    <Button
-        style={styles.button}
-        onClick={(e) => window.alert("Hello, world!")}
-        kind="tertiary"
-        disabled={true}
-    >
-        Tertiary
-    </Button>
-</View>
-```
-
-### Example: dark
-
-Buttons on a `darkBlue` background should set `light` to `true`.
-```jsx
-import Button from "@khanacademy/wonder-blocks-button";
-import Color from "@khanacademy/wonder-blocks-color";
-import {View} from "@khanacademy/wonder-blocks-core";
-import {StyleSheet} from "aphrodite";
-
-const styles = StyleSheet.create({
-    row: {
-        flexDirection: "row",
-        backgroundColor: Color.darkBlue,
-        padding: 10,
-    },
-    button: {
-        marginRight: 10,
-    }
-});
-
-<View style={styles.row}>
-    <Button
-        light={true}
-        style={styles.button}
-        onClick={(e) => window.alert("Hello, world!")}
-    >
-        Primary
-    </Button>
-    <Button
-        light={true}
-        style={styles.button}
-        onClick={(e) => window.alert("Hello, world!")}
-        kind="secondary"
-    >
-        Secondary
-    </Button>
-    <Button
-        light={true}
-        style={styles.button}
-        onClick={(e) => window.alert("Hello, world!")}
-        kind="tertiary"
-    >
-        Tertiary
-    </Button>
-    <Button
-        light={true}
-        style={styles.button}
-        onClick={(e) => window.alert("Hello, world!")}
-        disabled={true}
-    >
-        Primary
-    </Button>
-    <Button
-        light={true}
-        style={styles.button}
-        onClick={(e) => window.alert("Hello, world!")}
-        kind="secondary"
-        disabled={true}
-    >
-        Secondary
-    </Button>
-    <Button
-        light={true}
-        style={styles.button}
-        onClick={(e) => window.alert("Hello, world!")}
-        kind="tertiary"
-        disabled={true}
-    >
-        Tertiary
-    </Button>
-</View>
-```
-
-### Example: size
-
-Buttons have a `size` that's either `"medium"` (default), `"small"`, or `"xlarge"`.
-```js
-import Button from "@khanacademy/wonder-blocks-button";
-import {View} from "@khanacademy/wonder-blocks-core";
-import {StyleSheet} from "aphrodite";
-
-const styles = StyleSheet.create({
-    row: {
-        flexDirection: "row",
-        marginBottom: 8,
-    },
-    button: {
-        marginRight: 10,
-    }
-});
-
-<View>
-    <View style={styles.row}>
-        <Button
-            style={styles.button}
-            onClick={(e) => window.alert("Hello, world!")}
-            size="small"
-        >
-            Label
-        </Button>
-        <Button
-            style={styles.button}
-            onClick={(e) => window.alert("Hello, world!")}
-            kind="secondary"
-            size="small"
-        >
-            Label
-        </Button>
-        <Button
-            style={styles.button}
-            onClick={(e) => window.alert("Hello, world!")}
-            kind="tertiary"
-            size="small"
-        >
-            Label
-        </Button>
-    </View>
-    <View style={styles.row}>
-        <Button
-            style={styles.button}
-            onClick={(e) => window.alert("Hello, world!")}
-            size="medium"
-        >
-            Label
-        </Button>
-        <Button
-            style={styles.button}
-            onClick={(e) => window.alert("Hello, world!")}
-            kind="secondary"
-            size="medium"
-        >
-            Label
-        </Button>
-        <Button
-            style={styles.button}
-            onClick={(e) => window.alert("Hello, world!")}
-            kind="tertiary"
-            size="medium"
-        >
-            Label
-        </Button>
-    </View>
-    <View style={styles.row}>
-        <Button
-            style={styles.button}
-            onClick={(e) => window.alert("Hello, world!")}
-            size="xlarge"
-        >
-            Label
-        </Button>
-        <Button
-            style={styles.button}
-            onClick={(e) => window.alert("Hello, world!")}
-            kind="secondary"
-            size="xlarge"
-        >
-            Label
-        </Button>
-        <Button
-            style={styles.button}
-            onClick={(e) => window.alert("Hello, world!")}
-            kind="tertiary"
-            size="xlarge"
-        >
-            Label
-        </Button>
-    </View>
-</View>
-```
-
-### 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.
-While the `spinner` property is set to `true` the button is disabled.
-
-```jsx
-import Button from "@khanacademy/wonder-blocks-button";
-import {View} from "@khanacademy/wonder-blocks-core";
-import {StyleSheet} from "aphrodite";
-
-const styles = StyleSheet.create({
-    row: {
-        flexDirection: "row",
-        alignItems: "center",
-    },
-    button: {
-        marginRight: 10,
-    }
-});
-
-<View style={styles.row}>
-    <Button spinner={true} aria-label="loading" size="xlarge" style={styles.button}>
-        Click me!
-    </Button>
-    <Button spinner={true} aria-label="loading" style={styles.button} href="/foo">
-        Click me!
-    </Button>
-    <Button spinner={true} aria-label="loading" size="small" style={styles.button}>
-        Click me!
-    </Button>
-</View>
-```
-
-### Example: Navigation
-
-```jsx
-import Button from "@khanacademy/wonder-blocks-button";
-import {View} from "@khanacademy/wonder-blocks-core";
-import {StyleSheet} from "aphrodite";
-
-const styles = StyleSheet.create({
-    row: {
-        flexDirection: "row",
-    },
-    button: {
-        marginRight: 10,
-    }
-});
-
-<View style={styles.row}>
-    <Button
-        href="#button-1"
-        style={styles.button}
-    >
-        href
-    </Button>
-    <Button
-        kind="secondary"
-        onClick={(e) => window.alert("Hello, world!")}
-        style={styles.button}
-    >
-        onClick
-    </Button>
-    <Button
-        kind="tertiary"
-        href="#button-1"
-        onClick={(e) => window.alert("Hello, world!")}
-        style={styles.button}
-    >
-        both
-    </Button>
-</View>
-```
-
-### Example: Navigation with React Router
-
-Buttons do client-side navigation by default, if React Router exists:
-```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}>
-            Uses Client-side Nav
-        </Button>
-        <Button  href="/foo" style={styles.button} skipClientNav>
-            Avoids Client-side Nav
-        </Button>
-        <Switch>
-            <Route path="/foo">
-                <View id="foo">Hello, world!</View>
-            </Route>
-        </Switch>
-    </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.
-
-```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}
-            beforeNav={() => new Promise((resolve, reject) => {
-                setTimeout(resolve, 1000);
-            })}
-        >
-            beforeNav, client-side nav
-        </Button>
-        <Button
-            href="/foo"
-            style={styles.button}
-            skipClientNav={true}
-            beforeNav={() => new Promise((resolve, reject) => {
-                setTimeout(resolve, 1000);
-            })}
-        >
-            beforeNav, server-side nav
-        </Button>
-        <Button
-            href="https://google.com"
-            target="_blank"
-            style={styles.button}
-            skipClientNav={true}
-            beforeNav={() => new Promise((resolve, reject) => {
-                setTimeout(resolve, 1000);
-            })}
-        >
-            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">
-                <View id="foo">Hello, world!</View>
-            </Route>
-        </Switch>
-    </View>
-</MemoryRouter>
-```
-
-### Example: Prevent navigation by calling e.preventDefault()
-
-If the `onClick` callback calls `preventDefault()`, then navigation
-will not occur.
-
-```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}
-            onClick={e => e.preventDefault()}
-        >
-            This button prevents navigation.
-        </Button>
-        <Switch>
-            <Route path="/foo">
-                <View id="foo">Hello, world!</View>
-            </Route>
-        </Switch>
-    </View>
-</MemoryRouter>
-```
-
-### Example: style
-
-Buttons can have a `style` props which supports width, position, margin,
-and flex styles.
-
-Buttons can have an icon on it's left side.
-
-```jsx
-import Button from "@khanacademy/wonder-blocks-button";
-import {View} from "@khanacademy/wonder-blocks-core";
-import {StyleSheet} from "aphrodite";
-import {icons} from "@khanacademy/wonder-blocks-icon";
-
-const styles = StyleSheet.create({
-    row: {
-        flexDirection: "row",
-        marginBottom: 10,
-    },
-    button: {
-        marginRight: 10,
-    },
-});
-
-const kinds = ["primary", "secondary", "tertiary"];
-
-<View>
-    <View style={styles.row}>
-        {
-            kinds.map((kind, idx) => (
-                <Button
-                    kind={kind}
-                    icon={icons.contentExercise}
-                    style={styles.button}
-                    key={idx}
-                >
-                    {kind}
-                </Button>
-            ))
-        }
-    </View>
-    <View style={styles.row}>
-        {
-            kinds.map((kind, idx) => (
-                <Button
-                    kind={kind}
-                    icon={icons.contentExercise}
-                    style={styles.button}
-                    key={idx}
-                    size="small"
-                >
-                    {kind} small
-                </Button>
-            ))
-        }
-    </View>
-</View>
-```
-
-### Example: "submit" buttons in forms
-
-```jsx
-import Button from "@khanacademy/wonder-blocks-button";
-import {View} from "@khanacademy/wonder-blocks-core";
-
-<View>
-    <form onSubmit={() => alert("the form was submitted")}>
-        <Button type="submit">Submit</Button>
-    </form>
-</View>
-```
-
-### Best Practices
-
-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.
-
-```jsx
-import Button from "@khanacademy/wonder-blocks-button";
-import {View} from "@khanacademy/wonder-blocks-core";
-
-<View>
-    <Button>
-        Label
-    </Button>
-</View>
-```
-
-This can be corrected by applying appropriate flex styles to the container.
-
-```jsx
-import Button from "@khanacademy/wonder-blocks-button";
-import {View} from "@khanacademy/wonder-blocks-core";
-import {StyleSheet} from "aphrodite";
-
-const styles = StyleSheet.create({
-    column: {
-        alignItems: "flex-start",
-    },
-    row: {
-        flexDirection: "row",
-    },
-    gap: {
-        height: 16,
-    },
-    button: {
-        marginRight: 10,
-    },
-});
-
-<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>
-```
-
-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.
-```jsx
-import Button from "@khanacademy/wonder-blocks-button";
-import {View} from "@khanacademy/wonder-blocks-core";
-import {StyleSheet} from "aphrodite";
-
-const styles = StyleSheet.create({
-    row: {
-        flexDirection: "row",
-    },
-    gap: {
-        height: 16,
-    },
-    button: {
-        marginRight: 10,
-        minWidth: 144,
-    },
-});
-
-<View style={styles.row}>
-    <Button
-        style={styles.button}
-        kind="secondary"
-    >
-        label
-    </Button>
-    <Button
-        style={styles.button}
-    >
-        label in a different language
-    </Button>
-</View>
-```
-
-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.
-```jsx
-import Button from "@khanacademy/wonder-blocks-button";
-import {View} from "@khanacademy/wonder-blocks-core";
-import {StyleSheet} from "aphrodite";
-
-const styles = StyleSheet.create({
-    row: {
-        flexDirection: "row",
-        width: 300,
-    },
-    gap: {
-        height: 16,
-    },
-    button: {
-        marginRight: 10,
-        minWidth: 144,
-    },
-});
-
-<View style={styles.row}>
-    <Button
-        style={styles.button}
-        kind="secondary"
-    >
-        label
-    </Button>
-    <Button
-        style={styles.button}
-    >
-        label too long for the parent container
-    </Button>
-</View>
-```
-
-Only one button in a layout should be `primary`.
-```jsx
-import Button from "@khanacademy/wonder-blocks-button";
-import {View} from "@khanacademy/wonder-blocks-core";
-import {StyleSheet} from "aphrodite";
-
-const styles = StyleSheet.create({
-    row: {
-        flexDirection: "row",
-    },
-    button: {
-        marginRight: 10,
-    },
-});
-
-<View>
-    <View style={styles.row}>
-        <Button
-            style={styles.button}
-            kind="tertiary"
-        >
-            Tertiary
-        </Button>
-        <Button
-            style={styles.badButton}
-        >
-            Primary
-        </Button>
-    </View>
-</View>
-```
-
-When an action is going to take a while, show a spinner during that time.
-
-```jsx
-import Button from "@khanacademy/wonder-blocks-button";
-import {View} from "@khanacademy/wonder-blocks-core";
-import {StyleSheet} from "aphrodite";
-
-const styles = StyleSheet.create({
-    row: {
-        flexDirection: "row",
-    },
-    button: {
-        marginRight: 10,
-    },
-});
-
-class Example extends React.Component {
-    constructor(props) {
-        super(props);
-        this.state = {
-            waiting: false,
-        }
-    }
-
-    componentWillUnmount() {
-        this.timeout && this.timeout.clear();
-    }
-
-    handleClick() {
-        this.setState({waiting: true});
-        this.timeout = setTimeout(() => {
-            this.setState({waiting: false});
-        }, 2000);
-    }
-
-    render() {
-        return <View style={styles.row}>
-            <Button
-                spinner={this.state.waiting}
-                aria-label={this.state.waiting ? "waiting" : ""}
-                onClick={() => this.handleClick()}
-            >
-                Click me!
-            </Button>
-        </View>
-    }
-}
-
-<Example />
-```
+Either run `yarn start:storybook` locally, or visit the docs for the `main`
+branch on [GitHub
+Pages](https://khan.github.io/wonder-blocks/?path=/docs/button--default).