@mks2508/mks-ui 0.2.0 → 0.3.1

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;
+}

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

@@ -0,0 +1,140 @@
+"use client";
+
+import React, { useRef, useState, useLayoutEffect, useEffect } from 'react';
+import type { ISlidingTextProps } from './SlidingText.types';
+import { cn } from '@/react-ui/lib/utils';
+
+/**
+ * SlidingText - Character or word-by-word text animations
+ *
+ * Animated text component with entrance/exit transitions and blur effects.
+ * Supports character-level or word-level animation modes.
+ *
+ * @example
+ * ```tsx
+ * // Character animation (default)
+ * <SlidingText text="Hello World" mode="character" />
+ *
+ * // Word animation
+ * <SlidingText text="React Components" mode="word" />
+ *
+ * // Exit animation
+ * <SlidingText text="Goodbye" exit="exit" />
+ * ```
+ */
+export const SlidingText = ({
+  text,
+  mode = 'word',
+  direction = 'vertical',
+  staggerDelay = 15,
+  duration = 200,
+  easing = 'cubic-bezier(0.33, 1, 0.68, 1)',
+  blur = true,
+  widthAnimation = false,
+  initial = 'initial',
+  exit,
+  className = '',
+  style,
+}: ISlidingTextProps): React.ReactElement => {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const contentRef = useRef<HTMLDivElement>(null);
+
+  // Track if we've triggered the enter animation
+  const hasTriggeredEnterRef = useRef(false);
+  const [showAnimate, setShowAnimate] = useState(initial !== 'initial');
+
+  // Trigger enter animation after mount
+  useEffect(() => {
+    if (initial === 'initial' && !hasTriggeredEnterRef.current) {
+      hasTriggeredEnterRef.current = true;
+      requestAnimationFrame(() => {
+        setShowAnimate(true);
+      });
+    }
+  }, [initial]);
+
+  // Compute the actual visual state
+  const visualState = exit === 'exit' ? 'exit' : showAnimate ? 'animate' : 'initial';
+
+  // Split text based on mode
+  const elements = mode === 'character' ? text.split('') : [text];
+
+  // Width Animation Logic
+  useLayoutEffect(() => {
+    if (!widthAnimation || !containerRef.current || !contentRef.current) return;
+
+    const container = containerRef.current;
+    const content = contentRef.current;
+
+    if (visualState === 'initial') {
+      container.style.width = '0px';
+    } else if (visualState === 'animate') {
+      const supportsInterpolateSize = CSS.supports('interpolate-size', 'allow-keywords');
+
+      if (supportsInterpolateSize) {
+        container.style.width = 'auto';
+        container.style.transition = `width ${duration}ms ${easing}`;
+      } else {
+        const targetWidth = content.scrollWidth;
+        container.style.width = `${targetWidth}px`;
+        container.style.transition = `width ${duration}ms ${easing}`;
+
+        const timer = setTimeout(() => {
+          container.style.width = 'auto';
+        }, duration);
+        return () => clearTimeout(timer);
+      }
+    } else if (visualState === 'exit') {
+      const currentWidth = container.getBoundingClientRect().width;
+      container.style.width = `${currentWidth}px`;
+      container.getBoundingClientRect(); // Force reflow
+      container.style.width = '0px';
+      container.style.transition = `width 180ms cubic-bezier(0.32, 0, 0.67, 0)`;
+    }
+  }, [visualState, widthAnimation, duration, easing, text]);
+
+  const getTransitionStyle = (index: number): React.CSSProperties => {
+    const delay = index * staggerDelay;
+    const isExit = visualState === 'exit';
+    const currentDuration = isExit ? 180 : duration;
+    const currentEasing = isExit ? 'cubic-bezier(0.32, 0, 0.67, 0)' : easing;
+
+    return {
+      transition: `
+        opacity ${currentDuration}ms ${currentEasing} ${delay}ms,
+        transform ${currentDuration}ms ${currentEasing} ${delay}ms,
+        filter ${currentDuration}ms ${currentEasing} ${delay}ms
+      `,
+      '--blur-amount': blur ? '4px' : '0px',
+      '--offset': direction === 'vertical' ? '8px' : '16px'
+    } as React.CSSProperties;
+  };
+
+  return (
+    <div
+      ref={containerRef}
+      className={cn('waapi-sliding-text-container', className)}
+      style={style}
+    >
+      <div ref={contentRef} className={cn('waapi-sliding-text-content', `waapi-direction-${direction}`)}>
+        {elements.map((char, index) => (
+          <span
+            key={index}
+            className={cn('waapi-sliding-text-token',
+              visualState === 'initial' && 'enter-from',
+              visualState === 'animate' && 'enter-to',
+              visualState === 'exit' && 'exit-active'
+            )}
+            style={getTransitionStyle(index)}
+          >
+            {char}
+          </span>
+        ))}
+      </div>
+    </div>
+  );
+};
+
+SlidingText.displayName = 'SlidingText';
+
+export type { ISlidingTextProps };

