@khanacademy/wonder-blocks-link 3.8.17 → 3.9.0

package/src/__tests__/custom-snapshot.test.js

@@ -43,35 +43,38 @@ describe("LinkCore", () => {
     for (const kind of ["primary", "secondary"]) {
         for (const href of ["#", "#non-existent-link"]) {
             for (const light of kind === "primary" ? [true, false] : [false]) {
-                for (const visitable of kind === "primary" && !light
+                for (const visitable of kind === "primary"
                     ? [true, false]
                     : [false]) {
-                    for (const state of ["focused", "hovered", "pressed"]) {
-                        const stateProps = {
-                            focused: state === "focused",
-                            hovered: state === "hovered",
-                            pressed: state === "pressed",
-                            waiting: false,
-                        };
-                        test(`kind:${kind} href:${href} light:${String(
-                            light,
-                        )} visitable:${String(visitable)} ${state}`, () => {
-                            const tree = renderer
-                                .create(
-                                    <LinkCore
-                                        href="#"
-                                        kind={kind}
-                                        light={light}
-                                        visitable={visitable}
-                                        {...stateProps}
-                                        {...defaultHandlers}
-                                    >
-                                        Click me
-                                    </LinkCore>,
-                                )
-                                .toJSON();
-                            expect(tree).toMatchSnapshot();
-                        });
+                    for (const inline of [true, false]) {
+                        for (const state of ["focused", "hovered", "pressed"]) {
+                            const stateProps = {
+                                focused: state === "focused",
+                                hovered: state === "hovered",
+                                pressed: state === "pressed",
+                                waiting: false,
+                            };
+                            test(`kind:${kind} href:${href} light:${String(
+                                light,
+                            )} visitable:${String(visitable)} ${state}`, () => {
+                                const tree = renderer
+                                    .create(
+                                        <LinkCore
+                                            href="#"
+                                            inline={inline}
+                                            kind={kind}
+                                            light={light}
+                                            visitable={visitable}
+                                            {...stateProps}
+                                            {...defaultHandlers}
+                                        >
+                                            Click me
+                                        </LinkCore>,
+                                    )
+                                    .toJSON();
+                                expect(tree).toMatchSnapshot();
+                            });
+                        }
                     }
                 }
             }

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

@@ -20,6 +20,14 @@ export default {
         table: {type: {summary: "string"}},
         type: {required: false},
     },
+    inline: {
+        control: {type: "boolean"},
+        description: `Indicates that this link is used within a body of text.
+            This styles the link with an underline to distinguish it
+            from surrounding text.`,
+        table: {type: {summary: "boolean"}},
+        type: {required: false},
+    },
     kind: {
         control: {type: "select"},
         description:

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

@@ -1,10 +1,16 @@
+// We need to use fireEvent for mouseDown in these tests, none of the userEvent
+// alternatives work. Click includes mouseUp, which removes the pressed style.
+/* eslint-disable testing-library/prefer-user-event */
 // @flow
+import {expect} from "@storybook/jest";
 import * as React from "react";
+import {within, userEvent, fireEvent} from "@storybook/testing-library";
 import {StyleSheet} from "aphrodite";
 import {MemoryRouter, Route, Switch} from "react-router-dom";
 
 import Color from "@khanacademy/wonder-blocks-color";
 import {View} from "@khanacademy/wonder-blocks-core";
+import {Strut} from "@khanacademy/wonder-blocks-layout";
 import Link from "@khanacademy/wonder-blocks-link";
 import Spacing from "@khanacademy/wonder-blocks-spacing";
 import {
@@ -29,6 +35,9 @@ export default {
     argTypes: LinkArgTypes,
 };
 
+const activeBlue = "#1b50b3";
+const fadedBlue = "#b5cefb";
+
 export const Default: StoryComponentType = (args) => (
     <Link target="_blank" {...args} />
 );
@@ -38,61 +47,324 @@ Default.args = {
     children: "Hello, world!",
 };
 
-export const Basic: StoryComponentType = () => (
-    <Link href="#">Hello, world!</Link>
+export const Primary: StoryComponentType = () => (
+    <Link href="#">The quick brown fox jumps over the lazy dog.</Link>
 );
 
-Basic.parameters = {
+Primary.parameters = {
     docs: {
         storyDescription: `Minimal link usage.
             This links to the top of the page.`,
     },
 };
 
-export const Variants: StoryComponentType = () => (
+Primary.play = async ({canvasElement}) => {
+    const canvas = within(canvasElement);
+
+    const link = canvas.getByRole("link");
+
+    await expect(link).toHaveStyle(`color: ${Color.blue}`);
+
+    await userEvent.hover(link);
+    await expect(link).toHaveStyle(
+        `text-decoration: underline ${Color.blue} dashed 2px`,
+    );
+
+    await fireEvent.mouseDown(link);
+    await expect(link).toHaveStyle(
+        `text-decoration: underline solid ${activeBlue} 1px`,
+    );
+};
+
+export const Secondary: StoryComponentType = () => (
+    <Link href="#" kind="secondary">
+        The quick brown fox jumps over the lazy dog.
+    </Link>
+);
+
+Secondary.parameters = {
+    docs: {
+        storyDescription: `Minimal secondary link usage. A secondary link
+            has lighter text. This links to the top of the page.`,
+    },
+};
+
+Secondary.play = async ({canvasElement}) => {
+    const canvas = within(canvasElement);
+
+    const link = canvas.getByRole("link");
+
+    await expect(link).toHaveStyle(`color: ${Color.offBlack64}`);
+
+    await userEvent.hover(link);
+    await expect(link).toHaveStyle(
+        `text-decoration: underline ${Color.offBlack64} dashed 2px`,
+    );
+
+    await fireEvent.mouseDown(link);
+    await expect(link).toHaveStyle(
+        `text-decoration: underline solid ${Color.offBlack} 1px`,
+    );
+};
+
+export const Visitable: StoryComponentType = () => (
+    <Link href="#" visitable={true}>
+        The quick brown fox jumps over the lazy dog.
+    </Link>
+);
+
+Visitable.parameters = {
+    docs: {
+        storyDescription: `This is a visitable link. It changes color after
+            it has been clicked on to indicate that it's been visited before.
+            This link's \`visitable\` prop is set to true.
+            It links to the top of the page.`,
+    },
+};
+
+export const LightPrimary: StoryComponentType = () => (
+    <Link href="#" light={true}>
+        The quick brown fox jumps over the lazy dog.
+    </Link>
+);
+
+LightPrimary.parameters = {
+    docs: {
+        storyDescription: `Minimal link usage on a dark background. This
+            link has its \`light\` prop set to true. It links to the top
+            of the page.`,
+    },
+    backgrounds: {
+        default: "darkBlue",
+    },
+};
+
+LightPrimary.play = async ({canvasElement}) => {
+    const canvas = within(canvasElement);
+
+    const link = canvas.getByRole("link");
+
+    await userEvent.hover(link);
+    await expect(link).toHaveStyle(
+        `text-decoration: underline ${Color.white} dashed 2px`,
+    );
+
+    await fireEvent.mouseDown(link);
+    await expect(link).toHaveStyle(
+        `text-decoration: underline solid ${fadedBlue} 1px`,
+    );
+};
+
+export const LightVisitable: StoryComponentType = () => (
+    <Link href="#" light={true} visitable={true}>
+        The quick brown fox jumps over the lazy dog.
+    </Link>
+);
+
+LightVisitable.parameters = {
+    backgrounds: {
+        default: "darkBlue",
+    },
+    docs: {
+        storyDescription: `This is a visitable link on a dark background.
+            It changes color after it has been clicked on to indicate
+            that it's been visited before. This link's \`visitable\` prop
+            is set to true. It links to the top of the page.`,
+    },
+};
+
+export const Inline: StoryComponentType = () => (
     <Body>
-        I am a <Link href="#nonexistent-link">Primary Link</Link>.{" "}
-        <span style={{color: Color.offBlack64}}>
-            My friend the{" "}
-            <Link href="#secondary-nonexistent-link" kind="secondary">
-                Secondary Link
-            </Link>{" "}
-            is used here with a lighter text.
-        </span>{" "}
-        We also have a{" "}
-        <Link href="#" visitable={true}>
-            Visitable Primary Link
-        </Link>{" "}
-        friend.
+        This is an inline{" "}
+        <Link href="#" inline={true}>
+            Primary link
+        </Link>
+        , whereas this is an inline{" "}
+        <Link href="#" kind="secondary" inline={true}>
+            Secondary link
+        </Link>
+        , and this is an inline{" "}
+        <Link href="#" visitable={true} inline={true}>
+            Visitable link (Primary only)
+        </Link>
+        .
     </Body>
 );
 
-Variants.parameters = {
+Inline.parameters = {
     docs: {
-        storyDescription: `Primary links are blue, secondary links are black,
-            and visitable links turn purple after they've been clicked on.`,
+        storyDescription: `Inline links include an underline to distinguish
+            them from the surrounding text. Make a link inline by setting the
+            \`inline\` prop to \`true\`. It is recommended to use inline
+            links within paragraphs and sentences.`,
     },
 };
 
-export const LightVariants: StoryComponentType = () => (
-    <Body style={styles.darkBackground}>
-        I am a{" "}
-        <Link href="#dark-link" light={true}>
-            Primary Link
-        </Link>{" "}
-        used on a dark background. My friend the Secondary Link is not supported
-        on this dark background.
+Inline.play = async ({canvasElement}) => {
+    const canvas = within(canvasElement);
+
+    const primaryLink = canvas.getByText("Primary link");
+    const secondaryLink = canvas.getByText("Secondary link");
+
+    // Primary link styles
+    await expect(primaryLink).toHaveStyle(`color: ${Color.blue}`);
+
+    await userEvent.hover(primaryLink);
+    await expect(primaryLink).toHaveStyle(
+        `text-decoration: underline ${Color.blue} dashed 2px`,
+    );
+
+    await fireEvent.mouseDown(primaryLink);
+    await expect(primaryLink).toHaveStyle(
+        `text-decoration: underline solid ${activeBlue} 1px`,
+    );
+
+    // Secondary link styles
+    await expect(secondaryLink).toHaveStyle(`color: ${Color.offBlack}`);
+
+    await userEvent.hover(secondaryLink);
+    await expect(secondaryLink).toHaveStyle(
+        `text-decoration: underline ${Color.offBlack} dashed 2px`,
+    );
+
+    await fireEvent.mouseDown(secondaryLink);
+    await expect(secondaryLink).toHaveStyle(
+        `text-decoration: underline solid ${activeBlue} 1px`,
+    );
+};
+
+export const InlineLight: StoryComponentType = () => (
+    <Body style={{color: Color.white}}>
+        This is an inline{" "}
+        <Link href="#" inline={true} light={true}>
+            Primary link
+        </Link>
+        , whereas this is an inline{" "}
+        <Link href="#" visitable={true} inline={true} light={true}>
+            Visitable link (Primary only)
+        </Link>
+        . Secondary light links are not supported.
     </Body>
 );
 
-LightVariants.parameters = {
+InlineLight.parameters = {
+    backgrounds: {
+        default: "darkBlue",
+    },
+    docs: {
+        storyDescription: `Inline links include an underline to distinguish
+            them from the surrounding text. If the link is on a
+            dark background, set the \`light\` prop to true for it to
+            be appropriately visible.\n\n**NOTE:** Secondary light links are
+            not supported.`,
+    },
+};
+
+InlineLight.play = async ({canvasElement}) => {
+    const canvas = within(canvasElement);
+
+    const primaryLink = canvas.getByText("Primary link");
+
+    await expect(primaryLink).toHaveStyle(`color: ${Color.white}`);
+
+    await userEvent.hover(primaryLink);
+    await expect(primaryLink).toHaveStyle(
+        `text-decoration: underline ${Color.white} dashed 2px`,
+    );
+
+    await fireEvent.mouseDown(primaryLink);
+    await expect(primaryLink).toHaveStyle(
+        `text-decoration: underline solid ${fadedBlue} 1px`,
+    );
+};
+
+export const Variants: StoryComponentType = () => (
+    <View>
+        {/* Default (dark) */}
+        <View style={{padding: Spacing.large_24}}>
+            {/* Standalone */}
+            <View>
+                <View style={styles.standaloneLinkWrapper}>
+                    <Link href="#nonexistent-link">
+                        Standalone Primary Link
+                    </Link>
+                </View>
+                <View style={styles.standaloneLinkWrapper}>
+                    <Link href="#secondary-nonexistent-link" kind="secondary">
+                        Standalone Secondary Link
+                    </Link>
+                </View>
+                <View style={styles.standaloneLinkWrapper}>
+                    <Link href="#" visitable={true}>
+                        Standalone Visitable Link (Primary only)
+                    </Link>
+                </View>
+            </View>
+            <Strut size={Spacing.xSmall_8} />
+            {/* Inline */}
+            <Body>
+                This is an{" "}
+                <Link href="#" inline={true}>
+                    Inline Primary link
+                </Link>
+                , whereas this is an{" "}
+                <Link href="#" kind="secondary" inline={true}>
+                    Inline Secondary link
+                </Link>
+                , and this is an{" "}
+                <Link href="#" visitable={true} inline={true}>
+                    Inline Visitable link (Primary only)
+                </Link>
+                .
+            </Body>
+        </View>
+        {/* Light */}
+        <View
+            style={{
+                backgroundColor: Color.darkBlue,
+                padding: Spacing.large_24,
+            }}
+        >
+            {/* Standalone */}
+            <View>
+                <View style={styles.standaloneLinkWrapper}>
+                    <Link href="#nonexistent-link" light={true}>
+                        Standalone Light Link (Primary only)
+                    </Link>
+                </View>
+                <View style={styles.standaloneLinkWrapper}>
+                    <Link href="#" visitable={true} light={true}>
+                        Standalone Light Visitable Link (Primary only)
+                    </Link>
+                </View>
+            </View>
+            <Strut size={Spacing.xSmall_8} />
+            {/* Inline */}
+            <Body style={{color: Color.white}}>
+                This is an{" "}
+                <Link href="#" inline={true} light={true}>
+                    Inline Primary link
+                </Link>
+                , whereas this is an{" "}
+                <Link href="#" visitable={true} inline={true} light={true}>
+                    Inline Visitable link (Primary only)
+                </Link>
+                . Secondary light links are not supported.
+            </Body>
+        </View>
+    </View>
+);
+
+Variants.parameters = {
     docs: {
-        storyDescription: `Links are white on a dark background when the
-            \`light\` prop is true. Secondary \`light\` links are not supported.
-            Links also cannot be \`visitable\` if they're \`light\`. If
-            a link has \`light\` set to \`true\` and you try to set \`kind\`
-            to \`"secondary"\` or \`visitable\` to \`true\`, it will throw
-            an error.`,
+        storyDescription: `By default, primary links are blue, secondary
+            links are gray, and visitable links turn purple after they've
+            been clicked on. Default inline links are underlined, and the
+            secondary kind is black to match surrounding text color.
+            Light standalone and inline links have the same colors - white
+            with visited visitable links being pink. Light inline links are
+            also underlined like default inline links. Light secondary links
+            are not supported and will result in an error.`,
     },
 };
 
@@ -110,6 +382,17 @@ WithTypography.parameters = {
     },
 };
 
+WithTypography.play = async ({canvasElement}) => {
+    const canvas = within(canvasElement);
+
+    const heading = canvas.getByText("Heading inside a Link element");
+
+    // Confirm that the default font size (16px) and line height (22px)
+    // are successfully overridden by typography.
+    await expect(heading).toHaveStyle("font-size: 20px");
+    await expect(heading).toHaveStyle("lineHeight: 24px");
+};
+
 export const WithStyle: StoryComponentType = () => (
     <Link href="#" style={styles.pinkLink}>
         This link has a style.
@@ -176,7 +459,7 @@ Navigation.parameters = {
 const styles = StyleSheet.create({
     darkBackground: {
         backgroundColor: Color.darkBlue,
-        color: Color.white64,
+        color: Color.white,
         padding: 10,
     },
     heading: {
@@ -194,4 +477,11 @@ const styles = StyleSheet.create({
         flexDirection: "row",
         alignItems: "center",
     },
+    standaloneLinkWrapper: {
+        // Use inline-block so the outline wraps only the text
+        // instead of taking the full width of the parent
+        // container.
+        display: "inline-block",
+        marginBottom: Spacing.xSmall_8,
+    },
 });

package/src/components/__tests__/link.test.js

@@ -4,6 +4,8 @@ import {MemoryRouter, Route, Switch} from "react-router-dom";
 import {fireEvent, render, screen, waitFor} from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
+import Color from "@khanacademy/wonder-blocks-color";
+
 import Link from "../link.js";
 
 describe("Link", () => {
@@ -332,4 +334,104 @@ describe("Link", () => {
             expect(keyCode).toEqual(32);
         });
     });
+
+    describe("focus style", () => {
+        test("blue outline around primary links on focus", () => {
+            // Arrange
+            render(<Link href="/">Click me!</Link>);
+
+            // Act
+            userEvent.tab();
+            const link = screen.getByText("Click me!");
+
+            // Assert
+            expect(link).toHaveFocus();
+            expect(link).toHaveStyle(`outline: 1px solid ${Color.blue}`);
+        });
+
+        test("blue outline around secondary links on focus", () => {
+            // Arrange
+            render(
+                <Link href="/" kind="secondary">
+                    Click me!
+                </Link>,
+            );
+
+            // Act
+            userEvent.tab();
+            const link = screen.getByText("Click me!");
+
+            // Assert
+            expect(link).toHaveFocus();
+            expect(link).toHaveStyle(`outline: 1px solid ${Color.blue}`);
+        });
+
+        test("blue outline around primary inline links on focus", () => {
+            // Arrange
+            render(
+                <Link href="/" kind="primary" inline={true}>
+                    Click me!
+                </Link>,
+            );
+
+            // Act
+            userEvent.tab();
+            const link = screen.getByText("Click me!");
+
+            // Assert
+            expect(link).toHaveFocus();
+            expect(link).toHaveStyle(`outline: 1px solid ${Color.blue}`);
+        });
+
+        test("blue outline around secondary inline links on focus", () => {
+            // Arrange
+            render(
+                <Link href="/" kind="secondary" inline={true}>
+                    Click me!
+                </Link>,
+            );
+
+            // Act
+            userEvent.tab();
+            const link = screen.getByText("Click me!");
+
+            // Assert
+            expect(link).toHaveFocus();
+            expect(link).toHaveStyle(`outline: 1px solid ${Color.blue}`);
+        });
+
+        test("white outline around light links on focus", () => {
+            // Arrange
+            render(
+                <Link href="/" light={true}>
+                    Click me!
+                </Link>,
+            );
+
+            // Act
+            userEvent.tab();
+            const link = screen.getByText("Click me!");
+
+            // Assert
+            expect(link).toHaveFocus();
+            expect(link).toHaveStyle(`outline: 1px solid ${Color.white}`);
+        });
+
+        test("white outline around inline light links on focus", () => {
+            // Arrange
+            render(
+                <Link href="/" light={true} inline={true}>
+                    Click me!
+                </Link>,
+            );
+
+            // Act
+            userEvent.tab();
+            const link = screen.getByText("Click me!");
+
+            // Assert
+            expect(link).toHaveFocus();
+            expect(link).toHaveStyle(`outline: 1px solid ${Color.white}`);
+        });
+    });
 });