react-panel-layout 0.5.2 → 0.6.1

package/src/hooks/useAnimatedVisibility.spec.ts

@@ -0,0 +1,277 @@
+/**
+ * @file Tests for useAnimatedVisibility hook.
+ *
+ * アニメーション完了待機パターンのテスト:
+ * 1. アニメーションなし → 即座にdisplay:none
+ * 2. アニメーションあり → 完了待ってdisplay:none
+ */
+import type * as React from "react";
+import { renderHook, act } from "@testing-library/react";
+import { useAnimatedVisibility } from "./useAnimatedVisibility.js";
+
+/**
+ * Create a mock AnimationEvent for testing.
+ */
+function createMockAnimationEvent(
+  target: EventTarget,
+  currentTarget: EventTarget,
+): React.AnimationEvent {
+  const noop = (): void => {};
+  const noopBool = (): boolean => false;
+  const nativeEvent = {
+    animationName: "test",
+    elapsedTime: 0,
+    pseudoElement: "",
+  } as AnimationEvent;
+  return {
+    target,
+    currentTarget,
+    nativeEvent,
+    bubbles: true,
+    cancelable: false,
+    defaultPrevented: false,
+    eventPhase: 0,
+    isTrusted: true,
+    preventDefault: noop,
+    isDefaultPrevented: noopBool,
+    stopPropagation: noop,
+    isPropagationStopped: noopBool,
+    persist: noop,
+    timeStamp: Date.now(),
+    type: "animationend",
+    animationName: "test",
+    elapsedTime: 0,
+    pseudoElement: "",
+  };
+}
+
+describe("useAnimatedVisibility", () => {
+  describe("initial state", () => {
+    it("displays when initially visible", () => {
+      const { result } = renderHook(() =>
+        useAnimatedVisibility({
+          isVisible: true,
+          leaveAnimation: "fadeOut 200ms ease-out",
+        }),
+      );
+
+      expect(result.current.style.display).toBe("block");
+      expect(result.current.state.shouldDisplay).toBe(true);
+      expect(result.current.state.isAnimatingOut).toBe(false);
+    });
+
+    it("hides when initially not visible", () => {
+      const { result } = renderHook(() =>
+        useAnimatedVisibility({
+          isVisible: false,
+          leaveAnimation: "fadeOut 200ms ease-out",
+        }),
+      );
+
+      expect(result.current.style.display).toBe("none");
+      expect(result.current.state.shouldDisplay).toBe(false);
+      expect(result.current.state.isAnimatingOut).toBe(false);
+    });
+  });
+
+  describe("no animation", () => {
+    it("hides immediately when leaveAnimation is undefined", () => {
+      const { result, rerender } = renderHook(
+        ({ isVisible }) => useAnimatedVisibility({ isVisible }),
+        { initialProps: { isVisible: true } },
+      );
+
+      expect(result.current.style.display).toBe("block");
+
+      rerender({ isVisible: false });
+
+      // Should hide immediately (no animation to wait for)
+      expect(result.current.style.display).toBe("none");
+      expect(result.current.state.isAnimatingOut).toBe(false);
+    });
+
+    it("hides immediately when leaveAnimation is 'none'", () => {
+      const { result, rerender } = renderHook(
+        ({ isVisible }) =>
+          useAnimatedVisibility({
+            isVisible,
+            leaveAnimation: "none",
+          }),
+        { initialProps: { isVisible: true } },
+      );
+
+      rerender({ isVisible: false });
+
+      expect(result.current.style.display).toBe("none");
+      expect(result.current.state.isAnimatingOut).toBe(false);
+    });
+
+    it("hides immediately when skipAnimation is true", () => {
+      const { result, rerender } = renderHook(
+        ({ isVisible }) =>
+          useAnimatedVisibility({
+            isVisible,
+            leaveAnimation: "fadeOut 200ms ease-out",
+            skipAnimation: true,
+          }),
+        { initialProps: { isVisible: true } },
+      );
+
+      rerender({ isVisible: false });
+
+      expect(result.current.style.display).toBe("none");
+      expect(result.current.state.isAnimatingOut).toBe(false);
+    });
+  });
+
+  describe("with animation", () => {
+    it("stays visible during leave animation", () => {
+      const { result, rerender } = renderHook(
+        ({ isVisible }) =>
+          useAnimatedVisibility({
+            isVisible,
+            leaveAnimation: "fadeOut 200ms ease-out",
+          }),
+        { initialProps: { isVisible: true } },
+      );
+
+      rerender({ isVisible: false });
+
+      // Should stay visible while animating out
+      expect(result.current.style.display).toBe("block");
+      expect(result.current.state.isAnimatingOut).toBe(true);
+    });
+
+    it("hides after animationEnd event", () => {
+      const { result, rerender } = renderHook(
+        ({ isVisible }) =>
+          useAnimatedVisibility({
+            isVisible,
+            leaveAnimation: "fadeOut 200ms ease-out",
+          }),
+        { initialProps: { isVisible: true } },
+      );
+
+      rerender({ isVisible: false });
+      expect(result.current.style.display).toBe("block");
+
+      // Simulate animationend event
+      const sharedElement = document.createElement("div");
+      const mockEvent = createMockAnimationEvent(sharedElement, sharedElement);
+
+      act(() => {
+        result.current.props.onAnimationEnd(mockEvent);
+      });
+
+      // Now should be hidden
+      expect(result.current.style.display).toBe("none");
+      expect(result.current.state.isAnimatingOut).toBe(false);
+    });
+
+    it("ignores animationEnd from child elements", () => {
+      const { result, rerender } = renderHook(
+        ({ isVisible }) =>
+          useAnimatedVisibility({
+            isVisible,
+            leaveAnimation: "fadeOut 200ms ease-out",
+          }),
+        { initialProps: { isVisible: true } },
+      );
+
+      rerender({ isVisible: false });
+
+      // Simulate animationend from a child element (target !== currentTarget)
+      const parent = document.createElement("div");
+      const child = document.createElement("div");
+      const mockEvent = createMockAnimationEvent(child, parent);
+
+      act(() => {
+        result.current.props.onAnimationEnd(mockEvent);
+      });
+
+      // Should still be visible (event was from child)
+      expect(result.current.style.display).toBe("block");
+      expect(result.current.state.isAnimatingOut).toBe(true);
+    });
+  });
+
+  describe("rapid state changes", () => {
+    it("shows again if made visible during leave animation", () => {
+      const { result, rerender } = renderHook(
+        ({ isVisible }) =>
+          useAnimatedVisibility({
+            isVisible,
+            leaveAnimation: "fadeOut 200ms ease-out",
+          }),
+        { initialProps: { isVisible: true } },
+      );
+
+      // Start hiding
+      rerender({ isVisible: false });
+      expect(result.current.state.isAnimatingOut).toBe(true);
+
+      // Immediately show again
+      rerender({ isVisible: true });
+      expect(result.current.style.display).toBe("block");
+      expect(result.current.state.isAnimatingOut).toBe(false);
+    });
+  });
+
+  describe("timeout fallback", () => {
+    it("hides after timeout if animationEnd never fires", async () => {
+      const { result, rerender } = renderHook(
+        ({ isVisible }) =>
+          useAnimatedVisibility({
+            isVisible,
+            leaveAnimation: "fadeOut 200ms ease-out",
+            animationTimeout: 10,
+          }),
+        { initialProps: { isVisible: true } },
+      );
+
+      rerender({ isVisible: false });
+      expect(result.current.style.display).toBe("block");
+      expect(result.current.state.isAnimatingOut).toBe(true);
+
+      // Advance time past timeout
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 20));
+      });
+
+      // Should be hidden now (fallback triggered)
+      expect(result.current.style.display).toBe("none");
+      expect(result.current.state.isAnimatingOut).toBe(false);
+    });
+
+    it("clears timeout when animationEnd fires before timeout", async () => {
+      const { result, rerender } = renderHook(
+        ({ isVisible }) =>
+          useAnimatedVisibility({
+            isVisible,
+            leaveAnimation: "fadeOut 200ms ease-out",
+            animationTimeout: 10,
+          }),
+        { initialProps: { isVisible: true } },
+      );
+
+      rerender({ isVisible: false });
+
+      // Fire animationEnd before timeout
+      const sharedElement = document.createElement("div");
+      const mockEvent = createMockAnimationEvent(sharedElement, sharedElement);
+
+      act(() => {
+        result.current.props.onAnimationEnd(mockEvent);
+      });
+
+      expect(result.current.style.display).toBe("none");
+
+      // Advance past timeout - should not affect state
+      await act(async () => {
+        await new Promise((resolve) => setTimeout(resolve, 20));
+      });
+
+      expect(result.current.style.display).toBe("none");
+    });
+  });
+});

