@bug-on/md3-react 2.0.3 → 3.0.0

package/src/ui/shared/constants.ts

@@ -0,0 +1,122 @@
+/**
+ * @file shared/constants.ts
+ *
+ * Shared animation constants for MD3 Expressive UI components.
+ * Centralises spring transition configs and motion variant objects to avoid
+ * duplication across button, icon-button, FAB, and other interactive components.
+ *
+ * @see https://m3.material.io/foundations/animation/overview
+ */
+
+import type { Target, TargetAndTransition, Transition } from "motion/react";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Spring Transitions
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Fast critically-damped spring — used for border-radius morphing.
+ *
+ * - Duration: 200ms
+ * - Bounce: 0 (no overshoot → prevents negative radius jitter)
+ *
+ * @example
+ * ```tsx
+ * <m.button transition={{ borderRadius: SPRING_TRANSITION_FAST }}>...</m.button>
+ * ```
+ */
+export const SPRING_TRANSITION_FAST: Transition = {
+	type: "spring",
+	bounce: 0,
+	duration: 0.2,
+} as const;
+
+/**
+ * Standard critically-damped spring — used for icon/content scale animations.
+ *
+ * - Duration: 300ms
+ * - Bounce: 0 (no overshoot)
+ *
+ * @example
+ * ```tsx
+ * <m.span transition={SPRING_TRANSITION}>...</m.span>
+ * ```
+ */
+export const SPRING_TRANSITION: Transition = {
+	type: "spring",
+	bounce: 0,
+	duration: 0.3,
+} as const;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Icon Span Motion Variants
+// Used for icon/loading indicator swap animation inside FAB and IconButton.
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Framer Motion variants for animating icon spans in/out.
+ *
+ * Scale from near-zero → 1 on enter; back to near-zero on exit.
+ * The near-zero value (0.01) avoids the SMIL freeze bug on Chromium
+ * that occurs when an element starts at exactly `scale(0)`.
+ *
+ * @example
+ * ```tsx
+ * <AnimatePresence mode="wait">
+ *   {loading ? (
+ *     <m.span key="loading" {...ICON_SPAN_VARIANTS} transition={SPRING_TRANSITION}>
+ *       <LoadingIndicator />
+ *     </m.span>
+ *   ) : (
+ *     <m.span key="icon" {...ICON_SPAN_VARIANTS} transition={SPRING_TRANSITION}>
+ *       {icon}
+ *     </m.span>
+ *   )}
+ * </AnimatePresence>
+ * ```
+ */
+export const ICON_SPAN_VARIANTS: {
+	initial: Target;
+	animate: TargetAndTransition;
+	exit: TargetAndTransition;
+} = {
+	initial: { scale: 0.01 },
+	animate: { scale: 1 },
+	exit: { scale: 0.01 },
+} as const;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MD3 TextField Animation Constants
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * MD3 Standard easing curve — used for label float, active indicator expand.
+ * cubic-bezier(0.2, 0, 0, 1)
+ *
+ * @see https://m3.material.io/foundations/animation/easing-and-duration
+ */
+export const MD3_STANDARD_EASING: [number, number, number, number] = [
+	0.2, 0, 0, 1,
+];
+
+/**
+ * Duration for floating label transition: 150ms.
+ * Used when label moves between inline position ↔ floated position.
+ */
+export const MD3_LABEL_FLOAT_DURATION = 0.15;
+
+/**
+ * Duration for active indicator expand/collapse: 200ms.
+ * Used for the bottom border (filled) and outline (outlined) on focus.
+ */
+export const MD3_INDICATOR_DURATION = 0.2;
+
+/**
+ * Duration for supporting text / error text appear/disappear: 120ms.
+ */
+export const MD3_SUPPORTING_DURATION = 0.12;
+
+/**
+ * Duration for trailing icon appear/disappear (clear button, password toggle): 100ms.
+ */
+export const MD3_ICON_SWAP_DURATION = 0.1;

package/{dist/ui/shared/touch-target.d.ts → src/ui/shared/touch-target.tsx}

