@bug-on/md3-react 2.0.3 → 3.0.1

package/src/ui/tabs/tabs.types.ts

@@ -0,0 +1,185 @@
+/**
+ * @file tabs.types.ts
+ * MD3 Expressive Tabs — TypeScript prop definitions.
+ * Spec: https://m3.material.io/components/tabs/overview
+ */
+
+import type * as React from "react";
+
+// ─── Variant & Layout ─────────────────────────────────────────────────────────
+
+/** Visual variant: primary (content-width indicator) or secondary (full-width indicator + divider). */
+export type TabsVariant = "primary" | "secondary";
+
+// ─── Internal Context ──────────────────────────────────────────────────────────
+
+/**
+ * Internal context shared across all compound components.
+ * @internal
+ */
+export interface TabsContextValue {
+	/** Currently selected tab value. */
+	value: string;
+	/** Callback to change the selected tab. */
+	onValueChange: (value: string) => void;
+	/** Currently keyboard-focused tab value (for roving tabindex). */
+	focusedValue: string;
+	/** Sets the focused tab value (keyboard nav only — does NOT select). */
+	setFocusedValue: (value: string) => void;
+	/** Ordered list of all registered tab values (for ArrowKey nav). */
+	tabValues: string[];
+	/** Register a tab value when a <Tab> mounts. */
+	registerTab: (value: string) => void;
+	/** Unregister a tab value when a <Tab> unmounts. */
+	unregisterTab: (value: string) => void;
+	/** Unique layout group ID scoped to this Tabs instance. */
+	layoutGroupId: string;
+	/**
+	 * Set of currently disabled tab values.
+	 * Used by keyboard navigation to skip disabled tabs.
+	 */
+	disabledValues: Set<string>;
+	/**
+	 * Mark or unmark a tab value as disabled.
+	 * Called by <Tab> on mount and when `disabled` prop changes.
+	 */
+	markTabDisabled: (value: string, disabled: boolean) => void;
+	/**
+	 * When true, focus moving via ArrowKey also selects the tab immediately.
+	 * Mirrors Google's `autoActivate` attribute on <md-tabs>.
+	 * @default false
+	 */
+	autoActivate: boolean;
+}
+
+// ─── Component Props ───────────────────────────────────────────────────────────
+
+/**
+ * Props for the `<Tabs>` root component.
+ *
+ * Supports both controlled (`value` + `onValueChange`) and
+ * uncontrolled (`defaultValue`) usage patterns.
+ *
+ * @example
+ * ```tsx
+ * // Controlled
+ * <Tabs value={tab} onValueChange={setTab}>...</Tabs>
+ *
+ * // Uncontrolled
+ * <Tabs defaultValue="flights">...</Tabs>
+ *
+ * // Auto-activate (focus = select)
+ * <Tabs defaultValue="flights" autoActivate>...</Tabs>
+ * ```
+ */
+export interface TabsProps {
+	/** Controlled selected value. Use with `onValueChange`. */
+	value?: string;
+	/** Initial value for uncontrolled usage. */
+	defaultValue?: string;
+	/** Called when the selected tab changes. */
+	onValueChange?: (value: string) => void;
+	/**
+	 * When true, ArrowKey navigation also selects the focused tab immediately.
+	 * Mirrors Google's `auto-activate` attribute on `<md-tabs>`.
+	 * @default false
+	 */
+	autoActivate?: boolean;
+	/** Tab compound components as children. */
+	children: React.ReactNode;
+	/** Additional CSS class names for the root wrapper. */
+	className?: string;
+}
+
+/**
+ * Props for the `<TabsList>` container component.
+ *
+ * @example
+ * ```tsx
+ * <TabsList variant="primary" scrollable={false}>
+ *   <Tab value="tab1">Tab 1</Tab>
+ * </TabsList>
+ * ```
+ */
+export interface TabsListProps {
+	/** Visual style variant. @required */
+	variant: TabsVariant;
+	/**
+	 * When true, tabs scroll horizontally with 52px edge padding (MD3 spec).
+	 * When false, tabs divide the available width equally (flex-1).
+	 * @default false
+	 */
+	scrollable?: boolean;
+	/**
+	 * Background color override for the tab bar.
+	 * @default "var(--md-sys-color-surface)"
+	 */
+	backgroundColor?: string;
+	/** Tab components as children. */
+	children: React.ReactNode;
+	/** Additional CSS class names. */
+	className?: string;
+	/** Forwarded aria-label for the tablist. */
+	"aria-label"?: string;
+}
+
+/**
+ * Props for an individual `<Tab>` component.
+ *
+ * @example
+ * ```tsx
+ * <Tab value="flights" icon={<Icon name="flight" />}>Flights</Tab>
+ * <Tab value="trips" disabled>Trips</Tab>
+ * <Tab value="hotels" icon={<Icon name="hotel" />} inlineIcon>Hotels</Tab>
+ * ```
+ */
+export interface TabProps {
+	/** Unique value identifying this tab. Must match a `<TabsContent value>`. */
+	value: string;
+	/**
+	 * Optional icon rendered with the label text.
+	 * - Default (stacked): icon above label, height increases to 64dp.
+	 * - With `inlineIcon`: icon beside label (same row), height stays 48dp.
+	 */
+	icon?: React.ReactNode;
+	/**
+	 * When true, icon is placed inline (same row) with the label text.
+	 * Container height stays at 48dp (does NOT increase to 64dp).
+	 * Mirrors the `inline-icon` attribute on `<md-primary-tab>`.
+	 * @default false
+	 */
+	inlineIcon?: boolean;
+	/**
+	 * When true, disables interaction.
+	 * Disabled tabs are skipped entirely in keyboard navigation (ArrowKey).
+	 */
+	disabled?: boolean;
+	/** Additional CSS class names. */
+	className?: string;
+	/**
+	 * Optional badge element overlaid on the tab content.
+	 * Handled via `BadgedBox`:
+	 * - Stacked icon: Overlaps icon's top-trailing corner.
+	 * - Inline/Text-only: Placed next to the text.
+	 */
+	badge?: React.ReactNode;
+	/** Label text rendered inside the tab. */
+	children: React.ReactNode;
+}
+
+/**
+ * Props for the `<TabsContent>` panel component.
+ *
+ * @example
+ * ```tsx
+ * <TabsContent value="flights">Flight content here</TabsContent>
+ * ```
+ */
+export interface TabsContentProps {
+	/** Must match the `value` of a sibling `<Tab>`. */
+	value: string;
+	/** Additional CSS class names. */
+	className?: string;
+	/** Panel content. */
+	children: React.ReactNode;
+}

