react-panel-layout 0.5.2 → 0.6.1

package/src/components/window/PopupLayerPortal.tsx

@@ -0,0 +1,218 @@
+/**
+ * @file Renders floating layers inside a dedicated browser popup window.
+ */
+import * as React from "react";
+import { createPortal } from "react-dom";
+import type { LayerDefinition, PopupWindowOptions, WindowPosition, WindowBounds } from "../../types";
+import { LayerInstanceProvider } from "../../modules/grid/LayerInstanceContext";
+
+const ensureNumericOffset = (value: number | string | undefined, key: keyof WindowPosition, layerId: string): number => {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  throw new Error(`Popup layer "${layerId}" requires a numeric "${key}" value.`);
+};
+
+const resolvePopupAnchor = (position: WindowPosition | undefined, layerId: string): { left: number; top: number } => {
+  if (!position) {
+    throw new Error(`Popup layer "${layerId}" must define position (left/top).`);
+  }
+  return {
+    left: ensureNumericOffset(position.left, "left", layerId),
+    top: ensureNumericOffset(position.top, "top", layerId),
+  };
+};
+
+const numericFeature = (value: number): string => {
+  return `${Math.round(value)}`;
+};
+
+const booleanFeature = (value: boolean | undefined): string | undefined => {
+  if (value === undefined) {
+    return undefined;
+  }
+  return value ? "yes" : "no";
+};
+
+const buildWindowFeatures = (
+  layerId: string,
+  position: WindowPosition | undefined,
+  width: number | string | undefined,
+  height: number | string | undefined,
+  options: PopupWindowOptions | undefined,
+): string => {
+  const features: Record<string, string> = {};
+  const anchor = resolvePopupAnchor(position, layerId);
+
+  if (typeof width !== "number" || typeof height !== "number") {
+    throw new Error(`Popup layer "${layerId}" requires numeric width/height.`);
+  }
+  features.width = numericFeature(width);
+  features.height = numericFeature(height);
+  features.left = numericFeature(anchor.left);
+  features.top = numericFeature(anchor.top);
+
+  const overrides = options?.features;
+  if (overrides) {
+    const toolbar = booleanFeature(overrides.toolbar);
+    const menubar = booleanFeature(overrides.menubar);
+    const location = booleanFeature(overrides.location);
+    const status = booleanFeature(overrides.status);
+    const resizable = booleanFeature(overrides.resizable);
+    const scrollbars = booleanFeature(overrides.scrollbars);
+
+    if (toolbar !== undefined) {
+      features.toolbar = toolbar;
+    }
+    if (menubar !== undefined) {
+      features.menubar = menubar;
+    }
+    if (location !== undefined) {
+      features.location = location;
+    }
+    if (status !== undefined) {
+      features.status = status;
+    }
+    if (resizable !== undefined) {
+      features.resizable = resizable;
+    }
+    if (scrollbars !== undefined) {
+      features.scrollbars = scrollbars;
+    }
+  }
+
+  return Object.entries(features)
+    .map(([key, value]) => `${key}=${value}`)
+    .join(",");
+};
+
+const applyBoundsToWindow = (
+  popupWindow: Window,
+  layerId: string,
+  position: WindowPosition | undefined,
+  width: number | string | undefined,
+  height: number | string | undefined,
+) => {
+  const anchor = resolvePopupAnchor(position, layerId);
+  if (typeof width !== "number" || typeof height !== "number") {
+    throw new Error(`Popup layer "${layerId}" requires numeric width/height.`);
+  }
+  popupWindow.moveTo(Math.round(anchor.left), Math.round(anchor.top));
+  popupWindow.resizeTo(Math.round(width), Math.round(height));
+};
+
+type PopupLayerPortalProps = {
+  layer: LayerDefinition;
+};
+
+export const PopupLayerPortal: React.FC<PopupLayerPortalProps> = ({ layer }) => {
+  const floating = layer.floating;
+  if (!floating) {
+    throw new Error(`Layer "${layer.id}" is missing floating configuration required for popup mode.`);
+  }
+  const mode = floating.mode ?? "embedded";
+  if (mode !== "popup") {
+    throw new Error(`PopupLayerPortal received layer "${layer.id}" that is not configured for popup mode.`);
+  }
+
+  const containerRef = React.useRef<HTMLDivElement | null>(null);
+  const popupWindowRef = React.useRef<Window | null>(null);
+  const [isMounted, setIsMounted] = React.useState(false);
+
+  React.useEffect(() => {
+    if (typeof window === "undefined") {
+      return;
+    }
+
+    const features = buildWindowFeatures(layer.id, layer.position, layer.width, layer.height, floating.popup);
+    const windowName = floating.popup?.name ?? layer.id;
+    const createdWindow = resolvePopupWindow(
+      windowName,
+      features,
+      {
+        position: layer.position,
+        size: { width: layer.width as number, height: layer.height as number },
+      },
+      floating.popup,
+    );
+
+    if (!createdWindow) {
+      throw new Error(`Failed to open popup window for layer "${layer.id}".`);
+    }
+
+    const openedWindow = createdWindow;
+
+    popupWindowRef.current = openedWindow;
+
+    if (floating.popup?.focus !== false) {
+      openedWindow.focus();
+    }
+
+    if (!openedWindow.document.title) {
+      openedWindow.document.title = layer.id;
+    }
+    openedWindow.document.body.innerHTML = "";
+    const mountNode = openedWindow.document.createElement("div");
+    mountNode.dataset.layerId = layer.id;
+    openedWindow.document.body.appendChild(mountNode);
+    containerRef.current = mountNode;
+    setIsMounted(true);
+
+    applyBoundsToWindow(openedWindow, layer.id, layer.position, layer.width, layer.height);
+
+    const handleBeforeUnload = () => {
+      popupWindowRef.current = null;
+      containerRef.current = null;
+      setIsMounted(false);
+    };
+    openedWindow.addEventListener("beforeunload", handleBeforeUnload);
+
+    return () => {
+      openedWindow.removeEventListener("beforeunload", handleBeforeUnload);
+      if (floating.popup?.closeOnUnmount !== false) {
+        openedWindow.close();
+      }
+      popupWindowRef.current = null;
+      containerRef.current = null;
+      setIsMounted(false);
+    };
+  }, [
+    floating.popup?.closeOnUnmount,
+    floating.popup?.features?.location,
+    floating.popup?.features?.menubar,
+    floating.popup?.features?.resizable,
+    floating.popup?.features?.scrollbars,
+    floating.popup?.features?.status,
+    floating.popup?.features?.toolbar,
+    floating.popup?.focus,
+    floating.popup?.name,
+    layer.id,
+  ]);
+
+  React.useEffect(() => {
+    const popupWindow = popupWindowRef.current;
+    if (!popupWindow) {
+      return;
+    }
+    applyBoundsToWindow(popupWindow, layer.id, layer.position, layer.width, layer.height);
+  }, [layer.position?.left, layer.position?.top, layer.height, layer.width, layer.id]);
+
+  if (!isMounted || !containerRef.current) {
+    return null;
+  }
+
+  return createPortal(<LayerInstanceProvider layerId={layer.id}>{layer.component}</LayerInstanceProvider>, containerRef.current);
+};
+
+const resolvePopupWindow = (
+  windowName: string,
+  features: string,
+  bounds: WindowBounds,
+  options: PopupWindowOptions | undefined,
+): Window | null => {
+  const customFactory = options?.createWindow;
+  if (customFactory) {
+    return customFactory({ name: windowName, features, bounds });
+  }
+  return window.open("", windowName, features);
+};

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

