react-panel-layout 0.6.0 → 0.7.0

package/src/modules/drawer/revealDrawerStateMachine.ts

@@ -0,0 +1,197 @@
+/**
+ * @file Reveal drawer state machine (backward-compatible re-export).
+ *
+ * This module provides backward compatibility by re-exporting the generic
+ * drawer state machine configured with the reveal strategy.
+ *
+ * For new code, prefer importing from drawerStateMachine.ts directly
+ * with the appropriate strategy.
+ */
+
+import type { DrawerPlacement } from "../../components/window/drawerStyles.js";
+import { revealStrategy } from "./strategies/revealStrategy.js";
+import type { RevealPosition } from "./strategies/types.js";
+import {
+  createDrawerReducer,
+  createDrawerInitialState,
+  drawerActions,
+  computeProgressFromDisplacement as genericComputeProgress,
+  computeSwipeEndTarget as genericComputeSwipeEndTarget,
+  type DrawerPhase,
+  type SwipeDirection,
+  type AnimationState,
+  type DrawerState,
+  type DrawerAction,
+} from "./drawerStateMachine.js";
+import {
+  REVEAL_DRAWER_CLOSED_OFFSET_PERCENT,
+  REVEAL_DRAWER_SNAP_THRESHOLD,
+} from "./revealDrawerConstants.js";
+import { getPlacementConfig } from "./strategies/types.js";
+
+// ============================================================================
+// Backward-Compatible Type Aliases
+// ============================================================================
+
+/**
+ * @deprecated Use DrawerPhase from drawerStateMachine.ts
+ */
+export type RevealDrawerPhase = DrawerPhase;
+
+/**
+ * @deprecated Use RevealPosition from strategies/types.ts
+ */
+export type RevealPositionPx = RevealPosition;
+
+/**
+ * @deprecated Use AnimationState<RevealPosition>
+ */
+export type { AnimationState };
+
+/**
+ * @deprecated Use DrawerState<RevealPosition>
+ */
+export type RevealDrawerState = DrawerState<RevealPosition>;
+
+/**
+ * Configuration for the reveal drawer state machine.
+ */
+export type RevealDrawerConfig = {
+  placement: DrawerPlacement;
+  drawerSize: number;
+};
+
+// Re-export SwipeDirection
+export type { SwipeDirection };
+
+// Re-export getPlacementConfig
+export { getPlacementConfig };
+
+// ============================================================================
+// Backward-Compatible Action Creators
+// ============================================================================
+
+/**
+ * @deprecated Use drawerActions from drawerStateMachine.ts
+ */
+export const revealDrawerActions = drawerActions;
+
+export type RevealDrawerAction = DrawerAction;
+
+// ============================================================================
+// Backward-Compatible Pure Functions
+// ============================================================================
+
+/**
+ * Compute progress from displacement.
+ * @deprecated Use computeProgressFromDisplacement from drawerStateMachine.ts
+ */
+export const computeProgressFromDisplacement = genericComputeProgress;
+
+/**
+ * Compute swipe end target.
+ * @deprecated Use computeSwipeEndTarget from drawerStateMachine.ts
+ */
+export const computeSwipeEndTarget = genericComputeSwipeEndTarget;
+
+/**
+ * Compute drawer offset in pixels from progress.
+ */
+export function computeDrawerOffsetPx(
+  progress: number,
+  drawerSize: number,
+  placement: DrawerPlacement,
+): number {
+  const { sign } = getPlacementConfig(placement);
+  const maxOffsetPx = drawerSize * (REVEAL_DRAWER_CLOSED_OFFSET_PERCENT / 100);
+  const offsetPx = maxOffsetPx * (1 - progress);
+  return sign > 0 ? -offsetPx : offsetPx;
+}
+
+/**
+ * Compute content offset in pixels from progress.
+ */
+export function computeContentOffsetPx(
+  progress: number,
+  drawerSize: number,
+  placement: DrawerPlacement,
+): number {
+  const { sign } = getPlacementConfig(placement);
+  return sign * drawerSize * progress;
+}
+
+/**
+ * Compute position from progress.
+ */
+export function computePositionFromProgress(
+  progress: number,
+  config: RevealDrawerConfig,
+): RevealPosition {
+  return revealStrategy.computePositionFromProgress(progress, config);
+}
+
+/**
+ * Compute target position for open or closed state.
+ */
+export function computeTargetPosition(
+  isOpen: boolean,
+  config: RevealDrawerConfig,
+): RevealPosition {
+  if (isOpen) {
+    return revealStrategy.getOpenPosition(config);
+  }
+  return revealStrategy.getClosedPosition(config);
+}
+
+/**
+ * Determine if animation is needed between two positions.
+ */
+export function shouldAnimate(from: RevealPosition, to: RevealPosition): boolean {
+  const distance = Math.abs(from.contentPx - to.contentPx);
+  return distance > REVEAL_DRAWER_SNAP_THRESHOLD;
+}
+
+/**
+ * Interpolate between two positions.
+ */
+export function interpolatePosition(
+  from: RevealPosition,
+  to: RevealPosition,
+  progress: number,
+): RevealPosition {
+  return revealStrategy.interpolatePosition(from, to, progress);
+}
+
+// ============================================================================
+// Backward-Compatible Initial State
+// ============================================================================
+
+/**
+ * Create initial state for reveal drawer.
+ */
+export function createInitialState(
+  isOpen: boolean,
+  config: RevealDrawerConfig,
+): RevealDrawerState {
+  return createDrawerInitialState(isOpen, revealStrategy, config);
+}
+
+// ============================================================================
+// Backward-Compatible Reducer
+// ============================================================================
+
+/**
+ * Pre-configured reveal drawer reducer.
+ */
+const revealReducer = createDrawerReducer(revealStrategy);
+
+/**
+ * Reveal drawer reducer function.
+ */
+export function revealDrawerReducer(
+  state: RevealDrawerState,
+  action: RevealDrawerAction,
+  config: RevealDrawerConfig,
+): RevealDrawerState {
+  return revealReducer(state, action, config);
+}

