@bug-on/md3-react 2.0.3 → 3.0.0

package/src/ui/tabs/tabs.test.tsx

@@ -0,0 +1,290 @@
+"use client";
+
+import { fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { Tab, Tabs, TabsContent, TabsList } from "./index";
+
+describe("Tabs Component System", () => {
+	it("renders correctly and selects the default tab", async () => {
+		render(
+			<Tabs defaultValue="tab2">
+				<TabsList variant="primary">
+					<Tab value="tab1">Tab 1</Tab>
+					<Tab value="tab2">Tab 2</Tab>
+				</TabsList>
+				<TabsContent value="tab1">Content 1</TabsContent>
+				<TabsContent value="tab2">Content 2</TabsContent>
+			</Tabs>,
+		);
+
+		const tabItems = screen.getAllByRole("tab");
+		expect(tabItems).toHaveLength(2);
+
+		// "tab2" should be selected
+		expect(tabItems[1]).toHaveAttribute("aria-selected", "true");
+		expect(tabItems[0]).toHaveAttribute("aria-selected", "false");
+
+		// "Content 2" should be visible
+		await waitFor(() => {
+			expect(screen.getByRole("tabpanel")).toHaveTextContent("Content 2");
+		});
+	});
+
+	it("switches tabs on click", async () => {
+		render(
+			<Tabs defaultValue="tab1">
+				<TabsList variant="primary">
+					<Tab value="tab1">Tab 1</Tab>
+					<Tab value="tab2">Tab 2</Tab>
+				</TabsList>
+				<TabsContent value="tab1">Content 1</TabsContent>
+				<TabsContent value="tab2">Content 2</TabsContent>
+			</Tabs>,
+		);
+
+		const tabItems = screen.getAllByRole("tab");
+
+		// Wait for initial render
+		await waitFor(() => {
+			expect(screen.getByRole("tabpanel")).toHaveTextContent("Content 1");
+		});
+
+		// Click "tab2"
+		fireEvent.click(tabItems[1]);
+
+		expect(tabItems[1]).toHaveAttribute("aria-selected", "true");
+
+		await waitFor(() => {
+			expect(screen.getByText("Content 2")).toBeInTheDocument();
+		});
+	});
+
+	it("handles controlled value correctly", async () => {
+		const handleChange = vi.fn();
+
+		render(
+			<Tabs value="tab1" onValueChange={handleChange}>
+				<TabsList variant="primary">
+					<Tab value="tab1">Tab 1</Tab>
+					<Tab value="tab2">Tab 2</Tab>
+				</TabsList>
+				<TabsContent value="tab1">Content 1</TabsContent>
+				<TabsContent value="tab2">Content 2</TabsContent>
+			</Tabs>,
+		);
+
+		const tabItems = screen.getAllByRole("tab");
+
+		// Click "tab2"
+		fireEvent.click(tabItems[1]);
+
+		// the value shouldn't update internally if strictly controlled without state update wrapper,
+		// but `onValueChange` should be called.
+		expect(handleChange).toHaveBeenCalledWith("tab2");
+	});
+
+	it("supports keyboard navigation (Arrow Right/Left)", async () => {
+		render(
+			<Tabs defaultValue="tab1">
+				<TabsList variant="primary">
+					<Tab value="tab1">Tab 1</Tab>
+					<Tab value="tab2">Tab 2</Tab>
+					<Tab value="tab3">Tab 3</Tab>
+				</TabsList>
+			</Tabs>,
+		);
+
+		const tabItems = screen.getAllByRole("tab");
+		tabItems[0].focus();
+
+		// Move right
+		fireEvent.keyDown(tabItems[0], { key: "ArrowRight" });
+		expect(tabItems[1]).toHaveFocus();
+
+		// Move right again
+		fireEvent.keyDown(tabItems[1], { key: "ArrowRight" });
+		expect(tabItems[2]).toHaveFocus();
+
+		// Move right again (should wrap to first)
+		fireEvent.keyDown(tabItems[2], { key: "ArrowRight" });
+		expect(tabItems[0]).toHaveFocus();
+
+		// Move left (should wrap to last)
+		fireEvent.keyDown(tabItems[0], { key: "ArrowLeft" });
+		expect(tabItems[2]).toHaveFocus();
+	});
+
+	it("supports Home/End keyboard navigation", () => {
+		render(
+			<Tabs defaultValue="tab1">
+				<TabsList variant="primary">
+					<Tab value="tab1">Tab 1</Tab>
+					<Tab value="tab2">Tab 2</Tab>
+					<Tab value="tab3">Tab 3</Tab>
+				</TabsList>
+			</Tabs>,
+		);
+
+		const tabItems = screen.getAllByRole("tab");
+		tabItems[0].focus();
+
+		// End key
+		fireEvent.keyDown(tabItems[0], { key: "End" });
+		expect(tabItems[2]).toHaveFocus();
+
+		// Home key
+		fireEvent.keyDown(tabItems[2], { key: "Home" });
+		expect(tabItems[0]).toHaveFocus();
+	});
+
+	it("auto-activates tabs on keyboard focus when autoActivate is true", async () => {
+		render(
+			<Tabs defaultValue="tab1" autoActivate>
+				<TabsList variant="primary">
+					<Tab value="tab1">Tab 1</Tab>
+					<Tab value="tab2">Tab 2</Tab>
+				</TabsList>
+				<TabsContent value="tab1">Content 1</TabsContent>
+				<TabsContent value="tab2">Content 2</TabsContent>
+			</Tabs>,
+		);
+
+		const tabItems = screen.getAllByRole("tab");
+		tabItems[0].focus();
+
+		// Move to second tab
+		fireEvent.keyDown(tabItems[0], { key: "ArrowRight" });
+		expect(tabItems[1]).toHaveFocus();
+
+		// Because of autoActivate, tab2 should instantly be selected
+		expect(tabItems[1]).toHaveAttribute("aria-selected", "true");
+		await waitFor(() => {
+			expect(screen.getByRole("tabpanel")).toHaveTextContent("Content 2");
+		});
+	});
+
+	it("does not select focused tabs with keyboard when autoActivate is false", async () => {
+		render(
+			<Tabs defaultValue="tab1" autoActivate={false}>
+				<TabsList variant="primary">
+					<Tab value="tab1">Tab 1</Tab>
+					<Tab value="tab2">Tab 2</Tab>
+				</TabsList>
+				<TabsContent value="tab1">Content 1</TabsContent>
+				<TabsContent value="tab2">Content 2</TabsContent>
+			</Tabs>,
+		);
+
+		const tabItems = screen.getAllByRole("tab");
+		tabItems[0].focus();
+
+		// Move to second tab
+		fireEvent.keyDown(tabItems[0], { key: "ArrowRight" });
+		expect(tabItems[1]).toHaveFocus();
+
+		// Should still be tab1
+		expect(tabItems[0]).toHaveAttribute("aria-selected", "true");
+		expect(tabItems[1]).toHaveAttribute("aria-selected", "false");
+
+		// Only updates selection upon Space or Enter
+		fireEvent.keyDown(tabItems[1], { key: "Enter" });
+		expect(tabItems[1]).toHaveAttribute("aria-selected", "true");
+	});
+
+	it("skips disabled tabs during keyboard navigation", () => {
+		render(
+			<Tabs defaultValue="tab1">
+				<TabsList variant="primary">
+					<Tab value="tab1">Tab 1</Tab>
+					<Tab value="tab2" disabled>
+						Tab 2
+					</Tab>
+					<Tab value="tab3">Tab 3</Tab>
+				</TabsList>
+			</Tabs>,
+		);
+
+		const tabItems = screen.getAllByRole("tab");
+		tabItems[0].focus();
+
+		// ArrowRight should skip tab2 and land on tab3
+		fireEvent.keyDown(tabItems[0], { key: "ArrowRight" });
+		expect(tabItems[2]).toHaveFocus();
+	});
+
+	it("respects tab selection with Enter and Space keys", () => {
+		const handleChange = vi.fn();
+		render(
+			<Tabs value="tab1" onValueChange={handleChange}>
+				<TabsList variant="primary">
+					<Tab value="tab1">Tab 1</Tab>
+					<Tab value="tab2">Tab 2</Tab>
+				</TabsList>
+			</Tabs>,
+		);
+
+		const tabItems = screen.getAllByRole("tab");
+		tabItems[0].focus();
+
+		// Move focus
+		fireEvent.keyDown(tabItems[0], { key: "ArrowRight" });
+		expect(tabItems[1]).toHaveFocus();
+
+		// Press Space
+		fireEvent.keyDown(tabItems[1], { key: " " });
+		expect(handleChange).toHaveBeenCalledWith("tab2");
+
+		// Press Enter
+		fireEvent.keyDown(tabItems[1], { key: "Enter" });
+		expect(handleChange).toHaveBeenCalledTimes(2);
+	});
+
+	it("sets correct attributes for accessibility", () => {
+		render(
+			<Tabs defaultValue="1">
+				<TabsList variant="primary" aria-label="My Tabs">
+					<Tab value="1">One</Tab>
+					<Tab value="2">Two</Tab>
+				</TabsList>
+				<TabsContent value="1">Content One</TabsContent>
+			</Tabs>,
+		);
+
+		expect(screen.getByRole("tablist")).toHaveAttribute(
+			"aria-label",
+			"My Tabs",
+		);
+
+		const tab = screen.getAllByRole("tab")[0];
+		expect(tab.getAttribute("id")).toMatch(/tab-1$/);
+		expect(tab.getAttribute("aria-controls")).toMatch(/panel-1$/);
+		expect(tab).toHaveAttribute("tabindex", "0");
+
+		const panel = screen.getByRole("tabpanel");
+		expect(panel.getAttribute("id")).toMatch(/panel-1$/);
+		expect(panel.getAttribute("aria-labelledby")).toMatch(/tab-1$/);
+	});
+
+	it("selects first enabled tab if no defaultValue is provided", async () => {
+		render(
+			<Tabs>
+				<TabsList variant="primary">
+					<Tab value="tab1" disabled>
+						Tab 1
+					</Tab>
+					<Tab value="tab2">Tab 2</Tab>
+					<Tab value="tab3">Tab 3</Tab>
+				</TabsList>
+				<TabsContent value="tab2">Content 2</TabsContent>
+			</Tabs>,
+		);
+
+		const tabItems = screen.getAllByRole("tab");
+
+		await waitFor(() => {
+			expect(tabItems[1]).toHaveAttribute("aria-selected", "true");
+		});
+
+		expect(screen.getByRole("tabpanel")).toHaveTextContent("Content 2");
+	});
+});

package/src/ui/tabs/tabs.tokens.ts

@@ -0,0 +1,121 @@
+/**
+ * @file tabs.tokens.ts
+ * MD3 Expressive Tabs — Design tokens ported from:
+ *   - PrimaryNavigationTabTokens.kt (v0_162)
+ *   - SecondaryNavigationTabTokens.kt (v0_162)
+ *
+ * All dimensional values are in px (dp equivalent for web).
+ * @see docs/m3/tabs/PrimaryNavigationTabTokens.kt
+ * @see docs/m3/tabs/SecondaryNavigationTabTokens.kt
+ */
+
+/**
+ * Dimensional design tokens for the MD3 Tabs component.
+ *
+ * Maps directly from the `.kt` token files to CSS/JS values.
+ * Use as the single source of truth for sizing.
+ */
+export const TabsTokens = {
+	// ── Container ─────────────────────────────────────────────────────────────
+	/** ContainerHeight = 48dp (text-only tab) */
+	containerHeight: 48,
+	/** IconAndLabelTextContainerHeight = 64dp (tab with icon + label stacked) */
+	containerHeightWithIcon: 64,
+
+	// ── Indicator ─────────────────────────────────────────────────────────────
+	/** ActiveIndicatorHeight (Primary) = 3dp */
+	primaryIndicatorHeight: 3,
+	/** ActiveIndicatorHeight (Secondary) = 2dp */
+	secondaryIndicatorHeight: 2,
+	/**
+	 * ActiveIndicatorShape = 3dp top-left and top-right (per MD3 token, not a full pill).
+	 * Google reference: `var(--_active-indicator-shape)` resolves to `3px 3px 0 0` effectively.
+	 */
+	indicatorBorderRadius: "3px 3px 0 0",
+
+	// ── Icon ──────────────────────────────────────────────────────────────────
+	/** IconSize = 24dp */
+	iconSize: 24,
+
+	// ── Scrollable layout ─────────────────────────────────────────────────────
+	/**
+	 * Edge start/end padding for scrollable mode = 52px.
+	 * Per MD3 spec: tabs have padding on both leading and trailing edges.
+	 */
+	scrollableEdgePadding: 52,
+	/** Minimum tab width in scrollable mode = 90px. */
+	scrollableMinTabWidth: 90,
+
+	// ── Divider (Secondary only) ───────────────────────────────────────────────
+	/** DividerHeight = 1dp */
+	dividerHeight: 1,
+
+	// ── Focus ring ────────────────────────────────────────────────────────────
+	/**
+	 * Focus ring border-radius = 8px.
+	 * Google reference: `focus-ring.theme({ shape: 8px })` in _tab.scss.
+	 */
+	focusRingBorderRadius: 8,
+} as const;
+
+// ── MD3 Color token references (CSS custom properties) ────────────────────────
+
+/**
+ * CSS custom property references for Tabs colors.
+ * Maps to `--md-sys-color-*` tokens in the MD3 theme system.
+ *
+ * DO NOT hardcode hex values — use these references for automatic
+ * light/dark theme adaptation.
+ */
+export const TabsColors = {
+	// ── Primary variant ───────────────────────────────────────────────────────
+	/** Primary: ActiveLabelTextColor / ActiveIconColor = Primary */
+	primaryActiveText: "var(--md-sys-color-primary)",
+	/** Primary: InactiveLabelTextColor / InactiveIconColor = OnSurfaceVariant */
+	primaryInactiveText: "var(--md-sys-color-on-surface-variant)",
+	/** Primary: ActiveIndicatorColor = Primary */
+	primaryIndicator: "var(--md-sys-color-primary)",
+
+	// ── Secondary variant ─────────────────────────────────────────────────────
+	/** Secondary: ActiveLabelTextColor / ActiveIconColor = OnSurface */
+	secondaryActiveText: "var(--md-sys-color-on-surface)",
+	/** Secondary: InactiveLabelTextColor / InactiveIconColor = OnSurfaceVariant */
+	secondaryInactiveText: "var(--md-sys-color-on-surface-variant)",
+	/** Secondary: Indicator color = Primary (same as primary variant) */
+	secondaryIndicator: "var(--md-sys-color-primary)",
+	/** Secondary: DividerColor = SurfaceVariant */
+	divider: "var(--md-sys-color-surface-variant)",
+
+	// ── Shared ────────────────────────────────────────────────────────────────
+	/** ContainerColor = Surface */
+	container: "var(--md-sys-color-surface)",
+	/** Focus ring indicator = Secondary */
+	focusIndicator: "var(--md-sys-color-secondary)",
+
+	// ── State overlays ────────────────────────────────────────────────────────
+	/** Hover state layer (primary active) */
+	primaryActiveHover: "var(--md-sys-color-primary)",
+	/** Hover state layer (inactive, both variants) */
+	inactiveHover: "var(--md-sys-color-on-surface)",
+} as const;
+
+// ── Animation constants ────────────────────────────────────────────────────────
+
+/** Spring transition for the sliding indicator (FastSpatial equivalent). */
+export const TABS_INDICATOR_SPRING = {
+	type: "spring",
+	stiffness: 500,
+	damping: 40,
+} as const;
+
+/** Color transition for label/icon color animate (active ↔ inactive). */
+export const TABS_COLOR_TRANSITION = {
+	duration: 0.2,
+	ease: "easeInOut",
+} as const;
+
+/** Content fade transition when switching tabs. */
+export const TABS_CONTENT_TRANSITION = {
+	duration: 0.15,
+	ease: "easeInOut",
+} as const;

package/src/ui/tabs/tabs.tsx

@@ -0,0 +1,229 @@
+/**
+ * @file tabs.tsx
+ * MD3 Expressive Tabs — Root context provider and state manager.
+ * Implements compound component pattern (similar to Radix UI).
+ * Spec: https://m3.material.io/components/tabs/overview
+ */
+
+import { domMax, LazyMotion } from "motion/react";
+import * as React from "react";
+import { cn } from "../../lib/utils";
+import type { TabsContextValue, TabsProps } from "./tabs.types";
+
+// ─── Context ───────────────────────────────────────────────────────────────────
+
+const TabsContext = React.createContext<TabsContextValue | null>(null);
+
+/**
+ * Hook to consume the Tabs context.
+ * Throws if used outside a `<Tabs>` root.
+ * @internal
+ */
+export function useTabsContext(): TabsContextValue {
+	const ctx = React.useContext(TabsContext);
+	if (!ctx) {
+		throw new Error(
+			"[MD3 Tabs] Component must be used within a <Tabs> root. " +
+				"Ensure <TabsList>, <Tab>, and <TabsContent> are descendants of <Tabs>.",
+		);
+	}
+	return ctx;
+}
+
+// ─── Tabs Root ─────────────────────────────────────────────────────────────────
+
+const TabsComponent = React.forwardRef<HTMLDivElement, TabsProps>(
+	(
+		{
+			value: controlledValue,
+			defaultValue = "",
+			onValueChange,
+			autoActivate = false,
+			children,
+			className,
+		},
+		ref,
+	) => {
+		// ── State: selected value (controlled + uncontrolled) ──────────────────
+		const [internalValue, setInternalValue] = React.useState(defaultValue);
+		const isControlled = controlledValue !== undefined;
+		const value = isControlled ? controlledValue : internalValue;
+
+		const handleValueChange = React.useCallback(
+			(newValue: string) => {
+				if (!isControlled) setInternalValue(newValue);
+				onValueChange?.(newValue);
+			},
+			[isControlled, onValueChange],
+		);
+
+		// ── State: keyboard focus (roving tabindex) ────────────────────────────
+		// focusedValue is separate from `value` so focus can move without selecting.
+		const [focusedValue, setFocusedValue] = React.useState(value);
+
+		// Sync focusedValue when controlled value changes externally
+		React.useEffect(() => {
+			setFocusedValue(value);
+		}, [value]);
+
+		// ── Registered tabs registry ───────────────────────────────────────────
+		// Tabs register/unregister themselves to enable ArrowKey navigation.
+		const [tabValues, setTabValues] = React.useState<string[]>([]);
+
+		const registerTab = React.useCallback((tabValue: string) => {
+			setTabValues((prev) => {
+				if (prev.includes(tabValue)) return prev;
+				return [...prev, tabValue];
+			});
+		}, []);
+
+		const unregisterTab = React.useCallback((tabValue: string) => {
+			setTabValues((prev) => prev.filter((v) => v !== tabValue));
+		}, []);
+
+		// ── Auto-select first enabled tab when no defaultValue is provided ─────
+		// Mirrors Google's behavior: if no tab is active, select the first one.
+		const hasAutoSelected = React.useRef(false);
+
+		// ── Disabled tab tracking ──────────────────────────────────────────────
+		const [disabledValues, setDisabledValues] = React.useState<Set<string>>(
+			new Set(),
+		);
+
+		const markTabDisabled = React.useCallback(
+			(tabValue: string, disabled: boolean) => {
+				setDisabledValues((prev) => {
+					const next = new Set(prev);
+					if (disabled) {
+						next.add(tabValue);
+					} else {
+						next.delete(tabValue);
+					}
+					return next;
+				});
+			},
+			[],
+		);
+
+		// Auto-select first enabled tab if no value is set
+		React.useEffect(() => {
+			if (isControlled || hasAutoSelected.current || tabValues.length === 0) {
+				return;
+			}
+			if (value && tabValues.includes(value)) {
+				hasAutoSelected.current = true;
+				return;
+			}
+			const firstEnabled = tabValues.find((v) => !disabledValues.has(v));
+			if (firstEnabled) {
+				hasAutoSelected.current = true;
+				setInternalValue(firstEnabled);
+				setFocusedValue(firstEnabled);
+			}
+		}, [tabValues, disabledValues, isControlled, value]);
+
+		// ── Unique layout group ID for Framer Motion ───────────────────────────
+		const id = React.useId();
+		const layoutGroupId = `tabs-${id}`;
+
+		// ── Context value ──────────────────────────────────────────────────────
+		const contextValue = React.useMemo<TabsContextValue>(
+			() => ({
+				value,
+				onValueChange: handleValueChange,
+				focusedValue,
+				setFocusedValue,
+				tabValues,
+				registerTab,
+				unregisterTab,
+				layoutGroupId,
+				disabledValues,
+				markTabDisabled,
+				autoActivate,
+			}),
+			[
+				value,
+				handleValueChange,
+				focusedValue,
+				tabValues,
+				registerTab,
+				unregisterTab,
+				layoutGroupId,
+				disabledValues,
+				markTabDisabled,
+				autoActivate,
+			],
+		);
+
+		return (
+			<LazyMotion features={domMax} strict>
+				<TabsContext.Provider value={contextValue}>
+					<div ref={ref} className={cn("w-full", className)}>
+						{children}
+					</div>
+				</TabsContext.Provider>
+			</LazyMotion>
+		);
+	},
+);
+
+TabsComponent.displayName = "Tabs";
+
+/**
+ * MD3 Expressive Tabs root component.
+ *
+ * Manages tab selection state and provides context to all
+ * compound sub-components. Supports both controlled and
+ * uncontrolled usage.
+ *
+ * @example
+ * ```tsx
+ * // Uncontrolled
+ * <Tabs defaultValue="flights">
+ *   <TabsList variant="primary">
+ *     <Tab value="flights">Flights</Tab>
+ *     <Tab value="trips">Trips</Tab>
+ *   </TabsList>
+ *   <TabsContent value="flights">Flight content</TabsContent>
+ *   <TabsContent value="trips">Trip content</TabsContent>
+ * </Tabs>
+ *
+ * // Controlled
+ * const [tab, setTab] = useState("flights");
+ * <Tabs value={tab} onValueChange={setTab}>...</Tabs>
+ *
+ * // Auto-activate mode (focus = select)
+ * <Tabs defaultValue="flights" autoActivate>...</Tabs>
+ * ```
+ *
+ * @see https://m3.material.io/components/tabs/overview
+ */
+export const Tabs = React.memo(TabsComponent);
+
+// ─── TabsListContext ───────────────────────────────────────────────────────────
+
+/**
+ * Secondary context carrying variant + scrollable from <TabsList>.
+ * Separate from TabsContext so Tabs root doesn't need these props —
+ * they belong to the list, not the root.
+ * @internal
+ */
+export interface TabsListContextValue {
+	variant: "primary" | "secondary";
+	scrollable: boolean;
+}
+
+export const TabsListContext = React.createContext<TabsListContextValue | null>(
+	null,
+);
+
+/**
+ * Hook to consume TabsList-level context (variant, scrollable).
+ * @internal
+ */
+export function useTabsListContext(): TabsListContextValue {
+	const ctx = React.useContext(TabsListContext);
+	// Fallback to sensible defaults instead of throwing, since
+	// Tab might be rendered without explicit context in tests.
+	return ctx ?? { variant: "primary", scrollable: false };
+}