react-panel-layout 0.6.0 → 0.7.0

package/src/components/window/drawerStyles.ts

@@ -0,0 +1,252 @@
+/**
+ * @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)",
+};
+
+/**
+ * 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.
+ */
+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;
+}
+
+/**
+ * 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.
+ */
+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,
+  };
+}

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

@@ -0,0 +1,131 @@
+/**
+ * @file Tests for drawerSwipeConfig utilities.
+ */
+import {
+  parseSwipeGesturesConfig,
+  resolvePlacement,
+  shouldShowEdgeZone,
+} from "./drawerSwipeConfig.js";
+
+describe("drawerSwipeConfig", () => {
+  describe("parseSwipeGesturesConfig", () => {
+    it("returns disabled config for false", () => {
+      const config = parseSwipeGesturesConfig(false);
+      expect(config.enabled).toBe(false);
+      expect(config.edgeSwipeOpen).toBe(false);
+      expect(config.swipeClose).toBe(false);
+    });
+
+    it("returns disabled config for undefined", () => {
+      const config = parseSwipeGesturesConfig(undefined);
+      expect(config.enabled).toBe(false);
+    });
+
+    it("returns enabled defaults for true", () => {
+      const config = parseSwipeGesturesConfig(true);
+      expect(config.enabled).toBe(true);
+      expect(config.edgeSwipeOpen).toBe(true);
+      expect(config.swipeClose).toBe(true);
+      expect(config.edgeWidth).toBe(20);
+      expect(config.dismissThreshold).toBe(0.3);
+    });
+
+    it("parses object config with defaults", () => {
+      const config = parseSwipeGesturesConfig({});
+      expect(config.enabled).toBe(true);
+      expect(config.edgeSwipeOpen).toBe(true);
+      expect(config.swipeClose).toBe(true);
+    });
+
+    it("respects object config overrides", () => {
+      const config = parseSwipeGesturesConfig({
+        edgeSwipeOpen: false,
+        swipeClose: true,
+        edgeWidth: 40,
+        dismissThreshold: 0.5,
+      });
+      expect(config.enabled).toBe(true);
+      expect(config.edgeSwipeOpen).toBe(false);
+      expect(config.swipeClose).toBe(true);
+      expect(config.edgeWidth).toBe(40);
+      expect(config.dismissThreshold).toBe(0.5);
+    });
+  });
+
+  describe("resolvePlacement", () => {
+    it("returns anchor if provided", () => {
+      expect(resolvePlacement("left", undefined)).toBe("left");
+      expect(resolvePlacement("right", { left: 0 })).toBe("right");
+    });
+
+    it("returns right as default when no anchor or position", () => {
+      expect(resolvePlacement(undefined, undefined)).toBe("right");
+    });
+
+    it("infers left from position.left", () => {
+      expect(resolvePlacement(undefined, { left: 0 })).toBe("left");
+    });
+
+    it("infers right from position.right", () => {
+      expect(resolvePlacement(undefined, { right: 0 })).toBe("right");
+    });
+
+    it("infers top from position.top", () => {
+      expect(resolvePlacement(undefined, { top: 0 })).toBe("top");
+    });
+
+    it("infers bottom from position.bottom", () => {
+      expect(resolvePlacement(undefined, { bottom: 0 })).toBe("bottom");
+    });
+
+    it("prioritizes left over other positions", () => {
+      expect(resolvePlacement(undefined, { left: 0, right: 0 })).toBe("left");
+    });
+  });
+
+  describe("shouldShowEdgeZone", () => {
+    const enabledConfig = {
+      enabled: true,
+      edgeSwipeOpen: true,
+      swipeClose: true,
+      edgeWidth: 20,
+      dismissThreshold: 0.3,
+    };
+
+    const disabledConfig = {
+      enabled: false,
+      edgeSwipeOpen: false,
+      swipeClose: false,
+      edgeWidth: 20,
+      dismissThreshold: 0.3,
+    };
+
+    const noEdgeSwipeConfig = {
+      enabled: true,
+      edgeSwipeOpen: false,
+      swipeClose: true,
+      edgeWidth: 20,
+      dismissThreshold: 0.3,
+    };
+
+    it("returns false when config is disabled", () => {
+      expect(shouldShowEdgeZone(disabledConfig, false, false)).toBe(false);
+    });
+
+    it("returns false when edgeSwipeOpen is disabled", () => {
+      expect(shouldShowEdgeZone(noEdgeSwipeConfig, false, false)).toBe(false);
+    });
+
+    it("returns true when drawer is closed", () => {
+      expect(shouldShowEdgeZone(enabledConfig, false, false)).toBe(true);
+    });
+
+    it("returns true when actively opening", () => {
+      expect(shouldShowEdgeZone(enabledConfig, true, true)).toBe(true);
+    });
+
+    it("returns false when drawer is open and not opening", () => {
+      expect(shouldShowEdgeZone(enabledConfig, true, false)).toBe(false);
+    });
+  });
+});

package/src/components/window/drawerSwipeConfig.ts

