@khanacademy/wonder-blocks-cell 1.0.0

package/src/components/__docs__/basic-cell.argtypes.js

@@ -0,0 +1,178 @@
+// @flow
+import * as React from "react";
+import {View} from "@khanacademy/wonder-blocks-core";
+import Icon, {icons} from "@khanacademy/wonder-blocks-icon";
+import {LabelSmall, LabelXSmall} from "@khanacademy/wonder-blocks-typography";
+
+/**
+ * Some pre-defined accessory examples to use in our stories.
+ */
+export const AccessoryMappings = {
+    withContentArticle: ((
+        <Icon icon={icons.contentArticle} size="medium" />
+    ): React.Element<typeof Icon>),
+    withContentVideo: ((
+        <Icon icon={icons.contentVideo} size="medium" />
+    ): React.Element<typeof Icon>),
+    withCaret: (<Icon icon={icons.caretRight} size="medium" />: React.Element<
+        typeof Icon,
+    >),
+    withText: (<LabelSmall>26.3 GB</LabelSmall>: React.Element<
+        typeof LabelSmall,
+    >),
+    withIconText: ((
+        <View style={{alignItems: "center"}}>
+            <Icon icon={icons.info} size="small" />
+            <LabelXSmall>Info</LabelXSmall>
+        </View>
+    ): React.Element<typeof View>),
+    withImage: ((
+        <img src="/avatar.png" alt="ItemAvatar" width={48} height={48} />
+    ): React$Element<"img">),
+};
+
+export default {
+    title: {
+        description:
+            "The title / main content of the cell. You can either provide a string or a Typography component. If a string is provided, typography defaults to `LabelLarge`.",
+        type: {required: true},
+        table: {
+            type: {
+                summary: "TypographyText",
+                detail: "string | React.Element<Typography>",
+            },
+        },
+    },
+    leftAccessory: {
+        description: `If provided, this adds a left accessory to the cell. Left Accessories can be defined using WB components such as Icon, IconButton, or it can even be used for a custom node/component if needed. What ever is passed in will occupy the "LeftAccessory” area of the Cell.`,
+        control: {type: "select"},
+        options: (Object.keys(AccessoryMappings): Array<React.Node>),
+        mapping: AccessoryMappings,
+        table: {
+            category: "Layout",
+            type: {
+                summary: "React.Node",
+                detail: "By default it uses a free width and its default alignment is center (for both vertical and horizontal).",
+            },
+        },
+    },
+    leftAccessoryStyle: {
+        description: `Optional custom styles applied to the leftAccessory wrapper. For example, it can be used to set a custom minWidth or a custom alignment.`,
+        table: {
+            category: "Styling",
+            type: {
+                summary: "AccessoryStyle",
+                detail: "NOTE: leftAccessoryStyle can only be used if leftAccessory is set.",
+            },
+        },
+    },
+    rightAccessory: {
+        description: `If provided, this adds a right accessory to the cell. Right Accessories can be defined using WB components such as Icon, IconButton, or it can even be used for a custom node/component if needed. What ever is passed in will occupy the “RightAccessory” area of the Cell.`,
+        control: {type: "select"},
+        options: (Object.keys(AccessoryMappings): Array<React.Node>),
+        mapping: AccessoryMappings,
+        table: {
+            category: "Layout",
+            type: {
+                summary: "React.Node",
+                detail: "By default it uses a free width and its default alignment is center (for both vertical and horizontal).",
+            },
+        },
+    },
+    rightAccessoryStyle: {
+        description: `Optional custom styles applied to the rightAccessory wrapper. For example, it can be used to set a custom minWidth or a custom alignment.`,
+        table: {
+            category: "Styling",
+            type: {
+                summary: "AccessoryStyle",
+                detail: "NOTE: rightAccessoryStyle can only be used if rightAccessory is set.",
+            },
+        },
+    },
+    horizontalRule: {
+        description:
+            "Adds a horizontal rule at the bottom of the cell that can be used to separate cells within groups such as lists. Defaults to `inset`.",
+        defaultValue: "inset",
+        options: ["inset", "full-width", "none"],
+        control: {type: "select"},
+        table: {
+            category: "Layout",
+            type: {
+                summary: "inset | full-width | none",
+            },
+        },
+    },
+    style: {
+        description: "Optional custom styles.",
+        control: {type: "object"},
+        table: {
+            category: "Styling",
+            type: {
+                summary: "StyleType",
+            },
+        },
+    },
+    testId: {
+        description: "Test ID used for e2e testing.",
+        control: {type: "text"},
+        table: {
+            type: {
+                summary: "string",
+            },
+        },
+    },
+    onClick: {
+        action: "clicked",
+        description: `Called when the cell is clicked.
+        If not provided, the Cell can’t be hovered and/or pressed (highlighted on
+    hover).
+        `,
+        table: {
+            category: "Events",
+            type: {
+                summary: "(e: SyntheticEvent<>) => mixed",
+            },
+        },
+    },
+    disabled: {
+        description: "Whether the cell is disabled.",
+        control: {
+            type: "boolean",
+        },
+        defaultValue: false,
+        table: {
+            type: {
+                summary: "boolean",
+            },
+        },
+    },
+    active: {
+        description: "Whether the cell is active (or currently selected).",
+        control: {
+            type: "boolean",
+        },
+        defaultValue: false,
+        table: {
+            type: {
+                summary: "boolean",
+            },
+        },
+    },
+    /**
+     * Accessibility
+     */
+    ariaLabel: {
+        name: "aria-label",
+        control: {
+            type: "string",
+        },
+        description: "Used to announce the cell's content to screen readers.",
+        table: {
+            category: "Accessibility",
+            type: {
+                summary: "string",
+                detail: `aria-label should be specially used when the cell is pressable so screen readers can announce the link when the user is focused on it.`,
+            },
+        },
+    },
+};

