@mks2508/mks-ui 0.5.7 → 0.6.0

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

@@ -1,430 +0,0 @@
-'use client';
-import { useRef, useCallback, useEffect } from 'react';
-import { TIMING, TRANSFORMS, EFFECTS, EASINGS } from './animationConstants';
-import { useElementRegistry } from './useElementRegistry';
-import { usePositionCapture } from './usePositionCapture';
-import { useFLIPAnimation } from './useFLIPAnimation';
-import type {
-  IAnimationOrchestratorAPI,
-  IAnimationOrchestratorConfig,
-  IExitOptions,
-  IEnterOptions,
-  IOrchestratorState
-} from './types';
-
-/**
- * Main animation orchestrator hook.
- * Composes useElementRegistry, usePositionCapture, and useFLIPAnimation
- * into a full FLIP exit/enter pipeline.
- *
- * Handles the full exit animation sequence:
- * 1. Capture positions of remaining elements (FIRST)
- * 2. Apply position:absolute to exiting element
- * 3. Force synchronous reflow
- * 4. Capture AFTER positions (LAST)
- * 5. Calculate INVERT deltas and PLAY FLIP animations
- * 6. Run exit animation (per-token stagger or whole-element)
- * 7. Wait for all animations to complete
- * 8. Cleanup and notify completion
- *
- * @param config - Optional orchestrator configuration
- * @returns Full orchestrator API
- *
- * @example
- * ```tsx
- * const orchestrator = useAnimationOrchestrator({
- *   onExitComplete: (id) => removeFromList(id)
- * });
- *
- * <div ref={el => orchestrator.registerElement('item-1', el)} />
- *
- * await orchestrator.startExit('item-1');
- * ```
- */
-export function useAnimationOrchestrator(
-  config?: IAnimationOrchestratorConfig
-): IAnimationOrchestratorAPI {
-  const configRef = useRef(config);
-  useEffect(() => {
-    configRef.current = config;
-  }, [config]);
-
-  const stateRef = useRef<IOrchestratorState>({
-    animatingIds: new Set(),
-    positions: new Map(),
-    activeAnimations: new Map()
-  });
-
-  const registry = useElementRegistry();
-  const positions = usePositionCapture(registry.getAll, {
-    minDeltaPx: config?.minDeltaPx ?? TIMING.MIN_DELTA_PX
-  });
-  const flip = useFLIPAnimation();
-
-  const exitDuration = config?.exitDuration ?? TIMING.EXIT_DURATION;
-  const flipDuration = config?.flipDuration ?? TIMING.FLIP_DURATION;
-  const exitEasing = config?.exitEasing ?? EASINGS.EASE_IN_CUBIC;
-
-  const cancelAnimation = useCallback((id: string) => {
-    const animations = stateRef.current.activeAnimations.get(id);
-    if (animations) {
-      animations.forEach(anim => anim.cancel());
-      stateRef.current.activeAnimations.delete(id);
-    }
-    stateRef.current.animatingIds.delete(id);
-    flip.cancel(id);
-  }, [flip]);
-
-  const cancelAllAnimations = useCallback(() => {
-    stateRef.current.activeAnimations.forEach(animations => {
-      animations.forEach(anim => anim.cancel());
-    });
-    stateRef.current.activeAnimations.clear();
-    stateRef.current.animatingIds.clear();
-    flip.cancelAll();
-  }, [flip]);
-
-  const flipBehavior = config?.flipBehavior ?? 'all';
-  const exitPositionStrategy = config?.exitPositionStrategy ?? 'absolute-fixed';
-
-  /**
-   * Full FLIP exit implementation.
-   * Based on research from Paul Lewis (aerotwist.com), react-flip-move,
-   * and Framer Motion popLayout mode.
-   */
-  const startExit = useCallback(async (id: string, options?: IExitOptions): Promise<void> => {
-    const el = registry.get(id);
-
-    if (!el || stateRef.current.animatingIds.has(id)) {
-      return;
-    }
-
-    stateRef.current.animatingIds.add(id);
-
-    const duration = options?.duration ?? exitDuration;
-    const easing = options?.easing ?? exitEasing;
-
-    // ========================================
-    // STEP 1: FIRST - Capture ALL positions BEFORE any DOM/CSS changes
-    // CRITICAL: Must capture BEFORE setting data attributes!
-    // ========================================
-    const allElements = registry.getAll();
-    const beforePositions = new Map<string, DOMRect>();
-
-    const exitingRect = el.getBoundingClientRect();
-    beforePositions.set(id, exitingRect);
-
-    allElements.forEach((element, elemId) => {
-      if (elemId !== id) {
-        const rect = element.getBoundingClientRect();
-        if (rect.width > 0 && rect.height > 0) {
-          beforePositions.set(elemId, rect);
-        }
-      }
-    });
-
-    const parent = el.parentElement;
-
-    // Set data attributes (triggers CSS position:absolute)
-    el.dataset.reorderState = 'exiting';
-    if (exitPositionStrategy === 'absolute-fixed') {
-      el.dataset.exitPosition = 'absolute';
-    }
-
-    // ========================================
-    // STEP 2: Apply position:absolute to exiting element
-    // Calculate position relative to parent BEFORE it re-centers
-    // ========================================
-    const parentRectBefore = parent?.getBoundingClientRect() || { left: 0, top: 0 };
-    const absoluteLeft = exitingRect.left - parentRectBefore.left;
-    const absoluteTop = exitingRect.top - parentRectBefore.top;
-
-    if (exitPositionStrategy === 'absolute-fixed') {
-      el.style.position = 'absolute';
-      el.style.left = `${absoluteLeft}px`;
-      el.style.top = `${absoluteTop}px`;
-      el.style.width = `${exitingRect.width}px`;
-      el.style.height = `${exitingRect.height}px`;
-      el.style.margin = '0';
-    }
-
-    // Compensate for parent movement after absolute positioning
-    const parentRectAfter = parent?.getBoundingClientRect() || { left: 0, top: 0 };
-    const parentDeltaX = parentRectAfter.left - parentRectBefore.left;
-    const parentDeltaY = parentRectAfter.top - parentRectBefore.top;
-
-    if (Math.abs(parentDeltaX) > 0.5 || Math.abs(parentDeltaY) > 0.5) {
-      el.style.transform = `translate(${-parentDeltaX}px, ${-parentDeltaY}px)`;
-    }
-
-    // ========================================
-    // STEP 3: SYNCHRONOUS reflow via getBoundingClientRect
-    // ========================================
-    // (Forces layout recalculation before paint)
-
-    // ========================================
-    // STEP 4: LAST - Capture AFTER positions IMMEDIATELY (same frame)
-    // ========================================
-    const afterPositions = new Map<string, DOMRect>();
-    allElements.forEach((element, elemId) => {
-      if (elemId !== id) {
-        const rect = element.getBoundingClientRect();
-        if (rect.width > 0 && rect.height > 0) {
-          afterPositions.set(elemId, rect);
-        }
-      }
-    });
-
-    // ========================================
-    // STEP 5: INVERT + PLAY - Calculate deltas and animate siblings
-    // ========================================
-    const flipAnimations: Animation[] = [];
-
-    if (flipBehavior !== 'none') {
-      let siblingsToAnimate: string[] = [];
-
-      if (flipBehavior === 'all') {
-        siblingsToAnimate = [...afterPositions.keys()];
-      } else if (flipBehavior === 'siblings-after') {
-        // Sort by actual DOM order using compareDocumentPosition
-        const elementsWithIds = Array.from(allElements.entries());
-        elementsWithIds.sort((a, b) => {
-          const posA = a[1];
-          const posB = b[1];
-          const position = posA.compareDocumentPosition(posB);
-          return position & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1;
-        });
-
-        const sortedKeys = elementsWithIds.map(([k]) => k);
-        const exitingIndex = sortedKeys.indexOf(id);
-
-        if (exitingIndex !== -1) {
-          siblingsToAnimate = sortedKeys.slice(exitingIndex + 1).filter(k => afterPositions.has(k));
-        }
-      }
-
-      siblingsToAnimate.forEach(siblingId => {
-        const before = beforePositions.get(siblingId);
-        const after = afterPositions.get(siblingId);
-
-        if (!before || !after) return;
-
-        const deltaX = before.left - after.left;
-        const deltaY = before.top - after.top;
-
-        const isSignificant = Math.abs(deltaX) > 1 || Math.abs(deltaY) > 1;
-
-        if (isSignificant) {
-          const siblingEl = allElements.get(siblingId);
-          if (siblingEl) {
-            siblingEl.dataset.reorderState = 'flipping';
-
-            // Apply initial transform SYNCHRONOUSLY via CSS
-            // element.animate() does NOT apply initial keyframe synchronously
-            siblingEl.style.transform = `translate(${deltaX}px, ${deltaY}px)`;
-
-            const anim = siblingEl.animate([
-              { transform: `translate(${deltaX}px, ${deltaY}px)` },
-              { transform: 'none' }
-            ], {
-              duration: flipDuration,
-              easing: EASINGS.MATERIAL_DECELERATE,
-              fill: 'forwards'
-            });
-
-            flipAnimations.push(anim);
-
-            anim.finished.then(() => {
-              siblingEl.style.transform = '';
-              siblingEl.dataset.reorderState = 'idle';
-            }).catch(() => {
-              siblingEl.style.transform = '';
-              siblingEl.dataset.reorderState = 'idle';
-            });
-          }
-        }
-      });
-    }
-
-    // ========================================
-    // STEP 6: Animate exiting element (fade out)
-    // ========================================
-    const exitAnimations: Animation[] = [];
-    // FIX: Use .waapi-sliding-text-token (not .sliding-text-token)
-    const tokens = el.querySelectorAll('.waapi-sliding-text-token');
-
-    if (tokens.length > 0) {
-      tokens.forEach((token, index) => {
-        const delay = index * TIMING.EXIT_STAGGER;
-        const anim = (token as HTMLElement).animate([
-          { opacity: 1, transform: 'translateY(0) scale(1)', filter: 'blur(0px)' },
-          {
-            opacity: 0,
-            transform: `translateY(${TRANSFORMS.OFFSET_Y_EXIT}px) scale(${TRANSFORMS.SCALE_EXIT})`,
-            filter: `blur(${EFFECTS.BLUR_EXIT}px)`
-          }
-        ], {
-          duration,
-          easing,
-          delay,
-          fill: 'forwards'
-        });
-        exitAnimations.push(anim);
-      });
-    } else {
-      const anim = el.animate([
-        { opacity: 1, transform: 'scale(1)' },
-        { opacity: 0, transform: `scale(${TRANSFORMS.SCALE_EXIT})` }
-      ], {
-        duration,
-        easing,
-        fill: 'forwards'
-      });
-      exitAnimations.push(anim);
-    }
-
-    stateRef.current.activeAnimations.set(id, [...exitAnimations, ...flipAnimations]);
-
-    // ========================================
-    // STEP 7: Wait for all animations to complete
-    // ========================================
-    try {
-      await Promise.all([
-        ...exitAnimations.map(a => a.finished),
-        ...flipAnimations.map(a => a.finished)
-      ]);
-    } catch {
-      stateRef.current.animatingIds.delete(id);
-      stateRef.current.activeAnimations.delete(id);
-      return;
-    }
-
-    // ========================================
-    // STEP 8: Cleanup
-    // ========================================
-    stateRef.current.animatingIds.delete(id);
-    stateRef.current.activeAnimations.delete(id);
-
-    el.dataset.reorderState = 'completed';
-
-    if (exitPositionStrategy === 'absolute-fixed') {
-      el.style.removeProperty('position');
-      el.style.removeProperty('left');
-      el.style.removeProperty('top');
-      el.style.removeProperty('width');
-      el.style.removeProperty('height');
-      el.style.removeProperty('margin');
-    }
-
-    delete el.dataset.exitPosition;
-    registry.unregister(id);
-
-    options?.onComplete?.();
-    configRef.current?.onExitComplete?.(id);
-  }, [registry, exitDuration, exitEasing, flipDuration, flipBehavior, exitPositionStrategy]);
-
-  /**
-   * Start enter animation for an element.
-   *
-   * Architecture: CSS + WAAPI
-   * - Assumes element already has data-reorder-state="entering" (set by Reorder.tsx)
-   * - CSS [data-reorder-state="entering"] { opacity: 0; transform: translateY(-8px) scale(0.95); }
-   * - WAAPI animates FROM that state TO visible
-   * - Sets data-reorder-state="idle" on completion
-   */
-  const startEnter = useCallback(async (id: string, options?: IEnterOptions): Promise<void> => {
-    const el = registry.get(id);
-    if (!el) return;
-
-    // Fallback: set entering state if not already set
-    if (!el.dataset.reorderState) {
-      el.dataset.reorderState = 'entering';
-    }
-
-    const enterDuration = configRef.current?.enterDuration ?? TIMING.ENTER_DURATION;
-    const enterEasing = configRef.current?.enterEasing ?? EASINGS.MATERIAL_DECELERATE;
-
-    const duration = options?.duration ?? enterDuration;
-    const easing = options?.easing ?? enterEasing;
-    const stagger = options?.stagger ?? TIMING.ENTER_STAGGER;
-
-    // FIX: Use .waapi-sliding-text-token (not .sliding-text-token)
-    const tokens = el.querySelectorAll('.waapi-sliding-text-token');
-    const animations: Animation[] = [];
-
-    // Keyframes match CSS entering state -> visible
-    const fromKeyframe = {
-      opacity: 0,
-      transform: 'translateY(-8px) scale(0.95)'
-    };
-    const toKeyframe = {
-      opacity: 1,
-      transform: 'none'
-    };
-
-    if (tokens.length > 0) {
-      tokens.forEach((token, index) => {
-        const delay = index * stagger;
-        (token as HTMLElement).dataset.reorderIndex = String(index);
-
-        const anim = (token as HTMLElement).animate([
-          { ...fromKeyframe, filter: `blur(${EFFECTS.BLUR_ENTER}px)` },
-          { ...toKeyframe, filter: 'blur(0px)' }
-        ], {
-          duration,
-          easing,
-          delay,
-          fill: 'forwards'
-        });
-        animations.push(anim);
-      });
-    } else {
-      const anim = el.animate([fromKeyframe, toKeyframe], {
-        duration,
-        easing,
-        fill: 'forwards'
-      });
-      animations.push(anim);
-    }
-
-    try {
-      await Promise.all(animations.map(a => a.finished));
-    } catch {
-      el.dataset.reorderState = 'idle';
-      return;
-    }
-
-    el.dataset.reorderState = 'idle';
-
-    options?.onComplete?.();
-    configRef.current?.onEnterComplete?.(id);
-  }, [registry]);
-
-  const isAnimating = useCallback((id?: string): boolean => {
-    if (id) return stateRef.current.animatingIds.has(id);
-    return stateRef.current.animatingIds.size > 0;
-  }, []);
-
-  const capturePositions = useCallback((excludeIds?: Set<string>) => {
-    return positions.capture(excludeIds);
-  }, [positions]);
-
-  useEffect(() => {
-    return () => {
-      cancelAllAnimations();
-    };
-  }, [cancelAllAnimations]);
-
-  return {
-    registry,
-    positions,
-    flip,
-    registerElement: registry.register,
-    startExit,
-    startEnter,
-    isAnimating,
-    cancelAnimation,
-    cancelAllAnimations,
-    capturePositions
-  };
-}

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

