@bug-on/md3-react 2.0.3 → 3.0.1

package/src/index.ts

@@ -0,0 +1,349 @@
+export { useMediaQuery } from "./hooks/useMediaQuery";
+// Hooks
+/** @deprecated Use `useRippleState` (Framer Motion) from the main package instead. DOM-only ripple. */
+export { useRipple as useDOMRipple } from "./hooks/useRipple";
+export { MaterialSymbolsPreconnect } from "./lib/material-symbols-preconnect";
+// Theme — MD3 Dynamic Color
+export type { MD3ColorScheme, ThemeMode } from "./lib/theme-utils";
+export { applyTheme, generateM3Theme, resolveMode } from "./lib/theme-utils";
+// Utils
+export { cn } from "./lib/utils";
+// Types
+export type {
+	MD3ColorStyle,
+	MD3Shape,
+	MD3Size,
+	PolymorphicProps,
+	PolymorphicRef,
+} from "./types/md3";
+// App Bar — MD3 Expressive App Bar system
+export type {
+	AppBarColors,
+	AppBarColumnProps,
+	AppBarItem,
+	AppBarItemType,
+	AppBarMenuState,
+	AppBarOverflowIndicatorProps,
+	AppBarRowProps,
+	AppBarScrollBehavior,
+	BaseAppBarProps,
+	BottomAppBarProps,
+	DockedToolbarProps,
+	FlexibleAppBarProps,
+	SearchAppBarProps,
+	SearchBarVariant,
+	SearchViewProps,
+	SmallAppBarProps,
+	TitleAlignment,
+	UseAppBarScrollReturn,
+} from "./ui/app-bar";
+export {
+	APP_BAR_BOTTOM_SPRING,
+	APP_BAR_COLOR_TRANSITION,
+	APP_BAR_COLORS,
+	APP_BAR_ENTER_ALWAYS_SPRING,
+	APP_BAR_TITLE_FADE,
+	AppBarColumn,
+	AppBarOverflowIndicator,
+	AppBarRow,
+	AppBarTokens,
+	appBarTypography,
+	BottomAppBar,
+	DockedToolbar,
+	LargeFlexibleAppBar,
+	MediumFlexibleAppBar,
+	SEARCH_VIEW_SPRING,
+	SearchAppBar,
+	SearchView,
+	SearchViewContainer,
+	SmallAppBar,
+	useAppBarScroll,
+} from "./ui/app-bar";
+export type { BadgedBoxProps, BadgeProps } from "./ui/badge";
+// Badge — MD3 Expressive status indicator
+export { Badge, BadgedBox } from "./ui/badge";
+export type { BaseButtonProps, ButtonProps } from "./ui/button";
+export { Button } from "./ui/button";
+export type { ButtonGroupProps } from "./ui/button-group";
+export { ButtonGroup } from "./ui/button-group";
+export type { CardProps } from "./ui/card";
+export { Card } from "./ui/card";
+// Checkbox — MD3 Expressive tri-state checkbox
+export type {
+	CheckboxProps,
+	CheckboxState,
+	TriStateCheckboxProps,
+} from "./ui/checkbox";
+export { Checkbox, TriStateCheckbox } from "./ui/checkbox";
+export type { ChipProps } from "./ui/chip";
+export { Chip } from "./ui/chip";
+export type { CodeBlockProps } from "./ui/code-block";
+export { CodeBlock } from "./ui/code-block";
+export type {
+	DialogContentProps,
+	DialogFullScreenContentProps,
+	DialogProps,
+} from "./ui/dialog";
+// Dialog
+export {
+	Dialog,
+	DialogBody,
+	DialogClose,
+	DialogContent,
+	DialogDescription,
+	DialogFooter,
+	DialogFullScreenContent,
+	DialogHeader,
+	DialogIcon,
+	DialogOverlay,
+	DialogPortal,
+	DialogTitle,
+	DialogTrigger,
+} from "./ui/dialog";
+// Divider — MD3 Expressive divider line
+export type { DividerProps } from "./ui/divider";
+export { buildWavePath, Divider } from "./ui/divider";
+export type { DrawerContentProps, DrawerProps } from "./ui/drawer";
+// Drawer (Bottom Sheet)
+export {
+	Drawer,
+	DrawerClose,
+	DrawerContent,
+	DrawerDescription,
+	DrawerFooter,
+	DrawerHeader,
+	DrawerOverlay,
+	DrawerPortal,
+	DrawerTitle,
+	DrawerTrigger,
+} from "./ui/drawer";
+export type { FABPositionProps, FABProps } from "./ui/fab";
+// Floating Action Button
+export { FAB, FABPosition } from "./ui/fab";
+export type {
+	FABMenuItemData,
+	FABMenuItemProps,
+	FABMenuProps,
+	ToggleFABProps,
+} from "./ui/fab-menu";
+// FAB Menu
+export { FABMenu, FABMenuItem, ToggleFAB } from "./ui/fab-menu";
+// Icon — Material Symbols variable font
+export type { IconProps } from "./ui/icon";
+export { Icon } from "./ui/icon";
+export type { BaseIconButtonProps, IconButtonProps } from "./ui/icon-button";
+export { IconButton } from "./ui/icon-button";
+export type { LoadingIndicatorProps } from "./ui/loading-indicator";
+export { LoadingIndicator } from "./ui/loading-indicator";
+// MD3 Expressive Menu — Standard + Vibrant + shape morphing
+export type {
+	// ContextMenu
+	ContextMenuContentProps,
+	ContextMenuProps,
+	ContextMenuTriggerProps,
+	MenuColorVariant,
+	MenuContentProps,
+	MenuDividerProps,
+	MenuGroupPosition,
+	MenuGroupProps,
+	MenuItemPosition,
+	MenuItemProps,
+	MenuPrimitive,
+	MenuProps,
+	MenuTriggerProps,
+	MenuVariant,
+	SubMenuProps,
+	// Vertical Menu
+	VerticalMenuContentProps,
+	VerticalMenuDividerProps,
+	VerticalMenuGroupProps,
+	VerticalMenuProps,
+	VerticalMenuSeparatorStyle,
+} from "./ui/menu";
+export {
+	CHECK_ICON_VARIANTS,
+	ContextMenu,
+	ContextMenuContent,
+	ContextMenuTrigger,
+	DIVIDER_COLOR,
+	DIVIDER_PADDING,
+	FAST_EFFECTS_TRANSITION,
+	FAST_SPATIAL_SPRING,
+	GROUP_SHAPES,
+	ITEM_SHAPE_CLASSES,
+	MENU_CHECK_ICON_SIZE,
+	MENU_CONTAINER_VARIANTS,
+	MENU_GROUP_GAP,
+	MENU_ICON_SIZE,
+	MENU_ITEM_MIN_HEIGHT,
+	MENU_MAX_WIDTH,
+	MENU_MIN_WIDTH,
+	Menu,
+	MenuContent,
+	MenuDivider,
+	MenuGroup,
+	MenuItem,
+	MenuProvider,
+	MenuTrigger,
+	STANDARD_COLORS,
+	SUBMENU_CONTAINER_VARIANTS,
+	SubMenu,
+	useMenuContext,
+	// Vertical Menu (static, always-visible)
+	VerticalMenu,
+	VerticalMenuContent,
+	VerticalMenuDivider,
+	VerticalMenuGroup,
+	VIBRANT_COLORS,
+} from "./ui/menu";
+// Navigation Rail
+export type {
+	NavigationRailItemProps,
+	NavigationRailLabelVisibility,
+	NavigationRailProps,
+	NavigationRailVariant,
+} from "./ui/navigation-rail";
+export { NavigationRail, NavigationRailItem } from "./ui/navigation-rail";
+export type {
+	CircularProgressProps,
+	LinearProgressProps,
+	ProgressIndicatorProps,
+} from "./ui/progress-indicator";
+export { ProgressIndicator } from "./ui/progress-indicator";
+// RadioButton — MD3 Expressive radio button
+export type {
+	RadioButtonColors,
+	RadioButtonProps,
+	RadioGroupProps,
+} from "./ui/radio-button";
+export { RadioButton, RadioGroup } from "./ui/radio-button";
+export type {
+	RippleOrigin,
+	RippleProps,
+	UseRippleStateOptions,
+} from "./ui/ripple";
+export { Ripple, useRipple, useRippleState } from "./ui/ripple";
+// ScrollArea
+export type {
+	ScrollAreaOrientation,
+	ScrollAreaProps,
+	ScrollAreaType,
+} from "./ui/scroll-area";
+export {
+	ScrollArea,
+	ScrollAreaScrollbar,
+} from "./ui/scroll-area";
+// Search — MD3 Expressive Search component
+export type {
+	SearchProps,
+	SearchStyleType,
+	SearchVariant,
+} from "./ui/search";
+export {
+	SEARCH_BAR_EXPAND_SPRING,
+	SEARCH_COLORS,
+	SEARCH_DOCKED_REVEAL_SPRING,
+	SEARCH_FULLSCREEN_SPRING,
+	SEARCH_TYPOGRAPHY,
+	Search,
+	SearchBar,
+	SearchTokens,
+	SearchViewDocked,
+	SearchViewFullScreen,
+	useSearchKeyboard,
+} from "./ui/search";
+// Slider — MD3 Expressive
+export type {
+	RangeSliderProps,
+	SliderOrientation,
+	SliderProps,
+	SliderTrackSize,
+	SliderVariant,
+} from "./ui/slider";
+export { RangeSlider, Slider, SliderColors, SliderTokens } from "./ui/slider";
+// Snackbar — MD3 Expressive imperative toast system
+export type {
+	SnackbarData,
+	SnackbarDuration,
+	SnackbarHostProps,
+	SnackbarProps,
+	SnackbarResult,
+	SnackbarVisuals,
+	UseSnackbarStateReturn,
+} from "./ui/snackbar";
+export {
+	Snackbar,
+	SnackbarHost,
+	SnackbarProvider,
+	useSnackbar,
+	useSnackbarState,
+} from "./ui/snackbar";
+// Switch — MD3 Expressive toggle
+export type { SwitchProps } from "./ui/switch";
+export { Switch, SwitchColors, SwitchTokens } from "./ui/switch";
+export { Text, type TextProps } from "./ui/Text";
+// Tabs — MD3 Expressive navigation tabs
+export type {
+	TabProps,
+	TabsContentProps,
+	TabsListProps,
+	TabsProps,
+	TabsVariant,
+} from "./ui/tabs";
+export {
+	Tab,
+	Tabs,
+	TabsColors,
+	TabsContent,
+	TabsList,
+	TabsTokens,
+} from "./ui/tabs";
+// TextField — MD3 Expressive
+export type {
+	TextFieldHandle,
+	TextFieldInputType,
+	TextFieldProps,
+	TextFieldTrailingIconMode,
+	TextFieldVariant,
+} from "./ui/text-field";
+export { TextField } from "./ui/text-field";
+export type { MD3ThemeProviderProps } from "./ui/theme-provider";
+export { MD3ThemeProvider, useTheme, useThemeMode } from "./ui/theme-provider";
+export type { TableOfContentsProps, ToCItem } from "./ui/toc";
+export { TableOfContents } from "./ui/toc";
+// Tooltip — MD3 Expressive
+export type {
+	CaretConfig,
+	PlainTooltipProps,
+	RichTooltipProps,
+	TooltipBoxProps,
+	TooltipPlacement,
+	TooltipState,
+	TooltipStateConfig,
+	TooltipTrigger,
+} from "./ui/tooltip";
+export {
+	PlainTooltip,
+	RichTooltip,
+	TooltipBox,
+	TooltipCaretShape,
+	TooltipTokens,
+	useTooltipPosition,
+	useTooltipState,
+} from "./ui/tooltip";
+export type {
+	TextStyle,
+	TypeScaleTokensType,
+	TypographyProviderProps,
+} from "./ui/typography";
+// Typography - MD3 Expressive
+export {
+	MD3_EXPRESSIVE_FONT_VARIATION,
+	TypeScaleTokens,
+	Typography,
+	TypographyContext,
+	TypographyKeyTokens,
+	TypographyProvider,
+	TypographyTokens,
+	useTypography,
+} from "./ui/typography";

