react-panel-layout 0.5.1 → 0.6.0

package/src/hooks/useIntersectionObserver.tsx

@@ -0,0 +1,125 @@
+/**
+ * @file Shared useIntersectionObserver hook with cached observer instances.
+ */
+import * as React from "react";
+
+const createIdGenerator = () => {
+  const map = new Map<object, number>();
+  return (ref: object | null | undefined) => {
+    if (!ref) {
+      return undefined;
+    }
+    const existing = map.get(ref);
+    if (existing !== undefined) {
+      return existing;
+    }
+    const nextId = map.size;
+    map.set(ref, nextId);
+    return nextId;
+  };
+};
+
+const getId = createIdGenerator();
+type Unobserve = () => void;
+type Callback = (entry: IntersectionObserverEntry) => void;
+type SharedObserver = {
+  observe: (target: Element, callback: Callback) => Unobserve;
+};
+const observerCache = new Map<string, SharedObserver>();
+const getSharedObserver = (options: IntersectionObserverInit) => {
+  const observerKey = `ovs-threshold:${options.threshold}-rootMargin:${options.rootMargin}-root:${getId(options.root)}`;
+
+  if (observerCache.has(observerKey)) {
+    return observerCache.get(observerKey)!;
+  }
+  const observer = new (class {
+    #callbackMap = new Map<Element, Callback>();
+    #intersectionObserver = new IntersectionObserver((entries) => {
+      entries.forEach((entry) => {
+        const callback = this.#callbackMap.get(entry.target);
+        if (callback) {
+          callback(entry);
+        }
+      });
+    }, options);
+    observe(target: Element, callback: Callback) {
+      this.#callbackMap.set(target, callback);
+      this.#intersectionObserver.observe(target);
+      return () => {
+        this.#callbackMap.delete(target);
+        this.#intersectionObserver.unobserve(target);
+      };
+    }
+  })();
+  observerCache.set(observerKey, observer);
+
+  return observer;
+};
+const voidClientRect = Object.freeze({
+  x: 0,
+  y: 0,
+  width: 0,
+  height: 0,
+  top: 0,
+  right: 0,
+  bottom: 0,
+  left: 0,
+}) as DOMRectReadOnly;
+/**
+ * Observe intersection changes for a given element reference using shared observers.
+ *
+ * @param ref - Ref holding the element to observe.
+ * @param options - Intersection observer configuration.
+ * @returns Latest intersection entry snapshot with sensible defaults.
+ */
+export function useIntersectionObserver<T extends HTMLElement>(
+  ref: React.RefObject<T | null>,
+  { threshold = 0, rootMargin = "0px", root = null }: IntersectionObserverInit,
+): {
+  readonly boundingClientRect: DOMRectReadOnly;
+  readonly intersectionRatio: number;
+  readonly intersectionRect: DOMRectReadOnly;
+  readonly isIntersecting: boolean;
+  readonly rootBounds: DOMRectReadOnly | null;
+  readonly target: Element | null;
+  readonly time: DOMHighResTimeStamp;
+} {
+  const [intersection, setIntersection] = React.useState<IntersectionObserverEntry | null>(null);
+
+  React.useEffect(() => {
+    const target = ref.current;
+    if (!target) {
+      return;
+    }
+
+    const observer = getSharedObserver({
+      threshold,
+      rootMargin,
+      root,
+    });
+
+    return observer.observe(target, (entry) => {
+      setIntersection({
+        isIntersecting: entry.isIntersecting,
+        boundingClientRect: entry.boundingClientRect,
+        intersectionRatio: entry.intersectionRatio,
+        intersectionRect: entry.intersectionRect,
+        rootBounds: entry.rootBounds,
+        target: entry.target,
+        time: entry.time,
+      });
+    });
+  }, [ref, threshold, rootMargin, root]);
+
+  return React.useMemo(() => {
+    return {
+      isIntersecting: intersection?.isIntersecting ?? false,
+      boundingClientRect: intersection?.boundingClientRect ?? voidClientRect,
+      intersectionRatio: intersection?.intersectionRatio ?? 0,
+      intersectionRect: intersection?.intersectionRect ?? voidClientRect,
+      rootBounds: intersection?.rootBounds ?? null,
+      target: intersection?.target ?? ref.current,
+      time: intersection?.time ?? 0,
+    };
+  }, [intersection, ref]);
+}

package/src/hooks/useIsomorphicLayoutEffect.ts

