@bug-on/md3-react 2.0.3 → 3.0.0

package/src/ui/switch/switch.stories.tsx

@@ -0,0 +1,309 @@
+/**
+ * @file switch.stories.tsx
+ * MD3 Expressive Switch — all usage patterns and states.
+ *
+ * Can be used as:
+ * 1. Storybook stories (if Storybook is configured)
+ * 2. Standalone demo component for the docs app
+ *
+ * Covers all 7 patterns from the MD3 Switch specification:
+ * 1. Basic toggle
+ * 2. With label
+ * 3. With icons (both states)
+ * 4. With only selected icon
+ * 5. Disabled (checked)
+ * 6. Disabled (unchecked)
+ * 7. All states grid
+ */
+
+"use client";
+
+import * as React from "react";
+import { Switch } from "./switch";
+
+// ─── Icon helper ──────────────────────────────────────────────────────────────
+
+/** Simple check icon using SVG (no external icon dependency). @internal */
+function CheckIcon() {
+	return (
+		<svg
+			viewBox="0 0 16 16"
+			width={16}
+			height={16}
+			fill="none"
+			stroke="currentColor"
+			strokeWidth={2.5}
+			strokeLinecap="round"
+			strokeLinejoin="round"
+			aria-hidden="true"
+		>
+			<polyline points="3,8 6.5,11.5 13,5" />
+		</svg>
+	);
+}
+
+/** Simple close/X icon for unselected state. @internal */
+function CloseIcon() {
+	return (
+		<svg
+			viewBox="0 0 16 16"
+			width={16}
+			height={16}
+			fill="none"
+			stroke="currentColor"
+			strokeWidth={2.5}
+			strokeLinecap="round"
+			aria-hidden="true"
+		>
+			<line x1="4" y1="4" x2="12" y2="12" />
+			<line x1="12" y1="4" x2="4" y2="12" />
+		</svg>
+	);
+}
+
+// ─── Story 1: Basic ───────────────────────────────────────────────────────────
+
+/** Basic stateful switch — no label, no icons. */
+export function Basic() {
+	const [checked, setChecked] = React.useState(false);
+	return (
+		<div className="flex flex-col gap-4">
+			<p className="text-sm text-neutral-500">
+				State: <strong>{checked ? "On" : "Off"}</strong>
+			</p>
+			<Switch
+				checked={checked}
+				onCheckedChange={setChecked}
+				ariaLabel="Basic switch"
+			/>
+		</div>
+	);
+}
+
+// ─── Story 2: With Label ──────────────────────────────────────────────────────
+
+/** Switch with a visible text label using htmlFor linkage. */
+export function WithLabel() {
+	const [checked, setChecked] = React.useState(true);
+	return (
+		<Switch checked={checked} onCheckedChange={setChecked} label="Wi-Fi" />
+	);
+}
+
+// ─── Story 3: With Icons (both states) ───────────────────────────────────────
+
+/**
+ * Switch showing icons in both checked and unchecked states.
+ * Uses check icon when on, close icon when off.
+ */
+export function WithIcons() {
+	const [checked, setChecked] = React.useState(false);
+	return (
+		<div className="flex flex-col gap-4">
+			<Switch
+				checked={checked}
+				onCheckedChange={setChecked}
+				icons
+				thumbContent={checked ? <CheckIcon /> : <CloseIcon />}
+				label="Notifications"
+			/>
+		</div>
+	);
+}
+
+// ─── Story 4: Only Selected Icon ─────────────────────────────────────────────
+
+/**
+ * Switch showing the icon only in the checked (selected) state.
+ * Unselected state has no icon.
+ */
+export function WithOnlySelectedIcon() {
+	const [checked, setChecked] = React.useState(false);
+	return (
+		<Switch
+			checked={checked}
+			onCheckedChange={setChecked}
+			showOnlySelectedIcon
+			thumbContent={<CheckIcon />}
+			label="Dark mode"
+		/>
+	);
+}
+
+// ─── Story 5: Disabled (checked) ─────────────────────────────────────────────
+
+/** Disabled switch in the checked (on) state. */
+export function DisabledChecked() {
+	return (
+		<Switch
+			checked
+			onCheckedChange={() => {}}
+			disabled
+			label="Always on (disabled)"
+		/>
+	);
+}
+
+// ─── Story 6: Disabled (unchecked) ───────────────────────────────────────────
+
+/** Disabled switch in the unchecked (off) state. */
+export function DisabledUnchecked() {
+	return (
+		<Switch
+			checked={false}
+			onCheckedChange={() => {}}
+			disabled
+			label="Unavailable feature (disabled)"
+		/>
+	);
+}
+
+// ─── Story 7: All States Grid ─────────────────────────────────────────────────
+
+/**
+ * Grid displaying all Switch state combinations:
+ * - Enabled: checked / unchecked
+ * - Disabled: checked / unchecked
+ * - With icons: checked / unchecked
+ * - With only selected icon: checked / unchecked
+ */
+export function AllStatesGrid() {
+	const [checkedMap, setCheckedMap] = React.useState<Record<string, boolean>>({
+		enabled_on: true,
+		enabled_off: false,
+		icons_on: true,
+		icons_off: false,
+		selected_icon_on: true,
+		selected_icon_off: false,
+	});
+
+	const toggle = (key: string) =>
+		setCheckedMap((prev) => ({ ...prev, [key]: !prev[key] }));
+
+	const Row = ({
+		title,
+		children,
+	}: {
+		title: string;
+		children: React.ReactNode;
+	}) => (
+		<div className="flex items-center gap-6">
+			<span className="w-48 text-sm text-neutral-500 shrink-0">{title}</span>
+			{children}
+		</div>
+	);
+
+	return (
+		<div className="flex flex-col gap-6 p-4">
+			<Row title="Enabled (unchecked)">
+				<Switch
+					checked={checkedMap.enabled_off}
+					onCheckedChange={() => toggle("enabled_off")}
+					ariaLabel="Enabled unchecked"
+				/>
+			</Row>
+			<Row title="Enabled (checked)">
+				<Switch
+					checked={checkedMap.enabled_on}
+					onCheckedChange={() => toggle("enabled_on")}
+					ariaLabel="Enabled checked"
+				/>
+			</Row>
+			<Row title="Disabled (unchecked)">
+				<Switch
+					checked={false}
+					onCheckedChange={() => {}}
+					disabled
+					ariaLabel="Disabled unchecked"
+				/>
+			</Row>
+			<Row title="Disabled (checked)">
+				<Switch
+					checked
+					onCheckedChange={() => {}}
+					disabled
+					ariaLabel="Disabled checked"
+				/>
+			</Row>
+			<Row title="With icons (off)">
+				<Switch
+					checked={checkedMap.icons_off}
+					onCheckedChange={() => toggle("icons_off")}
+					icons
+					thumbContent={checkedMap.icons_off ? <CheckIcon /> : <CloseIcon />}
+					ariaLabel="With icons unchecked"
+				/>
+			</Row>
+			<Row title="With icons (on)">
+				<Switch
+					checked={checkedMap.icons_on}
+					onCheckedChange={() => toggle("icons_on")}
+					icons
+					thumbContent={checkedMap.icons_on ? <CheckIcon /> : <CloseIcon />}
+					ariaLabel="With icons checked"
+				/>
+			</Row>
+			<Row title="Selected icon only (off)">
+				<Switch
+					checked={checkedMap.selected_icon_off}
+					onCheckedChange={() => toggle("selected_icon_off")}
+					showOnlySelectedIcon
+					thumbContent={<CheckIcon />}
+					ariaLabel="Selected icon only unchecked"
+				/>
+			</Row>
+			<Row title="Selected icon only (on)">
+				<Switch
+					checked={checkedMap.selected_icon_on}
+					onCheckedChange={() => toggle("selected_icon_on")}
+					showOnlySelectedIcon
+					thumbContent={<CheckIcon />}
+					ariaLabel="Selected icon only checked"
+				/>
+			</Row>
+		</div>
+	);
+}
+
+// ─── Master Demo ──────────────────────────────────────────────────────────────
+
+/**
+ * All switch stories in one scrollable demo page.
+ * Used by the docs app to showcase all variants.
+ */
+export function SwitchDemo() {
+	return (
+		<div className="flex flex-col gap-10 p-8 max-w-2xl">
+			<section>
+				<h2 className="text-xl font-semibold mb-4">1. Basic</h2>
+				<Basic />
+			</section>
+			<section>
+				<h2 className="text-xl font-semibold mb-4">2. With Label</h2>
+				<WithLabel />
+			</section>
+			<section>
+				<h2 className="text-xl font-semibold mb-4">
+					3. With Icons (Both States)
+				</h2>
+				<WithIcons />
+			</section>
+			<section>
+				<h2 className="text-xl font-semibold mb-4">4. Only Selected Icon</h2>
+				<WithOnlySelectedIcon />
+			</section>
+			<section>
+				<h2 className="text-xl font-semibold mb-4">5. Disabled (Checked)</h2>
+				<DisabledChecked />
+			</section>
+			<section>
+				<h2 className="text-xl font-semibold mb-4">6. Disabled (Unchecked)</h2>
+				<DisabledUnchecked />
+			</section>
+			<section>
+				<h2 className="text-xl font-semibold mb-4">7. All States Grid</h2>
+				<AllStatesGrid />
+			</section>
+		</div>
+	);
+}

