@bug-on/md3-react 2.0.3 → 3.0.0

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

@@ -0,0 +1,180 @@
+/**
+ * @file text-field.types.ts
+ * TypeScript interfaces and types for TextField MD3 Expressive component.
+ * @see https://m3.material.io/components/text-fields/overview
+ */
+
+import type * as React from "react";
+
+// ─── Variant & Input Types ───────────────────────────────────────────────────
+
+export type TextFieldVariant = "filled" | "outlined";
+
+export type TextFieldInputType =
+	| "text"
+	| "email"
+	| "number"
+	| "password"
+	| "search"
+	| "tel"
+	| "url"
+	| "textarea";
+
+export type TextFieldTrailingIconMode =
+	| "none"
+	| "clear"
+	| "password-toggle"
+	| "custom";
+
+// ─── Imperative Handle ───────────────────────────────────────────────────────
+
+/**
+ * Imperative handle exposed via forwardRef.
+ * Allows parent components to programmatically control the text field.
+ */
+export interface TextFieldHandle {
+	/** Focuses the input element. */
+	focus(): void;
+	/** Blurs the input element. */
+	blur(): void;
+	/** Selects all text in the input. */
+	select(): void;
+	/** Clears the current value and fires onChange with empty string. */
+	clear(): void;
+	/** Sets a custom validation message on the native input. */
+	setCustomValidity(message: string): void;
+	/** Returns true if the input is valid. Does not show validation UI. */
+	checkValidity(): boolean;
+	/** Returns true if the input is valid. Shows validation UI if invalid. */
+	reportValidity(): boolean;
+	/** Returns the current value string. */
+	getValue(): string;
+	/** Returns the underlying input or textarea element. */
+	getInputElement(): HTMLInputElement | HTMLTextAreaElement | null;
+}
+
+// ─── Main Props ──────────────────────────────────────────────────────────────
+
+export interface TextFieldProps {
+	// ── Core ──────────────────────────────────────────────────────────────────
+	/** Filled or outlined variant. @default 'filled' */
+	variant?: TextFieldVariant;
+	/** Floating label text. Also used as accessible name when no aria-label is set. */
+	label?: string;
+	/** Controlled value. Use with onChange for controlled mode. */
+	value?: string;
+	/** Initial value for uncontrolled mode. */
+	defaultValue?: string;
+	/** Fires when value changes. Receives new value string and native event. */
+	onChange?: (
+		value: string,
+		event: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>,
+	) => void;
+
+	// ── Input config ──────────────────────────────────────────────────────────
+	/** Input type. Use 'textarea' for multi-line input. @default 'text' */
+	type?: TextFieldInputType;
+	/** Placeholder text — shown only when no label OR label is floated. */
+	placeholder?: string;
+	name?: string;
+	id?: string;
+	autoComplete?: string;
+	inputMode?: React.HTMLAttributes<HTMLInputElement>["inputMode"];
+	/** Number of rows for textarea type. @default 2 */
+	rows?: number;
+	/** Number of columns for textarea type. @default 20 */
+	cols?: number;
+	/** Whether the textarea should automatically resize to fit its content. @default false */
+	autoResize?: boolean;
+	/** Maximum number of rows when autoResize is true. */
+	maxRows?: number;
+	/** CSS direction override for input text. */
+	textDirection?: "ltr" | "rtl" | "";
+
+	// ── Validation ────────────────────────────────────────────────────────────
+	/** Marks field as required. Shows asterisk on label. */
+	required?: boolean;
+	/** Hides the asterisk even when required=true. */
+	noAsterisk?: boolean;
+	/** Manual error override — forces error visual state. */
+	error?: boolean;
+	/** Error message shown below the field (replaces supportingText). */
+	errorText?: string;
+	minLength?: number;
+	/** When set, enables character counter display. */
+	maxLength?: number;
+	min?: string;
+	max?: string;
+	step?: string;
+	pattern?: string;
+	/** For type="email" — allows multiple email addresses. */
+	multiple?: boolean;
+
+	// ── Supporting text ───────────────────────────────────────────────────────
+	/** Helper text shown below the field. Replaced by errorText when in error state. */
+	supportingText?: string;
+
+	// ── Decorators ────────────────────────────────────────────────────────────
+	/** Text displayed before the input value (e.g., "$"). */
+	prefixText?: string;
+	/** Text displayed after the input value (e.g., ".00"). */
+	suffixText?: string;
+	/** Icon node for the leading slot. Should be 24×24px. */
+	leadingIcon?: React.ReactNode;
+	/** Custom trailing icon node. Used when trailingIconMode='custom'. */
+	trailingIcon?: React.ReactNode;
+
+	// ── Trailing icon mode ────────────────────────────────────────────────────
+	/**
+	 * Built-in trailing icon behavior.
+	 * - 'none' — no trailing icon
+	 * - 'clear' — ✕ button, clears value when clicked
+	 * - 'password-toggle' — eye icon, toggles password visibility
+	 * - 'custom' — uses trailingIcon prop
+	 * @default 'none'
+	 */
+	trailingIconMode?: TextFieldTrailingIconMode;
+
+	// ── States ────────────────────────────────────────────────────────────────
+	disabled?: boolean;
+	readOnly?: boolean;
+	/** Hides spinner arrows on type="number". */
+	noSpinner?: boolean;
+
+	// ── Form integration ──────────────────────────────────────────────────────
+	form?: string;
+
+	// ── Accessibility ─────────────────────────────────────────────────────────
+	"aria-label"?: string;
+	"aria-describedby"?: string;
+	"aria-labelledby"?: string;
+
+	// ── Layout ────────────────────────────────────────────────────────────────
+	/** Extra class applied to the root wrapper element. */
+	className?: string;
+	/** Makes the component fill its container width. */
+	fullWidth?: boolean;
+	/** Dense variant — reduced height (48px instead of 56px). */
+	dense?: boolean;
+
+	// ── Callbacks ─────────────────────────────────────────────────────────────
+	onFocus?: React.FocusEventHandler<HTMLInputElement | HTMLTextAreaElement>;
+	onBlur?: React.FocusEventHandler<HTMLInputElement | HTMLTextAreaElement>;
+	onKeyDown?: React.KeyboardEventHandler<
+		HTMLInputElement | HTMLTextAreaElement
+	>;
+	onKeyUp?: React.KeyboardEventHandler<HTMLInputElement | HTMLTextAreaElement>;
+
+	// ── Ref ───────────────────────────────────────────────────────────────────
+	ref?: React.Ref<TextFieldHandle>;
+
+	// ── ScrollArea ────────────────────────────────────────────────────────────
+	/**
+	 * Controls when the scrollbars are visible when type="textarea".
+	 * - `hover`: Show on hover (default)
+	 * - `scroll`: Show only while scrolling
+	 * - `always`: Always visible
+	 * - `none`: Never visible
+	 */
+	scrollAreaType?: "hover" | "scroll" | "always" | "none";
+}

