react-panel-layout 0.2.0

package/dist/modules/panels/dom/DomRegistry.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @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>;
+};
+export declare const useDomRegistry: () => DomRegistryContextValue;
+export declare const DomRegistryProvider: React.FC<React.PropsWithChildren<unknown>>;

package/dist/modules/panels/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @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";
+export type IdFactory = () => Gid;
+export declare const splitGroup: (state: PState, groupId: Gid, direction: Dir, createGroupId: IdFactory) => PState;
+export declare const buildInitialState: (tabs: TabDefinition[]) => PState;

package/dist/modules/panels/interactions/InteractionsContext.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @file Centralized panel interactions (DnD) using Context + reducer.
+ * Handles content (panel area) split/move and tabbar reordering/cross-move.
+ */
+import * as React from "react";
+import type { DropZone, GroupId, PanelId } from "../state/types";
+export type SuggestInfo = {
+    rect: DOMRectReadOnly;
+    zone: DropZone;
+} | null;
+export type InteractionsContextValue = {
+    suggest: SuggestInfo;
+    onStartContentDrag: (groupId: GroupId, tabId: PanelId, e: React.PointerEvent<HTMLDivElement>) => void;
+    onStartTabDrag: (tabId: PanelId, groupId: GroupId, e: React.PointerEvent) => void;
+    isTabDragging: boolean;
+    draggingTabId: PanelId | null;
+    dragPointer: {
+        x: number;
+        y: number;
+    } | null;
+    tabbarHover: {
+        groupId: GroupId;
+        index: number;
+        rect: DOMRectReadOnly;
+        insertX: number;
+    } | null;
+    draggingTabElement: HTMLElement | null;
+};
+export declare const usePanelInteractions: () => InteractionsContextValue;
+export type InteractionsProviderProps = React.PropsWithChildren<{
+    containerRef: React.RefObject<HTMLDivElement | null>;
+    dragThresholdPx: number;
+    onCommitContentDrop: (payload: {
+        fromGroupId: GroupId;
+        tabId: PanelId;
+        targetGroupId: GroupId;
+        zone: DropZone;
+    }) => void;
+    onCommitTabDrop: (payload: {
+        fromGroupId: GroupId;
+        tabId: PanelId;
+        targetGroupId: GroupId;
+        targetIndex: number;
+    }) => void;
+    isContentZoneAllowed?: (payload: {
+        targetGroupId: GroupId;
+        zone: DropZone;
+    }) => boolean;
+}>;
+export declare const InteractionsProvider: React.FC<InteractionsProviderProps>;

package/dist/modules/panels/interactions/InteractionsContext.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/modules/panels/interactions/dnd.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @file DnD utilities for panel interactions
+ */
+import type { DropZone } from "../state/types";
+export declare const pickDropZone: (rect: DOMRectReadOnly, x: number, y: number) => DropZone;

package/dist/modules/panels/keybindings/KeybindingsInstaller.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @file Registers default keybindings using the single-source commands.
+ */
+import * as React from "react";
+export declare const DefaultKeybindingsInstaller: React.FC;

package/dist/modules/panels/layout/adapter.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @file Adapters bridging panel-system model to existing GridLayout definitions.
+ * Strategy: Use a 1x1 relative grid and place groups as absolute layers using computed rects.
+ */
+import type { LayerDefinition, PanelLayoutConfig } from "../../../types";
+import type { GroupId, PanelSystemState, PanelTree } from "../state/types";
+export type Rect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+export declare const computeRects: (node: PanelTree, bounds?: Rect) => Map<GroupId, Rect>;
+export declare const buildGridForAbsolutePanels: (state: PanelSystemState, renderGroup: (groupId: GroupId) => React.ReactNode) => {
+    config: PanelLayoutConfig;
+    layers: LayerDefinition[];
+};
+export declare const buildGridFromRects: (state: PanelSystemState, renderGroup: (groupId: GroupId) => React.ReactNode, interactiveTracks: boolean) => {
+    config: PanelLayoutConfig;
+    layers: LayerDefinition[];
+};

