@khanacademy/wonder-blocks-tooltip 1.3.21 → 1.3.22

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @khanacademy/wonder-blocks-tooltip
 
+## 1.3.22
+
+### Patch Changes
+
+-   Updated dependencies [13cdc7fe]
+    -   @khanacademy/wonder-blocks-modal@3.0.0
+
 ## 1.3.21
 
 ### Patch Changes

package/dist/index.js

@@ -540,6 +540,16 @@ const styles = aphrodite__WEBPACK_IMPORTED_MODULE_1__["StyleSheet"].create({
 /**
  * This component is used to provide the content that is to be rendered in the
  * tooltip bubble.
+ *
+ * ### Usage
+ *
+ * ```jsx
+ * import {TooltipContent} from "@khanacademy/wonder-blocks-tooltip";
+ *
+ * <TooltipContent title="Title text!">
+ *  Some content in my tooltip.
+ * </TooltipContent>
+ * ```
  */
 class TooltipContent extends react__WEBPACK_IMPORTED_MODULE_0__["Component"] {
   _renderTitle() {
@@ -800,6 +810,31 @@ class RefTracker {
 
 
 
+
+/**
+ * Use a tooltip to help describe an on screen object.
+ *
+ * Tooltips:
+ *  - contain text
+ *  - (optional) contain small graphic elements to complement the text
+ *  - appear on hover or focus (for non-assistive tech keyboard users)
+ *  - must have a tail that points to a parent object
+ *  - DO NOT include actions
+ *
+ * For more rich content see Popovers, for taking action on an object, see
+ * Snackbars (proposed).
+ *
+ * ### Usage
+ *
+ * ```jsx
+ * import Tooltip from "@khanacademy/wonder-blocks-tooltip";
+ *
+ * <Tooltip content="This is a text tooltip">
+ *  Tooltip anchor
+ * </Tooltip>
+ * ```
+ *
+ */
 class Tooltip extends react__WEBPACK_IMPORTED_MODULE_0__["Component"] {
   constructor(...args) {
     super(...args);

package/docs.md

@@ -1,11 +1,4 @@
-Use a tooltip to help describe an on screen object.
+Documentation for `@khanacademy/wonder-blocks-tooltip` is now in Storybook.
 
-Tooltips:
-
-- contain text
-- (optional) contain small graphic elements to complement the text
-- appear on hover or focus (for non-assistive tech keyboard users)
-- must have a tail that points to a parent object
-- DO NOT include actions
-
-For more rich content see Popovers, for taking action on an object, see Snackbars (proposed).
+Visit the [Storybook
+Tooltip](https://khan.github.io/wonder-blocks/?path=/docs/tooltip) docs on GitHub Pages.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanacademy/wonder-blocks-tooltip",
-  "version": "1.3.21",
+  "version": "1.3.22",
   "design": "v1",
   "publishConfig": {
     "access": "public"
@@ -19,7 +19,7 @@
     "@khanacademy/wonder-blocks-color": "^1.2.0",
     "@khanacademy/wonder-blocks-core": "^4.5.0",
     "@khanacademy/wonder-blocks-layout": "^1.4.12",
-    "@khanacademy/wonder-blocks-modal": "^2.3.11",
+    "@khanacademy/wonder-blocks-modal": "^3.0.0",
     "@khanacademy/wonder-blocks-spacing": "^3.0.5",
     "@khanacademy/wonder-blocks-typography": "^1.1.34"
   },

package/src/components/__docs__/tooltip-content.stories.js

@@ -0,0 +1,89 @@
+// @flow
+import * as React from "react";
+import {TooltipContent} from "@khanacademy/wonder-blocks-tooltip";
+import {Body, LabelSmall} from "@khanacademy/wonder-blocks-typography";
+
+import type {StoryComponentType} from "@storybook/react";
+
+import ComponentInfo from "../../../../../.storybook/components/component-info.js";
+import {name, version} from "../../../package.json";
+
+export default {
+    title: "Tooltip / TooltipContent",
+    component: TooltipContent,
+    parameters: {
+        componentSubtitle: ((
+            <ComponentInfo name={name} version={version} />
+        ): any),
+    },
+};
+
+const Template = (args) => <TooltipContent {...args} />;
+
+/**
+ * Default example (interactive).
+ */
+export const Default: StoryComponentType = Template.bind({});
+
+Default.args = {
+    title: "A Tooltip with a title",
+    children: "some text",
+};
+
+/**
+ * Only text content
+ */
+export const OnlyTextContent: StoryComponentType = Template.bind({});
+
+OnlyTextContent.args = {
+    children: "Only the content",
+};
+
+OnlyTextContent.parameters = {
+    docs: {
+        description: {
+            story: "This shows the default which is text rendered using `LabelMedium`.",
+        },
+    },
+};
+
+/**
+ * Titled content
+ */
+export const TitledContent: StoryComponentType = Template.bind({});
+
+TitledContent.args = {
+    title: "This tooltip has a title",
+    children: "Some content in my tooltip",
+};
+
+TitledContent.parameters = {
+    docs: {
+        description: {
+            story: "This shows the default with a title; the title is rendered using `HeadingSmall`.",
+        },
+    },
+};
+
+/**
+ * Custom title and custom content
+ */
+export const CustomContent: StoryComponentType = Template.bind({});
+
+CustomContent.args = {
+    title: <Body>Body text title!</Body>,
+    children: (
+        <>
+            <Body>Body text content!</Body>
+            <LabelSmall>And LabelSmall!</LabelSmall>
+        </>
+    ),
+};
+
+CustomContent.parameters = {
+    docs: {
+        description: {
+            story: "This shows how we can customize both the title and the content.",
+        },
+    },
+};

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

@@ -0,0 +1,15 @@
+// @flow
+
+export default {
+    placement: {
+        control: {
+            type: "select",
+            options: ["top", "bottom", "right", "left"],
+        },
+    },
+    title: {
+        control: {
+            type: "text",
+        },
+    },
+};

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

@@ -0,0 +1,245 @@
+// @flow
+import * as React from "react";
+import {StyleSheet} from "aphrodite";
+import Button from "@khanacademy/wonder-blocks-button";
+import Color from "@khanacademy/wonder-blocks-color";
+import {View} from "@khanacademy/wonder-blocks-core";
+import {TextField} from "@khanacademy/wonder-blocks-form";
+import IconButton from "@khanacademy/wonder-blocks-icon-button";
+import {icons} from "@khanacademy/wonder-blocks-icon";
+import {OnePaneDialog, ModalLauncher} from "@khanacademy/wonder-blocks-modal";
+import Spacing from "@khanacademy/wonder-blocks-spacing";
+import Tooltip from "@khanacademy/wonder-blocks-tooltip";
+import {Body} from "@khanacademy/wonder-blocks-typography";
+
+import type {StoryComponentType} from "@storybook/react";
+import TooltipArgtypes from "./tooltip.argtypes.js";
+
+import ComponentInfo from "../../../../../.storybook/components/component-info.js";
+import {name, version} from "../../../package.json";
+
+export default {
+    title: "Tooltip / Tooltip",
+    component: Tooltip,
+    argTypes: TooltipArgtypes,
+    args: {
+        forceAnchorFocusivity: true,
+        placement: "top",
+    },
+    parameters: {
+        // TODO(WB-1170): Reassess this after investigating more about Chromatic
+        // flakyness.
+        chromatic: {
+            disableSnapshot: true,
+        },
+        componentSubtitle: ((
+            <ComponentInfo name={name} version={version} />
+        ): any),
+    },
+};
+
+const Template = (args) => <Tooltip {...args} />;
+
+/**
+ * Default example (interactive).
+ */
+export const Default: StoryComponentType = Template.bind({});
+
+Default.args = {
+    content: "This is a text tooltip on the top",
+    children: "some text",
+};
+
+/**
+ * Complex anchor & title tooltip
+ */
+export const ComplexAnchorAndTitle: StoryComponentType = Template.bind({});
+
+ComplexAnchorAndTitle.args = {
+    forceAnchorFocusivity: false,
+    id: "my-a11y-tooltip",
+    title: "This tooltip has a title",
+    content: "I'm at the top!",
+    children: (
+        <View>
+            Some text
+            <TextField
+                aria-describedby="my-a11y-tooltip"
+                id=""
+                onChange={() => {}}
+                value=""
+            />
+        </View>
+    ),
+};
+
+ComplexAnchorAndTitle.parameters = {
+    docs: {
+        description: {
+            story: "In this example, we're no longer forcing the anchor root to be focusable, since the text input can take focus. However, that needs a custom accessibility implementation too (for that, we should use `UniqueIDProvider`, but we'll cheat here and give our own identifier).",
+        },
+    },
+};
+
+/**
+ * Anchor in scrollable parent & placement bottom
+ */
+export const AnchorInScrollableParent: StoryComponentType = () => (
+    <View style={styles.scrollbox}>
+        <View style={styles.hostbox}>
+            <Body>
+                This is a big long piece of text with a
+                <Tooltip
+                    content="This tooltip will disappear when scrolled out of bounds"
+                    placement="bottom"
+                >
+                    [tooltip]
+                </Tooltip>{" "}
+                in the middle.
+            </Body>
+        </View>
+    </View>
+);
+
+AnchorInScrollableParent.parameters = {
+    docs: {
+        description: {
+            story: "In this example, we have the anchor in a scrollable parent. Notice how, when the anchor is focused but scrolled out of bounds, the tooltip disappears.",
+        },
+    },
+};
+
+/**
+ * Tooltip in a modal
+ */
+export const TooltipInModal: StoryComponentType = () => {
+    const scrollyContent = (
+        <View style={styles.scrollbox}>
+            <View style={styles.hostbox}>
+                <Tooltip content="I'm on the left!" placement="left">
+                    tooltip
+                </Tooltip>
+            </View>
+        </View>
+    );
+
+    const modal = (
+        <OnePaneDialog
+            title="My modal"
+            footer="Still my modal"
+            content={<View style={styles.modalbox}>{scrollyContent}</View>}
+        />
+    );
+
+    return (
+        <ModalLauncher modal={modal}>
+            {({openModal}) => <Button onClick={openModal}>Click here!</Button>}
+        </ModalLauncher>
+    );
+};
+
+TooltipInModal.parameters = {
+    docs: {
+        description: {
+            story: "This checks that the tooltip works how we want inside a modal. Click the button to take a look.",
+        },
+    },
+};
+
+/**
+ * Tooltips side-by-side
+ */
+export const SideBySide: StoryComponentType = () => (
+    <View style={styles.row}>
+        <Tooltip content="Tooltip A" placement="bottom">
+            <View style={styles.block}>A</View>
+        </Tooltip>
+        <Tooltip content="Tooltip B" placement="bottom">
+            <View style={styles.block}>B</View>
+        </Tooltip>
+        <Tooltip content="Tooltip C" placement="bottom">
+            <View style={styles.block}>C</View>
+        </Tooltip>
+        <Tooltip content="Tooltip D" placement="bottom">
+            <View style={styles.block}>D</View>
+        </Tooltip>
+    </View>
+);
+
+SideBySide.storyName = "Side-by-side";
+
+SideBySide.parameters = {
+    docs: {
+        description: {
+            story: "Here, we can see that the first tooltip shown has an initial delay before it appears, as does the last tooltip shown, yet when moving between tooltipped items, the transition from one to another is instantaneous.",
+        },
+    },
+};
+
+/**
+ * Tooltips on buttons
+ */
+export const TooltipOnButtons: StoryComponentType = () => {
+    return (
+        <View style={[styles.centered, styles.row]}>
+            <Tooltip content={"This is a tooltip on a button."}>
+                <Button disabled={false}>Example 1</Button>
+            </Tooltip>
+            <Tooltip
+                content="This is a tooltip on a disabled button."
+                placement="bottom"
+            >
+                <Button disabled={true}>Example 2</Button>
+            </Tooltip>
+            <Tooltip content="Short and stout">
+                <IconButton
+                    icon={icons.search}
+                    aria-label="search"
+                    onClick={() => {}}
+                />
+            </Tooltip>
+        </View>
+    );
+};
+
+TooltipOnButtons.parameters = {
+    chromatic: {
+        disableSnapshot: true,
+    },
+    docs: {
+        description: {
+            story: "This example shows tooltips on different types of buttons.",
+        },
+    },
+};
+
+const styles = StyleSheet.create({
+    row: {
+        flexDirection: "row",
+    },
+    centered: {
+        alignItems: "center",
+        justifyContent: "center",
+        gap: Spacing.medium_16,
+        padding: Spacing.xxLarge_48,
+    },
+    scrollbox: {
+        height: 100,
+        overflow: "auto",
+        border: "1px solid black",
+        margin: Spacing.small_12,
+    },
+    hostbox: {
+        minHeight: "200vh",
+    },
+    modalbox: {
+        height: "200vh",
+    },
+    block: {
+        border: `solid 1px ${Color.lightBlue}`,
+        width: Spacing.xLarge_32,
+        height: Spacing.xLarge_32,
+        alignItems: "center",
+        justifyContent: "center",
+    },
+});

package/src/components/tooltip-content.js

@@ -28,6 +28,16 @@ type Props = {|
 /**
  * This component is used to provide the content that is to be rendered in the
  * tooltip bubble.
+ *
+ * ### Usage
+ *
+ * ```jsx
+ * import {TooltipContent} from "@khanacademy/wonder-blocks-tooltip";
+ *
+ * <TooltipContent title="Title text!">
+ *  Some content in my tooltip.
+ * </TooltipContent>
+ * ```
  */
 export default class TooltipContent extends React.Component<Props> {
     _renderTitle(): React.Node {

package/src/components/tooltip.js

@@ -122,6 +122,30 @@ type DefaultProps = {|
     placement: $PropertyType<Props, "placement">,
 |};
 
+/**
+ * Use a tooltip to help describe an on screen object.
+ *
+ * Tooltips:
+ *  - contain text
+ *  - (optional) contain small graphic elements to complement the text
+ *  - appear on hover or focus (for non-assistive tech keyboard users)
+ *  - must have a tail that points to a parent object
+ *  - DO NOT include actions
+ *
+ * For more rich content see Popovers, for taking action on an object, see
+ * Snackbars (proposed).
+ *
+ * ### Usage
+ *
+ * ```jsx
+ * import Tooltip from "@khanacademy/wonder-blocks-tooltip";
+ *
+ * <Tooltip content="This is a text tooltip">
+ *  Tooltip anchor
+ * </Tooltip>
+ * ```
+ *
+ */
 export default class Tooltip extends React.Component<Props, State> {
     static defaultProps: DefaultProps = {
         forceAnchorFocusivity: true,