@@ -0,0 +1,29 @@
+/**
+ * @file useIsomorphicLayoutEffect - SSR-safe version of useLayoutEffect
+ *
+ * Uses useLayoutEffect on the client and useEffect on the server to avoid warnings
+ * during server-side rendering (e.g., with Next.js)
+ */
+import * as React from "react";
+
+/**
+ * Check if we're running in a browser environment
+ */
+const isBrowser = typeof window !== "undefined" && typeof window.document !== "undefined";
+
+/**
+ * SSR-safe version of useLayoutEffect
+ *
+ * - Client: Uses useLayoutEffect for synchronous layout updates
+ * - Server: Uses useEffect to avoid SSR warnings
+ *
+ * @example
+ * ```tsx
+ * useIsomorphicLayoutEffect(() => {
+ *   // This runs synchronously after DOM mutations on the client
+ *   // but safely falls back to useEffect on the server
+ *   measureElement();
+ * }, [deps]);
+ * ```
+ */
+export const useIsomorphicLayoutEffect = isBrowser ? React.useLayoutEffect : React.useEffect;

package/src/hooks/useResizeObserver.tsx

@@ -0,0 +1,81 @@
+/**
+ * @file Shared useResizeObserver hook with cached observer instances.
+ */
+import * as React from "react";
+
+type Unobserve = () => void;
+type Callback = (entry: ResizeObserverEntry, observer: ResizeObserver) => void;
+type SharedObserver = {
+  observe: (target: Element, callback: Callback) => Unobserve;
+};
+const observerCache = new Map<string, SharedObserver>();
+const getSharedObserver = (options: ResizeObserverOptions) => {
+  const { box = "content-box" } = options;
+  const observerKey = `resize-box:${box}`;
+  const cached = observerCache.get(observerKey);
+  if (cached) {
+    return cached;
+  }
+  const observer = new (class {
+    #callbackMap = new Map<Element, Callback>();
+    #resizeObserver = new ResizeObserver((entries, observer) => {
+      entries.forEach((entry) => {
+        const callback = this.#callbackMap.get(entry.target);
+        if (callback) {
+          callback(entry, observer);
+        }
+      });
+    });
+    observe(target: Element, callback: Callback) {
+      this.#callbackMap.set(target, callback);
+      this.#resizeObserver.observe(target, options);
+      return () => {
+        this.#callbackMap.delete(target);
+        this.#resizeObserver.unobserve(target);
+      };
+    }
+  })();
+  observerCache.set(observerKey, observer);
+
+  return observer;
+};
+/**
+ * Observe size changes for a given element reference using shared resize observers.
+ *
+ * @param ref - Ref holding the element whose size to monitor.
+ * @param options - Resize observer configuration.
+ * @returns Latest resize entry and a derived DOMRect snapshot.
+ */
+export function useResizeObserver<T extends HTMLElement>(
+  ref: React.RefObject<T | null>,
+  { box }: ResizeObserverOptions,
+) {
+  const [entry, setEntry] = React.useState<ResizeObserverEntry | null>(null);
+  const target = ref.current;
+
+  React.useEffect(() => {
+    if (!target) {
+      return;
+    }
+
+    const observer = getSharedObserver({ box });
+    return observer.observe(target, (nextEntry) => {
+      setEntry(nextEntry);
+    });
+  }, [box, target]);
+
+  const rect = React.useMemo(() => {
+    if (!entry) {
+      return null;
+    }
+
+    if (entry.borderBoxSize?.length > 0) {
+      const size = entry.borderBoxSize[0];
+      return new DOMRect(0, 0, size.inlineSize, size.blockSize);
+    }
+
+    return entry.contentRect;
+  }, [entry]);
+
+  return { entry, rect };
+}

package/src/hooks/useScrollContainer.ts

