react-panel-layout 0.6.1 → 0.7.1

package/src/components/window/DrawerLayers.tsx

@@ -2,34 +2,60 @@
  * @file DrawerLayers component
  */
 import * as React from "react";
+import * as ReactDOM from "react-dom";
 import type { LayerDefinition } from "../../types.js";
 import { Drawer } from "./Drawer.js";
 import { useDrawerState } from "../../modules/window/useDrawerState.js";
+import { isRevealMode } from "./DrawerRevealContext.js";
 
 export type DrawerLayersProps = {
   layers: LayerDefinition[];
 };
 
+/**
+ * Check if a drawer should be rendered in a portal (outside #root).
+ * Reveal mode + non-inline drawers need to be outside #root so they
+ * don't move when #root is transformed.
+ */
+function shouldUsePortal(layer: LayerDefinition): boolean {
+  if (!layer.drawer) {
+    return false;
+  }
+  const { animationMode, inline = false } = layer.drawer;
+  if (!isRevealMode(animationMode)) {
+    return false;
+  }
+  return !inline;
+}
+
+/**
+ * Create a map of layer ID to handler function.
+ */
+function createHandlerMap(
+  layers: LayerDefinition[],
+  createHandler: (layerId: string) => () => void,
+): Map<string, () => void> {
+  const handlers = new Map<string, () => void>();
+  layers.forEach((layer) => {
+    handlers.set(layer.id, createHandler(layer.id));
+  });
+  return handlers;
+}
+
 export const DrawerLayers: React.FC<DrawerLayersProps> = ({ layers }) => {
   const drawer = useDrawerState(layers);
 
   const drawerLayers = React.useMemo(() => layers.filter((layer) => layer.drawer), [layers]);
 
-  const closeHandlers = React.useMemo(() => {
-    const handlers = new Map<string, () => void>();
-    drawerLayers.forEach((layer) => {
-      handlers.set(layer.id, () => drawer.close(layer.id));
-    });
-    return handlers;
-  }, [drawerLayers, drawer.close]);
+  const closeHandlers = React.useMemo(
+    () => createHandlerMap(drawerLayers, (id) => () => drawer.close(id)),
+    [drawerLayers, drawer.close],
+  );
 
-  const openHandlers = React.useMemo(() => {
-    const handlers = new Map<string, () => void>();
-    drawerLayers.forEach((layer) => {
-      handlers.set(layer.id, () => drawer.open(layer.id));
-    });
-    return handlers;
-  }, [drawerLayers, drawer.open]);
+  const openHandlers = React.useMemo(
+    () => createHandlerMap(drawerLayers, (id) => () => drawer.open(id)),
+    [drawerLayers, drawer.open],
+  );
 
   return (
     <>
@@ -46,7 +72,7 @@ export const DrawerLayers: React.FC<DrawerLayersProps> = ({ layers }) => {
           return null;
         }
 
-        return (
+        const drawerElement = (
           <Drawer
             key={layer.id}
             id={layer.id}
@@ -62,6 +88,13 @@ export const DrawerLayers: React.FC<DrawerLayersProps> = ({ layers }) => {
             {layer.component}
           </Drawer>
         );
+
+        // Render reveal-mode (non-inline) drawers in a portal to document.body
+        if (shouldUsePortal(layer)) {
+          return ReactDOM.createPortal(drawerElement, document.body);
+        }
+
+        return drawerElement;
       })}
     </>
   );

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

@@ -0,0 +1,20 @@
+/**
+ * @file Tests for DrawerRevealContext utilities.
+ */
+import { isRevealMode } from "./DrawerRevealContext.js";
+
+describe("DrawerRevealContext", () => {
+  describe("isRevealMode", () => {
+    it("returns true for reveal animation mode", () => {
+      expect(isRevealMode("reveal")).toBe(true);
+    });
+
+    it("returns false for overlay animation mode", () => {
+      expect(isRevealMode("overlay")).toBe(false);
+    });
+
+    it("returns false for undefined animation mode", () => {
+      expect(isRevealMode(undefined)).toBe(false);
+    });
+  });
+});

package/src/components/window/DrawerRevealContext.tsx

