react-panel-layout 0.6.0 → 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

@@ -0,0 +1,302 @@
+/**
+ * @file Tests for drawerStyles utilities.
+ */
+import {
+  getPlacementStyle,
+  getOpenTransform,
+  getClosedTransform,
+  getRevealTransform,
+  computeTransitionValue,
+  computeBackdropTransition,
+  isHorizontalPlacement,
+  formatDimension,
+  computeEdgeZoneStyle,
+} from "./drawerStyles.js";
+
+describe("drawerStyles", () => {
+  describe("getPlacementStyle", () => {
+    it("returns correct style for left placement", () => {
+      const style = getPlacementStyle("left");
+      expect(style.left).toBe(0);
+      expect(style.top).toBe(0);
+      expect(style.bottom).toBe(0);
+      expect(style.transform).toBe("translateX(-100%)");
+    });
+
+    it("returns correct style for right placement", () => {
+      const style = getPlacementStyle("right");
+      expect(style.right).toBe(0);
+      expect(style.top).toBe(0);
+      expect(style.bottom).toBe(0);
+      expect(style.transform).toBe("translateX(100%)");
+    });
+
+    it("returns correct style for top placement", () => {
+      const style = getPlacementStyle("top");
+      expect(style.top).toBe(0);
+      expect(style.left).toBe(0);
+      expect(style.right).toBe(0);
+      expect(style.transform).toBe("translateY(-100%)");
+    });
+
+    it("returns correct style for bottom placement", () => {
+      const style = getPlacementStyle("bottom");
+      expect(style.bottom).toBe(0);
+      expect(style.left).toBe(0);
+      expect(style.right).toBe(0);
+      expect(style.transform).toBe("translateY(100%)");
+    });
+  });
+
+  describe("getOpenTransform", () => {
+    it("returns translateX(0) for horizontal placements", () => {
+      expect(getOpenTransform("left")).toBe("translateX(0)");
+      expect(getOpenTransform("right")).toBe("translateX(0)");
+    });
+
+    it("returns translateY(0) for vertical placements", () => {
+      expect(getOpenTransform("top")).toBe("translateY(0)");
+      expect(getOpenTransform("bottom")).toBe("translateY(0)");
+    });
+  });
+
+  describe("getClosedTransform", () => {
+    it("returns correct closed transform for each placement", () => {
+      expect(getClosedTransform("left")).toBe("translateX(-100%)");
+      expect(getClosedTransform("right")).toBe("translateX(100%)");
+      expect(getClosedTransform("top")).toBe("translateY(-100%)");
+      expect(getClosedTransform("bottom")).toBe("translateY(100%)");
+    });
+  });
+
+  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();
+    });
+
+    it("returns transition with defaults when no values provided", () => {
+      const result = computeTransitionValue(undefined, undefined, undefined);
+      expect(result).toContain("transform");
+    });
+
+    it("uses provided duration and easing", () => {
+      const result = computeTransitionValue("css", "300ms", "ease-in-out");
+      expect(result).toBe("transform 300ms ease-in-out");
+    });
+  });
+
+  describe("computeBackdropTransition", () => {
+    it("returns undefined when mode is none", () => {
+      expect(computeBackdropTransition("none", undefined)).toBeUndefined();
+    });
+
+    it("returns opacity transition with defaults", () => {
+      const result = computeBackdropTransition(undefined, undefined);
+      expect(result).toContain("opacity");
+      expect(result).toContain("220ms");
+    });
+
+    it("uses provided duration", () => {
+      const result = computeBackdropTransition("css", "400ms");
+      expect(result).toBe("opacity 400ms ease");
+    });
+  });
+
+  describe("isHorizontalPlacement", () => {
+    it("returns true for left and right", () => {
+      expect(isHorizontalPlacement("left")).toBe(true);
+      expect(isHorizontalPlacement("right")).toBe(true);
+    });
+
+    it("returns false for top and bottom", () => {
+      expect(isHorizontalPlacement("top")).toBe(false);
+      expect(isHorizontalPlacement("bottom")).toBe(false);
+    });
+  });
+
+  describe("formatDimension", () => {
+    it("returns undefined for undefined input", () => {
+      expect(formatDimension(undefined)).toBeUndefined();
+    });
+
+    it("returns number with px suffix", () => {
+      expect(formatDimension(100)).toBe("100px");
+      expect(formatDimension(0)).toBe("0px");
+    });
+
+    it("returns string as-is", () => {
+      expect(formatDimension("50%")).toBe("50%");
+      expect(formatDimension("auto")).toBe("auto");
+    });
+  });
+
+  describe("computeEdgeZoneStyle", () => {
+    describe("positioning context", () => {
+      it("uses fixed positioning when inline is false", () => {
+        const style = computeEdgeZoneStyle({
+          placement: "left",
+          inline: false,
+          edgeWidth: 20,
+          zIndex: 1000,
+        });
+        expect(style.position).toBe("fixed");
+      });
+
+      it("uses absolute positioning when inline is true", () => {
+        const style = computeEdgeZoneStyle({
+          placement: "left",
+          inline: true,
+          edgeWidth: 20,
+          zIndex: 1000,
+        });
+        expect(style.position).toBe("absolute");
+      });
+    });
+
+    describe("left placement", () => {
+      it("positions at left edge with correct dimensions", () => {
+        const style = computeEdgeZoneStyle({
+          placement: "left",
+          inline: false,
+          edgeWidth: 20,
+          zIndex: 1000,
+        });
+        expect(style.left).toBe(0);
+        expect(style.top).toBe(0);
+        expect(style.bottom).toBe(0);
+        expect(style.width).toBe(20);
+        expect(style.right).toBeUndefined();
+      });
+    });
+
+    describe("right placement", () => {
+      it("positions at right edge with correct dimensions", () => {
+        const style = computeEdgeZoneStyle({
+          placement: "right",
+          inline: false,
+          edgeWidth: 30,
+          zIndex: 2000,
+        });
+        expect(style.right).toBe(0);
+        expect(style.top).toBe(0);
+        expect(style.bottom).toBe(0);
+        expect(style.width).toBe(30);
+        expect(style.left).toBeUndefined();
+      });
+    });
+
+    describe("top placement", () => {
+      it("positions at top edge with correct dimensions", () => {
+        const style = computeEdgeZoneStyle({
+          placement: "top",
+          inline: false,
+          edgeWidth: 25,
+          zIndex: 1000,
+        });
+        expect(style.top).toBe(0);
+        expect(style.left).toBe(0);
+        expect(style.right).toBe(0);
+        expect(style.height).toBe(25);
+        expect(style.bottom).toBeUndefined();
+      });
+    });
+
+    describe("bottom placement", () => {
+      it("positions at bottom edge with correct dimensions", () => {
+        const style = computeEdgeZoneStyle({
+          placement: "bottom",
+          inline: false,
+          edgeWidth: 40,
+          zIndex: 1000,
+        });
+        expect(style.bottom).toBe(0);
+        expect(style.left).toBe(0);
+        expect(style.right).toBe(0);
+        expect(style.height).toBe(40);
+        expect(style.top).toBeUndefined();
+      });
+    });
+
+    describe("zIndex handling", () => {
+      it("sets zIndex to provided value minus 2", () => {
+        const style = computeEdgeZoneStyle({
+          placement: "left",
+          inline: false,
+          edgeWidth: 20,
+          zIndex: 1000,
+        });
+        expect(style.zIndex).toBe(998);
+      });
+
+      it("uses default zIndex of 1000 when zIndex is undefined", () => {
+        const style = computeEdgeZoneStyle({
+          placement: "left",
+          inline: false,
+          edgeWidth: 20,
+          zIndex: undefined,
+        });
+        expect(style.zIndex).toBe(1000);
+      });
+    });
+
+    describe("common properties", () => {
+      it("has transparent background", () => {
+        const style = computeEdgeZoneStyle({
+          placement: "left",
+          inline: false,
+          edgeWidth: 20,
+          zIndex: 1000,
+        });
+        expect(style.background).toBe("transparent");
+      });
+
+      it("has pointer events enabled", () => {
+        const style = computeEdgeZoneStyle({
+          placement: "left",
+          inline: false,
+          edgeWidth: 20,
+          zIndex: 1000,
+        });
+        expect(style.pointerEvents).toBe("auto");
+      });
+    });
+  });
+});