@khanacademy/wonder-blocks-clickable 2.2.4 → 2.2.7

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

@@ -0,0 +1,237 @@
+export default {
+    children: {
+        description:
+            "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.",
+        control: {
+            type: "text",
+        },
+        type: {
+            required: true,
+        },
+        table: {
+            type: {
+                summary: "(ClickableState) => React.Node",
+            },
+        },
+    },
+    id: {
+        description: "An optional id attribute.",
+        table: {
+            type: {
+                summary: "string",
+            },
+        },
+        control: {
+            type: "text",
+        },
+    },
+    /**
+     * States
+     */
+    light: {
+        description:
+            "Whether the Clickable is on a dark colored background. Sets the default focus ring color to white, instead of blue. Defaults to false.",
+        defaultValue: false,
+        type: {
+            required: true,
+        },
+        table: {
+            category: "States",
+            type: {
+                summary: "boolean",
+            },
+        },
+    },
+    disabled: {
+        description: "Disables or enables the child; defaults to false",
+        defaultValue: false,
+        type: {
+            required: true,
+        },
+        table: {
+            category: "States",
+            type: {
+                summary: "boolean",
+            },
+        },
+    },
+    hideDefaultFocusRing: {
+        description:
+            "Don't show the default focus ring.  This should be used when implementing a custom focus ring within your own component that uses Clickable.",
+        table: {
+            category: "States",
+            type: {
+                summary: "boolean",
+            },
+        },
+    },
+    /**
+     * Styling
+     */
+    className: {
+        description: "Adds CSS classes to the Clickable.",
+        control: {
+            type: "text",
+        },
+        table: {
+            category: "Styling",
+        },
+        type: {
+            summary: "string",
+        },
+    },
+    style: {
+        description: "Optional custom styles.",
+        table: {
+            category: "Styling",
+            type: {
+                summary: "StyleType",
+            },
+        },
+    },
+    /**
+     * Events
+     */
+    onClick: {
+        description:
+            "An onClick function which Clickable can execute when clicked.",
+        table: {
+            category: "Events",
+            type: {
+                summary: "(e: SyntheticEvent<>) => mixed",
+                detail: "`onClick` is optional if `href` is present, but must be defined if `href` is not",
+            },
+        },
+        action: "clicked",
+    },
+    onkeyDown: {
+        description: "Respond to raw `keydown` event.",
+        table: {
+            category: "Events",
+            type: {
+                summary: "(e: SyntheticKeyboardEvent<>) => mixed",
+            },
+        },
+    },
+    onKeyUp: {
+        description: "Respond to raw `keyup` event.",
+        table: {
+            category: "Events",
+            type: {
+                summary: "(e: SyntheticKeyboardEvent<>) => mixed",
+            },
+        },
+    },
+    /**
+     * Navigation
+     */
+    skipClientNav: {
+        description:
+            "Avoids client-side routing in the presence of the `href` prop",
+        defaultValue: false,
+        control: {
+            type: "boolean",
+        },
+        table: {
+            category: "Navigation",
+            type: {
+                summary: "boolean",
+            },
+        },
+    },
+    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:
+            "Optional `href` which `Clickable` should direct to, uses client-side routing by default if react-router is present",
+        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
+     */
+    "aria-label": {
+        description:
+            "A label for the clickable element read by a screen reader.",
+        control: {
+            type: "text",
+        },
+        table: {
+            category: "Accessibility",
+            type: {
+                summary: "string",
+                detail: `aria-label should be used when using
+                graphical elements to let people using screen readers the purpose of the
+                clickable element.`,
+            },
+        },
+    },
+    role: {
+        description:
+            "The role of the component, can be a role of type `ClickableRole`",
+        control: {type: "select"},
+        options: [
+            "button",
+            "checkbox",
+            "link",
+            "listbox",
+            "menu",
+            "menuitem",
+            "radio",
+            "tab",
+        ],
+        table: {
+            category: "Accessibility",
+            type: {
+                summary: "ClickableRole",
+                detail: `"button" | "link" | "checkbox" | "radio" | "listbox" | "option" | "menuitem" | "menu" | "tab"`,
+            },
+        },
+    },
+};