@@ -0,0 +1,79 @@
+/**
+ * @file useScrollContainer - Detect the nearest scrollable ancestor
+ *
+ * Traverses the DOM tree to find the nearest ancestor with overflow: scroll/auto.
+ * Returns null if the document is the scroll container.
+ */
+import * as React from "react";
+
+/**
+ * Check if an element is a scroll container.
+ */
+function isScrollContainer(element: Element): boolean {
+  const style = getComputedStyle(element);
+  const overflowY = style.overflowY;
+  const overflowX = style.overflowX;
+
+  return (
+    overflowY === "scroll" ||
+    overflowY === "auto" ||
+    overflowX === "scroll" ||
+    overflowX === "auto"
+  );
+}
+
+/**
+ * Find the nearest scrollable ancestor of an element.
+ *
+ * @param element - Starting element to search from
+ * @returns The nearest scrollable ancestor, or null if document is the container
+ */
+function findScrollContainer(element: Element | null): HTMLElement | null {
+  if (!element) {
+    return null;
+  }
+
+  // eslint-disable-next-line no-restricted-syntax -- DOM traversal requires let
+  let current = element.parentElement;
+
+  while (current) {
+    if (isScrollContainer(current)) {
+      return current;
+    }
+    current = current.parentElement;
+  }
+
+  return null;
+}
+
+/**
+ * Hook to detect the nearest scrollable ancestor of a ref element.
+ *
+ * @param ref - Ref to the element to find scroll container for
+ * @returns The nearest scrollable ancestor element, or null if document is the container
+ *
+ * @example
+ * ```tsx
+ * const elementRef = useRef<HTMLDivElement>(null);
+ * const scrollContainer = useScrollContainer(elementRef);
+ * // scrollContainer is HTMLElement if in nested scroll, null if document scroll
+ * ```
+ */
+export function useScrollContainer<T extends HTMLElement>(
+  ref: React.RefObject<T | null>,
+): HTMLElement | null {
+  const [container, setContainer] = React.useState<HTMLElement | null>(null);
+
+  React.useEffect(() => {
+    const element = ref.current;
+    if (!element) {
+      setContainer(null);
+      return;
+    }
+
+    const scrollContainer = findScrollContainer(element);
+    setContainer(scrollContainer);
+  }, [ref]);
+
+  return container;
+}

package/src/hooks/useSnapAnimation.ts

@@ -0,0 +1,128 @@
+/**
+ * @file Hook for snapping element transform animation.
+ *
+ * Built on top of useAnimationFrame, provides a convenient API
+ * for animating element transforms from one position to another.
+ */
+import * as React from "react";
+import { useAnimationFrame, interpolate, easings } from "./useAnimationFrame.js";
+import type { EasingFunction } from "./useAnimationFrame.js";
+
+// Re-export easings for convenience
+export { easings } from "./useAnimationFrame.js";
+export type { EasingFunction } from "./useAnimationFrame.js";
+
+/**
+ * Options for useSnapAnimation hook.
+ */
+export type UseSnapAnimationOptions = {
+  /** Reference to the element to animate */
+  elementRef: React.RefObject<HTMLElement | null>;
+  /** Duration of animation in milliseconds */
+  duration?: number;
+  /** Easing function for the animation */
+  easing?: EasingFunction;
+  /** Callback when animation completes */
+  onComplete?: () => void;
+};
+
+/**
+ * Result from useSnapAnimation hook.
+ */
+export type UseSnapAnimationResult = {
+  /** Whether animation is currently running */
+  isAnimating: boolean;
+  /** Start a new animation from current value to target */
+  animate: (from: number, to: number, axis: "x" | "y") => void;
+  /** Cancel any running animation */
+  cancel: () => void;
+};
+
+/** Default animation duration in ms */
+const DEFAULT_DURATION = 300;
+
+/**
+ * Hook for snapping element transform animation.
+ *
+ * Animates an element's transform from one position to another
+ * using requestAnimationFrame for smooth animation.
+ *
+ * @example
+ * ```tsx
+ * const elementRef = useRef<HTMLDivElement>(null);
+ * const { animate, isAnimating } = useSnapAnimation({
+ *   elementRef,
+ *   duration: 300,
+ *   easing: easings.easeOutExpo,
+ * });
+ *
+ * // Start animation
+ * animate(currentX, targetX, "x");
+ * ```
+ */
+export function useSnapAnimation(options: UseSnapAnimationOptions): UseSnapAnimationResult {
+  const {
+    elementRef,
+    duration = DEFAULT_DURATION,
+    easing = easings.easeOutExpo,
+    onComplete,
+  } = options;
+
+  // Store animation parameters in refs for use in onFrame callback
+  const animParamsRef = React.useRef<{
+    from: number;
+    to: number;
+    axis: "x" | "y";
+  } | null>(null);
+
+  const handleFrame = React.useCallback(
+    ({ easedProgress }: { easedProgress: number }) => {
+      const element = elementRef.current;
+      const params = animParamsRef.current;
+      if (!element || !params) {
+        return;
+      }
+
+      const currentValue = interpolate(params.from, params.to, easedProgress);
+      const translateFn = params.axis === "x" ? "translateX" : "translateY";
+      element.style.transform = `${translateFn}(${currentValue}px)`;
+    },
+    [elementRef],
+  );
+
+  const { isAnimating, start, cancel } = useAnimationFrame({
+    duration,
+    easing,
+    onFrame: handleFrame,
+    onComplete,
+  });
+
+  const animate = React.useCallback(
+    (from: number, to: number, axis: "x" | "y") => {
+      const element = elementRef.current;
+      if (!element) {
+        return;
+      }
+
+      // If from and to are the same, no animation needed
+      if (Math.abs(from - to) < 0.5) {
+        const translateFn = axis === "x" ? "translateX" : "translateY";
+        element.style.transform = `${translateFn}(${to}px)`;
+        return;
+      }
+
+      // Store animation parameters
+      animParamsRef.current = { from, to, axis };
+
+      // Start animation
+      start();
+    },
+    [elementRef, start],
+  );
+
+  return {
+    isAnimating,
+    animate,
+    cancel,
+  };
+}