package/dist/modules/panels/rendering/GroupContainer.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @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";
+export type ConnectedGroupContainerProps = {
+    id: GroupId;
+    TabBarComponent?: React.ComponentType<TabBarRenderProps>;
+    PanelGroupComponent?: React.ComponentType<PanelGroupRenderProps>;
+};
+export declare const GroupContainer: React.FC<ConnectedGroupContainerProps>;

package/dist/modules/panels/rendering/RenderBridge.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @file Bridge component that binds InteractionsContext to PanelRenderContext using panel state.
+ */
+import * as React from "react";
+export declare const RenderBridge: React.FC<React.PropsWithChildren<{
+    emptyContentComponent?: React.ComponentType;
+    doubleClickToAdd?: boolean;
+}>>;

package/dist/modules/panels/rendering/RenderContext.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @file Panel render context providing per-group accessors and actions.
+ */
+import * as React from "react";
+import type { GroupId, GroupModel, PanelId } from "../state/types";
+export type PanelRenderContextValue = {
+    getGroup: (id: GroupId) => GroupModel | null;
+    getGroupContent: (id: GroupId) => React.ReactNode;
+    onClickTab: (groupId: GroupId, tabId: PanelId) => void;
+    onAddTab?: (groupId: GroupId) => void;
+    onCloseTab?: (groupId: GroupId, tabId: PanelId) => void;
+    onStartTabDrag: (tabId: PanelId, groupId: GroupId, e: React.PointerEvent) => void;
+    onStartContentDrag: (groupId: GroupId, e: React.PointerEvent<HTMLDivElement>) => void;
+    doubleClickToAdd?: boolean;
+};
+export declare const usePanelRenderContext: () => PanelRenderContextValue;
+export declare const PanelRenderProvider: React.FC<React.PropsWithChildren<{
+    value: PanelRenderContextValue;
+}>>;

package/dist/modules/panels/state/PanelSplitHandles.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @file Connected split handles overlay.
+ */
+import * as React from "react";
+export type PanelSplitHandlesProps = {
+    containerRef: React.RefObject<HTMLDivElement | null>;
+};
+export declare const PanelSplitHandles: React.FC<PanelSplitHandlesProps>;

package/dist/modules/panels/state/PanelSystemContext.d.ts

