@khanacademy/wonder-blocks-clickable 3.1.3 → 4.0.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @khanacademy/wonder-blocks-clickable
 
+## 4.0.1
+
+### Patch Changes
+
+-   f230b267: Allow 'safeWithNav()' to be used on its own without 'beforeNav()' in prop types
+
+## 4.0.0
+
+### Major Changes
+
+-   674a1e5c: Props are using discriminated union types to prevent invalid combinations of props
+
+### Minor Changes
+
+-   8c77f29d: Create new Switch component and add 'switch' role to ClickableRole
+
+### Patch Changes
+
+-   674a1e5c: We're no longer building flow types
+-   Updated dependencies [674a1e5c]
+-   Updated dependencies [674a1e5c]
+    -   @khanacademy/wonder-blocks-core@6.0.0
+
 ## 3.1.3
 
 ### Patch Changes

package/dist/components/clickable-behavior.d.ts

@@ -1,6 +1,6 @@
 import * as React from "react";
-export type ClickableRole = "button" | "link" | "checkbox" | "radio" | "listbox" | "option" | "menuitem" | "menu" | "tab";
-type Props = Readonly<{
+export type ClickableRole = "button" | "checkbox" | "link" | "listbox" | "menu" | "menuitem" | "option" | "radio" | "switch" | "tab";
+type CommonProps = Readonly<{
     /**
      * A function that returns the a React `Element`.
      *
@@ -74,11 +74,15 @@ type Props = Readonly<{
      * Respond to raw "keyup" event.
      */
     onKeyUp?: (e: React.KeyboardEvent) => unknown;
+}>;
+type Props = (CommonProps & Readonly<{
     /**
      * A target destination window for a link to open in. Should only be used
      * when `href` is specified.
      */
     target?: "_blank";
+    beforeNav?: never;
+}>) | (CommonProps & Readonly<{
     /**
      * Run async code before navigating to the URL passed to `href`. If the
      * promise returned rejects then navigation will not occur.
@@ -93,7 +97,8 @@ type Props = Readonly<{
      * navigation.
      */
     beforeNav?: () => Promise<unknown>;
-}>;
+    target?: never;
+}>);
 export type ClickableState = Readonly<{
     /**
      * Whether the component is hovered.

package/dist/components/clickable.d.ts

@@ -2,55 +2,28 @@ import * as React from "react";
 import { Link } from "react-router-dom";
 import type { AriaProps, StyleType } from "@khanacademy/wonder-blocks-core";
 import type { ClickableRole, ClickableState } from "./clickable-behavior";
+type CommonProps = 
 /**
- * A component to turn any custom component into a clickable one.
- *
- * Works by wrapping `ClickableBehavior` around the child element and styling
- * the child appropriately and encapsulates routing logic which can be
- * customized. Expects a function which returns an element as its child.
- *
- * Clickable allows your components to:
- *
- * - Handle mouse / touch / keyboard events
- * - Match the standard behavior of the given role
- * - Apply custom styles based on pressed / focused / hovered state
- * - Perform Client Side Navigation when href is passed and the component is a
- *   descendent of a react-router Router.
- *
- * ### Usage
- *
- * ```jsx
- * <Clickable onClick={() => alert("You clicked me!")}>
- *     {({hovered, focused, pressed}) =>
- *         <div
- *             style={[
- *                 hovered && styles.hovered,
- *                 focused && styles.focused,
- *                 pressed && styles.pressed,
- *             ]}
- *         >
- *             Click Me!
- *         </div>
- *     }
- * </Clickable>
- * ```
+ * aria-label should be used when `spinner={true}` to let people using screen
+ * readers that the action taken by clicking the button will take some
+ * time to complete.
  */
-declare const Clickable: React.ForwardRefExoticComponent<Partial<Omit<AriaProps, "aria-disabled">> & {
+Partial<Omit<AriaProps, "aria-disabled">> & {
     /**
      * The child of Clickable must be a function which returns the component
      * which should be made Clickable.  The function is passed an object with
      * three boolean properties: hovered, focused, and pressed.
      */
-    children: (arg1: ClickableState) => React.ReactNode;
+    children: (clickableState: ClickableState) => React.ReactNode;
     /**
      * An onClick function which Clickable can execute when clicked
      */
-    onClick?: ((e: React.SyntheticEvent) => unknown) | undefined;
+    onClick?: (e: React.SyntheticEvent) => unknown;
     /**
      * Optional href which Clickable should direct to, uses client-side routing
      * by default if react-router is present
      */
-    href?: string | undefined;
+    href?: string;
     /**
      * Styles to apply to the Clickable component
      */
@@ -58,63 +31,57 @@ declare const Clickable: React.ForwardRefExoticComponent<Partial<Omit<AriaProps,
     /**
      * Adds CSS classes to the Clickable.
      */
-    className?: string | undefined;
+    className?: string;
     /**
      * Whether the Clickable is on a dark colored background.
      * Sets the default focus ring color to white, instead of blue.
      * Defaults to false.
      */
-    light?: boolean | undefined;
+    light?: boolean;
     /**
      * Disables or enables the child; defaults to false
      */
-    disabled?: boolean | undefined;
+    disabled?: boolean;
     /**
      * An optional id attribute.
      */
-    id?: string | undefined;
+    id?: string;
     /**
      * 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;
+    rel?: string;
     /**
      * The role of the component, can be a role of type ClickableRole
      */
-    role?: ClickableRole | undefined;
+    role?: ClickableRole;
     /**
      * Avoids client-side routing in the presence of the href prop
      */
-    skipClientNav?: boolean | undefined;
+    skipClientNav?: boolean;
     /**
      * Test ID used for e2e testing.
      */
-    testId?: string | undefined;
+    testId?: string;
     /**
      * Respond to raw "keydown" event.
      */
-    onKeyDown?: ((e: React.KeyboardEvent) => unknown) | undefined;
+    onKeyDown?: (e: React.KeyboardEvent) => unknown;
     /**
      * Respond to raw "keyup" event.
      */
-    onKeyUp?: ((e: React.KeyboardEvent) => unknown) | undefined;
+    onKeyUp?: (e: React.KeyboardEvent) => unknown;
     /**
      * Don't show the default focus ring.  This should be used when implementing
      * a custom focus ring within your own component that uses Clickable.
      */
-    hideDefaultFocusRing?: boolean | undefined;
-    /**
-     * A target destination window for a link to open in.
-     *
-     * TODO(WB-1262): only allow this prop when `href` is also set.t
-     */
-    target?: "_blank" | undefined;
+    hideDefaultFocusRing?: boolean;
     /**
      * Set the tabindex attribute on the rendered element.
      */
-    tabIndex?: number | undefined;
+    tabIndex?: number;
     /**
      * Run async code before navigating. If the promise returned rejects then
      * navigation will not occur.
@@ -125,13 +92,84 @@ declare const Clickable: React.ForwardRefExoticComponent<Partial<Omit<AriaProps,
      * WARNING: This prop must be used with `href` and should not be used with
      * `target="blank"`.
      */
-    beforeNav?: (() => Promise<unknown>) | undefined;
+    beforeNav?: () => Promise<unknown>;
+    /**
+     * 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>;
+};
+type Props = (CommonProps & {
+    target?: never;
+    beforeNav?: never;
+    safeWithNav?: never;
+}) | (CommonProps & {
+    href: string;
+    /**
+     * 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>;
+    /**
+     * A target destination window for a link to open in.
+     */
+    target?: "_blank";
+    beforeNav?: never;
+}) | (CommonProps & {
+    href: string;
+    /**
+     * Run async code before navigating. 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.
+     */
+    beforeNav?: () => Promise<unknown>;
     /**
      * 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;
-} & React.RefAttributes<HTMLAnchorElement | HTMLButtonElement | typeof Link>>;
+    safeWithNav?: () => Promise<unknown>;
+    target?: never;
+});
+/**
+ * A component to turn any custom component into a clickable one.
+ *
+ * Works by wrapping `ClickableBehavior` around the child element and styling
+ * the child appropriately and encapsulates routing logic which can be
+ * customized. Expects a function which returns an element as its child.
+ *
+ * Clickable allows your components to:
+ *
+ * - Handle mouse / touch / keyboard events
+ * - Match the standard behavior of the given role
+ * - Apply custom styles based on pressed / focused / hovered state
+ * - Perform Client Side Navigation when href is passed and the component is a
+ *   descendent of a react-router Router.
+ *
+ * ### Usage
+ *
+ * ```jsx
+ * <Clickable onClick={() => alert("You clicked me!")}>
+ *     {({hovered, focused, pressed}) =>
+ *         <div
+ *             style={[
+ *                 hovered && styles.hovered,
+ *                 focused && styles.focused,
+ *                 pressed && styles.pressed,
+ *             ]}
+ *         >
+ *             Click Me!
+ *         </div>
+ *     }
+ * </Clickable>
+ * ```
+ */
+declare const Clickable: React.ForwardRefExoticComponent<Props & React.RefAttributes<HTMLAnchorElement | HTMLButtonElement | typeof Link>>;
 export default Clickable;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanacademy/wonder-blocks-clickable",
-  "version": "3.1.3",
+  "version": "4.0.1",
   "design": "v1",
   "description": "Clickable component for Wonder-Blocks.",
   "main": "dist/index.js",
@@ -17,7 +17,7 @@
   "dependencies": {
     "@babel/runtime": "^7.18.6",
     "@khanacademy/wonder-blocks-color": "^2.0.1",
-    "@khanacademy/wonder-blocks-core": "^5.4.0"
+    "@khanacademy/wonder-blocks-core": "^6.0.0"
   },
   "peerDependencies": {
     "aphrodite": "^1.2.5",
@@ -27,6 +27,6 @@
     "react-router-dom": "5.3.0"
   },
   "devDependencies": {
-    "wb-dev-build-settings": "^0.9.7"
+    "@khanacademy/wb-dev-build-settings": "^1.0.0"
   }
 }

package/src/components/__tests__/clickable-behavior.typestest.tsx

@@ -0,0 +1,20 @@
+import * as React from "react";
+
+import ClickableBehavior from "../clickable-behavior";
+
+<ClickableBehavior>
+    {(_, childrenProps) => <div {...childrenProps} />}
+</ClickableBehavior>;
+
+<ClickableBehavior target="_blank">
+    {(_, childrenProps) => <div {...childrenProps} />}
+</ClickableBehavior>;
+
+<ClickableBehavior beforeNav={() => Promise.resolve()}>
+    {(_, childrenProps) => <div {...childrenProps} />}
+</ClickableBehavior>;
+
+// @ts-expect-error `target` and `beforeNav` can't be used together.
+<ClickableBehavior target="_blank" beforeNav={() => Promise.resolve()}>
+    {(_, childrenProps) => <div {...childrenProps} />}
+</ClickableBehavior>;

package/src/components/__tests__/clickable.typestest.tsx

@@ -0,0 +1,49 @@
+import * as React from "react";
+
+import Clickable from "../clickable";
+
+<Clickable>{(_) => "Hello, world!"}</Clickable>;
+
+<Clickable href="/foo">{(_) => "Hello, world!"}</Clickable>;
+
+<Clickable href="/foo" target="_blank">
+    {(_) => "Hello, world!"}
+</Clickable>;
+
+// @ts-expect-error - `href` must be set when using `target="_blank"`.
+<Clickable target="_blank">{(_) => "Hello, world!"}</Clickable>;
+
+<Clickable href="/foo" beforeNav={() => Promise.resolve()}>
+    {(_) => "Hello, world!"}
+</Clickable>;
+
+<Clickable href="/foo" safeWithNav={() => Promise.resolve()}>
+    {(_) => "Hello, world!"}
+</Clickable>;
+
+<Clickable href="/foo" target="_blank" safeWithNav={() => Promise.resolve()}>
+    {(_) => "Hello, world!"}
+</Clickable>;
+
+// @ts-expect-error - `target="_blank"` cannot be used with `beforeNav`.
+<Clickable href="/foo" target="_blank" beforeNav={() => Promise.resolve()}>
+    {(_) => "Hello, world!"}
+</Clickable>;
+
+// @ts-expect-error - `target="_blank"` cannot be used with `beforeNav`.
+<Clickable
+    href="/foo"
+    target="_blank"
+    beforeNav={() => Promise.resolve()}
+    safeWithNav={() => Promise.resolve()}
+>
+    {(_) => "Hello, world!"}
+</Clickable>;
+
+<Clickable
+    href="/foo"
+    beforeNav={() => Promise.resolve()}
+    safeWithNav={() => Promise.resolve()}
+>
+    {(_) => "Hello, world!"}
+</Clickable>;

package/src/components/clickable-behavior.ts

@@ -3,13 +3,14 @@ import * as React from "react";
 // NOTE: Potentially add to this as more cases come up.
 export type ClickableRole =
     | "button"
-    | "link"
     | "checkbox"
-    | "radio"
+    | "link"
     | "listbox"
-    | "option"
-    | "menuitem"
     | "menu"
+    | "menuitem"
+    | "option"
+    | "radio"
+    | "switch"
     | "tab";
 
 const getAppropriateTriggersForRole = (role?: ClickableRole | null) => {
@@ -41,8 +42,7 @@ const getAppropriateTriggersForRole = (role?: ClickableRole | null) => {
     }
 };
 
-// TODO(FEI-5000): Convert back to conditional props after TS migration is complete.
-type Props = Readonly<{
+type CommonProps = Readonly<{
     /**
      * A function that returns the a React `Element`.
      *
@@ -119,28 +119,40 @@ type Props = Readonly<{
      * Respond to raw "keyup" event.
      */
     onKeyUp?: (e: React.KeyboardEvent) => unknown;
-    /**
-     * A target destination window for a link to open in. Should only be used
-     * when `href` is specified.
-     */
-    // TODO(WB-1262): only allow this prop when `href` is also set.
-    target?: "_blank";
-    /**
-     * 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>;
 }>;
 
+type Props =
+    | (CommonProps &
+          Readonly<{
+              /**
+               * A target destination window for a link to open in. Should only be used
+               * when `href` is specified.
+               */
+              // TODO(WB-1262): only allow this prop when `href` is also set.
+              target?: "_blank";
+
+              beforeNav?: never; // disallow beforeNav when target="_blank"
+          }>)
+    | (CommonProps &
+          Readonly<{
+              /**
+               * 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>;
+
+              target?: never; // disallow target="_blank" when beforeNav is set
+          }>);
+
 export type ClickableState = Readonly<{
     /**
      * Whether the component is hovered.

package/src/components/clickable.tsx

@@ -11,8 +11,7 @@ import getClickableBehavior from "../util/get-clickable-behavior";
 import type {ClickableRole, ClickableState} from "./clickable-behavior";
 import {isClientSideUrl} from "../util/is-client-side-url";
 
-// TODO(FEI-5000): Convert back to conditional props after TS migration is complete.
-type Props =
+type CommonProps =
     /**
      * aria-label should be used when `spinner={true}` to let people using screen
      * readers that the action taken by clicking the button will take some
@@ -24,7 +23,7 @@ type Props =
          * which should be made Clickable.  The function is passed an object with
          * three boolean properties: hovered, focused, and pressed.
          */
-        children: (arg1: ClickableState) => React.ReactNode;
+        children: (clickableState: ClickableState) => React.ReactNode;
         /**
          * An onClick function which Clickable can execute when clicked
          */
@@ -88,12 +87,6 @@ type Props =
          * a custom focus ring within your own component that uses Clickable.
          */
         hideDefaultFocusRing?: boolean;
-        /**
-         * A target destination window for a link to open in.
-         *
-         * TODO(WB-1262): only allow this prop when `href` is also set.t
-         */
-        target?: "_blank";
         /**
          * Set the tabindex attribute on the rendered element.
          */
@@ -118,6 +111,53 @@ type Props =
         safeWithNav?: () => Promise<unknown>;
     };
 
+type Props =
+    | (CommonProps & {
+          target?: never;
+          beforeNav?: never;
+          safeWithNav?: never;
+      })
+    | (CommonProps & {
+          href: string;
+
+          /**
+           * 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>;
+
+          /**
+           * A target destination window for a link to open in.
+           */
+          target?: "_blank";
+
+          beforeNav?: never;
+      })
+    | (CommonProps & {
+          href: string;
+
+          /**
+           * Run async code before navigating. 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.
+           */
+          beforeNav?: () => Promise<unknown>;
+
+          /**
+           * 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>;
+
+          target?: never;
+      });
+
 const StyledAnchor = addStyle("a");
 const StyledButton = addStyle("button");
 const StyledLink = addStyle(Link);