@nationaldesignstudio/react 0.2.0 → 0.5.0

package/src/components/atoms/tooltip/tooltip.test.tsx

@@ -0,0 +1,363 @@
+import { describe, expect, test, vi } from "vitest";
+import { page, userEvent } from "vitest/browser";
+import { render } from "vitest-browser-react";
+import { Button } from "../button";
+import {
+	Tooltip,
+	TooltipArrow,
+	TooltipParts,
+	TooltipPopup,
+	TooltipPortal,
+	TooltipPositioner,
+	TooltipProvider,
+	TooltipTrigger,
+} from "./tooltip";
+
+describe("Tooltip", () => {
+	describe("Accessibility", () => {
+		test("trigger element is accessible", async () => {
+			render(
+				<Tooltip content="Helpful tip">
+					<Button>Hover me</Button>
+				</Tooltip>,
+			);
+			await expect
+				.element(page.getByRole("button", { name: "Hover me" }))
+				.toBeInTheDocument();
+		});
+
+		test("tooltip has correct role when visible", async () => {
+			render(
+				<Tooltip content="Helpful tip" defaultOpen>
+					<Button>Hover me</Button>
+				</Tooltip>,
+			);
+			await expect
+				.element(page.getByRole("tooltip", { name: "Helpful tip" }))
+				.toBeInTheDocument();
+		});
+
+		test("trigger element is focusable", async () => {
+			render(
+				<Tooltip content="Helpful tip">
+					<Button>Focus me</Button>
+				</Tooltip>,
+			);
+			await userEvent.keyboard("{Tab}");
+			await expect
+				.element(page.getByRole("button", { name: "Focus me" }))
+				.toHaveFocus();
+		});
+	});
+
+	describe("Interactions", () => {
+		test("shows tooltip on hover", async () => {
+			render(
+				<Tooltip content="Hover tooltip">
+					<Button>Hover me</Button>
+				</Tooltip>,
+			);
+
+			// Tooltip should not be visible initially
+			await expect
+				.element(page.getByRole("tooltip", { name: "Hover tooltip" }))
+				.not.toBeInTheDocument();
+
+			// Hover over the trigger
+			await page.getByRole("button", { name: "Hover me" }).hover();
+
+			// Tooltip should now be visible
+			await expect
+				.element(page.getByRole("tooltip", { name: "Hover tooltip" }))
+				.toBeInTheDocument();
+		});
+
+		test("shows tooltip on focus", async () => {
+			render(
+				<Tooltip content="Focus tooltip">
+					<Button>Focus me</Button>
+				</Tooltip>,
+			);
+
+			// Tooltip should not be visible initially
+			await expect
+				.element(page.getByRole("tooltip", { name: "Focus tooltip" }))
+				.not.toBeInTheDocument();
+
+			// Focus the trigger
+			page.getByRole("button", { name: "Focus me" }).element().focus();
+
+			// Tooltip should now be visible
+			await expect
+				.element(page.getByRole("tooltip", { name: "Focus tooltip" }))
+				.toBeInTheDocument();
+		});
+
+		test("hides tooltip on blur", async () => {
+			render(
+				<>
+					<Tooltip content="Focus tooltip">
+						<Button>Focus me</Button>
+					</Tooltip>
+					<Button>Other button</Button>
+				</>,
+			);
+
+			// Focus the trigger to show tooltip
+			page.getByRole("button", { name: "Focus me" }).element().focus();
+			await expect
+				.element(page.getByRole("tooltip", { name: "Focus tooltip" }))
+				.toBeInTheDocument();
+
+			// Blur by focusing another element
+			page.getByRole("button", { name: "Other button" }).element().focus();
+
+			// Tooltip should be hidden
+			await expect
+				.element(page.getByRole("tooltip", { name: "Focus tooltip" }))
+				.not.toBeInTheDocument();
+		});
+	});
+
+	describe("Controlled State", () => {
+		test("respects controlled open state", async () => {
+			render(
+				<Tooltip content="Controlled tooltip" open={true}>
+					<Button>Trigger</Button>
+				</Tooltip>,
+			);
+
+			// Tooltip should be visible when open=true
+			await expect
+				.element(page.getByRole("tooltip", { name: "Controlled tooltip" }))
+				.toBeInTheDocument();
+		});
+
+		test("respects controlled closed state", async () => {
+			render(
+				<Tooltip content="Controlled tooltip" open={false}>
+					<Button>Trigger</Button>
+				</Tooltip>,
+			);
+
+			// Tooltip should not be visible when open=false
+			await expect
+				.element(page.getByRole("tooltip", { name: "Controlled tooltip" }))
+				.not.toBeInTheDocument();
+
+			// Should not show on hover when controlled
+			await page.getByRole("button", { name: "Trigger" }).hover();
+			await expect
+				.element(page.getByRole("tooltip", { name: "Controlled tooltip" }))
+				.not.toBeInTheDocument();
+		});
+
+		test("calls onOpenChange callback", async () => {
+			const handleOpenChange = vi.fn();
+			render(
+				<Tooltip content="Callback tooltip" onOpenChange={handleOpenChange}>
+					<Button>Trigger</Button>
+				</Tooltip>,
+			);
+
+			// Hover to trigger open
+			await page.getByRole("button", { name: "Trigger" }).hover();
+
+			// Wait for tooltip to appear (ensures callback has been called)
+			await expect
+				.element(page.getByRole("tooltip", { name: "Callback tooltip" }))
+				.toBeInTheDocument();
+
+			// Callback should have been called with true as first argument
+			// (Base UI passes additional context as second argument)
+			expect(handleOpenChange).toHaveBeenCalled();
+			expect(handleOpenChange.mock.calls[0][0]).toBe(true);
+		});
+
+		test("defaultOpen shows tooltip initially", async () => {
+			render(
+				<Tooltip content="Default open tooltip" defaultOpen>
+					<Button>Trigger</Button>
+				</Tooltip>,
+			);
+
+			// Tooltip should be visible initially
+			await expect
+				.element(page.getByRole("tooltip", { name: "Default open tooltip" }))
+				.toBeInTheDocument();
+		});
+	});
+
+	describe("Content", () => {
+		test("displays text content", async () => {
+			render(
+				<Tooltip content="Simple text" defaultOpen>
+					<Button>Trigger</Button>
+				</Tooltip>,
+			);
+
+			await expect.element(page.getByText("Simple text")).toBeInTheDocument();
+		});
+
+		test("displays React node content", async () => {
+			render(
+				<Tooltip
+					content={
+						<span data-testid="custom-content">
+							<strong>Bold</strong> text
+						</span>
+					}
+					defaultOpen
+				>
+					<Button>Trigger</Button>
+				</Tooltip>,
+			);
+
+			await expect
+				.element(page.getByTestId("custom-content"))
+				.toBeInTheDocument();
+			await expect.element(page.getByText("Bold")).toBeInTheDocument();
+		});
+	});
+
+	describe("Arrow", () => {
+		test("shows arrow by default", async () => {
+			render(
+				<Tooltip content="With arrow" defaultOpen>
+					<Button>Trigger</Button>
+				</Tooltip>,
+			);
+
+			// The arrow is an SVG element rendered by Base UI
+			const tooltip = page.getByRole("tooltip");
+			await expect.element(tooltip).toBeInTheDocument();
+		});
+
+		test("hides arrow when showArrow is false", async () => {
+			render(
+				<Tooltip content="Without arrow" defaultOpen showArrow={false}>
+					<Button>Trigger</Button>
+				</Tooltip>,
+			);
+
+			const tooltip = page.getByRole("tooltip");
+			await expect.element(tooltip).toBeInTheDocument();
+		});
+	});
+
+	describe("Compound Components", () => {
+		test("renders with compound component API", async () => {
+			render(
+				<TooltipParts defaultOpen>
+					<TooltipTrigger>
+						<Button>Compound trigger</Button>
+					</TooltipTrigger>
+					<TooltipPortal>
+						<TooltipPositioner>
+							<TooltipPopup>
+								<TooltipArrow />
+								Compound tooltip content
+							</TooltipPopup>
+						</TooltipPositioner>
+					</TooltipPortal>
+				</TooltipParts>,
+			);
+
+			await expect
+				.element(page.getByRole("button", { name: "Compound trigger" }))
+				.toBeInTheDocument();
+			await expect
+				.element(page.getByText("Compound tooltip content"))
+				.toBeInTheDocument();
+		});
+	});
+
+	describe("Provider", () => {
+		test("TooltipProvider wraps children", async () => {
+			render(
+				<TooltipProvider>
+					<Tooltip content="Provider tooltip" defaultOpen>
+						<Button>Trigger</Button>
+					</Tooltip>
+				</TooltipProvider>,
+			);
+
+			await expect
+				.element(page.getByRole("tooltip", { name: "Provider tooltip" }))
+				.toBeInTheDocument();
+		});
+	});
+
+	describe("Styles", () => {
+		test("tooltip popup has dark background", async () => {
+			render(
+				<Tooltip content="Styled tooltip" defaultOpen>
+					<Button>Trigger</Button>
+				</Tooltip>,
+			);
+
+			const tooltip = page.getByRole("tooltip");
+			await expect.element(tooltip).toBeInTheDocument();
+
+			const element = tooltip.element();
+			const styles = window.getComputedStyle(element);
+
+			// Tooltip should have a light background (not transparent)
+			expect(styles.backgroundColor).not.toBe("rgba(0, 0, 0, 0)");
+			expect(styles.backgroundColor).not.toBe("transparent");
+		});
+
+		test("tooltip has border radius", async () => {
+			render(
+				<Tooltip content="Styled tooltip" defaultOpen>
+					<Button>Trigger</Button>
+				</Tooltip>,
+			);
+
+			const tooltip = page.getByRole("tooltip");
+			await expect.element(tooltip).toBeInTheDocument();
+
+			const element = tooltip.element();
+			const styles = window.getComputedStyle(element);
+
+			// Should have border radius
+			const borderRadius = parseFloat(styles.borderRadius);
+			expect(borderRadius).toBeGreaterThan(0);
+		});
+
+		test("tooltip has shadow", async () => {
+			render(
+				<Tooltip content="Styled tooltip" defaultOpen>
+					<Button>Trigger</Button>
+				</Tooltip>,
+			);
+
+			const tooltip = page.getByRole("tooltip");
+			await expect.element(tooltip).toBeInTheDocument();
+
+			const element = tooltip.element();
+			const styles = window.getComputedStyle(element);
+
+			// Should have a box shadow
+			expect(styles.boxShadow).not.toBe("none");
+		});
+
+		test("tooltip has high z-index", async () => {
+			render(
+				<Tooltip content="Styled tooltip" defaultOpen>
+					<Button>Trigger</Button>
+				</Tooltip>,
+			);
+
+			const tooltip = page.getByRole("tooltip");
+			await expect.element(tooltip).toBeInTheDocument();
+
+			const element = tooltip.element();
+			const styles = window.getComputedStyle(element);
+
+			// Should have z-index of 50 or higher
+			const zIndex = parseInt(styles.zIndex, 10);
+			expect(zIndex).toBeGreaterThanOrEqual(50);
+		});
+	});
+});

