@bug-on/md3-react 2.0.3 → 3.0.0

package/src/ui/slider/slider.tokens.ts

@@ -0,0 +1,189 @@
+/**
+ * @file slider.tokens.ts
+ * MD3 Expressive Slider — Design tokens ported from:
+ *   - SliderTokens.kt (Jetpack Compose M3 Expressive)
+ *   - M3 Expressive visual spec (handle squeeze, gaps, asymmetric radii)
+ *
+ * All dimensional values are in px (dp equivalents for web).
+ * Colors reference CSS custom properties — do NOT hardcode hex.
+ * @see docs/m3/sliders/Slider.kt
+ */
+
+import type { SliderTrackSize } from "./slider.types";
+
+// ─── Dimensional tokens ───────────────────────────────────────────────────────
+
+/**
+ * Core dimensional design tokens for the MD3 Expressive Slider.
+ * Maps directly from SliderTokens.kt to CSS/JS values.
+ */
+export const SliderTokens = {
+	// ── Track sizes (height for horizontal, width for vertical) ────────────────
+	trackSizes: {
+		xs: 16,
+		s: 24,
+		m: 40,
+		l: 56,
+		xl: 96,
+	} satisfies Record<SliderTrackSize, number>,
+
+	// ── Track shapes (border radius) ──────────────────────────────────────────
+	trackShapes: {
+		xs: 8,
+		s: 8,
+		m: 12,
+		l: 16,
+		xl: 28,
+	} satisfies Record<SliderTrackSize, number>,
+
+	// ── Thumb (handle) ────────────────────────────────────────────────────────
+	/** Thumb height grows with track size */
+	thumbHeights: {
+		xs: 44,
+		s: 44,
+		m: 52,
+		l: 68,
+		xl: 108,
+	} satisfies Record<SliderTrackSize, number>,
+	/**
+	 * Thumb width at rest and on hover.
+	 * MD3 Expressive handle pill: 4dp wide.
+	 */
+	thumbWidthDefault: 4,
+	/**
+	 * Thumb width while pressed/dragging.
+	 * "Squeeze" animation: 4dp → 2dp (M3 Expressive behavior).
+	 */
+	thumbWidthPressed: 2,
+
+	// ── Track–thumb gap ───────────────────────────────────────────────────────
+	/**
+	 * Transparent gap between the active/inactive track segments and the thumb.
+	 * Maps to ActiveHandleLeadingSpace / ActiveHandleTrailingSpace = 6dp.
+	 *
+	 * This gap is rendered by mathematically subtracting it from the track
+	 * segment width — NOT using margin/padding.
+	 */
+	thumbGap: 6,
+
+	// ── Track corner radii ────────────────────────────────────────────────────
+	/**
+	 * Corner radius on the INNER ends of each track segment (facing the thumb).
+	 * Fixed to 2px according to MD3 Expressive Slider specs (TrackInsideCornerSize).
+	 * Outer ends use `trackSize / 2` (pill cap) — computed inline per component.
+	 */
+	trackInnerRadius: 2,
+
+	// ── Stop indicator / Tick ─────────────────────────────────────────────────
+	/** Tick dot size (width and height). = 4dp. */
+	tickSize: 4,
+
+	// ── Touch target ─────────────────────────────────────────────────────────
+	/**
+	 * Minimum touch target for the thumb wrapper.
+	 * MD3 requires 48dp minimum touch target for interactive elements.
+	 */
+	thumbTouchTarget: 48,
+
+	// ── Value indicator ───────────────────────────────────────────────────────
+	/** Offset above the thumb center for the value indicator tooltip. */
+	valueIndicatorOffset: 52,
+
+	// ── Inset icon ────────────────────────────────────────────────────────────
+	/** Standard icon size map for inset icons inside the track. */
+	insetIconSizes: {
+		xs: 0,
+		s: 0,
+		m: 24,
+		l: 24,
+		xl: 32,
+	} satisfies Record<SliderTrackSize, number>,
+	/**
+	 * Padding between icon and track edge (horizontal).
+	 * Keeps the icon visually centered within the pill track.
+	 */
+	insetIconPadding: 4,
+} as const;
+
+// ─── Color tokens ─────────────────────────────────────────────────────────────
+
+/**
+ * CSS custom property references for Slider colors.
+ * Maps to --md-sys-color-* tokens in the MD3 theme system.
+ *
+ * DO NOT hardcode hex/rgba values — these references automatically
+ * adapt to light/dark theme.
+ */
+export const SliderColors = {
+	// ── Track ─────────────────────────────────────────────────────────────────
+	/** Active track color. Maps to ActiveTrackColor token. */
+	activeTrack: "var(--md-sys-color-primary)",
+	/** Inactive track color. Maps to InactiveTrackColor token. */
+	inactiveTrack: "var(--md-sys-color-secondary-container)",
+	/**
+	 * Disabled track color.
+	 * Uses opacity + on-surface per MD3 disabled state spec.
+	 */
+	disabledActiveTrack: "var(--md-sys-color-on-surface)",
+	disabledInactiveTrack: "var(--md-sys-color-on-surface)",
+
+	// ── Thumb ─────────────────────────────────────────────────────────────────
+	/** Thumb (handle) color. Maps to HandleColor token. */
+	thumb: "var(--md-sys-color-primary)",
+	/** Disabled thumb color. */
+	disabledThumb: "var(--md-sys-color-on-surface)",
+
+	// ── Value indicator ───────────────────────────────────────────────────────
+	/** Value indicator (tooltip) background. Maps to InverseSurface. */
+	valueIndicatorBg: "var(--md-sys-color-inverse-surface)",
+	/** Value indicator (tooltip) text. Maps to InverseOnSurface. */
+	valueIndicatorText: "var(--md-sys-color-inverse-on-surface)",
+
+	// ── Ticks ────────────────────────────────────────────────────────────────
+	/**
+	 * Tick on the INACTIVE portion of the track.
+	 * Maps to TickMarkActiveContainerColor (in spec: primary color stands out).
+	 */
+	tickOnInactive: "var(--md-sys-color-primary)",
+	/**
+	 * Tick on the ACTIVE portion of the track.
+	 * Maps to TickMarkInactiveContainerColor (secondary-container blends in).
+	 */
+	tickOnActive: "var(--md-sys-color-secondary-container)",
+	disabledTick: "var(--md-sys-color-on-surface)",
+} as const;
+
+// ─── Animation constants ──────────────────────────────────────────────────────
+
+/**
+ * FastSpatial spring for thumb width squeeze animation.
+ * Equivalent to MotionSchemeKeyTokens.FastSpatial in Compose.
+ */
+export const SLIDER_THUMB_SPRING = {
+	type: "spring",
+	stiffness: 500,
+	damping: 40,
+} as const;
+
+/**
+ * DefaultSpatial spring for thumb position/track updates.
+ * Slightly looser feel for position changes.
+ */
+export const SLIDER_POSITION_SPRING = {
+	type: "spring",
+	stiffness: 400,
+	damping: 38,
+} as const;
+
+/** Color crossfade for active/inactive track color transitions. */
+export const SLIDER_COLOR_TRANSITION = {
+	duration: 0.18,
+	ease: "easeInOut",
+} as const;
+
+/** Value indicator appear/disappear animation. */
+export const SLIDER_INDICATOR_TRANSITION = {
+	type: "spring",
+	stiffness: 450,
+	damping: 32,
+} as const;

