@bug-on/md3-react 2.0.3 → 3.0.0

package/src/ui/card.test.tsx

@@ -0,0 +1,187 @@
+"use client";
+
+import { fireEvent, render, screen } from "@testing-library/react";
+import * as MotionReact from "motion/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Card } from "./card";
+
+// Mock motion/react – tương tự pattern trong button.test.tsx
+vi.mock("motion/react", async (importOriginal) => {
+	const actual = await importOriginal<typeof import("motion/react")>();
+	return {
+		...actual,
+		useReducedMotion: () => false,
+	};
+});
+
+const renderCard = (props = {}, children = <p>Content</p>) =>
+	render(<Card {...props}>{children}</Card>);
+
+describe("Card Component", () => {
+	afterEach(() => {
+		vi.restoreAllMocks();
+	});
+
+	// ── Static Card ──────────────────────────────────────────────────────────
+
+	describe("static card (no interaction)", () => {
+		it("renders a <div> when no onClick/href/interactive given", () => {
+			const { container } = renderCard();
+			expect(container.firstChild?.nodeName).toBe("DIV");
+		});
+
+		it("does not have tabIndex on static card", () => {
+			const { container } = renderCard();
+			expect(container.firstChild).not.toHaveAttribute("tabIndex");
+		});
+
+		it("renders children inside the card", () => {
+			renderCard({}, <span data-testid="child">Hello</span>);
+			expect(screen.getByTestId("child")).toBeInTheDocument();
+		});
+	});
+
+	// ── Interactive Card (onClick) ────────────────────────────────────────────
+
+	describe("interactive card (onClick prop)", () => {
+		it("renders a <button> when onClick is provided", () => {
+			renderCard({ onClick: vi.fn() });
+			expect(screen.getByRole("button")).toBeInTheDocument();
+		});
+
+		it("has tabIndex={0} when interactive", () => {
+			renderCard({ onClick: vi.fn() });
+			expect(screen.getByRole("button")).toHaveAttribute("tabIndex", "0");
+		});
+
+		it("calls onClick when clicked", () => {
+			const handleClick = vi.fn();
+			renderCard({ onClick: handleClick });
+			fireEvent.click(screen.getByRole("button"));
+			expect(handleClick).toHaveBeenCalledTimes(1);
+		});
+
+		it("triggers ripple on pointerDown", () => {
+			renderCard({ onClick: vi.fn() });
+			const btn = screen.getByRole("button");
+			fireEvent.pointerDown(btn, { clientX: 10, clientY: 10 });
+			// Ripple mounts a span[aria-hidden] inside the button
+			expect(btn.querySelector("span[aria-hidden='true']")).not.toBeNull();
+		});
+	});
+
+	// ── Interactive Card (interactive prop) ───────────────────────────────────
+
+	describe("interactive card (interactive prop)", () => {
+		it("renders a <button> when interactive=true even without onClick", () => {
+			renderCard({ interactive: true });
+			expect(screen.getByRole("button")).toBeInTheDocument();
+		});
+
+		it("has tabIndex={0} when interactive=true", () => {
+			renderCard({ interactive: true });
+			expect(screen.getByRole("button")).toHaveAttribute("tabIndex", "0");
+		});
+	});
+
+	// ── Link Card (href) ───────────────────────────────────────────────────────
+
+	describe("link card (href prop)", () => {
+		it("renders an <a> tag when href is provided", () => {
+			renderCard({ href: "/some-page" });
+			expect(screen.getByRole("link")).toBeInTheDocument();
+		});
+
+		it("passes href attribute to the <a> element", () => {
+			renderCard({ href: "/some-page" });
+			expect(screen.getByRole("link")).toHaveAttribute("href", "/some-page");
+		});
+
+		it("adds rel='noreferrer' automatically when target='_blank'", () => {
+			renderCard({ href: "https://example.com", target: "_blank" });
+			expect(screen.getByRole("link")).toHaveAttribute("rel", "noreferrer");
+		});
+
+		it("does not add rel when target is not '_blank'", () => {
+			renderCard({ href: "/internal", target: "_self" });
+			expect(screen.getByRole("link")).not.toHaveAttribute("rel");
+		});
+	});
+
+	// ── Disabled State ────────────────────────────────────────────────────────
+
+	describe("disabled state", () => {
+		it("static card: has aria-disabled when disabled=true", () => {
+			const { container } = renderCard({ disabled: true });
+			expect(container.firstChild).toHaveAttribute("aria-disabled", "true");
+		});
+
+		it("interactive card: has aria-disabled when disabled=true", () => {
+			renderCard({ onClick: vi.fn(), disabled: true });
+			expect(screen.getByRole("button")).toHaveAttribute(
+				"aria-disabled",
+				"true",
+			);
+		});
+
+		it("interactive card: has tabIndex=-1 when disabled", () => {
+			renderCard({ onClick: vi.fn(), disabled: true });
+			expect(screen.getByRole("button")).toHaveAttribute("tabIndex", "-1");
+		});
+
+		it("interactive card: has 'pointer-events-none' class when disabled", () => {
+			renderCard({ onClick: vi.fn(), disabled: true });
+			expect(screen.getByRole("button").className).toContain(
+				"pointer-events-none",
+			);
+		});
+
+		it("interactive card: has 'opacity-[0.38]' class when disabled", () => {
+			renderCard({ onClick: vi.fn(), disabled: true });
+			expect(screen.getByRole("button").className).toMatch(/opacity-\[0\.38\]/);
+		});
+
+		it("link card: href is removed when disabled", () => {
+			const { container } = renderCard({ href: "/page", disabled: true });
+			// When disabled, href is set to undefined so the <a> has no href attribute.
+			// Note: without href, the element loses its "link" role, so we query by tag.
+			const anchor = container.querySelector("a");
+			expect(anchor).toBeInTheDocument();
+			expect(anchor).not.toHaveAttribute("href");
+		});
+	});
+
+	// ── Variant Token Classes ─────────────────────────────────────────────────
+
+	describe("variant token classes (MD3)", () => {
+		it("elevated variant → bg-m3-surface-container-low", () => {
+			const { container } = renderCard({ variant: "elevated" });
+			expect(container.firstChild).toHaveClass("bg-m3-surface-container-low");
+		});
+
+		it("filled variant → bg-m3-surface-container-highest", () => {
+			const { container } = renderCard({ variant: "filled" });
+			expect(container.firstChild).toHaveClass(
+				"bg-m3-surface-container-highest",
+			);
+		});
+
+		it("outlined variant → bg-m3-surface + border-m3-outline-variant", () => {
+			const { container } = renderCard({ variant: "outlined" });
+			expect(container.firstChild).toHaveClass("bg-m3-surface");
+			expect(container.firstChild).toHaveClass("border-m3-outline-variant");
+		});
+	});
+
+	// ── A11y: prefers-reduced-motion ──────────────────────────────────────────
+
+	describe("accessibility - reduced motion", () => {
+		it("Ripple renders nothing when prefers-reduced-motion is active", () => {
+			vi.spyOn(MotionReact, "useReducedMotion").mockReturnValue(true);
+			renderCard({ onClick: vi.fn() });
+			const btn = screen.getByRole("button");
+			fireEvent.pointerDown(btn, { clientX: 5, clientY: 5 });
+			expect(btn.querySelector("span[aria-hidden='true']")).toBeNull();
+		});
+	});
+});

