react-panel-layout 0.6.1 → 0.7.1

package/src/modules/drawer/drawerStateMachine.ts

@@ -0,0 +1,500 @@
+/**
+ * @file Generic state machine for drawer animations.
+ *
+ * This module provides a React-independent state machine for managing drawer
+ * transitions. It handles swipe gestures, button operations, and animations through
+ * a reducer pattern with typed actions.
+ *
+ * The position type is generic, allowing different drawer modes (reveal, overlay)
+ * to use the same state machine logic with mode-specific position calculations.
+ *
+ * Key design principles:
+ * - Pure functions: same input → same output
+ * - No React/DOM dependencies
+ * - Testable in isolation
+ * - Deterministic state transitions
+ */
+
+import { createAction, createActionHandlerMap } from "../../utils/typedActions.js";
+import type { DrawerTransformStrategy, DrawerStrategyConfig } from "./strategies/types.js";
+import {
+  REVEAL_DRAWER_OPEN_DISTANCE_THRESHOLD,
+  REVEAL_DRAWER_DISMISS_RATIO,
+} from "./revealDrawerConstants.js";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Phase of drawer animation lifecycle.
+ * - closed: Drawer is hidden
+ * - opening: Drawer is animating open
+ * - open: Drawer is fully visible
+ * - closing: Drawer is animating closed
+ */
+export type DrawerPhase = "closed" | "opening" | "open" | "closing";
+
+/**
+ * Direction of swipe gesture.
+ */
+export type SwipeDirection = "opening" | "closing" | null;
+
+/**
+ * Animation state tracking from/to positions.
+ */
+export type AnimationState<TPosition> = {
+  /** Animation type */
+  type: "opening" | "closing";
+  /** Starting position */
+  from: TPosition;
+  /** Target position */
+  to: TPosition;
+};
+
+/**
+ * Complete state for drawer.
+ */
+export type DrawerState<TPosition> = {
+  /** Current animation phase */
+  phase: DrawerPhase;
+  /** Target open state (what the drawer should be after current operation) */
+  targetOpen: boolean;
+  /** Current position */
+  position: TPosition;
+  /** Whether a swipe operation is active */
+  isOperating: boolean;
+  /** Direction of current swipe */
+  swipeDirection: SwipeDirection;
+  /** Current swipe displacement in pixels */
+  displacement: number;
+  /** Animation state if animating */
+  animation: AnimationState<TPosition> | null;
+};
+
+// ============================================================================
+// Pure Computation Functions
+// ============================================================================
+
+/**
+ * Compute progress (0-1) from displacement.
+ *
+ * @param displacement - Current swipe displacement in pixels
+ * @param drawerSize - Size of the drawer in pixels
+ * @param direction - Swipe direction ("opening" or "closing")
+ * @returns Progress value between 0 and 1
+ */
+export function computeProgressFromDisplacement(
+  displacement: number,
+  drawerSize: number,
+  direction: SwipeDirection,
+): number {
+  if (drawerSize <= 0 || direction === null) {
+    return 0;
+  }
+
+  const ratio = Math.min(1, Math.max(0, displacement / drawerSize));
+
+  if (direction === "opening") {
+    return ratio;
+  }
+  return 1 - ratio;
+}
+
+/**
+ * Determine if drawer should open or close after swipe ends.
+ *
+ * @param displacement - Final swipe displacement in pixels
+ * @param drawerSize - Size of the drawer in pixels
+ * @param direction - Swipe direction
+ * @returns true if drawer should be open, false if closed
+ */
+export function computeSwipeEndTarget(
+  displacement: number,
+  drawerSize: number,
+  direction: SwipeDirection,
+): boolean {
+  if (direction === "opening") {
+    return displacement >= REVEAL_DRAWER_OPEN_DISTANCE_THRESHOLD;
+  }
+  if (direction === "closing") {
+    const ratio = drawerSize > 0 ? displacement / drawerSize : 0;
+    return ratio < REVEAL_DRAWER_DISMISS_RATIO;
+  }
+  return false;
+}
+
+// ============================================================================
+// Actions
+// ============================================================================
+
+/**
+ * Action creators for drawer state machine.
+ */
+export const drawerActions = {
+  /** Start swipe operation */
+  swipeStart: createAction(
+    "SWIPE_START",
+    (direction: "opening" | "closing") => ({ direction }),
+  ),
+
+  /** Update swipe displacement */
+  swipeUpdate: createAction(
+    "SWIPE_UPDATE",
+    (displacement: number) => ({ displacement }),
+  ),
+
+  /** End swipe operation */
+  swipeEnd: createAction("SWIPE_END"),
+
+  /** Animation frame update */
+  animationFrame: createAction(
+    "ANIMATION_FRAME",
+    (easedProgress: number) => ({ easedProgress }),
+  ),
+
+  /** Animation complete */
+  animationComplete: createAction("ANIMATION_COMPLETE"),
+
+  /** Button open */
+  buttonOpen: createAction("BUTTON_OPEN"),
+
+  /** Button close */
+  buttonClose: createAction("BUTTON_CLOSE"),
+
+  /** Sync open state from external prop */
+  syncOpenState: createAction(
+    "SYNC_OPEN_STATE",
+    (isOpen: boolean) => ({ isOpen }),
+  ),
+
+  /** Initialize state */
+  initialize: createAction(
+    "INITIALIZE",
+    (isOpen: boolean) => ({ isOpen }),
+  ),
+} as const;
+
+export type DrawerAction = ReturnType<
+  (typeof drawerActions)[keyof typeof drawerActions]
+>;
+
+// ============================================================================
+// Initial State Factory
+// ============================================================================
+
+/**
+ * Get target position based on open state.
+ */
+function getTargetPositionFromOpenState<TPosition>(
+  isOpen: boolean,
+  strategy: DrawerTransformStrategy<TPosition>,
+  config: DrawerStrategyConfig,
+): TPosition {
+  if (isOpen) {
+    return strategy.getOpenPosition(config);
+  }
+  return strategy.getClosedPosition(config);
+}
+
+/**
+ * Create initial state for drawer.
+ *
+ * @param isOpen - Initial open state
+ * @param strategy - Transform strategy
+ * @param config - Drawer configuration
+ * @returns Initial state
+ */
+export function createDrawerInitialState<TPosition>(
+  isOpen: boolean,
+  strategy: DrawerTransformStrategy<TPosition>,
+  config: DrawerStrategyConfig,
+): DrawerState<TPosition> {
+  const position = getTargetPositionFromOpenState(isOpen, strategy, config);
+
+  return {
+    phase: isOpen ? "open" : "closed",
+    targetOpen: isOpen,
+    position,
+    isOperating: false,
+    swipeDirection: null,
+    displacement: 0,
+    animation: null,
+  };
+}
+
+// ============================================================================
+// Reducer Factory
+// ============================================================================
+
+/**
+ * Create a drawer reducer for a specific strategy.
+ *
+ * @param strategy - Transform strategy to use for position calculations
+ * @returns Reducer function for the drawer state machine
+ */
+export function createDrawerReducer<TPosition>(
+  strategy: DrawerTransformStrategy<TPosition>,
+) {
+  type State = DrawerState<TPosition>;
+  type ReducerHandler = (
+    state: State,
+    action: DrawerAction,
+    config: DrawerStrategyConfig,
+  ) => State;
+
+  const handlers = createActionHandlerMap<State, typeof drawerActions, DrawerStrategyConfig>(
+    drawerActions,
+    {
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars -- callback signature requires config
+      swipeStart: (state, action, _config) => {
+        if (!("payload" in action)) {return state;}
+        return {
+          ...state,
+          isOperating: true,
+          swipeDirection: action.payload.direction,
+          displacement: 0,
+          animation: null,
+        };
+      },
+
+      swipeUpdate: (state, action, config) => {
+        if (!("payload" in action)) {return state;}
+        if (!state.isOperating) {return state;}
+
+        const progress = computeProgressFromDisplacement(
+          action.payload.displacement,
+          config.drawerSize,
+          state.swipeDirection,
+        );
+        const position = strategy.computePositionFromProgress(progress, config);
+
+        return {
+          ...state,
+          displacement: action.payload.displacement,
+          position,
+        };
+      },
+
+      swipeEnd: (state, _action, config) => {
+        if (!state.isOperating) {return state;}
+
+        const targetOpen = computeSwipeEndTarget(
+          state.displacement,
+          config.drawerSize,
+          state.swipeDirection,
+        );
+        const targetPosition = getTargetPositionFromOpenState(
+          targetOpen,
+          strategy,
+          config
+        );
+
+        if (strategy.shouldAnimate(state.position, targetPosition)) {
+          const animType = targetOpen ? "opening" : "closing";
+          return {
+            ...state,
+            isOperating: false,
+            swipeDirection: null,
+            displacement: 0,
+            targetOpen,
+            phase: animType,
+            animation: {
+              type: animType,
+              from: state.position,
+              to: targetPosition,
+            },
+          };
+        }
+
+        return {
+          ...state,
+          isOperating: false,
+          swipeDirection: null,
+          displacement: 0,
+          targetOpen,
+          phase: targetOpen ? "open" : "closed",
+          position: targetPosition,
+          animation: null,
+        };
+      },
+
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars -- callback signature requires config
+      animationFrame: (state, action, _config) => {
+        if (!("payload" in action)) {return state;}
+        if (!state.animation) {return state;}
+
+        const position = strategy.interpolatePosition(
+          state.animation.from,
+          state.animation.to,
+          action.payload.easedProgress,
+        );
+
+        return {
+          ...state,
+          position,
+        };
+      },
+
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars -- callback signature requires action and config
+      animationComplete: (state, _action, _config) => {
+        if (!state.animation) {return state;}
+
+        const isOpen = state.animation.type === "opening";
+        return {
+          ...state,
+          phase: isOpen ? "open" : "closed",
+          position: state.animation.to,
+          animation: null,
+        };
+      },
+
+      buttonOpen: (state, _action, config) => {
+        if (state.phase === "open" || state.phase === "opening") {
+          return state;
+        }
+        if (state.isOperating) {
+          return state;
+        }
+
+        const targetPosition = strategy.getOpenPosition(config);
+        const fromPosition = state.position;
+
+        if (strategy.shouldAnimate(fromPosition, targetPosition)) {
+          return {
+            ...state,
+            targetOpen: true,
+            phase: "opening",
+            animation: {
+              type: "opening",
+              from: fromPosition,
+              to: targetPosition,
+            },
+          };
+        }
+
+        return {
+          ...state,
+          targetOpen: true,
+          phase: "open",
+          position: targetPosition,
+          animation: null,
+        };
+      },
+
+      buttonClose: (state, _action, config) => {
+        if (state.phase === "closed" || state.phase === "closing") {
+          return state;
+        }
+        if (state.isOperating) {
+          return state;
+        }
+
+        const targetPosition = strategy.getClosedPosition(config);
+        const fromPosition = state.position;
+
+        if (strategy.shouldAnimate(fromPosition, targetPosition)) {
+          return {
+            ...state,
+            targetOpen: false,
+            phase: "closing",
+            animation: {
+              type: "closing",
+              from: fromPosition,
+              to: targetPosition,
+            },
+          };
+        }
+
+        return {
+          ...state,
+          targetOpen: false,
+          phase: "closed",
+          position: targetPosition,
+          animation: null,
+        };
+      },
+
+      syncOpenState: (state, action, config) => {
+        if (!("payload" in action)) {return state;}
+
+        const { isOpen } = action.payload;
+
+        if (state.targetOpen === isOpen && !state.isOperating && !state.animation) {
+          return state;
+        }
+
+        if (state.isOperating) {
+          return {
+            ...state,
+            targetOpen: isOpen,
+          };
+        }
+
+        if (state.animation) {
+          const animTarget = state.animation.type === "opening";
+          if (animTarget === isOpen) {
+            return {
+              ...state,
+              targetOpen: isOpen,
+            };
+          }
+        }
+
+        const currentlyOpen = state.phase === "open" || state.phase === "opening";
+        if (currentlyOpen === isOpen) {
+          return {
+            ...state,
+            targetOpen: isOpen,
+          };
+        }
+
+        const targetPosition = getTargetPositionFromOpenState(
+          isOpen,
+          strategy,
+          config
+        );
+        const fromPosition = state.position;
+
+        if (strategy.shouldAnimate(fromPosition, targetPosition)) {
+          const animType = isOpen ? "opening" : "closing";
+          return {
+            ...state,
+            targetOpen: isOpen,
+            phase: animType,
+            animation: {
+              type: animType,
+              from: fromPosition,
+              to: targetPosition,
+            },
+          };
+        }
+
+        return {
+          ...state,
+          targetOpen: isOpen,
+          phase: isOpen ? "open" : "closed",
+          position: targetPosition,
+          animation: null,
+        };
+      },
+
+      initialize: (_state, action, config) => {
+        if (!("payload" in action)) {return _state;}
+        return createDrawerInitialState(action.payload.isOpen, strategy, config);
+      },
+    },
+  );
+
+  return function drawerReducer(
+    state: State,
+    action: DrawerAction,
+    config: DrawerStrategyConfig,
+  ): State {
+    const handler = handlers[action.type] as ReducerHandler | undefined;
+    if (handler) {
+      return handler(state, action, config);
+    }
+    return state;
+  };
+}