package/src/react-ui/primitives/waapi/core/animationConstants.ts

@@ -0,0 +1,215 @@
+// ============================================
+// ANIMATION CONFIGURATION
+// Single Source of Truth for all animation values.
+// Research-based values from:
+// - Material Design Motion
+// - CSS-Tricks FLIP Technique
+// - Josh W. Comeau Spring Animations
+// - Easings.net
+// ============================================
+
+// ============================================
+// RESPONSIVE & ACCESSIBILITY HELPERS
+// ============================================
+
+/**
+ * Obtains responsive animation duration for the current device.
+ * Returns 0 if the user prefers reduced motion, 60% on mobile.
+ * @param baseDuration - Base duration in ms
+ * @returns Adjusted duration for the current device
+ */
+export const getResponsiveDuration = (baseDuration: number): number => {
+  if (typeof window === 'undefined') return baseDuration;
+
+  const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  if (prefersReducedMotion) return 0;
+
+  const isMobile = window.innerWidth < 768;
+  if (isMobile) {
+    return Math.round(baseDuration * 0.6);
+  }
+
+  return baseDuration;
+};
+
+/**
+ * Obtains responsive stagger delay for the current device.
+ * Returns 0 if the user prefers reduced motion, 50% on mobile.
+ * @param baseDelay - Base delay in ms
+ * @returns Adjusted delay for the current device
+ */
+export const getResponsiveStagger = (baseDelay: number): number => {
+  if (typeof window === 'undefined') return baseDelay;
+
+  const prefersReducedMotion = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+  if (prefersReducedMotion) return 0;
+
+  const isMobile = window.innerWidth < 768;
+  return isMobile ? Math.round(baseDelay * 0.5) : baseDelay;
+};
+
+/** Core timing constants (ms) */
+export const TIMING = {
+  ENTER_DURATION: 200,
+  EXIT_DURATION: 180,
+  COLLAPSE_DURATION: 200,
+  FLIP_DURATION: 300,
+
+  ENTER_STAGGER: 15,
+  EXIT_STAGGER: 0,
+
+  COLLAPSE_DELAY: 30,
+  FLIP_DELAY_PERCENT: 0.25,
+
+  MIN_DELTA_PX: 1,
+} as const;
+
+/** Transform offsets (px/deg) */
+export const TRANSFORMS = {
+  OFFSET_Y_ENTER: 8,
+  OFFSET_Y_EXIT: -8,
+  OFFSET_X: 16,
+
+  SCALE_ENTER: 0.85,
+  SCALE_EXIT: 0.85,
+
+  ROTATE_EXIT: 0,
+} as const;
+
+/** Visual effects */
+export const EFFECTS = {
+  BLUR_ENTER: 4,
+  BLUR_EXIT: 2,
+} as const;
+
+/** Research-based easing curves (Material Design + CSS-Tricks + Josh W. Comeau) */
+export const EASINGS = {
+  MATERIAL_DECELERATE: 'cubic-bezier(0, 0, 0.2, 1)',
+  MATERIAL_ACCELERATE: 'cubic-bezier(0.4, 0, 1, 1)',
+  MATERIAL_STANDARD: 'cubic-bezier(0.4, 0, 0.2, 1)',
+
+  EASE_REORDER: 'cubic-bezier(0.215, 0.61, 0.355, 1)',
+
+  EASE_OUT_CUBIC: 'cubic-bezier(0.33, 1, 0.68, 1)',
+  EASE_IN_CUBIC: 'cubic-bezier(0.32, 0, 0.67, 0)',
+  EASE_IN_OUT: 'cubic-bezier(0.42, 0, 0.58, 1)',
+  EASE_OUT_EXPO: 'cubic-bezier(0.16, 1, 0.3, 1)',
+
+  EASE_FLIP: 'cubic-bezier(0.2, 0, 0.2, 1)',
+
+  SPRING_GENTLE: `linear(0, 0.009, 0.035 2.1%, 0.141 4.4%, 0.723 12.9%, 0.938 16.7%, 1.017 19.4%, 1.067, 1.099 24.3%, 1.108 26%, 1.100, 1.078 30.1%, 1.049 32.5%, 0.994 37.3%, 0.981 40.2%, 0.974 43.4%, 0.975 50.2%, 0.997 62.5%, 1.001 74.7%, 1)`,
+
+  SPRING_SNAPPY: `linear(0, 0.006, 0.024 2%, 0.096 4.2%, 0.397 9.3%, 0.861 15.8%, 1.002 18.7%, 1.093 21.4%, 1.143 24%, 1.156, 1.149 28.3%, 1.115 31.5%, 1.022 40%, 0.988 47.1%, 0.984 55.1%, 0.998 72.3%, 1.001 85.4%, 1)`,
+} as const;
+
+/** Responsive animation configurations with accessibility */
+export const RESPONSIVE_CONFIGS = {
+  tokenEnter: {
+    get duration() { return getResponsiveDuration(TIMING.ENTER_DURATION); },
+    get stagger() { return getResponsiveStagger(TIMING.ENTER_STAGGER); },
+    easing: EASINGS.MATERIAL_DECELERATE,
+    blur: EFFECTS.BLUR_ENTER,
+    offsetY: TRANSFORMS.OFFSET_Y_ENTER,
+    scale: TRANSFORMS.SCALE_ENTER,
+  },
+  tokenExit: {
+    get duration() { return getResponsiveDuration(TIMING.EXIT_DURATION); },
+    get stagger() { return getResponsiveStagger(TIMING.EXIT_STAGGER); },
+    easing: EASINGS.MATERIAL_ACCELERATE,
+    blur: EFFECTS.BLUR_EXIT,
+    offsetY: TRANSFORMS.OFFSET_Y_EXIT,
+    scale: TRANSFORMS.SCALE_EXIT,
+  },
+  collapse: {
+    get duration() { return getResponsiveDuration(TIMING.COLLAPSE_DURATION); },
+    delay: TIMING.COLLAPSE_DELAY,
+    easing: EASINGS.MATERIAL_STANDARD,
+  },
+  flip: {
+    get duration() { return getResponsiveDuration(TIMING.FLIP_DURATION); },
+    delayPercent: TIMING.FLIP_DELAY_PERCENT,
+    easing: EASINGS.EASE_REORDER,
+  },
+} as const;
+
+/** Legacy defaults for backward compatibility */
+export const ANIMATION_DEFAULTS = {
+  DURATION_ENTER: TIMING.ENTER_DURATION,
+  DURATION_EXIT: TIMING.EXIT_DURATION,
+  DURATION_FLIP: TIMING.FLIP_DURATION,
+  STAGGER_DELAY: TIMING.ENTER_STAGGER,
+
+  OFFSET_VERTICAL: TRANSFORMS.OFFSET_Y_ENTER,
+  OFFSET_HORIZONTAL: TRANSFORMS.OFFSET_X,
+
+  BLUR_AMOUNT: EFFECTS.BLUR_ENTER,
+
+  EASING_ENTER: EASINGS.EASE_OUT_CUBIC,
+  EASING_EXIT: EASINGS.EASE_IN_CUBIC,
+  EASING_FLIP: EASINGS.SPRING_GENTLE,
+
+  SPRING_EASING: EASINGS.SPRING_GENTLE,
+};
+
+/** Composite presets for specific use cases */
+export const ANIMATION_CONFIGS = {
+  tokenEnter: {
+    duration: TIMING.ENTER_DURATION,
+    stagger: TIMING.ENTER_STAGGER,
+    easing: EASINGS.MATERIAL_DECELERATE,
+    blur: EFFECTS.BLUR_ENTER,
+    offsetY: TRANSFORMS.OFFSET_Y_ENTER,
+    scale: TRANSFORMS.SCALE_ENTER,
+  },
+  tokenExit: {
+    duration: TIMING.EXIT_DURATION,
+    stagger: TIMING.EXIT_STAGGER,
+    easing: EASINGS.MATERIAL_ACCELERATE,
+    blur: EFFECTS.BLUR_EXIT,
+    offsetY: TRANSFORMS.OFFSET_Y_EXIT,
+    scale: TRANSFORMS.SCALE_EXIT,
+  },
+  collapse: {
+    duration: TIMING.COLLAPSE_DURATION,
+    delay: TIMING.COLLAPSE_DELAY,
+    easing: EASINGS.MATERIAL_STANDARD,
+  },
+  flip: {
+    duration: TIMING.FLIP_DURATION,
+    delayPercent: TIMING.FLIP_DELAY_PERCENT,
+    easing: EASINGS.EASE_REORDER,
+  },
+} as const;
+
+/** High-level animation presets */
+export const PRESETS = {
+  newToken: {
+    mode: 'character' as const,
+    direction: 'vertical' as const,
+    staggerDelay: 15,
+    blur: true,
+    widthAnimation: true,
+    duration: 200,
+    initial: 'initial' as const,
+  },
+
+  existingToken: {
+    mode: 'none' as const,
+    blur: false,
+    widthAnimation: false,
+    initial: false as const,
+  },
+
+  placeholder: {
+    mode: 'word' as const,
+    direction: 'vertical' as const,
+    blur: true,
+    widthAnimation: false,
+    duration: 150,
+  },
+
+  separator: {
+    duration: 100,
+    widthAnimation: true,
+  },
+};

