@bug-on/md3-react 2.0.3 → 3.0.0

package/src/ui/tooltip/plain-tooltip.tsx

@@ -0,0 +1,63 @@
+import type { CSSProperties } from "react";
+import { forwardRef } from "react";
+import { TooltipTokens } from "./tooltip.tokens";
+import type { PlainTooltipProps } from "./tooltip.types";
+import { TooltipCaretShape } from "./tooltip-caret-shape";
+
+export const PlainTooltip = forwardRef<HTMLDivElement, PlainTooltipProps>(
+	(
+		{
+			children,
+			caret,
+			className = "",
+			maxWidth,
+			containerColor,
+			textColor,
+			...props
+		},
+		ref,
+	) => {
+		const {
+			containerColor: tokenContainer,
+			textColor: tokenText,
+			font,
+			padding,
+			shape,
+			height,
+			maxWidth: tokenMaxWidth,
+		} = TooltipTokens.PlainTooltip;
+
+		const style: CSSProperties = {
+			...props.style,
+			backgroundColor: containerColor ?? tokenContainer,
+			color: textColor ?? tokenText,
+			...(maxWidth && { maxWidth }),
+		};
+
+		const side = props["data-side"] ?? "top";
+
+		return (
+			<div
+				ref={ref}
+				className={`relative inline-flex items-center box-border ${shape} ${font} ${padding} ${height} ${!maxWidth ? tokenMaxWidth : ""} ${className}`}
+				style={style}
+				{...props}
+			>
+				{caret?.enabled && (
+					<TooltipCaretShape
+						side={side}
+						width={caret.width}
+						height={caret.height}
+						color={style.backgroundColor as string}
+						customPath={caret.customPath}
+					/>
+				)}
+				<span className="whitespace-normal text-start wrap-break-word">
+					{children}
+				</span>
+			</div>
+		);
+	},
+);
+
+PlainTooltip.displayName = "PlainTooltip";

package/src/ui/tooltip/rich-tooltip.tsx

@@ -0,0 +1,94 @@
+import type { CSSProperties } from "react";
+import { forwardRef } from "react";
+import { TooltipTokens } from "./tooltip.tokens";
+import type { RichTooltipProps } from "./tooltip.types";
+import { TooltipCaretShape } from "./tooltip-caret-shape";
+
+export const RichTooltip = forwardRef<HTMLDivElement, RichTooltipProps>(
+	(
+		{
+			children,
+			title,
+			action,
+			caret,
+			className = "",
+			maxWidth,
+			colors = {},
+			...props
+		},
+		ref,
+	) => {
+		const {
+			containerColor: tokenContainer,
+			elevation,
+			shape,
+			paddingTop,
+			paddingBottom,
+			paddingX,
+			maxWidth: tokenMaxWidth,
+			subheadColor,
+			subheadFont,
+			bodyColor,
+			bodyFont,
+			actionColor,
+			actionFont,
+		} = TooltipTokens.RichTooltip;
+
+		const containerStyle: CSSProperties = {
+			...props.style,
+			backgroundColor: colors.container ?? tokenContainer,
+			...(maxWidth && { maxWidth }),
+		};
+
+		const side = props["data-side"] ?? "top";
+
+		const titleColor = colors.title ?? subheadColor;
+		const bodyColorResolved = colors.body ?? bodyColor;
+		const actionColorResolved = colors.action ?? actionColor;
+
+		return (
+			<div
+				ref={ref}
+				className={`relative box-border flex flex-col ${shape} ${elevation} ${paddingTop} ${paddingBottom} ${paddingX} ${!maxWidth ? tokenMaxWidth : ""} ${className}`}
+				style={containerStyle}
+				{...props}
+			>
+				{caret?.enabled && (
+					<TooltipCaretShape
+						side={side}
+						width={caret.width}
+						height={caret.height}
+						color={containerStyle.backgroundColor as string}
+						customPath={caret.customPath}
+					/>
+				)}
+
+				{title && (
+					<div className={`mb-1 ${subheadFont}`} style={{ color: titleColor }}>
+						{title}
+					</div>
+				)}
+
+				{children && (
+					<div
+						className={`whitespace-normal text-start wrap-break-word ${bodyFont}`}
+						style={{ color: bodyColorResolved }}
+					>
+						{children}
+					</div>
+				)}
+
+				{action && (
+					<div
+						className={`mt-2 flex min-h-9 flex-wrap items-center gap-2 ${actionFont}`}
+						style={{ color: actionColorResolved }}
+					>
+						{action}
+					</div>
+				)}
+			</div>
+		);
+	},
+);
+
+RichTooltip.displayName = "RichTooltip";