@@ -0,0 +1,148 @@
+/**
+ * @file Root PanelSystemContext that combines subdomain contexts (groups, tree, focus).
+ * Provides unified state and dispatch while exposing domain-specific actions via subcontexts.
+ */
+import * as React from "react";
+import type { DropZone, GroupId, PanelId, PanelSplitLimits, PanelSystemState, SplitDirection, TabDefinition } from "./types";
+import { type NodePath } from "./tree/logic";
+import { type BoundActionCreators } from "../../../utils/typedActions";
+declare const actions: {
+    readonly splitFocused: ((direction: SplitDirection) => {
+        type: "panelState/splitFocused";
+        payload: {
+            direction: SplitDirection;
+        };
+    }) & {
+        readonly type: "panelState/splitFocused";
+    };
+    readonly focusGroupIndex: ((index1Based: number) => {
+        type: "panelState/focusGroupIndex";
+        payload: {
+            index1Based: number;
+        };
+    }) & {
+        readonly type: "panelState/focusGroupIndex";
+    };
+    readonly focusNextGroup: (() => {
+        type: "panelState/focusNextGroup";
+    }) & {
+        readonly type: "panelState/focusNextGroup";
+    };
+    readonly focusPrevGroup: (() => {
+        type: "panelState/focusPrevGroup";
+    }) & {
+        readonly type: "panelState/focusPrevGroup";
+    };
+    readonly setActiveTab: ((groupId: string, tabId: string) => {
+        type: "panelState/setActiveTab";
+        payload: {
+            groupId: string;
+            tabId: string;
+        };
+    }) & {
+        readonly type: "panelState/setActiveTab";
+    };
+    readonly addTab: ((payload: {
+        groupId: GroupId;
+        tab: TabDefinition;
+        index?: number;
+        makeActive?: boolean;
+    }) => {
+        type: "panelState/addTab";
+        payload: {
+            groupId: GroupId;
+            tab: TabDefinition;
+            index?: number;
+            makeActive?: boolean;
+        };
+    }) & {
+        readonly type: "panelState/addTab";
+    };
+    readonly addNewTab: ((payload: {
+        groupId: GroupId;
+        title: string;
+        index?: number;
+        makeActive?: boolean;
+    }) => {
+        type: "panelState/addNewTab";
+        payload: {
+            groupId: GroupId;
+            title: string;
+            index?: number;
+            makeActive?: boolean;
+        };
+    }) & {
+        readonly type: "panelState/addNewTab";
+    };
+    readonly removeTab: ((groupId: string, tabId: string) => {
+        type: "panelState/removeTab";
+        payload: {
+            groupId: string;
+            tabId: string;
+        };
+    }) & {
+        readonly type: "panelState/removeTab";
+    };
+    readonly contentDrop: ((payload: {
+        fromGroupId: GroupId;
+        tabId: PanelId;
+        targetGroupId: GroupId;
+        zone: DropZone;
+    }) => {
+        type: "panelState/contentDrop";
+        payload: {
+            fromGroupId: GroupId;
+            tabId: PanelId;
+            targetGroupId: GroupId;
+            zone: DropZone;
+        };
+    }) & {
+        readonly type: "panelState/contentDrop";
+    };
+    readonly tabDrop: ((payload: {
+        fromGroupId: GroupId;
+        tabId: PanelId;
+        targetGroupId: GroupId;
+        targetIndex: number;
+    }) => {
+        type: "panelState/tabDrop";
+        payload: {
+            fromGroupId: GroupId;
+            tabId: PanelId;
+            targetGroupId: GroupId;
+            targetIndex: number;
+        };
+    }) & {
+        readonly type: "panelState/tabDrop";
+    };
+    readonly adjustSplitRatio: ((payload: {
+        path: NodePath;
+        deltaRatio: number;
+    }) => {
+        type: "panelState/adjustSplitRatio";
+        payload: {
+            path: NodePath;
+            deltaRatio: number;
+        };
+    }) & {
+        readonly type: "panelState/adjustSplitRatio";
+    };
+};
+type PanelStateAction = ReturnType<(typeof actions)[keyof typeof actions]>;
+type PanelStateActions = BoundActionCreators<typeof actions>;
+export type PanelSystemContextValue = {
+    state: PanelSystemState;
+    dispatch: (action: PanelStateAction) => void;
+    actions: PanelStateActions;
+};
+export declare const usePanelSystem: () => PanelSystemContextValue;
+export type PanelSystemProviderProps = React.PropsWithChildren<{
+    initialState: PanelSystemState;
+    createGroupId: () => GroupId;
+    createPanelId?: () => PanelId;
+    state?: PanelSystemState;
+    onStateChange?: (next: PanelSystemState) => void;
+    splitLimits?: PanelSplitLimits;
+}>;
+export declare const PanelSystemProvider: React.FC<PanelSystemProviderProps>;
+export type { PanelStateAction, PanelStateActions };

package/dist/modules/panels/state/StateContext.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @file State context for VSCode-like panel system (backward compatibility layer).
+ * This file re-exports PanelSystemContext for compatibility with existing code.
+ */
+export { PanelSystemProvider as PanelStateProvider, usePanelSystem as usePanelState, type PanelSystemProviderProps as PanelStateProviderProps, type PanelSystemContextValue as PanelStateContextValue, type PanelStateAction, type PanelStateActions, } from "./PanelSystemContext";

package/dist/modules/panels/state/cleanup.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @file Cleanup utilities for PanelSystem state.
+ * - Removes groups with no tabs and collapses the tree accordingly.
+ */
+import type { PanelSystemState } from "./types";
+/**
+ * Remove empty groups (tabs.length === 0) by collapsing corresponding leaves.
+ * Keeps at least one group in the system.
+ * Returns the same reference if no changes are necessary to help callers short-circuit updates.
+ */
+export declare const cleanupEmptyGroups: (state: PanelSystemState) => PanelSystemState;

