@bug-on/md3-react 2.0.2 → 3.0.0

package/src/ui/progress-indicator/linear.tsx

@@ -0,0 +1,143 @@
+import { domMax, LazyMotion } from "motion/react";
+import * as React from "react";
+import { cn } from "../../lib/utils";
+import { useMergedRef } from "./hooks";
+import { FlatLinearTrack } from "./linear-flat";
+import { WavyLinearTrack } from "./linear-wavy";
+import type { LinearProgressProps } from "./types";
+
+export const LinearProgress = React.forwardRef<
+	HTMLDivElement,
+	LinearProgressProps
+>(
+	(
+		{
+			value,
+			shape = "flat",
+			trackShape,
+			trackHeight = 4,
+			amplitude,
+			wavelength = 40,
+			indeterminateWavelength = 20,
+			waveSpeed = 1,
+			crawlerSpeed = 1,
+			determinateAnimation = "md3",
+			indeterminateAnimation = "continuous",
+			gapSize = 4,
+			showStopIndicator = "auto",
+			color,
+			trackColor,
+			className,
+			"aria-label": ariaLabel,
+			...restProps
+		},
+		ref,
+	) => {
+		const isDeterminate = value !== undefined;
+		const clampedValue = isDeterminate ? Math.min(100, Math.max(0, value)) : 0;
+
+		const containerRef = React.useRef<HTMLDivElement>(null);
+		const mergedRef = useMergedRef(ref, containerRef);
+		const [isRtl, setIsRtl] = React.useState(false);
+
+		React.useEffect(() => {
+			if (containerRef.current) {
+				const dir = getComputedStyle(containerRef.current).direction;
+				setIsRtl(dir === "rtl");
+			}
+		}, []);
+
+		const isWavy = shape === "wavy";
+		const resolvedTrackShape = trackShape ?? shape;
+
+		const effectiveAmplitude = React.useMemo(() => amplitude ?? 3, [amplitude]);
+		const svgHeight = React.useMemo(
+			() => (isWavy ? trackHeight + effectiveAmplitude * 2 : trackHeight),
+			[isWavy, trackHeight, effectiveAmplitude],
+		);
+
+		const shouldShowStop = React.useMemo(
+			() =>
+				isDeterminate &&
+				resolvedTrackShape === "flat" &&
+				(showStopIndicator === true ||
+					(showStopIndicator === "auto" && isDeterminate)),
+			[isDeterminate, resolvedTrackShape, showStopIndicator],
+		);
+
+		const stopSize = React.useMemo(
+			() => Math.max(2, trackHeight > 4 ? 4 : trackHeight / 2),
+			[trackHeight],
+		);
+
+		const stopOffset = (trackHeight - stopSize) / 2;
+
+		const activeColor = color || "var(--md-sys-color-indicator-active)";
+		const bgTrackColor = trackColor || "var(--md-sys-color-indicator-track)";
+
+		return (
+			<LazyMotion features={domMax} strict>
+				<div
+					ref={mergedRef}
+					role="progressbar"
+					aria-label={ariaLabel}
+					aria-valuenow={isDeterminate ? clampedValue : undefined}
+					aria-valuemin={0}
+					aria-valuemax={100}
+					className={cn(
+						"relative flex w-full flex-col justify-center",
+						className,
+					)}
+					style={{ height: svgHeight }}
+					{...restProps}
+				>
+					{isWavy ? (
+						<WavyLinearTrack
+							trackHeight={trackHeight}
+							svgHeight={svgHeight}
+							amplitude={effectiveAmplitude}
+							wavelength={wavelength}
+							indeterminateWavelength={indeterminateWavelength}
+							activeColor={activeColor}
+							trackColor={bgTrackColor}
+							value={isDeterminate ? clampedValue : undefined}
+							isRtl={isRtl}
+							gapSize={gapSize}
+							waveSpeed={waveSpeed}
+							crawlerSpeed={crawlerSpeed}
+							determinateAnimation={determinateAnimation}
+							indeterminateAnimation={indeterminateAnimation}
+							trackShape={resolvedTrackShape}
+						/>
+					) : (
+						<FlatLinearTrack
+							trackHeight={trackHeight}
+							activeColor={activeColor}
+							trackColor={bgTrackColor}
+							value={isDeterminate ? clampedValue : undefined}
+							isRtl={isRtl}
+							gapSize={gapSize}
+							crawlerSpeed={crawlerSpeed}
+						/>
+					)}
+
+					{shouldShowStop && (
+						<div
+							aria-hidden="true"
+							className="absolute rounded-full"
+							style={{
+								width: stopSize,
+								height: stopSize,
+								backgroundColor: "var(--md-sys-color-indicator-stop)",
+								top: svgHeight / 2 - stopSize / 2,
+								...(isRtl ? { left: stopOffset } : { right: stopOffset }),
+							}}
+						/>
+					)}
+				</div>
+			</LazyMotion>
+		);
+	},
+);
+
+LinearProgress.displayName = "LinearProgress";

