react-panel-layout 0.5.2 → 0.6.1

package/src/modules/dialog/Modal.tsx

@@ -0,0 +1,182 @@
+/**
+ * @file Modal component - Centered modal dialog with optional chrome
+ */
+import * as React from "react";
+import type { ModalProps } from "./types";
+import { DialogContainer } from "./DialogContainer";
+import {
+  FloatingPanelFrame,
+  FloatingPanelHeader,
+  FloatingPanelTitle,
+  FloatingPanelContent,
+  FloatingPanelCloseButton,
+} from "../../components/paneling/FloatingPanelFrame";
+import {
+  MODAL_MIN_WIDTH,
+  MODAL_MAX_WIDTH,
+  MODAL_MAX_HEIGHT,
+  FLOATING_PANEL_HEADER_PADDING_Y,
+  FLOATING_PANEL_HEADER_PADDING_X,
+  FLOATING_PANEL_GAP,
+} from "../../constants/styles";
+
+const modalContentStyle: React.CSSProperties = {
+  minWidth: MODAL_MIN_WIDTH,
+  maxWidth: MODAL_MAX_WIDTH,
+  maxHeight: MODAL_MAX_HEIGHT,
+  display: "flex",
+  flexDirection: "column",
+};
+
+type ModalContentProps = {
+  header?: ModalProps["header"];
+  dismissible: boolean;
+  onClose: () => void;
+  children: React.ReactNode;
+  contentStyle?: React.CSSProperties;
+};
+
+const ModalContentWithChrome: React.FC<ModalContentProps> = ({
+  header,
+  dismissible,
+  onClose,
+  children,
+  contentStyle,
+}) => {
+  const showCloseButton = header?.showCloseButton ?? true;
+  const shouldShowClose = dismissible ? showCloseButton : false;
+
+  const hasHeader = header !== undefined;
+
+  return (
+    <FloatingPanelFrame>
+      <React.Activity mode={hasHeader ? "visible" : "hidden"}>
+        <FloatingPanelHeader
+          style={{
+            padding: `${FLOATING_PANEL_HEADER_PADDING_Y} ${FLOATING_PANEL_HEADER_PADDING_X}`,
+            gap: FLOATING_PANEL_GAP,
+          }}
+        >
+          <FloatingPanelTitle>{header?.title}</FloatingPanelTitle>
+          <React.Activity mode={shouldShowClose ? "visible" : "hidden"}>
+            <FloatingPanelCloseButton onClick={onClose} aria-label="Close modal" style={{ marginLeft: "auto" }} />
+          </React.Activity>
+        </FloatingPanelHeader>
+      </React.Activity>
+      <FloatingPanelContent style={{ flex: 1, overflow: "auto", ...contentStyle }}>{children}</FloatingPanelContent>
+    </FloatingPanelFrame>
+  );
+};
+
+type ModalContentRendererProps = ModalContentProps & {
+  chrome: boolean;
+};
+
+const ModalContentRenderer: React.FC<ModalContentRendererProps> = ({ chrome, children, ...chromeProps }) => {
+  if (chrome) {
+    return <ModalContentWithChrome {...chromeProps}>{children}</ModalContentWithChrome>;
+  }
+  return <>{children}</>;
+};
+
+/**
+ * Modal component for displaying centered dialogs.
+ * Uses native <dialog> element for proper accessibility and top-layer rendering.
+ *
+ * @example
+ * ```tsx
+ * const [isOpen, setIsOpen] = useState(false);
+ *
+ * <Modal
+ *   visible={isOpen}
+ *   onClose={() => setIsOpen(false)}
+ *   header={{ title: "Settings" }}
+ * >
+ *   <form>
+ *     <input type="text" placeholder="Name" />
+ *     <button type="submit">Save</button>
+ *   </form>
+ * </Modal>
+ * ```
+ */
+export const Modal: React.FC<ModalProps> = ({
+  visible,
+  onClose,
+  children,
+  header,
+  width,
+  height,
+  maxWidth,
+  maxHeight,
+  chrome = true,
+  dismissible = true,
+  closeOnEscape = true,
+  preventBodyScroll = true,
+  returnFocus = true,
+  ariaLabel,
+  ariaLabelledBy,
+  ariaDescribedBy,
+  transitionMode = "css",
+  transitionDuration,
+  transitionEasing,
+  contentStyle: propContentStyle,
+  swipeDismissible,
+  openDirection = "center",
+  useViewTransition = false,
+}) => {
+  const computedStyle = React.useMemo((): React.CSSProperties => {
+    const style: React.CSSProperties = { ...modalContentStyle };
+
+    if (width !== undefined) {
+      style.width = typeof width === "number" ? `${width}px` : width;
+    }
+    if (height !== undefined) {
+      style.height = typeof height === "number" ? `${height}px` : height;
+    }
+    if (maxWidth !== undefined) {
+      style.maxWidth = typeof maxWidth === "number" ? `${maxWidth}px` : maxWidth;
+    }
+    if (maxHeight !== undefined) {
+      style.maxHeight = typeof maxHeight === "number" ? `${maxHeight}px` : maxHeight;
+    }
+
+    return style;
+  }, [width, height, maxWidth, maxHeight]);
+
+  const effectiveAriaLabel = ariaLabel ?? header?.title ?? "Modal";
+
+  return (
+    <DialogContainer
+      visible={visible}
+      onClose={onClose}
+      position="center"
+      dismissible={dismissible}
+      closeOnEscape={closeOnEscape}
+      preventBodyScroll={preventBodyScroll}
+      returnFocus={returnFocus}
+      ariaLabel={effectiveAriaLabel}
+      ariaLabelledBy={ariaLabelledBy}
+      ariaDescribedBy={ariaDescribedBy}
+      transitionMode={transitionMode}
+      transitionDuration={transitionDuration}
+      transitionEasing={transitionEasing}
+      swipeDismissible={swipeDismissible}
+      openDirection={openDirection}
+      useViewTransition={useViewTransition}
+    >
+      <div style={computedStyle}>
+        <ModalContentRenderer
+          chrome={chrome}
+          header={header}
+          dismissible={dismissible}
+          onClose={onClose}
+          contentStyle={propContentStyle}
+        >
+          {children}
+        </ModalContentRenderer>
+      </div>
+    </DialogContainer>
+  );
+};
+
+Modal.displayName = "Modal";