package/src/ui/theme-provider/index.tsx

@@ -0,0 +1,190 @@
+"use client";
+
+import { domMax, LazyMotion } from "motion/react";
+import {
+	createContext,
+	type ReactNode,
+	useContext,
+	useEffect,
+	useMemo,
+	useState,
+} from "react";
+import { applyTheme, type ThemeMode } from "../../lib/theme-utils";
+import {
+	SnackbarContext,
+	SnackbarHost,
+	useSnackbarState,
+} from "../snackbar/snackbar";
+import { Typography, TypographyContext } from "../typography/typography";
+import {
+	type FontVariationAxes,
+	TypographyTokens,
+} from "../typography/typography-tokens";
+
+// ─── Theme Context ─────────────────────────────────────────────────────────────
+
+interface ThemeContextValue {
+	sourceColor: string;
+	setSourceColor: (color: string) => void;
+	mode: ThemeMode;
+	setMode: (mode: ThemeMode) => void;
+}
+
+const ThemeContext = createContext<ThemeContextValue | undefined>(undefined);
+
+const STORAGE_KEY_COLOR = "md3-source-color";
+const STORAGE_KEY_MODE = "md3-theme-mode";
+
+// ─── Singleton defaults (computed once) ───────────────────────────────────────
+
+const defaultTokens = new TypographyTokens();
+const defaultTypography = new Typography(defaultTokens);
+
+// ─── MD3ThemeProvider ──────────────────────────────────────────────────────────
+
+export interface MD3ThemeProviderProps {
+	children: ReactNode;
+	// ── Theme ─────────────────────────────────────────────────────────────────
+	sourceColor?: string;
+	defaultMode?: ThemeMode;
+	persistToLocalStorage?: boolean;
+	// ── Typography ────────────────────────────────────────────────────────────
+	/**
+	 * A fully custom `Typography` instance.
+	 * When provided, `fontFamily` and `fontVariationAxes` are ignored.
+	 */
+	typography?: Typography;
+	/**
+	 * Override the CSS `font-family` for all typography styles.
+	 * Ignored when `typography` prop is provided.
+	 * @example "'Inter', sans-serif"
+	 */
+	fontFamily?: string;
+	/**
+	 * Variable font axes applied globally via `font-variation-settings`.
+	 * Merged on top of defaults (`ROND: 100`). Ignored when `typography` is provided.
+	 * @example { ROND: 50 }
+	 */
+	fontVariationAxes?: FontVariationAxes;
+	// ── Snackbar ──────────────────────────────────────────────────────────────
+	/**
+	 * When `true`, mounts `SnackbarHost` inside the provider and exposes
+	 * `useSnackbar()` to all descendants — no separate `<SnackbarProvider>` needed.
+	 *
+	 * Opt-in, default `false`. For advanced usage (e.g., scoped snackbars or
+	 * custom host positioning), keep this `false` and use `<SnackbarProvider>`
+	 * or `<SnackbarHost>` directly.
+	 *
+	 * @default false
+	 */
+	enableSnackbar?: boolean;
+}
+
+export function MD3ThemeProvider({
+	children,
+	sourceColor: initialSourceColor = "#6750A4",
+	defaultMode = "light",
+	persistToLocalStorage = false,
+	typography: typographyProp,
+	fontFamily,
+	fontVariationAxes,
+	enableSnackbar = false,
+}: MD3ThemeProviderProps) {
+	// ── Theme state ──────────────────────────────────────────────────────────
+	const [sourceColor, setSourceColor] = useState(initialSourceColor);
+	const [mode, setMode] = useState<ThemeMode>(defaultMode);
+	const [isHydrated, setIsHydrated] = useState(!persistToLocalStorage);
+
+	useEffect(() => {
+		if (!persistToLocalStorage) return;
+
+		const savedColor = localStorage.getItem(STORAGE_KEY_COLOR);
+		const savedMode = localStorage.getItem(
+			STORAGE_KEY_MODE,
+		) as ThemeMode | null;
+
+		if (savedColor) setSourceColor(savedColor);
+		if (savedMode === "light" || savedMode === "dark") setMode(savedMode);
+
+		setIsHydrated(true);
+	}, [persistToLocalStorage]);
+
+	useEffect(() => {
+		if (!isHydrated) return;
+
+		applyTheme(sourceColor, mode);
+
+		if (persistToLocalStorage) {
+			localStorage.setItem(STORAGE_KEY_COLOR, sourceColor);
+			localStorage.setItem(STORAGE_KEY_MODE, mode);
+		}
+	}, [sourceColor, mode, persistToLocalStorage, isHydrated]);
+
+	const themeValue = useMemo<ThemeContextValue>(
+		() => ({ sourceColor, setSourceColor, mode, setMode }),
+		[sourceColor, mode],
+	);
+
+	// ── Typography value ─────────────────────────────────────────────────────
+	const typographyValue = useMemo<Typography>(() => {
+		if (typographyProp) return typographyProp;
+		if (fontFamily ?? fontVariationAxes) {
+			return new Typography(
+				new TypographyTokens({ fontFamily, fontVariationAxes }),
+			);
+		}
+		return defaultTypography;
+	}, [typographyProp, fontFamily, fontVariationAxes]);
+
+	// ── Snackbar — mounted as isolated subtree so hook only allocates when needed
+
+	return (
+		<LazyMotion features={domMax}>
+			<ThemeContext.Provider value={themeValue}>
+				<TypographyContext.Provider value={typographyValue}>
+					{enableSnackbar ? (
+						<SnackbarMountedProvider>{children}</SnackbarMountedProvider>
+					) : (
+						children
+					)}
+				</TypographyContext.Provider>
+			</ThemeContext.Provider>
+		</LazyMotion>
+	);
+}
+
+// ─── SnackbarMountedProvider ──────────────────────────────────────────────────
+
+/**
+ * Internal helper component — renders only when `enableSnackbar={true}`.
+ * Isolates `useSnackbarState` so the hook is never allocated unnecessarily.
+ */
+function SnackbarMountedProvider({ children }: { children: ReactNode }) {
+	const state = useSnackbarState();
+	const contextValue = useMemo(
+		() => ({ showSnackbar: state.showSnackbar }),
+		[state.showSnackbar],
+	);
+
+	return (
+		<SnackbarContext.Provider value={contextValue}>
+			{children}
+			<SnackbarHost state={state} />
+		</SnackbarContext.Provider>
+	);
+}
+
+// ─── Hooks ────────────────────────────────────────────────────────────────────
+
+export function useTheme(): ThemeContextValue {
+	const context = useContext(ThemeContext);
+	if (!context) {
+		throw new Error("useTheme must be used within <MD3ThemeProvider>.");
+	}
+	return context;
+}
+
+export function useThemeMode(): Pick<ThemeContextValue, "mode" | "setMode"> {
+	const { mode, setMode } = useTheme();
+	return { mode, setMode };
+}