package/src/ui/progress-indicator/types.ts

@@ -0,0 +1,158 @@
+import type * as React from "react";
+
+export interface ProgressBaseProps
+	extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+	/**
+	 * Giá trị phần trăm tiến trình hiện tại (từ 0 đến 100).
+	 * Nếu truyền giá trị này, tiến trình sẽ hiển thị ở trạng thái Determinate.
+	 * Nếu bỏ trống (undefined), tiến trình sẽ tự động ở trạng thái Indeterminate.
+	 *
+	 * @example
+	 * ```tsx
+	 * <ProgressIndicator value={45} aria-label="Loading profile..." />
+	 * ```
+	 */
+	value?: number;
+	/**
+	 * Nhan đề mô tả mục đích của thanh tiến trình dành cho screen readers (bắt buộc).
+	 */
+	"aria-label": string;
+	/**
+	 * Độ dày của track (đường nền) của thanh tiến trình (đơn vị: px).
+	 * - Với Linear: là chiều cao của thanh.
+	 * - Với Circular: là độ dày của viền hình tròn.
+	 *
+	 * @example
+	 * trackHeight={8} // Dày hơn bình thường
+	 */
+	trackHeight?: number;
+	/**
+	 * Màu sắc của phần tiến trình (phần đã hoàn thành).
+	 * Mặc định mượn màu `currentColor` của thẻ wrap, để dễ dàng tuỳ biến qua utility class.
+	 *
+	 * @example
+	 * color="var(--md-sys-color-primary)" // Sử dụng custom token
+	 */
+	color?: string;
+	/**
+	 * Màu sắc của thanh nền (phần chưa hoàn thành).
+	 * Mặc định sử dụng màu được tính toán từ bề mặt hoặc transparency để tạo sự tinh tế.
+	 */
+	trackColor?: string;
+}
+
+export interface LinearProgressProps extends ProgressBaseProps {
+	/** Phân loại component sang kiểu dáng Linear (đường thẳng ngang). */
+	variant: "linear";
+	/**
+	 * Hình dáng của vạch tiến trình (phần đã hoàn thành).
+	 * - `flat`: Đường nét liền phẳng (mặc định)
+	 * - `wavy`: Đường lượn sóng động
+	 */
+	shape?: "flat" | "wavy";
+	/**
+	 * Hình dáng của thanh nền chờ (track).
+	 * - `flat`: Đường nét liền phẳng (mặc định)
+	 * - `wavy`: Đường lượn sóng cố định hoặc động
+	 */
+	trackShape?: "flat" | "wavy";
+	/**
+	 * Biên độ sóng (áp dụng khi `shape` hoặc `trackShape` là "wavy").
+	 * Chỉ định độ lượn cao thấp của con sóng.
+	 */
+	amplitude?: number;
+	/**
+	 * Chiều dài một nhịp sóng (áp dụng khi `shape` là "wavy" theo determinate).
+	 * Khoảng cách giữa 2 đỉnh sóng kề nhau.
+	 */
+	wavelength?: number;
+	/**
+	 * Nhịp sóng dành riêng cho trạng thái chạy liên tục (Indeterminate Wavy).
+	 */
+	indeterminateWavelength?: number;
+	/**
+	 * Khoảng hở kết dính giữa cụm vạch đang chạy và thanh nền.
+	 * Cho phép truyền \`0\` để hai thanh chạm sát vào nhau liền mạch.
+	 *
+	 * @example
+	 * ```tsx
+	 * <ProgressIndicator variant="linear" shape="wavy" gapSize={0} /> // Sóng chạm track liền nét
+	 * ```
+	 */
+	gapSize?: number;
+	/**
+	 * Tốc độ dao động vỗ của sóng (Multiplier). Mặc định là \`1\`.
+	 * Tăng giá trị (VD: 1.5, 2) để sóng dao động nhanh hơn.
+	 */
+	waveSpeed?: number;
+	/**
+	 * Tốc độ lướt / cuộn dải màu dọc trên track (Crawler) đối với trạng thái Indeterminate.
+	 * Mặc định là \`1\`.
+	 */
+	crawlerSpeed?: number;
+	/**
+	 * Cấu hình hiệu ứng gợn khi thanh determinate ở mức xấp xỉ mép viền (<= 10% hoặc >= 90%).
+	 * - `md3`: Tự động ép phẳng biên độ sóng thành số 0 một cách mềm mại (Chuẩn Google MD3).
+	 * - `continuous`: Bỏ qua các ràng buộc ép phẳng, con sóng vẫn gợn lấp lóa trên mọi giá trị phần trăm.
+	 *
+	 * @example
+	 * ```tsx
+	 * <ProgressIndicator variant="linear" shape="wavy" determinateAnimation="continuous" />
+	 * ```
+	 */
+	determinateAnimation?: "md3" | "continuous";
+	/**
+	 * Kiểu kịch bản tịnh tiến cho thanh Indeterminate.
+	 * - `md3`: Render 2 vạch song song vọt tới & co giãn mô phỏng vật lý (Chuẩn Google MD3).
+	 * - `continuous`: Vạch không ngắt quãng mà tràn lướt vòng lặp mượt mà.
+	 *
+	 * @example
+	 * ```tsx
+	 * <ProgressIndicator variant="linear" indeterminateAnimation="continuous" />
+	 * ```
+	 */
+	indeterminateAnimation?: "md3" | "continuous";
+	/**
+	 * Bật/tắt dấm chấm điểm báo kết thúc ở cuối track (Stop Indicator).
+	 * - `true`: Luôn thấy một chấm tròn bé xíu ở cuối đường đi
+	 * - `false`: Tắt hoàn toàn
+	 * - `"auto"`: Chấm tròn chỉ hiển thị và hòa trộn khi progress đạt 100%
+	 */
+	showStopIndicator?: boolean | "auto";
+}
+
+export interface CircularProgressProps extends ProgressBaseProps {
+	/** Phân loại component sang kiểu dáng Circular (hình tròn khép kín). */
+	variant: "circular";
+	/**
+	 * Đường kính hiển thị của vòng biểu đồ, đơn vị px.
+	 *
+	 * @example
+	 * ```tsx
+	 * <ProgressIndicator variant="circular" size={48} aria-label="Loading..." />
+	 * ```
+	 */
+	size?: number;
+	/**
+	 * Phong cách nét vẽ của đường viền trong trạng thái trượt.
+	 * - `flat`: Đường nét cứng, vuốt tròn hai đầu stroke.
+	 * - `wavy`: Vệt màu chuyển động rung tạo hình răng cưa/gợn sóng.
+	 */
+	shape?: "flat" | "wavy";
+	/**
+	 * Biên độ gợn của trạng thái `wavy` cho vòng tròn.
+	 */
+	amplitude?: number;
+	/** Bước sóng bao trọn chu vi hình tròn. */
+	wavelength?: number;
+	/** Khoảng hở khe đứt ngang nối đỉnh nét vẽ. */
+	gapSize?: number;
+	/**
+	 * Xoay nhanh hay chậm theo số nhân cho Crawler Circular quay Indeterminate.
+	 */
+	crawlerSpeed?: number;
+}
+
+export type ProgressIndicatorProps =
+	| LinearProgressProps
+	| CircularProgressProps;

