react-panel-layout 0.5.2 → 0.6.0

package/src/modules/panels/state/types.ts

@@ -0,0 +1,142 @@
+/**
+ * @file Types for VSCode-like panel system (tabs, groups, splits).
+ */
+import * as React from "react";
+
+export type PanelId = string;
+export type GroupId = string;
+
+export type SplitDirection = "vertical" | "horizontal";
+
+type RowsColsSplitLimits = {
+  /**
+   * Maximum number of rows (horizontal panes stacked vertically). Mirrors the HTML `rows` attribute.
+   * Value of 1 disables horizontal splits.
+   */
+  rows?: number;
+  /**
+   * Maximum number of columns (vertical panes stacked horizontally). Mirrors the HTML `cols` attribute.
+   * Value of 1 disables vertical splits.
+   */
+  cols?: number;
+};
+
+type LegacySplitLimits = {
+  /**
+   * @deprecated Use `rows` instead.
+   */
+  maxHorizontal?: number;
+  /**
+   * @deprecated Use `cols` instead.
+   */
+  maxVertical?: number;
+};
+
+/**
+ * Controls how many times panes may be split. Accepts a single number (applied to both rows/cols)
+ * or an object that mirrors HTML's `rows`/`cols` attributes for clarity.
+ */
+export type PanelSplitLimits = number | RowsColsSplitLimits | LegacySplitLimits;
+
+export type TabDefinition = {
+  id: PanelId;
+  title: string;
+  /** Render function receives panel id to enable proper keying */
+  render: (id: PanelId) => React.ReactNode;
+};
+
+export type GroupModel = {
+  id: GroupId;
+  /** Ordered panel ids belonging to this group */
+  tabIds: PanelId[];
+  /** Deprecated: view adapter may synthesize from registry; kept for backward-compat */
+  tabs: TabDefinition[];
+  activeTabId: PanelId | null;
+};
+
+export type SplitNode =
+  | { type: "group"; groupId: GroupId }
+  | { type: "split"; direction: SplitDirection; ratio: number; a: SplitNode; b: SplitNode };
+
+export type PanelTree = SplitNode;
+
+export type PanelSystemState = {
+  tree: PanelTree;
+  /** Single source registry of panels (id -> definition) */
+  panels: Record<PanelId, TabDefinition>;
+  groups: Record<GroupId, GroupModel>;
+  /** Keeps stable order for focusing groups with Cmd+1..9 */
+  groupOrder: GroupId[];
+  /** Currently focused group */
+  focusedGroupId: GroupId | null;
+};
+
+export type DropZone = "center" | "left" | "right" | "top" | "bottom";
+
+export type DraggingTab = {
+  tabId: PanelId;
+  fromGroupId: GroupId;
+};
+
+export type PanelCommands = {
+  splitFocused: (direction: SplitDirection) => void;
+  focusGroupIndex: (index1Based: number) => void;
+  focusNextGroup: () => void;
+  focusPrevGroup: () => void;
+  closeFocusedGroup: () => void;
+};
+
+// Public render props for pluggable UI components
+export type TabBarRenderProps = {
+  group: GroupModel;
+  onClickTab: (tabId: string) => void;
+  onStartDrag?: (tabId: string, groupId: string, e: React.PointerEvent) => void;
+  rootRef?: React.Ref<HTMLDivElement>;
+  /** Optional: request to add a tab to this group (UI triggers only; state lives in context) */
+  onAddTab?: (groupId: GroupId) => void;
+  /** Optional: request to close a tab (UI triggers only; state lives in context) */
+  onCloseTab?: (groupId: GroupId, tabId: PanelId) => void;
+  /** Enable double-click on empty tabbar area to add a new tab (default: false) */
+  doubleClickToAdd?: boolean;
+};
+
+export type PanelGroupRenderProps = {
+  group: GroupModel;
+  tabbar: React.ReactNode;
+  content: React.ReactNode;
+  onContentPointerDown?: (e: React.PointerEvent<HTMLDivElement>) => void;
+  groupRef?: React.Ref<HTMLDivElement>;
+  contentRef?: React.Ref<HTMLDivElement>;
+};
+
+export type PanelSystemProps = {
+  /** Initial tree and groups. Component is uncontrolled by default. */
+  initialState: PanelSystemState;
+  /** Explicit group id factory. Required by no-magic policy. */
+  createGroupId: () => GroupId;
+  /** Explicit panel id factory for newly-created tabs. Required by no-magic policy when adding tabs via UI. */
+  createPanelId?: () => PanelId;
+  /** Adapter layout mode: explicit selection required by no-magic policy. */
+  layoutMode: "absolute" | "grid";
+  /** When layoutMode==='grid', whether grid track resize is interactive (single source if false). */
+  gridTracksInteractive?: boolean;
+  /** Drag activation threshold in px (explicit, no-magic). */
+  dragThresholdPx: number;
+  /** View component for a group (no operation injection at PanelSystem layer). */
+  view?: React.ComponentType<{ groupId: GroupId }>;
+  /** Optional component for empty content in a group (when no active tab). */
+  emptyContentComponent?: React.ComponentType;
+  /** Optional controlled state */
+  state?: PanelSystemState;
+  onStateChange?: (next: PanelSystemState) => void;
+  /** ClassName/style passthrough */
+  className?: string;
+  style?: React.CSSProperties;
+  /** Pluggable UI components */
+  tabBarComponent?: React.ComponentType<TabBarRenderProps>;
+  panelGroupComponent?: React.ComponentType<PanelGroupRenderProps>;
+  /** Optional limits controlling split directions. */
+  splitLimits?: PanelSplitLimits;
+  /** Enable double-click on empty tabbar area to add a new tab (default: false) */
+  doubleClickToAdd?: boolean;
+};

