@khanacademy/wonder-blocks-link 4.0.8 → 4.2.0

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

@@ -3,7 +3,7 @@ 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 {icons} from "@khanacademy/wonder-blocks-icon";
 
 import Link from "../link";
 
@@ -337,103 +337,176 @@ describe("Link", () => {
         });
     });
 
-    describe("focus style", () => {
-        test("blue outline around primary links on focus", () => {
+    describe("external link that opens in a new tab", () => {
+        test("target attribute passed down correctly", () => {
             // Arrange
-            render(<Link href="/">Click me!</Link>);
+            render(
+                <Link href="/" target="_blank">
+                    Click me!
+                </Link>,
+            );
 
             // Act
-            userEvent.tab();
-            const link = screen.getByText("Click me!");
+            const link = screen.getByRole("link");
 
             // Assert
-            expect(link).toHaveFocus();
-            expect(link).toHaveStyle(`outline: 1px solid ${Color.blue}`);
+            expect(link).toHaveAttribute("target", "_blank");
         });
 
-        test("blue outline around secondary links on focus", () => {
+        test("render external icon when `target=_blank`", () => {
             // Arrange
             render(
-                <Link href="/" kind="secondary">
+                <Link href="/" target="_blank">
                     Click me!
                 </Link>,
             );
 
             // Act
-            userEvent.tab();
-            const link = screen.getByText("Click me!");
+            const link = screen.getByRole("link");
+            const icon = screen.getByTestId("external-icon");
+
+            // Assert
+            expect(link.innerHTML).toEqual(expect.stringContaining("<svg"));
+            expect(icon).toBeInTheDocument();
+        });
+
+        test("does not render external icon when there is no target", () => {
+            // Arrange
+            render(<Link href="/">Click me!</Link>);
+
+            // Act
+            const icon = screen.queryByTestId("external-icon");
 
             // Assert
-            expect(link).toHaveFocus();
-            expect(link).toHaveStyle(`outline: 1px solid ${Color.blue}`);
+            expect(icon).not.toBeInTheDocument();
         });
+    });
 
-        test("blue outline around primary inline links on focus", () => {
+    describe("start and end icons", () => {
+        test("render icon with link when startIcon prop is passed in", () => {
             // Arrange
             render(
-                <Link href="/" kind="primary" inline={true}>
-                    Click me!
+                <Link href="/" startIcon={icons.add}>
+                    Add new item
                 </Link>,
             );
 
             // Act
-            userEvent.tab();
-            const link = screen.getByText("Click me!");
+            const link = screen.getByRole("link");
+            const icon = screen.getByTestId("start-icon");
 
             // Assert
-            expect(link).toHaveFocus();
-            expect(link).toHaveStyle(`outline: 1px solid ${Color.blue}`);
+            expect(link.innerHTML).toEqual(expect.stringContaining("<svg"));
+            expect(icon).toBeInTheDocument();
         });
 
-        test("blue outline around secondary inline links on focus", () => {
+        test("does not render icon when startIcon prop is not passed in", () => {
+            // Arrange
+            render(<Link href="/">Click me!</Link>);
+
+            // Act
+            const icon = screen.queryByTestId("start-icon");
+
+            // Assert
+            expect(icon).not.toBeInTheDocument();
+        });
+
+        test("startIcon prop passed down correctly", () => {
             // Arrange
             render(
-                <Link href="/" kind="secondary" inline={true}>
-                    Click me!
+                <Link href="/" startIcon={icons.add}>
+                    Add new item
                 </Link>,
             );
 
             // Act
-            userEvent.tab();
-            const link = screen.getByText("Click me!");
+            const icon = screen.getByTestId("start-icon");
+            const iconToExpect =
+                "M11 11V7a1 1 0 0 1 2 0v4h4a1 1 0 0 1 0 2h-4v4a1 1 0 0 1-2 0v-4H7a1 1 0 0 1 0-2h4zm1 13C5.373 24 0 18.627 0 12S5.373 0 12 0s12 5.373 12 12-5.373 12-12 12zm0-2c5.523 0 10-4.477 10-10S17.523 2 12 2 2 6.477 2 12s4.477 10 10 10z";
 
             // Assert
-            expect(link).toHaveFocus();
-            expect(link).toHaveStyle(`outline: 1px solid ${Color.blue}`);
+            expect(icon.innerHTML).toEqual(
+                expect.stringContaining(iconToExpect),
+            );
         });
 
-        test("white outline around light links on focus", () => {
+        test("render icon with link when endIcon prop is passed in", () => {
             // Arrange
             render(
-                <Link href="/" light={true}>
-                    Click me!
+                <Link href="/" endIcon={icons.caretRight}>
+                    Click to go back
                 </Link>,
             );
 
             // Act
-            userEvent.tab();
-            const link = screen.getByText("Click me!");
+            const link = screen.getByRole("link");
+            const icon = screen.getByTestId("end-icon");
 
             // Assert
-            expect(link).toHaveFocus();
-            expect(link).toHaveStyle(`outline: 1px solid ${Color.white}`);
+            expect(link.innerHTML).toEqual(expect.stringContaining("<svg"));
+            expect(icon).toBeInTheDocument();
         });
 
-        test("white outline around inline light links on focus", () => {
+        test("does not render icon when endIcon prop is not passed in", () => {
+            // Arrange
+            render(<Link href="/">Click me!</Link>);
+
+            // Act
+            const icon = screen.queryByTestId("end-icon");
+
+            // Assert
+            expect(icon).not.toBeInTheDocument();
+        });
+
+        test("does not render externalIcon when endIcon is passed in and `target='_blank'`", () => {
             // Arrange
             render(
-                <Link href="/" light={true} inline={true}>
-                    Click me!
+                <Link href="/" endIcon={icons.caretRight} target="_blank">
+                    Open a new tab
                 </Link>,
             );
 
             // Act
-            userEvent.tab();
-            const link = screen.getByText("Click me!");
+            const externalIcon = screen.queryByTestId("external-icon");
 
             // Assert
-            expect(link).toHaveFocus();
-            expect(link).toHaveStyle(`outline: 1px solid ${Color.white}`);
+            expect(externalIcon).not.toBeInTheDocument();
+        });
+
+        test("render endIcon instead of default externalIcon when `target='_blank'`", () => {
+            // Arrange
+            render(
+                <Link href="/" endIcon={icons.caretRight} target="_blank">
+                    Open a new tab
+                </Link>,
+            );
+
+            // Act
+            const link = screen.getByRole("link");
+            const endIcon = screen.getByTestId("end-icon");
+
+            // Assert
+            expect(link.innerHTML).toEqual(expect.stringContaining("<svg"));
+            expect(endIcon).toBeInTheDocument();
+        });
+
+        test("endIcon prop passed down correctly", () => {
+            // Arrange
+            render(
+                <Link href="/" endIcon={icons.caretRight}>
+                    Click to go back
+                </Link>,
+            );
+
+            // Act
+            const icon = screen.getByTestId("end-icon");
+            const iconToExpect =
+                "M8.586 8L5.293 4.707a1 1 0 0 1 1.414-1.414l4 4a1 1 0 0 1 0 1.414l-4 4a1 1 0 0 1-1.414-1.414L8.586 8z";
+
+            // Assert
+            expect(icon.innerHTML).toEqual(
+                expect.stringContaining(iconToExpect),
+            );
         });
     });
 });

package/src/components/link-core.tsx

@@ -6,12 +6,15 @@ import {__RouterContext} from "react-router";
 import {addStyle} from "@khanacademy/wonder-blocks-core";
 import Color, {mix, fade} from "@khanacademy/wonder-blocks-color";
 import {isClientSideUrl} from "@khanacademy/wonder-blocks-clickable";
+import Icon from "@khanacademy/wonder-blocks-icon";
+import Spacing from "@khanacademy/wonder-blocks-spacing";
 
 import type {
     ChildrenProps,
     ClickableState,
 } from "@khanacademy/wonder-blocks-clickable";
 import type {StyleDeclaration} from "aphrodite";
+import type {IconAsset} from "@khanacademy/wonder-blocks-icon";
 import type {SharedProps} from "./link";
 
 type Props = SharedProps &
@@ -20,8 +23,8 @@ type Props = SharedProps &
         href: string;
     };
 
-const StyledAnchor = addStyle<"a">("a");
-const StyledLink = addStyle<typeof Link>(Link);
+const StyledAnchor = addStyle("a");
+const StyledLink = addStyle(Link);
 
 export default class LinkCore extends React.Component<Props> {
     renderInner(router: any): React.ReactNode {
@@ -39,6 +42,9 @@ export default class LinkCore extends React.Component<Props> {
             style,
             testId,
             waiting: _,
+            target,
+            startIcon,
+            endIcon,
             ...restProps
         } = this.props;
 
@@ -49,7 +55,7 @@ export default class LinkCore extends React.Component<Props> {
 
         const defaultStyles = [
             sharedStyles.shared,
-            !(hovered || focused || pressed) && restingStyles,
+            restingStyles,
             pressed && linkStyles.active,
             // A11y: The focus ring should always be present when the
             // the link has focus, even the link is being hovered over.
@@ -63,16 +69,57 @@ export default class LinkCore extends React.Component<Props> {
         const commonProps = {
             "data-test-id": testId,
             style: [defaultStyles, style],
+            target,
             ...restProps,
         } as const;
 
+        // Default external icon
+        const externalIconPath: IconAsset = {
+            small: "M14 6.5C14 6.63261 13.9473 6.75979 13.8536 6.85355C13.7598 6.94732 13.6326 7 13.5 7C13.3674 7 13.2402 6.94732 13.1464 6.85355C13.0527 6.75979 13 6.63261 13 6.5V3.7075L8.85437 7.85375C8.76055 7.94757 8.63331 8.00028 8.50062 8.00028C8.36794 8.00028 8.2407 7.94757 8.14688 7.85375C8.05306 7.75993 8.00035 7.63268 8.00035 7.5C8.00035 7.36732 8.05306 7.24007 8.14688 7.14625L12.2925 3H9.5C9.36739 3 9.24021 2.94732 9.14645 2.85355C9.05268 2.75979 9 2.63261 9 2.5C9 2.36739 9.05268 2.24021 9.14645 2.14645C9.24021 2.05268 9.36739 2 9.5 2H13.5C13.6326 2 13.7598 2.05268 13.8536 2.14645C13.9473 2.24021 14 2.36739 14 2.5V6.5ZM11.5 8C11.3674 8 11.2402 8.05268 11.1464 8.14645C11.0527 8.24021 11 8.36739 11 8.5V13H3V5H7.5C7.63261 5 7.75979 4.94732 7.85355 4.85355C7.94732 4.75979 8 4.63261 8 4.5C8 4.36739 7.94732 4.24021 7.85355 4.14645C7.75979 4.05268 7.63261 4 7.5 4H3C2.73478 4 2.48043 4.10536 2.29289 4.29289C2.10536 4.48043 2 4.73478 2 5V13C2 13.2652 2.10536 13.5196 2.29289 13.7071C2.48043 13.8946 2.73478 14 3 14H11C11.2652 14 11.5196 13.8946 11.7071 13.7071C11.8946 13.5196 12 13.2652 12 13V8.5C12 8.36739 11.9473 8.24021 11.8536 8.14645C11.7598 8.05268 11.6326 8 11.5 8Z",
+        };
+
+        const externalIcon = (
+            <Icon
+                icon={externalIconPath}
+                size="small"
+                style={iconStyles.endIcon}
+                testId="external-icon"
+            />
+        );
+
+        const linkContent = (
+            <>
+                {startIcon && (
+                    <Icon
+                        icon={startIcon}
+                        size="small"
+                        style={iconStyles.startIcon}
+                        testId="start-icon"
+                        aria-hidden="true"
+                    />
+                )}
+                <span style={{verticalAlign: "middle"}}>{children}</span>
+                {endIcon ? (
+                    <Icon
+                        icon={endIcon}
+                        size="small"
+                        style={iconStyles.endIcon}
+                        testId="end-icon"
+                        aria-hidden="true"
+                    />
+                ) : (
+                    target === "_blank" && externalIcon
+                )}
+            </>
+        );
+
         return router && !skipClientNav && isClientSideUrl(href) ? (
             <StyledLink {...commonProps} to={href}>
-                {children}
+                {linkContent}
             </StyledLink>
         ) : (
             <StyledAnchor {...commonProps} href={href}>
-                {children}
+                {linkContent}
             </StyledAnchor>
         );
     }
@@ -88,12 +135,25 @@ export default class LinkCore extends React.Component<Props> {
 
 const styles: Record<string, any> = {};
 
+const iconStyles = StyleSheet.create({
+    startIcon: {
+        marginInlineEnd: Spacing.xxxSmall_4,
+        verticalAlign: "middle",
+    },
+    endIcon: {
+        marginInlineStart: Spacing.xxxSmall_4,
+        verticalAlign: "middle",
+    },
+});
+
 const sharedStyles = StyleSheet.create({
     shared: {
         cursor: "pointer",
         textDecoration: "none",
         outline: "none",
-        display: "inline-flex",
+        verticalAlign: "bottom",
+        textUnderlineOffset: "3px",
+        alignItems: "center",
     },
 });
 
@@ -184,10 +244,14 @@ const _generateStyles = (
             ...defaultVisited,
         },
         focus: {
-            color: defaultTextColor,
-            outline: `1px solid ${light ? white : blue}`,
-            borderRadius: 3,
-            ...defaultVisited,
+            // Focus styles only show up with keyboard navigation.
+            // Mouse users don't see focus styles.
+            ":focus-visible": {
+                color: defaultTextColor,
+                outline: `1px solid ${light ? white : blue}`,
+                borderRadius: 3,
+                ...defaultVisited,
+            },
         },
         active: {
             color: activeColor,

package/src/components/link.tsx

@@ -4,6 +4,7 @@ import {getClickableBehavior} from "@khanacademy/wonder-blocks-clickable";
 
 import type {AriaProps, StyleType} from "@khanacademy/wonder-blocks-core";
 import type {Typography} from "@khanacademy/wonder-blocks-typography";
+import type {IconAsset} from "@khanacademy/wonder-blocks-icon";
 import LinkCore from "./link-core";
 
 // TODO(FEI-5000): Convert back to conditional props after TS migration is complete.
@@ -136,6 +137,20 @@ export type SharedProps = AriaProps & {
      * navigation.
      */
     beforeNav?: () => Promise<unknown>;
+    /**
+     * An optional title attribute.
+     */
+    title?: string;
+    /**
+     * An optional icon displayed before the link label.
+     */
+    startIcon?: IconAsset;
+    /**
+     * An optional icon displayed after the link label.
+     * If `target="_blank"` and `endIcon` is passed in, `endIcon` will override
+     * the default `externalIcon`.
+     */
+    endIcon?: IconAsset;
 };
 
 type DefaultProps = {

package/tsconfig.json

@@ -10,5 +10,7 @@
         {"path": "../wonder-blocks-color"},
         {"path": "../wonder-blocks-core"},
         {"path": "../wonder-blocks-typography"},
+        {"path": "../wonder-blocks-icon"},
+        {"path": "../wonder-blocks-spacing"},
     ]
 }