@thecb/components 12.0.0-beta.0 → 12.0.0-beta.2

package/src/components/molecules/tooltip/Tooltip.js

@@ -0,0 +1,269 @@
+import React, { useContext, useEffect, useRef, useState } from "react";
+import { createThemeValues } from "../../../util/themeUtils";
+import { WHITE } from "../../../constants/colors";
+import { ThemeContext } from "styled-components";
+import Text from "../../atoms/text";
+import { Box } from "../../atoms/layouts";
+import ButtonWithAction from "../../atoms/button-with-action";
+import { noop, arrowBorder } from "../../../util/general";
+import { fallbackValues } from "./Tooltip.theme";
+
+const TOOLTIP_THEME_SOURCE = "Popover";
+
+const Tooltip = ({
+  tooltipID,
+  children,
+  hasCustomTrigger = false,
+  triggerText = "",
+  containerExtraStyles = "",
+  triggerButtonVariant = "smallGhost",
+  content = "",
+  contentExtraStyles = "",
+  minWidth = "250px",
+  maxWidth = "100%",
+  height = "auto",
+  contentPosition = {
+    top: "-110px",
+    right: "auto",
+    bottom: "auto",
+    left: "-225px"
+  },
+  arrowDirection = "down",
+  arrowPosition = {
+    arrowTop: "auto",
+    arrowRight: "10px",
+    arrowBottom: "-8px",
+    arrowLeft: "auto"
+  },
+  customTriggerRole,
+  backgroundColor = WHITE
+}) => {
+  /**
+   * closeTimeoutRef is used internally to store a timer ID for delaying tooltip close. It will have a `.current` property (the timer ID) when the effect or event handlers set it.
+   */
+  const closeTimeoutRef = useRef(null);
+  /**
+   * containerRef is used to store a reference to the container element. It will have a `.current` property (the container element) when the effect or event handlers set it.
+   */
+  const containerRef = useRef(null);
+
+  const [tooltipOpen, setTooltipOpen] = useState(false);
+  const themeContext = useContext(ThemeContext);
+  const themeValues = createThemeValues(
+    themeContext,
+    fallbackValues,
+    TOOLTIP_THEME_SOURCE
+  );
+
+  const { top, right, bottom, left } = contentPosition;
+  const { arrowTop, arrowRight, arrowBottom, arrowLeft } = arrowPosition;
+
+  const handleToggleTooltip = desiredState => {
+    if (tooltipOpen !== desiredState) {
+      setTooltipOpen(desiredState);
+    }
+  };
+
+  const handleKeyDown = e => {
+    if (e.key === "Escape") {
+      handleToggleTooltip(false);
+    }
+  };
+
+  /**
+   * @function renderTrigger
+   * Renders the tooltip trigger element.
+   *
+   * When `hasCustomTrigger` is true, the provided child element is cloned and
+   * injected with the event handlers needed to control tooltip visibility:
+   *  - onFocus/onBlur: open and close for keyboard users
+   *  - onKeyDown: allows Escape to dismiss the tooltip
+   *  - onTouchStart: open on tap for touch/mobile users (onFocus is unreliable on touch)
+   *
+   * Mouse interactions (hover) are handled at the container level via
+   * onMouseEnter/onMouseLeave, so they do not need to be injected here.
+   *
+   * Any existing event handlers on the child are preserved and called first,
+   * so the child's own behavior is not overridden.
+   *
+   * When no custom trigger is provided, a default ButtonWithAction is rendered
+   * using `triggerText` and `triggerButtonVariant`.
+   */
+  const renderTrigger = () => {
+    if (hasCustomTrigger && !children) {
+      console.warn(
+        "Tooltip: children prop is required when hasCustomTrigger is true"
+      );
+    }
+
+    if (hasCustomTrigger && children) {
+      const child = React.Children.only(children);
+      /**
+       * Capture the child's existing handlers before overwriting
+       */
+      const {
+        onFocus: childOnFocus,
+        onBlur: childOnBlur,
+        onKeyDown: childOnKeyDown,
+        onTouchStart: childOnTouchStart
+      } = child.props ?? {};
+
+      /**
+       * Clone the child element and add the necessary event handlers
+       */
+      return React.cloneElement(child, {
+        tabIndex: child.props?.tabIndex ?? 0,
+        ariaDescribedby: tooltipID,
+        style: { cursor: `pointer`, ...child.props?.style },
+        onFocus: e => {
+          childOnFocus?.(e);
+          handleToggleTooltip(true);
+        },
+        onBlur: e => {
+          childOnBlur?.(e);
+          handleToggleTooltip(false);
+        },
+        onKeyDown: e => {
+          childOnKeyDown?.(e);
+          handleKeyDown(e);
+        },
+        onTouchStart: e => {
+          childOnTouchStart?.(e);
+          handleToggleTooltip(true);
+        },
+        role: customTriggerRole || child.props?.role,
+        "aria-describedby": tooltipID,
+        "data-qa": `tooltip-trigger-${tooltipID}`
+      });
+    } else {
+      return (
+        <ButtonWithAction
+          action={noop}
+          onKeyDown={handleKeyDown}
+          variant={triggerButtonVariant}
+          text={triggerText}
+          tabIndex={0}
+          aria-describedby={tooltipID}
+          onFocus={() => handleToggleTooltip(true)}
+          onBlur={() => handleToggleTooltip(false)}
+          onTouchStart={() => handleToggleTooltip(true)}
+          dataQa={`tooltip-trigger-${tooltipID}`}
+          extraStyles={`
+            color: ${themeValues.linkColor};
+            &:hover { color: ${themeValues.hoverColor}; text-decoration: none;}
+            &:active, &:focus { color: ${themeValues.activeColor};text-decoration: none;}
+            button, span, &:hover span { text-decoration: none; }
+          `}
+        />
+      );
+    }
+  };
+
+  /**
+   * @function handleMouseEnter
+   * Handles the mouse enter event for the tooltip container.
+   * It clears any existing timeout and opens the tooltip.
+   */
+  const handleMouseEnter = () => {
+    if (closeTimeoutRef.current) {
+      clearTimeout(closeTimeoutRef.current);
+      closeTimeoutRef.current = null;
+    }
+    handleToggleTooltip(true);
+  };
+
+  /**
+   * @function handleMouseLeave
+   * Handles the mouse leave event for the tooltip container.
+   * It sets a timeout to close the tooltip after 200ms.
+   */
+  const handleMouseLeave = () => {
+    closeTimeoutRef.current = setTimeout(() => {
+      handleToggleTooltip(false);
+    }, 200);
+  };
+
+  /**
+   * Handles the touch start event for the tooltip container.
+   * It closes the tooltip if the touch is outside the container.
+   */
+  useEffect(() => {
+    if (!tooltipOpen) return;
+
+    const handleOutsideTouch = e => {
+      if (containerRef.current && !containerRef.current.contains(e.target)) {
+        setTooltipOpen(false);
+      }
+    };
+    document.addEventListener("touchstart", handleOutsideTouch);
+    return () => document.removeEventListener("touchstart", handleOutsideTouch);
+  }, [tooltipOpen]);
+
+  /**
+   * Cleans up the timeout when the component unmounts.
+   */
+  useEffect(() => {
+    return () => {
+      if (closeTimeoutRef?.current) clearTimeout(closeTimeoutRef.current);
+    };
+  }, []);
+
+  return (
+    <Box
+      ref={containerRef}
+      padding="0"
+      extraStyles={`position: relative; ${containerExtraStyles}`}
+      onMouseEnter={handleMouseEnter}
+      onMouseLeave={handleMouseLeave}
+      data-qa={`${tooltipID}-container`}
+    >
+      {renderTrigger()}
+      <Box
+        role="tooltip"
+        id={tooltipID}
+        aria-hidden={!tooltipOpen}
+        background={backgroundColor}
+        data-qa="tooltip-contents"
+        extraStyles={`
+          position: absolute;
+          display: ${tooltipOpen ? "block" : "none"};
+          top: ${top};
+          right: ${right};
+          bottom: ${bottom};
+          left: ${left};
+          height: ${height};
+          color: ${themeValues.textColor};
+          ${contentExtraStyles}
+        `}
+        boxShadow="0px 2px 14px 0px rgb(246, 246, 249), 0px 3px 8px 0px rgb(202, 206, 216)"
+        border="1px solid transparent"
+        borderRadius="4px"
+        minWidth={minWidth}
+        maxWidth={maxWidth}
+      >
+        {typeof content === "string" && content !== "" ? (
+          <Text color={themeValues.textColor}>{content}</Text>
+        ) : content !== undefined && content !== null ? (
+          content
+        ) : null}
+        <Box
+          padding="0"
+          extraStyles={`
+            position: absolute;
+            content: "";
+            width: 0;
+            height: 0;
+            ${arrowBorder(backgroundColor, arrowDirection, "8px")};
+            filter: drop-shadow(2px 8px 14px black);
+            bottom: ${arrowBottom};
+            right: ${arrowRight};
+            top: ${arrowTop};
+            left: ${arrowLeft};
+          `}
+        />
+      </Box>
+    </Box>
+  );
+};
+
+export default Tooltip;