package/src/components/__docs__/clickable.stories.js

@@ -0,0 +1,300 @@
+// @flow
+import * as React from "react";
+
+import {StyleSheet} from "aphrodite";
+import {MemoryRouter, Route, Switch} from "react-router-dom";
+
+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, LabelLarge} from "@khanacademy/wonder-blocks-typography";
+
+import type {StoryComponentType} from "@storybook/react";
+import ComponentInfo from "../../../../../.storybook/components/component-info.js";
+import {name, version} from "../../../package.json";
+import argTypes from "./clickable.argtypes.js";
+
+export default {
+    title: "Clickable / Clickable",
+    component: Clickable,
+    argTypes: argTypes,
+    args: {
+        testId: "",
+        disabled: false,
+        light: false,
+        hideDefaultFocusRing: false,
+    },
+    decorators: [
+        (Story: StoryComponentType): React.Element<typeof View> => (
+            <View style={styles.centerText}>
+                <Story />
+            </View>
+        ),
+    ],
+    parameters: {
+        componentSubtitle: ((
+            <ComponentInfo name={name} version={version} />
+        ): any),
+        docs: {
+            description: {
+                component: null,
+            },
+            source: {
+                // See https://github.com/storybookjs/storybook/issues/12596
+                excludeDecorators: true,
+            },
+        },
+    },
+};
+
+export const Default: StoryComponentType = (args) => (
+    <Clickable {...args}>
+        {({hovered, focused, pressed}) => {
+            return (
+                <View
+                    style={[
+                        styles.clickable,
+                        hovered && styles.hovered,
+                        pressed && styles.pressed,
+                    ]}
+                >
+                    <Body>This text is clickable!</Body>
+                </View>
+            );
+        }}
+    </Clickable>
+);
+
+export const Basic: StoryComponentType = () => (
+    <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>
+);
+
+Basic.parameters = {
+    docs: {
+        description: {
+            story: "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.\n\nClickable 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`.",
+        },
+    },
+    chromatic: {
+        // we don't need screenshots because this story is already covered in
+        // `Default`. We add this story to the `Docs` tab to present the
+        // description above along with the example.
+        disableSnapshot: true,
+    },
+};
+
+/**
+ * Clickable usage on dark backgrounds
+ */
+export const Light: StoryComponentType = () => (
+    <View style={styles.dark}>
+        <Clickable
+            href="https://www.khanacademy.org/about/tos"
+            skipClientNav={true}
+            light={true}
+        >
+            {({hovered, focused, pressed}) => (
+                <View
+                    style={[
+                        styles.clickable,
+                        hovered && styles.hovered,
+                        pressed && styles.pressed,
+                    ]}
+                >
+                    <Body>This text is clickable!</Body>
+                </View>
+            )}
+        </Clickable>
+    </View>
+);
+
+Light.parameters = {
+    chromatic: {
+        // Not needed because the default state doesn't test the disabled
+        // clickable behavior.
+        disableSnapshot: true,
+    },
+    docs: {
+        description: {
+            story: "Clickable has a `light` prop which changes the default focus ring color to fit a dark background.",
+        },
+    },
+    backgrounds: {
+        default: "darkBlue",
+    },
+};
+
+/**
+ * Disabled state
+ */
+export const Disabled: StoryComponentType = (args) => (
+    <>
+        <Clickable onClick={() => {}} {...args}>
+            {({hovered, focused, pressed}) => (
+                <View
+                    style={[
+                        styles.clickable,
+                        hovered && styles.hovered,
+                        pressed && styles.pressed,
+                    ]}
+                >
+                    <Body>
+                        Disabled clickable using the default disabled style
+                    </Body>
+                </View>
+            )}
+        </Clickable>
+        <Clickable onClick={() => {}} {...args}>
+            {({hovered, focused, pressed}) => (
+                <View
+                    style={[
+                        styles.clickable,
+                        hovered && styles.hovered,
+                        pressed && styles.pressed,
+                        args.disabled && styles.disabled,
+                    ]}
+                >
+                    <Body>
+                        Disabled clickable passing custom disabled styles
+                    </Body>
+                </View>
+            )}
+        </Clickable>
+    </>
+);
+
+Disabled.args = {
+    disabled: true,
+};
+
+Disabled.parameters = {
+    docs: {
+        description: {
+            story: "Clickable has a `disabled` prop which prevents the element from being operable. Note that the default disabled style is applied to the element, but you can also pass custom styles to the children element by passing any `disabled` styles (see the second clickable element in the example below).",
+        },
+    },
+};
+
+export const ClientSideNavigation: StoryComponentType = () => (
+    <MemoryRouter>
+        <View>
+            <View style={styles.row}>
+                <Clickable
+                    href="/foo"
+                    style={styles.heading}
+                    onClick={() => {
+                        // eslint-disable-next-line no-console
+                        console.log("I'm still on the same page!");
+                    }}
+                >
+                    {(eventState) => (
+                        <LabelLarge>Uses Client-side Nav</LabelLarge>
+                    )}
+                </Clickable>
+                <Clickable
+                    href="/iframe.html?id=clickable-clickable--default&viewMode=story"
+                    style={styles.heading}
+                    skipClientNav
+                >
+                    {(eventState) => (
+                        <LabelLarge>Avoids Client-side Nav</LabelLarge>
+                    )}
+                </Clickable>
+            </View>
+            <View style={styles.navigation}>
+                <Switch>
+                    <Route path="/foo">
+                        <View id="foo">
+                            The first clickable element does client-side
+                            navigation here.
+                        </View>
+                    </Route>
+                    <Route path="*">See navigation changes here</Route>
+                </Switch>
+            </View>
+        </View>
+    </MemoryRouter>
+);
+
+ClientSideNavigation.storyName = "Client-side Navigation";
+
+ClientSideNavigation.parameters = {
+    docs: {
+        description: {
+            story: "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.",
+        },
+    },
+};
+
+ClientSideNavigation.parameters = {
+    chromatic: {
+        // we don't need screenshots because this story only tests behavior.
+        disableSnapshot: true,
+    },
+    docs: {
+        description: {
+            story:
+                "Clickable adds support to keyboard navigation. This way, your components are accessible and emulate better the browser's behavior.\n\n" +
+                "**NOTE:** If you want to navigate to an external URL and/or reload the window, make sure to use `href` and `skipClientNav={true}`",
+        },
+    },
+};
+
+const styles = StyleSheet.create({
+    clickable: {
+        borderWidth: 1,
+        padding: Spacing.medium_16,
+    },
+    hovered: {
+        textDecoration: "underline",
+        backgroundColor: Color.teal,
+    },
+    pressed: {
+        color: Color.blue,
+    },
+    focused: {
+        outline: `solid 4px ${Color.lightBlue}`,
+    },
+    centerText: {
+        gap: Spacing.medium_16,
+        textAlign: "center",
+    },
+    dark: {
+        backgroundColor: Color.darkBlue,
+        color: Color.white,
+        padding: Spacing.xSmall_8,
+    },
+    row: {
+        flexDirection: "row",
+        alignItems: "center",
+    },
+    heading: {
+        marginRight: Spacing.large_24,
+    },
+    navigation: {
+        border: `1px dashed ${Color.lightBlue}`,
+        marginTop: Spacing.large_24,
+        padding: Spacing.large_24,
+    },
+    disabled: {
+        color: Color.white,
+        backgroundColor: Color.offBlack64,
+    },
+});