package/src/lib/material-symbols-preconnect.tsx

@@ -0,0 +1,82 @@
+/**
+ * MaterialSymbolsPreconnect
+ *
+ * Inject preconnect resource hints cho Google Fonts CDN và <head>.
+ * Đặt component này CÀNG SỚM CÀNG TỐT trong app tree, lý tưởng là
+ * ngay trong <head> hoặc root layout.
+ *
+ * WHY THIS MATTERS:
+ * Nếu @import url() nằm trong CSS file, browser phải:
+ * 1. Parse HTML -> download JS bundle -> execute CSS -> gặp @import -> mới bắt đầu connect Google Fonts
+ * Preconnect hints cho phép browser bắt đầu TCP handshake + TLS ngay từ bước 1,
+ * tiết kiệm 100-500ms connection time tùy network.
+ *
+ * USAGE:
+ * ```tsx
+ * // app/layout.tsx (Next.js) hoặc index.html equivalent
+ * import { MaterialSymbolsPreconnect } from '@bug-on/md3-react';
+ *
+ * export default function RootLayout({ children }) {
+ *   return (
+ *     <html>
+ *       <head>
+ *         <MaterialSymbolsPreconnect />
+ *       </head>
+ *       <body>{children}</body>
+ *     </html>
+ *   );
+ * }
+ * ```
+ *
+ * NOTE: Chỉ dùng component này với CDN mode.
+ * Với self-hosted fonts thì không cần preconnect đến external origin.
+ */
+export interface MaterialSymbolsPreconnectProps {
+	/**
+	 * Mảng các biến thể font Material Symbols cần tải.
+	 * Chỉ nên chọn các biến thể mà ứng dụng thực sự sử dụng để tiết kiệm băng thông.
+	 * @default ["outlined"]
+	 */
+	variants?: Array<"outlined" | "rounded" | "sharp">;
+}
+
+export function MaterialSymbolsPreconnect({
+	variants = ["outlined"],
+}: MaterialSymbolsPreconnectProps) {
+	return (
+		<>
+			{/* Preconnect cho CSS stylesheet */}
+			<link rel="preconnect" href="https://fonts.googleapis.com" />
+			{/* Preconnect cho font files — crossorigin bắt buộc vì font download là CORS request */}
+			<link
+				rel="preconnect"
+				href="https://fonts.gstatic.com"
+				crossOrigin="anonymous"
+			/>
+			{/* Load các biến thể được chọn.
+			    Sử dụng display=swap để tối ưu hóa hiệu năng (Lighthouse/Next.js recommendation).
+			    Lưu ý: Có thể gây ra hiện tượng chớp chữ (ligature flicker) trong tích tắc. */}
+			{variants.includes("outlined") && (
+				<link
+					href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap"
+					rel="stylesheet"
+					precedence="default"
+				/>
+			)}
+			{variants.includes("rounded") && (
+				<link
+					href="https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap"
+					rel="stylesheet"
+					precedence="default"
+				/>
+			)}
+			{variants.includes("sharp") && (
+				<link
+					href="https://fonts.googleapis.com/css2?family=Material+Symbols+Sharp:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=swap"
+					rel="stylesheet"
+					precedence="default"
+				/>
+			)}
+		</>
+	);
+}