@@ -0,0 +1,112 @@
+/**
+ * @file Drawer swipe gesture configuration parsing.
+ *
+ * Normalizes swipeGestures config from DrawerBehavior into a consistent shape.
+ */
+import type { DrawerBehavior, WindowPosition } from "../../types.js";
+import type { DrawerPlacement } from "./drawerStyles.js";
+
+/**
+ * Normalized swipe gesture configuration.
+ */
+export type NormalizedSwipeConfig = {
+  enabled: boolean;
+  edgeSwipeOpen: boolean;
+  swipeClose: boolean;
+  edgeWidth: number;
+  dismissThreshold: number;
+};
+
+const DEFAULT_EDGE_WIDTH = 20;
+const DEFAULT_DISMISS_THRESHOLD = 0.3;
+
+const DISABLED_CONFIG: NormalizedSwipeConfig = {
+  enabled: false,
+  edgeSwipeOpen: false,
+  swipeClose: false,
+  edgeWidth: DEFAULT_EDGE_WIDTH,
+  dismissThreshold: DEFAULT_DISMISS_THRESHOLD,
+};
+
+const ENABLED_DEFAULT_CONFIG: NormalizedSwipeConfig = {
+  enabled: true,
+  edgeSwipeOpen: true,
+  swipeClose: true,
+  edgeWidth: DEFAULT_EDGE_WIDTH,
+  dismissThreshold: DEFAULT_DISMISS_THRESHOLD,
+};
+
+/**
+ * Parse swipeGestures config into normalized options.
+ */
+export function parseSwipeGesturesConfig(
+  swipeGestures: DrawerBehavior["swipeGestures"],
+): NormalizedSwipeConfig {
+  if (swipeGestures === true) {
+    return ENABLED_DEFAULT_CONFIG;
+  }
+
+  if (swipeGestures === false || swipeGestures === undefined) {
+    return DISABLED_CONFIG;
+  }
+
+  return {
+    enabled: true,
+    edgeSwipeOpen: swipeGestures.edgeSwipeOpen ?? true,
+    swipeClose: swipeGestures.swipeClose ?? true,
+    edgeWidth: swipeGestures.edgeWidth ?? DEFAULT_EDGE_WIDTH,
+    dismissThreshold: swipeGestures.dismissThreshold ?? DEFAULT_DISMISS_THRESHOLD,
+  };
+}
+
+/**
+ * Resolve drawer placement from anchor and position.
+ */
+export function resolvePlacement(
+  anchor: DrawerBehavior["anchor"],
+  position: WindowPosition | undefined,
+): DrawerPlacement {
+  if (anchor) {
+    return anchor;
+  }
+
+  if (!position) {
+    return "right";
+  }
+
+  if (position.left !== undefined) {
+    return "left";
+  }
+  if (position.right !== undefined) {
+    return "right";
+  }
+  if (position.top !== undefined) {
+    return "top";
+  }
+  if (position.bottom !== undefined) {
+    return "bottom";
+  }
+
+  return "right";
+}
+
+/**
+ * Determine if edge zone should be visible.
+ */
+export function shouldShowEdgeZone(
+  config: NormalizedSwipeConfig,
+  isOpen: boolean,
+  isOpening: boolean,
+): boolean {
+  if (!config.enabled) {
+    return false;
+  }
+  if (!config.edgeSwipeOpen) {
+    return false;
+  }
+  // Show when closed or actively opening
+  if (!isOpen) {
+    return true;
+  }
+  return isOpening;
+}

package/src/components/window/useDrawerSwipeTransform.ts

@@ -0,0 +1,67 @@
+/**
+ * @file Hook for applying real-time transform during drawer swipe gestures (backward-compatible wrapper).
+ *
+ * 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 type { DrawerSwipeDirection } from "../../modules/drawer/types.js";
+import { useDrawerTransform } from "./useDrawerTransform.js";
+
+type UseDrawerSwipeTransformOptions = {
+  drawerRef: React.RefObject<HTMLDivElement | null>;
+  backdropRef: React.RefObject<HTMLDivElement | null>;
+  placement: DrawerSwipeDirection;
+  swipeState: ContinuousOperationState;
+  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 {
+    drawerRef,
+    backdropRef,
+    placement,
+    swipeState,
+    displacement,
+    isOpening,
+    isClosing,
+    isOpen,
+    enabled,
+  } = options;
+
+  // Get drawer size from element
+  const drawerSizeRef = React.useRef(0);
+  React.useLayoutEffect(() => {
+    const drawer = drawerRef.current;
+    if (drawer) {
+      const isHorizontal = placement === "left" || placement === "right";
+      drawerSizeRef.current = isHorizontal ? drawer.clientWidth : drawer.clientHeight;
+    }
+  }, [drawerRef, placement]);
+
+  useDrawerTransform({
+    mode: "overlay",
+    drawerRef,
+    backdropRef,
+    placement,
+    drawerSize: drawerSizeRef.current,
+    isOpen,
+    swipeState,
+    displacement,
+    isOpening,
+    isClosing,
+    enabled,
+  });
+}