react-panel-layout 0.5.2 → 0.6.0

package/src/hooks/useContentCache.spec.tsx

@@ -0,0 +1,232 @@
+/**
+ * @file Unit tests for useContentCache hook.
+ * Verifies content caching, cache cleanup, and state preservation.
+ */
+import { renderHook, act } from "@testing-library/react";
+import * as React from "react";
+import { useContentCache } from "./useContentCache";
+
+/**
+ * Creates a simple fake function that tracks call count and can return a configured value.
+ */
+function createFake<T>(returnValue: T) {
+  const state = { callCount: 0 };
+  const fn = () => {
+    state.callCount++;
+    return returnValue;
+  };
+  return { fn, state };
+}
+
+/**
+ * Creates a fake function with custom implementation that tracks call count.
+ */
+function createFakeWithImpl<T>(impl: (id: string) => T) {
+  const state = { callCount: 0 };
+  const fn = (id: string) => {
+    state.callCount++;
+    return impl(id);
+  };
+  return { fn, state };
+}
+
+describe("useContentCache", () => {
+  describe("content caching", () => {
+    it("returns cached content for the same ID", () => {
+      const content = <div>Test Content</div>;
+      const { fn: resolveContent, state } = createFake(content);
+
+      const { result } = renderHook(() =>
+        useContentCache({
+          resolveContent,
+          validIds: ["item-1"],
+        }),
+      );
+
+      // First call should invoke resolveContent
+      const first = result.current.getCachedContent("item-1");
+      expect(state.callCount).toBe(1);
+      expect(first).toBe(content);
+
+      // Second call should return cached value without calling resolveContent
+      const second = result.current.getCachedContent("item-1");
+      expect(state.callCount).toBe(1);
+      expect(second).toBe(first);
+    });
+
+    it("returns the same reference across re-renders", () => {
+      const content = <div>Test Content</div>;
+      const { fn: resolveContent, state } = createFake(content);
+
+      const { result, rerender } = renderHook(
+        ({ validIds }) =>
+          useContentCache({
+            resolveContent,
+            validIds,
+          }),
+        { initialProps: { validIds: ["item-1"] as readonly string[] } },
+      );
+
+      const first = result.current.getCachedContent("item-1");
+      expect(state.callCount).toBe(1);
+
+      // Re-render with same validIds
+      rerender({ validIds: ["item-1"] });
+      const afterRerender = result.current.getCachedContent("item-1");
+
+      // Should still be the same reference, resolveContent not called again
+      expect(state.callCount).toBe(1);
+      expect(afterRerender).toBe(first);
+    });
+
+    it("caches content for multiple IDs independently", () => {
+      const content1 = <div>Content 1</div>;
+      const content2 = <div>Content 2</div>;
+      const { fn: resolveContent, state } = createFakeWithImpl((id: string) => {
+        if (id === "item-1") {
+          return content1;
+        }
+        if (id === "item-2") {
+          return content2;
+        }
+        return null;
+      });
+
+      const { result } = renderHook(() =>
+        useContentCache({
+          resolveContent,
+          validIds: ["item-1", "item-2"],
+        }),
+      );
+
+      const cached1 = result.current.getCachedContent("item-1");
+      const cached2 = result.current.getCachedContent("item-2");
+
+      expect(cached1).toBe(content1);
+      expect(cached2).toBe(content2);
+      expect(state.callCount).toBe(2);
+
+      // Accessing again should not call resolveContent
+      result.current.getCachedContent("item-1");
+      result.current.getCachedContent("item-2");
+      expect(state.callCount).toBe(2);
+    });
+
+    it("returns null for non-existent IDs", () => {
+      const { fn: resolveContent } = createFake(null);
+      const validIds: string[] = ["item-1"];
+
+      const { result } = renderHook(() =>
+        useContentCache({
+          resolveContent,
+          validIds,
+        }),
+      );
+
+      const cached = result.current.getCachedContent("non-existent");
+      expect(cached).toBeNull();
+    });
+  });
+
+  describe("cache cleanup", () => {
+    it("removes stale entries when validIds changes", () => {
+      const content1 = <div>Content 1</div>;
+      const content2 = <div>Content 2</div>;
+      const { fn: resolveContent, state } = createFakeWithImpl((id: string) => {
+        if (id === "item-1") {
+          return content1;
+        }
+        if (id === "item-2") {
+          return content2;
+        }
+        return null;
+      });
+
+      const { result, rerender } = renderHook(
+        ({ validIds }) =>
+          useContentCache({
+            resolveContent,
+            validIds,
+          }),
+        { initialProps: { validIds: ["item-1", "item-2"] as readonly string[] } },
+      );
+
+      // Cache both items
+      result.current.getCachedContent("item-1");
+      result.current.getCachedContent("item-2");
+      expect(state.callCount).toBe(2);
+
+      // Remove item-1 from validIds
+      rerender({ validIds: ["item-2"] });
+
+      // item-2 should still be cached
+      result.current.getCachedContent("item-2");
+      expect(state.callCount).toBe(2);
+
+      // item-1 should be removed from cache, so resolveContent will be called again
+      result.current.getCachedContent("item-1");
+      expect(state.callCount).toBe(3);
+    });
+  });
+
+  describe("clearCache", () => {
+    it("clears all cached content", () => {
+      const content = <div>Test Content</div>;
+      const { fn: resolveContent, state } = createFake(content);
+
+      const { result } = renderHook(() =>
+        useContentCache({
+          resolveContent,
+          validIds: ["item-1"],
+        }),
+      );
+
+      // Cache the content
+      result.current.getCachedContent("item-1");
+      expect(state.callCount).toBe(1);
+
+      // Clear cache
+      act(() => {
+        result.current.clearCache();
+      });
+
+      // Accessing again should call resolveContent
+      result.current.getCachedContent("item-1");
+      expect(state.callCount).toBe(2);
+    });
+  });
+
+  describe("resolveContent updates", () => {
+    it("uses latest resolveContent function via ref pattern", () => {
+      const initialContent = <div>Initial</div>;
+      const updatedContent = <div>Updated</div>;
+      const { result, rerender } = renderHook(
+        ({ content }) =>
+          useContentCache({
+            resolveContent: () => content,
+            validIds: ["item-1"],
+          }),
+        { initialProps: { content: initialContent } },
+      );
+
+      // Cache with initial content
+      const first = result.current.getCachedContent("item-1");
+      expect(first).toBe(initialContent);
+
+      // Update content
+      rerender({ content: updatedContent });
+
+      // getCachedContent should still return cached value
+      const cached = result.current.getCachedContent("item-1");
+      expect(cached).toBe(first);
+
+      // Clear cache and get new content
+      act(() => {
+        result.current.clearCache();
+      });
+
+      const updated = result.current.getCachedContent("item-1");
+      expect(updated).toBe(updatedContent);
+    });
+  });
+});