package/src/ui/toc.test.tsx

@@ -0,0 +1,108 @@
+import {
+	act,
+	fireEvent,
+	render,
+	screen,
+	waitFor,
+} from "@testing-library/react";
+import { beforeEach, describe, expect, it, type Mock, vi } from "vitest";
+
+// Mock implementation
+let mockObserve: Mock<(element: Element) => void>;
+let mockDisconnect: Mock<() => void>;
+let observerCallback: IntersectionObserverCallback | undefined;
+
+class MockObserver implements IntersectionObserver {
+	readonly root: Element | null = null;
+	readonly rootMargin: string = "";
+	readonly thresholds: ReadonlyArray<number> = [];
+
+	constructor(callback: IntersectionObserverCallback) {
+		observerCallback = callback;
+	}
+
+	observe = (element: Element) => mockObserve(element);
+	disconnect = () => mockDisconnect();
+	unobserve = vi.fn();
+	takeRecords = vi.fn(() => []);
+}
+
+vi.stubGlobal("IntersectionObserver", MockObserver);
+
+import { TableOfContents } from "./toc";
+
+const mockItems = [
+	{ id: "section-1", label: "Section 1" },
+	{ id: "section-2", label: "Section 2" },
+];
+
+describe("TableOfContents", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+		mockObserve = vi.fn();
+		mockDisconnect = vi.fn();
+		window.HTMLElement.prototype.scrollIntoView = vi.fn();
+	});
+
+	it("renders correctly", () => {
+		render(<TableOfContents items={mockItems} />);
+		expect(screen.getByText("On this page")).toBeInTheDocument();
+		expect(screen.getByText("Section 1")).toBeInTheDocument();
+	});
+
+	it("handles active state change", async () => {
+		render(
+			<>
+				<div id="section-1">Content 1</div>
+				<div id="section-2">Content 2</div>
+				<TableOfContents items={mockItems} />
+			</>,
+		);
+
+		const firstLink = screen.getByText("Section 1");
+
+		// Trigger observer inside act to handle state update
+		if (observerCallback) {
+			await act(async () => {
+				const mockEntry = {
+					isIntersecting: true,
+					target: { id: "section-1" } as unknown as Element,
+					time: Date.now(),
+					intersectionRatio: 1,
+					boundingClientRect: {} as DOMRectReadOnly,
+					intersectionRect: {} as DOMRectReadOnly,
+					rootBounds: null,
+				} as IntersectionObserverEntry;
+
+				observerCallback?.([mockEntry], {} as IntersectionObserver);
+			});
+		}
+
+		await waitFor(() => {
+			expect(firstLink).toHaveClass("text-m3-primary");
+			expect(firstLink).toHaveClass("font-bold");
+		});
+	});
+
+	it("handles click navigation", () => {
+		render(
+			<>
+				<div id="section-1">Content 1</div>
+				<TableOfContents items={mockItems} />
+			</>,
+		);
+
+		const firstLink = screen.getByText("Section 1");
+		const target = document.getElementById("section-1");
+
+		if (target) {
+			const scrollSpy = vi.fn();
+			target.scrollIntoView = scrollSpy;
+			fireEvent.click(firstLink);
+			expect(scrollSpy).toHaveBeenCalledWith({
+				behavior: "smooth",
+				block: "start",
+			});
+		}
+	});
+});