package/src/modules/drawer/strategies/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @file Drawer transform strategies module.
+ *
+ * Exports strategy implementations for different drawer animation modes.
+ */
+
+export * from "./types.js";
+export { revealStrategy } from "./revealStrategy.js";
+export { overlayStrategy } from "./overlayStrategy.js";

package/src/modules/drawer/strategies/overlayStrategy.ts

@@ -0,0 +1,133 @@
+/**
+ * @file Overlay mode drawer transform strategy.
+ *
+ * Implements the overlay animation where:
+ * - Drawer slides from ±100% to 0% (slides over content)
+ * - Backdrop opacity changes from 0 to 1
+ */
+
+import type {
+  DrawerTransformStrategy,
+  OverlayPosition,
+  DrawerStrategyConfig,
+} from "./types.js";
+import { getPlacementConfig } from "./types.js";
+
+/**
+ * Snap threshold for overlay mode (in pixels).
+ */
+const OVERLAY_SNAP_THRESHOLD = 1;
+
+// ============================================================================
+// Overlay Strategy Implementation
+// ============================================================================
+
+/**
+ * Overlay mode drawer transform strategy.
+ */
+export const overlayStrategy: DrawerTransformStrategy<OverlayPosition> = {
+  getClosedPosition(config) {
+    const { sign } = getPlacementConfig(config.placement);
+    // For overlay mode, drawer starts off-screen on its anchor side:
+    // - LEFT drawer: closed at -drawerSize (off-screen left)
+    // - RIGHT drawer: closed at +drawerSize (off-screen right)
+    // The sign in PLACEMENT_CONFIG is for content movement direction,
+    // so we negate it for overlay drawer position.
+    return {
+      drawerPx: -sign * config.drawerSize,
+      backdropOpacity: 0,
+    };
+  },
+
+  getOpenPosition() {
+    return {
+      drawerPx: 0,
+      backdropOpacity: 1,
+    };
+  },
+
+  computePositionFromProgress(progress, config) {
+    const { sign } = getPlacementConfig(config.placement);
+    // Negate sign for overlay mode (see getClosedPosition comment)
+    const closedOffset = -sign * config.drawerSize;
+    return {
+      drawerPx: closedOffset * (1 - progress),
+      backdropOpacity: progress,
+    };
+  },
+
+  interpolatePosition(from, to, progress) {
+    return {
+      drawerPx: from.drawerPx + (to.drawerPx - from.drawerPx) * progress,
+      backdropOpacity: from.backdropOpacity + (to.backdropOpacity - from.backdropOpacity) * progress,
+    };
+  },
+
+  shouldAnimate(from, to) {
+    return Math.abs(from.drawerPx - to.drawerPx) > OVERLAY_SNAP_THRESHOLD;
+  },
+
+  applyToDOM(position, elements, config) {
+    const { drawer, backdrop } = elements;
+    const { axis } = getPlacementConfig(config.placement);
+
+    if (drawer) {
+      drawer.style.transition = "none";
+      drawer.style.transform = `translate${axis}(${position.drawerPx}px)`;
+    }
+    if (backdrop) {
+      backdrop.style.opacity = String(position.backdropOpacity);
+      backdrop.style.pointerEvents = position.backdropOpacity > 0 ? "auto" : "none";
+    }
+  },
+
+  clearFromDOM(elements) {
+    const { drawer, backdrop } = elements;
+
+    // Clear all inline styles to restore CSS defaults
+    if (drawer) {
+      drawer.style.transform = "";
+      drawer.style.transition = "";
+    }
+    if (backdrop) {
+      backdrop.style.opacity = "";
+      backdrop.style.pointerEvents = "";
+    }
+  },
+
+  onOpeningStart() {
+    // Overlay mode doesn't need special handling on opening start
+    // The drawer is already positioned via CSS
+  },
+
+  onClosingComplete(elements, config) {
+    const { drawer, backdrop } = elements;
+    const closedTransform = getClosedTransformForPlacement(config);
+
+    // Set to closed state (not clearing - that's clearFromDOM's job)
+    if (drawer) {
+      drawer.style.transform = closedTransform;
+      drawer.style.transition = "";
+    }
+    if (backdrop) {
+      backdrop.style.opacity = "0";
+      backdrop.style.pointerEvents = "none";
+    }
+  },
+};
+
+/**
+ * Get the closed transform string for a placement.
+ */
+function getClosedTransformForPlacement(config: DrawerStrategyConfig): string {
+  switch (config.placement) {
+    case "left":
+      return "translateX(-100%)";
+    case "right":
+      return "translateX(100%)";
+    case "top":
+      return "translateY(-100%)";
+    case "bottom":
+      return "translateY(100%)";
+  }
+}

