react-panel-layout 0.5.2 → 0.6.0

package/src/modules/panels/rendering/ContentRegistry.spec.tsx

@@ -0,0 +1,304 @@
+/**
+ * @file ContentRegistry tests - state persistence across tab switch, panel move, and split
+ */
+/* eslint-disable no-restricted-imports, no-restricted-properties, no-restricted-syntax -- integration test */
+import { render, screen, fireEvent } from "@testing-library/react";
+import * as React from "react";
+import { ContentRegistryProvider, useContentRegistry } from "./ContentRegistry";
+import type { TabDefinition, PanelId, GroupId } from "../state/types";
+
+// Counter component that maintains state
+const CounterContent: React.FC<{ id: string }> = ({ id }) => {
+  const [count, setCount] = React.useState(0);
+  return (
+    <div data-testid={`content-${id}`}>
+      <span data-testid={`count-${id}`}>{count}</span>
+      <button data-testid={`increment-${id}`} onClick={() => setCount((c) => c + 1)}>
+        +1
+      </button>
+    </div>
+  );
+};
+
+// Test harness that simulates GroupContainer behavior
+const GroupContent: React.FC<{ groupId: GroupId }> = ({ groupId }) => {
+  const { registerContentContainer } = useContentRegistry();
+  const ref = React.useCallback(
+    (el: HTMLDivElement | null) => {
+      registerContentContainer(groupId, el);
+    },
+    [groupId, registerContentContainer],
+  );
+  return <div ref={ref} data-testid={`container-${groupId}`} style={{ width: 100, height: 100 }} />;
+};
+
+type TestState = {
+  panels: Record<PanelId, TabDefinition>;
+  placements: Record<PanelId, { groupId: GroupId; isActive: boolean }>;
+  groupIds: GroupId[];
+};
+
+const TestHarness: React.FC<{ state: TestState }> = ({ state }) => {
+  return (
+    <ContentRegistryProvider panels={state.panels} placements={state.placements}>
+      {state.groupIds.map((gid) => (
+        <GroupContent key={gid} groupId={gid} />
+      ))}
+    </ContentRegistryProvider>
+  );
+};
+
+describe("ContentRegistry", () => {
+  const createPanel = (id: string): TabDefinition => ({
+    id,
+    title: `Panel ${id}`,
+    render: (panelId) => <CounterContent key={panelId} id={panelId} />,
+  });
+
+  beforeEach(() => {
+    // Mock ResizeObserver (polyfill provided in vitest.setup.ts)
+
+    // Mock pointer capture methods
+    Element.prototype.setPointerCapture = vi.fn();
+    Element.prototype.releasePointerCapture = vi.fn();
+    // Mock getBoundingClientRect
+    Element.prototype.getBoundingClientRect = vi.fn().mockReturnValue({
+      top: 0,
+      left: 0,
+      width: 100,
+      height: 100,
+      right: 100,
+      bottom: 100,
+      x: 0,
+      y: 0,
+      toJSON: () => ({}),
+    });
+  });
+
+  afterEach(() => {
+    // Clean up any portal containers
+    document.querySelectorAll("[data-panel-content-root]").forEach((el) => el.remove());
+  });
+
+  it("should render content inside the registered container element", () => {
+    const panels = {
+      "panel-1": createPanel("panel-1"),
+    };
+
+    const state: TestState = {
+      panels,
+      placements: {
+        "panel-1": { groupId: "group-1", isActive: true },
+      },
+      groupIds: ["group-1"],
+    };
+
+    render(<TestHarness state={state} />);
+
+    // The content should be rendered
+    const content = screen.getByTestId("content-panel-1");
+    expect(content).toBeInTheDocument();
+
+    // The container element should exist
+    const container = screen.getByTestId("container-group-1");
+    expect(container).toBeInTheDocument();
+
+    // Content should be inside the container (not in a separate portal overlay)
+    expect(container.contains(content)).toBe(true);
+  });
+
+  it("should preserve state when switching tabs", async () => {
+    const panels = {
+      "panel-1": createPanel("panel-1"),
+      "panel-2": createPanel("panel-2"),
+    };
+
+    const initialState: TestState = {
+      panels,
+      placements: {
+        "panel-1": { groupId: "group-1", isActive: true },
+        "panel-2": { groupId: "group-1", isActive: false },
+      },
+      groupIds: ["group-1"],
+    };
+
+    const { rerender } = render(<TestHarness state={initialState} />);
+
+    // Increment panel-1's counter
+    const incrementBtn = screen.getByTestId("increment-panel-1");
+    fireEvent.click(incrementBtn);
+    expect(screen.getByTestId("count-panel-1").textContent).toBe("1");
+
+    // Switch to panel-2 (make it active, panel-1 inactive)
+    const switchedState: TestState = {
+      panels,
+      placements: {
+        "panel-1": { groupId: "group-1", isActive: false },
+        "panel-2": { groupId: "group-1", isActive: true },
+      },
+      groupIds: ["group-1"],
+    };
+    rerender(<TestHarness state={switchedState} />);
+
+    // Switch back to panel-1
+    rerender(<TestHarness state={initialState} />);
+
+    // panel-1's counter should still be 1
+    expect(screen.getByTestId("count-panel-1").textContent).toBe("1");
+  });
+
+  it("should preserve state when moving panel to another group", async () => {
+    const panels = {
+      "panel-1": createPanel("panel-1"),
+    };
+
+    const initialState: TestState = {
+      panels,
+      placements: {
+        "panel-1": { groupId: "group-1", isActive: true },
+      },
+      groupIds: ["group-1"],
+    };
+
+    const { rerender } = render(<TestHarness state={initialState} />);
+
+    // Increment counter
+    fireEvent.click(screen.getByTestId("increment-panel-1"));
+    fireEvent.click(screen.getByTestId("increment-panel-1"));
+    expect(screen.getByTestId("count-panel-1").textContent).toBe("2");
+
+    // Move panel to group-2 (new group is created at the same time)
+    const movedState: TestState = {
+      panels,
+      placements: {
+        "panel-1": { groupId: "group-2", isActive: true },
+      },
+      groupIds: ["group-1", "group-2"],
+    };
+    rerender(<TestHarness state={movedState} />);
+
+    // Counter should still be 2
+    expect(screen.getByTestId("count-panel-1").textContent).toBe("2");
+  });
+
+  it("should preserve state when splitting panel (adding new group)", async () => {
+    const panels = {
+      "panel-1": createPanel("panel-1"),
+      "panel-2": createPanel("panel-2"),
+    };
+
+    // Initial: both panels in group-1
+    const initialState: TestState = {
+      panels,
+      placements: {
+        "panel-1": { groupId: "group-1", isActive: true },
+        "panel-2": { groupId: "group-1", isActive: false },
+      },
+      groupIds: ["group-1"],
+    };
+
+    const { rerender } = render(<TestHarness state={initialState} />);
+
+    // Increment panel-1's counter to 3
+    fireEvent.click(screen.getByTestId("increment-panel-1"));
+    fireEvent.click(screen.getByTestId("increment-panel-1"));
+    fireEvent.click(screen.getByTestId("increment-panel-1"));
+    expect(screen.getByTestId("count-panel-1").textContent).toBe("3");
+
+    // Split: panel-2 moves to new group-2
+    const splitState: TestState = {
+      panels,
+      placements: {
+        "panel-1": { groupId: "group-1", isActive: true },
+        "panel-2": { groupId: "group-2", isActive: true },
+      },
+      groupIds: ["group-1", "group-2"],
+    };
+    rerender(<TestHarness state={splitState} />);
+
+    // panel-1's counter should still be 3
+    expect(screen.getByTestId("count-panel-1").textContent).toBe("3");
+  });
+
+  it("should handle multiple panels in same group without wrapper conflicts", () => {
+    const panels = {
+      "panel-1": createPanel("panel-1"),
+      "panel-2": createPanel("panel-2"),
+      "panel-3": createPanel("panel-3"),
+    };
+
+    const state: TestState = {
+      panels,
+      placements: {
+        "panel-1": { groupId: "group-1", isActive: true },
+        "panel-2": { groupId: "group-1", isActive: false },
+        "panel-3": { groupId: "group-1", isActive: false },
+      },
+      groupIds: ["group-1"],
+    };
+
+    render(<TestHarness state={state} />);
+
+    const container = screen.getByTestId("container-group-1");
+
+    // All panel wrappers should be inside the container
+    const wrappers = container.querySelectorAll("[data-panel-wrapper]");
+    expect(wrappers.length).toBe(3);
+
+    // Each wrapper should have unique panel id
+    const wrapperIds = Array.from(wrappers).map((w) => w.getAttribute("data-panel-wrapper"));
+    expect(wrapperIds).toContain("panel-1");
+    expect(wrapperIds).toContain("panel-2");
+    expect(wrapperIds).toContain("panel-3");
+
+    // Active panel content should be visible
+    expect(screen.getByTestId("content-panel-1")).toBeVisible();
+  });
+
+  it("should not have wrapper nesting issues when panels move between groups", () => {
+    const panels = {
+      "panel-1": createPanel("panel-1"),
+      "panel-2": createPanel("panel-2"),
+    };
+
+    const initialState: TestState = {
+      panels,
+      placements: {
+        "panel-1": { groupId: "group-1", isActive: true },
+        "panel-2": { groupId: "group-1", isActive: false },
+      },
+      groupIds: ["group-1", "group-2"],
+    };
+
+    const { rerender } = render(<TestHarness state={initialState} />);
+
+    // Initially both panels in group-1
+    const container1 = screen.getByTestId("container-group-1");
+    expect(container1.querySelectorAll("[data-panel-wrapper]").length).toBe(2);
+
+    // Move panel-2 to group-2
+    const movedState: TestState = {
+      panels,
+      placements: {
+        "panel-1": { groupId: "group-1", isActive: true },
+        "panel-2": { groupId: "group-2", isActive: true },
+      },
+      groupIds: ["group-1", "group-2"],
+    };
+    rerender(<TestHarness state={movedState} />);
+
+    // Now each group should have exactly one wrapper
+    const container1After = screen.getByTestId("container-group-1");
+    const container2 = screen.getByTestId("container-group-2");
+
+    expect(container1After.querySelectorAll("[data-panel-wrapper]").length).toBe(1);
+    expect(container2.querySelectorAll("[data-panel-wrapper]").length).toBe(1);
+
+    // Wrappers should not be nested inside each other
+    const allWrappers = document.querySelectorAll("[data-panel-wrapper]");
+    allWrappers.forEach((wrapper) => {
+      const nestedWrappers = wrapper.querySelectorAll("[data-panel-wrapper]");
+      expect(nestedWrappers.length).toBe(0);
+    });
+  });
+});