package/src/ui/toc.tsx

@@ -0,0 +1,172 @@
+/**
+ * @file toc.tsx
+ *
+ * Table of Contents component for long-form documentation pages.
+ *
+ * Uses `IntersectionObserver` to track which section heading is currently in the
+ * viewport and highlights the corresponding link. Smooth-scrolls to the target
+ * when a link is clicked (respecting the browser's `prefers-reduced-motion`
+ * media query via the native `scrollIntoView` API).
+ *
+ * @remarks
+ * - SSR-safe: `IntersectionObserver` usage is guarded by a `typeof` check.
+ * - The observer `rootMargin` is tuned for documentation layout with a fixed header
+ *   (~100px) and early deactivation (~80% from bottom) so the active item changes
+ *   before the section scrolls off-screen.
+ */
+
+import type React from "react";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { cn } from "../lib/utils";
+import { ScrollArea, type ScrollAreaProps } from "./scroll-area";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * A single entry in the Table of Contents.
+ *
+ * @example
+ * ```ts
+ * const items: ToCItem[] = [
+ *   { id: "installation", label: "Installation" },
+ *   { id: "usage", label: "Usage" },
+ * ];
+ * ```
+ */
+export interface ToCItem {
+	/** The DOM `id` attribute of the corresponding section heading. */
+	id: string;
+	/** Human-readable label shown in the ToC. */
+	label: string;
+}
+
+/**
+ * Props for the `TableOfContents` component.
+ */
+export interface TableOfContentsProps {
+	/**
+	 * Ordered list of section items to display.
+	 * Each item must have a matching DOM element with the same `id`.
+	 */
+	items: ToCItem[];
+	/**
+	 * Additional CSS classes applied to the root `<nav>` element.
+	 * Use this to control positioning (e.g. sticky, fixed) from the consumer.
+	 */
+	className?: string;
+	/**
+	 * Configuration for the internal ScrollArea.
+	 * @default { type: "hover" }
+	 */
+	scrollAreaProps?: Omit<ScrollAreaProps, "children">;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Component
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Table of Contents sidebar component.
+ *
+ * Renders a `<nav>` sidebar with links to page sections. Tracks the active
+ * section using `IntersectionObserver` and applies active styles to the
+ * current link.
+ *
+ * @remarks
+ * - Visible only on `xl` screens (`hidden xl:block` — sticky sidebar).
+ * - The `aria-current` attribute is set on the active link for screen readers.
+ * - Click scroll is smooth: `scrollIntoView({ behavior: "smooth" })`.
+ *
+ * @example
+ * ```tsx
+ * const toc: ToCItem[] = [
+ *   { id: "overview", label: "Overview" },
+ *   { id: "props", label: "Props" },
+ *   { id: "examples", label: "Examples" },
+ * ];
+ *
+ * <TableOfContents items={toc} />
+ * ```
+ *
+ * @see https://m3.material.io/foundations/content-design/navigation
+ */
+export function TableOfContents({
+	items,
+	className,
+	scrollAreaProps,
+}: TableOfContentsProps) {
+	const [activeId, setActiveId] = useState("");
+
+	// Stabilize dependency — re-subscribe only when the item IDs actually change.
+	const itemIds = useMemo(() => items.map((i) => i.id), [items]);
+
+	useEffect(() => {
+		// SSR guard: IntersectionObserver is not available in Node.js.
+		if (typeof IntersectionObserver === "undefined") return;
+
+		const observer = new IntersectionObserver(
+			(entries) => {
+				for (const entry of entries) {
+					if (entry.isIntersecting) setActiveId(entry.target.id);
+				}
+			},
+			// rootMargin: top offset ~100px (fixed header), bottom -80% (early switch)
+			{ rootMargin: "-100px 0% -80% 0%" },
+		);
+
+		for (const id of itemIds) {
+			const el = document.getElementById(id);
+			if (el) observer.observe(el);
+		}
+
+		return () => observer.disconnect();
+	}, [itemIds]);
+
+	const handleClick = useCallback(
+		(e: React.MouseEvent<HTMLAnchorElement>, id: string) => {
+			e.preventDefault();
+			document
+				.getElementById(id)
+				?.scrollIntoView({ behavior: "smooth", block: "start" });
+		},
+		[],
+	);
+
+	return (
+		<nav
+			aria-label="On this page"
+			className={cn("pl-6 flex flex-col h-full", className)}
+		>
+			<h4 className="text-xs font-bold text-m3-on-surface-variant uppercase tracking-widest mb-4 sm:hidden lg:block">
+				On this page
+			</h4>
+			<ScrollArea
+				type="hover"
+				{...scrollAreaProps}
+				className={cn("flex-1 min-h-0", scrollAreaProps?.className)}
+			>
+				<ul className="space-y-4 pr-4">
+					{items.map((item) => (
+						<li key={item.id}>
+							<a
+								href={`#${item.id}`}
+								onClick={(e) => handleClick(e, item.id)}
+								aria-current={activeId === item.id ? "true" : undefined}
+								className={cn(
+									"text-sm transition-colors hover:text-m3-primary block",
+									activeId === item.id
+										? "text-m3-primary font-bold"
+										: "text-m3-on-surface-variant font-medium",
+								)}
+							>
+								{item.label}
+							</a>
+						</li>
+					))}
+				</ul>
+			</ScrollArea>
+		</nav>
+	);
+}