@mks2508/mks-ui 0.2.1 → 0.3.1

package/src/react-ui/primitives/waapi/SlidingNumber/SlidingNumber.types.ts

@@ -0,0 +1,84 @@
+/**
+ * Format options for number display using Intl.NumberFormat
+ */
+export interface IFormatOptions {
+  /** Number formatting style */
+  style?: 'decimal' | 'currency' | 'percent';
+  /** Currency code (required when style is 'currency') */
+  currency?: string;
+  /** Locale for formatting (e.g., 'en-US', 'es-ES') */
+  locale?: string;
+  /** Minimum fraction digits */
+  minimumFractionDigits?: number;
+  /** Maximum fraction digits */
+  maximumFractionDigits?: number;
+  /** Whether to use grouping separators */
+  useGrouping?: boolean;
+}
+
+/**
+ * Props for SlidingNumber component
+ *
+ * Animated number transitions with format preservation using WAAPI slot-machine-style animation.
+ *
+ * @example
+ * ```tsx
+ * // Basic counter
+ * <SlidingNumber value={1234} duration={700} />
+ *
+ * // Currency
+ * <SlidingNumber
+ *   value={99.99}
+ *   format={{ style: 'currency', currency: 'USD' }}
+ * />
+ *
+ * // With motion blur
+ * <SlidingNumber value={500} motionBlur={true} digitHeight={60} />
+ * ```
+ */
+export interface ISlidingNumberProps {
+  /** The numeric value to display */
+  value: number;
+
+  /** Animation duration in milliseconds */
+  duration?: number;
+
+  /** Font size for the number display */
+  fontSize?: string;
+
+  /** Font weight for the number display */
+  fontWeight?: string;
+
+  /** Text color */
+  color?: string;
+
+  /** Height of each digit row in pixels */
+  digitHeight?: number;
+
+  /** Delay between digit animations in milliseconds */
+  stagger?: number;
+
+  /** Enable motion blur effect during animation */
+  motionBlur?: boolean;
+
+  /** Number formatting options */
+  format?: IFormatOptions;
+
+  /**
+   * Animation direction trend
+   * - 1: Always animate upward (increasing)
+   * - -1: Always animate downward (decreasing)
+   * - 0: Auto (shorter path)
+   */
+  trend?: -1 | 0 | 1;
+
+  /** Physics-based animation configuration */
+  animationConfig?: {
+    /** Overshoot amount (higher = more bounce) */
+    overshoot?: number;
+    /** Mass of the animated object */
+    mass?: number;
+    /** Spring stiffness */
+    stiffness?: number;
+  };
+}

package/src/react-ui/primitives/waapi/SlidingNumber/index.tsx