package/src/components/atoms/tooltip/tooltip.tsx

@@ -0,0 +1,347 @@
+"use client";
+
+import { Tooltip as BaseTooltip } from "@base-ui-components/react/tooltip";
+import * as React from "react";
+import { tv, type VariantProps } from "tailwind-variants";
+import { cn } from "@/lib/utils";
+import {
+	FloatingArrowSvg,
+	floatingArrowVariants,
+} from "../../shared/floating-arrow";
+
+/**
+ * Tooltip popup variants
+ *
+ * Uses semantic tokens for themeable styling:
+ * - color.tooltip.bg - Dark background
+ * - color.tooltip.text - Light text
+ * - surface.tooltip.radius - Small border radius
+ * - spatial.component.tooltip.padding-x/y - Consistent padding
+ */
+const tooltipPopupVariants = tv({
+	base: [
+		// Layout - uses component tooltip tokens
+		"px-spatial-component-tooltip-padding-x py-spatial-component-tooltip-padding-y",
+		// Background and text - uses tooltip color tokens
+		"bg-tooltip-bg text-tooltip-text",
+		// Border radius - uses surface tooltip token
+		"rounded-surface-tooltip",
+		// Typography - uses semantic body text composite
+		"typography-body-sm-md font-medium",
+		// Shadow for elevation
+		"shadow-md",
+		// Allow arrow to extend outside popup bounds
+		"overflow-visible",
+		// Animation
+		"origin-[var(--transform-origin)]",
+		"transition-[transform,scale,opacity] duration-150",
+		"data-[starting-style]:scale-95 data-[starting-style]:opacity-0",
+		"data-[ending-style]:scale-95 data-[ending-style]:opacity-0",
+		// Ensure it's above other content
+		"z-50",
+	],
+	variants: {
+		variant: {
+			default: "",
+			// Future variants can be added here (e.g., light, primary)
+		},
+	},
+	defaultVariants: {
+		variant: "default",
+	},
+});
+
+/**
+ * Tooltip arrow variants - uses shared floating arrow variants
+ */
+const tooltipArrowVariants = floatingArrowVariants;
+
+// ============================================================================
+// Tooltip Provider
+// ============================================================================
+
+export interface TooltipProviderProps extends BaseTooltip.Provider.Props {
+	children: React.ReactNode;
+}
+
+/**
+ * Tooltip Provider
+ *
+ * Manages shared delays across multiple tooltips.
+ * Wrap your app or a section with this to enable tooltip delay grouping.
+ */
+const TooltipProvider = ({ children, ...props }: TooltipProviderProps) => {
+	return <BaseTooltip.Provider {...props}>{children}</BaseTooltip.Provider>;
+};
+
+// ============================================================================
+// Tooltip Root
+// ============================================================================
+
+export interface TooltipRootProps extends BaseTooltip.Root.Props {
+	children: React.ReactNode;
+}
+
+/**
+ * Tooltip Root
+ *
+ * Groups all tooltip parts. Does not render an element.
+ */
+const TooltipRoot = ({ children, ...props }: TooltipRootProps) => {
+	return <BaseTooltip.Root {...props}>{children}</BaseTooltip.Root>;
+};
+
+// ============================================================================
+// Tooltip Trigger
+// ============================================================================
+
+export interface TooltipTriggerProps
+	extends React.ComponentProps<typeof BaseTooltip.Trigger> {
+	className?: string;
+}
+
+/**
+ * Tooltip Trigger
+ *
+ * The element that triggers the tooltip on hover/focus.
+ * Renders as the child element with tooltip behavior attached.
+ * When children is a single React element, uses `render` prop to avoid wrapper element.
+ */
+const TooltipTrigger = React.forwardRef<HTMLButtonElement, TooltipTriggerProps>(
+	({ className, children, ...props }, ref) => {
+		// If children is a single React element, use render prop to avoid wrapper
+		const isSingleElement = React.isValidElement(children);
+
+		if (isSingleElement) {
+			return (
+				<BaseTooltip.Trigger
+					ref={ref}
+					className={className}
+					render={children}
+					{...props}
+				/>
+			);
+		}
+
+		return (
+			<BaseTooltip.Trigger ref={ref} className={className} {...props}>
+				{children}
+			</BaseTooltip.Trigger>
+		);
+	},
+);
+TooltipTrigger.displayName = "TooltipTrigger";
+
+// ============================================================================
+// Tooltip Portal
+// ============================================================================
+
+export interface TooltipPortalProps extends BaseTooltip.Portal.Props {
+	children: React.ReactNode;
+}
+
+/**
+ * Tooltip Portal
+ *
+ * Renders the tooltip popup in a portal outside the DOM hierarchy.
+ */
+const TooltipPortal = ({ children, ...props }: TooltipPortalProps) => {
+	return <BaseTooltip.Portal {...props}>{children}</BaseTooltip.Portal>;
+};
+
+// ============================================================================
+// Tooltip Positioner
+// ============================================================================
+
+export interface TooltipPositionerProps
+	extends Omit<
+		React.ComponentProps<typeof BaseTooltip.Positioner>,
+		"className"
+	> {
+	className?: string;
+}
+
+/**
+ * Tooltip Positioner
+ *
+ * Positions the tooltip popup relative to the trigger.
+ */
+const TooltipPositioner = React.forwardRef<
+	HTMLDivElement,
+	TooltipPositionerProps
+>(({ className, side = "top", sideOffset = 8, ...props }, ref) => {
+	return (
+		<BaseTooltip.Positioner
+			ref={ref}
+			side={side}
+			sideOffset={sideOffset}
+			className={className}
+			{...props}
+		/>
+	);
+});
+TooltipPositioner.displayName = "TooltipPositioner";
+
+// ============================================================================
+// Tooltip Popup
+// ============================================================================
+
+export interface TooltipPopupProps
+	extends Omit<React.ComponentProps<typeof BaseTooltip.Popup>, "className">,
+		VariantProps<typeof tooltipPopupVariants> {
+	className?: string;
+}
+
+/**
+ * Tooltip Popup
+ *
+ * The tooltip content container with styled appearance.
+ */
+const TooltipPopup = React.forwardRef<HTMLDivElement, TooltipPopupProps>(
+	({ className, variant, ...props }, ref) => {
+		return (
+			<BaseTooltip.Popup
+				ref={ref}
+				role="tooltip"
+				className={cn(tooltipPopupVariants({ variant }), className)}
+				{...props}
+			/>
+		);
+	},
+);
+TooltipPopup.displayName = "TooltipPopup";
+
+// ============================================================================
+// Tooltip Arrow
+// ============================================================================
+
+export interface TooltipArrowProps
+	extends Omit<React.ComponentProps<typeof BaseTooltip.Arrow>, "className"> {
+	className?: string;
+}
+
+/**
+ * Tooltip Arrow
+ *
+ * Visual pointer element for the tooltip.
+ * Uses shared FloatingArrowSvg with tooltip-bg color token.
+ */
+const TooltipArrow = React.forwardRef<HTMLDivElement, TooltipArrowProps>(
+	({ className, ...props }, ref) => {
+		return (
+			<BaseTooltip.Arrow
+				ref={ref}
+				className={cn(tooltipArrowVariants(), className)}
+				{...props}
+			>
+				<FloatingArrowSvg fillClassName="fill-tooltip-bg" />
+			</BaseTooltip.Arrow>
+		);
+	},
+);
+TooltipArrow.displayName = "TooltipArrow";
+
+// ============================================================================
+// Simple Tooltip Component
+// ============================================================================
+
+export interface TooltipProps {
+	/** The content to show in the tooltip */
+	content: React.ReactNode;
+	/** The element that triggers the tooltip */
+	children: React.ReactNode;
+	/** Side of the trigger to show the tooltip */
+	side?: "top" | "bottom" | "left" | "right";
+	/** Offset from the trigger */
+	sideOffset?: number;
+	/** Alignment along the side */
+	align?: "start" | "center" | "end";
+	/** Delay before showing the tooltip (ms) */
+	delay?: number;
+	/** Delay before hiding the tooltip (ms) */
+	closeDelay?: number;
+	/** Whether to show an arrow */
+	showArrow?: boolean;
+	/** Controlled open state */
+	open?: boolean;
+	/** Default open state */
+	defaultOpen?: boolean;
+	/** Callback when open state changes */
+	onOpenChange?: (open: boolean) => void;
+	/** Additional className for the popup */
+	className?: string;
+}
+
+/**
+ * Tooltip
+ *
+ * A simple, pre-composed tooltip component for common use cases.
+ *
+ * @example
+ * ```tsx
+ * <Tooltip content="Save your changes">
+ *   <Button>Save</Button>
+ * </Tooltip>
+ * ```
+ */
+const Tooltip = ({
+	content,
+	children,
+	side = "top",
+	sideOffset = 8,
+	align = "center",
+	delay,
+	closeDelay,
+	showArrow = true,
+	open,
+	defaultOpen,
+	onOpenChange,
+	className,
+}: TooltipProps) => {
+	return (
+		<TooltipRoot
+			open={open}
+			defaultOpen={defaultOpen}
+			onOpenChange={onOpenChange}
+		>
+			<TooltipTrigger delay={delay} closeDelay={closeDelay}>
+				{children}
+			</TooltipTrigger>
+			<TooltipPortal>
+				<TooltipPositioner side={side} sideOffset={sideOffset} align={align}>
+					<TooltipPopup className={className}>
+						{showArrow && <TooltipArrow />}
+						{content}
+					</TooltipPopup>
+				</TooltipPositioner>
+			</TooltipPortal>
+		</TooltipRoot>
+	);
+};
+
+// ============================================================================
+// Compound Component Export
+// ============================================================================
+
+export const TooltipParts = Object.assign(TooltipRoot, {
+	Provider: TooltipProvider,
+	Root: TooltipRoot,
+	Trigger: TooltipTrigger,
+	Portal: TooltipPortal,
+	Positioner: TooltipPositioner,
+	Popup: TooltipPopup,
+	Arrow: TooltipArrow,
+});
+
+export {
+	Tooltip,
+	TooltipProvider,
+	TooltipRoot,
+	TooltipTrigger,
+	TooltipPortal,
+	TooltipPositioner,
+	TooltipPopup,
+	TooltipArrow,
+	tooltipPopupVariants,
+	tooltipArrowVariants,
+};