Feat: [DS-209] Tooltip

.changeset/nice-fireants-worry.md

@@ -0,0 +1,5 @@
+---
+"@hopper-ui/components": patch
+---
+
+Added the Tooltip component.

packages/components/src/Tooltip/index.ts

@@ -0,0 +1 @@
+export * from "./src/index.ts";

packages/components/src/Tooltip/src/PassiveTrigger.module.css

@@ -0,0 +1,5 @@
+.hop-PassiveTrigger {
+    --hop-PassiveTrigger-inline-size: max-content;
+
+    inline-size: var(--hop-PassiveTrigger-inline-size);
+}

packages/components/src/Tooltip/src/PassiveTrigger.tsx

@@ -0,0 +1,80 @@
+import { useStyledSystem, type StyledSystemProps } from "@hopper-ui/styled-system";
+import clsx from "clsx";
+import { forwardRef, useRef, type ForwardedRef, type ReactNode } from "react";
+import { useFocusable } from "react-aria";
+import { useContextProps } from "react-aria-components";
+
+import { cssModule, type BaseComponentDOMProps } from "../../utils/index.ts";
+
+import { PassiveTriggerContext } from "./PassiveTriggerContext.ts";
+
+import styles from "./PassiveTrigger.module.css";
+
+export const GlobalPassiveTriggerCssSelector = "hop-PassiveTrigger";
+
+export interface PassiveTriggerProps extends StyledSystemProps, BaseComponentDOMProps {
+    /**
+     * The children of the PassiveTrigger.
+     */
+    children?: ReactNode;
+}
+/**
+ * A PassiveTrigger wraps a trigger element and Tooltip, handling visibility and positioning.
+ *
+ * [View Documentation](TODO)
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function PassiveTrigger(props: PassiveTriggerProps, ref: ForwardedRef<HTMLDivElement>) {
+    [props, ref] = useContextProps(props, ref, PassiveTriggerContext);
+
+    const { stylingProps, ...ownProps } = useStyledSystem(props);
+    const backupRef = useRef<HTMLDivElement>(null);
+    const determinedRef = (ref ?? backupRef);
+    const { focusableProps } = useFocusable(ownProps, determinedRef);
+    const {
+        children,
+        className,
+        slot,
+        style: styleProp,
+        ...otherProps
+    } = ownProps;
+
+    const classNames = clsx(
+        className,
+        GlobalPassiveTriggerCssSelector,
+        cssModule(
+            styles,
+            "hop-PassiveTrigger"
+        ),
+        stylingProps.className
+    );
+
+    const style = {
+        ...stylingProps.style,
+        ...styleProp
+    };
+
+    return (
+        <div
+            ref={determinedRef}
+            slot={slot ?? undefined}
+            className={classNames}
+            style={style}
+            {...focusableProps}
+            {...otherProps}
+        >
+            {children}
+        </div>
+    );
+}
+
+/**
+ * Wraps a tooltip trigger that is not normally focusable.
+ *
+ * [View Documentation](TODO)
+ */
+const _PassiveTrigger = forwardRef<HTMLDivElement, PassiveTriggerProps>(PassiveTrigger);
+_PassiveTrigger.displayName = "PassiveTrigger";
+
+export { _PassiveTrigger as PassiveTrigger };
+

packages/components/src/Tooltip/src/PassiveTriggerContext.ts

@@ -0,0 +1,8 @@
+import { createContext } from "react";
+import type { ContextValue } from "react-aria-components";
+
+import type { PassiveTriggerProps } from "./PassiveTrigger.tsx";
+
+export const PassiveTriggerContext = createContext<ContextValue<PassiveTriggerProps, HTMLDivElement>>({});
+
+PassiveTriggerContext.displayName = "PassiveTriggerContext";

packages/components/src/Tooltip/src/Tooltip.module.css

