@bug-on/md3-react 2.0.3 → 3.0.0

package/src/ui/tabs/tab.tsx

@@ -0,0 +1,407 @@
+/**
+ * @file tab.tsx
+ * MD3 Expressive Tab — Individual tab button with Framer Motion indicator.
+ *
+ * Design decisions:
+ * 1. PRIMARY indicator nested inside content wrapper → width = content width (not full button).
+ * 2. SECONDARY indicator outside content wrapper → `inset-x-0` = full button width.
+ * 3. ROVING TABINDEX (WAI-ARIA): only focused tab has tabIndex=0; ArrowKey moves focus, Enter/Space selects.
+ * 4. DISABLED tabs are skipped in ArrowKey navigation.
+ * 5. RTL: ArrowLeft/Right directions are swapped when `direction: rtl` is detected.
+ * 6. INLINE ICON: icon beside label, height stays 48dp (stacked = 64dp).
+ * 7. AUTO-ACTIVATE: when parent `<Tabs autoActivate>`, ArrowKey also selects.
+ *
+ * @see https://m3.material.io/components/tabs/overview
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/tabs/
+ */
+
+import { m, useReducedMotion } from "motion/react";
+import * as React from "react";
+import { cn } from "../../lib/utils";
+import { BadgedBox } from "../badge";
+import { useTabsContext, useTabsListContext } from "./tabs";
+import {
+	TABS_COLOR_TRANSITION,
+	TABS_INDICATOR_SPRING,
+	TabsColors,
+	TabsTokens,
+} from "./tabs.tokens";
+import type { TabProps } from "./tabs.types";
+
+// ─── Constants ──────────────────────────────────────────────────────────────────
+
+/** Minimum indicator width per MD3 spec (24dp). */
+const INDICATOR_MIN_WIDTH = 24;
+
+// ─── Tab ───────────────────────────────────────────────────────────────────────
+
+const TabComponent = React.forwardRef<HTMLButtonElement, TabProps>(
+	(
+		{
+			value,
+			icon,
+			inlineIcon = false,
+			disabled = false,
+			badge,
+			className,
+			children,
+		},
+		ref,
+	) => {
+		const {
+			value: selectedValue,
+			onValueChange,
+			focusedValue,
+			setFocusedValue,
+			tabValues,
+			registerTab,
+			unregisterTab,
+			layoutGroupId,
+			disabledValues,
+			markTabDisabled,
+			autoActivate,
+		} = useTabsContext();
+
+		const { variant, scrollable } = useTabsListContext();
+
+		const prefersReduced = useReducedMotion() ?? false;
+
+		const isActive = selectedValue === value;
+		const isFocused = focusedValue === value;
+		const hasIcon = icon != null;
+		const isStackedIcon = hasIcon && !inlineIcon;
+
+		// ── Refs ───────────────────────────────────────────────────────────────
+		const buttonRef = React.useRef<HTMLButtonElement | null>(null);
+		const isFirstMount = React.useRef(true);
+
+		// Merge forwarded ref with internal ref
+		const mergedRef = React.useCallback(
+			(node: HTMLButtonElement | null) => {
+				buttonRef.current = node;
+				if (typeof ref === "function") ref(node);
+				else if (ref) ref.current = node;
+			},
+			[ref],
+		);
+
+		// ── Register/unregister with parent context on mount/unmount ──────────
+		React.useEffect(() => {
+			registerTab(value);
+			return () => unregisterTab(value);
+		}, [value, registerTab, unregisterTab]);
+
+		// ── Sync disabled state with parent context ────────────────────────────
+		React.useEffect(() => {
+			markTabDisabled(value, disabled);
+			return () => markTabDisabled(value, false);
+		}, [value, disabled, markTabDisabled]);
+
+		// ── Keyboard navigation ────────────────────────────────────────────────
+		const handleKeyDown = React.useCallback(
+			(e: React.KeyboardEvent<HTMLButtonElement>) => {
+				const isRtl = buttonRef.current
+					? getComputedStyle(buttonRef.current).direction === "rtl"
+					: false;
+
+				const enabledValues = tabValues.filter((v) => !disabledValues.has(v));
+				const currentIndex = enabledValues.indexOf(value);
+
+				switch (e.key) {
+					case "ArrowRight":
+					case "ArrowLeft": {
+						e.preventDefault();
+						const goForward = isRtl
+							? e.key === "ArrowLeft"
+							: e.key === "ArrowRight";
+						const nextIndex = goForward
+							? (currentIndex + 1) % enabledValues.length
+							: (currentIndex - 1 + enabledValues.length) %
+								enabledValues.length;
+						const nextValue = enabledValues[nextIndex];
+						if (nextValue) {
+							setFocusedValue(nextValue);
+							if (autoActivate) onValueChange(nextValue);
+						}
+						break;
+					}
+					case "Home": {
+						e.preventDefault();
+						const firstValue = enabledValues[0];
+						if (firstValue) {
+							setFocusedValue(firstValue);
+							if (autoActivate) onValueChange(firstValue);
+						}
+						break;
+					}
+					case "End": {
+						e.preventDefault();
+						const lastValue = enabledValues[enabledValues.length - 1];
+						if (lastValue) {
+							setFocusedValue(lastValue);
+							if (autoActivate) onValueChange(lastValue);
+						}
+						break;
+					}
+					case "Enter":
+					case " ": {
+						e.preventDefault();
+						if (!disabled) onValueChange(value);
+						break;
+					}
+				}
+			},
+			[
+				tabValues,
+				disabledValues,
+				value,
+				disabled,
+				setFocusedValue,
+				onValueChange,
+				autoActivate,
+			],
+		);
+
+		// Focus DOM node when focusedValue changes via keyboard (skip initial mount)
+		React.useEffect(() => {
+			if (isFirstMount.current) {
+				isFirstMount.current = false;
+				return;
+			}
+			if (isFocused && buttonRef.current) {
+				buttonRef.current.focus({ preventScroll: true });
+			}
+		}, [isFocused]);
+
+		// ── Auto-scroll active tab into view (scrollable mode) ─────────────────
+		// Horizontally scrolls the nearest overflow-x container to reveal the
+		// active tab. Uses scrollTo (not scrollIntoView) to avoid vertical page jumps.
+		React.useEffect(() => {
+			if (!isActive || !scrollable || !buttonRef.current) return;
+
+			const btn = buttonRef.current;
+			let container: HTMLElement | null = btn.parentElement;
+			while (container) {
+				const { overflowX } = getComputedStyle(container);
+				if (overflowX === "auto" || overflowX === "scroll") break;
+				container = container.parentElement;
+			}
+			if (!container) return;
+
+			const btnRect = btn.getBoundingClientRect();
+			const containerRect = container.getBoundingClientRect();
+			const overflowLeft = containerRect.left - btnRect.left;
+			const overflowRight = btnRect.right - containerRect.right;
+
+			if (overflowLeft > 0) {
+				container.scrollTo({
+					left: container.scrollLeft - overflowLeft,
+					behavior: "smooth",
+				});
+			} else if (overflowRight > 0) {
+				container.scrollTo({
+					left: container.scrollLeft + overflowRight,
+					behavior: "smooth",
+				});
+			}
+		}, [isActive, scrollable]);
+
+		// ── Derived tokens ─────────────────────────────────────────────────────
+		const containerHeight = isStackedIcon
+			? TabsTokens.containerHeightWithIcon
+			: TabsTokens.containerHeight;
+
+		const activeColor =
+			variant === "primary"
+				? TabsColors.primaryActiveText
+				: TabsColors.secondaryActiveText;
+
+		const inactiveColor =
+			variant === "primary"
+				? TabsColors.primaryInactiveText
+				: TabsColors.secondaryInactiveText;
+
+		const indicatorColor =
+			variant === "primary"
+				? TabsColors.primaryIndicator
+				: TabsColors.secondaryIndicator;
+
+		const indicatorLayoutId = `${layoutGroupId}-indicator`;
+
+		const colorTransition = prefersReduced
+			? { duration: 0 }
+			: TABS_COLOR_TRANSITION;
+		const springTransition = prefersReduced
+			? { duration: 0 }
+			: TABS_INDICATOR_SPRING;
+
+		// ── IDs for ARIA wiring ────────────────────────────────────────────────
+		const tabId = `${layoutGroupId}-tab-${value}`;
+		const panelId = `${layoutGroupId}-panel-${value}`;
+
+		// ── Content wrapper layout ─────────────────────────────────────────────
+		// inlineIcon → flex-row; stacked icon → flex-col gap-0.5; text only → flex-col
+		const contentFlexClass = inlineIcon
+			? "flex-row gap-2"
+			: isStackedIcon
+				? "flex-col gap-0.5"
+				: "flex-col gap-0";
+
+		// Badge placement
+		const shouldWrapIconWithBadge = isStackedIcon && badge != null;
+		const shouldAppendInlineBadge = !isStackedIcon && badge != null;
+
+		return (
+			<button
+				ref={mergedRef}
+				id={tabId}
+				type="button"
+				role="tab"
+				aria-selected={isActive}
+				aria-controls={panelId}
+				aria-disabled={disabled || undefined}
+				disabled={disabled}
+				tabIndex={isFocused ? 0 : -1}
+				onClick={() => {
+					if (!disabled) {
+						onValueChange(value);
+						setFocusedValue(value);
+					}
+				}}
+				onFocus={() => setFocusedValue(value)}
+				onKeyDown={handleKeyDown}
+				className={cn(
+					"relative inline-flex items-center justify-center",
+					"cursor-pointer select-none",
+					scrollable ? "shrink-0" : "flex-1",
+					"focus-visible:outline-2 focus-visible:outline-offset-2",
+					"focus-visible:outline-(--md-sys-color-secondary)",
+					"focus-visible:rounded-lg",
+					"rounded-none",
+					disabled && "pointer-events-none opacity-[0.38]",
+					className,
+				)}
+				style={{
+					height: containerHeight,
+					zIndex: isActive ? 1 : 0,
+					...(scrollable && { minWidth: TabsTokens.scrollableMinTabWidth }),
+				}}
+			>
+				{/*
+				 * Content wrapper — PRIMARY INDICATOR TECHNIQUE:
+				 * Indicator lives inside this wrapper → width matches content (not button).
+				 * inlineIcon: flex-row places icon beside label, height stays 48dp.
+				 */}
+				<m.div
+					className={cn(
+						"relative flex h-full items-center justify-center",
+						contentFlexClass,
+					)}
+					animate={{ color: isActive ? activeColor : inactiveColor }}
+					transition={colorTransition}
+				>
+					{/* Icon (optional) — 24dp per MD3 token */}
+					{hasIcon && (
+						<span
+							aria-hidden={!shouldWrapIconWithBadge ? "true" : undefined}
+							className={cn("flex shrink-0 items-center justify-center")}
+							style={{
+								width: TabsTokens.iconSize,
+								height: TabsTokens.iconSize,
+							}}
+						>
+							{shouldWrapIconWithBadge ? (
+								<BadgedBox badge={badge}>
+									<span aria-hidden="true">{icon}</span>
+								</BadgedBox>
+							) : (
+								<span className="size-full" aria-hidden="true">
+									{icon}
+								</span>
+							)}
+						</span>
+					)}
+
+					{/* Label text — TitleSmall per MD3 typography token */}
+					<span className="text-title-sm font-medium whitespace-nowrap">
+						{children}
+					</span>
+
+					{/* Inline Badge */}
+					{shouldAppendInlineBadge && (
+						<span className="ml-1 flex items-center justify-center">
+							{badge}
+						</span>
+					)}
+
+					{/*
+					 * PRIMARY INDICATOR
+					 * Inside content wrapper → width matches content.
+					 * `layoutId` enables shared layout animation across tabs.
+					 */}
+					{variant === "primary" && isActive && (
+						<m.div
+							layoutId={indicatorLayoutId}
+							aria-hidden="true"
+							className="absolute bottom-0 left-1/2 -translate-x-1/2"
+							style={{
+								height: TabsTokens.primaryIndicatorHeight,
+								minWidth: INDICATOR_MIN_WIDTH,
+								width: "100%",
+								borderRadius: TabsTokens.indicatorBorderRadius,
+								backgroundColor: indicatorColor,
+							}}
+							transition={springTransition}
+						/>
+					)}
+				</m.div>
+
+				{/*
+				 * SECONDARY INDICATOR
+				 * Outside content wrapper → `inset-x-0` = full button width.
+				 */}
+				{variant === "secondary" && isActive && (
+					<m.div
+						layoutId={indicatorLayoutId}
+						aria-hidden="true"
+						className="absolute bottom-0 inset-x-0"
+						style={{
+							height: TabsTokens.secondaryIndicatorHeight,
+							borderRadius: TabsTokens.indicatorBorderRadius,
+							backgroundColor: indicatorColor,
+						}}
+						transition={springTransition}
+					/>
+				)}
+			</button>
+		);
+	},
+);
+
+TabComponent.displayName = "Tab";
+
+/**
+ * MD3 Expressive Tab component — individual tab button.
+ *
+ * Must be a direct child of `<TabsList>`. Implements WAI-ARIA Tabs pattern
+ * with roving tabindex keyboard navigation.
+ *
+ * - **Primary variant**: indicator width = content (text + icon) width.
+ * - **Secondary variant**: indicator width = full button hit area.
+ * - **Disabled**: Skipped entirely in ArrowKey navigation (cannot be focused).
+ * - **inlineIcon**: Icon beside (not above) label; height stays 48dp.
+ * - Framer Motion `layoutId` animates indicator with spring physics.
+ * - ArrowLeft/Right respect RTL direction automatically.
+ *
+ * @example
+ * ```tsx
+ * <Tab value="flights" icon={<Icon name="flight" />}>Flights</Tab>
+ * <Tab value="trips">Trips</Tab>
+ * <Tab value="explore" disabled>Explore</Tab>
+ * <Tab value="hotels" icon={<Icon name="hotel" />} inlineIcon>Hotels</Tab>
+ * ```
+ *
+ * @see https://m3.material.io/components/tabs/overview
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/tabs/
+ */
+export const Tab = React.memo(TabComponent);