package/src/modules/drawer/strategies/revealStrategy.ts

@@ -0,0 +1,111 @@
+/**
+ * @file Reveal mode drawer transform strategy.
+ *
+ * Implements the reveal animation where:
+ * - Drawer slides from -30% to 0% (parallax effect)
+ * - Content slides from 0 to +drawerSize (reveals drawer behind)
+ */
+
+import type {
+  DrawerTransformStrategy,
+  RevealPosition,
+} from "./types.js";
+import { getPlacementConfig } from "./types.js";
+import {
+  REVEAL_DRAWER_CLOSED_OFFSET_PERCENT,
+  REVEAL_DRAWER_SNAP_THRESHOLD,
+} from "../revealDrawerConstants.js";
+import {
+  showDrawer,
+  hideDrawer,
+  clearStackingContext,
+  applyStackingContextWithBackground,
+} from "../../../components/window/drawerRevealAnimationUtils.js";
+
+// ============================================================================
+// Reveal Strategy Implementation
+// ============================================================================
+
+/**
+ * Reveal mode drawer transform strategy.
+ */
+export const revealStrategy: DrawerTransformStrategy<RevealPosition> = {
+  getClosedPosition(config) {
+    return this.computePositionFromProgress(0, config);
+  },
+
+  getOpenPosition(config) {
+    return this.computePositionFromProgress(1, config);
+  },
+
+  computePositionFromProgress(progress, config) {
+    const { sign } = getPlacementConfig(config.placement);
+    const maxOffsetPx = config.drawerSize * (REVEAL_DRAWER_CLOSED_OFFSET_PERCENT / 100);
+    const offsetPx = maxOffsetPx * (1 - progress);
+    const drawerPx = sign > 0 ? -offsetPx : offsetPx;
+    const contentPx = sign * config.drawerSize * progress;
+
+    return { drawerPx, contentPx };
+  },
+
+  interpolatePosition(from, to, progress) {
+    return {
+      drawerPx: from.drawerPx + (to.drawerPx - from.drawerPx) * progress,
+      contentPx: from.contentPx + (to.contentPx - from.contentPx) * progress,
+    };
+  },
+
+  shouldAnimate(from, to) {
+    return Math.abs(from.contentPx - to.contentPx) > REVEAL_DRAWER_SNAP_THRESHOLD;
+  },
+
+  applyToDOM(position, elements, config) {
+    const { drawer, content } = elements;
+    const { axis } = getPlacementConfig(config.placement);
+
+    if (drawer) {
+      drawer.style.transition = "none";
+      drawer.style.transform = `translate${axis}(${position.drawerPx}px)`;
+    }
+    if (content) {
+      applyStackingContextWithBackground(content, config.contentBackground);
+      content.style.transition = "none";
+      content.style.transform = `translate${axis}(${position.contentPx}px)`;
+    }
+  },
+
+  clearFromDOM(elements) {
+    const { drawer, content } = elements;
+
+    if (drawer) {
+      drawer.style.transform = "";
+      drawer.style.transition = "";
+    }
+    if (content) {
+      content.style.transform = "";
+      content.style.transition = "";
+      clearStackingContext(content);
+    }
+  },
+
+  onOpeningStart(elements) {
+    if (elements.drawer) {
+      showDrawer(elements.drawer);
+    }
+  },
+
+  onClosingComplete(elements) {
+    const { drawer, content } = elements;
+
+    if (drawer) {
+      hideDrawer(drawer);
+      drawer.style.transform = "";
+      drawer.style.transition = "";
+    }
+    if (content) {
+      content.style.transform = "";
+      content.style.transition = "";
+      clearStackingContext(content);
+    }
+  },
+};

