@bug-on/md3-react 2.0.2 → 3.0.0

package/src/ui/icon.test.tsx

@@ -0,0 +1,197 @@
+/**
+ * @file icon.test.tsx
+ *
+ * Unit tests for the Material Symbols <Icon /> component.
+ *
+ * Tests cover:
+ *  - Correct text content (icon name as ligature)
+ *  - Font-family for each variant (outlined / rounded / sharp)
+ *  - font-variation-settings reflecting fill / weight / grade / opticalSize
+ *  - aria-hidden attribute
+ *  - className merging
+ *  - Static render (plain span) vs animated render (motion span)
+ *  - size prop overrides font-size independently of opticalSize
+ */
+
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+import { Icon } from "./icon";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Returns the rendered span's inline style object. */
+function getStyle(element: HTMLElement): CSSStyleDeclaration {
+	return element.style;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Tests
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("Icon", () => {
+	// ── Rendering ─────────────────────────────────────────────────────────────
+
+	it("renders the icon name as text content", () => {
+		render(<Icon name="home" />);
+		expect(screen.getByText("home")).toBeInTheDocument();
+	});
+
+	it("renders the icon name with underscores intact", () => {
+		render(<Icon name="arrow_forward" />);
+		expect(screen.getByText("arrow_forward")).toBeInTheDocument();
+	});
+
+	// ── Accessibility ─────────────────────────────────────────────────────────
+
+	it("sets aria-hidden='true' by default", () => {
+		render(<Icon name="home" />);
+		const el = screen.getByText("home");
+		expect(el).toHaveAttribute("aria-hidden", "true");
+	});
+
+	// ── Variant font-family ───────────────────────────────────────────────────
+
+	it("uses 'Material Symbols Outlined' font by default (outlined variant)", () => {
+		render(<Icon name="home" />);
+		const style = getStyle(screen.getByText("home"));
+		expect(style.fontFamily).toContain("Material Symbols Outlined");
+	});
+
+	it("uses 'Material Symbols Rounded' for variant='rounded'", () => {
+		render(<Icon name="home" variant="rounded" />);
+		const style = getStyle(screen.getByText("home"));
+		expect(style.fontFamily).toContain("Material Symbols Rounded");
+	});
+
+	it("uses 'Material Symbols Sharp' for variant='sharp'", () => {
+		render(<Icon name="home" variant="sharp" />);
+		const style = getStyle(screen.getByText("home"));
+		expect(style.fontFamily).toContain("Material Symbols Sharp");
+	});
+
+	// ── Font size ─────────────────────────────────────────────────────────────
+
+	it("defaults font-size to opticalSize (24px) when size is not provided", () => {
+		render(<Icon name="home" />);
+		const style = getStyle(screen.getByText("home"));
+		expect(style.fontSize).toBe("24px");
+	});
+
+	it("uses explicit size prop for font-size (overrides opticalSize)", () => {
+		render(<Icon name="home" size={18} opticalSize={20} />);
+		const style = getStyle(screen.getByText("home"));
+		expect(style.fontSize).toBe("18px");
+	});
+
+	it("applies opticalSize=48 as font-size when no explicit size given", () => {
+		render(<Icon name="home" opticalSize={48} />);
+		const style = getStyle(screen.getByText("home"));
+		expect(style.fontSize).toBe("48px");
+	});
+
+	// ── font-variation-settings ───────────────────────────────────────────────
+
+	it("applies default font-variation-settings (fill=0, wght=400, GRAD=0, opsz=24)", () => {
+		render(<Icon name="home" />);
+		const style = getStyle(screen.getByText("home"));
+		expect(style.fontVariationSettings).toBe(
+			"'FILL' 0, 'wght' 400, 'GRAD' 0, 'opsz' 24",
+		);
+	});
+
+	it("reflects fill=1 in font-variation-settings", () => {
+		render(<Icon name="favorite" fill={1} />);
+		const style = getStyle(screen.getByText("favorite"));
+		expect(style.fontVariationSettings).toContain("'FILL' 1");
+	});
+
+	it("reflects weight=700 in font-variation-settings", () => {
+		render(<Icon name="home" weight={700} />);
+		const style = getStyle(screen.getByText("home"));
+		expect(style.fontVariationSettings).toContain("'wght' 700");
+	});
+
+	it("reflects grade=-25 in font-variation-settings", () => {
+		render(<Icon name="home" grade={-25} />);
+		const style = getStyle(screen.getByText("home"));
+		expect(style.fontVariationSettings).toContain("'GRAD' -25");
+	});
+
+	it("reflects opticalSize=48 in font-variation-settings opsz axis", () => {
+		render(<Icon name="home" opticalSize={48} />);
+		const style = getStyle(screen.getByText("home"));
+		expect(style.fontVariationSettings).toContain("'opsz' 48");
+	});
+
+	it("composes all axes correctly when all props are provided", () => {
+		render(
+			<Icon name="star" fill={1} weight={300} grade={200} opticalSize={40} />,
+		);
+		const style = getStyle(screen.getByText("star"));
+		expect(style.fontVariationSettings).toBe(
+			"'FILL' 1, 'wght' 300, 'GRAD' 200, 'opsz' 40",
+		);
+	});
+
+	// ── className merging ─────────────────────────────────────────────────────
+
+	it("includes 'md-icon' base class by default", () => {
+		render(<Icon name="home" />);
+		const el = screen.getByText("home");
+		expect(el.className).toContain("md-icon");
+	});
+
+	it("merges additional className with md-icon", () => {
+		render(<Icon name="home" className="text-primary" />);
+		const el = screen.getByText("home");
+		expect(el.className).toContain("md-icon");
+		expect(el.className).toContain("text-primary");
+	});
+
+	// ── Static vs animated render ─────────────────────────────────────────────
+
+	it("renders a plain <span> when animateFill is false (default)", () => {
+		const { container } = render(<Icon name="home" />);
+		// motion/react m.span renders as a <span> in DOM, but static span has no
+		// data-framer / motion attributes injected. We check the element is a span.
+		const el = container.querySelector("span");
+		expect(el).not.toBeNull();
+		expect(el?.textContent).toBe("home");
+	});
+
+	it("still renders as a span element when animateFill=true (motion renders span)", () => {
+		const { container } = render(<Icon name="home" animateFill />);
+		// m.span renders as a real <span> in DOM
+		const el = container.querySelector("span");
+		expect(el).not.toBeNull();
+		expect(el?.textContent).toBe("home");
+	});
+
+	it("sets aria-hidden on animated span too", () => {
+		render(<Icon name="home" animateFill />);
+		const el = screen.getByText("home");
+		expect(el).toHaveAttribute("aria-hidden", "true");
+	});
+
+	// ── style prop passthrough ────────────────────────────────────────────────
+
+	it("merges custom style with computed style", () => {
+		render(<Icon name="home" style={{ color: "red" }} />);
+		const el = screen.getByText("home");
+		expect(el.style.color).toBe("red");
+		// Computed props still present
+		expect(el.style.fontFamily).toContain("Material Symbols Outlined");
+	});
+
+	// ── displayName ───────────────────────────────────────────────────────────
+
+	it("has displayName 'Icon'", () => {
+		// React.memo wraps the component; access display name via the inner type
+		// biome-ignore lint/suspicious/noExplicitAny: accessing React internals for testing
+		expect((Icon as any).type?.displayName ?? (Icon as any).displayName).toBe(
+			"Icon",
+		);
+	});
+});

package/src/ui/icon.tsx

@@ -0,0 +1,179 @@
+import { domMax, LazyMotion, m } from "motion/react";
+import * as React from "react";
+import { cn } from "../lib/utils";
+import { SPRING_TRANSITION_FAST } from "./shared/constants";
+
+// @internal — font must be loaded via '@bug-on/md3-react/material-symbols.css'
+const VARIANT_FONT: Record<NonNullable<IconProps["variant"]>, string> = {
+	outlined: "'Material Symbols Outlined'",
+	rounded: "'Material Symbols Rounded'",
+	sharp: "'Material Symbols Sharp'",
+};
+
+/**
+ * Props cho component {@link Icon}.
+ *
+ * Tất cả các trục biến thiên (variable font axes) được map trực tiếp sang `font-variation-settings`.
+ */
+export interface IconProps extends React.HTMLAttributes<HTMLSpanElement> {
+	/**
+	 * Tên của Material Symbol theo định dạng snake_case.
+	 * @example "home", "arrow_forward", "settings"
+	 * @see https://fonts.google.com/icons
+	 */
+	name: string;
+
+	/**
+	 * Kiểu hình học (Geometric style variant) — tương ứng với font family được tải.
+	 * @default "outlined"
+	 */
+	variant?: "outlined" | "rounded" | "sharp";
+
+	/**
+	 * Trục FILL. `0` = outlined (viền), `1` = filled (tràn màu).
+	 * Có hiệu ứng spring khi `animateFill` là true.
+	 * @default 0
+	 */
+	fill?: 0 | 1;
+
+	/**
+	 * Trục wght — độ dày của nét (stroke weight). Nên khớp với độ dày text xung quanh.
+	 * @default 400
+	 */
+	weight?: 100 | 200 | 300 | 400 | 500 | 600 | 700;
+
+	/**
+	 * Trục GRAD — tinh chỉnh độ dày thị giác mà không ảnh hưởng tới layout.
+	 * Dùng mức `-25` trên nền tối để bù trừ hiệu ứng phát sáng (halation).
+	 * @default 0
+	 */
+	grade?: -50 | -25 | 0 | 100 | 200;
+
+	/**
+	 * Trục opsz — kích thước quang học (optical size) tính bằng dp. Dùng để thiết lập `font-size` nếu không truyền `size`.
+	 * Hãy để giá trị khớp với pixel sẽ render ra để thấy chất lượng tốt nhất.
+	 * @default 24
+	 */
+	opticalSize?: 20 | 24 | 40 | 48;
+
+	/**
+	 * Ghi đè trực tiếp `font-size` bằng px. Trục `opsz` vẫn sẽ tuân theo thuộc tính `opticalSize`.
+	 * @example size={18} opticalSize={20}
+	 */
+	size?: number | "inherit";
+
+	/**
+	 * Kích hoạt hiệu ứng spring mượt mà khi chuyển đổi giá trị FILL (sử dụng cấu hình `SPRING_TRANSITION_FAST`).
+	 * Yêu cầu dependency `motion/react`.
+	 * @default false
+	 * @example <Icon name="favorite" fill={isLiked ? 1 : 0} animateFill />
+	 */
+	animateFill?: boolean;
+}
+
+const IconComponent = React.forwardRef<HTMLSpanElement, IconProps>(
+	(
+		{
+			name,
+			variant = "outlined",
+			fill = 0,
+			weight = 400,
+			grade = 0,
+			opticalSize = 24,
+			size,
+			animateFill = false,
+			className,
+			style,
+			...restProps
+		},
+		ref,
+	) => {
+		const fontVariationSettings = `'FILL' ${fill}, 'wght' ${weight}, 'GRAD' ${grade}, 'opsz' ${opticalSize}`;
+
+		const computedStyle: React.CSSProperties = {
+			fontFamily: VARIANT_FONT[variant],
+			fontSize:
+				size === "inherit"
+					? "inherit"
+					: size != null
+						? `${size}px`
+						: `${opticalSize}px`,
+			fontVariationSettings,
+			...style,
+		};
+
+		if (animateFill) {
+			return (
+				<LazyMotion features={domMax} strict>
+					<m.span
+						ref={ref}
+						className={cn(
+							"md-icon inline-flex items-center justify-center shrink-0 select-none",
+							className,
+						)}
+						aria-hidden="true"
+						animate={{ fontVariationSettings }}
+						transition={SPRING_TRANSITION_FAST}
+						style={computedStyle}
+						// biome-ignore lint/suspicious/noExplicitAny: motion v12 HTMLMotionProps conflicts with React's event types
+						{...(restProps as any)}
+					>
+						{name}
+					</m.span>
+				</LazyMotion>
+			);
+		}
+
+		return (
+			<span
+				ref={ref}
+				className={cn(
+					"md-icon inline-flex items-center justify-center shrink-0 select-none",
+					className,
+				)}
+				aria-hidden="true"
+				style={computedStyle}
+				{...restProps}
+			>
+				{name}
+			</span>
+		);
+	},
+);
+
+IconComponent.displayName = "Icon";
+
+/**
+ * Component hiển thị Icon bằng Material Symbols (variable font).
+ *
+ * Hãy đảm bảo đã import CSS chứa font trước khi dùng:
+ * ```ts
+ * import '@bug-on/md3-react/material-symbols.css';
+ * ```
+ *
+ * @remarks
+ * - Đặt tên icon dùng snake_case: `"arrow_forward"`, KHÔNG PHẢI `"ArrowForward"`.
+ * - Thuộc tính `aria-hidden="true"` được tự động thêm vào — bạn cần thêm label đọc bằng giọng nói (accessible labels) ở phần tử cha.
+ *
+ * @example
+ * ```tsx
+ * // Icon cơ bản
+ * <Icon name="home" />
+ *
+ * // Tùy chỉnh trực quan (filled, nét dày)
+ * <Icon name="favorite" variant="rounded" fill={1} weight={300} />
+ *
+ * // Animate khi trạng thái thay đổi
+ * <Icon name="bookmark" fill={saved ? 1 : 0} animateFill />
+ *
+ * // Đổi kích thước icon cụ thể
+ * <Icon name="close" size={18} opticalSize={20} />
+ *
+ * // Kết hợp với các component khác
+ * <Button icon={<Icon name="add" />}>Thêm vào giỏ</Button>
+ * ```
+ *
+ * @see https://fonts.google.com/icons
+ * @see https://m3.material.io/styles/icons/overview
+ */
+export const Icon = React.memo(IconComponent);

package/src/ui/loading-indicator.test.tsx

@@ -0,0 +1,73 @@
+import { act, render } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { LoadingIndicator } from "./loading-indicator";
+
+describe("LoadingIndicator Component", () => {
+	beforeEach(() => {
+		vi.useFakeTimers();
+		vi.spyOn(window, "requestAnimationFrame").mockImplementation(
+			(cb: FrameRequestCallback) => {
+				return setTimeout(() => cb(Date.now()), 16) as unknown as number;
+			},
+		);
+		vi.spyOn(window, "cancelAnimationFrame").mockImplementation(
+			(id: number) => {
+				clearTimeout(id);
+			},
+		);
+	});
+
+	afterEach(() => {
+		vi.restoreAllMocks();
+		vi.useRealTimers();
+	});
+
+	it("renders an <svg> element with correct structure", () => {
+		const { container } = render(
+			<LoadingIndicator size={24} aria-label="Loading" />,
+		);
+		const svg = container.querySelector("svg");
+		expect(svg).toBeInTheDocument();
+		expect(svg).toHaveAttribute("viewBox", "4 4 40 40");
+		expect(svg).toHaveAttribute("width", "24");
+		expect(svg).toHaveAttribute("height", "24");
+	});
+
+	it("delays rendering of <animate> tags by 1 frame to prevent SMIL freezing", async () => {
+		const { container } = render(<LoadingIndicator aria-label="Loading" />);
+		const svg = container.querySelector("svg");
+
+		// Ngay Frame 0 (lúc thẻ SVG vừa vẽ lên DOM), chưa được phép có <animate>
+		// để tránh đụng độ Chromium layout optimization (culling) gây tê liệt animation
+		expect(svg?.querySelector("animate")).toBeNull();
+		expect(svg?.querySelector("animateTransform")).toBeNull();
+
+		// Tua nhanh thời gian vượt qua 16ms để giả lập hoàn tất requestAnimationFrame
+		await act(async () => {
+			vi.advanceTimersByTime(20);
+		});
+
+		// Sang Frame 1, thẻ <animate> phải được inject vào trong DOM để khởi sinh đồng hồ SMIL
+		expect(svg?.querySelector("animate")).not.toBeNull();
+		expect(svg?.querySelector("animateTransform")).not.toBeNull();
+		expect(svg?.querySelector("animate")?.getAttribute("attributeName")).toBe(
+			"d",
+		);
+		expect(
+			svg?.querySelector("animateTransform")?.getAttribute("attributeName"),
+		).toBe("transform");
+	});
+
+	it("supports custom size and color", () => {
+		const { container } = render(
+			<LoadingIndicator size={48} color="red" aria-label="Loading" />,
+		);
+		const wrapper = container.firstChild as HTMLElement;
+		const svg = container.querySelector("svg");
+		expect(svg).toHaveAttribute("width", "48");
+		expect(svg).toHaveAttribute("height", "48");
+
+		const styleStr = wrapper.getAttribute("style") || "";
+		expect(styleStr).toMatch(/color:\s*(red|rgb\(255,\s*0,\s*0\))/);
+	});
+});