@@ -0,0 +1,474 @@
+"use client";
+
+import React, { useEffect, useRef, useMemo, useLayoutEffect } from 'react';
+import type { ISlidingNumberProps, IFormatOptions } from './SlidingNumber.types';
+import { cn } from '@/react-ui/lib/utils';
+
+/**
+ * SlidingNumber - Animated number transitions with format preservation
+ *
+ * Uses WAAPI slot-machine-style animation with optional motion blur.
+ * Supports Intl.NumberFormat for currency, percentage, and decimal formatting.
+ *
+ * @example
+ * ```tsx
+ * // Basic counter
+ * <SlidingNumber value={1234} />
+ *
+ * // Currency with animation
+ * <SlidingNumber
+ *   value={99.99}
+ *   format={{ style: 'currency', currency: 'USD' }}
+ *   duration={700}
+ * />
+ *
+ * // Percentage
+ * <SlidingNumber
+ *   value={75.5}
+ *   format={{ style: 'percent' }}
+ * />
+ * ```
+ */
+export const SlidingNumber = ({
+  value,
+  duration = 700,
+  fontSize = '3rem',
+  fontWeight = '700',
+  color = '#000',
+  digitHeight = 60,
+  stagger = 30,
+  motionBlur = true,
+  format,
+  trend = 0,
+  animationConfig,
+}: ISlidingNumberProps): React.ReactElement => {
+  const computedEasing = useMemo(() => {
+    if (animationConfig) {
+      const { overshoot = 1, stiffness = 1, mass = 1 } = animationConfig;
+      const p1 = 0.34 * stiffness;
+      const p2 = 1 + 0.56 * overshoot;
+      const p3 = 0.64 / mass;
+      return `cubic-bezier(${Math.min(p1, 1).toFixed(2)}, ${Math.min(p2, 2).toFixed(2)}, ${Math.min(p3, 1).toFixed(2)}, 1)`;
+    }
+    return 'cubic-bezier(0.34, 1.56, 0.64, 1)';
+  }, [animationConfig]);
+
+  const currentChars = useMemo(() => parseNumberToChars(value, format), [value, format]);
+  const prevKeysRef = useRef<Set<string>>(new Set());
+  const isFirstRenderRef = useRef(true);
+
+  const enteringKeys = useMemo(() => {
+    if (isFirstRenderRef.current) return new Set<string>();
+    const entering = new Set<string>();
+    currentChars.forEach((c) => {
+      if (!prevKeysRef.current.has(c.key)) {
+        entering.add(c.key);
+      }
+    });
+    return entering;
+  }, [currentChars]);
+
+  useEffect(() => {
+    isFirstRenderRef.current = false;
+    prevKeysRef.current = new Set(currentChars.map((c) => c.key));
+  }, [currentChars]);
+
+  const getDelay = (position: number) => {
+    const absPos = Math.abs(position);
+    return (absPos - 1) * stagger;
+  };
+
+  return (
+    <div
+      className={cn('waapi-sliding-number')}
+      style={{
+        display: 'inline-flex',
+        alignItems: 'center',
+        fontSize,
+        fontWeight,
+        color,
+        fontVariantNumeric: 'tabular-nums',
+        fontFamily: 'system-ui, -apple-system, sans-serif',
+        overflow: 'hidden',
+      }}
+    >
+      {currentChars.map((item) => {
+        const isEntering = enteringKeys.has(item.key);
+
+        if (item.isDigit) {
+          return (
+            <Digit
+              key={item.key}
+              digit={Number.parseInt(item.char)}
+              duration={duration}
+              digitHeight={digitHeight}
+              delay={getDelay(item.position)}
+              motionBlur={motionBlur}
+              easing={computedEasing}
+              isEntering={isEntering}
+              trend={trend}
+            />
+          );
+        }
+
+        return (
+          <Symbol key={item.key} char={item.char} isEntering={isEntering} duration={duration} easing={computedEasing} />
+        );
+      })}
+    </div>
+  );
+};
+
+SlidingNumber.displayName = 'SlidingNumber';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface ICharItem {
+  char: string;
+  key: string;
+  isDigit: boolean;
+  position: number;
+}
+
+interface IDigitProps {
+  digit: number;
+  duration: number;
+  digitHeight: number;
+  delay: number;
+  motionBlur: boolean;
+  easing: string;
+  isEntering: boolean;
+  trend: -1 | 0 | 1;
+}
+
+interface ISymbolProps {
+  char: string;
+  isEntering: boolean;
+  duration: number;
+  easing: string;
+}
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+function parseNumberToChars(value: number, format?: IFormatOptions): ICharItem[] {
+  const locale = format?.locale || 'en-US';
+  const options: Intl.NumberFormatOptions = {
+    style: format?.style || 'decimal',
+    minimumFractionDigits: format?.minimumFractionDigits,
+    maximumFractionDigits: format?.maximumFractionDigits,
+    useGrouping: format?.useGrouping ?? true,
+  };
+
+  if (format?.style === 'currency' && format?.currency) {
+    options.currency = format.currency;
+  }
+
+  const formatter = new Intl.NumberFormat(locale, options);
+  const parts = formatter.formatToParts(value);
+
+  const result: ICharItem[] = [];
+
+  let integerDigitCount = 0;
+  parts.forEach((part) => {
+    if (part.type === 'integer') {
+      integerDigitCount += part.value.length;
+    }
+  });
+
+  let integerIndex = integerDigitCount;
+  let fractionIndex = 0;
+  let groupCount = 0;
+
+  parts.forEach((part, partIdx) => {
+    if (part.type === 'integer') {
+      for (const char of part.value) {
+        result.push({
+          char,
+          key: `int-${integerIndex}`,
+          isDigit: true,
+          position: integerIndex,
+        });
+        integerIndex--;
+      }
+    } else if (part.type === 'fraction') {
+      for (const char of part.value) {
+        fractionIndex++;
+        result.push({
+          char,
+          key: `frac-${fractionIndex}`,
+          isDigit: true,
+          position: -fractionIndex,
+        });
+      }
+    } else if (part.type === 'decimal') {
+      result.push({ char: part.value, key: 'decimal', isDigit: false, position: 0 });
+    } else if (part.type === 'group') {
+      groupCount++;
+      result.push({ char: part.value, key: `group-${groupCount}`, isDigit: false, position: 0 });
+    } else if (part.type === 'currency') {
+      result.push({ char: part.value, key: `currency-${partIdx}`, isDigit: false, position: 0 });
+    } else if (part.type === 'percentSign') {
+      result.push({ char: part.value, key: 'percent', isDigit: false, position: 0 });
+    } else {
+      result.push({ char: part.value, key: `symbol-${partIdx}`, isDigit: false, position: 0 });
+    }
+  });
+
+  return result;
+}
+
+// ============================================================================
+// Symbol Component (non-digit characters)
+// ============================================================================
+
+function Symbol({ char, isEntering, duration, easing }: ISymbolProps) {
+  const ref = useRef<HTMLSpanElement>(null);
+  const hasAnimatedRef = useRef(false);
+
+  useLayoutEffect(() => {
+    if (!ref.current || !isEntering || hasAnimatedRef.current) return;
+    hasAnimatedRef.current = true;
+
+    ref.current.animate(
+      [
+        { opacity: 0, transform: 'scale(0.8)' },
+        { opacity: 1, transform: 'scale(1)' },
+      ],
+      {
+        duration: duration * 0.3,
+        easing,
+        fill: 'forwards',
+      }
+    );
+  }, [isEntering, duration, easing]);
+
+  return (
+    <span
+      ref={ref}
+      style={{
+        display: 'inline-block',
+        whiteSpace: 'pre',
+        opacity: isEntering ? 0 : 1,
+      }}
+    >
+      {char}
+    </span>
+  );
+}
+
+// ============================================================================
+// Digit Component (animated numbers)
+// ============================================================================
+
+function Digit({ digit, duration, digitHeight, delay, motionBlur, easing, isEntering, trend }: IDigitProps) {
+  const columnRef = useRef<HTMLDivElement>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+  const animationRef = useRef<Animation | null>(null);
+  const filterId = useRef(`blur-${Math.random().toString(36).slice(2, 9)}`).current;
+
+  const currentOffsetRef = useRef<number | null>(null);
+  const targetDigitRef = useRef(digit);
+  const hasInitializedRef = useRef(false);
+
+  const sequence = useMemo(() => {
+    const seq: number[] = [];
+    for (let cycle = -1; cycle <= 1; cycle++) {
+      for (let d = 0; d <= 9; d++) {
+        seq.push(d);
+      }
+    }
+    return seq;
+  }, []);
+
+  useLayoutEffect(() => {
+    if (!hasInitializedRef.current) {
+      hasInitializedRef.current = true;
+      const offset = -(digit + 10) * digitHeight;
+      currentOffsetRef.current = offset;
+      targetDigitRef.current = digit;
+
+      if (columnRef.current) {
+        columnRef.current.style.transform = `translateY(${offset}px)`;
+      }
+    }
+  }, [digit, digitHeight]);
+
+  useLayoutEffect(() => {
+    if (!containerRef.current || !isEntering) return;
+
+    containerRef.current.animate(
+      [
+        { opacity: 0, transform: 'scale(0.5) translateY(-20px)' },
+        { opacity: 1, transform: 'scale(1) translateY(0)' },
+      ],
+      {
+        duration: duration * 0.4,
+        easing,
+        fill: 'forwards',
+      }
+    );
+  }, [isEntering, duration, easing]);
+
+  useEffect(() => {
+    targetDigitRef.current = digit;
+
+    if (!hasInitializedRef.current) return;
+
+    const currentDigit =
+      currentOffsetRef.current !== null
+        ? (((Math.round(-currentOffsetRef.current / digitHeight) - 10) % 10) + 10) % 10
+        : digit;
+
+    if (digit === currentDigit && currentOffsetRef.current !== null) {
+      return;
+    }
+
+    animateToDigit(digit);
+  }, [digit, digitHeight]);
+
+  const animateToDigit = (target: number) => {
+    if (!columnRef.current || !containerRef.current) return;
+
+    if (animationRef.current) {
+      const computedStyle = getComputedStyle(columnRef.current);
+      const matrix = new DOMMatrix(computedStyle.transform);
+      currentOffsetRef.current = matrix.m42;
+      animationRef.current.cancel();
+      animationRef.current = null;
+      columnRef.current.style.transform = `translateY(${currentOffsetRef.current}px)`;
+    }
+
+    const rawIndex = currentOffsetRef.current !== null ? -currentOffsetRef.current / digitHeight : target + 10;
+
+    const currentDigitFromOffset = (((Math.round(rawIndex) - 10) % 10) + 10) % 10;
+    const from = currentDigitFromOffset;
+
+    if (target === from && currentOffsetRef.current !== null) {
+      const normalizedOffset = -(target + 10) * digitHeight;
+      if (columnRef.current) {
+        const currentAnim = animationRef.current as Animation | null;
+        if (currentAnim) {
+          currentAnim.cancel();
+        }
+        columnRef.current.style.transform = `translateY(${normalizedOffset}px)`;
+      }
+      currentOffsetRef.current = normalizedOffset;
+      return;
+    }
+
+    let diff: number;
+    if (trend === 1) {
+      diff = target >= from ? target - from : 10 - from + target;
+    } else if (trend === -1) {
+      diff = target <= from ? target - from : target - from - 10;
+    } else {
+      diff = target - from;
+      if (diff > 5) diff -= 10;
+      else if (diff < -5) diff += 10;
+    }
+
+    const startOffset = currentOffsetRef.current ?? -(from + 10) * digitHeight;
+    const endOffset = startOffset - diff * digitHeight;
+
+    const blurEl = document.getElementById(filterId)?.querySelector('feGaussianBlur');
+    if (motionBlur && blurEl) {
+      const intensity = Math.min(Math.abs(diff) * 1.2, 6);
+      blurEl.setAttribute('stdDeviation', `0,${intensity}`);
+      containerRef.current.style.filter = `url(#${filterId})`;
+    }
+
+    const anim = columnRef.current.animate(
+      [{ transform: `translateY(${startOffset}px)` }, { transform: `translateY(${endOffset}px)` }],
+      {
+        duration,
+        delay,
+        easing,
+        fill: 'forwards',
+      }
+    );
+
+    animationRef.current = anim;
+
+    anim.onfinish = () => {
+      const normalizedOffset = -(target + 10) * digitHeight;
+      if (columnRef.current) {
+        anim.cancel();
+        columnRef.current.style.transform = `translateY(${normalizedOffset}px)`;
+      }
+      currentOffsetRef.current = normalizedOffset;
+
+      if (containerRef.current) {
+        containerRef.current.style.filter = 'none';
+      }
+      if (blurEl) {
+        blurEl.setAttribute('stdDeviation', '0,0');
+      }
+
+      animationRef.current = null;
+
+      if (targetDigitRef.current !== target) {
+        requestAnimationFrame(() => {
+          animateToDigit(targetDigitRef.current);
+        });
+      }
+    };
+
+    anim.oncancel = () => {
+      animationRef.current = null;
+    };
+  };
+
+  return (
+    <>
+      <svg style={{ position: 'absolute', width: 0, height: 0 }} aria-hidden="true">
+        <defs>
+          <filter id={filterId}>
+            <feGaussianBlur in="SourceGraphic" stdDeviation="0,0" />
+          </filter>
+        </defs>
+      </svg>
+
+      <div
+        ref={containerRef}
+        style={{
+          position: 'relative',
+          height: `${digitHeight}px`,
+          overflow: 'hidden',
+          width: '0.65em',
+          textAlign: 'center',
+          opacity: isEntering ? 0 : 1,
+        }}
+      >
+        <div
+          ref={columnRef}
+          style={{
+            position: 'absolute',
+            left: 0,
+            right: 0,
+            willChange: 'transform',
+          }}
+        >
+          {sequence.map((d, i) => (
+            <div
+              key={i}
+              style={{
+                height: `${digitHeight}px`,
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+              }}
+            >
+              {d}
+            </div>
+          ))}
+        </div>
+      </div>
+    </>
+  );
+}
+
+export type { ISlidingNumberProps, IFormatOptions };