package/src/ui/progress-indicator/utils.ts

@@ -0,0 +1,73 @@
+export function easeInOutCubic(x: number): number {
+	return x < 0.5 ? 4 * x * x * x : 1 - (-2 * x + 2) ** 3 / 2;
+}
+
+export function generateWavyCircularPath(
+	center: number,
+	radius: number,
+	amplitude: number,
+	wavelength: number,
+): string {
+	const circumference = 2 * Math.PI * radius;
+	const numWaves = Math.max(
+		3,
+		Math.round(circumference / Math.max(1, wavelength)),
+	);
+	const steps = numWaves * 4;
+	const dt = (2 * Math.PI) / steps;
+
+	const rAt = (t: number) => radius + amplitude * Math.sin(numWaves * t);
+	const drAt = (t: number) => amplitude * numWaves * Math.cos(numWaves * t);
+	const xAt = (t: number) => center + rAt(t) * Math.cos(t);
+	const yAt = (t: number) => center + rAt(t) * Math.sin(t);
+	const dxAt = (t: number) => drAt(t) * Math.cos(t) - rAt(t) * Math.sin(t);
+	const dyAt = (t: number) => drAt(t) * Math.sin(t) + rAt(t) * Math.cos(t);
+
+	let d = "";
+	const tStart = 0;
+
+	for (let i = 0; i < steps; i++) {
+		const t0 = tStart + i * dt;
+		const t1 = tStart + (i + 1) * dt;
+
+		const scale = dt / 3;
+		const cp1x = xAt(t0) + scale * dxAt(t0);
+		const cp1y = yAt(t0) + scale * dyAt(t0);
+		const cp2x = xAt(t1) - scale * dxAt(t1);
+		const cp2y = yAt(t1) - scale * dyAt(t1);
+
+		if (i === 0) d += `M ${xAt(t0).toFixed(2)} ${yAt(t0).toFixed(2)}`;
+		d += ` C ${cp1x.toFixed(2)} ${cp1y.toFixed(2)}, ${cp2x.toFixed(2)} ${cp2y.toFixed(2)}, ${xAt(t1).toFixed(2)} ${yAt(t1).toFixed(2)}`;
+	}
+	d += " Z";
+	return d;
+}
+
+export function getSinePath(
+	startX: number,
+	endX: number,
+	phase: number,
+	wl: number,
+	amp: number,
+) {
+	if (startX >= endX) return "";
+	let d = "";
+	const step = amp === 0 ? Math.max(10, endX - startX) : 1;
+
+	const yStart = Math.sin(((startX + phase) / wl) * 2 * Math.PI) * amp;
+	d += `M ${startX.toFixed(2)} ${yStart.toFixed(2)}`;
+
+	let nextX = Math.ceil(startX / step) * step;
+	if (nextX === startX) nextX += step;
+
+	while (nextX < endX) {
+		const y = Math.sin(((nextX + phase) / wl) * 2 * Math.PI) * amp;
+		d += ` L ${nextX.toFixed(2)} ${y.toFixed(2)}`;
+		nextX += step;
+	}
+
+	const yEnd = Math.sin(((endX + phase) / wl) * 2 * Math.PI) * amp;
+	d += ` L ${endX.toFixed(2)} ${yEnd.toFixed(2)}`;
+
+	return d;
+}