package/src/components/molecules/tooltip/Tooltip.mdx

@@ -0,0 +1,25 @@
+import { Canvas, Meta, Title, Story, Controls } from '@storybook/blocks';
+
+import * as TooltipStories from './Tooltip.stories.js';
+
+<Meta of={TooltipStories} />
+
+<Title />
+
+Tooltip is an accessible tooltip component implementing the [WAI-ARIA Tooltip Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/). It displays supplemental information when the user hovers over or focuses on a trigger element.
+
+The trigger can be either:
+- **Custom children**: Pass any single React element as `children`. It will receive `aria-describedby`, focus, blur, and keyboard handlers automatically.
+- **Default button**: When no `children` are provided, a `ButtonWithAction` is rendered using the `triggerText` prop.
+
+The tooltip content (`content` prop) accepts a plain string or a React node for rich content. It is styled similarly to the Popover component, including an arrow pointing toward the trigger.
+
+### Accessibility
+- The trigger element has `aria-describedby` referencing the tooltip.
+- The tooltip container has `role="tooltip"`.
+- Pressing **Escape** dismisses the tooltip.
+- Focus stays on the trigger while the tooltip is displayed.
+
+<Controls />
+
+<Story />

package/src/components/molecules/tooltip/Tooltip.stories.js

@@ -0,0 +1,287 @@
+import React from "react";
+import Tooltip from "./Tooltip";
+import Text from "../../atoms/text/Text";
+import AutopayOnIcon from "../../atoms/icons/AutopayOnIcon";
+import Box from "../../atoms/layouts/Box";
+import { SEA_GREEN, WHITE } from "../../../constants/colors";
+
+const meta = {
+  title: "Molecules/Tooltip",
+  component: Tooltip,
+  parameters: {
+    layout: "centered"
+  },
+  tags: ["!autodocs"],
+  decorators: [
+    Story => (
+      <div style={{ padding: "120px 300px" }}>
+        <Story />
+      </div>
+    )
+  ],
+  args: {
+    tooltipID: "tooltip-id",
+    triggerText: "Hover me",
+    content: "This is the tooltip content.",
+    contentPosition: {
+      top: "-110px",
+      right: "auto",
+      bottom: "auto",
+      left: "-225px"
+    },
+    arrowDirection: "down",
+    arrowPosition: {
+      arrowTop: "auto",
+      arrowRight: "10px",
+      arrowBottom: "-8px",
+      arrowLeft: "auto"
+    },
+    minWidth: "250px",
+    maxWidth: "300px",
+    height: "auto",
+    containerExtraStyles: "",
+    contentExtraStyles: ""
+  },
+  argTypes: {
+    hasCustomTrigger: {
+      description:
+        "When true, the component uses the children prop as the trigger element instead of the default ButtonWithAction.",
+      control: { type: "boolean" },
+      table: {
+        type: { summary: "boolean" },
+        defaultValue: { summary: false }
+      }
+    },
+    customTriggerRole: {
+      description:
+        "Role for the custom trigger element for accessibility purposes. Defaults to undefined.",
+      control: { type: "text" },
+      table: {
+        type: { summary: "string" },
+        defaultValue: { summary: undefined }
+      }
+    },
+    children: {
+      description:
+        "Optional trigger element. When provided, it replaces the default ButtonWithAction trigger. The child element will receive aria-describedby, focus, blur, and keydown handlers.",
+      table: {
+        type: { summary: "React.ReactNode" },
+        defaultValue: { summary: undefined }
+      }
+    },
+    content: {
+      description:
+        "The content displayed inside the tooltip. Can be a string or a React node/element.",
+      table: {
+        type: { summary: "string | React.ReactNode" },
+        defaultValue: { summary: '""' }
+      }
+    },
+    tooltipID: {
+      description:
+        "Unique ID for the tooltip content element. Used as the aria-describedby value on the trigger.",
+      table: {
+        type: { summary: "string" },
+        defaultValue: { summary: undefined }
+      }
+    },
+    triggerText: {
+      description:
+        "Text shown in the default ButtonWithAction trigger. Not needed when children are provided.",
+      table: {
+        type: { summary: "string" },
+        defaultValue: { summary: '""' }
+      }
+    },
+    triggerButtonVariant: {
+      description:
+        "Variant passed to the default ButtonWithAction trigger. Has no effect when a custom trigger is used.",
+      table: {
+        type: { summary: "string" },
+        defaultValue: { summary: '"smallGhost"' }
+      }
+    },
+    contentPosition: {
+      description:
+        "CSS position values (top, right, bottom, left) for the tooltip content box relative to the trigger.",
+      table: {
+        type: { summary: "object" },
+        defaultValue: {
+          summary:
+            '{ top: "-110px", right: "auto", bottom: "auto", left: "-225px" }'
+        }
+      }
+    },
+    arrowDirection: {
+      description:
+        "Direction the tooltip arrow points (up, down, left, right).",
+      control: { type: "select" },
+      options: ["up", "down", "left", "right"],
+      table: {
+        type: { summary: "string" },
+        defaultValue: { summary: "down" }
+      }
+    },
+    arrowPosition: {
+      description:
+        "CSS position values (arrowTop, arrowRight, arrowBottom, arrowLeft) for the arrow element.",
+      table: {
+        type: { summary: "object" },
+        defaultValue: {
+          summary:
+            '{ arrowTop: "auto", arrowRight: "10px", arrowBottom: "-8px", arrowLeft: "auto" }'
+        }
+      }
+    },
+    minWidth: {
+      description: "Minimum width of the tooltip content box.",
+      table: {
+        type: { summary: "string" },
+        defaultValue: { summary: "250px" }
+      }
+    },
+    maxWidth: {
+      description: "Maximum width of the tooltip content box.",
+      table: {
+        type: { summary: "string" },
+        defaultValue: { summary: "100%" }
+      }
+    },
+    height: {
+      description: "Height of the tooltip content box.",
+      table: {
+        type: { summary: "string" },
+        defaultValue: { summary: "auto" }
+      }
+    },
+    containerExtraStyles: {
+      description:
+        "Additional CSS string applied to the tooltip container element.",
+      table: {
+        type: { summary: "string" },
+        defaultValue: { summary: '""' }
+      }
+    },
+    contentExtraStyles: {
+      description:
+        "Additional CSS string applied to the tooltip content element.",
+      table: {
+        type: { summary: "string" },
+        defaultValue: { summary: '""' }
+      }
+    },
+    backgroundColor: {
+      description:
+        "Override backgroundColor for the tooltip arrow. Defaults to WHITE when not provided.",
+      table: {
+        type: { summary: "string" },
+        defaultValue: { summary: WHITE }
+      }
+    }
+  }
+};
+
+export default meta;
+
+export const Basic = {
+  args: {
+    tooltipID: "tooltip-basic",
+    triggerText: "What is this?",
+    content:
+      "This is a detailed explanation of a feature or term that the user may need more context about."
+  }
+};
+
+export const WithChildren = {
+  args: {
+    tooltipID: "tooltip-children",
+    hasCustomTrigger: true,
+    content: "Extra information about this label.",
+    contentPosition: {
+      top: "-84px",
+      right: "auto",
+      bottom: "auto",
+      left: "-225px"
+    }
+  },
+  render: args => (
+    <Tooltip {...args}>
+      <Box padding="0" extraStyles="white-space: nowrap;">
+        <AutopayOnIcon />
+        <Text
+          color={SEA_GREEN}
+          extraStyles="margin-left: 5px; white-space: nowrap;"
+        >
+          Custom trigger
+        </Text>
+      </Box>
+    </Tooltip>
+  )
+};
+
+export const RichTooltipContent = {
+  args: {
+    tooltipID: "tooltip-node-content",
+    contentExtraStyles: "background-color: #000000; color: #ffffff;",
+    triggerText: "Rich content",
+    backgroundColor: "black",
+    contentPosition: {
+      top: "-126px",
+      right: "auto",
+      bottom: "auto",
+      left: "-225px"
+    },
+    content: React.createElement("div", { style: { padding: "8px" } }, [
+      React.createElement("strong", null, "Bold title"),
+      React.createElement(
+        "p",
+        null,
+        "With ",
+        React.createElement("em", null, "an italic text detail"),
+        " below."
+      )
+    ])
+  }
+};
+
+export const TooltipBelow = {
+  args: {
+    tooltipID: "tooltip-below",
+    triggerText: "Hover for info",
+    content: "This tooltip appears below the trigger.",
+    contentPosition: {
+      top: "50px",
+      right: "auto",
+      bottom: "auto",
+      left: "-225px"
+    },
+    arrowDirection: "up",
+    arrowPosition: {
+      arrowTop: "-8px",
+      arrowRight: "10px",
+      arrowBottom: "auto",
+      arrowLeft: "auto"
+    }
+  }
+};
+
+export const TooltipRight = {
+  args: {
+    tooltipID: "tooltip-right",
+    triggerText: "Hover for info",
+    content: "This tooltip appears to the right.",
+    contentPosition: {
+      top: "-40px",
+      right: "auto",
+      bottom: "auto",
+      left: "calc(100% + 12px)"
+    },
+    arrowDirection: "left",
+    arrowPosition: {
+      arrowTop: "50%",
+      arrowRight: "auto",
+      arrowBottom: "auto",
+      arrowLeft: "-8px"
+    }
+  }
+};