package/dist/modules/panels/state/commands.d.ts

@@ -0,0 +1,16 @@
+import type { DropZone, PanelCommands } from "../state/types";
+export declare const usePanelCommands: () => PanelCommands;
+export declare const useCommitHandlers: () => {
+    onCommitContentDrop: (payload: {
+        fromGroupId: string;
+        tabId: string;
+        targetGroupId: string;
+        zone: DropZone;
+    }) => void;
+    onCommitTabDrop: (payload: {
+        fromGroupId: string;
+        tabId: string;
+        targetGroupId: string;
+        targetIndex: number;
+    }) => void;
+};

package/dist/modules/panels/state/focus/Context.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @file FocusContext provides focus/navigation actions for PanelSystem.
+ * This context delegates to the root PanelSystemContext dispatch.
+ */
+import * as React from "react";
+export type FocusActions = {
+    focusGroupIndex: (index1Based: number) => void;
+    focusNextGroup: () => void;
+    focusPrevGroup: () => void;
+};
+export declare const useFocus: () => FocusActions;
+export declare const FocusProvider: React.FC<React.PropsWithChildren<{
+    value: FocusActions;
+}>>;

package/dist/modules/panels/state/focus/logic.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @file Focus and navigation helpers for panel-system.
+ */
+import type { GroupId, PanelSystemState } from "../types";
+export declare const setFocusedGroup: (state: PanelSystemState, groupId: GroupId) => PanelSystemState;
+export declare const focusGroupIndex: (state: PanelSystemState, index1Based: number) => PanelSystemState;
+export declare const nextGroup: (state: PanelSystemState) => PanelSystemState;
+export declare const prevGroup: (state: PanelSystemState) => PanelSystemState;
+export declare const refreshGroupOrder: (state: PanelSystemState) => PanelSystemState;

package/dist/modules/panels/state/groups/Context.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @file GroupsContext provides group/tab management actions for PanelSystem.
+ * This context delegates to the root PanelSystemContext dispatch.
+ */
+import * as React from "react";
+import type { GroupId, PanelId } from "../types";
+export type GroupsActions = {
+    setActiveTab: (groupId: GroupId, tabId: PanelId) => void;
+    tabDrop: (payload: {
+        fromGroupId: GroupId;
+        tabId: PanelId;
+        targetGroupId: GroupId;
+        targetIndex: number;
+    }) => void;
+};
+export declare const useGroups: () => GroupsActions;
+export declare const GroupsProvider: React.FC<React.PropsWithChildren<{
+    value: GroupsActions;
+}>>;

package/dist/modules/panels/state/groups/logic.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @file Group and tab registry operations (pure, no tree logic).
+ */
+import type { GroupId, GroupModel, PanelId, PanelSystemState, TabDefinition } from "../types";
+export declare const createEmptyGroup: (id: GroupId) => GroupModel;
+export declare const addTabToGroup: (state: PanelSystemState, groupId: GroupId, tab: TabDefinition, makeActive: boolean) => PanelSystemState;
+export declare const removeTabFromGroup: (state: PanelSystemState, groupId: GroupId, tabId: PanelId) => PanelSystemState;
+export declare const moveTab: (state: PanelSystemState, fromGroupId: GroupId, toGroupId: GroupId, tabId: PanelId, makeActive: boolean) => PanelSystemState;
+export declare const setActiveTab: (state: PanelSystemState, groupId: GroupId, tabId: PanelId) => PanelSystemState;
+export declare const reorderTabWithinGroup: (state: PanelSystemState, groupId: GroupId, tabId: PanelId, toIndex: number) => PanelSystemState;
+export declare const addTabToGroupAtIndex: (state: PanelSystemState, groupId: GroupId, tab: TabDefinition, index: number, makeActive: boolean) => PanelSystemState;