package/src/modules/panels/system/PanelSystem.empty-tabbar.spec.tsx

@@ -0,0 +1,53 @@
+/**
+ * @file Integration test: empty groups are auto-cleaned (no empty tabbars remain)
+ */
+import * as React from "react";
+import { render, screen } from "@testing-library/react";
+import { PanelSystem } from "./PanelSystem";
+import { buildInitialState, splitLeaf, createEmptyGroup } from "..";
+import type { TabDefinition } from "..";
+
+const makeTabs = (): TabDefinition[] => {
+  return [
+    { id: "welcome", title: "Welcome", render: () => React.createElement("div", null, "Welcome") },
+  ];
+};
+
+describe("PanelSystem empty groups cleanup", () => {
+  it("collapses empty groups so only non-empty tabbars render", () => {
+    const tabs = makeTabs();
+    const initial = buildInitialState(tabs);
+    // Split once to create a second, empty group
+    const { tree, newGroupId } = splitLeaf(initial.tree, initial.groupOrder[0], "vertical", () => "g_2");
+    const state = {
+      ...initial,
+      tree,
+      groupOrder: [initial.groupOrder[0], newGroupId],
+      groups: { ...initial.groups, [newGroupId]: createEmptyGroup(newGroupId) },
+    };
+
+    const Wrapper: React.FC = () => {
+      const [s, setS] = React.useState(state);
+      return (
+        <div style={{ width: 800, height: 600 }}>
+          <PanelSystem
+            initialState={s}
+            state={s}
+            onStateChange={setS}
+            createGroupId={() => `g_${Math.random().toString(36).slice(2, 6)}`}
+            layoutMode="grid"
+            gridTracksInteractive={false}
+            dragThresholdPx={6}
+            style={{ width: "100%", height: "100%" }}
+          />
+        </div>
+      );
+    };
+
+    render(<Wrapper />);
+
+    // After mount, the empty split is cleaned up; only one tablist remains
+    const tablists = screen.getAllByRole("tablist");
+    expect(tablists.length).toBe(1);
+  });
+});

package/src/modules/panels/system/PanelSystem.tab-click-activates.spec.tsx

@@ -0,0 +1,44 @@
+/**
+ * @file Integration test: clicking a tab activates it even with DnD enabled
+ */
+import * as React from "react";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { PanelSystem } from "./PanelSystem";
+import { buildInitialState } from "..";
+import type { TabDefinition } from "..";
+
+const makeTabs = (): TabDefinition[] => {
+  return [
+    { id: "welcome", title: "Welcome", render: () => React.createElement("div", null, "Welcome") },
+    { id: "explorer", title: "Explorer", render: () => React.createElement("div", null, "Explorer") },
+    { id: "preview", title: "Preview", render: () => React.createElement("div", null, "Preview") },
+  ];
+};
+
+describe("PanelSystem tab click activates", () => {
+  it("activates clicked tab reliably", () => {
+    const tabs = makeTabs();
+    const initial = buildInitialState(tabs);
+
+    render(
+      <div style={{ width: 800, height: 600 }}>
+        <PanelSystem
+          initialState={initial}
+          createGroupId={() => "g_2"}
+          layoutMode="grid"
+          gridTracksInteractive={false}
+          dragThresholdPx={6}
+          style={{ width: "100%", height: "100%" }}
+        />
+      </div>,
+    );
+
+    // Click Explorer tab
+    const before = screen.getByRole("tab", { name: /explorer/i });
+    fireEvent.click(before);
+    const explorer = screen.getByRole("tab", { name: /explorer/i });
+    // Activated tab has aria-selected=true (re-query to avoid stale node)
+    expect(explorer.getAttribute("aria-selected")).toBe("true");
+    // Content render will include the same label; aria-selected check is sufficient
+  });
+});