package/src/modules/panels/rendering/ContentRegistry.tsx

@@ -0,0 +1,205 @@
+/**
+ * @file Registry for panel content instances.
+ * Manages component lifecycle to preserve state across tab switches and panel moves.
+ *
+ * ## Architecture
+ *
+ * This module solves the problem of preserving React component state when panels
+ * move between different container elements (groups).
+ *
+ * ### The Problem
+ * React portals remount their content when the container element changes.
+ * This is React's intentional behavior, but it causes state loss when panels move.
+ *
+ * ### The Solution
+ * 1. Create a stable wrapper element per panel (outside React's tree management)
+ * 2. Use createPortal to render React content INTO the wrapper
+ * 3. Move the wrapper between containers using appendChild
+ *
+ * This works because:
+ * - React only manages content INSIDE the wrapper (via portal)
+ * - React doesn't track the wrapper's position in DOM
+ * - Moving the wrapper doesn't trigger React reconciliation
+ *
+ * ### DOM API Usage
+ * - document.createElement: Creates wrapper element (once per panel)
+ * - appendChild: Moves wrapper to target container
+ * - removeChild: Cleans up wrapper on unmount
+ *
+ * These are the minimum DOM APIs required. React features handle everything else.
+ */
+import * as React from "react";
+import { createPortal } from "react-dom";
+import type { PanelId, GroupId, TabDefinition } from "../state/types";
+import { useIsomorphicLayoutEffect } from "../../../hooks/useIsomorphicLayoutEffect";
+import { useContentCache } from "../../../hooks/useContentCache";
+
+type PanelPlacement = {
+  groupId: GroupId;
+  isActive: boolean;
+};
+
+type ContentRegistryContextValue = {
+  registerContentContainer: (groupId: GroupId, element: HTMLElement | null) => void;
+};
+
+const ContentRegistryContext = React.createContext<ContentRegistryContextValue | null>(null);
+
+export const useContentRegistry = (): ContentRegistryContextValue => {
+  const ctx = React.useContext(ContentRegistryContext);
+  if (!ctx) {
+    throw new Error("useContentRegistry must be used within ContentRegistryProvider");
+  }
+  return ctx;
+};
+
+/**
+ * Creates a wrapper element for panel content.
+ * This element lives outside React's tree management so it can be moved freely.
+ */
+const createPanelWrapper = (panelId: PanelId): HTMLDivElement => {
+  const wrapper = document.createElement("div");
+  wrapper.setAttribute("data-panel-wrapper", panelId);
+  wrapper.style.display = "contents";
+  return wrapper;
+};
+
+/**
+ * Hook to manage wrapper element lifecycle and positioning.
+ *
+ * Uses React.useState for lazy initialization (wrapper created once).
+ * Uses useIsomorphicLayoutEffect for DOM manipulation (SSR-safe).
+ */
+const usePanelWrapper = (
+  panelId: PanelId,
+  containerElement: HTMLElement | null,
+  isActive: boolean,
+): HTMLDivElement => {
+  // Create wrapper once using React's lazy state initialization
+  const [wrapper] = React.useState(() => createPanelWrapper(panelId));
+
+  // Manage wrapper position and visibility
+  useIsomorphicLayoutEffect(() => {
+    wrapper.style.display = isActive ? "contents" : "none";
+
+    if (containerElement && wrapper.parentElement !== containerElement) {
+      containerElement.appendChild(wrapper);
+    }
+
+    return () => {
+      wrapper.parentElement?.removeChild(wrapper);
+    };
+  }, [wrapper, containerElement, isActive]);
+
+  return wrapper;
+};
+
+/**
+ * Host component for panel content.
+ * Uses createPortal to render React content into a stable wrapper element.
+ */
+type PanelContentHostProps = {
+  panelId: PanelId;
+  content: React.ReactNode;
+  placement: PanelPlacement | null;
+  containerElement: HTMLElement | null;
+};
+
+const PanelContentHost: React.FC<PanelContentHostProps> = React.memo(
+  ({ panelId, content, placement, containerElement }) => {
+    const isActive = placement?.isActive ?? false;
+    const wrapper = usePanelWrapper(panelId, containerElement, isActive);
+
+    // Portal renders React content INTO the wrapper
+    // React manages content lifecycle, not wrapper position
+    return createPortal(
+      <React.Activity mode={isActive ? "visible" : "hidden"}>
+        {content}
+      </React.Activity>,
+      wrapper,
+    );
+  },
+);
+PanelContentHost.displayName = "PanelContentHost";
+
+type ContentRegistryProviderProps = React.PropsWithChildren<{
+  panels: Record<PanelId, TabDefinition>;
+  placements: Record<PanelId, PanelPlacement>;
+}>;
+
+/**
+ * Provider that manages panel content lifecycle.
+ * Caches rendered content per panel to preserve React element identity.
+ */
+export const ContentRegistryProvider: React.FC<ContentRegistryProviderProps> = ({
+  children,
+  panels,
+  placements,
+}) => {
+  const [containers, setContainers] = React.useState<Map<GroupId, HTMLElement>>(new Map());
+
+  const registerContentContainer = React.useCallback((groupId: GroupId, element: HTMLElement | null): void => {
+    setContainers((prev) => {
+      const next = new Map(prev);
+      if (element) {
+        next.set(groupId, element);
+      } else {
+        next.delete(groupId);
+      }
+      return next;
+    });
+  }, []);
+
+  const value = React.useMemo<ContentRegistryContextValue>(
+    () => ({ registerContentContainer }),
+    [registerContentContainer],
+  );
+
+  // Store panels in ref for stable resolveContent function
+  const panelsRef = React.useRef(panels);
+  panelsRef.current = panels;
+
+  // Content resolver for useContentCache
+  const resolveContent = React.useCallback((panelId: PanelId): React.ReactNode | null => {
+    const tab = panelsRef.current[panelId];
+    if (!tab) {
+      return null;
+    }
+    return tab.render(tab.id);
+  }, []);
+
+  // Valid IDs for cache cleanup
+  const validIds = React.useMemo(() => Object.keys(panels), [panels]);
+
+  // Use shared content cache hook
+  const { getCachedContent } = useContentCache({
+    resolveContent,
+    validIds,
+  });
+
+  const panelIds = Object.keys(panels);
+
+  return (
+    <ContentRegistryContext.Provider value={value}>
+      {children}
+      {panelIds.map((panelId) => {
+        const tab = panels[panelId];
+        if (!tab) {
+          return null;
+        }
+        const placement = placements[panelId] ?? null;
+        const containerElement = placement ? containers.get(placement.groupId) ?? null : null;
+        const content = getCachedContent(panelId);
+        return (
+          <PanelContentHost
+            key={panelId}
+            panelId={panelId}
+            content={content}
+            placement={placement}
+            containerElement={containerElement}
+          />
+        );
+      })}
+    </ContentRegistryContext.Provider>
+  );
+};