package/src/components/clickable-behavior.js

@@ -166,6 +166,7 @@ type Props =
            * A target destination window for a link to open in. Should only be used
            * when `href` is specified.
            */
+          // TODO(WB-1262): only allow this prop when `href` is also set.
           target?: "_blank",
       |}
     | {|
@@ -260,18 +261,19 @@ const startState: ClickableState = {
  * 3. Keyup (spacebar/enter) -> focus state
  *
  * Warning: The event handlers returned (onClick, onMouseEnter, onMouseLeave,
- * onMouseDown, onMouseUp, onDragStart, onTouchStart, onTouchEnd, onTouchCancel, onKeyDown,
- * onKeyUp, onFocus, onBlur, tabIndex) should be passed on to the component
- * that has the ClickableBehavior. You cannot override these handlers without
- * potentially breaking the functionality of ClickableBehavior.
+ * onMouseDown, onMouseUp, onDragStart, onTouchStart, onTouchEnd, onTouchCancel,
+ * onKeyDown, onKeyUp, onFocus, onBlur, tabIndex) should be passed on to the
+ * component that has the ClickableBehavior. You cannot override these handlers
+ * without potentially breaking the functionality of ClickableBehavior.
  *
- * There are internal props triggerOnEnter and triggerOnSpace that can be set
- * to false if one of those keys shouldn't count as a click on this component.
- * Be careful about setting those to false -- make certain that the component
+ * There are internal props triggerOnEnter and triggerOnSpace that can be set to
+ * false if one of those keys shouldn't count as a click on this component. Be
+ * careful about setting those to false -- make certain that the component
  * shouldn't process that key.
  *
- * See [this document](https://docs.google.com/document/d/1DG5Rg2f0cawIL5R8UqnPQpd7pbdObk8OyjO5ryYQmBM/edit#)
- * for a more thorough explanation of expected behaviors and potential cavaets.
+ * See [this
+   document](https://docs.google.com/document/d/1DG5Rg2f0cawIL5R8UqnPQpd7pbdObk8OyjO5ryYQmBM/edit#)
+   for a more thorough explanation of expected behaviors and potential cavaets.
  *
  * `ClickableBehavior` accepts a function as `children` which is passed state
  * and an object containing event handlers and some other props. The `children`
@@ -279,32 +281,30 @@ const startState: ClickableState = {
  *
  * Example:
  *
- * ```js
- * class MyClickableComponent extends React.Component<Props> {
- *     render(): React.Node {
- *         const ClickableBehavior = getClickableBehavior();
- *         return <ClickableBehavior
- *             disabled={this.props.disabled}
- *             onClick={this.props.onClick}
- *         >
- *             {({hovered}, childrenProps) =>
- *                 <RoundRect
- *                      textcolor='white'
- *                      backgroundColor={hovered ? 'red' : 'blue'}}
- *                      {...childrenProps}
- *                 >
- *                      {this.props.children}
- *                 </RoundRect>
- *             }
- *         </ClickableBehavior>
- *     }
+ * ```jsx
+ * function MyClickableComponent(props: Props) {
+ *   const ClickableBehavior = getClickableBehavior();
+ *
+ *   return (
+ *       <ClickableBehavior disabled={props.disabled} onClick={props.onClick}>
+ *           {({hovered}, childrenProps) => (
+ *               <RoundRect
+ *                   textcolor="white"
+ *                   backgroundColor={hovered ? "red" : "blue"}
+ *                   {...childrenProps}
+ *               >
+ *                   {props.children}
+ *               </RoundRect>
+ *           )}
+ *      </ClickableBehavior>
+ *   );
  * }
  * ```
  *
- * This follows a pattern called [Function as Child Components]
- * (https://medium.com/merrickchristensen/function-as-child-components-5f3920a9ace9).
+ * This follows a pattern called [Function as Child
+ * Components](https://medium.com/merrickchristensen/function-as-child-components-5f3920a9ace9).
  *
- * WARNING: Do not use this component directly, use getClickableBehavior
+ * **WARNING:** Do not use this component directly, use getClickableBehavior
  * instead. getClickableBehavior takes three arguments (href, directtNav, and
  * router) and returns either the default ClickableBehavior or a react-router
  * aware version.
@@ -312,9 +312,9 @@ const startState: ClickableState = {
  * The react-router aware version is returned if `router` is a react-router-dom
  * router, `skipClientNav` is not `true`, and `href` is an internal URL.
  *
- * The `router` can be accessed via __RouterContext (imported from 'react-router')
- * from a component rendered as a descendant of a BrowserRouter.
- * See https://reacttraining.com/react-router/web/guides/basic-components.
+ * The `router` can be accessed via __RouterContext (imported from
+   'react-router') from a component rendered as a descendant of a BrowserRouter.
+   See https://reacttraining.com/react-router/web/guides/basic-components.
  */
 export default class ClickableBehavior extends React.Component<
     Props,