package/src/modules/dialog/SwipeDialogContainer.tsx

@@ -0,0 +1,208 @@
+/**
+ * @file Swipeable dialog container component.
+ *
+ * This component extends the base dialog functionality with swipe-to-dismiss
+ * and multi-phase animations. It uses native <dialog> element for top layer
+ * positioning and custom transform animations.
+ */
+import * as React from "react";
+import type { DialogContainerProps } from "./types.js";
+import { useDialogContainer } from "./useDialogContainer.js";
+import { useDialogSwipeInput } from "./useDialogSwipeInput.js";
+import { useDialogTransform } from "./useDialogTransform.js";
+import { COLOR_MODAL_BACKDROP } from "../../constants/styles.js";
+
+const dialogBaseStyle: React.CSSProperties = {
+  border: "none",
+  padding: 0,
+  background: "transparent",
+  maxWidth: "none",
+  maxHeight: "none",
+  overflow: "visible",
+};
+
+const contentWrapperStyle: React.CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "center",
+  position: "fixed",
+  inset: 0,
+  pointerEvents: "none",
+};
+
+const contentStyle: React.CSSProperties = {
+  pointerEvents: "auto",
+  willChange: "transform, opacity",
+};
+
+const backdropStyle: React.CSSProperties = {
+  position: "fixed",
+  inset: 0,
+  background: COLOR_MODAL_BACKDROP,
+  pointerEvents: "auto",
+  willChange: "opacity",
+};
+
+/**
+ * Swipeable dialog container with multi-phase animation.
+ *
+ * Uses native <dialog> for top layer positioning and custom JS animations
+ * for swipe-to-dismiss functionality.
+ */
+export const SwipeDialogContainer: React.FC<DialogContainerProps> = ({
+  visible,
+  onClose,
+  children,
+  position = "center",
+  dismissible = true,
+  closeOnEscape = true,
+  returnFocus = true,
+  preventBodyScroll = true,
+  ariaLabel,
+  ariaLabelledBy,
+  ariaDescribedBy,
+  swipeDismissible = true,
+  openDirection = "center",
+  useViewTransition = false,
+}) => {
+  const contentRef = React.useRef<HTMLDivElement>(null);
+  const backdropRef = React.useRef<HTMLDivElement>(null);
+
+  // Base dialog lifecycle management
+  const { dialogRef, dialogProps } = useDialogContainer({
+    visible,
+    onClose,
+    dismissible,
+    closeOnEscape,
+    returnFocus,
+    preventBodyScroll,
+  });
+
+  // Swipe input detection - free 2D movement
+  const swipeEnabled = swipeDismissible ? visible : false;
+  const {
+    state: swipeState,
+    containerProps: swipeContainerProps,
+    displacement,
+    displacement2D,
+    isOperating,
+  } = useDialogSwipeInput({
+    containerRef: contentRef,
+    openDirection,
+    enabled: swipeEnabled,
+    onSwipeDismiss: onClose,
+  });
+
+  // Transform and animation management
+  const { phase, isAnimating, triggerClose } = useDialogTransform({
+    elementRef: contentRef,
+    backdropRef,
+    visible,
+    openDirection,
+    swipeState,
+    displacement,
+    displacement2D,
+    useViewTransition,
+    onCloseComplete: onClose,
+  });
+
+  // Handle backdrop click
+  const handleBackdropClick = React.useCallback(() => {
+    if (!dismissible) {
+      return;
+    }
+    if (isOperating) {
+      return;
+    }
+    if (isAnimating) {
+      return;
+    }
+    triggerClose();
+  }, [dismissible, isOperating, isAnimating, triggerClose]);
+
+  // Compute content wrapper style based on position
+  const computedContentWrapperStyle = React.useMemo((): React.CSSProperties => {
+    if (position === "center") {
+      return contentWrapperStyle;
+    }
+    // Absolute position
+    const style: React.CSSProperties = {
+      ...contentWrapperStyle,
+      alignItems: "flex-start",
+      justifyContent: "flex-start",
+    };
+    if (position.x !== undefined) {
+      style.left = position.x;
+    }
+    if (position.y !== undefined) {
+      style.top = position.y;
+    }
+    return style;
+  }, [position]);
+
+  // Merge swipe container props with content style
+  // Note: We don't use React.Activity here because it uses display:none,
+  // which prevents dimension measurement needed for animations.
+  // Instead, we use visibility and opacity controlled by the animation.
+  const mergedContentStyle = React.useMemo((): React.CSSProperties => {
+    const style: React.CSSProperties = {
+      ...contentStyle,
+      ...swipeContainerProps.style,
+    };
+
+    // When closed, hide the content but keep it in layout for dimension measurement
+    if (phase === "closed") {
+      style.visibility = "hidden";
+      style.pointerEvents = "none";
+    }
+
+    return style;
+  }, [swipeContainerProps.style, phase]);
+
+  // Stop propagation on content pointer events
+  const handleContentPointerDown = React.useCallback((event: React.PointerEvent<HTMLDivElement>) => {
+    swipeContainerProps.onPointerDown?.(event);
+    // Don't stop propagation - let swipe input handle it
+  }, [swipeContainerProps]);
+
+  // Hide dialog styling (we use our own backdrop)
+  const hideNativeBackdrop = `
+    dialog::backdrop {
+      background: transparent;
+    }
+  `;
+
+  return (
+    <>
+      <style>{hideNativeBackdrop}</style>
+      <dialog
+        ref={dialogRef}
+        style={dialogBaseStyle}
+        aria-label={ariaLabel}
+        aria-labelledby={ariaLabelledBy}
+        aria-describedby={ariaDescribedBy}
+        {...dialogProps}
+      >
+        {/* Custom backdrop for animated opacity */}
+        <div
+          ref={backdropRef}
+          style={backdropStyle}
+          onClick={handleBackdropClick}
+          aria-hidden="true"
+        />
+
+        <div style={computedContentWrapperStyle}>
+          <div
+            ref={contentRef}
+            style={mergedContentStyle}
+            onPointerDown={handleContentPointerDown}
+          >
+            {children}
+          </div>
+        </div>
+      </dialog>
+    </>
+  );
+};
+
+SwipeDialogContainer.displayName = "SwipeDialogContainer";

