@khanacademy/wonder-blocks-clickable 2.4.4 → 2.4.6

package/src/components/__docs__/accessibility.stories.mdx

@@ -1,152 +0,0 @@
-import {Meta, Story, Canvas} from "@storybook/addon-docs";
-import {StyleSheet} from "aphrodite";
-
-import Clickable from "@khanacademy/wonder-blocks-clickable";
-import Color from "@khanacademy/wonder-blocks-color";
-import {View} from "@khanacademy/wonder-blocks-core";
-import Icon, {icons} from "@khanacademy/wonder-blocks-icon";
-import Spacing from "@khanacademy/wonder-blocks-spacing";
-
-<Meta
-    title="Clickable / Clickable / Accessibility"
-    component={Clickable}
-    parameters={{
-        previewTabs: {
-            canvas: {hidden: true},
-        },
-        viewMode: "docs",
-        chromatic: {
-            // Disables chromatic testing for these stories.
-            disableSnapshot: true,
-        },
-    }}
-/>
-
-# Accessibility
-
-## Keyboard interactions
-
-| Key | Action |
-| --- | --- |
-| Enter or Space | Activates the clickable element |
-
-
-## Roles
-
-| Component | Role | Usage |
-| --- | --- | --- |
-| `<Clickable onClick={} />`  | button | A clickable button element |
-| `<Clickable href="/math" skipClientNav={true} />`  | link | A clickable anchor element |
-| `<Clickable href="/math" />`  | link | A clickable anchor element (using `react-router`'s Link) |
-
-## Attributes
-| Attribute | Usage |
-| --- | --- |
-| tabindex="0" | Includes the clickable element in the tab sequence. |
-| aria-disabled="true" | Indicates that the element is perceivable but disabled. |
-| aria-label="value" | Defines a string value that labels the clickable element. Use it in case the clickable element doesn't include any descriptive text (e.g. Icons, images) |
-
-## Examples
-
-### Labeling
-
-`Clickable` has an `ariaLabel` prop that sets the component's accessible name.
-ariaLabel should be passed when using graphical elements to let screen reader
-users know the purpose of the clickable element.
-
-_NOTE:_ If the clickable element is not graphical, it's best to avoid using `ariaLabel` as the text content of the element itself, which is read by default, should ideally be descriptive enough to not need to manually pass in the label.
-
-This is an example of a component with an accessible label:
-
-<Canvas>
-    <Story name="Labeling">
-        <View>
-            <Clickable onClick={()=>{}} aria-label="More information about this subject">
-                {({hovered, focused, pressed}) => (
-                    <Icon icon={icons.info} />
-                )}
-            </Clickable>
-        </View>
-    </Story>
-</Canvas>
-
-### Disabled state
-
-Clickable does not need an `aria-disabled` attribute, if it also has a
-`disabled` component prop. We internally take care of defining the behavior so
-users can use these type of controls (including Screen Readers). By defining the
-internal behavior we can ensure that the component is accessible via Keyboard
-but not interactable/operatable.
-
-<Canvas>
-    <Story name="Disabled state">
-        <Clickable
-            onClick={(e) => console.log("Hello, world!")}
-            disabled={true}
-        >
-            {({hovered, focused, pressed}) => (
-                "This is a disabled clickable element"
-            )}
-        </Clickable>
-    </Story>
-</Canvas>
-
-### Keyboard navigation
-
-Clickable adds support to keyboard navigation and setting ARIA attributes. 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}.
-
-<Canvas>
-    <Story name="Keyboard navigation">
-        <View>
-            <Clickable role="tab" aria-controls="panel-1" id="tab-1">
-                {({hovered, focused, pressed}) => (
-                    <View
-                        style={[
-                            styles.resting,
-                            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"
-                style={styles.panel}
-            >
-                This is the information for the school.
-            </View>
-        </View>
-    </Story>
-</Canvas>
-
-export const styles = StyleSheet.create({
-    resting: {
-        boxShadow: `inset 0px 0px 1px 1px ${Color.lightBlue}`,
-        padding: Spacing.xSmall_8,
-    },
-    hovered: {
-        textDecoration: "underline",
-        backgroundColor: Color.blue,
-        color: Color.white,
-    },
-    pressed: {
-        color: Color.darkBlue,
-    },
-    focused: {
-        outline: `solid 4px ${Color.lightBlue}`,
-    },
-    panel: {
-        padding: Spacing.medium_16,
-        boxShadow: `inset 0px 0px 0 1px ${Color.offBlack8}`,
-    }
-});

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

@@ -1,64 +0,0 @@
-import clickableArgtypes from "./clickable.argtypes.js";
-
-export default {
-    children: {
-        description:
-            "A function that returns the a React `Element`. The function is passed an object with three boolean properties: hovered, focused, and pressed, and a `childrenProps` argument that contains all the event handlers that should be passed to the React `Element` itself.",
-        type: {
-            required: true,
-        },
-        table: {
-            type: {
-                summary:
-                    "(state: ClickableState, childrenProps: ChildrenProps) => React.Node",
-            },
-        },
-    },
-    tabIndex: {
-        control: {type: "number"},
-        description: `Used to indicate the tab order of an element.
-            Use 0 to make an element focusable, and use -1 to make an
-            element non-focusable via keyboard navigation.`,
-        table: {
-            type: {summary: "number"},
-        },
-    },
-    /**
-     * States
-     */
-    disabled: {
-        ...clickableArgtypes.disabled,
-        description:
-            "Whether the component is disabled.\n\n" +
-            "If the component is disabled, this component will return handlers that do nothing.",
-    },
-    /**
-     * Events
-     */
-    onClick: {
-        ...clickableArgtypes.onClick,
-        description:
-            "An onClick function which ClickableBehavior can execute when clicked.",
-    },
-    onkeyDown: clickableArgtypes.onkeyDown,
-    onKeyUp: clickableArgtypes.onKeyUp,
-    /**
-     * Navigation
-     */
-    skipClientNav: clickableArgtypes.skipClientNav,
-    rel: clickableArgtypes.rel,
-    target: clickableArgtypes.target,
-    href: {
-        ...clickableArgtypes.href,
-        description:
-            "Optional `href` which `ClickableBehavior` should direct to, uses client-side routing by default if react-router is present.\n\n" +
-            "For keyboard navigation, the default is that both an enter and space press would also navigate to this location. See the triggerOnEnter and triggerOnSpace props for more details",
-    },
-    beforeNav: clickableArgtypes.beforeNav,
-    safeWithNav: clickableArgtypes.safeWithNav,
-
-    /**
-     * Accessibility
-     */
-    role: clickableArgtypes.role,
-};

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

@@ -1,178 +0,0 @@
-// @flow
-import * as React from "react";
-import {StyleSheet} from "aphrodite";
-
-import {getClickableBehavior} from "@khanacademy/wonder-blocks-clickable";
-import {View, addStyle} from "@khanacademy/wonder-blocks-core";
-import Color from "@khanacademy/wonder-blocks-color";
-import Spacing from "@khanacademy/wonder-blocks-spacing";
-
-import type {StoryComponentType} from "@storybook/react";
-import ComponentInfo from "../../../../../.storybook/components/component-info.js";
-import {name, version} from "../../../package.json";
-import argTypes from "./clickable-behavior.argtypes.js";
-
-const ClickableBehavior: React.ComponentType<
-    React.ElementConfig<typeof ClickableBehavior>,
-> = getClickableBehavior();
-
-export default {
-    title: "Clickable / ClickableBehavior",
-    component: ClickableBehavior,
-    argTypes: argTypes,
-    args: {
-        disabled: false,
-    },
-    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) => {
-    const ClickableBehavior = getClickableBehavior();
-
-    return (
-        <ClickableBehavior role="button" {...args}>
-            {(state, childrenProps) => {
-                const {pressed, hovered, focused} = state;
-                return (
-                    <View
-                        style={[
-                            styles.clickable,
-                            hovered && styles.hovered,
-                            focused && styles.focused,
-                            pressed && styles.pressed,
-                        ]}
-                        {...childrenProps}
-                    >
-                        This is an element wrapped with ClickableBehavior
-                    </View>
-                );
-            }}
-        </ClickableBehavior>
-    );
-};
-
-Default.parameters = {
-    chromatic: {
-        // we don't need screenshots because this story only displays the
-        // resting/default state.
-        disableSnapshot: true,
-    },
-};
-
-export const WrappingButton: StoryComponentType = (args) => {
-    const ClickableBehavior = getClickableBehavior();
-    const StyledButton = addStyle("button");
-
-    return (
-        <ClickableBehavior {...args}>
-            {(state, childrenProps) => {
-                const {pressed, hovered, focused} = state;
-                return (
-                    <StyledButton
-                        style={[
-                            styles.clickable,
-                            styles.newButton,
-                            hovered && styles.hovered,
-                            focused && styles.focused,
-                            pressed && styles.pressed,
-                        ]}
-                        {...childrenProps}
-                    >
-                        This is an element wrapped with ClickableBehavior
-                    </StyledButton>
-                );
-            }}
-        </ClickableBehavior>
-    );
-};
-
-WrappingButton.parameters = {
-    chromatic: {
-        // we don't need screenshots because this story only displays the
-        // resting/default state.
-        disableSnapshot: true,
-    },
-    docs: {
-        storyDescription: `This is an example of a \`<ClickableBehavior>\`
-            wrapping a button. Since buttons have a built in tabIndex,
-            a tabIndex does not need to be added to \`<ClickableBehavior>\`
-            here.`,
-    },
-};
-
-export const WithTabIndex: StoryComponentType = () => {
-    const ClickableBehavior = getClickableBehavior();
-
-    return (
-        <ClickableBehavior role="button" tabIndex={0}>
-            {(state, childrenProps) => {
-                const {pressed, hovered, focused} = state;
-                return (
-                    <View
-                        style={[
-                            styles.clickable,
-                            hovered && styles.hovered,
-                            focused && styles.focused,
-                            pressed && styles.pressed,
-                        ]}
-                        {...childrenProps}
-                    >
-                        This is an element wrapped with ClickableBehavior
-                    </View>
-                );
-            }}
-        </ClickableBehavior>
-    );
-};
-
-WithTabIndex.parameters = {
-    chromatic: {
-        // we don't need screenshots because this story only displays the
-        // resting/default state.
-        disableSnapshot: true,
-    },
-    docs: {
-        storyDescription: `A \`<ClickableBehavior>\` element does not have
-            a tabIndex by default, as many elements it could wrap may have
-            their own built in tabIndex attribute, such as buttons. If this
-            is not the case, a tabIndex should be passed in using the
-            \`tabIndex\` prop.`,
-    },
-};
-
-const styles = StyleSheet.create({
-    clickable: {
-        cursor: "pointer",
-        padding: Spacing.medium_16,
-        textAlign: "center",
-    },
-    newButton: {
-        border: "none",
-        backgroundColor: Color.white,
-        width: "100%",
-    },
-    hovered: {
-        textDecoration: "underline",
-        backgroundColor: Color.blue,
-        color: Color.white,
-    },
-    pressed: {
-        backgroundColor: Color.darkBlue,
-    },
-    focused: {
-        outline: `solid 4px ${Color.lightBlue}`,
-    },
-});

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

@@ -1,237 +0,0 @@
-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"`,
-            },
-        },
-    },
-};