@@ -0,0 +1,99 @@
+/**
+ * @file Context for coordinating reveal-mode drawer animations with GridLayout.
+ *
+ * When a drawer uses animationMode="reveal", the main content needs to slide away
+ * to reveal the drawer behind it. This context provides the communication mechanism
+ * between DrawerLayers and GridLayout.
+ */
+import * as React from "react";
+import type { DrawerAnimationMode } from "../../types.js";
+import type { DrawerPlacement } from "./drawerStyles.js";
+
+/**
+ * State for a reveal-mode drawer animation.
+ */
+export type DrawerRevealState = {
+  /** ID of the drawer layer */
+  layerId: string;
+  /** Drawer placement */
+  placement: DrawerPlacement;
+  /** Whether the drawer is currently open */
+  isOpen: boolean;
+  /** Drawer size in pixels (width for left/right, height for top/bottom) */
+  drawerSize: number;
+  /** Whether swipe operation is in progress */
+  isSwipeOperating: boolean;
+  /** Current swipe displacement during operation */
+  swipeDisplacement: number;
+  /** Whether currently opening via swipe */
+  isOpening: boolean;
+  /** Whether currently closing via swipe */
+  isClosing: boolean;
+  /** Whether the drawer is inline (container-relative) or fixed (viewport-relative) */
+  inline: boolean;
+};
+
+/**
+ * Context value provided to GridLayout for reveal-mode animations.
+ */
+export type DrawerRevealContextValue = {
+  /** Currently active reveal-mode drawer (only one at a time) */
+  activeRevealDrawer: DrawerRevealState | null;
+  /** Register/update a reveal-mode drawer state */
+  setRevealState: (state: DrawerRevealState | null) => void;
+  /** Grid container ref for inline mode transforms */
+  gridRef: React.RefObject<HTMLElement | null> | null;
+  /** Set the grid ref (called by GridLayout) */
+  setGridRef: (ref: React.RefObject<HTMLElement | null> | null) => void;
+};
+
+const defaultContextValue: DrawerRevealContextValue = {
+  activeRevealDrawer: null,
+  setRevealState: () => {},
+  gridRef: null,
+  setGridRef: () => {},
+};
+
+export const DrawerRevealContext = React.createContext<DrawerRevealContextValue>(defaultContextValue);
+
+/**
+ * Provider component for DrawerRevealContext.
+ */
+export const DrawerRevealProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
+  const [activeRevealDrawer, setActiveRevealDrawer] = React.useState<DrawerRevealState | null>(null);
+  const [gridRef, setGridRefState] = React.useState<React.RefObject<HTMLElement | null> | null>(null);
+
+  const setRevealState = React.useCallback((state: DrawerRevealState | null) => {
+    setActiveRevealDrawer(state);
+  }, []);
+
+  const setGridRef = React.useCallback((ref: React.RefObject<HTMLElement | null> | null) => {
+    setGridRefState(ref);
+  }, []);
+
+  const value = React.useMemo(
+    (): DrawerRevealContextValue => ({
+      activeRevealDrawer,
+      setRevealState,
+      gridRef,
+      setGridRef,
+    }),
+    [activeRevealDrawer, setRevealState, gridRef, setGridRef],
+  );
+
+  return <DrawerRevealContext.Provider value={value}>{children}</DrawerRevealContext.Provider>;
+};
+
+/**
+ * Hook to consume DrawerRevealContext.
+ */
+export function useDrawerReveal(): DrawerRevealContextValue {
+  return React.useContext(DrawerRevealContext);
+}
+
+/**
+ * Check if the given animation mode is reveal mode.
+ */
+export function isRevealMode(animationMode: DrawerAnimationMode | undefined): boolean {
+  return animationMode === "reveal";
+}

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