package/src/modules/panels/rendering/GroupContainer.tsx

@@ -0,0 +1,65 @@
+/**
+ * @file Connected group container bridging panel contexts to the presentational view.
+ */
+import * as React from "react";
+import type { GroupId, PanelGroupRenderProps, TabBarRenderProps } from "../../panels/state/types";
+import { usePanelRenderContext } from "../rendering/RenderContext";
+import { useDomRegistry } from "../dom/DomRegistry";
+import { PanelGroupView } from "../../../components/panels/PanelGroupView";
+import { TabBar } from "../../../components/tabs/TabBar";
+
+export type ConnectedGroupContainerProps = {
+  id: GroupId;
+  TabBarComponent?: React.ComponentType<TabBarRenderProps>;
+  PanelGroupComponent?: React.ComponentType<PanelGroupRenderProps>;
+};
+
+export const GroupContainer: React.FC<ConnectedGroupContainerProps> = ({ id, TabBarComponent, PanelGroupComponent }) => {
+  const { getGroup, getGroupContent, onClickTab, onAddTab, onCloseTab, onStartTabDrag, doubleClickToAdd, registerContentContainer } = usePanelRenderContext();
+  const { setGroupEl, setTabbarEl, setContentEl } = useDomRegistry();
+  const groupRef = React.useCallback(
+    (el: HTMLDivElement | null) => {
+      setGroupEl(id, el);
+    },
+    [id, setGroupEl],
+  );
+  const contentRef = React.useCallback(
+    (el: HTMLDivElement | null) => {
+      setContentEl(id, el);
+      registerContentContainer(id, el);
+    },
+    [id, setContentEl, registerContentContainer],
+  );
+  const tabbarRef = React.useCallback(
+    (el: HTMLDivElement | null) => {
+      setTabbarEl(id, el);
+    },
+    [id, setTabbarEl],
+  );
+  const group = getGroup(id);
+  if (!group) {
+    return null;
+  }
+  const content = getGroupContent(id);
+  const TabBarImpl = TabBarComponent ?? TabBar;
+  const PanelGroupImpl: React.ComponentType<PanelGroupRenderProps> = PanelGroupComponent ?? ((props) => <PanelGroupView {...props} />);
+  return (
+    <PanelGroupImpl
+      group={group}
+      tabbar={
+        <TabBarImpl
+          rootRef={tabbarRef}
+          group={group}
+          onClickTab={(tabId) => onClickTab(id, tabId)}
+          onAddTab={onAddTab}
+          onCloseTab={onCloseTab}
+          onStartDrag={(tabId, groupId, e) => onStartTabDrag(tabId, groupId, e)}
+          doubleClickToAdd={doubleClickToAdd}
+        />
+      }
+      content={content}
+      groupRef={groupRef}
+      contentRef={contentRef}
+    />
+  );
+};