@@ -0,0 +1,68 @@
+.hop-Tooltip {
+    --hop-Tooltip-max-inline-size: 25rem;
+    --hop-Tooltip-slide-amount: 0.25rem; /* Tokens not available here */
+
+    /* Internal Variables */
+    --origin-x: 0;
+    --origin-y: 0;
+
+    /* Ensures there's always 1rem space around the tooltip, but it'll still have a max width of 25rem. */
+    max-inline-size: min(var(--hop-Tooltip-max-inline-size), calc(100% - (var(--container-padding) * 2)));
+}
+
+.hop-Tooltip--top {
+    --origin-x: 0;
+    --origin-y: var(--hop-Tooltip-slide-amount);
+}
+
+.hop-Tooltip--right {
+    --origin-x: calc(-1 * var(--hop-Tooltip-slide-amount));
+    --origin-y: 0;
+}
+
+.hop-Tooltip--bottom {
+    --origin-x: 0;
+    --origin-y: calc(-1 * var(--hop-Tooltip-slide-amount));
+}
+
+.hop-Tooltip--left {
+    --origin-x: var(--hop-Tooltip-slide-amount);
+    --origin-y: 0;
+}
+
+.hop-Tooltip[data-entering] {
+    animation: slide 0.2s ease-out;
+}
+
+.hop-Tooltip[data-exiting] {
+    animation: slide 0.2s ease-in reverse;
+}
+
+.hop-Tooltip__container {
+    --hop-Tooltip-background: var(--hop-neutral-surface-strong);
+    --hop-Tooltip-border-radius: var(--hop-shape-rounded-md);
+    --hop-Tooltip-box-shadow: var(--hop-elevation-raised);
+    --hop-Tooltip-color: var(--hop-neutral-text-strong);
+    --hop-Tooltip-padding: var(--hop-space-inset-squish-md);
+
+    padding: var(--hop-Tooltip-padding);
+
+    color: var(--hop-Tooltip-color);
+
+    background: var(--hop-Tooltip-background);
+    border-radius: var(--hop-Tooltip-border-radius);
+    box-shadow: var(--hop-Tooltip-box-shadow);
+}
+
+@keyframes slide {
+    from {
+      transform: translate(var(--origin-x), var(--origin-y));
+      opacity: 0;
+    }
+
+    to {
+      transform: translateY(0);
+      opacity: 1;
+    }
+  }
+

packages/components/src/Tooltip/src/Tooltip.tsx

@@ -0,0 +1,136 @@
+import {
+    useColorSchemeContext,
+    useStyledSystem,
+    type StyledComponentProps,
+    type StyledSystemProps
+} from "@hopper-ui/styled-system";
+import clsx from "clsx";
+import { forwardRef, useContext, type ForwardedRef } from "react";
+import { composeRenderProps, Tooltip as RACTooltip, useContextProps, type TooltipProps as RACTooltipProps } from "react-aria-components";
+
+import { HopperProvider } from "../../HopperProvider/index.ts";
+import { TextContext } from "../../typography/index.ts";
+import { composeClassnameRenderProps, cssModule, ensureTextWrapper, SlotProvider, type BaseComponentDOMProps } from "../../utils/index.ts";
+
+import { TooltipContext } from "./TooltipContext.ts";
+import { TooltipTriggerContext } from "./TooltipTriggerContext.ts";
+
+import styles from "./Tooltip.module.css";
+
+export const GlobalTooltipCssSelector = "hop-Tooltip";
+
+type PropsToOmit = "triggerRef" | "UNSTABLE_portalContainer" | "placement" | "containerPadding" | "offset" | "crossOffset" |
+"shouldFlip" | "arrowBoundaryOffset" | "isOpen" | "defaultOpen" | "onOpenChange";
+
+export type TooltipContainerProps = Omit<BaseComponentDOMProps, "slot"> & StyledSystemProps;
+
+export interface TooltipProps extends StyledComponentProps<Omit<RACTooltipProps, PropsToOmit>> {
+    /**
+     * The props of the tooltip's inner container.
+     */
+    containerProps?: TooltipContainerProps;
+}
+
+function Tooltip(props: TooltipProps, ref: ForwardedRef<HTMLDivElement>) {
+    [props, ref] = useContextProps(props, ref, TooltipContext);
+    const { stylingProps, ...ownProps } = useStyledSystem(props);
+    const {
+        children: childrenProp,
+        className,
+        containerProps,
+        style: styleProp,
+        ...otherProps
+    } = ownProps;
+
+    const {
+        containerPadding = 16,
+        crossOffset,
+        offset,
+        placement = "top",
+        shouldFlip
+    } = useContext(TooltipTriggerContext);
+
+    const { colorScheme } = useColorSchemeContext();
+
+    const { stylingProps: containerStylingProps, ...containerOwnProps } = useStyledSystem(containerProps ?? {});
+    const {
+        className: containerClassName,
+        style: containerStyleProp,
+        ...containerOtherProps
+    } = containerOwnProps;
+
+    const classNames = composeClassnameRenderProps(
+        className,
+        GlobalTooltipCssSelector,
+        cssModule(
+            styles,
+            "hop-Tooltip",
+            placement
+        ),
+        stylingProps.className
+    );
+
+    const containerClassNames = clsx(containerClassName, styles["hop-Tooltip__container"], containerStylingProps.className);
+
+    const style = composeRenderProps(styleProp, prev => {
+        return {
+            ...stylingProps.style,
+            "--container-padding": `${containerPadding}px`,
+            ...prev
+        };
+    });
+
+    const containerStyle = {
+        ...containerStylingProps.style,
+        ...containerStyleProp
+    };
+
+    const children = composeRenderProps(childrenProp, prev => {
+        return ensureTextWrapper(prev);
+    });
+
+    return (
+        <RACTooltip
+            ref={ref}
+            className={classNames}
+            style={style}
+            containerPadding={containerPadding}
+            crossOffset={crossOffset}
+            offset={offset}
+            placement={placement}
+            shouldFlip={shouldFlip}
+            {...otherProps}
+        >
+            {tooltipRenderProps => {
+                return (
+                    <HopperProvider colorScheme={colorScheme} withCssVariables={false}>
+                        <div
+                            className={containerClassNames}
+                            style={containerStyle}
+                            {...containerOtherProps}
+                        >
+                            <SlotProvider values={[
+                                [TextContext, {
+                                    size: "xs"
+                                }]
+                            ]}
+                            >
+                                {children(tooltipRenderProps)}
+                            </SlotProvider>
+                        </div>
+                    </HopperProvider>
+                );
+            }}
+        </RACTooltip>
+    );
+}
+
+/**
+ * Displays concise information on hover or focus.
+ *
+ * [View Documentation](TODO)
+ */
+const _Tooltip = forwardRef<HTMLDivElement, TooltipProps>(Tooltip);
+_Tooltip.displayName = "Tooltip";
+
+export { _Tooltip as Tooltip };