package/src/modules/panels/system/PanelSystem.tab-reorder.spec.tsx

@@ -0,0 +1,64 @@
+/**
+ * @file Regression test: tabs reorder within the same tab bar.
+ */
+import * as React from "react";
+import { render, act } from "@testing-library/react";
+import type { PanelSystemState, TabDefinition } from "../state/types";
+import { buildInitialState } from "..";
+import { PanelStateProvider, usePanelState } from "../state/StateContext";
+import { useCommitHandlers } from "../state/commands";
+
+type RecorderHandle = {
+  handlers: ReturnType<typeof useCommitHandlers>;
+  getState: () => PanelSystemState;
+};
+
+const HandlerRecorder = React.forwardRef<RecorderHandle>((_props, ref) => {
+  const handlers = useCommitHandlers();
+  const { state } = usePanelState();
+  React.useImperativeHandle(
+    ref,
+    () => ({
+      handlers,
+      getState: () => state,
+    }),
+    [handlers, state],
+  );
+  return null;
+});
+HandlerRecorder.displayName = "HandlerRecorder";
+
+const makeTabs = (): TabDefinition[] => [
+  { id: "welcome", title: "Welcome", render: () => React.createElement("div", null, "Welcome") },
+  { id: "explorer", title: "Explorer", render: () => React.createElement("div", null, "Explorer") },
+  { id: "preview", title: "Preview", render: () => React.createElement("div", null, "Preview") },
+];
+
+describe("PanelSystem tab reorder", () => {
+  it("reorders tabs within the same group", () => {
+    const initial = buildInitialState(makeTabs());
+    const ref = React.createRef<RecorderHandle>();
+
+    render(
+      <PanelStateProvider initialState={initial} createGroupId={() => "g_new"}>
+        <HandlerRecorder ref={ref} />
+      </PanelStateProvider>,
+    );
+
+    expect(ref.current).not.toBeNull();
+
+    const targetGroupId = initial.groupOrder[0];
+    act(() => {
+      ref.current?.handlers.onCommitTabDrop({
+        fromGroupId: targetGroupId,
+        tabId: "preview",
+        targetGroupId,
+        targetIndex: 0,
+      });
+    });
+
+    const state = ref.current?.getState();
+    expect(state?.groups[targetGroupId]?.tabIds).toEqual(["preview", "welcome", "explorer"]);
+    expect(state?.groups[targetGroupId]?.tabs.map((tab) => tab.id)).toEqual(["preview", "welcome", "explorer"]);
+  });
+});

package/src/modules/panels/system/PanelSystem.tabs-no-dup.spec.tsx

@@ -0,0 +1,57 @@
+/**
+ * @file Integration test: clicking tabs does not duplicate TabBar items
+ */
+import * as React from "react";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { PanelSystem } from "./PanelSystem";
+import { buildInitialState } from "..";
+import type { TabDefinition } from "..";
+
+const makeTabs = (): TabDefinition[] => {
+  return [
+    { id: "welcome", title: "Welcome", render: () => React.createElement("div", null, "Welcome") },
+    { id: "explorer", title: "Explorer", render: () => React.createElement("div", null, "Explorer") },
+    { id: "preview", title: "Preview", render: () => React.createElement("div", null, "Preview") },
+  ];
+};
+
+const idFactory = () => {
+  const counter = { value: 2 };
+  return () => {
+    counter.value += 1;
+    return `g_${String(counter.value)}`;
+  };
+};
+
+describe("PanelSystem tabs", () => {
+  it("does not duplicate tabs when clicking items", () => {
+    const tabs = makeTabs();
+    const initial = buildInitialState(tabs);
+    const createGroupId = idFactory();
+
+    render(
+      <div style={{ width: 800, height: 600 }}>
+        <PanelSystem
+          initialState={initial}
+          createGroupId={createGroupId}
+          layoutMode="grid"
+          gridTracksInteractive={false}
+          dragThresholdPx={6}
+          style={{ width: "100%", height: "100%" }}
+        />
+      </div>,
+    );
+
+    const beforeTabs = screen.getAllByRole("tab");
+    expect(beforeTabs.length).toBe(3);
+
+    const explorer = screen.getByRole("tab", { name: /explorer/i });
+    fireEvent.click(explorer);
+
+    const afterTabs = screen.getAllByRole("tab");
+    expect(afterTabs.length).toBe(3);
+
+    const selected = afterTabs.filter((el) => el.getAttribute("aria-selected") === "true");
+    expect(selected.length).toBe(1);
+  });
+});