package/{dist/ui/text-field/index.d.ts → src/ui/text-field/index.ts}

@@ -7,5 +7,12 @@
  * import { TextField } from '@bug-on/md3-react';
  * ```
  */
+
 export { TextField } from "./text-field";
-export type { TextFieldHandle, TextFieldInputType, TextFieldProps, TextFieldTrailingIconMode, TextFieldVariant, } from "./text-field.types";
+export type {
+	TextFieldHandle,
+	TextFieldInputType,
+	TextFieldProps,
+	TextFieldTrailingIconMode,
+	TextFieldVariant,
+} from "./text-field.types";

package/src/ui/text-field/subcomponents/active-indicator.tsx

@@ -0,0 +1,67 @@
+/**
+ * @file active-indicator.tsx
+ * Animated bottom border line for the MD3 Filled TextField.
+ * Expands height from 1px → 2px and color changes on focus.
+ */
+
+import { m } from "motion/react";
+import * as React from "react";
+import {
+	MD3_INDICATOR_DURATION,
+	MD3_STANDARD_EASING,
+} from "../../shared/constants";
+import { TF_COLORS, TF_SIZE } from "../text-field.tokens";
+
+export interface ActiveIndicatorProps {
+	isFocused: boolean;
+	isError: boolean;
+	isDisabled: boolean;
+	isHovered: boolean;
+	prefersReduced: boolean;
+}
+
+/**
+ * MD3 Active Indicator — the bottom border line for Filled TextField.
+ *
+ * Animates:
+ * - `height`: 1px (enabled) → 2px (focused)
+ * - `backgroundColor`: on-surface-variant → primary (focused) → error
+ * - `scaleX`: 0 → 1 expanding from center on focus in
+ *
+ * @see https://m3.material.io/components/text-fields/specs#filled-text-field
+ */
+export const ActiveIndicator = React.memo(function ActiveIndicator({
+	isFocused,
+	isError,
+	isDisabled,
+	isHovered,
+	prefersReduced,
+}: ActiveIndicatorProps) {
+	const duration = prefersReduced ? 0 : MD3_INDICATOR_DURATION;
+	const ease = MD3_STANDARD_EASING;
+
+	const height =
+		isFocused || isError ? TF_SIZE.indicatorThick : TF_SIZE.indicatorThin;
+
+	let backgroundColor: string;
+	if (isError) {
+		backgroundColor = TF_COLORS.error;
+	} else if (isFocused) {
+		backgroundColor = TF_COLORS.primary;
+	} else if (isHovered && !isDisabled) {
+		backgroundColor = TF_COLORS.inputText;
+	} else {
+		backgroundColor = TF_COLORS.onSurfaceVariant;
+	}
+
+	return (
+		<m.div
+			aria-hidden="true"
+			className="absolute bottom-0 left-0 right-0 origin-center"
+			animate={{ height, backgroundColor }}
+			transition={{ duration, ease }}
+		/>
+	);
+});
+
+ActiveIndicator.displayName = "ActiveIndicator";

package/src/ui/text-field/subcomponents/floating-label.tsx

@@ -0,0 +1,161 @@
+/**
+ * @file floating-label.tsx
+ * Animated floating label for MD3 TextField.
+ * Animates between inline (body large) and floated (body small) positions.
+ */
+
+import { AnimatePresence, m } from "motion/react";
+import * as React from "react";
+import { cn } from "../../../lib/utils";
+import {
+	MD3_LABEL_FLOAT_DURATION,
+	MD3_STANDARD_EASING,
+} from "../../shared/constants";
+import { TF_COLORS, TF_TYPOGRAPHY } from "../text-field.tokens";
+
+export interface FloatingLabelProps {
+	/** The label text content. */
+	text: string;
+	/** Whether the label is in the floated (small) position. */
+	isFloated: boolean;
+	/** Whether the field is currently focused. */
+	isFocused: boolean;
+	/** Whether the field is in error state. */
+	isError: boolean;
+	/** Whether the field is disabled. */
+	isDisabled: boolean;
+	/** 'filled' or 'outlined' — determines vertical y offset. */
+	variant: "filled" | "outlined";
+	/** Container height in px (56 normal, 48 dense). */
+	containerHeight: number;
+	/** Whether to skip animations (prefers-reduced-motion). */
+	prefersReduced: boolean;
+	/** Whether the required asterisk should be shown. */
+	showAsterisk: boolean;
+	/** ID of the label element, for associating with a containing element. */
+	htmlFor?: string;
+	/** Ref callback so the parent can measure label width for the outlined notch. */
+	labelRef?: React.Ref<HTMLSpanElement>;
+	/** Whether there is a leading icon. */
+	hasLeading?: boolean;
+}
+
+/**
+ * Calculates the y-translation (in px) for the floated label position.
+ *
+ * For FILLED: move up from vertical center to the top inline padding area.
+ * For OUTLINED: move up so the label sits on the top border line.
+ *
+ * The label starts at y=0 (vertically centered by flex parent).
+ * When floated, it moves upward by `offset` pixels.
+ */
+function getFloatedY(
+	variant: "filled" | "outlined",
+	containerHeight: number,
+): number {
+	// Label body-large line height ≈ 24px (16px * 1.5)
+	// Label body-small line height ≈ 16px (12px * 1.33)
+	// Floated container top-padding: 8px from top of container
+	const labelSmallHeight = 16;
+	const paddingTop = 8;
+
+	if (variant === "filled") {
+		// Center of container → top-padding area
+		// Center is at containerHeight/2, floated center is at paddingTop + labelSmallHeight/2
+		const floatedCenter = paddingTop + labelSmallHeight / 2;
+		const unfloatedCenter = containerHeight / 2;
+		return -(unfloatedCenter - floatedCenter);
+	}
+	// Outlined: label sits on the border line (y = 0 relative to container top)
+	// We move up by half the container height to reach the border
+	return -(containerHeight / 2);
+}
+
+/**
+ * Returns the label color based on current state.
+ */
+function getLabelColor(
+	isFloated: boolean,
+	isFocused: boolean,
+	isError: boolean,
+	isDisabled: boolean,
+): string {
+	if (isDisabled) return TF_COLORS.onSurfaceVariant;
+	if (isError) return TF_COLORS.error;
+	if (isFloated && isFocused) return TF_COLORS.primary;
+	return TF_COLORS.onSurfaceVariant;
+}
+
+/**
+ * MD3 Expressive Floating Label.
+ *
+ * Animates y-position, scale, and color when the label floats.
+ * Uses `transformOrigin: 'left center'` so scaling anchors at the start.
+ *
+ * @accessibility
+ * Rendered as a `<label>` with `htmlFor` linking to the `<input>`.
+ * When floated, visual size changes but the semantic label is unchanged.
+ */
+export const FloatingLabel = React.memo(function FloatingLabel({
+	text,
+	isFloated,
+	isFocused,
+	isError,
+	isDisabled,
+	variant,
+	containerHeight,
+	prefersReduced,
+	showAsterisk,
+	htmlFor,
+	labelRef,
+	hasLeading = false,
+}: FloatingLabelProps) {
+	const duration = prefersReduced ? 0 : MD3_LABEL_FLOAT_DURATION;
+	const ease = MD3_STANDARD_EASING;
+
+	const y = isFloated ? getFloatedY(variant, containerHeight) : 0;
+	const x = variant === "outlined" && isFloated && hasLeading ? -36 : 0;
+	const scale = isFloated ? TF_TYPOGRAPHY.labelScaleRatio : 1;
+	const color = getLabelColor(isFloated, isFocused, isError, isDisabled);
+
+	return (
+		<m.label
+			htmlFor={htmlFor}
+			className={cn(
+				"absolute pointer-events-none select-none origin-[left_center] leading-6 text-base whitespace-nowrap",
+				"px-1 -mx-1", // Clear the notch gap and keep text aligned
+				variant === "outlined" && isFloated && "bg-m3-surface",
+				"left-4",
+				isDisabled && "opacity-[0.38]",
+			)}
+			animate={{ y, x, scale, color }}
+			transition={{ duration, ease }}
+			style={{
+				top: (containerHeight - 24) / 2, // 24px is the resting line-height
+				transformOrigin: "left center",
+				zIndex: 1,
+			}}
+		>
+			<span ref={labelRef} className="inline-block relative">
+				{text}
+				<AnimatePresence>
+					{showAsterisk && (
+						<m.span
+							key="asterisk"
+							aria-hidden="true"
+							initial={{ opacity: 0 }}
+							animate={{ opacity: 1 }}
+							exit={{ opacity: 0 }}
+							transition={{ duration: prefersReduced ? 0 : 0.1 }}
+							className="ml-0.5 text-m3-error"
+						>
+							*
+						</m.span>
+					)}
+				</AnimatePresence>
+			</span>
+		</m.label>
+	);
+});
+
+FloatingLabel.displayName = "FloatingLabel";

package/src/ui/text-field/subcomponents/leading-icon.tsx

@@ -0,0 +1,46 @@
+/**
+ * @file leading-icon.tsx
+ * Leading icon slot for MD3 TextField.
+ */
+
+import * as React from "react";
+import { TF_COLORS } from "../text-field.tokens";
+
+export interface LeadingIconProps {
+	/** Icon node — should be 24×24px. */
+	children: React.ReactNode;
+	/** Whether the field is in error state (changes icon color). */
+	isError: boolean;
+	/** Whether the field is disabled. */
+	isDisabled: boolean;
+}
+
+/**
+ * MD3 Leading Icon wrapper.
+ *
+ * Decorative — `aria-hidden="true"`.
+ * Color: `on-surface-variant` (default), `error` (error state).
+ * Size: 24×24px icon, 48×56px touch target via flex alignment.
+ *
+ * @see https://m3.material.io/components/text-fields/specs#anatomy
+ */
+export const LeadingIcon = React.memo(function LeadingIcon({
+	children,
+	isError,
+	isDisabled,
+}: LeadingIconProps) {
+	const color =
+		isError && !isDisabled ? TF_COLORS.error : TF_COLORS.onSurfaceVariant;
+
+	return (
+		<div
+			aria-hidden="true"
+			className="flex items-center justify-center shrink-0 w-6 h-6 ml-3"
+			style={{ color }}
+		>
+			{children}
+		</div>
+	);
+});
+
+LeadingIcon.displayName = "LeadingIcon";

package/src/ui/text-field/subcomponents/outline-container.tsx

@@ -0,0 +1,170 @@
+/**
+ * @file outline-container.tsx
+ * MD3-compliant outlined border with animated notch for the Outlined TextField.
+ *
+ * Implementation: 3-segment approach inspired by Material Web's fieldset/legend pattern.
+ * The top border is split into: [left-segment] [notch-gap] [right-segment].
+ * The notch-gap width animates from 0 → (labelWidth × scaleRatio + 8px) when label floats.
+ *
+ * This mirrors Material Web's implementation without requiring <fieldset> semantics.
+ *
+ * @see https://github.com/material-components/material-web/tree/main/textfield
+ * @see https://m3.material.io/components/text-fields/specs#outlined-text-field
+ */
+
+import { m } from "motion/react";
+import * as React from "react";
+import {
+	MD3_INDICATOR_DURATION,
+	MD3_LABEL_FLOAT_DURATION,
+	MD3_STANDARD_EASING,
+} from "../../shared/constants";
+import { TF_COLORS, TF_SIZE, TF_TYPOGRAPHY } from "../text-field.tokens";
+
+export interface OutlineContainerProps {
+	/** Whether the label is in the floated position. */
+	isFloated: boolean;
+	/** Whether the field is focused. */
+	isFocused: boolean;
+	/** Whether the field is in error state. */
+	isError: boolean;
+	/** Whether the field is disabled. */
+	isDisabled: boolean;
+	/** Whether the field is hovered. */
+	isHovered: boolean;
+	/**
+	 * Measured width of the label element in its full (unfloated) size.
+	 * The notch width = labelWidth × scaleRatio + 2×notchPadding.
+	 */
+	labelWidth: number;
+	/** Whether to disable animations. */
+	prefersReduced: boolean;
+}
+
+/**
+ * Determines the outline border color based on current state.
+ */
+function getOutlineColor(
+	isFocused: boolean,
+	isError: boolean,
+	isHovered: boolean,
+	isDisabled: boolean,
+): string {
+	if (isDisabled) return TF_COLORS.onSurfaceVariant;
+	if (isError) return TF_COLORS.error;
+	if (isFocused) return TF_COLORS.primary;
+	if (isHovered) return TF_COLORS.inputText;
+	return TF_COLORS.outline;
+}
+
+/**
+ * MD3 Outlined TextField container with animated notch.
+ *
+ * The notch gap expands/collapses in sync with the FloatingLabel animation,
+ * creating the visual effect of the label breaking through the border.
+ *
+ * Accessibility: `aria-hidden="true"` — purely decorative border.
+ */
+export const OutlineContainer = React.memo(function OutlineContainer({
+	isFloated,
+	isFocused,
+	isError,
+	isDisabled,
+	isHovered,
+	labelWidth,
+	prefersReduced,
+}: OutlineContainerProps) {
+	const colorDuration = prefersReduced ? 0 : MD3_INDICATOR_DURATION;
+	const notchDuration = prefersReduced ? 0 : MD3_LABEL_FLOAT_DURATION;
+	const ease = MD3_STANDARD_EASING;
+
+	const borderColor = getOutlineColor(
+		isFocused,
+		isError,
+		isHovered,
+		isDisabled,
+	);
+	const borderWidth =
+		isFocused || isError ? TF_SIZE.outlineThick : TF_SIZE.outlineThin;
+
+	// Calculate offset for notch (always 16px from the edge in M3 Outlined)
+	const leftSegmentWidth = TF_SIZE.paddingStart;
+
+	/**
+	 * Notch width calculation:
+	 * When floated: label is scaled to 0.75, so its displayed width = labelWidth × 0.75
+	 * Add 2 × notchPadding (4px each side) for spacing inside the notch gap.
+	 * When unfloated: 0 (no gap in the border).
+	 */
+	const notchWidth = isFloated
+		? labelWidth * TF_TYPOGRAPHY.labelScaleRatio + TF_SIZE.notchPadding * 2
+		: 0;
+
+	const borderTransition = { duration: colorDuration, ease };
+	const notchTransition = { duration: notchDuration, ease };
+
+	return (
+		<div
+			aria-hidden="true"
+			className="absolute inset-0 pointer-events-none flex rounded-[inherit]"
+		>
+			{/* Left segment — left + bottom + top borders */}
+			<m.div
+				className="rounded-tl-[inherit] rounded-bl-[inherit]"
+				style={{ width: leftSegmentWidth - TF_SIZE.notchPadding }}
+				animate={{
+					borderColor,
+					borderWidth,
+					borderStyle: "solid",
+					borderRightWidth: 0,
+				}}
+				transition={borderTransition}
+			/>
+
+			{/* Center (notch) segment */}
+			<m.div
+				className="flex flex-col shrink-0"
+				style={{ minWidth: 0 }}
+				animate={{ width: notchWidth }}
+				transition={notchTransition}
+			>
+				{/* Top border of notch: transparent when notched */}
+				<m.div
+					className="shrink-0"
+					style={{ height: borderWidth }}
+					animate={{
+						borderTopColor: borderColor,
+						opacity: isFloated ? 0 : 1,
+						borderTopWidth: borderWidth,
+						borderTopStyle: "solid",
+					}}
+					transition={borderTransition}
+				/>
+				{/* Bottom border (always present) */}
+				<m.div
+					className="flex-1"
+					animate={{
+						borderBottomColor: borderColor,
+						borderBottomWidth: borderWidth,
+						borderBottomStyle: "solid",
+					}}
+					transition={borderTransition}
+				/>
+			</m.div>
+
+			{/* Right segment — full height, right + bottom + top borders */}
+			<m.div
+				className="flex-1 rounded-tr-[inherit] rounded-br-[inherit]"
+				animate={{
+					borderColor,
+					borderWidth,
+					borderStyle: "solid",
+					borderLeftWidth: 0,
+				}}
+				transition={borderTransition}
+			/>
+		</div>
+	);
+});
+
+OutlineContainer.displayName = "OutlineContainer";

package/src/ui/text-field/subcomponents/prefix-suffix.tsx

@@ -0,0 +1,59 @@
+/**
+ * @file prefix-suffix.tsx
+ * Prefix and suffix text for MD3 TextField.
+ * Visible only when the label is floated (or when there is no label).
+ */
+
+import { AnimatePresence, m } from "motion/react";
+import * as React from "react";
+import {
+	MD3_LABEL_FLOAT_DURATION,
+	MD3_STANDARD_EASING,
+} from "../../shared/constants";
+import { TF_CLASSES } from "../text-field.tokens";
+
+export interface PrefixSuffixProps {
+	text: string;
+	type: "prefix" | "suffix";
+	/** Whether the label is floated (controls visibility). */
+	visible: boolean;
+	/** Disable animations. */
+	prefersReduced: boolean;
+}
+
+/**
+ * MD3 Prefix / Suffix Text.
+ *
+ * Animates in/out in sync with the floating label using AnimatePresence.
+ * Hidden when label is in the inline position (would overlap the label).
+ *
+ * @accessibility
+ * `aria-hidden="true"` — decorative. Screen readers read the full value in context.
+ */
+export const PrefixSuffix = React.memo(function PrefixSuffix({
+	text,
+	type,
+	visible,
+	prefersReduced,
+}: PrefixSuffixProps) {
+	const duration = prefersReduced ? 0 : MD3_LABEL_FLOAT_DURATION;
+
+	return (
+		<AnimatePresence>
+			{visible && (
+				<m.span
+					aria-hidden="true"
+					className={`${TF_CLASSES.prefixSuffix} ${type === "suffix" ? "ml-0.5" : "mr-0.5"}`}
+					initial={{ opacity: 0 }}
+					animate={{ opacity: 1 }}
+					exit={{ opacity: 0 }}
+					transition={{ duration, ease: MD3_STANDARD_EASING }}
+				>
+					{text}
+				</m.span>
+			)}
+		</AnimatePresence>
+	);
+});
+
+PrefixSuffix.displayName = "PrefixSuffix";