package/src/modules/drawer/revealDrawerConstants.ts

@@ -0,0 +1,38 @@
+/**
+ * @file Constants for reveal drawer state machine.
+ *
+ * Centralizes all threshold values used in reveal drawer behavior.
+ * These values control swipe gestures, animations, and state transitions.
+ */
+
+/**
+ * Minimum swipe distance in pixels to trigger drawer open.
+ * Used when opening via edge swipe gesture.
+ * ~27% of a 375px mobile screen width.
+ */
+export const REVEAL_DRAWER_OPEN_DISTANCE_THRESHOLD = 100;
+
+/**
+ * Ratio of drawer size that must be swiped to dismiss (close) the drawer.
+ * Value between 0 and 1. When swiping to close, if displacement exceeds
+ * this ratio of the drawer size, the drawer will close.
+ */
+export const REVEAL_DRAWER_DISMISS_RATIO = 0.3;
+
+/**
+ * Percentage offset for drawer when closed.
+ * The drawer is positioned at -30% (or +30% for right/bottom) when closed,
+ * creating a "pull out" parallax effect during the reveal animation.
+ */
+export const REVEAL_DRAWER_CLOSED_OFFSET_PERCENT = 30;
+
+/**
+ * Animation duration in milliseconds for reveal transitions.
+ */
+export const REVEAL_DRAWER_ANIMATION_DURATION = 300;
+
+/**
+ * Threshold in pixels below which positions are considered equal.
+ * Used to determine if animation is needed between two positions.
+ */
+export const REVEAL_DRAWER_SNAP_THRESHOLD = 1;