package/src/hooks/useAnimatedVisibility.ts

@@ -0,0 +1,172 @@
+/**
+ * @file Hook for animation-aware visibility control.
+ *
+ * Common pattern for showing/hiding elements with CSS animations:
+ * - If animation exists: wait for animationend before hiding
+ * - If no animation: hide immediately
+ * - Uses display:none for performance (removes from layout)
+ * - Includes timeout fallback in case animationend doesn't fire
+ */
+import * as React from "react";
+
+/** Default timeout for animation fallback (ms) */
+const DEFAULT_ANIMATION_TIMEOUT = 1000;
+
+type AnimatedVisibilityState = {
+  /** Whether element should be displayed (display: block/none) */
+  shouldDisplay: boolean;
+  /** Whether element is currently animating out */
+  isAnimatingOut: boolean;
+};
+
+type UseAnimatedVisibilityOptions = {
+  /** Whether the element is logically visible */
+  isVisible: boolean;
+  /** CSS animation value for leave animation (e.g., CSS variable) */
+  leaveAnimation?: string;
+  /** Skip animation and hide immediately */
+  skipAnimation?: boolean;
+  /** Timeout for animation fallback in ms (default: 1000ms) */
+  animationTimeout?: number;
+};
+
+type UseAnimatedVisibilityResult = {
+  /** Current visibility state */
+  state: AnimatedVisibilityState;
+  /** Props to spread on the animated element */
+  props: {
+    onAnimationEnd: (e: React.AnimationEvent) => void;
+  };
+  /** Style to apply for display control */
+  style: {
+    display: "block" | "none";
+  };
+};
+
+/**
+ * Hook for animation-aware visibility control.
+ *
+ * @example
+ * const { state, props, style } = useAnimatedVisibility({
+ *   isVisible: isActive,
+ *   leaveAnimation: PIVOT_ANIMATION_LEAVE,
+ * });
+ *
+ * return (
+ *   <div
+ *     style={{ ...baseStyle, ...style, animation: isActive ? enterAnim : leaveAnim }}
+ *     {...props}
+ *   >
+ *     {children}
+ *   </div>
+ * );
+ */
+export function useAnimatedVisibility({
+  isVisible,
+  leaveAnimation,
+  skipAnimation = false,
+  animationTimeout = DEFAULT_ANIMATION_TIMEOUT,
+}: UseAnimatedVisibilityOptions): UseAnimatedVisibilityResult {
+  const prevVisibleRef = React.useRef(isVisible);
+  const [isAnimatingOut, setIsAnimatingOut] = React.useState(false);
+  const timeoutRef = React.useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  // Clear timeout on unmount
+  const shouldSkipLeaveAnimation = (
+    isSkipped: boolean,
+    animation: string | undefined,
+  ): boolean => {
+    if (isSkipped) {
+      return true;
+    }
+    if (!animation) {
+      return true;
+    }
+    if (animation === "none") {
+      return true;
+    }
+    return false;
+  };
+
+  const getShouldDisplay = (visible: boolean, animatingOut: boolean): boolean => {
+    if (visible) {
+      return true;
+    }
+    if (animatingOut) {
+      return true;
+    }
+    return false;
+  };
+
+  React.useEffect(() => {
+    return () => {
+      if (timeoutRef.current) {
+        clearTimeout(timeoutRef.current);
+      }
+    };
+  }, []);
+
+  React.useEffect(() => {
+    const wasVisible = prevVisibleRef.current;
+    prevVisibleRef.current = isVisible;
+
+    // Clear any pending timeout
+    if (timeoutRef.current) {
+      clearTimeout(timeoutRef.current);
+      timeoutRef.current = null;
+    }
+
+    if (wasVisible && !isVisible) {
+      // Transitioning from visible to hidden
+      if (shouldSkipLeaveAnimation(skipAnimation, leaveAnimation)) {
+        // No animation, hide immediately
+        setIsAnimatingOut(false);
+      } else {
+        // Has animation, mark as animating out
+        setIsAnimatingOut(true);
+
+        // Set timeout fallback in case animationend doesn't fire
+        // (e.g., CSS variable resolves to "none", or animation is very short)
+        timeoutRef.current = setTimeout(() => {
+          setIsAnimatingOut(false);
+        }, animationTimeout);
+      }
+    } else if (!wasVisible && isVisible) {
+      // Transitioning from hidden to visible
+      setIsAnimatingOut(false);
+    }
+  }, [isVisible, leaveAnimation, skipAnimation, animationTimeout]);
+
+  const handleAnimationEnd = React.useCallback(
+    (e: React.AnimationEvent) => {
+      // Only handle animation end for this element (not bubbled from children)
+      if (e.target === e.currentTarget && isAnimatingOut) {
+        // Clear timeout since animation completed normally
+        if (timeoutRef.current) {
+          clearTimeout(timeoutRef.current);
+          timeoutRef.current = null;
+        }
+        setIsAnimatingOut(false);
+      }
+    },
+    [isAnimatingOut],
+  );
+
+  // Element should be displayed if:
+  // - It's visible, OR
+  // - It's animating out (leave animation in progress)
+  const shouldDisplay = getShouldDisplay(isVisible, isAnimatingOut);
+
+  return {
+    state: {
+      shouldDisplay,
+      isAnimatingOut,
+    },
+    props: {
+      onAnimationEnd: handleAnimationEnd,
+    },
+    style: {
+      display: shouldDisplay ? "block" : "none",
+    },
+  };
+}

