react-panel-layout 0.6.0 → 0.7.0

package/src/components/window/useDrawerTransform.ts

@@ -0,0 +1,505 @@
+/**
+ * @file Unified hook for drawer transform animations.
+ *
+ * This hook provides a single interface for both reveal and overlay drawer modes.
+ * It uses a strategy pattern internally to handle mode-specific position calculations
+ * and DOM operations while sharing the common state machine logic.
+ */
+import * as React from "react";
+import { useAnimationFrame, easings } from "../../hooks/useAnimationFrame.js";
+import type { ContinuousOperationState } from "../../hooks/gesture/types.js";
+import type { DrawerPlacement } from "./drawerStyles.js";
+import {
+  createDrawerReducer,
+  createDrawerInitialState,
+  drawerActions,
+  type DrawerPhase,
+  type DrawerAction,
+} from "../../modules/drawer/drawerStateMachine.js";
+import {
+  revealStrategy,
+  overlayStrategy,
+  type DrawerStrategyConfig,
+  type DrawerElements,
+  type DrawerTransformStrategy,
+  type RevealPosition,
+  type OverlayPosition,
+} from "../../modules/drawer/strategies/index.js";
+
+/**
+ * Union type for drawer positions (reveal or overlay mode).
+ */
+type DrawerPosition = RevealPosition | OverlayPosition;
+
+/**
+ * Strategy type that works with either position type.
+ */
+type AnyDrawerStrategy = DrawerTransformStrategy<DrawerPosition>;
+import { REVEAL_DRAWER_ANIMATION_DURATION } from "../../modules/drawer/revealDrawerConstants.js";
+import {
+  applyOverflowHidden,
+  clearOverflowHidden,
+  getContentElement,
+  clearDrawerVisibility,
+} from "./drawerRevealAnimationUtils.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Drawer animation mode.
+ */
+export type DrawerMode = "reveal" | "overlay";
+
+/**
+ * Phase of drawer animation lifecycle.
+ */
+export type DrawerAnimationPhase = "idle" | "opening" | "open" | "closing" | "closed";
+
+/**
+ * Options for useDrawerTransform hook.
+ */
+export type UseDrawerTransformOptions = {
+  /** Animation mode */
+  mode: DrawerMode;
+  /** Ref to the drawer element */
+  drawerRef: React.RefObject<HTMLElement | null>;
+  /** Ref to the content element (reveal mode) */
+  contentRef?: React.RefObject<HTMLElement | null>;
+  /** Ref to the backdrop element (overlay mode) */
+  backdropRef?: React.RefObject<HTMLElement | null>;
+  /** Drawer placement */
+  placement: DrawerPlacement;
+  /** Drawer size in pixels */
+  drawerSize: number;
+  /** Whether the drawer is open */
+  isOpen: boolean;
+  /** Current swipe state */
+  swipeState: ContinuousOperationState;
+  /** Current swipe displacement */
+  displacement: number;
+  /** Whether opening via swipe */
+  isOpening: boolean;
+  /** Whether closing via swipe */
+  isClosing: boolean;
+  /** Whether this hook is enabled */
+  enabled: boolean;
+  /** Whether drawer is inline (affects content element for reveal mode) */
+  inline?: boolean;
+  /** Grid container ref for inline mode (reveal mode) */
+  gridRef?: React.RefObject<HTMLElement | null>;
+  /** Content background color (reveal mode) */
+  contentBackground?: string;
+};
+
+/**
+ * Result from useDrawerTransform hook.
+ */
+export type UseDrawerTransformResult = {
+  /** Current animation phase */
+  phase: DrawerAnimationPhase;
+  /** Whether any animation is running */
+  isAnimating: boolean;
+};
+
+// ============================================================================
+// Implementation
+// ============================================================================
+
+/**
+ * Select strategy based on drawer mode.
+ */
+function selectStrategy(mode: DrawerMode): AnyDrawerStrategy {
+  if (mode === "reveal") {
+    return revealStrategy as AnyDrawerStrategy;
+  }
+  return overlayStrategy as AnyDrawerStrategy;
+}
+
+/**
+ * Convert state machine phase to animation phase.
+ */
+function toAnimationPhase(phase: DrawerPhase): DrawerAnimationPhase {
+  return phase;
+}
+
+/**
+ * Unified hook for drawer transform animations.
+ *
+ * Supports both reveal and overlay modes through a strategy pattern.
+ */
+export function useDrawerTransform(
+  options: UseDrawerTransformOptions,
+): UseDrawerTransformResult {
+  const {
+    mode,
+    drawerRef,
+    contentRef,
+    backdropRef,
+    placement,
+    drawerSize,
+    isOpen,
+    swipeState,
+    displacement,
+    isOpening,
+    isClosing,
+    enabled,
+    inline = false,
+    gridRef,
+    contentBackground = "#fff",
+  } = options;
+
+  const isOperating = swipeState.phase === "operating";
+
+  // Select strategy based on mode (cast to AnyDrawerStrategy for generic state machine)
+  const strategy: AnyDrawerStrategy = selectStrategy(mode);
+
+  // Config for strategy
+  const config: DrawerStrategyConfig = React.useMemo(
+    () => ({ placement, drawerSize, contentBackground }),
+    [placement, drawerSize, contentBackground],
+  );
+
+  // Create reducer for the selected strategy
+  const reducer = React.useMemo(
+    () => createDrawerReducer(strategy),
+    [strategy],
+  );
+
+  // State machine state
+  const stateRef = React.useRef(
+    createDrawerInitialState(isOpen, strategy, config),
+  );
+
+  // React state for phase (for external API)
+  const [phase, setPhase] = React.useState<DrawerAnimationPhase>(
+    isOpen ? "open" : "closed",
+  );
+
+  // Track previous values for detecting transitions
+  // Note: enabled starts as false to ensure initialization runs on first mount.
+  // This is critical for React Strict Mode compatibility where effects run twice.
+  const prevRef = React.useRef({
+    isOperating: false,
+    isOpening: false,
+    isClosing: false,
+    isOpen,
+    enabled: false,
+  });
+
+  // Resolve elements based on mode
+  const resolveContentElement = (): HTMLElement | null => {
+    if (mode !== "reveal") {
+      return null;
+    }
+    return contentRef?.current ?? getContentElement(inline, gridRef);
+  };
+
+  const resolveBackdropElement = (): HTMLElement | null => {
+    if (mode !== "overlay") {
+      return null;
+    }
+    return backdropRef?.current ?? null;
+  };
+
+  const getElements = React.useCallback((): DrawerElements => {
+    return {
+      drawer: drawerRef.current,
+      content: resolveContentElement(),
+      backdrop: resolveBackdropElement(),
+    };
+  }, [mode, drawerRef, contentRef, backdropRef, inline, gridRef]);
+
+  // Dispatch helper
+  const dispatch = React.useCallback(
+    (action: DrawerAction) => {
+      const newState = reducer(stateRef.current, action, config);
+      stateRef.current = newState;
+      setPhase(toAnimationPhase(newState.phase));
+      return newState;
+    },
+    [reducer, config],
+  );
+
+  // Animation frame handler
+  const handleFrame = React.useCallback(
+    ({ easedProgress }: { easedProgress: number }) => {
+      const state = stateRef.current;
+      if (!state.animation) {
+        return;
+      }
+
+      const position = strategy.interpolatePosition(
+        state.animation.from,
+        state.animation.to,
+        easedProgress,
+      );
+
+      stateRef.current = { ...state, position };
+
+      const elements = getElements();
+      strategy.applyToDOM(position, elements, config);
+    },
+    [strategy, getElements, config],
+  );
+
+  // Animation complete handler
+  const handleComplete = React.useCallback(() => {
+    const newState = dispatch(drawerActions.animationComplete());
+    const elements = getElements();
+
+    if (newState.phase === "closed") {
+      strategy.onClosingComplete?.(elements, config);
+    }
+  }, [dispatch, strategy, getElements, config]);
+
+  const { isAnimating, start, cancel } = useAnimationFrame({
+    duration: REVEAL_DRAWER_ANIMATION_DURATION,
+    easing: easings.easeOutExpo,
+    onFrame: handleFrame,
+    onComplete: handleComplete,
+  });
+
+  // Initialize drawer state on mount/enable
+  React.useLayoutEffect(() => {
+    if (!enabled) {
+      prevRef.current.enabled = false;
+      return;
+    }
+
+    if (prevRef.current.enabled) {
+      return;
+    }
+    prevRef.current.enabled = true;
+
+    // Re-initialize state machine
+    stateRef.current = createDrawerInitialState(isOpen, strategy, config);
+    setPhase(isOpen ? "open" : "closed");
+
+    const elements = getElements();
+
+    if (isOpen) {
+      strategy.onOpeningStart?.(elements, config);
+      strategy.applyToDOM(stateRef.current.position, elements, config);
+    } else {
+      strategy.onClosingComplete?.(elements, config);
+    }
+  }, [enabled, isOpen, strategy, config, getElements]);
+
+  // Handle swipe start/end
+  React.useLayoutEffect(() => {
+    if (!enabled) {
+      return;
+    }
+
+    const prev = prevRef.current;
+    const wasOperating = prev.isOperating;
+    const wasOpening = prev.isOpening;
+    const wasClosing = prev.isClosing;
+
+    prev.isOperating = isOperating;
+    prev.isOpening = isOpening;
+    prev.isClosing = isClosing;
+
+    // Swipe start
+    if (!wasOperating && isOperating) {
+      cancel();
+      const direction = isOpening ? "opening" : isClosing ? "closing" : null;
+      if (direction) {
+        dispatch(drawerActions.swipeStart(direction));
+      }
+      return;
+    }
+
+    // Swipe end
+    if (wasOperating && !isOperating) {
+      const newState = dispatch(drawerActions.swipeEnd());
+      const elements = getElements();
+
+      if (newState.animation) {
+        strategy.onOpeningStart?.(elements, config);
+        start();
+      } else {
+        if (newState.phase === "open") {
+          strategy.onOpeningStart?.(elements, config);
+          strategy.applyToDOM(newState.position, elements, config);
+        } else if (newState.phase === "closed") {
+          strategy.onClosingComplete?.(elements, config);
+        }
+      }
+      return;
+    }
+
+    // Direction change during operation
+    if (isOperating) {
+      const currentDirection = isOpening ? "opening" : isClosing ? "closing" : null;
+      const prevDirection = wasOpening ? "opening" : wasClosing ? "closing" : null;
+
+      if (currentDirection !== prevDirection && currentDirection) {
+        dispatch(drawerActions.swipeStart(currentDirection));
+      }
+    }
+  }, [
+    enabled,
+    isOperating,
+    isOpening,
+    isClosing,
+    dispatch,
+    cancel,
+    start,
+    strategy,
+    config,
+    getElements,
+  ]);
+
+  // Handle displacement updates during swipe
+  React.useLayoutEffect(() => {
+    if (!enabled) {
+      return;
+    }
+    if (!isOperating) {
+      return;
+    }
+    if (!isOpening && !isClosing) {
+      return;
+    }
+
+    const newState = dispatch(drawerActions.swipeUpdate(displacement));
+    const elements = getElements();
+
+    strategy.onOpeningStart?.(elements, config);
+    strategy.applyToDOM(newState.position, elements, config);
+  }, [
+    enabled,
+    isOperating,
+    isOpening,
+    isClosing,
+    displacement,
+    dispatch,
+    strategy,
+    config,
+    getElements,
+  ]);
+
+  // Handle external isOpen prop changes
+  React.useLayoutEffect(() => {
+    if (!enabled) {
+      return;
+    }
+
+    const prev = prevRef.current;
+    if (prev.isOpen === isOpen) {
+      return;
+    }
+    prev.isOpen = isOpen;
+
+    if (isOperating) {
+      dispatch(drawerActions.syncOpenState(isOpen));
+      return;
+    }
+
+    if (isAnimating) {
+      const currentTarget = stateRef.current.animation?.type === "opening";
+      if (currentTarget === isOpen) {
+        return;
+      }
+    }
+
+    const newState = dispatch(drawerActions.syncOpenState(isOpen));
+    const elements = getElements();
+
+    if (newState.animation) {
+      strategy.onOpeningStart?.(elements, config);
+      strategy.applyToDOM(newState.animation.from, elements, config);
+      start();
+    } else if (!isAnimating) {
+      if (newState.phase === "open") {
+        strategy.onOpeningStart?.(elements, config);
+        strategy.applyToDOM(newState.position, elements, config);
+      } else if (newState.phase === "closed") {
+        strategy.onClosingComplete?.(elements, config);
+      }
+    }
+  }, [
+    enabled,
+    isOpen,
+    isOperating,
+    isAnimating,
+    dispatch,
+    start,
+    strategy,
+    config,
+    getElements,
+  ]);
+
+  // Cleanup on disable
+  React.useLayoutEffect(() => {
+    if (enabled) {
+      return;
+    }
+    if (!prevRef.current.enabled) {
+      return;
+    }
+
+    const elements = getElements();
+    strategy.clearFromDOM(elements, config);
+
+    if (elements.drawer) {
+      clearDrawerVisibility(elements.drawer);
+    }
+  }, [enabled, strategy, config, getElements]);
+
+  // Effect A: Manage body overflow based on drawer state (reveal mode only)
+  //
+  // This effect runs frequently as isOpen/isOperating/isAnimating change.
+  // Cleanup only clears overflow - safe to call repeatedly.
+  React.useLayoutEffect(() => {
+    if (!enabled || mode !== "reveal") {
+      if (mode === "reveal") {
+        clearOverflowHidden();
+      }
+      return;
+    }
+
+    const isActive = isOpen ? true : isOperating ? true : isAnimating;
+
+    if (isActive) {
+      applyOverflowHidden();
+    } else {
+      clearOverflowHidden();
+    }
+
+    return () => {
+      clearOverflowHidden();
+    };
+  }, [enabled, mode, isOpen, isOperating, isAnimating]);
+
+  // Effect B: Clear content element styles on unmount (reveal mode only)
+  //
+  // This effect has minimal dependencies (enabled, mode) so cleanup only runs:
+  // - When enabled changes to false (handled by "Cleanup on disable" effect above)
+  // - When mode changes (rare)
+  // - On unmount (the main case we care about)
+  //
+  // Content styles are applied by strategy.applyToDOM() during swipe/animation.
+  // Content styles are cleared by strategy.onClosingComplete() during NORMAL close.
+  // This effect handles UNMOUNT where onClosingComplete never runs.
+  React.useLayoutEffect(() => {
+    if (!enabled || mode !== "reveal") {
+      return;
+    }
+
+    return () => {
+      const elements = getElements();
+      if (elements.content) {
+        strategy.clearFromDOM({ drawer: null, content: elements.content, backdrop: null }, config);
+      }
+    };
+  }, [enabled, mode, strategy, config, getElements]);
+
+  return {
+    phase,
+    isAnimating,
+  };
+}