package/src/react-ui/primitives/waapi/core/index.ts

@@ -0,0 +1,53 @@
+/**
+ * WAAPI Core — FLIP animation infrastructure.
+ *
+ * Provides the composable hooks and constants that power
+ * Reorder, Morph, and other WAAPI primitives.
+ *
+ * @module primitives/waapi/core
+ */
+
+// Constants (SSOT)
+export {
+  TIMING,
+  TRANSFORMS,
+  EFFECTS,
+  EASINGS,
+  RESPONSIVE_CONFIGS,
+  ANIMATION_CONFIGS,
+  ANIMATION_DEFAULTS,
+  PRESETS,
+  getResponsiveDuration,
+  getResponsiveStagger,
+} from './animationConstants';
+
+// Core types
+export type {
+  IFLIPDelta,
+  IAnimationTiming,
+  IPositionRect,
+  IElementRegistryAPI,
+  IElementRegistryCallbacks,
+  IPositionCaptureAPI,
+  IPositionCaptureOptions,
+  IFLIPAnimationAPI,
+  IFLIPAnimationOptions,
+  IExitOptions,
+  IEnterOptions,
+  IAnimationOrchestratorConfig,
+  IAnimationOrchestratorAPI,
+  IOrchestratorState,
+  IAnimationEvent,
+} from './types';
+
+export type {
+  FLIPBehavior,
+  ExitPositionStrategy,
+  AnimationPhase,
+} from './types';
+
+// Core hooks
+export { useElementRegistry } from './useElementRegistry';
+export { usePositionCapture } from './usePositionCapture';
+export { useFLIPAnimation } from './useFLIPAnimation';
+export { useAnimationOrchestrator } from './useAnimationOrchestrator';

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