package/src/ui/tooltip/tooltip-box.tsx

@@ -0,0 +1,266 @@
+import { Slot } from "@radix-ui/react-slot";
+import { AnimatePresence, m } from "motion/react";
+import * as React from "react";
+import {
+	cloneElement,
+	type ReactElement,
+	useEffect,
+	useId,
+	useRef,
+	useState,
+} from "react";
+import { createPortal } from "react-dom";
+import type { TooltipBoxProps } from "./tooltip.types";
+import { useTooltipPosition } from "./use-tooltip-position";
+import { useTooltipState } from "./use-tooltip-state";
+
+type Side = "top" | "bottom" | "left" | "right";
+
+const TRANSFORM_ORIGIN: Record<Side, string> = {
+	top: "50% 100%",
+	bottom: "50% 0%",
+	left: "100% 50%",
+	right: "0% 50%",
+};
+
+const MOTION_VARIANTS = {
+	full: {
+		hidden: { opacity: 0, scale: 0.8 },
+		visible: {
+			opacity: 1,
+			scale: 1,
+			transition: {
+				opacity: { duration: 0.1, ease: "easeOut" },
+				scale: { type: "spring", stiffness: 900, damping: 90, mass: 0.5 },
+			},
+		},
+		exit: {
+			opacity: 0,
+			scale: 0.8,
+			transition: {
+				opacity: { duration: 0.075, ease: "easeIn" },
+				scale: { duration: 0.1, ease: "easeIn" },
+			},
+		},
+	},
+	reduced: {
+		hidden: { opacity: 0 },
+		visible: { opacity: 1, transition: { duration: 0.15 } },
+		exit: { opacity: 0, transition: { duration: 0.1 } },
+	},
+} as const;
+
+function clearTimeout(ref: React.MutableRefObject<number | null>) {
+	if (ref.current !== null) window.clearTimeout(ref.current);
+}
+
+export function TooltipBox({
+	children,
+	tooltip,
+	placement = "top",
+	trigger = ["hover", "focus"],
+	state: controlledState,
+	spacingFromAnchor = 4,
+	disabled = false,
+	className = "",
+	showDelay = 400,
+	hideDelay = 200,
+	"aria-label": ariaLabel,
+}: TooltipBoxProps) {
+	const internalState = useTooltipState();
+	const state = controlledState ?? internalState;
+
+	const anchorRef = useRef<HTMLDivElement>(null);
+	const tooltipRef = useRef<HTMLDivElement>(null);
+	const hoverTimeoutRef = useRef<number | null>(null);
+	const hideTimeoutRef = useRef<number | null>(null);
+	const pressTimeoutRef = useRef<number | null>(null);
+
+	const triggers = Array.isArray(trigger) ? trigger : [trigger];
+
+	const [mounted, setMounted] = useState(false);
+	const [hasHoverSupport, setHasHoverSupport] = useState(true);
+	const [prefersReducedMotion, setPrefersReducedMotion] = useState(false);
+
+	useEffect(() => {
+		setMounted(true);
+		setHasHoverSupport(!window.matchMedia("(hover: none)").matches);
+	}, []);
+
+	useEffect(() => {
+		const mediaQuery = window.matchMedia("(prefers-reduced-motion: reduce)");
+		setPrefersReducedMotion(mediaQuery.matches);
+		const onChange = (e: MediaQueryListEvent) =>
+			setPrefersReducedMotion(e.matches);
+		mediaQuery.addEventListener("change", onChange);
+		return () => mediaQuery.removeEventListener("change", onChange);
+	}, []);
+
+	const position = useTooltipPosition(
+		anchorRef,
+		tooltipRef,
+		placement,
+		spacingFromAnchor,
+		state.isVisible,
+	);
+
+	const canHover = !disabled && hasHoverSupport && triggers.includes("hover");
+	const canClick = !disabled && triggers.includes("click");
+
+	const handlePointerEnter = () => {
+		if (!canHover) return;
+		clearTimeout(hoverTimeoutRef);
+		clearTimeout(hideTimeoutRef);
+		hoverTimeoutRef.current = window.setTimeout(() => state.show(), showDelay);
+	};
+
+	const handlePointerLeave = () => {
+		if (!canHover) return;
+		clearTimeout(hoverTimeoutRef);
+		hideTimeoutRef.current = window.setTimeout(
+			() => state.dismiss(),
+			hideDelay,
+		);
+	};
+
+	const handleFocus = () => {
+		if (disabled || !triggers.includes("focus")) return;
+		state.show();
+	};
+
+	const handleBlur = (e: React.FocusEvent) => {
+		if (disabled) return;
+		const focusMovedInside =
+			tooltipRef.current &&
+			(e.relatedTarget === tooltipRef.current ||
+				tooltipRef.current.contains(e.relatedTarget as Node));
+		if (focusMovedInside) return;
+		state.dismiss();
+	};
+
+	const handlePointerDown = (e: React.PointerEvent) => {
+		if (
+			disabled ||
+			!triggers.includes("long-press") ||
+			e.pointerType === "mouse"
+		)
+			return;
+		clearTimeout(pressTimeoutRef);
+		pressTimeoutRef.current = window.setTimeout(() => state.show(), 500);
+	};
+
+	const handleClick = () => {
+		if (!canClick) return;
+		if (state.isVisible) state.dismiss();
+		else state.show();
+	};
+
+	const handleKeyDown = (e: React.KeyboardEvent) => {
+		if (disabled || !canClick) return;
+		if (e.key === "Enter" || e.key === " ") {
+			e.preventDefault();
+			handleClick();
+		}
+	};
+
+	const handleContextMenu = (e: React.MouseEvent) => {
+		if (triggers.includes("long-press") && state.isVisible) e.preventDefault();
+	};
+
+	const handleTooltipPointerEnter = () => {
+		if (!canHover) return;
+		clearTimeout(hideTimeoutRef);
+	};
+
+	const handleTooltipPointerLeave = () => {
+		if (!canHover) return;
+		hideTimeoutRef.current = window.setTimeout(
+			() => state.dismiss(),
+			hideDelay,
+		);
+	};
+
+	useEffect(() => {
+		if (!state.isVisible) return;
+		const onKeyDown = (e: KeyboardEvent) => {
+			if (e.key === "Escape") {
+				state.dismiss();
+				anchorRef.current?.focus();
+			}
+		};
+		document.addEventListener("keydown", onKeyDown);
+		return () => document.removeEventListener("keydown", onKeyDown);
+	}, [state.isVisible, state]);
+
+	const tooltipId = useId();
+
+	const tooltipWithProps = cloneElement(
+		tooltip as ReactElement<{
+			"data-side"?: Side;
+			id?: string;
+			role?: string;
+			onBlur?: (e: React.FocusEvent) => void;
+		}>,
+		{
+			"data-side": position.actualSide,
+			id: tooltipId,
+			role: "tooltip",
+			onBlur: handleBlur,
+		},
+	);
+
+	const variants = prefersReducedMotion
+		? MOTION_VARIANTS.reduced
+		: MOTION_VARIANTS.full;
+
+	return (
+		<>
+			<Slot
+				ref={anchorRef}
+				className={`inline-flex ${className}`}
+				onPointerEnter={handlePointerEnter}
+				onPointerLeave={handlePointerLeave}
+				onFocus={handleFocus}
+				onBlur={handleBlur}
+				onPointerDown={handlePointerDown}
+				onPointerUp={() => clearTimeout(pressTimeoutRef)}
+				onPointerCancel={() => clearTimeout(pressTimeoutRef)}
+				onContextMenu={handleContextMenu}
+				onClick={handleClick}
+				onKeyDown={handleKeyDown}
+				aria-label={ariaLabel}
+				aria-describedby={state.isVisible ? tooltipId : undefined}
+			>
+				{React.isValidElement(children) ? children : <span>{children}</span>}
+			</Slot>
+
+			{mounted &&
+				createPortal(
+					<AnimatePresence mode="wait">
+						{state.isVisible && !disabled && (
+							<m.div
+								ref={tooltipRef}
+								initial="hidden"
+								animate="visible"
+								exit="exit"
+								variants={variants}
+								onPointerEnter={handleTooltipPointerEnter}
+								onPointerLeave={handleTooltipPointerLeave}
+								style={{
+									position: "fixed",
+									top: position.top,
+									left: position.left,
+									transformOrigin: TRANSFORM_ORIGIN[position.actualSide],
+									zIndex: 50,
+									pointerEvents: "auto",
+								}}
+							>
+								{tooltipWithProps}
+							</m.div>
+						)}
+					</AnimatePresence>,
+					document.body,
+				)}
+		</>
+	);
+}