package/src/hooks/useContentCache.tsx

@@ -0,0 +1,127 @@
+/**
+ * @file Shared content caching hook for preserving React component state.
+ *
+ * This hook provides a common pattern for caching ReactNode content by ID,
+ * ensuring the same reference is returned for the same ID across re-renders.
+ * This prevents component remounting when parent components re-create content arrays.
+ *
+ * Used by:
+ * - PanelSystemContext (GridLayout layer content)
+ * - usePivot (Pivot item content)
+ * - ContentRegistry (Panel content)
+ */
+import * as React from "react";
+
+/**
+ * Function type for resolving content by ID.
+ * Called only when content is not already cached.
+ */
+export type ContentResolver<TId extends string = string> = (id: TId) => React.ReactNode | null;
+
+/**
+ * Options for useContentCache hook.
+ */
+export type UseContentCacheOptions<TId extends string = string> = {
+  /**
+   * Function to resolve content by ID.
+   * Called only when content is not already in cache.
+   */
+  resolveContent: ContentResolver<TId>;
+  /**
+   * Current valid IDs. Used to clean up stale cache entries.
+   * When an ID is removed from this array, its cached content is deleted.
+   */
+  validIds: readonly TId[];
+};
+
+/**
+ * Result from useContentCache hook.
+ */
+export type UseContentCacheResult<TId extends string = string> = {
+  /**
+   * Get cached content for an ID.
+   * Returns the same ReactNode reference for the same ID.
+   */
+  getCachedContent: (id: TId) => React.ReactNode | null;
+  /**
+   * Clear all cached content.
+   * Use when you need to force re-creation of all content.
+   */
+  clearCache: () => void;
+};
+
+/**
+ * Hook for caching ReactNode content by ID.
+ *
+ * Ensures the same ReactNode reference is returned for the same ID,
+ * preventing unnecessary component remounting when parent re-renders.
+ *
+ * @example
+ * ```tsx
+ * const { getCachedContent } = useContentCache({
+ *   resolveContent: (id) => items.find(i => i.id === id)?.content ?? null,
+ *   validIds: items.map(i => i.id),
+ * });
+ *
+ * return items.map(item => (
+ *   <div key={item.id}>{getCachedContent(item.id)}</div>
+ * ));
+ * ```
+ */
+export function useContentCache<TId extends string = string>(
+  options: UseContentCacheOptions<TId>,
+): UseContentCacheResult<TId> {
+  const { resolveContent, validIds } = options;
+
+  /**
+   * Cache storage. Key: ID, Value: cached ReactNode.
+   * Uses ref to persist across re-renders without triggering updates.
+   */
+  const cacheRef = React.useRef<Map<string, React.ReactNode>>(new Map());
+
+  /**
+   * Store resolveContent in a ref for stable getCachedContent function.
+   * This allows getCachedContent to always use the latest resolver
+   * without needing to be recreated.
+   */
+  const resolveContentRef = React.useRef(resolveContent);
+  resolveContentRef.current = resolveContent;
+
+  /**
+   * Get or create cached content for an ID.
+   * On first access, calls resolveContent and caches the result.
+   * On subsequent accesses, returns the cached reference.
+   */
+  const getCachedContent = React.useCallback((id: TId): React.ReactNode | null => {
+    const cached = cacheRef.current.get(id);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    const content = resolveContentRef.current(id);
+    cacheRef.current.set(id, content);
+    return content;
+  }, []);
+
+  /**
+   * Clear all cached content.
+   */
+  const clearCache = React.useCallback((): void => {
+    cacheRef.current.clear();
+  }, []);
+
+  /**
+   * Clean up stale cache entries when validIds changes.
+   * Removes entries for IDs that are no longer valid.
+   */
+  React.useEffect(() => {
+    const currentValidIds = new Set<string>(validIds);
+    cacheRef.current.forEach((_, id) => {
+      if (!currentValidIds.has(id)) {
+        cacheRef.current.delete(id);
+      }
+    });
+  }, [validIds]);
+
+  return { getCachedContent, clearCache };
+}