@@ -0,0 +1,375 @@
+/**
+ * @file Tests for drawerRevealAnimationUtils.
+ */
+import {
+  DRAWER_CLOSED_OFFSET_PERCENT,
+  DEFAULT_ANIMATION_DURATION,
+  getPlacementConfig,
+  computeSwipeProgress,
+  computeRevealTransform,
+  buildDrawerTransformString,
+  buildContentTransformString,
+  STACKING_CONTEXT_STYLES,
+  computeDrawerOffsetPx,
+  computeContentOffsetPx,
+  computePositionFromProgress,
+  computeTargetPosition,
+  computePositionFromDisplacement,
+  buildDrawerTransformPx,
+  buildContentTransformPx,
+} from "./drawerRevealAnimationUtils.js";
+
+describe("drawerRevealAnimationUtils", () => {
+  describe("constants", () => {
+    it("DRAWER_CLOSED_OFFSET_PERCENT is 30", () => {
+      expect(DRAWER_CLOSED_OFFSET_PERCENT).toBe(30);
+    });
+
+    it("DEFAULT_ANIMATION_DURATION is 300ms", () => {
+      expect(DEFAULT_ANIMATION_DURATION).toBe(300);
+    });
+
+    it("STACKING_CONTEXT_STYLES has expected values", () => {
+      expect(STACKING_CONTEXT_STYLES.position).toBe("relative");
+      expect(STACKING_CONTEXT_STYLES.zIndex).toBe("1");
+      expect(STACKING_CONTEXT_STYLES.background).toBe("#fff");
+    });
+  });
+
+  describe("getPlacementConfig", () => {
+    it("returns X axis for left placement with positive sign", () => {
+      const config = getPlacementConfig("left");
+      expect(config.axis).toBe("X");
+      expect(config.sign).toBe(1);
+    });
+
+    it("returns X axis for right placement with negative sign", () => {
+      const config = getPlacementConfig("right");
+      expect(config.axis).toBe("X");
+      expect(config.sign).toBe(-1);
+    });
+
+    it("returns Y axis for top placement with positive sign", () => {
+      const config = getPlacementConfig("top");
+      expect(config.axis).toBe("Y");
+      expect(config.sign).toBe(1);
+    });
+
+    it("returns Y axis for bottom placement with negative sign", () => {
+      const config = getPlacementConfig("bottom");
+      expect(config.axis).toBe("Y");
+      expect(config.sign).toBe(-1);
+    });
+  });
+
+  describe("computeSwipeProgress", () => {
+    it("returns 0 when drawerSize is 0", () => {
+      expect(computeSwipeProgress(100, 0, true, false)).toBe(0);
+    });
+
+    it("returns 0 when drawerSize is negative", () => {
+      expect(computeSwipeProgress(100, -100, true, false)).toBe(0);
+    });
+
+    it("returns progress based on displacement when opening", () => {
+      expect(computeSwipeProgress(50, 200, true, false)).toBe(0.25);
+      expect(computeSwipeProgress(100, 200, true, false)).toBe(0.5);
+      expect(computeSwipeProgress(200, 200, true, false)).toBe(1);
+    });
+
+    it("clamps progress to 0-1 range when opening", () => {
+      expect(computeSwipeProgress(-50, 200, true, false)).toBe(0);
+      expect(computeSwipeProgress(300, 200, true, false)).toBe(1);
+    });
+
+    it("returns inverted progress when closing", () => {
+      expect(computeSwipeProgress(0, 200, false, true)).toBe(1);
+      expect(computeSwipeProgress(100, 200, false, true)).toBe(0.5);
+      expect(computeSwipeProgress(200, 200, false, true)).toBe(0);
+    });
+
+    it("clamps progress to 0-1 range when closing", () => {
+      expect(computeSwipeProgress(-50, 200, false, true)).toBe(1);
+      expect(computeSwipeProgress(300, 200, false, true)).toBe(0);
+    });
+
+    it("returns 0 when neither opening nor closing", () => {
+      expect(computeSwipeProgress(100, 200, false, false)).toBe(0);
+    });
+  });
+
+  describe("computeRevealTransform", () => {
+    describe("left placement", () => {
+      it("returns -30% drawer offset when closed", () => {
+        const result = computeRevealTransform(0, 300, "left");
+        expect(result.drawerOffsetPercent).toBe(-30);
+        expect(result.contentOffsetPx).toBeCloseTo(0);
+      });
+
+      it("returns 0% drawer offset when open", () => {
+        const result = computeRevealTransform(1, 300, "left");
+        expect(result.drawerOffsetPercent).toBeCloseTo(0);
+        expect(result.contentOffsetPx).toBe(300);
+      });
+
+      it("returns -15% drawer offset at halfway", () => {
+        const result = computeRevealTransform(0.5, 300, "left");
+        expect(result.drawerOffsetPercent).toBe(-15);
+        expect(result.contentOffsetPx).toBe(150);
+      });
+    });
+
+    describe("right placement", () => {
+      it("returns +30% drawer offset when closed", () => {
+        const result = computeRevealTransform(0, 300, "right");
+        expect(result.drawerOffsetPercent).toBe(30);
+        expect(result.contentOffsetPx).toBeCloseTo(0);
+      });
+
+      it("returns 0% drawer offset when open", () => {
+        const result = computeRevealTransform(1, 300, "right");
+        expect(result.drawerOffsetPercent).toBeCloseTo(0);
+        expect(result.contentOffsetPx).toBe(-300);
+      });
+    });
+
+    describe("top placement", () => {
+      it("returns -30% drawer offset when closed", () => {
+        const result = computeRevealTransform(0, 200, "top");
+        expect(result.drawerOffsetPercent).toBe(-30);
+        expect(result.contentOffsetPx).toBeCloseTo(0);
+      });
+
+      it("returns 0% drawer offset when open", () => {
+        const result = computeRevealTransform(1, 200, "top");
+        expect(result.drawerOffsetPercent).toBeCloseTo(0);
+        expect(result.contentOffsetPx).toBe(200);
+      });
+    });
+
+    describe("bottom placement", () => {
+      it("returns +30% drawer offset when closed", () => {
+        const result = computeRevealTransform(0, 200, "bottom");
+        expect(result.drawerOffsetPercent).toBe(30);
+        expect(result.contentOffsetPx).toBeCloseTo(0);
+      });
+
+      it("returns 0% drawer offset when open", () => {
+        const result = computeRevealTransform(1, 200, "bottom");
+        expect(result.drawerOffsetPercent).toBeCloseTo(0);
+        expect(result.contentOffsetPx).toBe(-200);
+      });
+    });
+  });
+
+  describe("buildDrawerTransformString", () => {
+    it("returns correct transform for left placement closed", () => {
+      expect(buildDrawerTransformString(0, "left")).toBe("translateX(-30%)");
+    });
+
+    it("returns correct transform for left placement open", () => {
+      expect(buildDrawerTransformString(1, "left")).toBe("translateX(0%)");
+    });
+
+    it("returns correct transform for right placement closed", () => {
+      expect(buildDrawerTransformString(0, "right")).toBe("translateX(30%)");
+    });
+
+    it("returns correct transform for right placement open", () => {
+      expect(buildDrawerTransformString(1, "right")).toBe("translateX(0%)");
+    });
+
+    it("returns correct transform for top placement closed", () => {
+      expect(buildDrawerTransformString(0, "top")).toBe("translateY(-30%)");
+    });
+
+    it("returns correct transform for top placement open", () => {
+      expect(buildDrawerTransformString(1, "top")).toBe("translateY(0%)");
+    });
+
+    it("returns correct transform for bottom placement closed", () => {
+      expect(buildDrawerTransformString(0, "bottom")).toBe("translateY(30%)");
+    });
+
+    it("returns correct transform for bottom placement open", () => {
+      expect(buildDrawerTransformString(1, "bottom")).toBe("translateY(0%)");
+    });
+  });
+
+  describe("buildContentTransformString", () => {
+    it("returns 0px offset when closed for left placement", () => {
+      expect(buildContentTransformString(0, 300, "left")).toBe("translateX(0px)");
+    });
+
+    it("returns +drawerSize offset when open for left placement", () => {
+      expect(buildContentTransformString(1, 300, "left")).toBe("translateX(300px)");
+    });
+
+    it("returns 0px offset when closed for right placement", () => {
+      expect(buildContentTransformString(0, 300, "right")).toBe("translateX(0px)");
+    });
+
+    it("returns -drawerSize offset when open for right placement", () => {
+      expect(buildContentTransformString(1, 300, "right")).toBe("translateX(-300px)");
+    });
+
+    it("returns 0px offset when closed for top placement", () => {
+      expect(buildContentTransformString(0, 200, "top")).toBe("translateY(0px)");
+    });
+
+    it("returns +drawerSize offset when open for top placement", () => {
+      expect(buildContentTransformString(1, 200, "top")).toBe("translateY(200px)");
+    });
+
+    it("returns 0px offset when closed for bottom placement", () => {
+      expect(buildContentTransformString(0, 200, "bottom")).toBe("translateY(0px)");
+    });
+
+    it("returns -drawerSize offset when open for bottom placement", () => {
+      expect(buildContentTransformString(1, 200, "bottom")).toBe("translateY(-200px)");
+    });
+
+    it("returns halfway offset at 50% progress", () => {
+      expect(buildContentTransformString(0.5, 300, "left")).toBe("translateX(150px)");
+    });
+  });
+
+  describe("computeDrawerOffsetPx", () => {
+    it("returns -90px for left placement when closed (progress=0)", () => {
+      // 30% of 300px = 90px, negated for left
+      expect(computeDrawerOffsetPx(0, 300, "left")).toBe(-90);
+    });
+
+    it("returns 0px for left placement when open (progress=1)", () => {
+      expect(computeDrawerOffsetPx(1, 300, "left")).toBeCloseTo(0);
+    });
+
+    it("returns +90px for right placement when closed (progress=0)", () => {
+      expect(computeDrawerOffsetPx(0, 300, "right")).toBe(90);
+    });
+
+    it("returns 0px for right placement when open (progress=1)", () => {
+      expect(computeDrawerOffsetPx(1, 300, "right")).toBeCloseTo(0);
+    });
+
+    it("returns -45px at halfway progress for left placement", () => {
+      expect(computeDrawerOffsetPx(0.5, 300, "left")).toBe(-45);
+    });
+  });
+
+  describe("computeContentOffsetPx", () => {
+    it("returns 0 for left placement when closed (progress=0)", () => {
+      expect(computeContentOffsetPx(0, 300, "left")).toBe(0);
+    });
+
+    it("returns drawerSize for left placement when open (progress=1)", () => {
+      expect(computeContentOffsetPx(1, 300, "left")).toBe(300);
+    });
+
+    it("returns -drawerSize for right placement when open (progress=1)", () => {
+      expect(computeContentOffsetPx(1, 300, "right")).toBe(-300);
+    });
+
+    it("returns halfway offset at 50% progress", () => {
+      expect(computeContentOffsetPx(0.5, 300, "left")).toBe(150);
+    });
+  });
+
+  describe("computePositionFromProgress", () => {
+    it("returns both offsets for left placement", () => {
+      const result = computePositionFromProgress(0.5, 300, "left");
+      expect(result.drawerPx).toBe(-45);
+      expect(result.contentPx).toBe(150);
+    });
+
+    it("returns closed state positions", () => {
+      const result = computePositionFromProgress(0, 300, "left");
+      expect(result.drawerPx).toBe(-90);
+      expect(result.contentPx).toBe(0);
+    });
+
+    it("returns open state positions", () => {
+      const result = computePositionFromProgress(1, 300, "left");
+      expect(result.drawerPx).toBeCloseTo(0);
+      expect(result.contentPx).toBe(300);
+    });
+  });
+
+  describe("computeTargetPosition", () => {
+    it("returns closed target positions", () => {
+      const result = computeTargetPosition(false, 300, "left");
+      expect(result.drawerPx).toBe(-90);
+      expect(result.contentPx).toBe(0);
+    });
+
+    it("returns open target positions", () => {
+      const result = computeTargetPosition(true, 300, "left");
+      expect(result.drawerPx).toBeCloseTo(0);
+      expect(result.contentPx).toBe(300);
+    });
+
+    it("handles right placement for open state", () => {
+      const result = computeTargetPosition(true, 300, "right");
+      expect(result.drawerPx).toBeCloseTo(0);
+      expect(result.contentPx).toBe(-300);
+    });
+  });
+
+  describe("computePositionFromDisplacement", () => {
+    it("returns closed position when not opening or closing", () => {
+      const result = computePositionFromDisplacement(100, 300, "left", false, false);
+      expect(result.drawerPx).toBe(-90);
+      expect(result.contentPx).toBe(0);
+    });
+
+    it("returns position based on displacement when opening", () => {
+      // 150px displacement on 300px drawer = 50% progress
+      const result = computePositionFromDisplacement(150, 300, "left", true, false);
+      expect(result.drawerPx).toBe(-45);
+      expect(result.contentPx).toBe(150);
+    });
+
+    it("returns position based on displacement when closing", () => {
+      // 150px displacement on 300px drawer = 50% progress (inverted)
+      const result = computePositionFromDisplacement(150, 300, "left", false, true);
+      expect(result.drawerPx).toBe(-45);
+      expect(result.contentPx).toBe(150);
+    });
+  });
+
+  describe("buildDrawerTransformPx", () => {
+    it("returns correct transform for left placement", () => {
+      expect(buildDrawerTransformPx(-90, "left")).toBe("translateX(-90px)");
+    });
+
+    it("returns correct transform for right placement", () => {
+      expect(buildDrawerTransformPx(90, "right")).toBe("translateX(90px)");
+    });
+
+    it("returns correct transform for top placement", () => {
+      expect(buildDrawerTransformPx(-60, "top")).toBe("translateY(-60px)");
+    });
+
+    it("returns correct transform for bottom placement", () => {
+      expect(buildDrawerTransformPx(60, "bottom")).toBe("translateY(60px)");
+    });
+  });
+
+  describe("buildContentTransformPx", () => {
+    it("returns correct transform for left placement", () => {
+      expect(buildContentTransformPx(300, "left")).toBe("translateX(300px)");
+    });
+
+    it("returns correct transform for right placement", () => {
+      expect(buildContentTransformPx(-300, "right")).toBe("translateX(-300px)");
+    });
+
+    it("returns correct transform for top placement", () => {
+      expect(buildContentTransformPx(200, "top")).toBe("translateY(200px)");
+    });
+
+    it("returns correct transform for bottom placement", () => {
+      expect(buildContentTransformPx(-200, "bottom")).toBe("translateY(-200px)");
+    });
+  });
+});