react-panel-layout 0.6.1 → 0.7.0

package/src/components/window/drawerRevealAnimationUtils.ts

@@ -0,0 +1,415 @@
+/**
+ * @file Drawer reveal animation utilities
+ *
+ * Provides transform calculations for reveal-mode drawer animations.
+ * The reveal mode creates a "pull out" effect where:
+ * - Drawer slides from partially hidden (-30%) to fully visible (0%)
+ * - Content slides away to reveal the drawer behind it
+ */
+
+import type * as React from "react";
+import type { DrawerPlacement } from "./drawerStyles.js";
+
+/**
+ * Percentage offset for drawer when closed (creates "pull out" effect).
+ */
+export const DRAWER_CLOSED_OFFSET_PERCENT = 30;
+
+/**
+ * Default animation duration in milliseconds.
+ */
+export const DEFAULT_ANIMATION_DURATION = 300;
+
+/**
+ * Placement configuration for transforms.
+ */
+export type PlacementConfig = {
+  axis: "X" | "Y";
+  sign: 1 | -1;
+};
+
+/**
+ * Lookup table for placement configuration.
+ */
+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];
+}
+
+/**
+ * Transform values for reveal drawer animation.
+ */
+export type RevealDrawerTransform = {
+  /** Drawer offset in percentage */
+  drawerOffsetPercent: number;
+  /** Content offset in pixels */
+  contentOffsetPx: number;
+};
+
+/**
+ * Compute progress from swipe displacement.
+ * Returns 0 (closed) to 1 (open).
+ *
+ * @param displacement - Current swipe displacement in pixels
+ * @param drawerSize - Size of the drawer in pixels
+ * @param isOpening - Whether the gesture is opening the drawer
+ * @param isClosing - Whether the gesture is closing the drawer
+ * @returns Progress value between 0 and 1
+ */
+export function computeSwipeProgress(
+  displacement: number,
+  drawerSize: number,
+  isOpening: boolean,
+  isClosing: boolean,
+): number {
+  if (drawerSize <= 0) {
+    return 0;
+  }
+
+  if (isOpening) {
+    return Math.min(1, Math.max(0, displacement / drawerSize));
+  }
+  if (isClosing) {
+    return Math.min(1, Math.max(0, 1 - displacement / drawerSize));
+  }
+  return 0;
+}
+
+/**
+ * Compute reveal drawer transforms from progress.
+ *
+ * @param progress - Animation progress (0 = closed, 1 = open)
+ * @param drawerSize - Size of the drawer in pixels
+ * @param placement - Drawer placement
+ * @returns Transform values for drawer and content
+ */
+export function computeRevealTransform(
+  progress: number,
+  drawerSize: number,
+  placement: DrawerPlacement,
+): RevealDrawerTransform {
+  const { sign } = PLACEMENT_CONFIG[placement];
+
+  // Drawer moves from -30% (closed) to 0% (open)
+  // For left: -30% to 0%
+  // For right: +30% to 0%
+  const offsetPercent = DRAWER_CLOSED_OFFSET_PERCENT * (1 - progress);
+  const drawerOffsetPercent = sign > 0 ? -offsetPercent : offsetPercent;
+
+  // Content moves from 0px (closed) to drawerSize (open)
+  const contentOffsetPx = sign * drawerSize * progress;
+
+  return {
+    drawerOffsetPercent,
+    contentOffsetPx,
+  };
+}
+
+/**
+ * Build drawer transform string from progress.
+ *
+ * @param progress - Animation progress (0 = closed, 1 = open)
+ * @param placement - Drawer placement
+ * @returns CSS transform string
+ */
+export function buildDrawerTransformString(
+  progress: number,
+  placement: DrawerPlacement,
+): string {
+  const { axis } = PLACEMENT_CONFIG[placement];
+  const transform = computeRevealTransform(progress, 0, placement);
+  return `translate${axis}(${transform.drawerOffsetPercent}%)`;
+}
+
+/**
+ * Build content transform string from progress.
+ *
+ * @param progress - Animation progress (0 = closed, 1 = open)
+ * @param drawerSize - Size of the drawer in pixels
+ * @param placement - Drawer placement
+ * @returns CSS transform string
+ */
+export function buildContentTransformString(
+  progress: number,
+  drawerSize: number,
+  placement: DrawerPlacement,
+): string {
+  const { axis } = PLACEMENT_CONFIG[placement];
+  const transform = computeRevealTransform(progress, drawerSize, placement);
+  return `translate${axis}(${transform.contentOffsetPx}px)`;
+}
+
+/**
+ * Stacking context styles for content element.
+ * Applied during reveal animation to ensure proper z-index layering.
+ */
+export type StackingContextStyles = {
+  position: string;
+  zIndex: string;
+  background: string;
+};
+
+/**
+ * Default stacking context styles.
+ */
+export const STACKING_CONTEXT_STYLES: StackingContextStyles = {
+  position: "relative",
+  zIndex: "1",
+  background: "#fff",
+};
+
+/**
+ * Apply stacking context styles to an element.
+ */
+export function applyStackingContext(element: HTMLElement): void {
+  element.style.position = STACKING_CONTEXT_STYLES.position;
+  element.style.zIndex = STACKING_CONTEXT_STYLES.zIndex;
+  element.style.background = STACKING_CONTEXT_STYLES.background;
+}
+
+/**
+ * Clear stacking context styles from an element.
+ */
+export function clearStackingContext(element: HTMLElement): void {
+  element.style.position = "";
+  element.style.zIndex = "";
+  element.style.background = "";
+}
+
+/**
+ * Apply overflow hidden to body to prevent scrolling during drawer open.
+ * This prevents both horizontal and vertical scrolling of the body
+ * while the drawer is open or animating.
+ */
+export function applyOverflowHidden(): void {
+  document.body.style.overflow = "hidden";
+}
+
+/**
+ * Clear overflow hidden from body.
+ */
+export function clearOverflowHidden(): void {
+  document.body.style.overflow = "";
+}
+
+/**
+ * Get the content element to transform.
+ *
+ * @param inline - Whether drawer is inline mode
+ * @param gridRef - Grid container ref for inline mode
+ * @returns The content element or null
+ */
+export function getContentElement(
+  inline: boolean,
+  gridRef?: React.RefObject<HTMLElement | null>,
+): HTMLElement | null {
+  if (inline) {
+    return gridRef?.current ?? null;
+  }
+  return document.getElementById("root") ?? (document.body.firstElementChild as HTMLElement | null);
+}
+
+// ============================================================================
+// Pixel-based transform computation (for animation continuity)
+// ============================================================================
+
+/**
+ * Tracked position for drawer and content elements in pixels.
+ */
+export type RevealPositionPx = {
+  /** Drawer offset in pixels */
+  drawerPx: number;
+  /** Content offset in pixels */
+  contentPx: number;
+};
+
+/**
+ * Compute drawer offset in pixels from progress.
+ *
+ * For reveal mode, the drawer animates from an offset position to 0.
+ * The offset is DRAWER_CLOSED_OFFSET_PERCENT of the drawer's own size.
+ *
+ * @param progress - Animation progress (0 = closed, 1 = open)
+ * @param drawerSize - Drawer size in pixels
+ * @param placement - Drawer placement
+ * @returns Drawer offset in pixels
+ */
+export function computeDrawerOffsetPx(
+  progress: number,
+  drawerSize: number,
+  placement: DrawerPlacement,
+): number {
+  const { sign } = PLACEMENT_CONFIG[placement];
+  // Drawer offset at closed state: -30% of drawer size (or +30% for right/bottom)
+  const maxOffsetPx = drawerSize * (DRAWER_CLOSED_OFFSET_PERCENT / 100);
+  const offsetPx = maxOffsetPx * (1 - progress);
+  return sign > 0 ? -offsetPx : offsetPx;
+}
+
+/**
+ * Compute content offset in pixels from progress.
+ *
+ * Content moves from 0 (closed) to ±drawerSize (open).
+ *
+ * @param progress - Animation progress (0 = closed, 1 = open)
+ * @param drawerSize - Drawer size in pixels
+ * @param placement - Drawer placement
+ * @returns Content offset in pixels
+ */
+export function computeContentOffsetPx(
+  progress: number,
+  drawerSize: number,
+  placement: DrawerPlacement,
+): number {
+  const { sign } = PLACEMENT_CONFIG[placement];
+  return sign * drawerSize * progress;
+}
+
+/**
+ * Compute both drawer and content offsets from progress.
+ *
+ * @param progress - Animation progress (0 = closed, 1 = open)
+ * @param drawerSize - Drawer size in pixels
+ * @param placement - Drawer placement
+ * @returns Position in pixels for both elements
+ */
+export function computePositionFromProgress(
+  progress: number,
+  drawerSize: number,
+  placement: DrawerPlacement,
+): RevealPositionPx {
+  return {
+    drawerPx: computeDrawerOffsetPx(progress, drawerSize, placement),
+    contentPx: computeContentOffsetPx(progress, drawerSize, placement),
+  };
+}
+
+/**
+ * Compute target positions for open or closed state.
+ *
+ * @param isOpen - Whether target is the open state
+ * @param drawerSize - Drawer size in pixels
+ * @param placement - Drawer placement
+ * @returns Target positions in pixels
+ */
+export function computeTargetPosition(
+  isOpen: boolean,
+  drawerSize: number,
+  placement: DrawerPlacement,
+): RevealPositionPx {
+  const targetProgress = isOpen ? 1 : 0;
+  return computePositionFromProgress(targetProgress, drawerSize, placement);
+}
+
+/**
+ * Compute position from swipe displacement.
+ *
+ * This is the main function for tracking position during swipe.
+ *
+ * @param displacement - Current swipe displacement in pixels
+ * @param drawerSize - Drawer size in pixels
+ * @param placement - Drawer placement
+ * @param isOpening - Whether opening via swipe
+ * @param isClosing - Whether closing via swipe
+ * @returns Current position in pixels
+ */
+export function computePositionFromDisplacement(
+  displacement: number,
+  drawerSize: number,
+  placement: DrawerPlacement,
+  isOpening: boolean,
+  isClosing: boolean,
+): RevealPositionPx {
+  const progress = computeSwipeProgress(displacement, drawerSize, isOpening, isClosing);
+  return computePositionFromProgress(progress, drawerSize, placement);
+}
+
+// ============================================================================
+// Pixel-based transform string builders
+// ============================================================================
+
+/**
+ * Build drawer transform string from pixel offset.
+ *
+ * @param drawerPx - Drawer offset in pixels
+ * @param placement - Drawer placement
+ * @returns CSS transform string
+ */
+export function buildDrawerTransformPx(
+  drawerPx: number,
+  placement: DrawerPlacement,
+): string {
+  const { axis } = PLACEMENT_CONFIG[placement];
+  return `translate${axis}(${drawerPx}px)`;
+}
+
+/**
+ * Build content transform string from pixel offset.
+ *
+ * @param contentPx - Content offset in pixels
+ * @param placement - Drawer placement
+ * @returns CSS transform string
+ */
+export function buildContentTransformPx(
+  contentPx: number,
+  placement: DrawerPlacement,
+): string {
+  const { axis } = PLACEMENT_CONFIG[placement];
+  return `translate${axis}(${contentPx}px)`;
+}
+
+// ============================================================================
+// Visibility management
+// ============================================================================
+
+/**
+ * Show the drawer element.
+ */
+export function showDrawer(element: HTMLElement): void {
+  element.style.visibility = "visible";
+  element.style.pointerEvents = "auto";
+}
+
+/**
+ * Hide the drawer element.
+ */
+export function hideDrawer(element: HTMLElement): void {
+  element.style.visibility = "hidden";
+  element.style.pointerEvents = "none";
+}
+
+/**
+ * Clear drawer visibility styles.
+ */
+export function clearDrawerVisibility(element: HTMLElement): void {
+  element.style.visibility = "";
+  element.style.pointerEvents = "";
+}
+
+// ============================================================================
+// Stacking context with configurable background
+// ============================================================================
+
+/**
+ * Apply stacking context styles with configurable background.
+ *
+ * @param element - Content element
+ * @param background - Background color (defaults to #fff)
+ */
+export function applyStackingContextWithBackground(
+  element: HTMLElement,
+  background: string = STACKING_CONTEXT_STYLES.background,
+): void {
+  element.style.position = STACKING_CONTEXT_STYLES.position;
+  element.style.zIndex = STACKING_CONTEXT_STYLES.zIndex;
+  element.style.background = background;
+}

