@mks2508/mks-ui 0.2.0 → 0.3.1

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

@@ -0,0 +1,429 @@
+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

@@ -0,0 +1,80 @@
+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

@@ -0,0 +1,137 @@
+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;
+}