package/src/ui/tooltip/tooltip-caret-shape.tsx

@@ -0,0 +1,68 @@
+export interface TooltipCaretProps {
+	side: "top" | "bottom" | "left" | "right";
+	width?: number;
+	height?: number;
+	color?: string;
+	customPath?: string;
+	className?: string;
+}
+
+type Side = TooltipCaretProps["side"];
+
+const CENTER_H = "left-1/2 -translate-x-1/2";
+const CENTER_V = "top-1/2 -translate-y-1/2 flex items-center justify-center";
+
+const POSITION_BY_SIDE: Record<Side, (h: number) => string> = {
+	top: (h) => `bottom-[calc(-1*${h}px)] ${CENTER_H}`,
+	bottom: (h) => `top-[calc(-1*${h}px)] ${CENTER_H}`,
+	left: (h) => `right-[calc(-1*${h}px)] ${CENTER_V}`,
+	right: (h) => `left-[calc(-1*${h}px)] ${CENTER_V}`,
+};
+
+const ROTATION: Record<Side, string> = {
+	top: "180deg",
+	bottom: "0deg",
+	left: "90deg",
+	right: "-90deg",
+};
+
+export function TooltipCaretShape({
+	side,
+	width = 16,
+	height = 8,
+	color,
+	customPath,
+	className = "",
+}: TooltipCaretProps) {
+	const isHorizontal = side === "left" || side === "right";
+	const path =
+		customPath ?? `M 0,${height} L ${width / 2},0 L ${width},${height} Z`;
+
+	return (
+		<div
+			className={`absolute pointer-events-none z-[-1] ${POSITION_BY_SIDE[side](height)} ${className}`}
+			style={{
+				width: isHorizontal ? height : width,
+				height: isHorizontal ? width : height,
+				color,
+			}}
+			aria-hidden="true"
+		>
+			<svg
+				width={width}
+				height={height}
+				viewBox={`0 0 ${width} ${height}`}
+				fill="currentColor"
+				xmlns="http://www.w3.org/2000/svg"
+				aria-hidden="true"
+				style={{
+					transform: `rotate(${ROTATION[side]})`,
+					display: "block",
+					transformOrigin: "center",
+				}}
+			>
+				<path d={path} />
+			</svg>
+		</div>
+	);
+}