package/src/hooks/useSwipeContentTransform.spec.ts

@@ -0,0 +1,133 @@
+/**
+ * @file Tests for useSwipeContentTransform hook.
+ */
+import { renderHook } from "@testing-library/react";
+import { useSwipeContentTransform } from "./useSwipeContentTransform.js";
+
+describe("useSwipeContentTransform", () => {
+  const createMockElementRef = (): { element: HTMLDivElement; ref: React.RefObject<HTMLDivElement> } => {
+    const element = document.createElement("div");
+    return { element, ref: { current: element } };
+  };
+
+  it("returns initial state correctly", () => {
+    const { ref } = createMockElementRef();
+    const { result } = renderHook(() =>
+      useSwipeContentTransform({
+        elementRef: ref,
+        targetPx: 0,
+        displacement: 0,
+        isSwiping: false,
+      }),
+    );
+
+    expect(result.current.isAnimating).toBe(false);
+    expect(result.current.currentPx).toBe(0);
+  });
+
+  it("updates element transform during swipe", () => {
+    const { element, ref } = createMockElementRef();
+    const { rerender } = renderHook(
+      ({ displacement, isSwiping }) =>
+        useSwipeContentTransform({
+          elementRef: ref,
+          targetPx: 0,
+          displacement,
+          isSwiping,
+        }),
+      {
+        initialProps: { displacement: 0, isSwiping: true },
+      },
+    );
+
+    // Simulate swipe movement
+    rerender({ displacement: 100, isSwiping: true });
+
+    expect(element.style.transform).toBe("translateX(100px)");
+  });
+
+  it("uses correct transform function for vertical axis", () => {
+    const { element, ref } = createMockElementRef();
+    const { rerender } = renderHook(
+      ({ displacement, isSwiping }) =>
+        useSwipeContentTransform({
+          elementRef: ref,
+          targetPx: 0,
+          displacement,
+          isSwiping,
+          axis: "vertical",
+        }),
+      {
+        initialProps: { displacement: 0, isSwiping: true },
+      },
+    );
+
+    rerender({ displacement: 50, isSwiping: true });
+
+    expect(element.style.transform).toBe("translateY(50px)");
+  });
+
+  it("applies target position with displacement", () => {
+    const { element, ref } = createMockElementRef();
+    const { rerender } = renderHook(
+      ({ displacement, isSwiping }) =>
+        useSwipeContentTransform({
+          elementRef: ref,
+          targetPx: -300, // target is off-screen left
+          displacement,
+          isSwiping,
+        }),
+      {
+        initialProps: { displacement: 0, isSwiping: true },
+      },
+    );
+
+    // During swipe, position = targetPx + displacement
+    rerender({ displacement: 100, isSwiping: true });
+
+    expect(element.style.transform).toBe("translateX(-200px)");
+  });
+
+  it("does not update transform when element ref is null", () => {
+    const nullRef: React.RefObject<HTMLElement | null> = { current: null };
+
+    const { rerender } = renderHook(
+      ({ displacement, isSwiping }) =>
+        useSwipeContentTransform({
+          elementRef: nullRef,
+          targetPx: 0,
+          displacement,
+          isSwiping,
+        }),
+      {
+        initialProps: { displacement: 0, isSwiping: true },
+      },
+    );
+
+    // Should not throw
+    expect(() => {
+      rerender({ displacement: 100, isSwiping: true });
+    }).not.toThrow();
+  });
+
+  it("snaps to target when target changes and not swiping", () => {
+    const { element, ref } = createMockElementRef();
+    const { rerender } = renderHook(
+      ({ targetPx }) =>
+        useSwipeContentTransform({
+          elementRef: ref,
+          targetPx,
+          displacement: 0,
+          isSwiping: false,
+        }),
+      {
+        initialProps: { targetPx: 0 },
+      },
+    );
+
+    // Change target without swiping - should snap
+    rerender({ targetPx: 300 });
+
+    expect(element.style.transform).toBe("translateX(300px)");
+  });
+});