package/src/modules/panels/system/PanelSystem.tsx

@@ -0,0 +1,206 @@
+/**
+ * @file VSCode-like PanelSystem composed via module contexts and presentational components.
+ */
+import * as React from "react";
+import type { DropZone, GroupId, PanelSystemProps, PanelSystemState } from "../state/types";
+import { KeybindingsProvider } from "../../keybindings/KeybindingsProvider";
+import { buildGridForAbsolutePanels, buildGridFromRects } from "../layout/adapter";
+import { GridLayout } from "../../../components/grid/GridLayout";
+import { GroupContainer } from "../rendering/GroupContainer";
+import { InteractionsProvider, usePanelInteractions } from "../interactions/InteractionsContext";
+import { DropSuggestOverlay } from "../../../components/panels/DropSuggestOverlay";
+import { TabDragOverlay } from "../../../components/tabs/TabDragOverlay";
+import { PanelStateProvider, usePanelState } from "../state/StateContext";
+import { DefaultKeybindingsInstaller } from "../keybindings/KeybindingsInstaller";
+import { useCommitHandlers } from "../state/commands";
+import { RenderBridge } from "../rendering/RenderBridge";
+import { DomRegistryProvider } from "../dom/DomRegistry";
+import { PanelSplitHandles } from "../state/PanelSplitHandles";
+import { canSplitDirection, normalizeSplitLimits, type NormalizedSplitLimits } from "../state/splitLimits";
+
+const rootStyle: React.CSSProperties = {
+  position: "relative",
+  display: "flex",
+  width: "100%",
+  height: "100%",
+};
+
+type PanelSystemContentProps = {
+  containerRef: React.RefObject<HTMLDivElement | null>;
+  layoutMode: PanelSystemProps["layoutMode"];
+  gridTracksInteractive?: boolean;
+  dragThresholdPx: number;
+  view?: PanelSystemProps["view"];
+  style?: React.CSSProperties;
+  className?: string;
+  tabBarComponent?: PanelSystemProps["tabBarComponent"];
+  panelGroupComponent?: PanelSystemProps["panelGroupComponent"];
+  splitLimits: NormalizedSplitLimits;
+  emptyContentComponent?: PanelSystemProps["emptyContentComponent"];
+  doubleClickToAdd?: boolean;
+};
+
+const GridLayoutRenderer = ({
+  state,
+  layoutMode,
+  gridTracksInteractive,
+  view,
+  tabBarComponent,
+  panelGroupComponent,
+}: {
+  state: PanelSystemState;
+  layoutMode: PanelSystemProps["layoutMode"];
+  gridTracksInteractive: PanelSystemProps["gridTracksInteractive"];
+  view: PanelSystemProps["view"];
+  tabBarComponent: PanelSystemProps["tabBarComponent"];
+  panelGroupComponent: PanelSystemProps["panelGroupComponent"];
+}): React.ReactNode => {
+  const renderGroup = (gid: GroupId): React.ReactNode => {
+    if (view) {
+      const ViewComponent = view;
+      return <ViewComponent groupId={gid} />;
+    }
+    return <GroupContainer id={gid} TabBarComponent={tabBarComponent} PanelGroupComponent={panelGroupComponent} />;
+  };
+  if (layoutMode === "grid") {
+    const grid = buildGridFromRects(state, renderGroup, Boolean(gridTracksInteractive));
+    return <GridLayout config={grid.config} layers={grid.layers} />;
+  }
+  const grid = buildGridForAbsolutePanels(state, renderGroup);
+  return <GridLayout config={grid.config} layers={grid.layers} />;
+};
+
+const PanelSystemContent: React.FC<PanelSystemContentProps> = ({
+  containerRef,
+  layoutMode,
+  gridTracksInteractive,
+  dragThresholdPx,
+  view,
+  style,
+  className,
+  tabBarComponent,
+  panelGroupComponent,
+  splitLimits,
+  emptyContentComponent,
+  doubleClickToAdd,
+}) => {
+  const { state } = usePanelState();
+  const { onCommitContentDrop, onCommitTabDrop } = useCommitHandlers();
+
+  const containerStyle = React.useMemo(() => ({ ...rootStyle, ...style }), [style]);
+
+  const isZoneAllowed = React.useCallback(
+    ({ targetGroupId, zone }: { targetGroupId: GroupId; zone: DropZone }): boolean => {
+      if (zone === "center") {
+        return true;
+      }
+      const direction = zone === "left" || zone === "right" ? "vertical" : "horizontal";
+      return canSplitDirection(state.tree, targetGroupId, direction, splitLimits);
+    },
+    [state.tree, splitLimits],
+  );
+
+  return (
+    <DomRegistryProvider>
+      <InteractionsProvider
+        containerRef={containerRef}
+        dragThresholdPx={dragThresholdPx}
+        onCommitContentDrop={onCommitContentDrop}
+        onCommitTabDrop={onCommitTabDrop}
+        isContentZoneAllowed={isZoneAllowed}
+      >
+        <RenderBridge emptyContentComponent={emptyContentComponent} doubleClickToAdd={doubleClickToAdd}>
+          <div ref={containerRef} className={className} style={containerStyle}>
+            <GridLayoutRenderer
+              state={state}
+              layoutMode={layoutMode}
+              gridTracksInteractive={gridTracksInteractive}
+              view={view}
+              tabBarComponent={tabBarComponent}
+              panelGroupComponent={panelGroupComponent}
+            />
+          </div>
+        </RenderBridge>
+        <PanelSplitHandles containerRef={containerRef} />
+        <OverlayWithinProvider />
+      </InteractionsProvider>
+    </DomRegistryProvider>
+  );
+};
+
+const OverlayWithinProvider: React.FC = () => {
+  const interactions = usePanelInteractions();
+  return (
+    <>
+      <DropSuggestOverlay suggest={interactions.suggest} />
+      <TabDragOverlay />
+    </>
+  );
+};
+
+export const PanelSystem: React.FC<PanelSystemProps> = ({
+  initialState,
+  createGroupId,
+  createPanelId,
+  layoutMode,
+  gridTracksInteractive,
+  dragThresholdPx,
+  view,
+  emptyContentComponent,
+  state: controlled,
+  onStateChange,
+  className,
+  style,
+  tabBarComponent,
+  panelGroupComponent,
+  splitLimits,
+  doubleClickToAdd,
+}) => {
+  if (!initialState) {
+    throw new Error("PanelSystem requires initialState.");
+  }
+  if (!createGroupId) {
+    throw new Error("PanelSystem requires explicit createGroupId function.");
+  }
+  if (!layoutMode) {
+    throw new Error("PanelSystem requires explicit layoutMode ('absolute' | 'grid').");
+  }
+  if (layoutMode === "grid" && gridTracksInteractive === undefined) {
+    throw new Error("PanelSystem(layoutMode='grid') requires explicit 'gridTracksInteractive' flag.");
+  }
+  if (dragThresholdPx === undefined) {
+    throw new Error("PanelSystem requires explicit 'dragThresholdPx' value.");
+  }
+
+  const containerRef = React.useRef<HTMLDivElement | null>(null);
+  const normalizedSplitLimits = React.useMemo(() => normalizeSplitLimits(splitLimits), [splitLimits]);
+
+  return (
+    <PanelStateProvider
+      initialState={initialState}
+      createGroupId={createGroupId}
+      createPanelId={createPanelId}
+      state={controlled}
+      onStateChange={onStateChange}
+      splitLimits={splitLimits}
+    >
+      <KeybindingsProvider>
+        <DefaultKeybindingsInstaller />
+        <PanelSystemContent
+          containerRef={containerRef}
+          layoutMode={layoutMode}
+          gridTracksInteractive={gridTracksInteractive}
+          dragThresholdPx={dragThresholdPx}
+          view={view}
+          style={style}
+          className={className}
+          tabBarComponent={tabBarComponent}
+          panelGroupComponent={panelGroupComponent}
+          splitLimits={normalizedSplitLimits}
+          emptyContentComponent={emptyContentComponent}
+          doubleClickToAdd={doubleClickToAdd}
+        />
+      </KeybindingsProvider>
+    </PanelStateProvider>
+  );
+};