@@ -12,6 +12,11 @@
  * @see https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html
  * @see https://m3.material.io/foundations/accessible-design/accessibility-basics
  */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TouchTarget Component
+// ─────────────────────────────────────────────────────────────────────────────
+
 /**
  * Invisible 48×48dp touch area expander — satisfies WCAG 2.5.5 + MD3 spec.
  *
@@ -35,4 +40,11 @@
  *
  * @see https://m3.material.io/components/buttons/specs (Touch target section)
  */
-export declare function TouchTarget(): import("react/jsx-runtime").JSX.Element;
+export function TouchTarget() {
+	return (
+		<span
+			aria-hidden="true"
+			className="absolute left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 min-w-12 min-h-12 cursor-pointer pointer-events-none"
+		/>
+	);
+}

package/src/ui/slider/hooks/useSliderMath.ts

@@ -0,0 +1,195 @@
+/**
+ * @file useSliderMath.ts
+ * MD3 Expressive Slider — Math utility hook.
+ *
+ * Handles all slider math in one place:
+ * - value coercion to [min, max]
+ * - step snapping for discrete mode
+ * - value ↔ percent conversion
+ * - keyboard delta calculation
+ * - tick position generation
+ *
+ * Exported as a pure hook for testability and reuse in both Slider and RangeSlider.
+ */
+
+import { useMemo } from "react";
+
+// ─── Pure math helpers (exported for unit testing) ───────────────────────────
+
+/**
+ * Clamps `value` to the closed interval `[min, max]`.
+ *
+ * @example coerceValue(150, 0, 100) → 100
+ */
+export function coerceValue(value: number, min: number, max: number): number {
+	return Math.max(min, Math.min(max, value));
+}
+
+/**
+ * Rounds `value` to the nearest multiple of `step` relative to `min`.
+ * When `step === 0`, returns `value` unchanged (continuous mode).
+ *
+ * @example snapToStep(23, 0, 10) → 20
+ * @example snapToStep(27, 0, 10) → 30
+ */
+export function snapToStep(value: number, min: number, step: number): number {
+	if (step <= 0) return value;
+	const steps = Math.round((value - min) / step);
+	// Use toPrecision to avoid floating-point drift (e.g., 0.1 + 0.2 issues)
+	return Number((min + steps * step).toPrecision(10));
+}
+
+/**
+ * Converts a raw value to a 0–1 fraction of the [min, max] range.
+ * Returns 0 when max === min (degenerate range).
+ *
+ * @example valueToPercent(50, 0, 100) → 0.5
+ */
+export function valueToPercent(
+	value: number,
+	min: number,
+	max: number,
+): number {
+	if (max === min) return 0;
+	return (value - min) / (max - min);
+}
+
+/**
+ * Converts a 0–1 fraction to a value within [min, max], then snaps to step.
+ * The result is also coerced to [min, max].
+ *
+ * @example percentToValue(0.5, 0, 100, 10) → 50
+ * @example percentToValue(0.23, 0, 100, 10) → 20
+ */
+export function percentToValue(
+	percent: number,
+	min: number,
+	max: number,
+	step: number,
+): number {
+	const raw = min + percent * (max - min);
+	const snapped = snapToStep(raw, min, step);
+	return coerceValue(snapped, min, max);
+}
+
+/**
+ * Computes the keyboard increment for a given key.
+ *
+ * Key mappings per WAI-ARIA Slider pattern:
+ * - ArrowRight/Up → +step (or +1% of range if continuous)
+ * - ArrowLeft/Down → -step (or -1% of range)
+ * - PageUp → +10% of range (snapped to step)
+ * - PageDown → -10% of range (snapped to step)
+ * - Home / End → handled by the caller (jump to min/max)
+ *
+ * @returns the signed delta to add to current value, or `null` for Home/End.
+ */
+export function getKeyboardDelta(
+	key: string,
+	step: number,
+	min: number,
+	max: number,
+): number | null {
+	const range = max - min;
+	const discreteStep = step > 0 ? step : range / 100; // 1% of range for continuous
+
+	switch (key) {
+		case "ArrowRight":
+		case "ArrowUp":
+			return discreteStep;
+		case "ArrowLeft":
+		case "ArrowDown":
+			return -discreteStep;
+		case "PageUp":
+			return step > 0 ? snapToStep(range * 0.1, 0, step) : range * 0.1;
+		case "PageDown":
+			return step > 0 ? -snapToStep(range * 0.1, 0, step) : -(range * 0.1);
+		default:
+			return null;
+	}
+}
+
+/**
+ * Generates the list of value positions for tick marks.
+ * Returns an empty array when `step === 0` (continuous mode).
+ *
+ * @example generateTicks(0, 100, 10) → [0, 10, 20, ..., 100]
+ */
+export function generateTicks(
+	min: number,
+	max: number,
+	step: number,
+): number[] {
+	if (step <= 0) return [];
+	const ticks: number[] = [];
+	let current = min;
+	while (current <= max) {
+		ticks.push(Number(current.toPrecision(10)));
+		current += step;
+	}
+	// Ensure max is included even if floating-point drift skips it
+	if (ticks[ticks.length - 1] !== max) {
+		ticks.push(max);
+	}
+	return ticks;
+}
+
+// ─── Hook ────────────────────────────────────────────────────────────────────
+
+export interface UseSliderMathOptions {
+	min: number;
+	max: number;
+	step: number;
+}
+
+export interface UseSliderMathReturn {
+	/** Clamp value to [min, max]. */
+	coerce: (v: number) => number;
+	/** Snap value to nearest step (no-op if step=0). */
+	snap: (v: number) => number;
+	/** Value → percent [0, 1]. */
+	toPercent: (v: number) => number;
+	/** Percent [0, 1] → snapped value. */
+	fromPercent: (pct: number) => number;
+	/**
+	 * Signed delta for a keyboard key.
+	 * Returns `null` for Home/End (jump to min/max, handled by caller).
+	 */
+	getKeyDelta: (key: string) => number | null;
+	/** Tick positions. Empty array in continuous mode. */
+	ticks: number[];
+}
+
+/**
+ * Math utility hook for MD3 Slider components.
+ *
+ * Memoizes all math functions against `min`, `max`, `step` changes.
+ * Use this in both `<Slider>` and `<RangeSlider>` to share logic.
+ *
+ * @example
+ * ```ts
+ * const { coerce, snap, toPercent, fromPercent, getKeyDelta, ticks } =
+ *   useSliderMath({ min: 0, max: 100, step: 10 });
+ *
+ * const percent = toPercent(value);          // → 0.5 for value=50
+ * const newValue = fromPercent(dragPercent); // → 50
+ * const delta = getKeyDelta("ArrowRight");   // → 10
+ * ```
+ */
+export function useSliderMath({
+	min,
+	max,
+	step,
+}: UseSliderMathOptions): UseSliderMathReturn {
+	return useMemo(
+		() => ({
+			coerce: (v: number) => coerceValue(v, min, max),
+			snap: (v: number) => snapToStep(v, min, step),
+			toPercent: (v: number) => valueToPercent(v, min, max),
+			fromPercent: (pct: number) => percentToValue(pct, min, max, step),
+			getKeyDelta: (key: string) => getKeyboardDelta(key, step, min, max),
+			ticks: generateTicks(min, max, step),
+		}),
+		[min, max, step],
+	);
+}

package/{dist/ui/slider/index.d.ts → src/ui/slider/index.ts}

@@ -2,8 +2,19 @@
  * @file index.ts
  * MD3 Expressive Slider — Public API exports.
  */
+
+"use client";
+
 export { RangeSlider } from "./range-slider";
 export { Slider } from "./slider";
+// Tokens (for customization)
 export { SliderColors, SliderTokens } from "./slider.tokens";
-export type { RangeSliderProps, SliderOrientation, SliderProps, SliderTrackSize, SliderVariant, } from "./slider.types";
+// Types
+export type {
+	RangeSliderProps,
+	SliderOrientation,
+	SliderProps,
+	SliderTrackSize,
+	SliderVariant,
+} from "./slider.types";
 export { SliderThumb } from "./slider-thumb";