@@ -1,81 +0,0 @@
-'use client';
-import { useRef, useCallback, useEffect } from 'react';
-import type { IElementRegistryAPI, IElementRegistryCallbacks } from './types';
-
-/**
- * Hook for tracking DOM elements by ID.
- * Extracted from the WAAPI animation system's element registration logic.
- *
- * @param callbacks - Optional lifecycle callbacks for register/unregister events
- * @returns Registry API for managing elements by ID
- *
- * @example
- * ```tsx
- * const registry = useElementRegistry({
- *   onRegister: (id) => console.log(`Registered: ${id}`),
- *   onUnregister: (id) => console.log(`Unregistered: ${id}`)
- * });
- *
- * // In render:
- * <div ref={el => registry.register('item-1', el)} />
- * ```
- */
-export function useElementRegistry(
-  callbacks?: IElementRegistryCallbacks
-): IElementRegistryAPI {
-  const elementsRef = useRef<Map<string, HTMLElement>>(new Map());
-
-  const callbacksRef = useRef(callbacks);
-  useEffect(() => {
-    callbacksRef.current = callbacks;
-  }, [callbacks]);
-
-  const register = useCallback((id: string, el: HTMLElement | null) => {
-    if (el) {
-      elementsRef.current.set(id, el);
-      callbacksRef.current?.onRegister?.(id, el);
-    } else {
-      if (elementsRef.current.has(id)) {
-        elementsRef.current.delete(id);
-        callbacksRef.current?.onUnregister?.(id);
-      }
-    }
-  }, []);
-
-  const unregister = useCallback((id: string) => {
-    if (elementsRef.current.has(id)) {
-      elementsRef.current.delete(id);
-      callbacksRef.current?.onUnregister?.(id);
-    }
-  }, []);
-
-  const get = useCallback((id: string): HTMLElement | undefined => {
-    return elementsRef.current.get(id);
-  }, []);
-
-  const getAll = useCallback((): Map<string, HTMLElement> => {
-    return new Map(elementsRef.current);
-  }, []);
-
-  const has = useCallback((id: string): boolean => {
-    return elementsRef.current.has(id);
-  }, []);
-
-  const clear = useCallback(() => {
-    const ids = Array.from(elementsRef.current.keys());
-    elementsRef.current.clear();
-    ids.forEach(id => callbacksRef.current?.onUnregister?.(id));
-  }, []);
-
-  return {
-    register,
-    unregister,
-    get,
-    getAll,
-    has,
-    clear,
-    get size() {
-      return elementsRef.current.size;
-    }
-  };
-}

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