@@ -0,0 +1,263 @@
+/**
+ * @file Tests for drawerStyles utilities.
+ */
+import {
+  getPlacementStyle,
+  getOpenTransform,
+  getClosedTransform,
+  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("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");
+      });
+    });
+  });
+});

package/src/components/window/drawerStyles.ts

@@ -0,0 +1,228 @@
+/**
+ * @file Drawer style computation utilities.
+ *
+ * Provides pure functions for computing drawer styles based on configuration.
+ */
+import type * as React from "react";
+import type { DrawerBehavior } from "../../types.js";
+import {
+  COLOR_DRAWER_BACKDROP,
+  DRAWER_TRANSITION_DURATION,
+  DRAWER_TRANSITION_EASING,
+} from "../../constants/styles.js";
+
+/**
+ * Base backdrop style shared by backdrop and edge zone.
+ */
+export const DRAWER_BACKDROP_BASE_STYLE: React.CSSProperties = {
+  position: "fixed",
+  inset: 0,
+  background: COLOR_DRAWER_BACKDROP,
+};
+
+/**
+ * Base drawer panel style.
+ */
+export const DRAWER_PANEL_BASE_STYLE: React.CSSProperties = {
+  willChange: "transform",
+};
+
+/**
+ * Placement-specific styles for drawer positioning.
+ */
+export type DrawerPlacement = "left" | "right" | "top" | "bottom";
+
+const PLACEMENT_STYLES: Record<DrawerPlacement, React.CSSProperties> = {
+  left: {
+    top: 0,
+    bottom: 0,
+    left: 0,
+    transform: "translateX(-100%)",
+  },
+  right: {
+    top: 0,
+    bottom: 0,
+    right: 0,
+    transform: "translateX(100%)",
+  },
+  top: {
+    top: 0,
+    left: 0,
+    right: 0,
+    transform: "translateY(-100%)",
+  },
+  bottom: {
+    bottom: 0,
+    left: 0,
+    right: 0,
+    transform: "translateY(100%)",
+  },
+};
+
+const OPEN_TRANSFORMS: Record<DrawerPlacement, string> = {
+  left: "translateX(0)",
+  right: "translateX(0)",
+  top: "translateY(0)",
+  bottom: "translateY(0)",
+};
+
+/**
+ * Get placement-specific style.
+ */
+export function getPlacementStyle(placement: DrawerPlacement): React.CSSProperties {
+  return PLACEMENT_STYLES[placement];
+}
+
+/**
+ * Get transform value for open state.
+ */
+export function getOpenTransform(placement: DrawerPlacement): string {
+  return OPEN_TRANSFORMS[placement];
+}
+
+/**
+ * Get closed transform value.
+ */
+export function getClosedTransform(placement: DrawerPlacement): string {
+  return PLACEMENT_STYLES[placement].transform as string;
+}
+
+/**
+ * Compute CSS transition value.
+ */
+export function computeTransitionValue(
+  mode: DrawerBehavior["transitionMode"] | undefined,
+  duration: DrawerBehavior["transitionDuration"],
+  easing: DrawerBehavior["transitionEasing"],
+): string | undefined {
+  if (mode === "none") {
+    return undefined;
+  }
+
+  const durationValue = duration ?? DRAWER_TRANSITION_DURATION;
+  const easingValue = easing ?? DRAWER_TRANSITION_EASING;
+
+  return `transform ${durationValue} ${easingValue}`;
+}
+
+/**
+ * Compute backdrop transition value.
+ */
+export function computeBackdropTransition(
+  mode: DrawerBehavior["transitionMode"] | undefined,
+  duration: DrawerBehavior["transitionDuration"],
+): string | undefined {
+  if (mode === "none") {
+    return undefined;
+  }
+  return `opacity ${duration ?? "220ms"} ease`;
+}
+
+/**
+ * Check if placement is horizontal (left/right).
+ */
+export function isHorizontalPlacement(placement: DrawerPlacement): boolean {
+  return placement === "left" || placement === "right";
+}
+
+/**
+ * Format dimension value to CSS string.
+ */
+export function formatDimension(value: string | number | undefined): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value === "number") {
+    return `${value}px`;
+  }
+  return value;
+}
+
+// ============================================================================
+// Edge Zone Styles
+// ============================================================================
+
+/**
+ * Options for computing edge zone style.
+ */
+export type EdgeZoneStyleOptions = {
+  placement: DrawerPlacement;
+  inline: boolean;
+  edgeWidth: number;
+  zIndex: number | undefined;
+};
+
+/**
+ * Compute edge zone style based on placement and positioning context.
+ *
+ * The edge zone is positioned at the edge where the drawer appears from:
+ * - left drawer: left edge of the container
+ * - right drawer: right edge of the container
+ * - top drawer: top edge of the container
+ * - bottom drawer: bottom edge of the container
+ *
+ * When inline=true, uses absolute positioning (relative to parent container).
+ * When inline=false, uses fixed positioning (relative to viewport).
+ */
+export function computeEdgeZoneStyle(options: EdgeZoneStyleOptions): React.CSSProperties {
+  const { placement, inline, edgeWidth, zIndex } = options;
+  const position = inline ? "absolute" : "fixed";
+  const computedZIndex = zIndex !== undefined ? zIndex - 2 : 1000;
+
+  return getEdgeZoneStyleByPlacement(placement, position, edgeWidth, computedZIndex);
+}
+
+function getEdgeZoneStyleByPlacement(
+  placement: DrawerPlacement,
+  position: "absolute" | "fixed",
+  edgeWidth: number,
+  zIndex: number,
+): React.CSSProperties {
+  // Common base style
+  const base: React.CSSProperties = {
+    position,
+    zIndex,
+    background: "transparent",
+    pointerEvents: "auto",
+  };
+
+  // Placement-specific positioning
+  if (placement === "left") {
+    return {
+      ...base,
+      top: 0,
+      bottom: 0,
+      left: 0,
+      width: edgeWidth,
+    };
+  }
+
+  if (placement === "right") {
+    return {
+      ...base,
+      top: 0,
+      bottom: 0,
+      right: 0,
+      width: edgeWidth,
+    };
+  }
+
+  if (placement === "top") {
+    return {
+      ...base,
+      top: 0,
+      left: 0,
+      right: 0,
+      height: edgeWidth,
+    };
+  }
+
+  // bottom
+  return {
+    ...base,
+    bottom: 0,
+    left: 0,
+    right: 0,
+    height: edgeWidth,
+  };
+}