package/src/hooks/useDocumentPointerEvents.ts

@@ -0,0 +1,137 @@
+/**
+ * @file Hooks for managing document-level pointer events with proper cleanup
+ */
+import * as React from "react";
+import { useEffectEvent } from "./useEffectEvent";
+
+export type UseDocumentPointerEventsOptions = {
+  onMove?: (e: PointerEvent) => void;
+  onUp?: (e: PointerEvent) => void;
+  onCancel?: (e: PointerEvent) => void;
+};
+
+/**
+ * Custom hook for managing document-level pointer events with proper cleanup
+ * This pattern is commonly used for drag operations that need to continue
+ * even when the pointer moves outside the original element
+ */
+export function useDocumentPointerEvents(enabled: boolean, handlers: UseDocumentPointerEventsOptions) {
+  const handleMoveEvent = useEffectEvent(handlers.onMove);
+  const handleUpEvent = useEffectEvent(handlers.onUp);
+  const handleCancelEvent = useEffectEvent(handlers.onCancel);
+
+  React.useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+
+    if (handlers.onMove) {
+      document.addEventListener("pointermove", handleMoveEvent, { passive: false });
+    }
+    if (handlers.onUp) {
+      document.addEventListener("pointerup", handleUpEvent);
+    }
+    if (handlers.onCancel) {
+      document.addEventListener("pointercancel", handleCancelEvent);
+    }
+
+    // Cleanup function
+    return () => {
+      if (handlers.onMove) {
+        document.removeEventListener("pointermove", handleMoveEvent);
+      }
+      if (handlers.onUp) {
+        document.removeEventListener("pointerup", handleUpEvent);
+      }
+      if (handlers.onCancel) {
+        document.removeEventListener("pointercancel", handleCancelEvent);
+      }
+    };
+  }, [enabled, handlers.onMove, handlers.onUp, handlers.onCancel, handleMoveEvent, handleUpEvent, handleCancelEvent]);
+}
+
+/**
+ * Hook for capturing pointer during drag operations
+ * This ensures that pointer events are delivered to the capturing element
+ * even when the pointer moves outside its boundaries
+ */
+export function usePointerCapture(elementRef: React.RefObject<HTMLElement | null>, enabled: boolean, pointerId?: number) {
+  React.useEffect(() => {
+    const element = elementRef.current;
+    if (!enabled || !element || pointerId === undefined) {
+      return;
+    }
+
+    // Capture pointer
+    element.setPointerCapture(pointerId);
+
+    // Release capture on cleanup
+    return () => {
+      if (element.hasPointerCapture && element.hasPointerCapture(pointerId)) {
+        element.releasePointerCapture(pointerId);
+      }
+    };
+  }, [elementRef, enabled, pointerId]);
+}
+
+/**
+ * Hook for preventing default pointer events during operations
+ * Useful for preventing text selection, context menus, etc. during drag operations
+ */
+export function usePreventPointerDefaults(
+  elementRef: React.RefObject<HTMLElement | null>,
+  enabled: boolean,
+  events: string[] = ["pointerdown", "pointermove", "pointerup"],
+) {
+  React.useEffect(() => {
+    const element = elementRef.current;
+    if (!enabled || !element) {
+      return;
+    }
+
+    const preventDefault = (e: Event) => {
+      e.preventDefault();
+    };
+
+    // Add listeners
+    events.forEach((eventType) => {
+      element.addEventListener(eventType, preventDefault, { passive: false });
+    });
+
+    // Cleanup
+    return () => {
+      events.forEach((eventType) => {
+        element.removeEventListener(eventType, preventDefault);
+      });
+    };
+  }, [elementRef, enabled, events]);
+}
+
+/**
+ * Hook that combines multiple pointer event patterns for drag operations
+ */
+export function useDragPointerEvents(
+  elementRef: React.RefObject<HTMLElement | null>,
+  enabled: boolean,
+  options: {
+    onMove?: (e: PointerEvent) => void;
+    onUp?: (e: PointerEvent) => void;
+    onCancel?: (e: PointerEvent) => void;
+    pointerId?: number;
+    capturePointer?: boolean;
+    preventDefaults?: boolean;
+  },
+) {
+  const { onMove, onUp, onCancel, pointerId, capturePointer = true, preventDefaults = true } = options;
+
+  // Document-level event handlers
+  useDocumentPointerEvents(enabled, { onMove, onUp, onCancel });
+
+  // Pointer capture
+  const shouldCapturePointer = enabled ? capturePointer : false;
+  usePointerCapture(elementRef, shouldCapturePointer, pointerId);
+
+  // Prevent defaults
+  const shouldPreventDefaults = enabled ? preventDefaults : false;
+  usePreventPointerDefaults(elementRef, shouldPreventDefaults);
+}