package/src/lib/theme-utils.ts

@@ -0,0 +1,195 @@
+import {
+	argbFromHex,
+	hexFromArgb,
+	themeFromSourceColor,
+} from "@material/material-color-utilities";
+
+export type ThemeMode = "light" | "dark" | "system";
+
+/**
+ * Resolves the effective color scheme from a ThemeMode.
+ * When mode is "system", reads the OS preference via matchMedia.
+ * Returns "light" as the safe default in SSR environments.
+ */
+export function resolveMode(mode: ThemeMode): "light" | "dark" {
+	if (mode !== "system") return mode;
+	if (typeof window === "undefined") return "light";
+	return window.matchMedia("(prefers-color-scheme: dark)").matches
+		? "dark"
+		: "light";
+}
+
+export interface MD3ColorScheme {
+	primary: string;
+	onPrimary: string;
+	primaryContainer: string;
+	onPrimaryContainer: string;
+	inversePrimary: string;
+	primaryFixed: string;
+	primaryFixedDim: string;
+	onPrimaryFixed: string;
+	onPrimaryFixedVariant: string;
+
+	secondary: string;
+	onSecondary: string;
+	secondaryContainer: string;
+	onSecondaryContainer: string;
+	secondaryFixed: string;
+	secondaryFixedDim: string;
+	onSecondaryFixed: string;
+	onSecondaryFixedVariant: string;
+
+	tertiary: string;
+	onTertiary: string;
+	tertiaryContainer: string;
+	onTertiaryContainer: string;
+	tertiaryFixed: string;
+	tertiaryFixedDim: string;
+	onTertiaryFixed: string;
+	onTertiaryFixedVariant: string;
+
+	error: string;
+	onError: string;
+	errorContainer: string;
+	onErrorContainer: string;
+
+	surface: string;
+	onSurface: string;
+	surfaceVariant: string;
+	onSurfaceVariant: string;
+	surfaceTint: string;
+	surfaceContainerLowest: string;
+	surfaceContainerLow: string;
+	surfaceContainer: string;
+	surfaceContainerHigh: string;
+	surfaceContainerHighest: string;
+
+	inverseSurface: string;
+	inverseOnSurface: string;
+
+	background: string;
+	onBackground: string;
+
+	outline: string;
+	outlineVariant: string;
+
+	shadow: string;
+	scrim: string;
+}
+
+/**
+ * Generate a complete MD3 color scheme from a source color hex string.
+ * Uses the HCT color space algorithm — same as Material You on Android.
+ */
+export function generateM3Theme(
+	sourceColorHex: string,
+	mode: "light" | "dark" = "light",
+): MD3ColorScheme {
+	const sourceColor = argbFromHex(sourceColorHex);
+	const theme = themeFromSourceColor(sourceColor);
+
+	const scheme = mode === "light" ? theme.schemes.light : theme.schemes.dark;
+	const palettes = theme.palettes;
+
+	const tone = (palette: (typeof palettes)[keyof typeof palettes], t: number) =>
+		hexFromArgb(palette.tone(t));
+
+	return {
+		primary: hexFromArgb(scheme.primary),
+		onPrimary: hexFromArgb(scheme.onPrimary),
+		primaryContainer: hexFromArgb(scheme.primaryContainer),
+		onPrimaryContainer: hexFromArgb(scheme.onPrimaryContainer),
+		inversePrimary: hexFromArgb(scheme.inversePrimary),
+		primaryFixed: tone(palettes.primary, 90),
+		primaryFixedDim: tone(palettes.primary, 80),
+		onPrimaryFixed: tone(palettes.primary, 10),
+		onPrimaryFixedVariant: tone(palettes.primary, 30),
+
+		secondary: hexFromArgb(scheme.secondary),
+		onSecondary: hexFromArgb(scheme.onSecondary),
+		secondaryContainer: hexFromArgb(scheme.secondaryContainer),
+		onSecondaryContainer: hexFromArgb(scheme.onSecondaryContainer),
+		secondaryFixed: tone(palettes.secondary, 90),
+		secondaryFixedDim: tone(palettes.secondary, 80),
+		onSecondaryFixed: tone(palettes.secondary, 10),
+		onSecondaryFixedVariant: tone(palettes.secondary, 30),
+
+		tertiary: hexFromArgb(scheme.tertiary),
+		onTertiary: hexFromArgb(scheme.onTertiary),
+		tertiaryContainer: hexFromArgb(scheme.tertiaryContainer),
+		onTertiaryContainer: hexFromArgb(scheme.onTertiaryContainer),
+		tertiaryFixed: tone(palettes.tertiary, 90),
+		tertiaryFixedDim: tone(palettes.tertiary, 80),
+		onTertiaryFixed: tone(palettes.tertiary, 10),
+		onTertiaryFixedVariant: tone(palettes.tertiary, 30),
+
+		error: hexFromArgb(scheme.error),
+		onError: hexFromArgb(scheme.onError),
+		errorContainer: hexFromArgb(scheme.errorContainer),
+		onErrorContainer: hexFromArgb(scheme.onErrorContainer),
+
+		surface: hexFromArgb(scheme.surface),
+		onSurface: hexFromArgb(scheme.onSurface),
+		surfaceVariant: hexFromArgb(scheme.surfaceVariant),
+		onSurfaceVariant: hexFromArgb(scheme.onSurfaceVariant),
+		surfaceTint: hexFromArgb(scheme.primary),
+		// Surface container roles from neutral palette tones
+		surfaceContainerLowest:
+			mode === "light"
+				? tone(palettes.neutral, 100)
+				: tone(palettes.neutral, 4),
+		surfaceContainerLow:
+			mode === "light"
+				? tone(palettes.neutral, 96)
+				: tone(palettes.neutral, 10),
+		surfaceContainer:
+			mode === "light"
+				? tone(palettes.neutral, 94)
+				: tone(palettes.neutral, 12),
+		surfaceContainerHigh:
+			mode === "light"
+				? tone(palettes.neutral, 92)
+				: tone(palettes.neutral, 17),
+		surfaceContainerHighest:
+			mode === "light"
+				? tone(palettes.neutral, 90)
+				: tone(palettes.neutral, 22),
+
+		inverseSurface: hexFromArgb(scheme.inverseSurface),
+		inverseOnSurface: hexFromArgb(scheme.inverseOnSurface),
+
+		background: hexFromArgb(scheme.background),
+		onBackground: hexFromArgb(scheme.onBackground),
+
+		outline: hexFromArgb(scheme.outline),
+		outlineVariant: hexFromArgb(scheme.outlineVariant),
+
+		shadow: hexFromArgb(scheme.shadow),
+		scrim: hexFromArgb(scheme.scrim),
+	};
+}
+
+/**
+ * Apply an MD3 dynamic color scheme to the document root as CSS custom properties.
+ * Sets both `--md-sys-color-*` tokens (used by components) and
+ * `--color-m3-*` tokens (used by Tailwind arbitrary values in apps).
+ *
+ * Also sets `data-theme` attribute for dark mode CSS selectors.
+ */
+export function applyTheme(
+	sourceColorHex: string,
+	mode: ThemeMode = "light",
+	root: HTMLElement = document.documentElement,
+): void {
+	const resolved = resolveMode(mode);
+	const colors = generateM3Theme(sourceColorHex, resolved);
+
+	for (const [key, value] of Object.entries(colors)) {
+		const kebabKey = key.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+		root.style.setProperty(`--md-sys-color-${kebabKey}`, value);
+		root.style.setProperty(`--color-m3-${kebabKey}`, value);
+	}
+
+	// data-theme is always "light" or "dark" — never "system"
+	root.setAttribute("data-theme", resolved);
+}

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs));
+}