package/src/modules/panels/rendering/RenderBridge.tsx

@@ -0,0 +1,115 @@
+/**
+ * @file Bridge component that binds InteractionsContext to PanelRenderContext using panel state.
+ */
+import * as React from "react";
+import { usePanelInteractions } from "../interactions/InteractionsContext";
+import { PanelRenderProvider } from "./RenderContext";
+import { usePanelState } from "../state/StateContext";
+import { ContentRegistryProvider, useContentRegistry } from "./ContentRegistry";
+import type { PanelId, GroupId } from "../state/types";
+
+type PanelPlacement = {
+  groupId: GroupId;
+  isActive: boolean;
+};
+
+const RenderBridgeInner: React.FC<React.PropsWithChildren<{ emptyContentComponent?: React.ComponentType; doubleClickToAdd?: boolean }>> = ({
+  children,
+  emptyContentComponent,
+  doubleClickToAdd,
+}) => {
+  const interactions = usePanelInteractions();
+  const { state, actions } = usePanelState();
+  const { registerContentContainer } = useContentRegistry();
+
+  const DefaultEmpty: React.FC = React.useCallback(() => {
+    return React.createElement("div", { style: { color: "#888", fontSize: 12, padding: 12 } }, "No tabs");
+  }, []);
+  const Empty = emptyContentComponent ?? DefaultEmpty;
+
+  const getGroup = React.useCallback(
+    (id: string) => {
+      const g = state.groups[id];
+      if (!g) {
+        return null;
+      }
+      const tabs = g.tabIds.map((tid) => state.panels[tid]).filter(Boolean);
+      return { ...g, tabs };
+    },
+    [state.groups, state.panels],
+  );
+
+  const getGroupContent = React.useCallback(
+    (id: string) => {
+      const group = state.groups[id];
+      if (!group || group.tabIds.length === 0) {
+        return <Empty />;
+      }
+      // Content is rendered via Portal from ContentRegistry
+      return null;
+    },
+    [state.groups, Empty],
+  );
+
+  const onClickTab = React.useCallback((gid: string, tabId: string) => {
+    actions.setActiveTab(gid, tabId);
+  }, [actions]);
+
+  const onAddTab = React.useCallback((gid: string) => {
+    actions.addNewTab({ groupId: gid, title: "New Tab", makeActive: true });
+  }, [actions]);
+
+  const onCloseTab = React.useCallback((gid: string, tabId: string) => {
+    actions.removeTab(gid, tabId);
+  }, [actions]);
+
+  const onStartTabDrag = React.useCallback((tabId: string, groupId: string, e: React.PointerEvent) => {
+    actions.setActiveTab(groupId, tabId);
+    interactions.onStartTabDrag(tabId, groupId, e);
+  }, [actions, interactions]);
+
+  const onStartContentDrag = React.useCallback((groupId: string, e: React.PointerEvent<HTMLDivElement>) => {
+    const g = state.groups[groupId];
+    if (!g || !g.activeTabId) {
+      return;
+    }
+    interactions.onStartContentDrag(groupId, g.activeTabId, e);
+  }, [state.groups, interactions]);
+
+  const value = React.useMemo(
+    () => ({ getGroup, getGroupContent, onClickTab, onAddTab, onCloseTab, onStartTabDrag, onStartContentDrag, doubleClickToAdd, registerContentContainer }),
+    [getGroup, getGroupContent, onClickTab, onAddTab, onCloseTab, onStartTabDrag, onStartContentDrag, doubleClickToAdd, registerContentContainer],
+  );
+
+  return <PanelRenderProvider value={value}>{children}</PanelRenderProvider>;
+};
+
+export const RenderBridge: React.FC<React.PropsWithChildren<{ emptyContentComponent?: React.ComponentType; doubleClickToAdd?: boolean }>> = ({
+  children,
+  emptyContentComponent,
+  doubleClickToAdd,
+}) => {
+  const { state } = usePanelState();
+
+  // Compute placements: which group each panel belongs to and if it's active
+  const placements = React.useMemo(() => {
+    const result: Record<PanelId, PanelPlacement> = {};
+    for (const [groupId, group] of Object.entries(state.groups)) {
+      for (const tabId of group.tabIds) {
+        result[tabId] = {
+          groupId,
+          isActive: tabId === group.activeTabId,
+        };
+      }
+    }
+    return result;
+  }, [state.groups]);
+
+  return (
+    <ContentRegistryProvider panels={state.panels} placements={placements}>
+      <RenderBridgeInner emptyContentComponent={emptyContentComponent} doubleClickToAdd={doubleClickToAdd}>
+        {children}
+      </RenderBridgeInner>
+    </ContentRegistryProvider>
+  );
+};