package/src/react-ui/primitives/waapi/SlidingText/SlidingText.styles.ts

@@ -0,0 +1,32 @@
+import type { StyleSlots } from '@/core/types';
+
+/**
+ * Style slots for SlidingText component
+ */
+export type SlidingTextSlot = 'root' | 'content' | 'token';
+
+/**
+ * Base styles for SlidingText component
+ */
+export const slidingTextBaseStyles: StyleSlots<SlidingTextSlot> = {
+  root: 'waapi-sliding-text-container',
+  content: 'waapi-sliding-text-content',
+  token: 'waapi-sliding-text-token',
+};
+
+/**
+ * CSS classes for animation states
+ */
+export const slidingTextAnimationClasses = {
+  enterFrom: 'enter-from',
+  enterTo: 'enter-to',
+  exitActive: 'exit-active',
+} as const;
+
+/**
+ * CSS classes for direction variants
+ */
+export const slidingTextDirectionClasses = {
+  vertical: 'waapi-direction-vertical',
+  horizontal: 'waapi-direction-horizontal',
+} as const;

package/src/react-ui/primitives/waapi/SlidingText/SlidingText.types.ts

@@ -0,0 +1,69 @@
+/**
+ * Props for SlidingText component
+ *
+ * Character or word-by-word text animations with entrance/exit transitions and blur effects.
+ *
+ * @example
+ * ```tsx
+ * // Character animation (default)
+ * <SlidingText text="Hello World" mode="character" />
+ *
+ * // Word animation
+ * <SlidingText text="React Components" mode="word" />
+ *
+ * // Horizontal direction
+ * <SlidingText
+ *   text="Slide In"
+ *   direction="horizontal"
+ *   blur={false}
+ * />
+ * ```
+ */
+export interface ISlidingTextProps {
+  /** The text content to animate */
+  text: string;
+
+  /**
+   * Animation mode
+   * - 'character': Each character animates individually
+   * - 'word': The text animates as a unit
+   * - 'none': No animation
+   */
+  mode?: 'word' | 'character' | 'none';
+
+  /** Animation direction */
+  direction?: 'vertical' | 'horizontal';
+
+  /** Delay between each character/word in milliseconds */
+  staggerDelay?: number;
+
+  /** Animation duration in milliseconds */
+  duration?: number;
+
+  /** CSS easing function */
+  easing?: string;
+
+  /** Enable blur effect during animation */
+  blur?: boolean;
+
+  /** Animate width changes during animation */
+  widthAnimation?: boolean;
+
+  /** Initial animation state */
+  initial?: 'initial' | false;
+
+  /** Trigger animation state */
+  animate?: 'animate';
+
+  /** Exit animation state */
+  exit?: 'exit';
+
+  /** Callback when animation completes */
+  onAnimationComplete?: () => void;
+
+  /** Additional CSS class name */
+  className?: string;
+
+  /** Additional inline styles */
+  style?: React.CSSProperties;
+}