@khanacademy/wonder-blocks-link 3.8.8 → 3.8.9

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @khanacademy/wonder-blocks-link
 
+## 3.8.9
+
+### Patch Changes
+
+-   Updated dependencies [34c7aacb]
+    -   @khanacademy/wonder-blocks-color@1.2.0
+
 ## 3.8.8
 
 ### Patch Changes

package/dist/index.js

@@ -283,7 +283,8 @@ function _extends() { _extends = Object.assign || function (target) { for (var i
  * `LinkCore` is a stateless component which displays the different states
  * the `Link` can take.
  *
- * Example usage:
+ * ### Usage
+ *
  * ```jsx
  * <Link
  *     href="https://khanacademy.org/"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanacademy/wonder-blocks-link",
-  "version": "3.8.8",
+  "version": "3.8.9",
   "design": "v1",
   "publishConfig": {
     "access": "public"
@@ -17,7 +17,7 @@
   "dependencies": {
     "@babel/runtime": "^7.18.6",
     "@khanacademy/wonder-blocks-clickable": "^2.3.0",
-    "@khanacademy/wonder-blocks-color": "^1.1.20",
+    "@khanacademy/wonder-blocks-color": "^1.2.0",
     "@khanacademy/wonder-blocks-core": "^4.3.2"
   },
   "peerDependencies": {

package/src/__tests__/__snapshots__/generated-snapshot.test.js.snap

@@ -130,7 +130,7 @@ exports[`wonder-blocks-link example 1 1`] = `
   <p
     style={
       Object {
-        "backgroundColor": "#0a2a66",
+        "backgroundColor": "#0b2149",
         "color": "rgba(255,255,255,0.64)",
         "padding": 10,
       }

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

@@ -0,0 +1,143 @@
+// @flow
+
+export default {
+    children: {
+        control: {type: "text"},
+        description:
+            "Text to appear on the link. It can be a plain text or Typography element.",
+        table: {type: {summary: "string | React.Element<Typography>"}},
+        type: {required: true},
+    },
+    href: {
+        control: {type: "text"},
+        description: "URL to navigate to.",
+        table: {type: {summary: "string"}},
+        type: {required: true},
+    },
+    id: {
+        control: {type: "text"},
+        description: "An optional id attribute.",
+        table: {type: {summary: "string"}},
+        type: {required: false},
+    },
+    kind: {
+        control: {type: "select"},
+        description:
+            "Kind of Link. Note: Secondary light Links are not supported.",
+        options: ["primary", "secondary"],
+        table: {
+            type: {summary: `"primary" | "secondary"`},
+        },
+        type: {required: false},
+    },
+    light: {
+        control: {type: "boolean"},
+        description: "Whether the button is on a dark/colored background.",
+        table: {
+            type: {summary: "boolean"},
+        },
+    },
+    visitable: {
+        control: {type: "boolean"},
+        description:
+            "Whether the link should change color once it's visited. Secondary or primary (light) links are not allowed to be visitable.",
+        table: {
+            type: {summary: "boolean"},
+        },
+    },
+    rel: {
+        control: {type: "text"},
+        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.`,
+        table: {
+            type: {summary: "string"},
+        },
+    },
+    tabIndex: {
+        control: {type: "number"},
+        description: "Set the tabindex attribute on the rendered element.",
+        table: {
+            defaultValue: {summary: 0},
+            type: {summary: "number"},
+        },
+    },
+    testId: {
+        control: {type: "text"},
+        description: "Test ID used for e2e testing.",
+        table: {
+            type: {summary: "string"},
+        },
+    },
+
+    style: {
+        control: {type: "object"},
+        description: "custom styles.",
+        table: {type: {summary: "StyleType"}},
+    },
+    className: {
+        control: {type: "text"},
+        description: "Adds CSS classes to the Link.",
+        table: {type: {summary: "string"}},
+    },
+    beforeNav: {
+        description: `Run async code before navigating to the URL passed to
+            \`href\`. 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>"},
+        },
+    },
+    skipClientNav: {
+        control: {type: "boolean"},
+        description: `Whether to avoid using client-side navigation.
+            If the URL passed to href is local to the client-side, e.g.
+            /math/algebra/eval-exprs, then it tries to use react-router-dom's
+            Link component which handles the client-side navigation. You can set
+            \`skipClientNav\` to true avoid using client-side nav entirely.`,
+        table: {
+            category: "Navigation",
+            type: {summary: "boolean"},
+        },
+    },
+    onClick: {
+        description: `Function to call when button is clicked.
+        This should NOT be used to redirect to a different URL or to
+        prevent navigation via e.preventDefault(). The event passed to this
+        handler will have its preventDefault() and stopPropagation() methods
+        stubbed out.`,
+        table: {
+            category: "Events",
+            type: {summary: "(e: SyntheticEvent<>) => mixed"},
+        },
+    },
+    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"},
+        },
+    },
+};

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

@@ -0,0 +1,197 @@
+// @flow
+import * as React from "react";
+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 Link from "@khanacademy/wonder-blocks-link";
+import Spacing from "@khanacademy/wonder-blocks-spacing";
+import {
+    Body,
+    HeadingSmall,
+    LabelLarge,
+} from "@khanacademy/wonder-blocks-typography";
+import type {StoryComponentType} from "@storybook/react";
+
+import LinkArgTypes from "./link.argtypes.js";
+import ComponentInfo from "../../../../../.storybook/components/component-info.js";
+import {name, version} from "../../../package.json";
+
+export default {
+    title: "Link",
+    component: Link,
+    parameters: {
+        componentSubtitle: ((
+            <ComponentInfo name={name} version={version} />
+        ): any),
+    },
+    argTypes: LinkArgTypes,
+};
+
+export const Default: StoryComponentType = (args) => (
+    <Link target="_blank" {...args} />
+);
+
+Default.args = {
+    href: "/",
+    children: "Hello, world!",
+};
+
+export const Basic: StoryComponentType = () => (
+    <Link href="#">Hello, world!</Link>
+);
+
+Basic.parameters = {
+    docs: {
+        storyDescription: `Minimal link usage.
+            This links to the top of the page.`,
+    },
+};
+
+export const Variants: 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.
+    </Body>
+);
+
+Variants.parameters = {
+    docs: {
+        storyDescription: `Primary links are blue, secondary links are black,
+            and visitable links turn purple after they've been clicked on.`,
+    },
+};
+
+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.
+    </Body>
+);
+
+LightVariants.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.`,
+    },
+};
+
+export const WithTypography: StoryComponentType = () => (
+    <Link href="#nonexistent-link" id="typography-link">
+        <HeadingSmall>Heading inside a Link element</HeadingSmall>
+    </Link>
+);
+
+WithTypography.parameters = {
+    docs: {
+        storyDescription: `Wonder Blocks Typography elements can also be used
+            inside Links instead of plain text. Here, we have a \`Link\`
+            containing a \`HeadingSmall\`.`,
+    },
+};
+
+export const WithStyle: StoryComponentType = () => (
+    <Link href="#" style={styles.pinkLink}>
+        This link has a style.
+    </Link>
+);
+
+WithStyle.parameters = {
+    docs: {
+        storyDescription: `Link can take a \`style\` prop. Here, the
+            Link has been given a style in which the \`color\` field has
+            been set to \`Colors.pink\`.`,
+    },
+};
+
+export const Navigation: StoryComponentType = () => (
+    <MemoryRouter>
+        <View>
+            <View style={styles.row}>
+                <Link
+                    href="/foo"
+                    style={styles.heading}
+                    onClick={() => {
+                        // eslint-disable-next-line no-console
+                        console.log("I'm still on the same page!");
+                    }}
+                >
+                    <LabelLarge>Uses Client-side Nav</LabelLarge>
+                </Link>
+                <Link
+                    href="/iframe.html?id=link--default&viewMode=story"
+                    style={styles.heading}
+                    skipClientNav
+                >
+                    <LabelLarge>Avoids Client-side Nav</LabelLarge>
+                </Link>
+            </View>
+            <View style={styles.navigation}>
+                <Switch>
+                    <Route path="/foo">
+                        <View id="foo">
+                            The first link does client-side navigation here.
+                        </View>
+                    </Route>
+                    <Route path="*">See navigation changes here</Route>
+                </Switch>
+            </View>
+        </View>
+    </MemoryRouter>
+);
+
+Navigation.parameters = {
+    docs: {
+        storyDescription: `If you want to navigate to an external URL
+            and/or reload the window, make sure to use \`href\` and
+            \`skipClientNav={true}\`, as shown in this example.
+            **For navigation callbacks:** The \`onClick\`, \`beforeNav\`, and
+            \`safeWithNav\` props can be used to run callbacks when navigating
+            to the new URL. Which prop to use depends on the use case. See the
+            [Button documentation](/story/button-navigation-callbacks--before-nav-callbacks&viewMode=docs)
+            for details.`,
+    },
+};
+
+const styles = StyleSheet.create({
+    darkBackground: {
+        backgroundColor: Color.darkBlue,
+        color: Color.white64,
+        padding: 10,
+    },
+    heading: {
+        marginRight: Spacing.large_24,
+    },
+    navigation: {
+        border: `1px dashed ${Color.lightBlue}`,
+        marginTop: Spacing.large_24,
+        padding: Spacing.large_24,
+    },
+    pinkLink: {
+        color: Color.pink,
+    },
+    row: {
+        flexDirection: "row",
+        alignItems: "center",
+    },
+});

package/src/components/link.js

@@ -172,7 +172,8 @@ type DefaultProps = {|
  * `LinkCore` is a stateless component which displays the different states
  * the `Link` can take.
  *
- * Example usage:
+ * ### Usage
+ *
  * ```jsx
  * <Link
  *     href="https://khanacademy.org/"