package/src/components/molecules/tooltip/Tooltip.theme.js

@@ -0,0 +1,18 @@
+import {
+  ROYAL_BLUE_VIVID,
+  ROYAL_BLUE,
+  CONGRESS_BLUE,
+  CHARADE_GREY
+} from "../../../constants/colors";
+
+const hoverColor = ROYAL_BLUE;
+const activeColor = CONGRESS_BLUE;
+const linkColor = ROYAL_BLUE_VIVID;
+const textColor = CHARADE_GREY;
+
+export const fallbackValues = {
+  linkColor,
+  hoverColor,
+  activeColor,
+  textColor
+};

package/src/components/molecules/tooltip/index.d.ts

@@ -0,0 +1,34 @@
+import React from "react";
+import Expand from "../../../util/expand";
+
+export interface TooltipProps {
+  children?: React.ReactNode;
+  content: React.ReactNode;
+  tooltipID: string;
+  hasCustomTrigger?: boolean;
+  triggerText?: string;
+  triggerButtonVariant?: string;
+  contentPosition?: {
+    top: string;
+    right: string;
+    bottom: string;
+    left: string;
+  };
+  arrowDirection?: string;
+  arrowPosition?: {
+    arrowTop: string;
+    arrowRight: string;
+    arrowBottom: string;
+    arrowLeft: string;
+  };
+  minWidth?: string;
+  maxWidth?: string;
+  height?: string;
+  containerExtraStyles?: string;
+  contentExtraStyles?: string;
+  backgroundColor?: string;
+  customTriggerRole?: string;
+}
+
+export const Tooltip: React.FC<Expand<TooltipProps> &
+  React.HTMLAttributes<HTMLElement>>;

package/src/components/molecules/tooltip/index.js

@@ -0,0 +1,3 @@
+import Tooltip from "./Tooltip";
+
+export default Tooltip;