package/src/ui/tabs/tabs-content.tsx

@@ -0,0 +1,89 @@
+/**
+ * @file tabs-content.tsx
+ * MD3 Expressive TabsContent — Animated panel component.
+ *
+ * Implements WAI-ARIA tabpanel role with:
+ * - AnimatePresence for fade transition on tab switch
+ * - Proper aria-labelledby pointing to the associated <Tab>
+ * - tabIndex=0 so keyboard users can Tab from the tablist into the panel
+ * - Hidden panels are removed from the DOM (not just visually hidden)
+ *   to prevent screen readers from reading inactive content
+ */
+
+import { AnimatePresence, m, useReducedMotion } from "motion/react";
+import * as React from "react";
+import { cn } from "../../lib/utils";
+import { useTabsContext } from "./tabs";
+import { TABS_CONTENT_TRANSITION } from "./tabs.tokens";
+import type { TabsContentProps } from "./tabs.types";
+
+// ─── TabsContent ───────────────────────────────────────────────────────────────
+
+const TabsContentComponent = React.forwardRef<HTMLDivElement, TabsContentProps>(
+	({ value, className, children }, ref) => {
+		const { value: selectedValue, layoutGroupId } = useTabsContext();
+		const isActive = selectedValue === value;
+		const prefersReduced = useReducedMotion() ?? false;
+
+		// ARIA wiring: panel is labelled by its corresponding <Tab> button
+		const tabId = `${layoutGroupId}-tab-${value}`;
+		const panelId = `${layoutGroupId}-panel-${value}`;
+
+		const contentTransition = prefersReduced
+			? { duration: 0 }
+			: TABS_CONTENT_TRANSITION;
+
+		return (
+			<AnimatePresence mode="popLayout" initial={false}>
+				{isActive && (
+					<m.div
+						ref={ref}
+						key={value}
+						id={panelId}
+						role="tabpanel"
+						aria-labelledby={tabId}
+						tabIndex={0}
+						className={cn(
+							"focus:outline-none w-full",
+							"focus-visible:outline-2 focus-visible:outline-offset-2",
+							"focus-visible:outline-(--md-sys-color-secondary)",
+							className,
+						)}
+						initial={{ opacity: 0 }}
+						animate={{ opacity: 1 }}
+						exit={{ opacity: 0 }}
+						transition={contentTransition}
+					>
+						{children}
+					</m.div>
+				)}
+			</AnimatePresence>
+		);
+	},
+);
+
+TabsContentComponent.displayName = "TabsContent";
+
+/**
+ * MD3 Expressive TabsContent panel component.
+ *
+ * Each panel corresponds to a `<Tab>` with the same `value`.
+ * Only the active panel is rendered in the DOM — inactive panels
+ * are fully unmounted (not `display: none`) to prevent screen readers
+ * from reading hidden content.
+ *
+ * Fade animation is applied on both enter and exit via Framer Motion
+ * `AnimatePresence`. We use `mode="popLayout"` to prevent height layout shifting
+ * during tab transitions. Animation is automatically disabled when the user
+ * has enabled `prefers-reduced-motion`.
+ *
+ * @example
+ * ```tsx
+ * <TabsContent value="flights">
+ *   <p>Available flights...</p>
+ * </TabsContent>
+ * ```
+ *
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/tabs/
+ */
+export const TabsContent = React.memo(TabsContentComponent);