package/src/ui/card.tsx

@@ -0,0 +1,259 @@
+/**
+ * @file card.tsx
+ *
+ * Thẻ Card của bộ khung MD3 Expressive.
+ *
+ * Phân chia làm hai khía cạnh chức năng (cấu trúc tham khảo từ con ruột Android Card.kt):
+ * - **Tĩnh Lặng (Static)**    → đơn thuần mang thẻ `<div>`, yên tĩnh và không hề mảy may phản hồi có tương tác nào.
+ * - **Có phản ứng (Interactive)** → được phù phép bằng `<motion.button>` hoặc `<motion.a>`, mang bùa Ripple vẫy sống cùng khả năng nhảy vọt elevation khi lướt lên.
+ *
+ * Nấc độ bóng Elevation levels (dịch từ các file mã ElevatedCardTokens / FilledCardTokens / OutlinedCardTokens / Elevation.kt):
+ * - Level 0 = "none" (Bằng phẳng)
+ * - Level 1 = box-shadow ~1dp (Hơi nhỉnh nổi nhẹ)
+ * - Level 2 = box-shadow ~2dp (Bay lên cao xíu)
+ *
+ * @example
+ * ```tsx
+ * // Card tĩnh
+ * <Card variant="elevated">
+ *   <div className="p-4">Nội dung thẻ Card nhẹ nhàng</div>
+ * </Card>
+ *
+ * // Card button tương tác
+ * <Card variant="filled" onClick={() => alert('Đã nhấn!')}>
+ *   <div className="p-4">Click vào đây em ei</div>
+ * </Card>
+ *
+ * // Card làm thẻ Link a
+ * <Card variant="outlined" href="/home">
+ *   <div className="p-4">Click để chuyển trang</div>
+ * </Card>
+ * ```
+ *
+ * @see https://m3.material.io/components/cards/overview
+ */
+
+import { cva, type VariantProps } from "class-variance-authority";
+import type { HTMLMotionProps } from "motion/react";
+import { domMax, LazyMotion, m } from "motion/react";
+import * as React from "react";
+import { cn } from "../lib/utils";
+import { Ripple, useRippleState } from "./ripple";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MD3 Elevation Shadows (from packages/tailwind/src/index.ts)
+// ─────────────────────────────────────────────────────────────────────────────
+const SHADOW = {
+	level0: "none",
+	level1: "0px 1px 2px 0px rgba(0,0,0,.3), 0px 1px 3px 1px rgba(0,0,0,.15)",
+	level2: "0px 1px 2px 0px rgba(0,0,0,.3), 0px 2px 6px 2px rgba(0,0,0,.15)",
+} as const;
+
+// Maps each variant to its elevation levels per interaction state.
+// Source: ElevatedCardTokens.kt, FilledCardTokens.kt, OutlinedCardTokens.kt
+const VARIANT_ELEVATION = {
+	elevated: {
+		rest: SHADOW.level1,
+		hover: SHADOW.level2,
+		pressed: SHADOW.level1,
+		disabled: SHADOW.level1, // ElevatedCardTokens.DisabledContainerElevation = Level1
+	},
+	filled: {
+		rest: SHADOW.level0,
+		hover: SHADOW.level1,
+		pressed: SHADOW.level0,
+		disabled: SHADOW.level0,
+	},
+	outlined: {
+		rest: SHADOW.level0,
+		hover: SHADOW.level1,
+		pressed: SHADOW.level0,
+		disabled: SHADOW.level0,
+	},
+} as const;
+
+type CardVariant = keyof typeof VARIANT_ELEVATION;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CVA – Variant base classes (token-aligned with MD3)
+// ─────────────────────────────────────────────────────────────────────────────
+const cardVariants = cva(
+	"rounded-m3-lg flex flex-col relative overflow-hidden transition-colors duration-200",
+	{
+		variants: {
+			variant: {
+				// ElevatedCardTokens.ContainerColor = SurfaceContainerLow
+				elevated: "bg-m3-surface-container-low",
+				// FilledCardTokens.ContainerColor = SurfaceContainerHighest
+				filled: "bg-m3-surface-container-highest",
+				// OutlinedCardTokens.ContainerColor = Surface, OutlineColor = OutlineVariant
+				outlined: "bg-m3-surface border border-m3-outline-variant",
+			},
+		},
+		defaultVariants: { variant: "elevated" },
+	},
+);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook: Card Elevation Animation
+// Mirrors animateElevation() from Elevation.kt.
+// Returns motion animation props for interactive boxShadow transitions.
+// ─────────────────────────────────────────────────────────────────────────────
+function useCardElevation(variant: CardVariant, disabled: boolean) {
+	const levels = VARIANT_ELEVATION[variant];
+	return {
+		animate: { boxShadow: disabled ? levels.disabled : levels.rest },
+		whileHover: disabled ? undefined : { boxShadow: levels.hover },
+		whileTap: disabled ? undefined : { boxShadow: levels.pressed },
+		whileFocus: disabled ? undefined : { boxShadow: levels.hover },
+		transition: {
+			boxShadow: {
+				// Incoming: 120ms (from Elevation.kt DefaultIncomingSpec)
+				duration: 0.12,
+				ease: [0.4, 0, 0.2, 1] as [number, number, number, number],
+			},
+		},
+	};
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// Use HTMLMotionProps<"button"> as the base to avoid onDrag / event handler
+// conflicts between native React HTMLAttributes and Motion's extended prop types.
+// ─────────────────────────────────────────────────────────────────────────────
+type MotionDivProps = Omit<HTMLMotionProps<"button">, "children" | "color">;
+
+export interface CardProps
+	extends MotionDivProps,
+		VariantProps<typeof cardVariants> {
+	/** Vô hiệu hóa tương tác và giảm opacity (MD3 disabled state). */
+	disabled?: boolean;
+	/**
+	 * Buộc card trở thành interactive dù không có `onClick`.
+	 * Hữu ích khi card chứa các element con là interactive.
+	 */
+	interactive?: boolean;
+	/**
+	 * Nếu có, card render thành thẻ `<a>`. Tự động kích hoạt interactive mode.
+	 * Ưu tiên dùng `href` thay vì `onClick` khi điều hướng trang.
+	 */
+	href?: string;
+	/** Target cho thẻ `<a>` (chỉ có hiệu lực khi `href` được cung cấp). */
+	target?: React.AnchorHTMLAttributes<HTMLAnchorElement>["target"];
+	/** rel cho thẻ `<a>` (tự động thêm `noreferrer` khi `target="_blank"`). */
+	rel?: string;
+	children?: React.ReactNode;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Component
+// ─────────────────────────────────────────────────────────────────────────────
+const CardImpl = React.forwardRef<HTMLElement, CardProps>(
+	(
+		{
+			className,
+			variant = "elevated",
+			disabled = false,
+			interactive = false,
+			href,
+			target,
+			rel: relProp,
+			onClick,
+			children,
+			...props
+		},
+		ref,
+	) => {
+		const safeVariant = variant as CardVariant;
+		const isInteractive = !!onClick || !!href || interactive;
+		const elevationProps = useCardElevation(safeVariant, disabled);
+		const { ripples, onPointerDown, removeRipple } = useRippleState();
+
+		const baseClass = cn(
+			cardVariants({ variant }),
+			// Disabled state:
+			// - pointer-events-none → vô hiệu hóa tương tác hoàn toàn
+			// - opacity-[0.38] → MD3 DisabledContainerOpacity
+			disabled && "pointer-events-none opacity-[0.38]",
+			className,
+		);
+
+		// MD3 State Layer (Hover: 8%, Focus: 10%, Pressed: 10%)
+		// Áp dụng cho interactive elements, dùng absolute inset ::before
+		const interactiveClass = cn(
+			// Xóa outline default, dùng state overlay & elevation của MD3 để biểu hiện focus
+			"focus-visible:outline-none focus:outline-none group",
+			// Layer overlay base pseudo-element
+			"before:absolute before:inset-0 before:pointer-events-none before:bg-m3-on-surface before:opacity-0 before:transition-opacity before:duration-200",
+			// Interactive states opacities
+			"hover:before:opacity-[0.08] focus-visible:before:opacity-[0.10] active:before:opacity-[0.10]",
+			// Outlined interactive card: đổi màu border sang m3-outline khi focus/press/hover
+			variant === "outlined" &&
+				"hover:border-m3-outline focus-visible:border-m3-outline active:border-m3-outline",
+		);
+
+		// ── Static Card – không có interaction ─────────────────────────────────
+		if (!isInteractive) {
+			return (
+				<div
+					ref={ref as React.Ref<HTMLDivElement>}
+					className={baseClass}
+					aria-disabled={disabled ? true : undefined}
+				>
+					{children}
+				</div>
+			);
+		}
+
+		// ── Safe rel: tự động thêm "noreferrer" khi target="_blank" ────────────
+		const safeRel = href
+			? (relProp ?? (target === "_blank" ? "noreferrer" : undefined))
+			: undefined;
+
+		// ── Link Card ────────────────────────────────────────────────────────────
+		if (href) {
+			return (
+				<LazyMotion features={domMax} strict>
+					<m.a
+						ref={ref as React.Ref<HTMLAnchorElement>}
+						href={disabled ? undefined : href}
+						target={target}
+						rel={safeRel}
+						className={cn(baseClass, interactiveClass)}
+						aria-disabled={disabled ? true : undefined}
+						tabIndex={disabled ? -1 : 0}
+						onPointerDown={onPointerDown}
+						{...elevationProps}
+					>
+						<Ripple ripples={ripples} onRippleDone={removeRipple} />
+						{children}
+					</m.a>
+				</LazyMotion>
+			);
+		}
+
+		// ── Interactive Button Card ──────────────────────────────────────────────
+		return (
+			<LazyMotion features={domMax} strict>
+				<m.button
+					ref={ref as React.Ref<HTMLButtonElement>}
+					type="button"
+					disabled={disabled}
+					onClick={onClick}
+					className={cn(baseClass, interactiveClass)}
+					aria-disabled={disabled ? true : undefined}
+					tabIndex={disabled ? -1 : 0}
+					onPointerDown={onPointerDown}
+					{...elevationProps}
+					{...props}
+				>
+					<Ripple ripples={ripples} onRippleDone={removeRipple} />
+					{children}
+				</m.button>
+			</LazyMotion>
+		);
+	},
+);
+CardImpl.displayName = "Card";
+
+export const Card = React.memo(CardImpl);