package/src/ui/slider/slider.tsx

@@ -0,0 +1,259 @@
+/**
+ * @file slider.tsx
+ * MD3 Expressive Slider — Main composition component.
+ *
+ * Supports:
+ * - Controlled and uncontrolled usage patterns
+ * - Horizontal and vertical orientations
+ * - Discrete mode (step snapping + tick marks)
+ * - Centered active track (isCentered)
+ * - Value indicator tooltip
+ * - Full keyboard navigation (ARIA Slider pattern)
+ * - Click-to-jump on track
+ *
+ * Architecture: Flat (no Context needed for single thumb variant).
+ * Track + Thumb are internal sub-components composed here.
+ *
+ * @see https://m3.material.io/components/sliders/overview
+ * @see docs/m3/sliders/Slider.kt
+ */
+
+import { domMax, LazyMotion } from "motion/react";
+import * as React from "react";
+import { cn } from "../../lib/utils";
+import { useSliderMath } from "./hooks/useSliderMath";
+import { SliderTokens } from "./slider.tokens";
+import type { SliderProps } from "./slider.types";
+import { SliderThumb } from "./slider-thumb";
+import { SliderTrack } from "./slider-track";
+
+// ─── Slider ───────────────────────────────────────────────────────────────────
+
+const SliderComponent = React.forwardRef<HTMLDivElement, SliderProps>(
+	(
+		{
+			value: controlledValue,
+			defaultValue,
+			onValueChange,
+			onValueChangeEnd,
+			min = 0,
+			max = 100,
+			step = 0,
+			orientation = "horizontal",
+			trackSize = "m",
+			trackShape = "md3",
+			variant = "primary",
+			isCentered = false,
+			disabled = false,
+			showValueIndicator = false,
+			showTicks = false,
+			insetIcon,
+			insetIconAtMin,
+			insetIconTrailing,
+			insetIconAtMax,
+			formatValue,
+			className,
+			"aria-label": ariaLabel,
+			"aria-labelledby": ariaLabelledBy,
+		},
+		ref,
+	) => {
+		const isHorizontal = orientation === "horizontal";
+
+		// ── Controlled / Uncontrolled state ────────────────────────────────────
+		const midpoint = min + (max - min) / 2;
+		const initialValue = defaultValue ?? midpoint;
+		const [internalValue, setInternalValue] = React.useState(initialValue);
+		const resolvedValue =
+			controlledValue !== undefined ? controlledValue : internalValue;
+
+		const { coerce, snap, toPercent, ticks } = useSliderMath({
+			min,
+			max,
+			step,
+		});
+
+		const safeValue = snap(coerce(resolvedValue));
+		const percent = toPercent(safeValue);
+
+		// ── Track ref (for click-to-jump + thumb drag constraint) ──────────────
+		const trackRef = React.useRef<HTMLDivElement>(null);
+
+		// ── onChange handler ───────────────────────────────────────────────────
+		const handleValueChange = React.useCallback(
+			(newValue: number) => {
+				const clamped = snap(coerce(newValue));
+				if (controlledValue === undefined) {
+					setInternalValue(clamped);
+				}
+				onValueChange?.(clamped);
+			},
+			[coerce, controlledValue, onValueChange, snap],
+		);
+
+		const handleValueChangeEnd = React.useCallback(
+			(newValue: number) => {
+				onValueChangeEnd?.(snap(coerce(newValue)));
+			},
+			[coerce, onValueChangeEnd, snap],
+		);
+
+		// ── Click-to-jump on track ─────────────────────────────────────────────
+		const handleTrackPointerDown = React.useCallback(
+			(e: React.PointerEvent<HTMLDivElement>) => {
+				if (disabled) return;
+				const trackEl = trackRef.current;
+				if (!trackEl) return;
+
+				const rect = trackEl.getBoundingClientRect();
+				let clickPercent: number;
+
+				const insetLimit =
+					SliderTokens.thumbGap + SliderTokens.thumbWidthDefault / 2;
+				const trackInset = Math.min(
+					SliderTokens.trackSizes[trackSize] / 2,
+					insetLimit,
+				);
+
+				if (isHorizontal) {
+					const x = e.clientX - rect.left;
+					clickPercent = (x - trackInset) / (rect.width - trackInset * 2);
+				} else {
+					const y = rect.bottom - e.clientY;
+					clickPercent = (y - trackInset) / (rect.height - trackInset * 2);
+				}
+
+				const clamped = Math.max(0, Math.min(1, clickPercent));
+				const rawValue = min + clamped * (max - min);
+				const newValue = snap(coerce(rawValue));
+				handleValueChange(newValue);
+			},
+			[
+				coerce,
+				disabled,
+				handleValueChange,
+				isHorizontal,
+				max,
+				min,
+				snap,
+				trackSize,
+			],
+		);
+
+		// ── Generate unique IDs for ARIA ───────────────────────────────────────
+		const id = React.useId();
+		const thumbId = `slider-thumb-${id}`;
+
+		// ── Inset icon guard (MD3 spec) ───────────────────────────────────────────
+		// Only track sizes >= 40dp support inset icon. Not valid with isCentered.
+		const supportsInsetIcon =
+			!isCentered && SliderTokens.trackSizes[trackSize] >= 40;
+		const hasAnyInsetIcon = !!(insetIcon || insetIconTrailing);
+		if (hasAnyInsetIcon && !supportsInsetIcon) {
+			console.warn(
+				"[Slider] insetIcon is only supported on track sizes >= 40dp (e.g. xl track sizes). " +
+					"See MD3 spec: https://m3.material.io/components/sliders/specs",
+			);
+		}
+
+		return (
+			<LazyMotion features={domMax} strict>
+				<div
+					ref={ref}
+					className={cn(
+						"relative flex items-center",
+						isHorizontal ? "w-full flex-row" : "h-full flex-col",
+						disabled && "pointer-events-none",
+						className,
+					)}
+					style={isHorizontal ? { minWidth: 0 } : { minHeight: 0 }}
+				>
+					<SliderTrack
+						percent={percent}
+						trackSize={trackSize}
+						trackShape={trackShape}
+						orientation={orientation}
+						isCentered={isCentered}
+						min={min}
+						max={max}
+						disabled={disabled}
+						variant={variant}
+						trackRef={trackRef}
+						onTrackPointerDown={handleTrackPointerDown}
+						ticks={showTicks ? ticks : []}
+						insetIcon={supportsInsetIcon ? insetIcon : undefined}
+						insetIconAtMin={supportsInsetIcon ? insetIconAtMin : undefined}
+						insetIconTrailing={
+							supportsInsetIcon ? insetIconTrailing : undefined
+						}
+						insetIconAtMax={supportsInsetIcon ? insetIconAtMax : undefined}
+						value={safeValue}
+					/>
+
+					<SliderThumb
+						value={safeValue}
+						percent={percent}
+						min={min}
+						max={max}
+						step={step}
+						disabled={disabled}
+						orientation={orientation}
+						trackSize={trackSize}
+						variant={variant}
+						showValueIndicator={showValueIndicator}
+						trackRef={trackRef}
+						onValueChange={handleValueChange}
+						onValueChangeEnd={handleValueChangeEnd}
+						formatValue={formatValue}
+						thumbId={thumbId}
+						zIndex={1}
+						aria-label={ariaLabel}
+						aria-labelledby={ariaLabelledBy}
+					/>
+				</div>
+			</LazyMotion>
+		);
+	},
+);
+
+SliderComponent.displayName = "Slider";
+
+/**
+ * MD3 Expressive Slider component.
+ *
+ * A pill-shaped vertical handle that slides along a rounded track.
+ * Supports continuous and discrete (step) modes, horizontal/vertical
+ * orientations, and centered active track.
+ *
+ * Features:
+ * - M3 Expressive handle: 4px pill that squeezes to 2px on press
+ * - 6px transparent gap between track and thumb
+ * - Asymmetric corner radii: outer ends=9999px, inner ends=2px
+ * - Tick marks for discrete mode
+ * - Optional floating value indicator tooltip
+ * - Full keyboard navigation per WAI-ARIA Slider pattern
+ *
+ * @example
+ * ```tsx
+ * // Basic controlled
+ * <Slider value={volume} onValueChange={setVolume} aria-label="Volume" />
+ *
+ * // Discrete with ticks
+ * <Slider defaultValue={0} step={10} min={0} max={100} />
+ *
+ * // Vertical orientation
+ * <div className="h-64">
+ *   <Slider defaultValue={50} orientation="vertical" aria-label="Brightness" />
+ * </div>
+ *
+ * // Centered active track
+ * <Slider defaultValue={0} isCentered showValueIndicator />
+ *
+ * // Large track with value tooltip
+ * <Slider defaultValue={50} trackSize="l" showValueIndicator
+ *   formatValue={(v) => `${v}%`} />
+ * ```
+ *
+ * @see https://m3.material.io/components/sliders/overview
+ */
+export const Slider = React.memo(SliderComponent);