package/src/ui/switch/switch.test.tsx

@@ -0,0 +1,243 @@
+/**
+ * @file switch.test.tsx
+ *
+ * Comprehensive test suite for the MD3 Expressive Switch component.
+ * Tests cover: rendering, controlled state, disabled, accessibility,
+ * and keyboard interaction.
+ */
+
+import { cleanup, fireEvent, render, screen } from "@testing-library/react";
+import * as React from "react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { Switch } from "./switch";
+
+afterEach(cleanup);
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Rendering
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("Switch — Rendering", () => {
+	it("renders unchecked by default", () => {
+		const onCheckedChange = vi.fn();
+		render(
+			<Switch
+				checked={false}
+				onCheckedChange={onCheckedChange}
+				ariaLabel="Test switch"
+			/>,
+		);
+		const toggle = screen.getByRole("switch", { name: "Test switch" });
+		expect(toggle).toHaveAttribute("aria-checked", "false");
+	});
+
+	it("renders checked when checked=true", () => {
+		const onCheckedChange = vi.fn();
+		render(
+			<Switch
+				checked={true}
+				onCheckedChange={onCheckedChange}
+				ariaLabel="Test switch"
+			/>,
+		);
+		const toggle = screen.getByRole("switch", { name: "Test switch" });
+		expect(toggle).toHaveAttribute("aria-checked", "true");
+	});
+
+	it("renders with label text", () => {
+		const onCheckedChange = vi.fn();
+		render(
+			<Switch
+				checked={false}
+				onCheckedChange={onCheckedChange}
+				label="Notifications"
+			/>,
+		);
+		expect(screen.getByText("Notifications")).toBeInTheDocument();
+		// Label should be associated with the switch
+		const toggle = screen.getByRole("switch", { name: "Notifications" });
+		expect(toggle).toBeInTheDocument();
+	});
+
+	it("applies custom className to the button (when no label)", () => {
+		const onCheckedChange = vi.fn();
+		render(
+			<Switch
+				checked={false}
+				onCheckedChange={onCheckedChange}
+				ariaLabel="Test"
+				className="custom-class"
+			/>,
+		);
+		const toggle = screen.getByRole("switch");
+		expect(toggle).toHaveClass("custom-class");
+	});
+
+	it("applies custom className to the label wrapper (when label exists)", () => {
+		const onCheckedChange = vi.fn();
+		render(
+			<Switch
+				checked={false}
+				onCheckedChange={onCheckedChange}
+				label="Test Label"
+				className="wrapper-class"
+			/>,
+		);
+		const label = screen.getByText("Test Label").closest("label");
+		expect(label).toHaveClass("wrapper-class");
+	});
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Interaction
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("Switch — Interaction", () => {
+	it("calls onCheckedChange with true when unchecked switch is clicked", () => {
+		const onCheckedChange = vi.fn();
+		render(
+			<Switch
+				checked={false}
+				onCheckedChange={onCheckedChange}
+				ariaLabel="Test"
+			/>,
+		);
+		const toggle = screen.getByRole("switch");
+		fireEvent.click(toggle);
+		expect(onCheckedChange).toHaveBeenCalledWith(true);
+	});
+
+	it("calls onCheckedChange with false when checked switch is clicked", () => {
+		const onCheckedChange = vi.fn();
+		render(
+			<Switch
+				checked={true}
+				onCheckedChange={onCheckedChange}
+				ariaLabel="Test"
+			/>,
+		);
+		const toggle = screen.getByRole("switch");
+		fireEvent.click(toggle);
+		expect(onCheckedChange).toHaveBeenCalledWith(false);
+	});
+
+	it("does not call onCheckedChange when disabled", () => {
+		const onCheckedChange = vi.fn();
+		render(
+			<Switch
+				checked={false}
+				onCheckedChange={onCheckedChange}
+				disabled
+				ariaLabel="Test"
+			/>,
+		);
+		const toggle = screen.getByRole("switch");
+		fireEvent.click(toggle);
+		expect(onCheckedChange).not.toHaveBeenCalled();
+	});
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Accessibility
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("Switch — Accessibility", () => {
+	it("has role='switch'", () => {
+		render(
+			<Switch checked={false} onCheckedChange={() => {}} ariaLabel="Test" />,
+		);
+		expect(screen.getByRole("switch")).toBeInTheDocument();
+	});
+
+	it("has correct aria-checked state", () => {
+		const { rerender } = render(
+			<Switch checked={false} onCheckedChange={() => {}} ariaLabel="Test" />,
+		);
+		expect(screen.getByRole("switch")).toHaveAttribute("aria-checked", "false");
+
+		rerender(
+			<Switch checked={true} onCheckedChange={() => {}} ariaLabel="Test" />,
+		);
+		expect(screen.getByRole("switch")).toHaveAttribute("aria-checked", "true");
+	});
+
+	it("has aria-disabled=true when disabled=true", () => {
+		render(
+			<Switch
+				disabled
+				checked={false}
+				onCheckedChange={() => {}}
+				ariaLabel="Test"
+			/>,
+		);
+		expect(screen.getByRole("switch")).toHaveAttribute("aria-disabled", "true");
+	});
+
+	it("forwards ref to the button element", () => {
+		const ref = React.createRef<HTMLButtonElement>();
+		render(
+			<Switch
+				ref={ref}
+				checked={false}
+				onCheckedChange={() => {}}
+				ariaLabel="Test"
+			/>,
+		);
+		expect(ref.current).toBeInstanceOf(HTMLButtonElement);
+	});
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Keyboard Interaction
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("Switch — Keyboard Interaction", () => {
+	it("toggles on Space key press", () => {
+		const onCheckedChange = vi.fn();
+		render(
+			<Switch
+				checked={false}
+				onCheckedChange={onCheckedChange}
+				ariaLabel="Space test"
+			/>,
+		);
+		const toggle = screen.getByRole("switch");
+		toggle.focus();
+		fireEvent.keyDown(toggle, { key: " ", code: "Space" });
+		expect(onCheckedChange).toHaveBeenCalledWith(true);
+	});
+
+	it("toggles on Enter key press", () => {
+		const onCheckedChange = vi.fn();
+		render(
+			<Switch
+				checked={false}
+				onCheckedChange={onCheckedChange}
+				ariaLabel="Enter test"
+			/>,
+		);
+		const toggle = screen.getByRole("switch");
+		toggle.focus();
+		fireEvent.keyDown(toggle, { key: "Enter", code: "Enter" });
+		expect(onCheckedChange).toHaveBeenCalledWith(true);
+	});
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Visual Props
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe("Switch — Visual Props", () => {
+	it("renders thumbContent when provided", () => {
+		render(
+			<Switch
+				checked={true}
+				onCheckedChange={() => {}}
+				thumbContent={<span data-testid="custom-icon">✓</span>}
+				icons={true}
+				ariaLabel="Icon test"
+			/>,
+		);
+		expect(screen.getByTestId("custom-icon")).toBeInTheDocument();
+	});
+});

package/src/ui/switch/switch.tokens.ts

@@ -0,0 +1,89 @@
+/**
+ * @file switch.tokens.ts
+ * MD3 Expressive Switch — Design tokens ported from SwitchTokens.kt.
+ * All dimensional values are in px (dp equivalent for web).
+ * @see docs/m3/switch/SwitchTokens.kt
+ */
+
+/**
+ * Design tokens for the MD3 Expressive Switch component.
+ *
+ * Maps directly from `SwitchTokens.kt` (v0_210) to CSS/JS values.
+ * Use these as the single source of truth for sizing and opacity.
+ *
+ * Color tokens are NOT included here — they reference CSS custom properties
+ * from the project's MD3 theme system (`--md-sys-color-*`).
+ */
+export const SwitchTokens = {
+	// ── Track ─────────────────────────────────────────────────────────────────
+	/** SwitchTokens.TrackWidth = 52dp */
+	trackWidth: 52,
+	/** SwitchTokens.TrackHeight = 32dp */
+	trackHeight: 32,
+	/** SwitchTokens.TrackOutlineWidth = 2dp */
+	trackOutlineWidth: 2,
+
+	// ── Handle (Thumb) ────────────────────────────────────────────────────────
+	/** SwitchTokens.SelectedHandleWidth/Height = 24dp */
+	selectedHandleSize: 24,
+	/** SwitchTokens.UnselectedHandleWidth/Height = 16dp */
+	unselectedHandleSize: 16,
+	/** SwitchTokens.IconHandleWidth/Height = 24dp (when thumb has icon content) */
+	iconHandleSize: 24,
+	/** SwitchTokens.PressedHandleWidth/Height = 28dp */
+	pressedHandleSize: 28,
+
+	// ── State Layer ───────────────────────────────────────────────────────────
+	/** SwitchTokens.StateLayerSize = 40dp */
+	stateLayerSize: 40,
+
+	// ── Icon ──────────────────────────────────────────────────────────────────
+	/** SwitchTokens.SelectedIconSize / UnselectedIconSize = 16dp */
+	iconSize: 16,
+
+	// ── Opacity (disabled states) ─────────────────────────────────────────────
+	/** SwitchTokens.DisabledTrackOpacity = 0.12 */
+	disabledTrackOpacity: 0.12,
+	/** SwitchTokens.DisabledSelectedHandleOpacity = 1.0 */
+	disabledSelectedHandleOpacity: 1.0,
+	/** SwitchTokens.DisabledUnselectedHandleOpacity = 0.38 */
+	disabledUnselectedHandleOpacity: 0.38,
+	/** SwitchTokens.DisabledSelectedIconOpacity = 0.38 */
+	disabledSelectedIconOpacity: 0.38,
+	/** SwitchTokens.DisabledUnselectedIconOpacity = 0.38 */
+	disabledUnselectedIconOpacity: 0.38,
+} as const;
+
+// ── MD3 Color token references (CSS custom properties) ────────────────────────
+
+/**
+ * CSS custom property references for Switch colors.
+ * These map to the project's `--md-sys-color-*` tokens in `colors.css`.
+ *
+ * DO NOT hardcode hex values — always use these references so the
+ * component automatically adapts to light/dark theme switching.
+ */
+export const SwitchColors = {
+	// Track
+	checkedTrack: "var(--md-sys-color-primary)",
+	uncheckedTrack: "var(--md-sys-color-surface-container-highest)",
+	uncheckedTrackOutline: "var(--md-sys-color-outline)",
+
+	// Thumb
+	checkedThumb: "var(--md-sys-color-on-primary)",
+	uncheckedThumb: "var(--md-sys-color-outline)",
+	hoverCheckedThumb: "var(--md-sys-color-primary-container)",
+	hoverUncheckedThumb: "var(--md-sys-color-on-surface-variant)",
+	disabledCheckedThumb: "var(--md-sys-color-surface)",
+
+	// Icon
+	checkedIcon: "var(--md-sys-color-on-primary-container)",
+	uncheckedIcon: "var(--md-sys-color-surface-container-highest)",
+
+	// State layer
+	checkedStateLayer: "var(--md-sys-color-primary)",
+	uncheckedStateLayer: "var(--md-sys-color-on-surface)",
+
+	// Focus indicator
+	focusIndicator: "var(--md-sys-color-secondary)",
+} as const;