@khanacademy/wonder-blocks-clickable 2.1.2

package/src/components/clickable.js

@@ -0,0 +1,388 @@
+// @flow
+import * as React from "react";
+import {StyleSheet} from "aphrodite";
+import * as PropTypes from "prop-types";
+import {Link} from "react-router-dom";
+
+import {addStyle} from "@khanacademy/wonder-blocks-core";
+import type {AriaProps, StyleType} from "@khanacademy/wonder-blocks-core";
+import Color from "@khanacademy/wonder-blocks-color";
+
+import getClickableBehavior from "../util/get-clickable-behavior.js";
+import type {ClickableRole, ClickableState} from "./clickable-behavior.js";
+import {isClientSideUrl} from "../util/is-client-side-url.js";
+
+type CommonProps = {|
+    /**
+     * 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.
+     */
+    ...$Rest<AriaProps, {|"aria-disabled": "true" | "false" | void|}>,
+
+    /**
+     * The child of Clickable must be a function which returns the component
+     * which should be made Clickable.  The function is passed an object with
+     * three boolean properties: hovered, focused, and pressed.
+     */
+    children: (ClickableState) => React.Node,
+
+    /**
+     * An onClick function which Clickable can execute when clicked
+     */
+    onClick?: (e: SyntheticEvent<>) => mixed,
+
+    /**
+     * Optinal href which Clickable should direct to, uses client-side routing
+     * by default if react-router is present
+     */
+    href?: string,
+
+    /**
+     * Styles to apply to the Clickable compoenent
+     */
+    style?: StyleType,
+
+    /**
+     * Adds CSS classes to the Clickable.
+     */
+    className?: string,
+
+    /**
+     * Whether the Clickable is on a dark colored background.
+     * Sets the default focus ring color to white, instead of blue.
+     * Defaults to false.
+     */
+    light: boolean,
+
+    /**
+     * Disables or enables the child; defaults to false
+     */
+    disabled: boolean,
+
+    /**
+     * An optional id attribute.
+     */
+    id?: string,
+
+    /**
+     * 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.
+     */
+    rel?: string,
+
+    /**
+     * The role of the component, can be a role of type ClickableRole
+     */
+    role?: ClickableRole,
+
+    /**
+     * Avoids client-side routing in the presence of the href prop
+     */
+    skipClientNav?: boolean,
+
+    /**
+     * Test ID used for e2e testing.
+     */
+    testId?: string,
+
+    /**
+     * Respond to raw "keydown" event.
+     */
+    onKeyDown?: (e: SyntheticKeyboardEvent<>) => mixed,
+
+    /**
+     * Respond to raw "keyup" event.
+     */
+    onKeyUp?: (e: SyntheticKeyboardEvent<>) => mixed,
+
+    /**
+     * Don't show the default focus ring.  This should be used when implementing
+     * a custom focus ring within your own component that uses Clickable.
+     */
+    hideDefaultFocusRing?: boolean,
+|};
+
+type Props =
+    | {|
+          ...CommonProps,
+
+          /**
+           * A target destination window for a link to open in.
+           */
+          target?: "_blank",
+      |}
+    | {|
+          ...CommonProps,
+
+          href: string,
+
+          /**
+           * 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.
+           */
+          beforeNav: () => Promise<mixed>,
+      |}
+    | {|
+          ...CommonProps,
+
+          href: string,
+
+          /**
+           * 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.
+           */
+          safeWithNav: () => Promise<mixed>,
+
+          /**
+           * A target destination window for a link to open in.
+           */
+          target?: "_blank",
+      |}
+    | {|
+          ...CommonProps,
+
+          href: string,
+
+          /**
+           * 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.
+           */
+          beforeNav: () => Promise<mixed>,
+
+          /**
+           * 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.
+           */
+          safeWithNav: () => Promise<mixed>,
+      |};
+
+type ContextTypes = {|
+    router: $FlowFixMe,
+|};
+
+type DefaultProps = {|
+    light: $PropertyType<Props, "light">,
+    disabled: $PropertyType<Props, "disabled">,
+    "aria-label": $PropertyType<Props, "aria-label">,
+|};
+
+const StyledAnchor = addStyle<"a">("a");
+const StyledButton = addStyle<"button">("button");
+const StyledLink = addStyle<typeof Link>(Link);
+
+/**
+ * A component to turn any custom component into a clickable one.
+ *
+ * Works by wrapping ClickableBehavior around the child element and styling the
+ * child appropriately and encapsulates routing logic which can be customized.
+ * Expects a function which returns an element as it's child.
+ *
+ * Example usage:
+ * ```jsx
+ * <Clickable onClick={() => alert("You clicked me!")}>
+ *     {({hovered, focused, pressed}) =>
+ *         <div
+ *             style={[
+ *                 hovered && styles.hovered,
+ *                 focused && styles.focused,
+ *                 pressed && styles.pressed,
+ *             ]}
+ *         >
+ *             Click Me!
+ *         </div>
+ *     }
+ * </Clickable>
+ * ```
+ */
+export default class Clickable extends React.Component<Props> {
+    static contextTypes: ContextTypes = {router: PropTypes.any};
+
+    static defaultProps: DefaultProps = {
+        light: false,
+        disabled: false,
+        "aria-label": "",
+    };
+
+    getCorrectTag: (
+        clickableState: ClickableState,
+        commonProps: {[string]: any, ...},
+    ) => React.Node = (clickableState, commonProps) => {
+        const activeHref = this.props.href && !this.props.disabled;
+        const useClient =
+            this.context.router &&
+            !this.props.skipClientNav &&
+            isClientSideUrl(this.props.href || "");
+
+        // NOTE: checking this.props.href here is redundant, but flow
+        // needs it to refine this.props.href to a string.
+        if (activeHref && useClient && this.props.href) {
+            return (
+                <StyledLink
+                    {...commonProps}
+                    to={this.props.href}
+                    role={this.props.role}
+                    target={this.props.target || undefined}
+                    aria-disabled={this.props.disabled ? "true" : undefined}
+                >
+                    {this.props.children(clickableState)}
+                </StyledLink>
+            );
+        } else if (activeHref && !useClient) {
+            return (
+                <StyledAnchor
+                    {...commonProps}
+                    href={this.props.href}
+                    role={this.props.role}
+                    target={this.props.target || undefined}
+                    aria-disabled={this.props.disabled ? "true" : undefined}
+                >
+                    {this.props.children(clickableState)}
+                </StyledAnchor>
+            );
+        } else {
+            return (
+                <StyledButton
+                    {...commonProps}
+                    type="button"
+                    disabled={this.props.disabled}
+                >
+                    {this.props.children(clickableState)}
+                </StyledButton>
+            );
+        }
+    };
+
+    render(): React.Node {
+        const {
+            href,
+            onClick,
+            skipClientNav,
+            beforeNav = undefined,
+            safeWithNav = undefined,
+            style,
+            target = undefined,
+            testId,
+            onKeyDown,
+            onKeyUp,
+            hideDefaultFocusRing,
+            light,
+            disabled,
+            ...restProps
+        } = this.props;
+        const ClickableBehavior = getClickableBehavior(
+            href,
+            skipClientNav,
+            this.context.router,
+        );
+
+        const getStyle = (state: ClickableState): StyleType => [
+            styles.reset,
+            styles.link,
+            !hideDefaultFocusRing &&
+                state.focused &&
+                (light ? styles.focusedLight : styles.focused),
+            style,
+        ];
+
+        if (beforeNav) {
+            return (
+                <ClickableBehavior
+                    href={href}
+                    onClick={onClick}
+                    beforeNav={beforeNav}
+                    safeWithNav={safeWithNav}
+                    onKeyDown={onKeyDown}
+                    onKeyUp={onKeyUp}
+                    disabled={disabled}
+                >
+                    {(state, childrenProps) =>
+                        this.getCorrectTag(state, {
+                            ...restProps,
+                            "data-test-id": testId,
+                            style: getStyle(state),
+                            ...childrenProps,
+                        })
+                    }
+                </ClickableBehavior>
+            );
+        } else {
+            return (
+                <ClickableBehavior
+                    href={href}
+                    onClick={onClick}
+                    safeWithNav={safeWithNav}
+                    onKeyDown={onKeyDown}
+                    onKeyUp={onKeyUp}
+                    target={target}
+                    disabled={disabled}
+                >
+                    {(state, childrenProps) =>
+                        this.getCorrectTag(state, {
+                            ...restProps,
+                            "data-test-id": testId,
+                            style: getStyle(state),
+                            ...childrenProps,
+                        })
+                    }
+                </ClickableBehavior>
+            );
+        }
+    }
+}
+
+// Source:  https://gist.github.com/MoOx/9137295
+const styles = StyleSheet.create({
+    reset: {
+        border: "none",
+        margin: 0,
+        padding: 0,
+        width: "auto",
+        overflow: "visible",
+
+        background: "transparent",
+        textDecoration: "none",
+
+        /* inherit font & color from ancestor */
+        color: "inherit",
+        font: "inherit",
+
+        boxSizing: "border-box",
+        // This removes the 300ms click delay on mobile browsers by indicating that
+        // "double-tap to zoom" shouldn't be used on this element.
+        touchAction: "manipulation",
+        userSelect: "none",
+
+        // This is usual frowned upon b/c of accessibility.  We expect users of Clickable
+        // to define their own focus styles.
+        outline: "none",
+
+        /* Normalize `line-height`. Cannot be changed from `normal` in Firefox 4+. */
+        lineHeight: "normal",
+
+        /* Corrects font smoothing for webkit */
+        WebkitFontSmoothing: "inherit",
+        MozOsxFontSmoothing: "inherit",
+    },
+    link: {
+        cursor: "pointer",
+    },
+    focused: {
+        outline: `solid 2px ${Color.blue}`,
+    },
+    focusedLight: {
+        outline: `solid 2px ${Color.white}`,
+    },
+});

