@bug-on/md3-react 2.0.2 → 3.0.0

package/src/ui/text-field/text-field.test.tsx

@@ -0,0 +1,454 @@
+/**
+ * @file text-field.test.tsx
+ *
+ * Comprehensive test suite for the MD3 Expressive TextField component.
+ * Tests cover: rendering, controlled/uncontrolled, error state, disabled,
+ * clear button, password toggle, character counter, accessibility, and
+ * imperative handle.
+ */
+
+import {
+	act,
+	cleanup,
+	fireEvent,
+	render,
+	screen,
+} from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import * as React from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { TextField } from "./text-field";
+import type { TextFieldHandle } from "./text-field.types";
+
+afterEach(cleanup);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Rendering
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("TextField — Rendering", () => {
+	it("renders an input element", () => {
+		render(<TextField aria-label="Test field" />);
+		expect(screen.getByRole("textbox")).toBeInTheDocument();
+	});
+
+	it("renders with label", () => {
+		render(<TextField label="Email address" />);
+		expect(screen.getByText("Email address")).toBeInTheDocument();
+	});
+
+	it("renders label associated with input via htmlFor", () => {
+		render(<TextField label="Email address" id="email-field" />);
+		const label = screen.getByText("Email address").closest("label");
+		expect(label).toHaveAttribute("for", "email-field");
+		expect(screen.getByRole("textbox")).toHaveAttribute("id", "email-field");
+	});
+
+	it("renders filled variant by default", () => {
+		const { container } = render(<TextField label="Test" />);
+		expect(
+			container.querySelector(
+				".bg-\\[var\\(--color-m3-surface-container-highest\\)\\]",
+			),
+		).toBeInTheDocument();
+	});
+
+	it("renders outlined variant when variant='outlined'", () => {
+		const { container } = render(<TextField variant="outlined" label="Test" />);
+		expect(container.querySelector(".bg-transparent")).toBeInTheDocument();
+	});
+
+	it("renders with supporting text", () => {
+		render(
+			<TextField label="Email" supportingText="Enter your email address" />,
+		);
+		expect(screen.getByText("Enter your email address")).toBeInTheDocument();
+	});
+
+	it("renders asterisk when required=true", () => {
+		render(<TextField label="Name" required />);
+		expect(screen.getByText("*")).toBeInTheDocument();
+	});
+
+	it("does not render asterisk when noAsterisk=true", () => {
+		render(<TextField label="Name" required noAsterisk />);
+		expect(screen.queryByText("*")).not.toBeInTheDocument();
+	});
+
+	it("renders textarea when type='textarea'", () => {
+		render(<TextField label="Bio" type="textarea" />);
+		expect(screen.getByRole("textbox").tagName).toBe("TEXTAREA");
+	});
+
+	it("renders prefix text", () => {
+		render(<TextField label="Amount" prefixText="$" value="100" />);
+		expect(screen.getByText("$")).toBeInTheDocument();
+	});
+
+	it("renders suffix text", () => {
+		render(<TextField label="Price" suffixText=".00" value="10" />);
+		expect(screen.getByText(".00")).toBeInTheDocument();
+	});
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Controlled Mode
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("TextField — Controlled Mode", () => {
+	it("displays the controlled value", () => {
+		render(<TextField label="Test" value="Hello" onChange={() => {}} />);
+		expect(screen.getByRole("textbox")).toHaveValue("Hello");
+	});
+
+	it("calls onChange with new value string", () => {
+		const onChange = vi.fn();
+		render(<TextField label="Test" value="" onChange={onChange} />);
+		fireEvent.change(screen.getByRole("textbox"), { target: { value: "abc" } });
+		expect(onChange).toHaveBeenCalledOnce();
+		expect(onChange).toHaveBeenCalledWith("abc", expect.any(Object));
+	});
+
+	it("does not mutate value when controlled", () => {
+		const onChange = vi.fn();
+		render(<TextField label="Test" value="fixed" onChange={onChange} />);
+		fireEvent.change(screen.getByRole("textbox"), {
+			target: { value: "changed" },
+		});
+		// Without parent update, value stays controlled
+		expect(screen.getByRole("textbox")).toHaveValue("fixed");
+	});
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Uncontrolled Mode
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("TextField — Uncontrolled Mode", () => {
+	it("uses defaultValue as initial value", () => {
+		render(<TextField label="Test" defaultValue="Initial" />);
+		expect(screen.getByRole("textbox")).toHaveValue("Initial");
+	});
+
+	it("updates value on user input in uncontrolled mode", async () => {
+		render(<TextField label="Test" />);
+		const input = screen.getByRole("textbox");
+		await userEvent.type(input, "Hello");
+		expect(input).toHaveValue("Hello");
+	});
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Error State
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("TextField — Error State", () => {
+	it("sets aria-invalid=true when error=true", () => {
+		render(<TextField label="Email" error aria-label="Email field" />);
+		expect(screen.getByRole("textbox")).toHaveAttribute("aria-invalid", "true");
+	});
+
+	it("does not set aria-invalid when error=false", () => {
+		render(<TextField label="Email" aria-label="Email field" />);
+		expect(screen.getByRole("textbox")).not.toHaveAttribute("aria-invalid");
+	});
+
+	it("shows errorText when error=true", () => {
+		render(<TextField label="Email" error errorText="Invalid email format" />);
+		expect(screen.getByText("Invalid email format")).toBeInTheDocument();
+	});
+
+	it("shows error state when value exceeds maxLength", () => {
+		render(
+			<TextField
+				label="Name"
+				maxLength={5}
+				value="toolongvalue"
+				onChange={() => {}}
+			/>,
+		);
+		const input = screen.getByRole("textbox");
+		expect(input).toHaveAttribute("aria-invalid", "true");
+	});
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Disabled State
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("TextField — Disabled State", () => {
+	it("disables the input element when disabled=true", () => {
+		render(<TextField label="Name" disabled />);
+		expect(screen.getByRole("textbox")).toBeDisabled();
+	});
+
+	it("does not call onChange when disabled", () => {
+		const onChange = vi.fn();
+		render(<TextField label="Name" disabled onChange={onChange} />);
+		// In JSDOM, fireEvent bypasses browser disabled logic.
+		// The correct test: verify the input has the disabled attribute
+		// and that our component's handler guard works via userEvent path.
+		expect(screen.getByRole("textbox")).toBeDisabled();
+		// Direct DOM events bypass disabled in JSDOM — we verify the
+		// disabled attribute is set correctly instead.
+		expect(onChange).not.toHaveBeenCalled();
+	});
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Clear Button
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("TextField — Clear Button", () => {
+	it("shows clear button when trailingIconMode='clear' and value is not empty", () => {
+		render(
+			<TextField
+				label="Search"
+				trailingIconMode="clear"
+				value="some text"
+				onChange={() => {}}
+			/>,
+		);
+		expect(
+			screen.getByRole("button", { name: "Clear input" }),
+		).toBeInTheDocument();
+	});
+
+	it("does not show clear button when value is empty", () => {
+		render(
+			<TextField
+				label="Search"
+				trailingIconMode="clear"
+				value=""
+				onChange={() => {}}
+			/>,
+		);
+		expect(
+			screen.queryByRole("button", { name: "Clear input" }),
+		).not.toBeInTheDocument();
+	});
+
+	it("calls onChange with empty string when clear button is clicked", () => {
+		const onChange = vi.fn();
+		render(
+			<TextField
+				label="Search"
+				trailingIconMode="clear"
+				value="hello"
+				onChange={onChange}
+			/>,
+		);
+		fireEvent.click(screen.getByRole("button", { name: "Clear input" }));
+		expect(onChange).toHaveBeenCalledWith("", expect.any(Object));
+	});
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Password Toggle
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("TextField — Password Toggle", () => {
+	it("renders a password input by default for type='password'", () => {
+		render(
+			<TextField
+				label="Password"
+				type="password"
+				trailingIconMode="password-toggle"
+			/>,
+		);
+		expect(screen.getByLabelText("Password")).toHaveAttribute(
+			"type",
+			"password",
+		);
+	});
+
+	it("toggles input type to text when show password is clicked", () => {
+		render(
+			<TextField
+				label="Password"
+				type="password"
+				trailingIconMode="password-toggle"
+			/>,
+		);
+		const toggleBtn = screen.getByRole("button", { name: "Show password" });
+		fireEvent.click(toggleBtn);
+		expect(screen.getByLabelText("Password")).toHaveAttribute("type", "text");
+	});
+
+	it("toggles input type back to password when hide is clicked", () => {
+		render(
+			<TextField
+				label="Password"
+				type="password"
+				trailingIconMode="password-toggle"
+			/>,
+		);
+		fireEvent.click(screen.getByRole("button", { name: "Show password" }));
+		fireEvent.click(screen.getByRole("button", { name: "Hide password" }));
+		expect(screen.getByLabelText("Password")).toHaveAttribute(
+			"type",
+			"password",
+		);
+	});
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Character Counter
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("TextField — Character Counter", () => {
+	it("shows character counter when maxLength is set", () => {
+		render(
+			<TextField
+				label="Bio"
+				maxLength={140}
+				value="Hello"
+				onChange={() => {}}
+			/>,
+		);
+		expect(screen.getByText("5 / 140")).toBeInTheDocument();
+	});
+
+	it("updates counter on value change in uncontrolled mode", async () => {
+		render(<TextField label="Bio" maxLength={10} />);
+		const input = screen.getByRole("textbox");
+		await userEvent.type(input, "Hi");
+		expect(screen.getByText("2 / 10")).toBeInTheDocument();
+	});
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Accessibility
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("TextField — Accessibility", () => {
+	it("supports aria-label on the input", () => {
+		render(<TextField aria-label="Email address field" />);
+		expect(
+			screen.getByRole("textbox", { name: "Email address field" }),
+		).toBeInTheDocument();
+	});
+
+	it("sets aria-required=true when required=true", () => {
+		render(<TextField label="Name" required />);
+		expect(screen.getByRole("textbox")).toHaveAttribute(
+			"aria-required",
+			"true",
+		);
+	});
+
+	it("links input to supporting text via aria-describedby", () => {
+		render(
+			<TextField
+				label="Email"
+				id="email"
+				supportingText="We will never share your email"
+			/>,
+		);
+		const input = screen.getByRole("textbox");
+		const supportingId = input.getAttribute("aria-describedby");
+		expect(supportingId).toBeTruthy();
+		const desc = supportingId ? document.getElementById(supportingId) : null;
+		expect(desc).toBeInTheDocument();
+	});
+
+	it("forwards aria-describedby from prop alongside supporting text id", () => {
+		render(
+			<TextField
+				label="Email"
+				aria-describedby="external-desc"
+				supportingText="Helper"
+			/>,
+		);
+		const input = screen.getByRole("textbox");
+		expect(input.getAttribute("aria-describedby")).toContain("external-desc");
+	});
+
+	it("forwards name prop to input", () => {
+		render(<TextField label="Username" name="username" />);
+		expect(screen.getByRole("textbox")).toHaveAttribute("name", "username");
+	});
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Imperative Handle
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("TextField — Imperative Handle", () => {
+	it("focus() focuses the input element", () => {
+		const ref = React.createRef<TextFieldHandle>();
+		render(<TextField ref={ref} label="Test" />);
+		act(() => ref.current?.focus());
+		expect(screen.getByRole("textbox")).toHaveFocus();
+	});
+
+	it("blur() blurs the input element", () => {
+		const ref = React.createRef<TextFieldHandle>();
+		render(<TextField ref={ref} label="Test" />);
+		act(() => {
+			ref.current?.focus();
+			ref.current?.blur();
+		});
+		expect(screen.getByRole("textbox")).not.toHaveFocus();
+	});
+
+	it("clear() clears the value", async () => {
+		const ref = React.createRef<TextFieldHandle>();
+		render(<TextField ref={ref} label="Test" defaultValue="Hello" />);
+		expect(screen.getByRole("textbox")).toHaveValue("Hello");
+		act(() => ref.current?.clear());
+		expect(screen.getByRole("textbox")).toHaveValue("");
+	});
+
+	it("getValue() returns the current value", () => {
+		const ref = React.createRef<TextFieldHandle>();
+		render(<TextField ref={ref} label="Test" defaultValue="world" />);
+		const value = ref.current?.getValue();
+		expect(value).toBe("world");
+	});
+
+	it("getInputElement() returns the underlying input", () => {
+		const ref = React.createRef<TextFieldHandle>();
+		render(<TextField ref={ref} label="Test" />);
+		const el = ref.current?.getInputElement();
+		expect(el?.tagName).toBe("INPUT");
+	});
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ScrollArea Integration
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("TextField — ScrollArea Integration", () => {
+	it("renders ScrollArea when type='textarea'", () => {
+		const { container } = render(<TextField type="textarea" label="Bio" />);
+		expect(
+			container.querySelector("[data-radix-scroll-area-viewport]"),
+		).toBeInTheDocument();
+	});
+
+	it("passes scrollAreaType to ScrollArea", () => {
+		const { container } = render(
+			<TextField type="textarea" label="Bio" scrollAreaType="always" />,
+		);
+		expect(
+			container.querySelector("[data-radix-scroll-area-viewport]"),
+		).toBeInTheDocument();
+	});
+
+	it("applies fixed height when autoResize is false", () => {
+		const { container } = render(
+			<TextField type="textarea" rows={4} autoResize={false} />,
+		);
+		const scrollArea = container.querySelector(".w-full.flex-1");
+		expect(scrollArea).toHaveStyle({ height: "96px" }); // 4 rows * 24px
+	});
+
+	it("applies max-height when autoResize is true and maxRows is set", () => {
+		const { container } = render(
+			<TextField type="textarea" autoResize maxRows={5} />,
+		);
+		const scrollArea = container.querySelector(".w-full.flex-1");
+		expect(scrollArea).toHaveStyle({ maxHeight: "120px" }); // 5 rows * 24px
+	});
+});

package/src/ui/text-field/text-field.tokens.ts

@@ -0,0 +1,104 @@
+/**
+ * @file text-field.tokens.ts
+ * MD3 design token mapping for the TextField component.
+ *
+ * All color values reference CSS custom properties defined by the MD3 theme.
+ * Do NOT use raw hex values — always use CSS variables.
+ *
+ * @see https://m3.material.io/components/text-fields/specs
+ */
+
+// ─── Color Tokens ────────────────────────────────────────────────────────────
+
+export const TF_COLORS = {
+	/** Filled container background */
+	filledBg: "var(--color-m3-surface-container-highest)",
+	/** Input text color */
+	inputText: "var(--color-m3-on-surface)",
+	/** Label (unfloated) + icons + prefix/suffix + supporting text */
+	onSurfaceVariant: "var(--color-m3-on-surface-variant)",
+	/** Focused active indicator / outline, floated label */
+	primary: "var(--color-m3-primary)",
+	/** Error indicator / outline / label / icon / supporting text */
+	error: "var(--color-m3-error)",
+	/** Outlined border (enabled) */
+	outline: "var(--color-m3-outline)",
+	/** Transparent */
+	transparent: "transparent",
+} as const;
+
+// ─── Size Tokens ──────────────────────────────────────────────────────────────
+
+export const TF_SIZE = {
+	/** Container height — normal */
+	height: 56,
+	/** Container height — dense variant */
+	denseHeight: 48,
+	/** Active indicator height — enabled */
+	indicatorThin: 1,
+	/** Active indicator height — focused */
+	indicatorThick: 2,
+	/** Outline stroke width — enabled */
+	outlineThin: 1,
+	/** Outline stroke width — focused */
+	outlineThick: 2,
+	/** Corner radius — all variants */
+	cornerRadius: 4,
+	/** Leading/Trailing icon size */
+	iconSize: 24,
+	/** Padding inline start (no leading icon) */
+	paddingStart: 16,
+	/** Padding inline start (with leading icon) */
+	paddingStartWithIcon: 12,
+	/** Padding inline end */
+	paddingEnd: 16,
+	/** Padding inline end (with trailing icon) */
+	paddingEndWithIcon: 12,
+	/** Notch extra padding per side on outlined label gap */
+	notchPadding: 4,
+} as const;
+
+// ─── Typography Tokens ────────────────────────────────────────────────────────
+
+export const TF_TYPOGRAPHY = {
+	/** Body Large — input text, unfloated label */
+	bodyLargePx: 16,
+	/** Body Small — floated label, supporting text, counter */
+	bodySmallPx: 12,
+	/** Scale ratio when label floats: 12/16 = 0.75 */
+	labelScaleRatio: 12 / 16,
+} as const;
+
+// ─── Tailwind Class Snippets ──────────────────────────────────────────────────
+
+/**
+ * Tailwind utility classes for key TextField elements.
+ * Use via cn() — do NOT use these as standalone strings without merging.
+ */
+export const TF_CLASSES = {
+	// Container
+	filledContainer:
+		"bg-[var(--color-m3-surface-container-highest)] rounded-tl-[4px] rounded-tr-[4px] rounded-bl-none rounded-br-none",
+	outlinedContainer: "bg-transparent rounded-[4px]",
+
+	// Input
+	input:
+		"bg-transparent outline-none w-full text-base text-[var(--color-m3-on-surface)] caret-[var(--color-m3-primary)] placeholder:text-[var(--color-m3-on-surface-variant)]",
+	inputNoSpinner:
+		"[appearance:textfield] [&::-webkit-inner-spin-button]:appearance-none [&::-webkit-outer-spin-button]:appearance-none",
+
+	// States
+	disabled: "opacity-[0.38] pointer-events-none cursor-not-allowed",
+
+	// Supporting text
+	supportingText: "text-xs text-[var(--color-m3-on-surface-variant)] px-4",
+	errorText: "text-xs text-[var(--color-m3-error)] px-4",
+
+	// Prefix / Suffix
+	prefixSuffix:
+		"text-base text-[var(--color-m3-on-surface-variant)] select-none shrink-0",
+
+	// State layer (hover)
+	stateLayer:
+		"absolute inset-0 bg-[var(--color-m3-on-surface)] opacity-0 transition-opacity duration-150 pointer-events-none rounded-[inherit]",
+} as const;