package/src/modules/drawer/strategies/types.ts

@@ -0,0 +1,160 @@
+/**
+ * @file Drawer transform strategy types.
+ *
+ * Defines the strategy pattern interface for different drawer animation modes.
+ * Each mode (reveal, overlay) implements this interface with mode-specific
+ * position calculations and DOM operations.
+ */
+
+import type { DrawerPlacement } from "../../../components/window/drawerStyles.js";
+
+// ============================================================================
+// Position Types
+// ============================================================================
+
+/**
+ * Position values for reveal mode.
+ * - Drawer moves from -30% to 0%
+ * - Content moves from 0 to +drawerSize
+ */
+export type RevealPosition = {
+  /** Drawer offset in pixels */
+  drawerPx: number;
+  /** Content offset in pixels */
+  contentPx: number;
+};
+
+/**
+ * Position values for overlay mode.
+ * - Drawer moves from ±100% to 0%
+ * - Backdrop opacity changes from 0 to 1
+ */
+export type OverlayPosition = {
+  /** Drawer offset in pixels */
+  drawerPx: number;
+  /** Backdrop opacity (0-1) */
+  backdropOpacity: number;
+};
+
+// ============================================================================
+// Configuration Types
+// ============================================================================
+
+/**
+ * Configuration for drawer strategy calculations.
+ */
+export type DrawerStrategyConfig = {
+  /** Drawer placement (left, right, top, bottom) */
+  placement: DrawerPlacement;
+  /** Drawer size in pixels */
+  drawerSize: number;
+  /** Content background color (reveal mode) */
+  contentBackground?: string;
+};
+
+/**
+ * DOM elements used by drawer strategies.
+ */
+export type DrawerElements = {
+  /** Drawer element */
+  drawer: HTMLElement | null;
+  /** Content element (reveal mode) */
+  content: HTMLElement | null;
+  /** Backdrop element (overlay mode) */
+  backdrop: HTMLElement | null;
+};
+
+// ============================================================================
+// Placement Configuration
+// ============================================================================
+
+/**
+ * Placement configuration for transform calculations.
+ */
+export type PlacementConfig = {
+  /** Transform axis (X or Y) */
+  axis: "X" | "Y";
+  /** Sign for transform direction (1 or -1) */
+  sign: 1 | -1;
+};
+
+/**
+ * Lookup table for placement configuration.
+ */
+export const PLACEMENT_CONFIG: Record<DrawerPlacement, PlacementConfig> = {
+  left: { axis: "X", sign: 1 },
+  right: { axis: "X", sign: -1 },
+  top: { axis: "Y", sign: 1 },
+  bottom: { axis: "Y", sign: -1 },
+};
+
+/**
+ * Get placement configuration for a drawer placement.
+ */
+export function getPlacementConfig(placement: DrawerPlacement): PlacementConfig {
+  return PLACEMENT_CONFIG[placement];
+}
+
+// ============================================================================
+// Strategy Interface
+// ============================================================================
+
+/**
+ * Strategy interface for drawer transform calculations.
+ *
+ * Each drawer mode (reveal, overlay) implements this interface to provide
+ * mode-specific position calculations and DOM operations while sharing
+ * the common state machine logic.
+ *
+ * @typeParam TPosition - The position type used by this strategy
+ */
+export type DrawerTransformStrategy<TPosition> = {
+  /**
+   * Get the closed position (progress = 0).
+   */
+  getClosedPosition: (config: DrawerStrategyConfig) => TPosition;
+
+  /**
+   * Get the open position (progress = 1).
+   */
+  getOpenPosition: (config: DrawerStrategyConfig) => TPosition;
+
+  /**
+   * Compute position from progress (0 = closed, 1 = open).
+   */
+  computePositionFromProgress: (progress: number, config: DrawerStrategyConfig) => TPosition;
+
+  /**
+   * Interpolate between two positions.
+   */
+  interpolatePosition: (from: TPosition, to: TPosition, progress: number) => TPosition;
+
+  /**
+   * Determine if animation is needed between two positions.
+   */
+  shouldAnimate: (from: TPosition, to: TPosition) => boolean;
+
+  /**
+   * Apply position to DOM elements.
+   */
+  applyToDOM: (
+    position: TPosition,
+    elements: DrawerElements,
+    config: DrawerStrategyConfig,
+  ) => void;
+
+  /**
+   * Clear transforms from DOM elements.
+   */
+  clearFromDOM: (elements: DrawerElements, config: DrawerStrategyConfig) => void;
+
+  /**
+   * Called when opening animation starts (optional).
+   */
+  onOpeningStart?: (elements: DrawerElements, config: DrawerStrategyConfig) => void;
+
+  /**
+   * Called when closing animation completes (optional).
+   */
+  onClosingComplete?: (elements: DrawerElements, config: DrawerStrategyConfig) => void;
+};