package/src/components/clickable.md

@@ -0,0 +1,196 @@
+### Creating a Clickable component
+
+You can make custom components `Clickable` by returning them in a function of the
+`Clickable` child. The eventState parameter the function takes allows access to states
+pressed, hovered and clicked, which you may use to create custom styles.
+
+Clickable has a default focus ring style built-in.  If you are creating your own
+custom focus ring it should be disabled using by setting `hideDefaultFocusRing={true}`
+in the props passed to `Clickable`.
+
+```jsx
+import {StyleSheet} from "aphrodite";
+import Clickable from "@khanacademy/wonder-blocks-clickable";
+import {View} from "@khanacademy/wonder-blocks-core";
+import Color from "@khanacademy/wonder-blocks-color";
+import {Body} from "@khanacademy/wonder-blocks-typography";
+
+const styles = StyleSheet.create({
+    hovered: {
+        textDecoration: "underline",
+        backgroundColor: Color.teal,
+    },
+    pressed: {
+        color: Color.blue,
+    },
+    focused: {
+        outline: `solid 4px ${Color.offBlack64}`,
+    },
+});
+
+<View>
+    <Clickable
+        onClick={() => alert("You clicked some text!")}
+        hideDefaultFocusRing={true}
+        role="tab"
+    >
+        {
+            ({hovered, focused, pressed}) =>
+            <View style={[
+                hovered && styles.hovered,
+                focused && styles.focused,
+                pressed && styles.pressed,
+            ]}>
+                <Body>
+                    This text is clickable!
+                </Body>
+            </View>
+        }
+    </Clickable>
+</View>
+```
+
+Clickable has a `light` prop which changes the default focus ring color to fit a dark background.
+
+```jsx
+import {StyleSheet} from "aphrodite";
+import Clickable from "@khanacademy/wonder-blocks-clickable";
+import {View} from "@khanacademy/wonder-blocks-core";
+import Color from "@khanacademy/wonder-blocks-color";
+import Spacing from "@khanacademy/wonder-blocks-spacing";
+import {Body} from "@khanacademy/wonder-blocks-typography";
+
+const styles = StyleSheet.create({
+    background: {
+        backgroundColor: Color.darkBlue,
+        color: Color.white,
+        padding: Spacing.small_12,
+    },
+    hovered: {
+        textDecoration: "underline",
+        backgroundColor: Color.purple,
+    },
+    pressed: {
+        color: Color.blue,
+    },
+});
+
+<View style={styles.background}>
+    <Clickable
+        onClick={() => alert("You clicked some text!")}
+        role="tab"
+        light={true}
+    >
+        {
+            ({hovered, focused, pressed}) =>
+            <View style={[
+                hovered && styles.hovered,
+                pressed && styles.pressed,
+            ]}>
+                <Body>
+                    This text is clickable!
+                </Body>
+            </View>
+        }
+    </Clickable>
+</View>
+```
+
+### Client-Side routing with Clickable
+
+If your Clickable component is within a React-Router enviroment, your component will automatically default to client-side routing with the `href` prop is set. This behavior can be toggeled by passing the `skipClientNav` prop. In this example we see two Clickable h1 tags, one which employs client-side routing, and the other uses skipClientNav to avoid this default behavior.
+
+```jsx
+import {StyleSheet} from "aphrodite";
+import Clickable from "@khanacademy/wonder-blocks-clickable";
+import {View} from "@khanacademy/wonder-blocks-core";
+import Spacing from "@khanacademy/wonder-blocks-spacing";
+import {MemoryRouter, Route, Switch} from "react-router-dom";
+
+const styles = StyleSheet.create({
+    row: {
+        flexDirection: "row",
+        alignItems: "center",
+    },
+    h1: {
+        marginRight: Spacing.large_24,
+    }
+});
+
+// NOTE: In actual code you would use BrowserRouter instead
+<MemoryRouter>
+    <View style={styles.row}>
+        <Clickable href="/foo" style={styles.h1} onClick={() => console.log("I'm still on the same page!")}>
+            {
+                eventState =>
+                    <h1>
+                        Uses Client-side Nav
+                    </h1>
+            }
+        </Clickable>
+        <Clickable href="/foo" style={styles.h1} skipClientNav>
+            {
+                eventState =>
+                    <h1>
+                        Avoids Client-side Nav
+                    </h1>
+            }
+        </Clickable>
+        <Switch>
+            <Route path="/foo">
+                <View id="foo">Hello, world!</View>
+            </Route>
+        </Switch>
+    </View>
+</MemoryRouter>
+```
+
+### Navigating with the Keyboard
+
+Clickable adds support to keyboard navigation. This way, your components are
+accessible and emulate better the browser's behavior.
+
+*NOTE:* If you want to navigate to an external URL and/or reload the window, make
+sure to use `href` and `skipClientNav={true}`.
+
+```jsx
+import {StyleSheet} from "aphrodite";
+import Clickable from "@khanacademy/wonder-blocks-clickable";
+import {View} from "@khanacademy/wonder-blocks-core";
+import Color from "@khanacademy/wonder-blocks-color";
+import {Body} from "@khanacademy/wonder-blocks-typography";
+
+const styles = StyleSheet.create({
+    hovered: {
+        textDecoration: "underline",
+        backgroundColor: Color.teal,
+    },
+    pressed: {
+        color: Color.blue,
+    },
+    focused: {
+        outline: `solid 4px ${Color.lightBlue}`,
+    },
+});
+
+<View>
+    <Clickable
+        href="https://www.khanacademy.org/about/tos"
+        skipClientNav={true}
+        hideDefaultFocusRing={true}
+    >
+        {
+            ({hovered, focused, pressed}) =>
+            <View style={[
+                hovered && styles.hovered,
+                focused && styles.focused,
+                pressed && styles.pressed,
+            ]}>
+                <Body>
+                    This text should navigate using the keyboard
+                </Body>
+            </View>
+        }
+    </Clickable>
+</View>
+```