package/src/ui/tooltip/tooltip.tokens.ts

@@ -0,0 +1,26 @@
+export const TooltipTokens = {
+	PlainTooltip: {
+		containerColor: "var(--md-sys-color-inverse-surface)", // #322F35 light / #E6E1E5 dark
+		textColor: "var(--md-sys-color-inverse-on-surface)", // #F5EFF7 light / #322F35 dark
+		shape: "rounded-[4px]", // CornerExtraSmall = 4dp
+		font: "text-[12px] font-normal tracking-[0.4px] leading-[16px]", // BodySmall
+		height: "min-h-6", // 24dp min height
+		padding: "px-2 py-1", // 8dp all sides
+		maxWidth: "max-w-50",
+	},
+	RichTooltip: {
+		containerColor: "var(--md-sys-color-surface-container)",
+		elevation: "shadow-md", // ElevationTokens.Level2 (approximate with shadow-md)
+		shape: "rounded-[12px]", // CornerMedium = 12dp
+		paddingTop: "pt-3", // 12dp
+		paddingBottom: "pb-2", // 8dp
+		paddingX: "px-4", // 16dp
+		maxWidth: "max-w-80",
+		subheadColor: "var(--md-sys-color-on-surface-variant)",
+		subheadFont: "text-[14px] font-medium leading-[20px]", // TitleSmall
+		bodyColor: "var(--md-sys-color-on-surface-variant)",
+		bodyFont: "text-[14px] font-normal leading-[20px]", // BodyMedium
+		actionColor: "var(--md-sys-color-primary)",
+		actionFont: "text-[14px] font-medium leading-[20px]", // LabelLarge
+	},
+} as const;