package/src/hooks/useAnimationFrame.ts

@@ -0,0 +1,208 @@
+/**
+ * @file Generic requestAnimationFrame-based animation hook.
+ *
+ * Provides a reusable animation loop with easing support.
+ * This is the foundation for more specific animation hooks.
+ */
+import * as React from "react";
+
+/**
+ * Easing function type.
+ * Takes a progress value (0-1) and returns an eased value (0-1).
+ */
+export type EasingFunction = (t: number) => number;
+
+/**
+ * Built-in easing functions.
+ */
+export const easings = {
+  /** Linear (no easing) */
+  linear: (t: number): number => t,
+
+  /** Ease out cubic */
+  easeOutCubic: (t: number): number => 1 - Math.pow(1 - t, 3),
+
+  /** Ease out expo (similar to cubic-bezier(0.22, 1, 0.36, 1)) */
+  easeOutExpo: (t: number): number => {
+    if (t === 1) {
+      return 1;
+    }
+    return 1 - Math.pow(2, -10 * t);
+  },
+
+  /** Ease out quart */
+  easeOutQuart: (t: number): number => 1 - Math.pow(1 - t, 4),
+
+  /** Ease in out cubic */
+  easeInOutCubic: (t: number): number => {
+    if (t < 0.5) {
+      return 4 * t * t * t;
+    }
+    return 1 - Math.pow(-2 * t + 2, 3) / 2;
+  },
+
+  /** Ease in expo (accelerating, for "suck in" effect) */
+  easeInExpo: (t: number): number => {
+    if (t === 0) {
+      return 0;
+    }
+    return Math.pow(2, 10 * t - 10);
+  },
+} as const;
+
+/**
+ * Animation state passed to callbacks.
+ */
+export type AnimationState = {
+  /** Raw progress (0-1) */
+  progress: number;
+  /** Eased progress (0-1) */
+  easedProgress: number;
+  /** Elapsed time in ms */
+  elapsed: number;
+  /** Whether animation is complete */
+  isComplete: boolean;
+};
+
+/**
+ * Options for useAnimationFrame hook.
+ */
+export type UseAnimationFrameOptions = {
+  /** Duration of animation in milliseconds */
+  duration?: number;
+  /** Easing function for the animation */
+  easing?: EasingFunction;
+  /** Callback called every frame with animation state */
+  onFrame?: (state: AnimationState) => void;
+  /** Callback when animation completes */
+  onComplete?: () => void;
+};
+
+/**
+ * Result from useAnimationFrame hook.
+ */
+export type UseAnimationFrameResult = {
+  /** Whether animation is currently running */
+  isAnimating: boolean;
+  /** Start the animation */
+  start: () => void;
+  /** Cancel the animation */
+  cancel: () => void;
+};
+
+/** Default animation duration in ms */
+const DEFAULT_DURATION = 300;
+
+/**
+ * Generic requestAnimationFrame-based animation hook.
+ *
+ * Provides a reusable animation loop with progress calculation and easing.
+ * Use this as a building block for specific animation behaviors.
+ *
+ * @example
+ * ```tsx
+ * const { start, isAnimating } = useAnimationFrame({
+ *   duration: 300,
+ *   easing: easings.easeOutExpo,
+ *   onFrame: ({ easedProgress }) => {
+ *     const value = fromValue + (toValue - fromValue) * easedProgress;
+ *     element.style.transform = `translateX(${value}px)`;
+ *   },
+ *   onComplete: () => console.log('Done!'),
+ * });
+ *
+ * // Start animation
+ * start();
+ * ```
+ */
+export function useAnimationFrame(options: UseAnimationFrameOptions): UseAnimationFrameResult {
+  const {
+    duration = DEFAULT_DURATION,
+    easing = easings.easeOutExpo,
+    onFrame,
+    onComplete,
+  } = options;
+
+  const [isAnimating, setIsAnimating] = React.useState(false);
+  const rafIdRef = React.useRef<number | null>(null);
+  const startTimeRef = React.useRef<number | null>(null);
+
+  // Use refs for callbacks to avoid stale closures
+  const onFrameRef = React.useRef(onFrame);
+  const onCompleteRef = React.useRef(onComplete);
+  React.useEffect(() => {
+    onFrameRef.current = onFrame;
+    onCompleteRef.current = onComplete;
+  }, [onFrame, onComplete]);
+
+  const cancel = React.useCallback(() => {
+    if (rafIdRef.current !== null) {
+      cancelAnimationFrame(rafIdRef.current);
+      rafIdRef.current = null;
+    }
+    startTimeRef.current = null;
+    setIsAnimating(false);
+  }, []);
+
+  const start = React.useCallback(() => {
+    // Cancel any existing animation
+    cancel();
+
+    setIsAnimating(true);
+    startTimeRef.current = null;
+
+    const step = (timestamp: number) => {
+      if (startTimeRef.current === null) {
+        startTimeRef.current = timestamp;
+      }
+
+      const elapsed = timestamp - startTimeRef.current;
+      const progress = Math.min(elapsed / duration, 1);
+      const easedProgress = easing(progress);
+      const isComplete = progress >= 1;
+
+      const state: AnimationState = {
+        progress,
+        easedProgress,
+        elapsed,
+        isComplete,
+      };
+
+      onFrameRef.current?.(state);
+
+      if (!isComplete) {
+        rafIdRef.current = requestAnimationFrame(step);
+      } else {
+        // Animation complete
+        rafIdRef.current = null;
+        startTimeRef.current = null;
+        setIsAnimating(false);
+        onCompleteRef.current?.();
+      }
+    };
+
+    rafIdRef.current = requestAnimationFrame(step);
+  }, [duration, easing, cancel]);
+
+  // Cleanup on unmount
+  React.useEffect(() => {
+    return () => {
+      if (rafIdRef.current !== null) {
+        cancelAnimationFrame(rafIdRef.current);
+      }
+    };
+  }, []);
+
+  return {
+    isAnimating,
+    start,
+    cancel,
+  };
+}
+
+/**
+ * Interpolate between two values using eased progress.
+ */
+export function interpolate(from: number, to: number, easedProgress: number): number {
+  return from + (to - from) * easedProgress;
+}