package/src/components/clickable.stories.js

@@ -0,0 +1,129 @@
+// @flow
+import * as React from "react";
+
+import {StyleSheet} from "aphrodite";
+import Clickable from "@khanacademy/wonder-blocks-clickable";
+import {View} from "@khanacademy/wonder-blocks-core";
+import Color from "@khanacademy/wonder-blocks-color";
+import {Strut} from "@khanacademy/wonder-blocks-layout";
+import Spacing from "@khanacademy/wonder-blocks-spacing";
+import {Body} from "@khanacademy/wonder-blocks-typography";
+
+import type {StoryComponentType} from "@storybook/react";
+
+export default {
+    title: "Clickable",
+};
+
+export const basic: StoryComponentType = () => (
+    <View>
+        <View style={styles.centerText}>
+            <Clickable
+                href="https://www.khanacademy.org/about/tos"
+                skipClientNav={true}
+            >
+                {({hovered, focused, pressed}) => (
+                    <View
+                        style={[
+                            hovered && styles.hovered,
+                            pressed && styles.pressed,
+                        ]}
+                    >
+                        <Body>This text is clickable!</Body>
+                    </View>
+                )}
+            </Clickable>
+        </View>
+        <Strut size={Spacing.xLarge_32} />
+        <View style={[styles.centerText, styles.dark]}>
+            <Clickable
+                href="https://www.khanacademy.org/about/tos"
+                skipClientNav={true}
+                light={true}
+            >
+                {({hovered, focused, pressed}) => (
+                    <View
+                        style={[
+                            hovered && styles.hovered,
+                            pressed && styles.pressed,
+                        ]}
+                    >
+                        <Body>This text is clickable!</Body>
+                    </View>
+                )}
+            </Clickable>
+        </View>
+    </View>
+);
+
+export const keyboardNavigation: StoryComponentType = () => (
+    <View>
+        <Clickable
+            href="https://www.khanacademy.org/about/tos"
+            skipClientNav={true}
+        >
+            {({hovered, focused, pressed}) => (
+                <View
+                    style={[
+                        hovered && styles.hovered,
+                        focused && styles.focused,
+                        pressed && styles.pressed,
+                    ]}
+                >
+                    <Body>This text should navigate using the keyboard</Body>
+                </View>
+            )}
+        </Clickable>
+    </View>
+);
+
+keyboardNavigation.story = {
+    parameters: {
+        chromatic: {
+            // we don't need screenshots because this story only tests behavior.
+            disable: true,
+        },
+    },
+};
+
+export const keyboardNavigationTab: StoryComponentType = () => (
+    <View>
+        <Clickable role="tab" aria-controls="panel-1" id="tab-1">
+            {({hovered, focused, pressed}) => (
+                <View
+                    style={[
+                        hovered && styles.hovered,
+                        focused && styles.focused,
+                        pressed && styles.pressed,
+                    ]}
+                >
+                    <Body>Open School Info</Body>
+                </View>
+            )}
+        </Clickable>
+        <View id="panel-1" role="tabpanel" tabindex="0" aria-labelledby="tab-1">
+            This is the information for the school.
+        </View>
+    </View>
+);
+
+const styles = StyleSheet.create({
+    hovered: {
+        textDecoration: "underline",
+        backgroundColor: Color.teal,
+    },
+    pressed: {
+        color: Color.blue,
+    },
+    focused: {
+        outline: `solid 4px ${Color.lightBlue}`,
+    },
+    centerText: {
+        textAlign: "center",
+    },
+    dark: {
+        backgroundColor: Color.darkBlue,
+        color: Color.white,
+        padding: Spacing.xSmall_8,
+    },
+});