@@ -0,0 +1,200 @@
+/**
+ * Core types for headless animation primitives.
+ * Based on WAAPI (Web Animations API) patterns.
+ *
+ * @module primitives/waapi/core/types
+ */
+
+// =============================================================================
+// FLIP ANIMATION TYPES
+// =============================================================================
+
+/** Calculated delta between two captured positions of an element */
+export interface IFLIPDelta {
+  id: string;
+  deltaX: number;
+  deltaY: number;
+  deltaWidth: number;
+  deltaHeight: number;
+  isSignificant: boolean;
+}
+
+/** Timing configuration for a single animation */
+export interface IAnimationTiming {
+  duration: number;
+  delay?: number;
+  easing: string;
+  fill?: FillMode;
+}
+
+/** Captured position rectangle */
+export interface IPositionRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+// =============================================================================
+// ELEMENT REGISTRY API
+// =============================================================================
+
+/** API for tracking DOM elements by ID */
+export interface IElementRegistryAPI {
+  register: (id: string, el: HTMLElement | null) => void;
+  unregister: (id: string) => void;
+  get: (id: string) => HTMLElement | undefined;
+  getAll: () => Map<string, HTMLElement>;
+  has: (id: string) => boolean;
+  clear: () => void;
+  size: number;
+}
+
+/** Callbacks for element registry lifecycle events */
+export interface IElementRegistryCallbacks {
+  onRegister?: (id: string, el: HTMLElement) => void;
+  onUnregister?: (id: string) => void;
+}
+
+// =============================================================================
+// POSITION CAPTURE API
+// =============================================================================
+
+/** API for capturing element positions and calculating FLIP deltas */
+export interface IPositionCaptureAPI {
+  capture: (excludeIds?: Set<string>) => Map<string, DOMRect>;
+  getPosition: (id: string) => DOMRect | undefined;
+  calculateDeltas: (before: Map<string, DOMRect>, after: Map<string, DOMRect>) => Map<string, IFLIPDelta>;
+  getLastCapture: () => Map<string, DOMRect>;
+  clear: () => void;
+}
+
+/** Options for position capture behavior */
+export interface IPositionCaptureOptions {
+  minDeltaPx?: number;
+}
+
+// =============================================================================
+// FLIP ANIMATION API
+// =============================================================================
+
+/** Options for individual FLIP animations */
+export interface IFLIPAnimationOptions {
+  duration?: number;
+  easing?: string;
+  onStart?: (id: string) => void;
+  onComplete?: (id: string) => void;
+}
+
+/** API for executing FLIP animations */
+export interface IFLIPAnimationAPI {
+  animate: (element: HTMLElement, delta: IFLIPDelta, options?: IFLIPAnimationOptions) => Animation;
+  animateAll: (elements: Map<string, HTMLElement>, deltas: Map<string, IFLIPDelta>, options?: IFLIPAnimationOptions) => Promise<void>;
+  cancel: (id: string) => void;
+  cancelAll: () => void;
+  isAnimating: (id?: string) => boolean;
+}
+
+// =============================================================================
+// EXIT ANIMATION TYPES
+// =============================================================================
+
+/** Options for exit animations */
+export interface IExitOptions {
+  duration?: number;
+  easing?: string;
+  collapseWidth?: boolean;
+  additionalIds?: string[];
+  onComplete?: () => void;
+}
+
+/** Options for enter animations */
+export interface IEnterOptions {
+  duration?: number;
+  easing?: string;
+  stagger?: number;
+  onComplete?: () => void;
+}
+
+// =============================================================================
+// FLIP BEHAVIOR & POSITIONING STRATEGIES
+// =============================================================================
+
+/**
+ * Controls which elements animate when an item exits.
+ * - `'all'`: All remaining elements animate to fill the gap (default)
+ * - `'siblings-after'`: Only elements after the exiting one animate
+ * - `'none'`: No FLIP animation, item exits in-place
+ */
+export type FLIPBehavior = 'all' | 'siblings-after' | 'none';
+
+/**
+ * Controls how the exiting element is positioned during exit animation.
+ * - `'absolute-fixed'`: Position absolute with fixed coordinates (default)
+ * - `'in-place'`: Stay in flow, no position change
+ * - `'custom'`: Consumer handles positioning via CSS/callbacks
+ */
+export type ExitPositionStrategy = 'absolute-fixed' | 'in-place' | 'custom';
+
+// =============================================================================
+// ANIMATION ORCHESTRATOR API
+// =============================================================================
+
+/** Configuration for the animation orchestrator */
+export interface IAnimationOrchestratorConfig {
+  exitDuration?: number;
+  flipDuration?: number;
+  enterDuration?: number;
+  exitEasing?: string;
+  flipEasing?: string;
+  enterEasing?: string;
+
+  flipBehavior?: FLIPBehavior;
+  exitPositionStrategy?: ExitPositionStrategy;
+
+  minDeltaPx?: number;
+
+  onExitComplete?: (id: string) => void;
+  onEnterComplete?: (id: string) => void;
+}
+
+/** Full API surface of the animation orchestrator */
+export interface IAnimationOrchestratorAPI {
+  registry: IElementRegistryAPI;
+  positions: IPositionCaptureAPI;
+  flip: IFLIPAnimationAPI;
+
+  registerElement: (id: string, el: HTMLElement | null) => void;
+  startExit: (id: string, options?: IExitOptions) => Promise<void>;
+  startEnter: (id: string, options?: IEnterOptions) => Promise<void>;
+  isAnimating: (id?: string) => boolean;
+  cancelAnimation: (id: string) => void;
+  cancelAllAnimations: () => void;
+  capturePositions: (excludeIds?: Set<string>) => Map<string, DOMRect>;
+}
+
+// =============================================================================
+// INTERNAL STATE TYPES
+// =============================================================================
+
+/** Internal state tracked by the orchestrator */
+export interface IOrchestratorState {
+  animatingIds: Set<string>;
+  positions: Map<string, DOMRect>;
+  activeAnimations: Map<string, Animation[]>;
+}
+
+// =============================================================================
+// UTILITY TYPES
+// =============================================================================
+
+/** Phase of an animation lifecycle */
+export type AnimationPhase = 'idle' | 'exit' | 'flip' | 'enter' | 'completed';
+
+/** Animation event emitted during orchestration */
+export interface IAnimationEvent {
+  id: string;
+  phase: AnimationPhase;
+  timestamp: number;
+  duration?: number;
+}