package/src/plugin.ts

@@ -0,0 +1,12 @@
+// Re-export the MD3 Tailwind plugin from @bug-on/md3-tailwind.
+// This allows users to reference the plugin directly from @bug-on/md3-react
+// without installing @bug-on/md3-tailwind separately.
+//
+// Usage in CSS (Tailwind v4):
+//   @import "@bug-on/md3-react/index.css";
+//   @plugin "@bug-on/md3-react/plugin";
+//
+// Usage in tailwind.config.ts (Tailwind v3):
+//   import md3Plugin from "@bug-on/md3-react/plugin";
+//   export default { plugins: [md3Plugin] };
+export { default } from "@bug-on/md3-tailwind";

package/src/test/button.test.tsx

@@ -0,0 +1,59 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+import { Button } from "../ui/button";
+
+describe("Button Loading State", () => {
+	it("does not render LoadingIndicator by default", () => {
+		render(<Button>Submit</Button>);
+		expect(screen.queryByRole("progressbar")).not.toBeInTheDocument();
+	});
+
+	it("renders LoadingIndicator when loading=true", () => {
+		render(<Button loading>Submit</Button>);
+		const progressbar = screen.getByRole("progressbar");
+		expect(progressbar).toBeInTheDocument();
+		expect(progressbar).toHaveAttribute("aria-label", "Loading");
+	});
+
+	it("applies aria-busy and aria-disabled when loading", () => {
+		render(<Button loading>Submit</Button>);
+		const button = screen.getByRole("button", { name: "Submit" });
+		expect(button).toHaveAttribute("aria-busy", "true");
+		expect(button).toHaveAttribute("aria-disabled", "true");
+	});
+
+	it("prevents interactions when loading", async () => {
+		const handleClick = vi.fn();
+		render(
+			<Button loading onClick={handleClick}>
+				Submit
+			</Button>,
+		);
+
+		const button = screen.getByRole("button", { name: "Submit" });
+		await userEvent.click(button);
+
+		expect(handleClick).not.toHaveBeenCalled();
+	});
+
+	it("replaces leading icon with loading indicator", () => {
+		const FakeIcon = <svg data-testid="fake-icon" />;
+
+		const { rerender } = render(
+			<Button icon={FakeIcon} iconPosition="leading">
+				Submit
+			</Button>,
+		);
+		expect(screen.getByTestId("fake-icon")).toBeInTheDocument();
+		expect(screen.queryByRole("progressbar")).not.toBeInTheDocument();
+
+		rerender(
+			<Button loading icon={FakeIcon} iconPosition="leading">
+				Submit
+			</Button>,
+		);
+		expect(screen.queryByTestId("fake-icon")).not.toBeInTheDocument();
+		expect(screen.getByRole("progressbar")).toBeInTheDocument();
+	});
+});