package/src/components/window/drawerStyles.spec.ts

@@ -5,6 +5,7 @@ import {
   getPlacementStyle,
   getOpenTransform,
   getClosedTransform,
+  getRevealTransform,
   computeTransitionValue,
   computeBackdropTransition,
   isHorizontalPlacement,
@@ -68,6 +69,44 @@ describe("drawerStyles", () => {
     });
   });
 
+  describe("getRevealTransform", () => {
+    describe("when drawer is closed", () => {
+      it("returns -30% offset for left placement", () => {
+        expect(getRevealTransform("left", false)).toBe("translateX(-30%)");
+      });
+
+      it("returns +30% offset for right placement", () => {
+        expect(getRevealTransform("right", false)).toBe("translateX(30%)");
+      });
+
+      it("returns -30% offset for top placement", () => {
+        expect(getRevealTransform("top", false)).toBe("translateY(-30%)");
+      });
+
+      it("returns +30% offset for bottom placement", () => {
+        expect(getRevealTransform("bottom", false)).toBe("translateY(30%)");
+      });
+    });
+
+    describe("when drawer is open", () => {
+      it("returns translateX(0) for left placement", () => {
+        expect(getRevealTransform("left", true)).toBe("translateX(0)");
+      });
+
+      it("returns translateX(0) for right placement", () => {
+        expect(getRevealTransform("right", true)).toBe("translateX(0)");
+      });
+
+      it("returns translateY(0) for top placement", () => {
+        expect(getRevealTransform("top", true)).toBe("translateY(0)");
+      });
+
+      it("returns translateY(0) for bottom placement", () => {
+        expect(getRevealTransform("bottom", true)).toBe("translateY(0)");
+      });
+    });
+  });
+
   describe("computeTransitionValue", () => {
     it("returns undefined when mode is none", () => {
       expect(computeTransitionValue("none", undefined, undefined)).toBeUndefined();

package/src/components/window/drawerStyles.ts

@@ -66,6 +66,19 @@ const OPEN_TRANSFORMS: Record<DrawerPlacement, string> = {
   bottom: "translateY(0)",
 };
 
+/**
+ * Reveal mode: drawer starts partially hidden and slides in with content.
+ * This creates a "pull out" effect rather than just content sliding away.
+ */
+const REVEAL_CLOSED_OFFSET_PERCENT = 30;
+
+const REVEAL_CLOSED_TRANSFORMS: Record<DrawerPlacement, string> = {
+  left: `translateX(-${REVEAL_CLOSED_OFFSET_PERCENT}%)`,
+  right: `translateX(${REVEAL_CLOSED_OFFSET_PERCENT}%)`,
+  top: `translateY(-${REVEAL_CLOSED_OFFSET_PERCENT}%)`,
+  bottom: `translateY(${REVEAL_CLOSED_OFFSET_PERCENT}%)`,
+};
+
 /**
  * Get placement-specific style.
  */
@@ -87,6 +100,17 @@ export function getClosedTransform(placement: DrawerPlacement): string {
   return PLACEMENT_STYLES[placement].transform as string;
 }
 
+/**
+ * Get reveal mode transform based on open state.
+ * When closed, drawer is partially hidden. When open, fully visible.
+ */
+export function getRevealTransform(placement: DrawerPlacement, isOpen: boolean): string {
+  if (isOpen) {
+    return OPEN_TRANSFORMS[placement];
+  }
+  return REVEAL_CLOSED_TRANSFORMS[placement];
+}
+
 /**
  * Compute CSS transition value.
  */

package/src/components/window/useDrawerSwipeTransform.ts

@@ -1,12 +1,15 @@
 /**
- * @file Hook for applying real-time transform during drawer swipe gestures.
+ * @file Hook for applying real-time transform during drawer swipe gestures (backward-compatible wrapper).
  *
- * Handles DOM manipulation for smooth swipe animations.
+ * This hook is a thin wrapper around useDrawerTransform with mode="overlay".
+ * For new code, prefer using useDrawerTransform directly.
+ *
+ * @deprecated Use useDrawerTransform with mode="overlay" instead.
  */
 import * as React from "react";
 import type { ContinuousOperationState } from "../../hooks/gesture/types.js";
-import { getDrawerAnimationAxis, getDrawerCloseSwipeSign } from "../../modules/drawer/types.js";
 import type { DrawerSwipeDirection } from "../../modules/drawer/types.js";
+import { useDrawerTransform } from "./useDrawerTransform.js";
 
 type UseDrawerSwipeTransformOptions = {
   drawerRef: React.RefObject<HTMLDivElement | null>;
@@ -16,11 +19,14 @@ type UseDrawerSwipeTransformOptions = {
   displacement: number;
   isOpening: boolean;
   isClosing: boolean;
+  isOpen: boolean;
   enabled: boolean;
 };
 
 /**
  * Apply real-time transform to drawer and backdrop during swipe.
+ *
+ * @deprecated Use useDrawerTransform with mode="overlay" instead.
  */
 export function useDrawerSwipeTransform(options: UseDrawerSwipeTransformOptions): void {
   const {
@@ -31,99 +37,31 @@ export function useDrawerSwipeTransform(options: UseDrawerSwipeTransformOptions)
     displacement,
     isOpening,
     isClosing,
+    isOpen,
     enabled,
   } = options;
 
-  const isOperating = swipeState.phase === "operating";
-
-  // Apply real-time transform during swipe
-  React.useLayoutEffect(() => {
-    if (!enabled || !isOperating) {
-      return;
-    }
-
-    const drawer = drawerRef.current;
-    const backdrop = backdropRef.current;
-
-    if (!drawer) {
-      return;
-    }
-
-    const axis = getDrawerAnimationAxis(placement);
-    const closeSign = getDrawerCloseSwipeSign(placement);
-    const drawerSize = axis === "x" ? drawer.clientWidth : drawer.clientHeight;
-
-    if (drawerSize <= 0) {
-      return;
-    }
-
-    const translateFn = axis === "x" ? "translateX" : "translateY";
-
-    if (isClosing) {
-      applyClosingTransform(drawer, backdrop, translateFn, closeSign, displacement, drawerSize);
-    } else if (isOpening) {
-      applyOpeningTransform(drawer, backdrop, translateFn, closeSign, displacement, drawerSize);
-    }
-  }, [enabled, isOperating, isClosing, isOpening, displacement, placement, drawerRef, backdropRef]);
-
-  // Reset transform after swipe ends
+  // Get drawer size from element
+  const drawerSizeRef = React.useRef(0);
   React.useLayoutEffect(() => {
-    if (!enabled || swipeState.phase !== "ended") {
-      return;
-    }
-
     const drawer = drawerRef.current;
-    const backdrop = backdropRef.current;
-
     if (drawer) {
-      drawer.style.transform = "";
-    }
-    if (backdrop) {
-      backdrop.style.opacity = "";
+      const isHorizontal = placement === "left" || placement === "right";
+      drawerSizeRef.current = isHorizontal ? drawer.clientWidth : drawer.clientHeight;
     }
-  }, [enabled, swipeState.phase, drawerRef, backdropRef]);
-}
-
-function applyClosingTransform(
-  drawer: HTMLDivElement,
-  backdrop: HTMLDivElement | null,
-  translateFn: "translateX" | "translateY",
-  closeSign: 1 | -1,
-  displacement: number,
-  drawerSize: number,
-): void {
-  const translate = closeSign * displacement;
-  drawer.style.transform = `${translateFn}(${translate}px)`;
-
-  const progress = Math.min(displacement / drawerSize, 1);
-  if (backdrop) {
-    backdrop.style.opacity = String(1 - progress);
-  }
-}
-
-function applyOpeningTransform(
-  drawer: HTMLDivElement,
-  backdrop: HTMLDivElement | null,
-  translateFn: "translateX" | "translateY",
-  closeSign: 1 | -1,
-  displacement: number,
-  drawerSize: number,
-): void {
-  const closedPosition = closeSign * drawerSize;
-  const translate = closedPosition + closeSign * -1 * displacement;
-  const clampedTranslate = clampTranslate(translate, closeSign);
-  drawer.style.transform = `${translateFn}(${clampedTranslate}px)`;
-
-  const progress = Math.min(displacement / drawerSize, 1);
-  if (backdrop) {
-    backdrop.style.opacity = String(progress);
-    backdrop.style.pointerEvents = "auto";
-  }
-}
+  }, [drawerRef, placement]);
 
-function clampTranslate(translate: number, closeSign: 1 | -1): number {
-  if (closeSign > 0) {
-    return Math.max(0, translate);
-  }
-  return Math.min(0, translate);
+  useDrawerTransform({
+    mode: "overlay",
+    drawerRef,
+    backdropRef,
+    placement,
+    drawerSize: drawerSizeRef.current,
+    isOpen,
+    swipeState,
+    displacement,
+    isOpening,
+    isClosing,
+    enabled,
+  });
 }