packages/components/src/Tooltip/src/TooltipContext.ts

@@ -0,0 +1,8 @@
+import { createContext } from "react";
+import type { ContextValue } from "react-aria-components";
+
+import type { TooltipProps } from "./Tooltip.tsx";
+
+export const TooltipContext = createContext<ContextValue<TooltipProps, HTMLDivElement>>({});
+
+TooltipContext.displayName = "TooltipContext";

packages/components/src/Tooltip/src/TooltipTrigger.tsx

@@ -0,0 +1,55 @@
+import { TooltipTrigger as RACTooltipTrigger, type TooltipProps as RACTooltipProps, type TooltipTriggerComponentProps as RACTooltipTriggerProps } from "react-aria-components";
+
+import { TooltipTriggerContext } from "./TooltipTriggerContext.ts";
+
+export type TooltipPlacement = "start" | "end" | "right" | "left" | "top" | "bottom";
+
+type PropsToPick = "shouldFlip" | "containerPadding" | "offset" | "crossOffset" | "isOpen" | "defaultOpen" | "onOpenChange";
+
+export interface TooltipTriggerProps extends RACTooltipTriggerProps, Pick<RACTooltipProps, PropsToPick> {
+    /**
+   * The placement of the element with respect to its anchor element.
+   *
+   * @default 'top'
+   */
+    placement?: TooltipPlacement;
+}
+
+/**
+ * A TooltipTrigger wraps a trigger element and Tooltip, handling visibility and positioning.
+ *
+ * [View Documentation](TODO)
+ */
+export function TooltipTrigger(props: TooltipTriggerProps) {
+    const {
+        children,
+        containerPadding = 16,
+        crossOffset,
+        delay = 600,
+        offset = 4,
+        placement = "top",
+        shouldFlip,
+        ...otherProps
+    } = props;
+
+    return (
+        <RACTooltipTrigger
+            delay={delay}
+            {...otherProps}
+        >
+            <TooltipTriggerContext.Provider
+                value={{
+                    containerPadding: containerPadding,
+                    crossOffset: crossOffset,
+                    offset: offset,
+                    placement: placement,
+                    shouldFlip: shouldFlip
+                }}
+            >
+                {children}
+            </TooltipTriggerContext.Provider>
+        </RACTooltipTrigger>
+    );
+}
+
+TooltipTrigger.displayName = "TooltipTrigger";

packages/components/src/Tooltip/src/TooltipTriggerContext.ts

@@ -0,0 +1,7 @@
+import { createContext } from "react";
+
+import type { TooltipTriggerProps } from "./TooltipTrigger.tsx";
+
+export const TooltipTriggerContext = createContext<Partial<TooltipTriggerProps>>({});
+
+TooltipTriggerContext.displayName = "TooltipTriggerContext";

packages/components/src/Tooltip/src/index.ts

@@ -0,0 +1,6 @@
+export * from "./PassiveTrigger.tsx";
+export * from "./PassiveTriggerContext.ts";
+export * from "./Tooltip.tsx";
+export * from "./TooltipContext.ts";
+export * from "./TooltipTrigger.tsx";
+