package/src/hooks/useDocumentScroll.ts

@@ -0,0 +1,41 @@
+/**
+ * @file useDocumentScroll - Track document scroll position
+ *
+ * Provides the current vertical scroll position of the document.
+ * Returns negative values during overscroll/bounce on iOS Safari and PWAs.
+ */
+import * as React from "react";
+
+/**
+ * Track document scroll position.
+ *
+ * @returns Current vertical scroll position (scrollY).
+ *          Returns negative values during overscroll/bounce.
+ *
+ * @example
+ * ```tsx
+ * const scrollY = useDocumentScroll();
+ * // scrollY < 0 during overscroll (pull-down bounce)
+ * ```
+ */
+export function useDocumentScroll(): number {
+  const [scrollY, setScrollY] = React.useState(() => {
+    if (typeof window === "undefined") {
+      return 0;
+    }
+    return window.scrollY;
+  });
+
+  React.useEffect(() => {
+    const handleScroll = () => {
+      setScrollY(window.scrollY);
+    };
+
+    window.addEventListener("scroll", handleScroll, { passive: true });
+    return () => {
+      window.removeEventListener("scroll", handleScroll);
+    };
+  }, []);
+
+  return scrollY;
+}

package/src/hooks/useEffectEvent.ts

@@ -0,0 +1,40 @@
+/**
+ * @file useEffectEvent hook - Stable event handler for Effects
+ *
+ * This hook allows you to extract event handlers from Effects without causing them to re-run.
+ * The returned function is stable and can be safely used in effect dependencies.
+ *
+ * @see https://react.dev/learn/separating-events-from-effects#declaring-an-effect-event
+ */
+import * as React from "react";
+
+/**
+ * Extract event handlers from Effects to avoid unnecessary re-runs
+ *
+ * @example
+ * ```tsx
+ * function Component({ onEvent }) {
+ *   const onEventHandler = useEffectEvent(onEvent);
+ *
+ *   React.useEffect(() => {
+ *     // onEventHandler is stable, but always calls the latest onEvent
+ *     const cleanup = subscribe(onEventHandler);
+ *     return cleanup;
+ *   }, []); // No need to include onEvent in dependencies
+ * }
+ * ```
+ */
+export function useEffectEvent<Args extends unknown[], Return>(
+  fn: ((...args: Args) => Return) | undefined,
+): (...args: Args) => Return | undefined {
+  const ref = React.useRef<typeof fn>(fn);
+  ref.current = fn;
+
+  return React.useCallback((...args: Args): Return | undefined => {
+    const currentFn = ref.current;
+    if (currentFn) {
+      return currentFn(...args);
+    }
+    return undefined;
+  }, []);
+}