package/src/components/__docs__/basic-cell.stories.js

@@ -0,0 +1,302 @@
+// @flow
+import * as React from "react";
+import {StyleSheet} from "aphrodite";
+
+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 Icon, {icons} from "@khanacademy/wonder-blocks-icon";
+
+import type {StoryComponentType} from "@storybook/react";
+
+import type {IconAsset} from "@khanacademy/wonder-blocks-icon";
+
+import ComponentInfo from "../../../../../.storybook/components/component-info.js";
+import {name, version} from "../../../package.json";
+import BasicCellArgTypes, {AccessoryMappings} from "./basic-cell.argtypes.js";
+
+import BasicCell from "../basic-cell.js";
+
+export default {
+    title: "Cell / BasicCell",
+    component: BasicCell,
+    argTypes: BasicCellArgTypes,
+    parameters: {
+        componentSubtitle: ((
+            <ComponentInfo name={name} version={version} />
+        ): any),
+        docs: {
+            description: {
+                component: null,
+            },
+            source: {
+                // See https://github.com/storybookjs/storybook/issues/12596
+                excludeDecorators: true,
+            },
+        },
+    },
+    decorators: [
+        (Story: any): React.Node => (
+            <View style={styles.example}>{Story()}</View>
+        ),
+    ],
+};
+
+/**
+ * Default BasicCell example. It will be rendered as the first/default story and
+ * it can be interacted with the controls panel in the Browser.
+ */
+const Template = (args) => <BasicCell {...args} />;
+
+export const DefaultBasicCell: StoryComponentType = Template.bind({});
+
+DefaultBasicCell.args = {
+    title: "Basic Cell",
+    rightAccessory: <Icon icon={icons.caretRight} />,
+};
+
+DefaultBasicCell.parameters = {
+    chromatic: {
+        // We have screenshots of other stories that cover other variants.
+        disableSnapshot: true,
+    },
+};
+
+/**
+ * Only including an accessory on the left.
+ */
+export const BasicCellLeft: StoryComponentType = () => (
+    <BasicCell
+        title="Intro to rational & irrational numbers"
+        leftAccessory={<Icon icon={icons.contentArticle} size="medium" />}
+    />
+);
+
+BasicCellLeft.parameters = {
+    docs: {
+        storyDescription:
+            "You can create a minimal cell that only uses a title and an Icon that can be placed on the left or right (or both). In this case, we will place the icon on the left to show you how cell is flexible. Note that you can pass any of the existing WB components such as `Icon`, `IconButton`, `Tooltip`, etc.",
+    },
+};
+
+/**
+ * Only including an accessory on the right.
+ */
+export const BasicCellRight: StoryComponentType = (args) => (
+    <BasicCell
+        title="Intro to rational & irrational numbers"
+        rightAccessory={<Icon icon={icons.caretRight} size="medium" />}
+    />
+);
+
+BasicCellRight.parameters = {
+    docs: {
+        storyDescription:
+            "You can also create a cell with an accessory placed on the right. Note that you can pass any of the existing WB components such as `Icon`.",
+    },
+};
+
+/**
+ * Adding multiline title to verify that the cell's height is correct.
+ */
+export const BasicCellWithDifferentHeights: StoryComponentType = (args) => (
+    <>
+        <BasicCell
+            title="Single line with short accessory."
+            rightAccessory={AccessoryMappings.withCaret}
+        />
+        <Strut size={Spacing.xSmall_8} />
+        <BasicCell
+            title="Single line with tall accessory."
+            rightAccessory={AccessoryMappings.withIconText}
+        />
+        <Strut size={Spacing.xSmall_8} />
+        <BasicCell
+            title="Multi line title with tall accessory. Content should fit within the container and the cell height should be consistent no matter the content length."
+            rightAccessory={AccessoryMappings.withIconText}
+        />
+    </>
+);
+
+BasicCellWithDifferentHeights.parameters = {
+    docs: {
+        storyDescription:
+            "Cells should keep a consistent height no matter the content passed in the title prop. It should also respect a `minHeight` of 48px",
+    },
+};
+
+/**
+ * A BasicCell example adding both accessories (left and right)
+ */
+const calendarIcon: IconAsset = {
+    small: `M14.22 1.6H13.33V0H11.56V1.6H4.44V0H2.67V1.6H1.78C0.79 1.6 0.01 2.32 0.01 3.2L0 14.4C0 15.28 0.79 16 1.78 16H14.22C15.2 16 16 15.28 16 14.4V3.2C16 2.32 15.2 1.6 14.22 1.6ZM14.22 14.4H1.78V5.6H14.22V14.4ZM3.56 7.2H8V11.2H3.56V7.2Z`,
+};
+
+export const BasicCellBoth: StoryComponentType = () => (
+    <BasicCell
+        title="Intro to rational & irrational numbers"
+        leftAccessory={<Icon icon={icons.contentArticle} size="medium" />}
+        rightAccessory={
+            <Icon icon={calendarIcon} size="medium" color={Color.blue} />
+        }
+    />
+);
+
+BasicCellBoth.storyName = "BasicCell with both accessories";
+
+BasicCellBoth.parameters = {
+    docs: {
+        storyDescription:
+            "You can also create a more complex cell with accessories placed on both sides. Note that you can extend the Icon component with custom paths such as the following example.",
+    },
+};
+
+export const BasicCellAccessoryStyles: StoryComponentType = () => (
+    <BasicCell
+        title="BasicCell with custom accessory styles"
+        leftAccessory={<Icon icon={icons.contentArticle} size="medium" />}
+        leftAccessoryStyle={{
+            minWidth: Spacing.xxLarge_48,
+            alignSelf: "flex-start",
+            alignItems: "flex-start",
+        }}
+        rightAccessory={<Icon icon={icons.caretRight} size="small" />}
+        rightAccessoryStyle={{
+            minWidth: Spacing.large_24,
+            alignSelf: "flex-end",
+            alignItems: "flex-end",
+        }}
+    />
+);
+
+BasicCellAccessoryStyles.storyName = "BasicCell accessories with custom styles";
+
+BasicCellAccessoryStyles.parameters = {
+    docs: {
+        storyDescription:
+            "Accessories can also be customized to adapt to different sizes and alignments. In this example, we can see how a cell can be customized for both accessories.",
+    },
+};
+
+/**
+ * Defining horizontal rule variants
+ */
+export const BasicCellHorizontalRules: StoryComponentType = () => (
+    <>
+        <BasicCell
+            title="This is a basic cell with an 'inset' horizontal rule"
+            leftAccessory={<Icon icon={icons.contentArticle} size="medium" />}
+            horizontalRule="inset"
+        />
+        <BasicCell
+            title="This is a basic cell with a 'full-width' horizontal rule"
+            leftAccessory={<Icon icon={icons.contentArticle} size="medium" />}
+            horizontalRule="full-width"
+        />
+        <BasicCell
+            title="This is a basic cell without a horizontal rule"
+            leftAccessory={<Icon icon={icons.contentArticle} size="medium" />}
+            horizontalRule="none"
+        />
+    </>
+);
+
+BasicCellHorizontalRules.storyName = "Defining horizontal rule variants";
+
+BasicCellHorizontalRules.parameters = {
+    docs: {
+        storyDescription:
+            "Cell components can use the `horizontalRule` prop to use a set of predefined variants that we can use to match our needs.",
+    },
+};
+
+export const BasicCellWithCustomStyles: StoryComponentType = () => (
+    <BasicCell
+        title="BasicCell with a darkBlue background"
+        leftAccessory={<Icon icon={icons.contentArticle} size="medium" />}
+        rightAccessory={<Icon icon={calendarIcon} color={Color.white} />}
+        style={{
+            background: Color.darkBlue,
+            color: Color.white,
+        }}
+        onClick={() => {}}
+    />
+);
+
+BasicCellWithCustomStyles.parameters = {
+    docs: {
+        storyDescription:
+            "Cell components can also adapt to different visual needs. One example of this can be done by passing a custom style object to the `style` prop.",
+    },
+};
+
+/*
+ * BasicCell with onClick set
+
+ */
+
+export const ClickableBasicCell: StoryComponentType = () => (
+    <BasicCell
+        title="Intro to rational & irrational numbers"
+        rightAccessory={<Icon icon={icons.caretRight} />}
+        onClick={() => {}}
+        aria-label="Press to navigate to the article"
+    />
+);
+
+ClickableBasicCell.parameters = {
+    chromatic: {
+        // This only includes interactions with the clickable cell, so no need
+        // to capture screenshots.
+        disableSnapshot: true,
+    },
+    docs: {
+        storyDescription:
+            "Cell components can also also be clickable. This is done by passing a `onClick` prop to the component.",
+    },
+};
+
+export const BasicCellActive: StoryComponentType = () => (
+    <BasicCell
+        title="Title for article item"
+        leftAccessory={
+            <Icon icon={icons.contentVideo} size="medium" color="black" />
+        }
+        rightAccessory={<Icon icon={calendarIcon} size="small" />}
+        active={true}
+        onClick={() => {}}
+    />
+);
+
+BasicCellActive.parameters = {
+    docs: {
+        storyDescription:
+            "The cell also supports different states within itself. The different styles are defined internally (e.g hover, focused, pressed, active, disabled) and we allow passing some props to use the `active` or `disabled` state.",
+    },
+};
+
+export const BasicCellDisabled: StoryComponentType = () => (
+    <BasicCell
+        title="Title for article item"
+        leftAccessory={AccessoryMappings.withImage}
+        rightAccessory={<Icon icon={calendarIcon} size="small" />}
+        disabled={true}
+        onClick={() => {}}
+    />
+);
+
+BasicCellDisabled.parameters = {
+    docs: {
+        storyDescription:
+            "In the following example we can see how the `disabled` state works. Note that we apply an opacity to all the elements to make it more apparent that the cell is disabled. This includes text, SVG icons, images, etc.",
+    },
+};
+
+const styles = StyleSheet.create({
+    example: {
+        backgroundColor: Color.offWhite,
+        padding: Spacing.large_24,
+        width: 320 + Spacing.xxLarge_48,
+    },
+});