package/src/ui/tabs/tabs-list.tsx

@@ -0,0 +1,146 @@
+/**
+ * @file tabs-list.tsx
+ * MD3 Expressive TabsList — Container component for tab buttons.
+ *
+ * Responsibilities:
+ * - Applies variant (primary/secondary) layout and styling
+ * - Manages horizontal scroll for scrollable mode (52px edge padding per MD3)
+ * - Renders the bottom divider for secondary variant
+ * - Scopes Framer Motion LayoutGroup so indicators animate correctly
+ *   when multiple <Tabs> instances are on the same page
+ * - Restores focus to activeTab when keyboard focus leaves the tablist
+ *   (matches Google's `focusout` handler on <md-tabs>)
+ */
+
+import { LayoutGroup } from "motion/react";
+import * as React from "react";
+import { cn } from "../../lib/utils";
+import { TabsListContext, useTabsContext } from "./tabs";
+import { TabsTokens } from "./tabs.tokens";
+import type { TabsListProps } from "./tabs.types";
+
+// ─── TabsList ──────────────────────────────────────────────────────────────────
+
+const TabsListComponent = React.forwardRef<HTMLDivElement, TabsListProps>(
+	(
+		{
+			variant,
+			scrollable = false,
+			backgroundColor,
+			children,
+			className,
+			"aria-label": ariaLabel,
+		},
+		ref,
+	) => {
+		const { layoutGroupId, value, setFocusedValue } = useTabsContext();
+
+		// Unique layout group ID scoped to this TabsList instance.
+		const listLayoutId = `${layoutGroupId}-list`;
+
+		// ── TabsListContext: provide variant + scrollable to children ──────────
+		const listContextValue = React.useMemo(
+			() => ({ variant, scrollable }),
+			[variant, scrollable],
+		);
+
+		// ── Background color ───────────────────────────────────────────────────
+		const bgColor = backgroundColor ?? "var(--md-sys-color-surface)";
+
+		// ── Focusout handler — restore roving focus to active tab ──────────────
+		// When keyboard focus leaves the tablist entirely (e.g. user presses Tab
+		// to move to the panel), reset `focusedValue` back to the selected tab.
+		// This ensures the next time the user Tabs back into the tablist, focus
+		// lands on the active tab — not the last arrow-key-focused tab.
+		// Mirrors Google's `handleFocusout` in tabs.ts:
+		//   "restore focus to selected item when blurring the tab bar"
+		const handleBlur = React.useCallback(
+			(e: React.FocusEvent<HTMLDivElement>) => {
+				// `relatedTarget` is the element receiving focus.
+				// If it's still inside the tablist, this is an internal focus move
+				// (e.g. clicking another tab) — don't restore.
+				const listEl = e.currentTarget;
+				if (listEl.contains(e.relatedTarget as Node | null)) return;
+
+				// Focus left the tablist — restore focusedValue to the active tab.
+				setFocusedValue(value);
+			},
+			[value, setFocusedValue],
+		);
+
+		return (
+			<TabsListContext.Provider value={listContextValue}>
+				{/* LayoutGroup scopes shared layout animation so indicators from different Tabs instances don't bleed into each other. */}
+				<LayoutGroup id={listLayoutId}>
+					{/* Outer wrapper: positioning context for the secondary divider */}
+					<div
+						ref={ref}
+						className={cn("relative w-full", className)}
+						style={{ backgroundColor: bgColor }}
+					>
+						<div
+							role="tablist"
+							aria-label={ariaLabel}
+							onBlur={handleBlur}
+							className={cn(
+								"flex flex-row items-stretch",
+								scrollable &&
+									"overflow-x-auto [scrollbar-width:none] [-ms-overflow-style:none] [&::-webkit-scrollbar]:hidden",
+							)}
+							style={
+								scrollable
+									? {
+											paddingLeft: TabsTokens.scrollableEdgePadding,
+											paddingRight: TabsTokens.scrollableEdgePadding,
+										}
+									: undefined
+							}
+						>
+							{children}
+						</div>
+
+						{/* Secondary variant: bottom divider — absolute so it doesn't affect tab layout flow */}
+						{variant === "secondary" && (
+							<div
+								aria-hidden="true"
+								className="absolute bottom-0 left-0 right-0"
+								style={{
+									height: TabsTokens.dividerHeight,
+									backgroundColor: "var(--md-sys-color-surface-variant)",
+								}}
+							/>
+						)}
+					</div>
+				</LayoutGroup>
+			</TabsListContext.Provider>
+		);
+	},
+);
+
+TabsListComponent.displayName = "TabsList";
+
+/**
+ * MD3 Expressive TabsList container component.
+ *
+ * Renders a horizontal row of `<Tab>` components with MD3-compliant
+ * layout (fixed or scrollable) and variant styling (primary or secondary).
+ *
+ * - **Primary**: Tabs divide available width equally, indicator width = content width.
+ * - **Secondary**: Tabs divide equally + full-width indicator + bottom divider line.
+ * - **Scrollable**: Tabs have min-width (90px), scroll horizontally with 52px edge padding.
+ * - **Focusout**: When focus leaves the tablist, roving focus resets to the active tab.
+ *
+ * @example
+ * ```tsx
+ * <TabsList variant="primary" scrollable={false}>
+ *   <Tab value="tab1">Tab 1</Tab>
+ *   <Tab value="tab2">Tab 2</Tab>
+ * </TabsList>
+ *
+ * <TabsList variant="secondary" scrollable={true} aria-label="Content sections">
+ *   <Tab value="a">Alpha</Tab>
+ *   <Tab value="b">Beta</Tab>
+ * </TabsList>
+ * ```
+ */
+export const TabsList = React.memo(TabsListComponent);