package/dist/modules/panels/state/splitLimits.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @file Split-limit helpers for the panel system.
+ */
+import type { GroupId, PanelSplitLimits, PanelTree, SplitDirection } from "./types";
+export type NormalizedSplitLimits = {
+    rows: number;
+    cols: number;
+};
+export declare const normalizeSplitLimits: (limits?: PanelSplitLimits) => NormalizedSplitLimits;
+export type SplitExtents = {
+    horizontal: number;
+    vertical: number;
+};
+export declare const measureSplitExtents: (tree: PanelTree) => SplitExtents;
+export declare const canSplitDirection: (tree: PanelTree, groupId: GroupId, direction: SplitDirection, limits: NormalizedSplitLimits) => boolean;

package/dist/modules/panels/state/tree/Context.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @file TreeContext provides tree/split management actions for PanelSystem.
+ * This context delegates to the root PanelSystemContext dispatch.
+ */
+import * as React from "react";
+import type { NodePath } from "./logic";
+export type TreeActions = {
+    adjustSplitRatio: (payload: {
+        path: NodePath;
+        deltaRatio: number;
+    }) => void;
+};
+export declare const useTree: () => TreeActions;
+export declare const TreeProvider: React.FC<React.PropsWithChildren<{
+    value: TreeActions;
+}>>;

package/dist/modules/panels/state/tree/logic.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @file Tree operations for panel-system (no registry or focus concerns).
+ */
+import type { GroupId, PanelTree, SplitDirection } from "../types";
+export type PathSegment = "a" | "b";
+export type NodePath = PathSegment[];
+export declare const isGroup: (node: PanelTree) => node is Extract<PanelTree, {
+    type: "group";
+}>;
+export declare const collectGroupsInOrder: (node: PanelTree, acc?: GroupId[]) => GroupId[];
+export declare const getAtPath: (root: PanelTree, path: NodePath) => PanelTree;
+export declare const setAtPath: (root: PanelTree, path: NodePath, value: PanelTree) => PanelTree;
+/**
+ * Find split parent of a given group leaf. This function explicitly returns the path to the split node
+ * and which side ("a" | "b") the target group occupies under that split. If there is no split parent
+ * (i.e., the root is the leaf group), splitPath and side are null.
+ */
+export declare const findLeafParent: (node: PanelTree, groupId: GroupId, path?: NodePath) => {
+    splitPath: NodePath | null;
+    side: PathSegment | null;
+} | null;
+/**
+ * Split the leaf group referenced by groupId into a split node, keeping the original group on side 'a'
+ * and inserting a new group on side 'b'. Returns the new tree and the new group's id.
+ * This function does not touch registries; only pure tree transformation.
+ */
+export declare const splitLeaf: (root: PanelTree, groupId: GroupId, direction: SplitDirection, createGroupId: () => GroupId) => {
+    tree: PanelTree;
+    newGroupId: GroupId;
+};
+/**
+ * Remove the leaf group by collapsing it with its sibling. Returns the new tree and the survivor group id
+ * (if any). If there is no split parent (single group), returns the original tree.
+ */
+export declare const closeLeaf: (root: PanelTree, groupId: GroupId) => {
+    tree: PanelTree;
+    survivorGroupId: GroupId | null;
+};
+/**
+ * Set split ratio at a specific split node path. Clamps ratio into (0.05 .. 0.95) to avoid zero-size panes.
+ */
+export declare const setSplitRatio: (root: PanelTree, splitPath: NodePath, ratio: number) => PanelTree;

package/dist/modules/panels/state/types.d.ts

@@ -0,0 +1,135 @@
+/**
+ * @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 to avoid remount on move */
+    render: () => 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;
+};
+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;
+};
+export {};

package/dist/modules/panels/system/PanelSystem.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @file VSCode-like PanelSystem composed via module contexts and presentational components.
+ */
+import * as React from "react";
+import type { PanelSystemProps } from "../state/types";
+export declare const PanelSystem: React.FC<PanelSystemProps>;