package/src/modules/dialog/dialogAnimationUtils.spec.ts

@@ -0,0 +1,253 @@
+/**
+ * @file Tests for dialog animation utilities
+ */
+import { describe, expect, it } from "vitest";
+import {
+  computeCloseTransform,
+  computeOpenTransform,
+  computeSwipeTransform,
+  shouldDismiss,
+  getAnimationAxis,
+  getDirectionSign,
+  getCloseDirectionFromSwipe,
+  supportsViewTransitions,
+  buildTransformString,
+} from "./dialogAnimationUtils.js";
+
+describe("dialogAnimationUtils", () => {
+  describe("getAnimationAxis", () => {
+    it("returns 'y' for center direction", () => {
+      expect(getAnimationAxis("center")).toBe("y");
+    });
+
+    it("returns 'y' for bottom direction", () => {
+      expect(getAnimationAxis("bottom")).toBe("y");
+    });
+
+    it("returns 'y' for top direction", () => {
+      expect(getAnimationAxis("top")).toBe("y");
+    });
+
+    it("returns 'x' for left direction", () => {
+      expect(getAnimationAxis("left")).toBe("x");
+    });
+
+    it("returns 'x' for right direction", () => {
+      expect(getAnimationAxis("right")).toBe("x");
+    });
+  });
+
+  describe("getDirectionSign", () => {
+    it("returns 1 for center (default down)", () => {
+      expect(getDirectionSign("center")).toBe(1);
+    });
+
+    it("returns 1 for bottom", () => {
+      expect(getDirectionSign("bottom")).toBe(1);
+    });
+
+    it("returns -1 for top", () => {
+      expect(getDirectionSign("top")).toBe(-1);
+    });
+
+    it("returns -1 for left", () => {
+      expect(getDirectionSign("left")).toBe(-1);
+    });
+
+    it("returns 1 for right", () => {
+      expect(getDirectionSign("right")).toBe(1);
+    });
+  });
+
+  describe("computeCloseTransform", () => {
+    const containerSize = 800;
+
+    it("returns identity transform at progress 0", () => {
+      const result = computeCloseTransform(0, containerSize, "bottom");
+      expect(result.translate).toBe(0);
+      expect(result.scale).toBe(1);
+      expect(result.backdropOpacity).toBe(1);
+    });
+
+    it("returns final transform at progress 1", () => {
+      const result = computeCloseTransform(1, containerSize, "bottom");
+      // 50% of container = 400px translate
+      expect(result.translate).toBeCloseTo(400);
+      // Final scale is 0.85
+      expect(result.scale).toBeCloseTo(0.85);
+      // Backdrop should be faded
+      expect(result.backdropOpacity).toBe(0);
+    });
+
+    it("phase 1 only applies translate", () => {
+      const result = computeCloseTransform(0.5, containerSize, "bottom");
+      // Still in phase 1 (before 0.7)
+      expect(result.scale).toBe(1);
+      expect(result.translate).toBeGreaterThan(0);
+      expect(result.translate).toBeLessThan(400);
+    });
+
+    it("phase 2 applies scale reduction", () => {
+      const result = computeCloseTransform(0.85, containerSize, "bottom");
+      // In phase 2 (after 0.7)
+      expect(result.scale).toBeLessThan(1);
+      expect(result.scale).toBeGreaterThan(0.85);
+    });
+
+    it("uses negative translate for top direction", () => {
+      const result = computeCloseTransform(1, containerSize, "top");
+      expect(result.translate).toBeLessThan(0);
+    });
+
+    it("uses negative translate for left direction", () => {
+      const result = computeCloseTransform(1, containerSize, "left");
+      expect(result.translate).toBeLessThan(0);
+    });
+  });
+
+  describe("computeOpenTransform", () => {
+    const containerSize = 800;
+
+    it("returns closed state at progress 0", () => {
+      const result = computeOpenTransform(0, containerSize, "bottom");
+      expect(result.translate).toBeCloseTo(400);
+      expect(result.scale).toBeCloseTo(0.85);
+    });
+
+    it("returns identity transform at progress 1", () => {
+      const result = computeOpenTransform(1, containerSize, "bottom");
+      expect(result.translate).toBe(0);
+      expect(result.scale).toBe(1);
+    });
+
+    it("is the reverse of computeCloseTransform", () => {
+      const closeAt30 = computeCloseTransform(0.3, containerSize, "bottom");
+      const openAt70 = computeOpenTransform(0.7, containerSize, "bottom");
+
+      expect(closeAt30.translate).toBeCloseTo(openAt70.translate, 5);
+      expect(closeAt30.scale).toBeCloseTo(openAt70.scale, 5);
+    });
+  });
+
+  describe("computeSwipeTransform", () => {
+    const containerSize = 400;
+
+    it("returns identity transform at displacement 0", () => {
+      const result = computeSwipeTransform(0, containerSize);
+      expect(result.translate).toBe(0);
+      expect(result.scale).toBe(1);
+      expect(result.backdropOpacity).toBe(1);
+    });
+
+    it("translates by displacement amount", () => {
+      const result = computeSwipeTransform(100, containerSize);
+      expect(result.translate).toBe(100);
+    });
+
+    it("applies light scale feedback during swipe", () => {
+      const result = computeSwipeTransform(200, containerSize);
+      // 50% progress, 2% max reduction = 1% reduction
+      expect(result.scale).toBeCloseTo(0.99);
+    });
+
+    it("fades backdrop with swipe progress", () => {
+      const result = computeSwipeTransform(200, containerSize);
+      // 50% progress, 80% max fade = 40% fade
+      expect(result.backdropOpacity).toBeCloseTo(0.6);
+    });
+
+    it("clamps progress at 1", () => {
+      const result = computeSwipeTransform(800, containerSize);
+      expect(result.scale).toBeCloseTo(0.98); // Max 2% reduction
+      expect(result.backdropOpacity).toBeCloseTo(0.2); // 80% fade
+    });
+  });
+
+  describe("shouldDismiss", () => {
+    const containerSize = 400;
+
+    it("returns true when displacement exceeds threshold", () => {
+      // 30% threshold = 120px
+      const result = shouldDismiss(130, 0, containerSize);
+      expect(result).toBe(true);
+    });
+
+    it("returns false when displacement is below threshold", () => {
+      const result = shouldDismiss(100, 0, containerSize);
+      expect(result).toBe(false);
+    });
+
+    it("returns true when velocity is high", () => {
+      // 0.5 px/ms threshold
+      const result = shouldDismiss(50, 0.6, containerSize);
+      expect(result).toBe(true);
+    });
+
+    it("returns false when velocity is low", () => {
+      const result = shouldDismiss(50, 0.3, containerSize);
+      expect(result).toBe(false);
+    });
+
+    it("respects custom threshold", () => {
+      // Custom 50% threshold = 200px
+      const belowThreshold = shouldDismiss(190, 0, containerSize, 0.5);
+      const aboveThreshold = shouldDismiss(210, 0, containerSize, 0.5);
+
+      expect(belowThreshold).toBe(false);
+      expect(aboveThreshold).toBe(true);
+    });
+  });
+
+  describe("getCloseDirectionFromSwipe", () => {
+    it("returns bottom for positive Y displacement", () => {
+      const result = getCloseDirectionFromSwipe(0, 100);
+      expect(result).toBe("bottom");
+    });
+
+    it("returns top for negative Y displacement", () => {
+      const result = getCloseDirectionFromSwipe(0, -100);
+      expect(result).toBe("top");
+    });
+
+    it("returns right for positive X displacement", () => {
+      const result = getCloseDirectionFromSwipe(100, 0);
+      expect(result).toBe("right");
+    });
+
+    it("returns left for negative X displacement", () => {
+      const result = getCloseDirectionFromSwipe(-100, 0);
+      expect(result).toBe("left");
+    });
+
+    it("prefers Y over X when equal", () => {
+      const result = getCloseDirectionFromSwipe(100, 100);
+      expect(result).toBe("bottom");
+    });
+
+    it("returns default when both are zero", () => {
+      const result = getCloseDirectionFromSwipe(0, 0, "left");
+      expect(result).toBe("left");
+    });
+  });
+
+  describe("supportsViewTransitions", () => {
+    it("returns a boolean", () => {
+      const result = supportsViewTransitions();
+      expect(typeof result).toBe("boolean");
+    });
+  });
+
+  describe("buildTransformString", () => {
+    it("builds translateY for y axis", () => {
+      const transform = { translate: 100, scale: 0.9, backdropOpacity: 0.5 };
+      const result = buildTransformString(transform, "y");
+      expect(result).toBe("translateY(100px) scale(0.9)");
+    });
+
+    it("builds translateX for x axis", () => {
+      const transform = { translate: -50, scale: 1, backdropOpacity: 1 };
+      const result = buildTransformString(transform, "x");
+      expect(result).toBe("translateX(-50px) scale(1)");
+    });
+  });
+});