@khanacademy/wonder-blocks-link 4.2.7 → 4.3.0

package/dist/components/link.d.ts

@@ -1,4 +1,5 @@
 import * as React from "react";
+import { Link as ReactRouterLink } from "react-router-dom";
 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";
@@ -20,20 +21,20 @@ export type SharedProps = AriaProps & {
      * This styles the link with an underline to distinguish it
      * from surrounding text.
      */
-    inline: boolean;
+    inline?: boolean;
     /**
      * Kind of Link. Note: Secondary light Links are not supported.
      */
-    kind: "primary" | "secondary";
+    kind?: "primary" | "secondary";
     /**
      * Whether the button is on a dark/colored background.
      */
-    light: boolean;
+    light?: boolean;
     /**
      * Whether the link should change color once it's visited.
      * secondary or primary (light) links are not allowed to be visitable.
      */
-    visitable: boolean;
+    visitable?: boolean;
     /**
      * Specifies the type of relationship between the current document and the
      * linked document. Should only be used when `href` is specified. This
@@ -131,12 +132,6 @@ export type SharedProps = AriaProps & {
      */
     endIcon?: IconAsset;
 };
-type DefaultProps = {
-    inline: SharedProps["inline"];
-    kind: SharedProps["kind"];
-    light: SharedProps["light"];
-    visitable: SharedProps["visitable"];
-};
 /**
  * Reusable link component.
  *
@@ -155,9 +150,135 @@ type DefaultProps = {
  * </Link>
  * ```
  */
-export default class Link extends React.Component<SharedProps> {
-    static defaultProps: DefaultProps;
-    renderClickableBehavior(router: any): React.ReactNode;
-    render(): React.ReactNode;
-}
-export {};
+declare const Link: React.ForwardRefExoticComponent<Readonly<import("../../../wonder-blocks-core/src/util/aria-types").AriaAttributes> & Readonly<{
+    role?: import("../../../wonder-blocks-core/src/util/aria-types").AriaRole | undefined;
+}> & {
+    /**
+     * Text to appear on the link. It can be a plain text or a Typography element.
+     */
+    children: string | React.ReactElement<React.ComponentProps<Typography>>;
+    /**
+     * URL to navigate to.
+     */
+    href: string;
+    /**
+     * An optional id attribute.
+     */
+    id?: string | undefined;
+    /**
+     * Indicates that this link is used within a body of text.
+     * This styles the link with an underline to distinguish it
+     * from surrounding text.
+     */
+    inline?: boolean | undefined;
+    /**
+     * Kind of Link. Note: Secondary light Links are not supported.
+     */
+    kind?: "primary" | "secondary" | undefined;
+    /**
+     * Whether the button is on a dark/colored background.
+     */
+    light?: boolean | undefined;
+    /**
+     * Whether the link should change color once it's visited.
+     * secondary or primary (light) links are not allowed to be visitable.
+     */
+    visitable?: boolean | undefined;
+    /**
+     * 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.
+     */
+    rel?: string | undefined;
+    /**
+     * Set the tabindex attribute on the rendered element.
+     */
+    tabIndex?: number | undefined;
+    /**
+     * Test ID used for e2e testing.
+     */
+    testId?: string | undefined;
+    /**
+     * 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.
+     *
+     * NOTE: All URLs containing a protocol are considered external, e.g.
+     * https://khanacademy.org/math/algebra/eval-exprs will trigger a full
+     * page reload.
+     */
+    skipClientNav?: boolean | undefined;
+    /**
+     * Custom styles.
+     */
+    style?: StyleType;
+    /**
+     * Adds CSS classes to the Link.
+     */
+    className?: string | undefined;
+    /**
+     * Function to call when button is clicked.
+     *
+     * This callback should be used for things like marking BigBingo
+     * conversions. It 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.
+     */
+    onClick?: ((e: React.SyntheticEvent) => unknown) | undefined;
+    /**
+     * 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.
+     */
+    safeWithNav?: (() => Promise<unknown>) | undefined;
+    /**
+     * Respond to raw "keydown" event.
+     */
+    onKeyDown?: ((e: React.KeyboardEvent) => unknown) | undefined;
+    /**
+     * Respond to raw "keyup" event.
+     */
+    onKeyUp?: ((e: React.KeyboardEvent) => unknown) | undefined;
+    /**
+     * A target destination window for a link to open in.  We only support
+     * "_blank" which opens the URL in a new tab.
+     *
+     * TODO(WB-1262): only allow this prop when `href` is also set.t
+     */
+    target?: "_blank" | undefined;
+    /**
+     * 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.
+     *
+     * WARNING: Using this with `target="_blank"` will trigger built-in popup
+     * blockers in Firefox and Safari.  This is because we do navigation
+     * programmatically and `beforeNav` causes a delay which means that the
+     * browser can't make a directly link between a user action and the
+     * navigation.
+     */
+    beforeNav?: (() => Promise<unknown>) | undefined;
+    /**
+     * An optional title attribute.
+     */
+    title?: string | undefined;
+    /**
+     * An optional icon displayed before the link label.
+     */
+    startIcon?: IconAsset | undefined;
+    /**
+     * An optional icon displayed after the link label.
+     * If `target="_blank"` and `endIcon` is passed in, `endIcon` will override
+     * the default `externalIcon`.
+     */
+    endIcon?: IconAsset | undefined;
+} & React.RefAttributes<HTMLAnchorElement | typeof ReactRouterLink>>;
+export default Link;