package/src/hooks/useElementComponentWrapper.tsx

@@ -0,0 +1,63 @@
+/**
+ * @file Hook for building wrapper components that accept either an element or a component override.
+ */
+import * as React from "react";
+
+type WrapperProps = React.HTMLAttributes<HTMLDivElement>;
+
+type CloneableProps = WrapperProps & {
+  ref?: React.Ref<HTMLDivElement>;
+};
+
+type UseElementComponentWrapperOptions = {
+  element?: React.ReactElement<WrapperProps>;
+  component?: React.ComponentType<WrapperProps & { ref?: React.Ref<HTMLDivElement> }>;
+};
+
+type WrapperComponent = React.ForwardRefExoticComponent<
+  React.PropsWithChildren<WrapperProps> & React.RefAttributes<HTMLDivElement>
+>;
+
+const createWrapperComponent = ({
+  element,
+  component: Component,
+}: UseElementComponentWrapperOptions): WrapperComponent =>
+  React.forwardRef<HTMLDivElement, React.PropsWithChildren<WrapperProps>>(({ children, ...rest }, forwardedRef) => {
+    if (element) {
+      return React.cloneElement(
+        element,
+        { ...rest, ref: forwardedRef } as CloneableProps,
+        children ?? element.props.children
+      );
+    }
+    if (Component) {
+      return (
+        <Component {...rest} ref={forwardedRef}>
+          {children}
+        </Component>
+      );
+    }
+    return (
+      <div {...rest} ref={forwardedRef}>
+        {children}
+      </div>
+    );
+  });
+
+/**
+ * Memoizes a wrapper component that can render either a provided element, a provided component, or a default tag.
+ * @returns Wrapper component honoring the overrides.
+ */
+export function useElementComponentWrapper({
+  element,
+  component,
+}: UseElementComponentWrapperOptions): WrapperComponent {
+  return React.useMemo(
+    () =>
+      createWrapperComponent({
+        element,
+        component,
+      }),
+    [component, element]
+  );
+}