@@ -1,138 +0,0 @@
-'use client';
-import { useRef, useCallback, useEffect } from 'react';
-import { TIMING, EASINGS } from './animationConstants';
-import type { IFLIPAnimationAPI, IFLIPAnimationOptions, IFLIPDelta } from './types';
-
-const DEFAULT_DURATION = TIMING.FLIP_DURATION;
-const DEFAULT_EASING = EASINGS.SPRING_GENTLE;
-
-/**
- * Hook for executing FLIP (First-Last-Invert-Play) animations.
- * Uses spring easing for natural motion with slight overshoot.
- *
- * @returns FLIP animation API with animate, cancel, and status methods
- *
- * @example
- * ```tsx
- * const flip = useFLIPAnimation();
- *
- * // After calculating deltas:
- * await flip.animateAll(elements, deltas, {
- *   duration: 300,
- *   onComplete: (id) => console.log(`${id} completed`)
- * });
- * ```
- */
-export function useFLIPAnimation(): IFLIPAnimationAPI {
-  const activeAnimationsRef = useRef<Map<string, Animation>>(new Map());
-  const animatingIdsRef = useRef<Set<string>>(new Set());
-
-  const animate = useCallback((
-    element: HTMLElement,
-    delta: IFLIPDelta,
-    options?: IFLIPAnimationOptions
-  ): Animation => {
-    const duration = options?.duration ?? DEFAULT_DURATION;
-    const easing = options?.easing ?? DEFAULT_EASING;
-
-    if (activeAnimationsRef.current.has(delta.id)) {
-      activeAnimationsRef.current.get(delta.id)?.cancel();
-    }
-
-    animatingIdsRef.current.add(delta.id);
-    options?.onStart?.(delta.id);
-
-    const animation = element.animate([
-      { transform: `translate3d(${delta.deltaX}px, ${delta.deltaY}px, 0)` },
-      { transform: 'translate3d(0, 0, 0)' }
-    ], {
-      duration,
-      easing
-    });
-
-    activeAnimationsRef.current.set(delta.id, animation);
-
-    animation.onfinish = () => {
-      animatingIdsRef.current.delete(delta.id);
-      activeAnimationsRef.current.delete(delta.id);
-      options?.onComplete?.(delta.id);
-    };
-
-    animation.oncancel = () => {
-      animatingIdsRef.current.delete(delta.id);
-      activeAnimationsRef.current.delete(delta.id);
-    };
-
-    return animation;
-  }, []);
-
-  const animateAll = useCallback(async (
-    elements: Map<string, HTMLElement>,
-    deltas: Map<string, IFLIPDelta>,
-    options?: IFLIPAnimationOptions
-  ): Promise<void> => {
-    const animations: Animation[] = [];
-
-    deltas.forEach((delta, id) => {
-      if (!delta.isSignificant) return;
-
-      const element = elements.get(id);
-      if (!element) return;
-
-      const anim = animate(element, delta, options);
-      animations.push(anim);
-    });
-
-    if (animations.length === 0) return;
-
-    await Promise.all(
-      animations.map(anim =>
-        anim.finished.catch(() => {})
-      )
-    );
-  }, [animate]);
-
-  const cancel = useCallback((id: string) => {
-    const animation = activeAnimationsRef.current.get(id);
-    if (animation) {
-      animation.cancel();
-      activeAnimationsRef.current.delete(id);
-      animatingIdsRef.current.delete(id);
-    }
-  }, []);
-
-  const cancelAll = useCallback(() => {
-    activeAnimationsRef.current.forEach(animation => animation.cancel());
-    activeAnimationsRef.current.clear();
-    animatingIdsRef.current.clear();
-  }, []);
-
-  const isAnimating = useCallback((id?: string): boolean => {
-    if (id) return animatingIdsRef.current.has(id);
-    return animatingIdsRef.current.size > 0;
-  }, []);
-
-  useEffect(() => {
-    return () => {
-      cancelAll();
-    };
-  }, [cancelAll]);
-
-  // Memoize return object to prevent cascading re-renders
-  // that would cancel animations via useEffect cleanup chains
-  const api = useRef<IFLIPAnimationAPI>({
-    animate,
-    animateAll,
-    cancel,
-    cancelAll,
-    isAnimating
-  });
-
-  api.current.animate = animate;
-  api.current.animateAll = animateAll;
-  api.current.cancel = cancel;
-  api.current.cancelAll = cancelAll;
-  api.current.isAnimating = isAnimating;
-
-  return api.current;
-}