package/src/ui/tooltip/tooltip.types.ts

@@ -0,0 +1,70 @@
+import type * as React from "react";
+
+export type TooltipPlacement = "top" | "bottom" | "left" | "right" | "auto";
+export type TooltipTrigger =
+	| "hover"
+	| "focus"
+	| "click"
+	| "long-press"
+	| "manual";
+
+export interface TooltipStateConfig {
+	initialVisible?: boolean;
+	isPersistent?: boolean;
+	duration?: number;
+}
+
+export interface TooltipState {
+	isVisible: boolean;
+	show: () => void;
+	dismiss: () => void;
+}
+
+export interface CaretConfig {
+	enabled: boolean;
+	width?: number;
+	height?: number;
+	customPath?: string;
+}
+
+export interface TooltipBoxProps {
+	children: React.ReactNode;
+	tooltip: React.ReactNode;
+	placement?: TooltipPlacement;
+	trigger?: TooltipTrigger | TooltipTrigger[];
+	state?: TooltipState;
+	spacingFromAnchor?: number;
+	disabled?: boolean;
+	className?: string;
+	showDelay?: number;
+	hideDelay?: number;
+	"aria-label"?: string;
+}
+
+export interface PlainTooltipProps
+	extends React.HTMLAttributes<HTMLDivElement> {
+	children: React.ReactNode;
+	caret?: CaretConfig | null;
+	maxWidth?: number;
+	className?: string;
+	containerColor?: string;
+	textColor?: string;
+	"data-side"?: "top" | "bottom" | "left" | "right";
+}
+
+export interface RichTooltipProps
+	extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+	children?: React.ReactNode;
+	title?: React.ReactNode;
+	action?: React.ReactNode;
+	caret?: CaretConfig | null;
+	maxWidth?: number;
+	className?: string;
+	colors?: {
+		container?: string;
+		title?: string;
+		body?: string;
+		action?: string;
+	};
+	"data-side"?: "top" | "bottom" | "left" | "right";
+}