package/dist/components/link.js.flow

@@ -4,7 +4,9 @@
  * Flowgen v1.21.0
  * @flow
  */
+import * as $Flowgen$Import$_2e__2e__2f__2e__2e__2f__2e__2e__2f_wonder_2d_blocks_2d_core_2f_src_2f_util_2f_aria_2d_types from "../../../wonder-blocks-core/src/util/aria-types";
 import * as React from "react";
+import { Link as ReactRouterLink } from "react-router-dom";
 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";
@@ -31,23 +33,23 @@ export type SharedProps = {|
      * This styles the link with an underline to distinguish it
      * from surrounding text.
      */
-    inline: boolean,
+    inline?: boolean,
 
     /**
      * Kind of Link. Note: Secondary light Links are not supported.
      */
-    kind: "primary" | "secondary",
+    kind?: "primary" | "secondary",
 
     /**
      * Whether the button is on a dark/colored background.
      */
-    light: boolean,
+    light?: boolean,
 
     /**
      * Whether the link should change color once it's visited.
      * secondary or primary (light) links are not allowed to be visitable.
      */
-    visitable: boolean,
+    visitable?: boolean,
 
     /**
      * Specifies the type of relationship between the current document and the
@@ -161,12 +163,6 @@ export type SharedProps = {|
     endIcon?: IconAsset,
   |},
 |};
-declare type DefaultProps = {|
-  inline: $PropertyType<SharedProps, "inline">,
-  kind: $PropertyType<SharedProps, "kind">,
-  light: $PropertyType<SharedProps, "light">,
-  visitable: $PropertyType<SharedProps, "visitable">,
-|};
 /**
  * Reusable link component.
  *
@@ -185,8 +181,161 @@ declare type DefaultProps = {|
  * </Link>
  * ```
  */
-declare export default class Link extends React.Component<SharedProps> {
-  static defaultProps: DefaultProps;
-  renderClickableBehavior(router: any): React.Node;
-  render(): React.Node;
-}
+declare var Link: React.ForwardRefExoticComponent<{|
+  ...$ReadOnly<$Flowgen$Import$_2e__2e__2f__2e__2e__2f__2e__2e__2f_wonder_2d_blocks_2d_core_2f_src_2f_util_2f_aria_2d_types.AriaAttributes>,
+  ...$ReadOnly<{|
+    role?: $Flowgen$Import$_2e__2e__2f__2e__2e__2f__2e__2e__2f_wonder_2d_blocks_2d_core_2f_src_2f_util_2f_aria_2d_types.AriaRole | void,
+  |}>,
+  ...{|
+    /**
+     * Text to appear on the link. It can be a plain text or a Typography element.
+     */
+    children: string | React.Element<Typography>,
+
+    /**
+     * URL to navigate to.
+     */
+    href: string,
+
+    /**
+     * An optional id attribute.
+     */
+    id?: string | void,
+
+    /**
+     * Indicates that this link is used within a body of text.
+     * This styles the link with an underline to distinguish it
+     * from surrounding text.
+     */
+    inline?: boolean | void,
+
+    /**
+     * Kind of Link. Note: Secondary light Links are not supported.
+     */
+    kind?: "primary" | "secondary" | void,
+
+    /**
+     * Whether the button is on a dark/colored background.
+     */
+    light?: boolean | void,
+
+    /**
+     * Whether the link should change color once it's visited.
+     * secondary or primary (light) links are not allowed to be visitable.
+     */
+    visitable?: boolean | void,
+
+    /**
+     * 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.
+     */
+    rel?: string | void,
+
+    /**
+     * Set the tabindex attribute on the rendered element.
+     */
+    tabIndex?: number | void,
+
+    /**
+     * Test ID used for e2e testing.
+     */
+    testId?: string | void,
+
+    /**
+     * 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.
+     *
+     * NOTE: All URLs containing a protocol are considered external, e.g.
+     * https://khanacademy.org/math/algebra/eval-exprs will trigger a full
+     * page reload.
+     */
+    skipClientNav?: boolean | void,
+
+    /**
+     * Custom styles.
+     */
+    style?: StyleType,
+
+    /**
+     * Adds CSS classes to the Link.
+     */
+    className?: string | void,
+
+    /**
+     * Function to call when button is clicked.
+     *
+     * This callback should be used for things like marking BigBingo
+     * conversions. It 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.
+     */
+    onClick?: ((e: SyntheticEvent<>) => mixed) | void,
+
+    /**
+     * 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.
+     */
+    safeWithNav?: (() => Promise<mixed>) | void,
+
+    /**
+     * Respond to raw "keydown" event.
+     */
+    onKeyDown?: ((e: SyntheticKeyboardEvent<>) => mixed) | void,
+
+    /**
+     * Respond to raw "keyup" event.
+     */
+    onKeyUp?: ((e: SyntheticKeyboardEvent<>) => mixed) | void,
+
+    /**
+     * A target destination window for a link to open in.  We only support
+     * "_blank" which opens the URL in a new tab.
+     *
+     * TODO(WB-1262): only allow this prop when `href` is also set.t
+     */
+    target?: "_blank" | void,
+
+    /**
+     * 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.
+     *
+     * WARNING: Using this with `target="_blank"` will trigger built-in popup
+     * blockers in Firefox and Safari.  This is because we do navigation
+     * programmatically and `beforeNav` causes a delay which means that the
+     * browser can't make a directly link between a user action and the
+     * navigation.
+     */
+    beforeNav?: (() => Promise<mixed>) | void,
+
+    /**
+     * An optional title attribute.
+     */
+    title?: string | void,
+
+    /**
+     * An optional icon displayed before the link label.
+     */
+    startIcon?: IconAsset | void,
+
+    /**
+     * An optional icon displayed after the link label.
+     * If `target="_blank"` and `endIcon` is passed in, `endIcon` will override
+     * the default `externalIcon`.
+     */
+    endIcon?: IconAsset | void,
+  |},
+  ...React.RefAttributes<HTMLAnchorElement | typeof ReactRouterLink>,
+|}>;
+declare export default typeof Link;

package/dist/es/index.js

@@ -43,32 +43,29 @@ function _objectWithoutPropertiesLoose(source, excluded) {
 const _excluded$1 = ["children", "skipClientNav", "focused", "hovered", "href", "inline", "kind", "light", "visitable", "pressed", "style", "testId", "waiting", "target", "startIcon", "endIcon"];
 const StyledAnchor = addStyle("a");
 const StyledLink = addStyle(Link$1);
-const StyledSpan = addStyle("span");
-class LinkCore extends React.Component {
-  renderInner(router) {
-    const _this$props = this.props,
-      {
+const LinkCore = React.forwardRef((props, ref) => {
+  const renderInner = router => {
+    const {
         children,
         skipClientNav,
         focused,
         hovered,
         href,
-        inline,
-        kind,
-        light,
-        visitable,
+        inline = false,
+        kind = "primary",
+        light = false,
+        visitable = false,
         pressed,
         style,
         testId,
         target,
         startIcon,
         endIcon
-      } = _this$props,
-      restProps = _objectWithoutPropertiesLoose(_this$props, _excluded$1);
-    const withIcon = startIcon || endIcon || target === "_blank";
+      } = props,
+      restProps = _objectWithoutPropertiesLoose(props, _excluded$1);
     const linkStyles = _generateStyles(inline, kind, light, visitable);
     const restingStyles = inline ? linkStyles.restingInline : linkStyles.resting;
-    const defaultStyles = [sharedStyles.shared, restingStyles, pressed && linkStyles.active, !pressed && hovered && linkStyles.hover, !pressed && focused && linkStyles.focus, withIcon && sharedStyles.withIcon];
+    const defaultStyles = [sharedStyles.shared, restingStyles, pressed && linkStyles.active, !pressed && hovered && linkStyles.hover, !pressed && focused && linkStyles.focus];
     const commonProps = _extends({
       "data-test-id": testId,
       style: [defaultStyles, style],
@@ -91,9 +88,7 @@ class LinkCore extends React.Component {
       style: [linkContentStyles.startIcon, linkContentStyles.centered],
       testId: "start-icon",
       "aria-hidden": "true"
-    }), withIcon ? React.createElement(StyledSpan, {
-      style: linkContentStyles.centered
-    }, children) : children, endIcon ? React.createElement(Icon, {
+    }), children, endIcon ? React.createElement(Icon, {
       icon: endIcon,
       size: "small",
       style: [linkContentStyles.endIcon, linkContentStyles.centered],
@@ -101,15 +96,15 @@ class LinkCore extends React.Component {
       "aria-hidden": "true"
     }) : isExternalLink && target === "_blank" && externalIcon);
     return router && !skipClientNav && isClientSideUrl(href) ? React.createElement(StyledLink, _extends({}, commonProps, {
-      to: href
+      to: href,
+      ref: ref
     }), linkContent) : React.createElement(StyledAnchor, _extends({}, commonProps, {
-      href: href
+      href: href,
+      ref: ref
     }), linkContent);
-  }
-  render() {
-    return React.createElement(__RouterContext.Consumer, null, router => this.renderInner(router));
-  }
-}
+  };
+  return React.createElement(__RouterContext.Consumer, null, router => renderInner(router));
+});
 const styles = {};
 const linkContentStyles = StyleSheet.create({
   startIcon: {
@@ -119,7 +114,7 @@ const linkContentStyles = StyleSheet.create({
     marginInlineStart: Spacing.xxxSmall_4
   },
   centered: {
-    verticalAlign: "middle"
+    verticalAlign: "-10%"
   }
 });
 const sharedStyles = StyleSheet.create({
@@ -128,10 +123,6 @@ const sharedStyles = StyleSheet.create({
     textDecoration: "none",
     outline: "none",
     alignItems: "center"
-  },
-  withIcon: {
-    verticalAlign: "bottom",
-    textUnderlineOffset: 4
   }
 });
 const _generateStyles = (inline, kind, light, visitable) => {
@@ -203,23 +194,26 @@ const _generateStyles = (inline, kind, light, visitable) => {
   return styles[buttonType];
 };
 
-const _excluded = ["onClick", "beforeNav", "safeWithNav", "href", "skipClientNav", "children", "tabIndex", "onKeyDown", "onKeyUp", "target"];
-class Link extends React.Component {
-  renderClickableBehavior(router) {
-    const _this$props = this.props,
-      {
-        onClick,
-        beforeNav = undefined,
-        safeWithNav,
-        href,
-        skipClientNav,
-        children,
-        tabIndex,
-        onKeyDown,
-        onKeyUp,
-        target = undefined
-      } = _this$props,
-      sharedProps = _objectWithoutPropertiesLoose(_this$props, _excluded);
+const _excluded = ["onClick", "beforeNav", "safeWithNav", "href", "skipClientNav", "children", "tabIndex", "onKeyDown", "onKeyUp", "target", "inline", "kind", "light", "visitable"];
+const Link = React.forwardRef((props, ref) => {
+  const {
+      onClick,
+      beforeNav = undefined,
+      safeWithNav,
+      href,
+      skipClientNav,
+      children,
+      tabIndex,
+      onKeyDown,
+      onKeyUp,
+      target = undefined,
+      inline = false,
+      kind = "primary",
+      light = false,
+      visitable = false
+    } = props,
+    sharedProps = _objectWithoutPropertiesLoose(props, _excluded);
+  const renderClickableBehavior = router => {
     const ClickableBehavior = getClickableBehavior(href, skipClientNav, router);
     if (beforeNav) {
       return React.createElement(ClickableBehavior, {
@@ -237,7 +231,12 @@ class Link extends React.Component {
           skipClientNav: skipClientNav,
           href: href,
           target: target,
-          tabIndex: tabIndex
+          tabIndex: tabIndex,
+          inline: inline,
+          kind: kind,
+          light: light,
+          visitable: visitable,
+          ref: ref
         }), children);
       });
     } else {
@@ -256,20 +255,17 @@ class Link extends React.Component {
           skipClientNav: skipClientNav,
           href: href,
           target: target,
-          tabIndex: tabIndex
+          tabIndex: tabIndex,
+          inline: inline,
+          kind: kind,
+          light: light,
+          visitable: visitable,
+          ref: ref
         }), children);
       });
     }
-  }
-  render() {
-    return React.createElement(__RouterContext.Consumer, null, router => this.renderClickableBehavior(router));
-  }
-}
-Link.defaultProps = {
-  inline: false,
-  kind: "primary",
-  light: false,
-  visitable: false
-};
+  };
+  return React.createElement(__RouterContext.Consumer, null, router => renderClickableBehavior(router));
+});
 
 export { Link as default };