react-panel-layout 0.5.2 → 0.6.0

package/src/modules/keybindings/KeybindingsProvider.tsx

@@ -0,0 +1,111 @@
+/**
+ * @file Central keybindings provider for PanelSystem.
+ * Belongs to modules: distributes a single source of keybindings to UI.
+ */
+import * as React from "react";
+import type { PanelCommands } from "../panels/state/types";
+
+export type KeyCombo = string; // e.g., "Mod-Shift-\\", "Mod-1"
+
+export type KeybindingsMap = Record<KeyCombo, (e: KeyboardEvent) => void>;
+
+export type KeybindingsContextValue = {
+  register: (combo: KeyCombo, handler: (e: KeyboardEvent) => void) => void;
+  unregister: (combo: KeyCombo) => void;
+};
+
+const KeybindingsContext = React.createContext<KeybindingsContextValue | null>(null);
+
+export const useKeybindings = (): KeybindingsContextValue => {
+  const ctx = React.useContext(KeybindingsContext);
+  if (!ctx) {
+    throw new Error("useKeybindings must be used within KeybindingsProvider");
+  }
+  return ctx;
+};
+
+const normalizeEventToCombo = (e: KeyboardEvent): KeyCombo => {
+  const parts: string[] = [];
+  if (e.metaKey) {
+    parts.push("Mod");
+  }
+  if (e.ctrlKey) {
+    parts.push("Ctrl");
+  }
+  if (e.altKey) {
+    parts.push("Alt");
+  }
+  if (e.shiftKey) {
+    parts.push("Shift");
+  }
+  const key = e.key.length === 1 ? e.key.toUpperCase() : e.key;
+  parts.push(key);
+  return parts.join("-");
+};
+
+export const KeybindingsProvider: React.FC<React.PropsWithChildren<{ configure?: (api: KeybindingsContextValue) => void }>> = ({ children, configure }) => {
+  const handlersRef = React.useRef<KeybindingsMap>({});
+
+  const register = React.useCallback((combo: KeyCombo, handler: (e: KeyboardEvent) => void): void => {
+    handlersRef.current = { ...handlersRef.current, [combo]: handler };
+  }, []);
+
+  const unregister = React.useCallback((combo: KeyCombo): void => {
+    const rest = { ...handlersRef.current };
+    delete (rest as Record<string, unknown>)[combo];
+    handlersRef.current = rest;
+  }, []);
+
+  React.useEffect(() => {
+    const onKeyDown = (e: KeyboardEvent): void => {
+      const combo = normalizeEventToCombo(e);
+      const handler = handlersRef.current[combo];
+      if (!handler) {
+        return;
+      }
+      handler(e);
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => {
+      window.removeEventListener("keydown", onKeyDown);
+    };
+  }, []);
+
+  const api: KeybindingsContextValue = React.useMemo(() => ({ register, unregister }), [register, unregister]);
+
+  React.useEffect(() => {
+    if (!configure) {
+      return;
+    }
+    configure(api);
+  }, [api, configure]);
+
+  return <KeybindingsContext.Provider value={api}>{children}</KeybindingsContext.Provider>;
+};
+
+export const registerDefaultBindings = (api: KeybindingsContextValue, commands: PanelCommands): void => {
+  api.register("Mod-\\", (e) => {
+    e.preventDefault();
+    commands.splitFocused("vertical");
+  });
+  api.register("Mod-Shift-\\", (e) => {
+    e.preventDefault();
+    commands.splitFocused("horizontal");
+  });
+
+  for (const n of [1, 2, 3, 4, 5, 6, 7, 8, 9]) {
+    api.register(`Mod-${String(n)}`, (e) => {
+      e.preventDefault();
+      commands.focusGroupIndex(n);
+    });
+  }
+
+  api.register("Alt-ArrowRight", (e) => {
+    e.preventDefault();
+    commands.focusNextGroup();
+  });
+  api.register("Alt-ArrowLeft", (e) => {
+    e.preventDefault();
+    commands.focusPrevGroup();
+  });
+};

package/src/modules/panels/dom/DomRegistry.tsx

@@ -0,0 +1,94 @@
+/**
+ * @file DOM registry for panel-system. React-first: components register their own refs
+ * instead of global querySelectorAll scans.
+ */
+import * as React from "react";
+import type { GroupId } from "../state/types";
+
+export type RegisteredEls = {
+  group: HTMLElement | null;
+  tabbar: HTMLElement | null;
+  content: HTMLElement | null;
+};
+
+export type DomRegistryContextValue = {
+  setGroupEl: (groupId: GroupId, el: HTMLElement | null) => void;
+  setTabbarEl: (groupId: GroupId, el: HTMLElement | null) => void;
+  setContentEl: (groupId: GroupId, el: HTMLElement | null) => void;
+  getAll: () => Map<GroupId, RegisteredEls>;
+};
+
+const DomRegistryContext = React.createContext<DomRegistryContextValue | null>(null);
+
+export const useDomRegistry = (): DomRegistryContextValue => {
+  const ctx = React.useContext(DomRegistryContext);
+  if (!ctx) {
+    throw new Error("useDomRegistry must be used within DomRegistryProvider");
+  }
+  return ctx;
+};
+
+export const DomRegistryProvider: React.FC<React.PropsWithChildren<unknown>> = ({ children }) => {
+  const mapRef = React.useRef<Map<GroupId, RegisteredEls>>(new Map());
+
+  const ensure = React.useCallback((groupId: GroupId): RegisteredEls => {
+    const current = mapRef.current.get(groupId);
+    if (current) {
+      return current;
+    }
+    const next: RegisteredEls = { group: null, tabbar: null, content: null };
+    mapRef.current.set(groupId, next);
+    return next;
+  }, []);
+
+  const setGroupEl = React.useCallback(
+    (groupId: GroupId, el: HTMLElement | null) => {
+      const r = ensure(groupId);
+      r.group = el;
+      if (el === null) {
+        const v = mapRef.current.get(groupId);
+        const noOthers = v ? v.tabbar === null && v.content === null : false;
+        if (noOthers) {
+          mapRef.current.delete(groupId);
+        }
+      }
+    },
+    [ensure],
+  );
+
+  const setTabbarEl = React.useCallback(
+    (groupId: GroupId, el: HTMLElement | null) => {
+      const r = ensure(groupId);
+      r.tabbar = el;
+      if (el === null) {
+        const v = mapRef.current.get(groupId);
+        const noOthers = v ? v.group === null && v.content === null : false;
+        if (noOthers) {
+          mapRef.current.delete(groupId);
+        }
+      }
+    },
+    [ensure],
+  );
+
+  const setContentEl = React.useCallback(
+    (groupId: GroupId, el: HTMLElement | null) => {
+      const r = ensure(groupId);
+      r.content = el;
+      if (el === null) {
+        const v = mapRef.current.get(groupId);
+        const noOthers = v ? v.group === null && v.tabbar === null : false;
+        if (noOthers) {
+          mapRef.current.delete(groupId);
+        }
+      }
+    },
+    [ensure],
+  );
+
+  const getAll = React.useCallback(() => mapRef.current, []);
+
+  const value = React.useMemo<DomRegistryContextValue>(() => ({ setGroupEl, setTabbarEl, setContentEl, getAll }), [setGroupEl, setTabbarEl, setContentEl, getAll]);
+
+  return <DomRegistryContext.Provider value={value}>{children}</DomRegistryContext.Provider>;
+};

package/src/modules/panels/index.ts

@@ -0,0 +1,45 @@
+/**
+ * @file Public state operations aggregator (flattened under src/modules/panels).
+ */
+export type {
+  PanelId,
+  GroupId,
+  SplitDirection,
+  TabDefinition,
+  GroupModel,
+  PanelTree,
+  PanelSystemState,
+  DropZone,
+  DraggingTab,
+  PanelCommands,
+  PanelSystemProps,
+  PanelSplitLimits,
+} from "./state/types";
+
+export { collectGroupsInOrder, splitLeaf, closeLeaf, isGroup, setSplitRatio } from "./state/tree/logic";
+export { createEmptyGroup, addTabToGroup, removeTabFromGroup, moveTab, setActiveTab, reorderTabWithinGroup, addTabToGroupAtIndex } from "./state/groups/logic";
+export { setFocusedGroup, focusGroupIndex, nextGroup, prevGroup, refreshGroupOrder } from "./state/focus/logic";
+
+import type { GroupId as Gid, PanelSystemState as PState, SplitDirection as Dir, TabDefinition } from "./state/types";
+import { splitLeaf, collectGroupsInOrder } from "./state/tree/logic";
+import { createEmptyGroup } from "./state/groups/logic";
+
+export type IdFactory = () => Gid;
+
+export const splitGroup = (state: PState, groupId: Gid, direction: Dir, createGroupId: IdFactory): PState => {
+  const { tree, newGroupId } = splitLeaf(state.tree, groupId, direction, createGroupId);
+  const groups = { ...state.groups, [newGroupId]: createEmptyGroup(newGroupId) };
+  const groupOrder = collectGroupsInOrder(tree);
+  const focusedGroupId = newGroupId;
+  return { ...state, tree, groups, groupOrder, focusedGroupId };
+};
+
+export const buildInitialState = (tabs: TabDefinition[]): PState => {
+  const groupId: Gid = "g_1";
+  const tree = { type: "group", groupId } as const;
+  const panels = Object.fromEntries(tabs.map((t) => [t.id, t]));
+  const group = { id: groupId, tabIds: tabs.map((t) => t.id), tabs, activeTabId: tabs[0]?.id ?? null } as const;
+  const groups = { [groupId]: group } as PState["groups"];
+  const groupOrder: Gid[] = [groupId];
+  return { tree, panels, groups, groupOrder, focusedGroupId: groupId } as PState;
+};

package/src/modules/panels/interactions/InteractionsContext.test.tsx

@@ -0,0 +1,330 @@
+/**
+ * @file InteractionsContext integration tests
+ */
+/* eslint-disable no-restricted-imports, no-restricted-properties, no-restricted-syntax -- integration test requires vitest APIs for timer/pointer mocks */
+import { vi, describe, it, expect, beforeEach, afterEach } from "vitest";
+import { render, screen, fireEvent, act } from "@testing-library/react";
+import * as React from "react";
+import { InteractionsProvider, usePanelInteractions } from "./InteractionsContext";
+import { DomRegistryProvider, useDomRegistry } from "../dom/DomRegistry";
+
+// Mock components to test interactions
+const TestComponent = () => {
+    const { onStartContentDrag, dragPointer, suggest } = usePanelInteractions();
+    const { setGroupEl, setContentEl } = useDomRegistry();
+
+    const groupRef = React.useRef<HTMLDivElement>(null);
+    const contentRef = React.useRef<HTMLDivElement>(null);
+
+    React.useEffect(() => {
+        if (groupRef.current) {
+            setGroupEl("group-1", groupRef.current);
+        }
+        if (contentRef.current) {
+            setContentEl("group-1", contentRef.current);
+        }
+        return () => {
+            setGroupEl("group-1", null);
+            setContentEl("group-1", null);
+        };
+    }, [setGroupEl, setContentEl]);
+
+    return (
+        <div
+            data-testid="container"
+            style={{ width: 800, height: 600, position: "relative" }}
+        >
+            <div
+                ref={groupRef}
+                data-testid="group"
+                style={{
+                    position: "absolute",
+                    left: 100,
+                    top: 100,
+                    width: 200,
+                    height: 200,
+                    background: "red",
+                }}
+            >
+                <div
+                    ref={contentRef}
+                    data-testid="content"
+                    style={{ width: "100%", height: "100%" }}
+                    onPointerDown={(e) => onStartContentDrag("group-1", "tab-1", e)}
+                >
+                    Content
+                </div>
+            </div>
+            {dragPointer ? <div data-testid="drag-pointer">Dragging</div> : null}
+            {suggest ? <div data-testid="suggest">Suggest: {suggest.zone}</div> : null}
+        </div>
+    );
+};
+
+const noopContentDrop = (): void => {
+    // no-op fake
+};
+const noopTabDrop = (): void => {
+    // no-op fake
+};
+
+const Wrapper = () => {
+    const containerRef = React.useRef<HTMLDivElement>(null);
+
+    return (
+        <DomRegistryProvider>
+            <div ref={containerRef}>
+                <InteractionsProvider
+                    containerRef={containerRef}
+                    dragThresholdPx={5}
+                    onCommitContentDrop={noopContentDrop}
+                    onCommitTabDrop={noopTabDrop}
+                >
+                    <TestComponent />
+                </InteractionsProvider>
+            </div>
+        </DomRegistryProvider>
+    );
+};
+
+// Tab drag test component
+const TabDragTestComponent = () => {
+    const { onStartTabDrag, dragPointer, suggest, isTabDragging } = usePanelInteractions();
+    const { setGroupEl, setContentEl, setTabbarEl } = useDomRegistry();
+
+    const groupRef = React.useRef<HTMLDivElement>(null);
+    const contentRef = React.useRef<HTMLDivElement>(null);
+    const tabbarRef = React.useRef<HTMLDivElement>(null);
+
+    React.useEffect(() => {
+        if (groupRef.current) {
+            setGroupEl("group-1", groupRef.current);
+        }
+        if (contentRef.current) {
+            setContentEl("group-1", contentRef.current);
+        }
+        if (tabbarRef.current) {
+            setTabbarEl("group-1", tabbarRef.current);
+        }
+        return () => {
+            setGroupEl("group-1", null);
+            setContentEl("group-1", null);
+            setTabbarEl("group-1", null);
+        };
+    }, [setGroupEl, setContentEl, setTabbarEl]);
+
+    return (
+        <div
+            data-testid="container"
+            style={{ width: 800, height: 600, position: "relative" }}
+        >
+            <div
+                ref={groupRef}
+                data-testid="group"
+                style={{
+                    position: "absolute",
+                    left: 100,
+                    top: 100,
+                    width: 200,
+                    height: 200,
+                    background: "red",
+                }}
+            >
+                <div
+                    ref={tabbarRef}
+                    data-testid="tabbar"
+                    role="tablist"
+                    style={{ width: "100%", height: 30 }}
+                >
+                    <button
+                        role="tab"
+                        data-testid="tab"
+                        style={{ width: 80, height: 30 }}
+                        onPointerDown={(e) => onStartTabDrag("tab-1", "group-1", e)}
+                    >
+                        Tab 1
+                    </button>
+                </div>
+                <div
+                    ref={contentRef}
+                    data-testid="content"
+                    style={{ width: "100%", height: 170 }}
+                >
+                    Content
+                </div>
+            </div>
+            {isTabDragging ? <div data-testid="is-tab-dragging">isTabDragging</div> : null}
+            {dragPointer ? <div data-testid="drag-pointer">Dragging</div> : null}
+            {suggest ? <div data-testid="suggest">Suggest: {suggest.zone}</div> : null}
+        </div>
+    );
+};
+
+const TabDragWrapper = () => {
+    const containerRef = React.useRef<HTMLDivElement>(null);
+
+    return (
+        <DomRegistryProvider>
+            <div ref={containerRef}>
+                <InteractionsProvider
+                    containerRef={containerRef}
+                    dragThresholdPx={5}
+                    onCommitContentDrop={noopContentDrop}
+                    onCommitTabDrop={noopTabDrop}
+                >
+                    <TabDragTestComponent />
+                </InteractionsProvider>
+            </div>
+        </DomRegistryProvider>
+    );
+};
+
+describe("InteractionsContext", () => {
+    beforeEach(() => {
+        vi.useFakeTimers();
+        // Mock pointer capture methods which are not available in JSDOM
+        Element.prototype.setPointerCapture = vi.fn();
+        Element.prototype.releasePointerCapture = vi.fn();
+    });
+
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+
+    it("should NOT show suggest when tab drag has not exceeded threshold", () => {
+        render(<TabDragWrapper />);
+
+        const tab = screen.getByTestId("tab");
+
+        // Mock getBoundingClientRect
+        vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockReturnValue({
+            left: 100,
+            top: 100,
+            width: 200,
+            height: 200,
+            right: 300,
+            bottom: 300,
+            x: 100,
+            y: 100,
+            toJSON: () => { },
+        });
+
+        // Start tab drag (pointerDown)
+        fireEvent.pointerDown(tab, { clientX: 150, clientY: 115, button: 0, pointerId: 1 });
+
+        // Move within threshold (less than 5px)
+        act(() => {
+            const moveEvent = new Event("pointermove");
+            Object.assign(moveEvent, { clientX: 152, clientY: 117 });
+            window.dispatchEvent(moveEvent);
+        });
+
+        // suggest should NOT be visible because we haven't exceeded threshold
+        expect(screen.queryByTestId("suggest")).not.toBeInTheDocument();
+        // dragPointer should NOT be visible
+        expect(screen.queryByTestId("drag-pointer")).not.toBeInTheDocument();
+    });
+
+    it("should show suggest when tab drag exceeds threshold", () => {
+        render(<TabDragWrapper />);
+
+        const tab = screen.getByTestId("tab");
+
+        // Mock getBoundingClientRect
+        vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockReturnValue({
+            left: 100,
+            top: 100,
+            width: 200,
+            height: 200,
+            right: 300,
+            bottom: 300,
+            x: 100,
+            y: 100,
+            toJSON: () => { },
+        });
+
+        // Start tab drag (pointerDown)
+        fireEvent.pointerDown(tab, { clientX: 150, clientY: 115, button: 0, pointerId: 1 });
+
+        // Move past threshold (more than 5px)
+        act(() => {
+            const moveEvent = new Event("pointermove");
+            Object.assign(moveEvent, { clientX: 160, clientY: 160 });
+            window.dispatchEvent(moveEvent);
+        });
+
+        // suggest should be visible because we exceeded threshold
+        expect(screen.getByTestId("suggest")).toBeInTheDocument();
+        expect(screen.getByTestId("drag-pointer")).toBeInTheDocument();
+    });
+
+    it("should start drag and update pointer", () => {
+        render(<Wrapper />);
+
+        const content = screen.getByTestId("content");
+
+        // Mock getBoundingClientRect
+        vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockReturnValue({
+            left: 100,
+            top: 100,
+            width: 200,
+            height: 200,
+            right: 300,
+            bottom: 300,
+            x: 100,
+            y: 100,
+            toJSON: () => { },
+        });
+
+        // Start drag
+        fireEvent.pointerDown(content, { clientX: 150, clientY: 150, button: 0, pointerId: 1 });
+
+        // Move past threshold
+        act(() => {
+            const moveEvent = new Event("pointermove");
+            Object.assign(moveEvent, { clientX: 160, clientY: 160 });
+            window.dispatchEvent(moveEvent);
+        });
+
+        expect(screen.getByTestId("drag-pointer")).toBeInTheDocument();
+    });
+
+    it("should reset on pointer cancel", () => {
+        render(<Wrapper />);
+
+        const content = screen.getByTestId("content");
+
+        // Mock getBoundingClientRect
+        vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockReturnValue({
+            left: 100,
+            top: 100,
+            width: 200,
+            height: 200,
+            right: 300,
+            bottom: 300,
+            x: 100,
+            y: 100,
+            toJSON: () => { },
+        });
+
+        // Start drag
+        fireEvent.pointerDown(content, { clientX: 150, clientY: 150, button: 0, pointerId: 1 });
+
+        // Move past threshold
+        act(() => {
+            const moveEvent = new Event("pointermove");
+            Object.assign(moveEvent, { clientX: 160, clientY: 160 });
+            window.dispatchEvent(moveEvent);
+        });
+
+        expect(screen.getByTestId("drag-pointer")).toBeInTheDocument();
+
+        // Cancel drag
+        act(() => {
+            const cancelEvent = new Event("pointercancel");
+            window.dispatchEvent(cancelEvent);
+        });
+
+        expect(screen.queryByTestId("drag-pointer")).not.toBeInTheDocument();
+    });
+});