package/src/components/__docs__/detail-cell.argtypes.js

@@ -0,0 +1,28 @@
+// @flow
+import BasicCellArgTypes from "./basic-cell.argtypes.js";
+
+export default {
+    ...BasicCellArgTypes,
+    subtitle1: {
+        control: {
+            type: "text",
+        },
+        table: {
+            category: "Layout",
+            type: {
+                detail: "string | React.Element<Typography>",
+            },
+        },
+    },
+    subtitle2: {
+        control: {
+            type: "text",
+        },
+        table: {
+            category: "Layout",
+            type: {
+                detail: "string | React.Element<Typography>",
+            },
+        },
+    },
+};

package/src/components/__docs__/detail-cell.stories.js

@@ -0,0 +1,154 @@
+// @flow
+import * as React from "react";
+import {StyleSheet} from "aphrodite";
+
+import {View} from "@khanacademy/wonder-blocks-core";
+import Color from "@khanacademy/wonder-blocks-color";
+import Spacing from "@khanacademy/wonder-blocks-spacing";
+import Icon, {icons} from "@khanacademy/wonder-blocks-icon";
+
+import type {StoryComponentType} from "@storybook/react";
+
+import ComponentInfo from "../../../../../.storybook/components/component-info.js";
+import {name, version} from "../../../package.json";
+import DetailCellArgTypes from "./detail-cell.argtypes.js";
+
+import DetailCell from "../detail-cell.js";
+
+export default {
+    title: "Cell / DetailCell",
+    component: DetailCell,
+    argTypes: DetailCellArgTypes,
+    parameters: {
+        componentSubtitle: ((
+            <ComponentInfo name={name} version={version} />
+        ): any),
+        docs: {
+            description: {
+                component: null,
+            },
+            source: {
+                // See https://github.com/storybookjs/storybook/issues/12596
+                excludeDecorators: true,
+            },
+        },
+    },
+    decorators: [
+        (Story: any): React.Node => (
+            <View style={styles.example}>{Story()}</View>
+        ),
+    ],
+};
+
+/**
+ * Default DetailCell example. It will be rendered as the first/default story and
+ * it can be interacted with the controls panel in the Browser.
+ */
+const Template = (args) => <DetailCell {...args} />;
+
+export const DefaultDetailCell: StoryComponentType = Template.bind({});
+
+DefaultDetailCell.args = {
+    title: "Title for article item",
+    subtitle1: "Subtitle 1 for article item",
+    subtitle2: "Subtitle 2 for article item",
+    leftAccessory: <Icon icon={icons.contentVideo} size="medium" />,
+    rightAccessory: <Icon icon={icons.caretRight} />,
+};
+
+/**
+ * Active detail cell example.
+ */
+export const DetailCellActive: StoryComponentType = () => (
+    <DetailCell
+        title="Title for article item"
+        subtitle1="Subtitle for article item"
+        subtitle2="Subtitle for article item"
+        leftAccessory={<Icon icon={icons.contentVideo} size="medium" />}
+        rightAccessory={<Icon icon={icons.caretRight} size="small" />}
+        active={true}
+    />
+);
+
+DetailCellActive.parameters = {
+    docs: {
+        storyDescription:
+            "For more complex scenarios where we need to use more content such as subtitles, we provide a DetailCell component that can be used to cover these cases. The following example shows how to include a subtitle and use the active state.",
+    },
+};
+
+/**
+ * Disabled detail cell example.
+ */
+export const DetailCellDisabled: StoryComponentType = () => (
+    <DetailCell
+        title="Title for article item"
+        subtitle1="Subtitle for article item"
+        subtitle2="Subtitle for article item"
+        leftAccessory={<Icon icon={icons.contentVideo} size="medium" />}
+        rightAccessory={<Icon icon={icons.caretRight} size="small" />}
+        disabled={true}
+    />
+);
+
+DetailCellDisabled.parameters = {
+    docs: {
+        storyDescription:
+            "For more complex scenarios where we need to use more content such as subtitles, we provide a DetailCell component that can be used to cover these cases. The following example shows how to include a subtitle and use the active state.",
+    },
+};
+
+/**
+ * Using custom styles.
+ */
+export const DetailCellWithCustomStyles: StoryComponentType = () => (
+    <DetailCell
+        title="Title for article item"
+        subtitle1="Subtitle for article item"
+        subtitle2="Subtitle for article item"
+        leftAccessory={<Icon icon={icons.contentVideo} size="medium" />}
+        leftAccessoryStyle={{
+            minWidth: Spacing.xxLarge_48,
+        }}
+        rightAccessory={<Icon icon={icons.caretRight} size="small" />}
+        rightAccessoryStyle={{
+            minWidth: Spacing.medium_16,
+            alignSelf: "flex-end",
+        }}
+    />
+);
+
+DetailCellWithCustomStyles.parameters = {
+    docs: {
+        storyDescription:
+            "Accessories can also be customized to adapt to different sizes and alignments. In this example, we can see how a cell can be customized for both accessories.            ",
+    },
+};
+
+export const ClickableDetailCell: StoryComponentType = () => (
+    <DetailCell
+        title="Title for article item"
+        subtitle1="Subtitle for article item"
+        subtitle2="Subtitle for article item"
+        leftAccessory={<Icon icon={icons.contentVideo} size="medium" />}
+        rightAccessory={<Icon icon={icons.caretRight} />}
+        onClick={() => {}}
+        aria-label="Press to navigate to the article"
+    />
+);
+
+ClickableDetailCell.parameters = {
+    chromatic: {
+        // This only includes interactions with the clickable cell, so no need
+        // to capture screenshots.
+        disableSnapshot: true,
+    },
+};
+
+const styles = StyleSheet.create({
+    example: {
+        backgroundColor: Color.offWhite,
+        padding: Spacing.large_24,
+        width: 376,
+    },
+});