react-panel-layout 0.5.2 → 0.6.0

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

@@ -0,0 +1,31 @@
+/**
+ * @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;
+  registerContentContainer: (groupId: GroupId, element: HTMLElement | null) => void;
+};
+
+const PanelRenderContext = React.createContext<PanelRenderContextValue | null>(null);
+
+export const usePanelRenderContext = (): PanelRenderContextValue => {
+  const ctx = React.useContext(PanelRenderContext);
+  if (!ctx) {
+    throw new Error("usePanelRenderContext must be used within PanelRenderProvider");
+  }
+  return ctx;
+};
+
+export const PanelRenderProvider: React.FC<React.PropsWithChildren<{ value: PanelRenderContextValue }>> = ({ value, children }) => {
+  return <PanelRenderContext.Provider value={value}>{children}</PanelRenderContext.Provider>;
+};

package/src/modules/panels/state/PanelSplitHandles.tsx

@@ -0,0 +1,147 @@
+/**
+ * @file Connected split handles overlay.
+ */
+import * as React from "react";
+import type { PanelTree } from "../../panels/state/types";
+import type { NodePath, PathSegment } from "../../panels/state/tree/logic";
+import { isGroup } from "../../panels/state/tree/logic";
+import { usePanelState } from "../../panels/state/StateContext";
+import { useTree } from "../../panels/state/tree/Context";
+import { ResizeHandle } from "../../../components/resizer/ResizeHandle";
+import { SPLIT_HANDLE_THICKNESS } from "../../../constants/styles";
+import { useIsomorphicLayoutEffect } from "../../../hooks/useIsomorphicLayoutEffect";
+
+type Rect = { x: number; y: number; w: number; h: number };
+
+type Handle = {
+  path: NodePath;
+  direction: "vertical" | "horizontal";
+  parentRect: Rect;
+  linePos: number;
+};
+
+const collectHandles = (node: PanelTree, path: NodePath, rect: Rect, acc: Handle[]): Handle[] => {
+  if (isGroup(node)) {
+    return acc;
+  }
+  const direction = node.direction;
+  const linePos = direction === "vertical" ? rect.x + rect.w * node.ratio : rect.y + rect.h * node.ratio;
+  acc.push({ path, direction, parentRect: rect, linePos });
+  if (direction === "vertical") {
+    const wA = rect.w * node.ratio;
+    const wB = rect.w - wA;
+    collectHandles(node.a, [...path, "a" as PathSegment], { x: rect.x, y: rect.y, w: wA, h: rect.h }, acc);
+    collectHandles(node.b, [...path, "b" as PathSegment], { x: rect.x + wA, y: rect.y, w: wB, h: rect.h }, acc);
+    return acc;
+  }
+  const hA = rect.h * node.ratio;
+  const hB = rect.h - hA;
+  collectHandles(node.a, [...path, "a" as PathSegment], { x: rect.x, y: rect.y, w: rect.w, h: hA }, acc);
+  collectHandles(node.b, [...path, "b" as PathSegment], { x: rect.x, y: rect.y + hA, w: rect.w, h: hB }, acc);
+  return acc;
+};
+
+export type PanelSplitHandlesProps = { containerRef: React.RefObject<HTMLDivElement | null> };
+
+export const PanelSplitHandles: React.FC<PanelSplitHandlesProps> = ({ containerRef }) => {
+  const { state } = usePanelState();
+  const { adjustSplitRatio } = useTree();
+
+  const handles = React.useMemo(() => collectHandles(state.tree, [], { x: 0, y: 0, w: 100, h: 100 }, []), [state.tree]);
+
+  // Measure container rect after layout to avoid reading stale geometry during render
+  const [containerRect, setContainerRect] = React.useState<Pick<DOMRect, "left" | "top" | "width" | "height"> | null>(null);
+  useIsomorphicLayoutEffect(() => {
+    const el = containerRef.current;
+    if (!el) {
+      return;
+    }
+    const measure = (): void => {
+      const r = el.getBoundingClientRect();
+      setContainerRect({ left: r.left, top: r.top, width: r.width, height: r.height });
+    };
+    measure();
+    function getResizeObserverCtor(): typeof ResizeObserver | null {
+      try {
+        const ctor = (window as { ResizeObserver?: typeof ResizeObserver }).ResizeObserver;
+        return typeof ctor === "function" ? ctor : null;
+      } catch {
+        return null;
+      }
+    }
+    const RO = getResizeObserverCtor();
+    const ro: ResizeObserver | null = RO ? new RO(() => measure()) : null;
+    if (ro) {
+      ro.observe(el);
+    }
+    const onScroll = (): void => measure();
+    window.addEventListener("scroll", onScroll, true);
+    return () => {
+      window.removeEventListener("scroll", onScroll, true);
+      if (ro) {
+        ro.disconnect();
+      }
+    };
+  }, [containerRef, state.tree]);
+  if (!containerRect) {
+    return null;
+  }
+
+  const renderHandle = (handle: Handle, index: number): React.ReactNode => {
+    // Compute viewport-fixed coordinates by adding container offsets
+    const parentPx = {
+      left: containerRect.left + (containerRect.width * handle.parentRect.x) / 100,
+      top: containerRect.top + (containerRect.height * handle.parentRect.y) / 100,
+      width: (containerRect.width * handle.parentRect.w) / 100,
+      height: (containerRect.height * handle.parentRect.h) / 100,
+    };
+
+    const thickness = SPLIT_HANDLE_THICKNESS;
+
+    if (handle.direction === "vertical") {
+      const x = parentPx.left + (parentPx.width * (handle.linePos - handle.parentRect.x)) / handle.parentRect.w;
+      const style: React.CSSProperties = {
+        position: "fixed",
+        left: `calc(${Math.round(x)}px - ${thickness} / 2)`,
+        top: Math.round(parentPx.top),
+        width: thickness,
+        height: Math.round(parentPx.height),
+        cursor: "col-resize",
+        pointerEvents: "auto",
+      };
+      const onResize = (delta: number): void => {
+        const parentWidth = (containerRect.width * handle.parentRect.w) / 100;
+        const dRatio = parentWidth === 0 ? 0 : delta / parentWidth;
+        adjustSplitRatio({ path: handle.path, deltaRatio: dRatio });
+      };
+      return (
+        <div key={`split-${index}`} style={style}>
+          <ResizeHandle direction="vertical" onResize={onResize} />
+        </div>
+      );
+    }
+
+    const y = parentPx.top + (parentPx.height * (handle.linePos - handle.parentRect.y)) / handle.parentRect.h;
+    const style: React.CSSProperties = {
+      position: "fixed",
+      left: Math.round(parentPx.left),
+      top: `calc(${Math.round(y)}px - ${thickness} / 2)`,
+      width: Math.round(parentPx.width),
+      height: thickness,
+      cursor: "row-resize",
+      pointerEvents: "auto",
+    };
+    const onResize = (delta: number): void => {
+      const parentHeight = (containerRect.height * handle.parentRect.h) / 100;
+      const dRatio = parentHeight === 0 ? 0 : delta / parentHeight;
+      adjustSplitRatio({ path: handle.path, deltaRatio: dRatio });
+    };
+    return (
+      <div key={`split-${index}`} style={style}>
+        <ResizeHandle direction="horizontal" onResize={onResize} />
+      </div>
+    );
+  };
+
+  return <div style={{ position: "fixed", inset: 0, pointerEvents: "none" }}>{handles.map((h, idx) => renderHandle(h, idx))}</div>;
+};

package/src/modules/panels/state/PanelSystemContext.splitLimits.spec.tsx

@@ -0,0 +1,50 @@
+/**
+ * @file Integration-like tests for PanelSystemProvider split limits.
+ */
+import * as React from "react";
+import { act, renderHook } from "@testing-library/react";
+import { PanelStateProvider, usePanelState } from "./StateContext";
+import { buildInitialState } from "..";
+import type { TabDefinition } from "./types";
+
+const makeTab = (id: string): TabDefinition => ({ id, title: id, render: () => id });
+
+const createIdFactory = (): (() => string) => {
+  const counter = { value: 1 };
+  return () => {
+    counter.value += 1;
+    return `g_${counter.value}`;
+  };
+};
+
+describe("PanelSystemProvider split limits", () => {
+  it("blocks splitFocused when vertical limit is reached", () => {
+    const initial = buildInitialState([makeTab("a")]);
+    const wrapper: React.FC<{ children: React.ReactNode }> = ({ children }) => (
+      <PanelStateProvider initialState={initial} createGroupId={createIdFactory()} splitLimits={{ cols: 1 }}>
+        {children}
+      </PanelStateProvider>
+    );
+    const { result } = renderHook(() => usePanelState(), { wrapper });
+    act(() => {
+      result.current.actions.splitFocused("vertical");
+    });
+    expect(result.current.state.groupOrder.length).toBe(1);
+  });
+
+  it("ignores content drops that would violate horizontal limit", () => {
+    const tabs = [makeTab("a"), makeTab("b")];
+    const initial = buildInitialState(tabs);
+    const wrapper: React.FC<{ children: React.ReactNode }> = ({ children }) => (
+      <PanelStateProvider initialState={initial} createGroupId={createIdFactory()} splitLimits={{ rows: 1 }}>
+        {children}
+      </PanelStateProvider>
+    );
+    const { result } = renderHook(() => usePanelState(), { wrapper });
+    const gid = result.current.state.groupOrder[0];
+    act(() => {
+      result.current.actions.contentDrop({ fromGroupId: gid, tabId: tabs[0].id, targetGroupId: gid, zone: "top" });
+    });
+    expect(result.current.state.groupOrder.length).toBe(1);
+  });
+});

package/src/modules/panels/state/PanelSystemContext.tsx

@@ -0,0 +1,289 @@
+/**
+ * @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 { cleanupEmptyGroups } from "./cleanup";
+import { addTabToGroup, addTabToGroupAtIndex, moveTab, removeTabFromGroup, setActiveTab } from "./groups/logic";
+import { setFocusedGroup, focusGroupIndex as focusIdx, nextGroup, prevGroup } from "./focus/logic";
+import { splitGroup } from "../index";
+import { getAtPath, isGroup, setSplitRatio, type NodePath } from "./tree/logic";
+import { bindActionCreators, createAction, createActionHandlerMap, type BoundActionCreators } from "../../../utils/typedActions";
+import { GroupsProvider, type GroupsActions } from "./groups/Context";
+import { TreeProvider, type TreeActions } from "./tree/Context";
+import { FocusProvider, type FocusActions } from "./focus/Context";
+import { canSplitDirection, normalizeSplitLimits, type NormalizedSplitLimits } from "./splitLimits";
+
+type ReducerExtra = {
+  createGroupId: () => GroupId;
+  splitLimits: NormalizedSplitLimits;
+  createPanelId?: () => PanelId;
+};
+
+const actions = {
+  splitFocused: createAction("panelState/splitFocused", (direction: SplitDirection) => ({ direction })),
+  focusGroupIndex: createAction("panelState/focusGroupIndex", (index1Based: number) => ({ index1Based })),
+  focusNextGroup: createAction("panelState/focusNextGroup"),
+  focusPrevGroup: createAction("panelState/focusPrevGroup"),
+  setActiveTab: createAction("panelState/setActiveTab", (groupId: GroupId, tabId: PanelId) => ({ groupId, tabId })),
+  addTab: createAction(
+    "panelState/addTab",
+    (payload: { groupId: GroupId; tab: TabDefinition; index?: number; makeActive?: boolean }) => payload,
+  ),
+  addNewTab: createAction(
+    "panelState/addNewTab",
+    (payload: { groupId: GroupId; title: string; index?: number; makeActive?: boolean }) => payload,
+  ),
+  removeTab: createAction("panelState/removeTab", (groupId: GroupId, tabId: PanelId) => ({ groupId, tabId })),
+  contentDrop: createAction(
+    "panelState/contentDrop",
+    (payload: { fromGroupId: GroupId; tabId: PanelId; targetGroupId: GroupId; zone: DropZone }) => payload,
+  ),
+  tabDrop: createAction(
+    "panelState/tabDrop",
+    (payload: { fromGroupId: GroupId; tabId: PanelId; targetGroupId: GroupId; targetIndex: number }) => payload,
+  ),
+  adjustSplitRatio: createAction("panelState/adjustSplitRatio", (payload: { path: NodePath; deltaRatio: number }) => payload),
+} as const;
+
+type PanelStateAction = ReturnType<(typeof actions)[keyof typeof actions]>;
+type PanelStateActions = BoundActionCreators<typeof actions>;
+
+const handleContentDrop = (
+  state: PanelSystemState,
+  payload: { fromGroupId: GroupId; tabId: PanelId; targetGroupId: GroupId; zone: DropZone },
+  extra: ReducerExtra,
+): PanelSystemState => {
+  const fromGroup = state.groups[payload.fromGroupId];
+  const targetGroup = state.groups[payload.targetGroupId];
+  if (!fromGroup || !targetGroup) {
+    return state;
+  }
+  const tab = fromGroup.tabs.find((t) => t.id === payload.tabId);
+  if (!tab) {
+    return state;
+  }
+  if (payload.zone === "center" && payload.fromGroupId === payload.targetGroupId) {
+    return setActiveTab(state, payload.fromGroupId, payload.tabId);
+  }
+  if (payload.zone === "center") {
+    const moved = moveTab(state, payload.fromGroupId, payload.targetGroupId, payload.tabId, true);
+    return setFocusedGroup(moved, payload.targetGroupId);
+  }
+  const direction: SplitDirection = payload.zone === "left" || payload.zone === "right" ? "vertical" : "horizontal";
+  if (!canSplitDirection(state.tree, payload.targetGroupId, direction, extra.splitLimits)) {
+    return state;
+  }
+  const newGroupId = extra.createGroupId();
+  const afterSplit = splitGroup(state, payload.targetGroupId, direction, () => newGroupId);
+  const destination = payload.zone === "left" || payload.zone === "top" ? payload.targetGroupId : newGroupId;
+  const withTab = moveTab(afterSplit, payload.fromGroupId, destination, payload.tabId, true);
+  return setFocusedGroup(withTab, destination);
+};
+
+const handleTabDrop = (
+  state: PanelSystemState,
+  payload: { fromGroupId: GroupId; tabId: PanelId; targetGroupId: GroupId; targetIndex: number },
+): PanelSystemState => {
+  const fromGroup = state.groups[payload.fromGroupId];
+  const targetGroup = state.groups[payload.targetGroupId];
+  if (!fromGroup || !targetGroup) {
+    return state;
+  }
+  const tab = state.panels[payload.tabId];
+  if (!tab) {
+    return state;
+  }
+  if (payload.fromGroupId === payload.targetGroupId) {
+    const filteredIds = fromGroup.tabIds.filter((id) => id !== payload.tabId);
+    const insertIndex = Math.max(0, Math.min(payload.targetIndex, filteredIds.length));
+    const nextTabIds = filteredIds.slice(0, insertIndex).concat([payload.tabId], filteredIds.slice(insertIndex));
+    const nextTabs = nextTabIds.map((id) => state.panels[id]).filter(Boolean);
+    const groups = { ...state.groups, [payload.fromGroupId]: { ...fromGroup, tabIds: nextTabIds, tabs: nextTabs } };
+    return { ...state, groups };
+  }
+  const groups = { ...state.groups };
+  const sourceIds = fromGroup.tabIds.filter((id) => id !== payload.tabId);
+  const sourceTabs = sourceIds.map((id) => state.panels[id]);
+  groups[payload.fromGroupId] = {
+    ...fromGroup,
+    tabIds: sourceIds,
+    tabs: sourceTabs,
+    activeTabId: fromGroup.activeTabId === payload.tabId ? sourceTabs[0]?.id ?? null : fromGroup.activeTabId,
+  };
+  const targetIdsBase = targetGroup.tabIds.filter((id) => id !== payload.tabId);
+  const bounded = Math.max(0, Math.min(payload.targetIndex, targetIdsBase.length));
+  const nextTargetIds = targetIdsBase.slice(0, bounded).concat([payload.tabId], targetIdsBase.slice(bounded));
+  const targetTabs = nextTargetIds.map((id) => state.panels[id]).filter(Boolean);
+  groups[payload.targetGroupId] = { ...targetGroup, tabIds: nextTargetIds, tabs: targetTabs, activeTabId: payload.tabId };
+  return { ...state, groups, focusedGroupId: payload.targetGroupId };
+};
+
+const handlers = createActionHandlerMap<PanelSystemState, typeof actions, ReducerExtra>(actions, {
+  splitFocused: (state, action, extra) => {
+    const gid = state.focusedGroupId ?? state.groupOrder[0] ?? null;
+    if (!gid) {
+      return state;
+    }
+    if (!canSplitDirection(state.tree, gid, action.payload.direction, extra.splitLimits)) {
+      return state;
+    }
+    return splitGroup(state, gid, action.payload.direction, extra.createGroupId);
+  },
+  focusGroupIndex: (state, action) => focusIdx(state, action.payload.index1Based),
+  focusNextGroup: (state) => nextGroup(state),
+  focusPrevGroup: (state) => prevGroup(state),
+  setActiveTab: (state, action) => setActiveTab(state, action.payload.groupId, action.payload.tabId),
+  addTab: (state, action) => {
+    const { groupId, tab, index, makeActive } = action.payload;
+    if (typeof index === "number") {
+      return addTabToGroupAtIndex(state, groupId, tab, index, makeActive ?? true);
+    }
+    return addTabToGroup(state, groupId, tab, makeActive ?? true);
+  },
+  addNewTab: (state, action, extra) => {
+    if (!extra.createPanelId) {
+      throw new Error("addNewTab requires PanelSystemProvider.createPanelId");
+    }
+    const id = extra.createPanelId();
+    const tab: TabDefinition = { id, title: action.payload.title, render: () => action.payload.title };
+    const { groupId, index, makeActive } = action.payload;
+    if (typeof index === "number") {
+      return addTabToGroupAtIndex(state, groupId, tab, index, makeActive ?? true);
+    }
+    return addTabToGroup(state, groupId, tab, makeActive ?? true);
+  },
+  removeTab: (state, action) => removeTabFromGroup(state, action.payload.groupId, action.payload.tabId),
+  contentDrop: (state, action, extra) => handleContentDrop(state, action.payload, extra),
+  tabDrop: (state, action) => handleTabDrop(state, action.payload),
+  adjustSplitRatio: (state, action) => {
+    const node = getAtPath(state.tree, action.payload.path);
+    if (isGroup(node)) {
+      return state;
+    }
+    const nextTree = setSplitRatio(state.tree, action.payload.path, node.ratio + action.payload.deltaRatio);
+    return { ...state, tree: nextTree };
+  },
+});
+
+const reducePanelState = (state: PanelSystemState, action: PanelStateAction, extra: ReducerExtra): PanelSystemState => {
+  const handler = handlers[action.type];
+  if (!handler) {
+    return state;
+  }
+  const next = handler(state, action, extra);
+  return cleanupEmptyGroups(next);
+};
+
+export type PanelSystemContextValue = {
+  state: PanelSystemState;
+  dispatch: (action: PanelStateAction) => void;
+  actions: PanelStateActions;
+};
+
+const PanelSystemContext = React.createContext<PanelSystemContextValue | null>(null);
+
+export const usePanelSystem = (): PanelSystemContextValue => {
+  const ctx = React.useContext(PanelSystemContext);
+  if (!ctx) {
+    throw new Error("usePanelSystem must be used within PanelSystemProvider");
+  }
+  return ctx;
+};
+
+export type PanelSystemProviderProps = React.PropsWithChildren<{
+  initialState: PanelSystemState;
+  createGroupId: () => GroupId;
+  createPanelId?: () => PanelId;
+  state?: PanelSystemState;
+  onStateChange?: (next: PanelSystemState) => void;
+  splitLimits?: PanelSplitLimits;
+}>;
+
+export const PanelSystemProvider: React.FC<PanelSystemProviderProps> = ({
+  initialState,
+  createGroupId,
+  createPanelId,
+  state: controlled,
+  onStateChange,
+  splitLimits,
+  children,
+}) => {
+  const initialSanitized = React.useMemo(() => cleanupEmptyGroups(initialState), [initialState]);
+  const normalizedSplitLimits = React.useMemo(() => normalizeSplitLimits(splitLimits), [splitLimits]);
+  const extraRef = React.useRef<ReducerExtra>({ createGroupId, splitLimits: normalizedSplitLimits, createPanelId });
+  extraRef.current.createGroupId = createGroupId;
+  extraRef.current.splitLimits = normalizedSplitLimits;
+  extraRef.current.createPanelId = createPanelId;
+  const [uncontrolled, baseDispatch] = React.useReducer(
+    (prev: PanelSystemState, action: PanelStateAction) => reducePanelState(prev, action, extraRef.current),
+    initialSanitized,
+  );
+  const derivedState = React.useMemo(
+    () => (controlled ? cleanupEmptyGroups(controlled) : uncontrolled),
+    [controlled, uncontrolled],
+  );
+  const stateRef = React.useRef<PanelSystemState>(derivedState);
+  stateRef.current = derivedState;
+  const isControlled = controlled !== undefined;
+
+  const dispatch = React.useCallback(
+    (action: PanelStateAction) => {
+      if (isControlled) {
+        const next = reducePanelState(stateRef.current, action, extraRef.current);
+        onStateChange?.(next);
+        return;
+      }
+      baseDispatch(action);
+    },
+    [isControlled, onStateChange, baseDispatch],
+  );
+
+  const boundActions = React.useMemo<PanelStateActions>(() => bindActionCreators(actions, dispatch), [dispatch]);
+
+  const groupsActions = React.useMemo<GroupsActions>(
+    () => ({
+      setActiveTab: boundActions.setActiveTab,
+      tabDrop: boundActions.tabDrop,
+    }),
+    [boundActions],
+  );
+
+  const treeActions = React.useMemo<TreeActions>(
+    () => ({
+      adjustSplitRatio: boundActions.adjustSplitRatio,
+    }),
+    [boundActions],
+  );
+
+  const focusActions = React.useMemo<FocusActions>(
+    () => ({
+      focusGroupIndex: boundActions.focusGroupIndex,
+      focusNextGroup: boundActions.focusNextGroup,
+      focusPrevGroup: boundActions.focusPrevGroup,
+    }),
+    [boundActions],
+  );
+
+  const value = React.useMemo<PanelSystemContextValue>(
+    () => ({
+      state: derivedState,
+      dispatch,
+      actions: boundActions,
+    }),
+    [derivedState, dispatch, boundActions],
+  );
+
+  return (
+    <PanelSystemContext.Provider value={value}>
+      <GroupsProvider value={groupsActions}>
+        <TreeProvider value={treeActions}>
+          <FocusProvider value={focusActions}>{children}</FocusProvider>
+        </TreeProvider>
+      </GroupsProvider>
+    </PanelSystemContext.Provider>
+  );
+};
+
+export type { PanelStateAction, PanelStateActions };

package/src/modules/panels/state/StateContext.tsx

@@ -0,0 +1,12 @@
+/**
+ * @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/src/modules/panels/state/cleanup.ts

@@ -0,0 +1,37 @@
+/**
+ * @file Cleanup utilities for PanelSystem state.
+ * - Removes groups with no tabs and collapses the tree accordingly.
+ */
+import type { GroupId, PanelSystemState } from "./types";
+import { closeLeaf, collectGroupsInOrder } from "./tree/logic";
+
+/**
+ * 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 const cleanupEmptyGroups = (state: PanelSystemState): PanelSystemState => {
+  const allGroupIds = Object.keys(state.groups);
+  const emptyIds = allGroupIds.filter((gid) => state.groups[gid]!.tabIds.length === 0);
+  if (emptyIds.length === 0) {
+    return state;
+  }
+
+  const removeIfEmpty = (acc: PanelSystemState, gid: GroupId): PanelSystemState => {
+    const group = acc.groups[gid];
+    if (!group || group.tabs.length > 0) {
+      return acc;
+    }
+    const groupCount = Object.keys(acc.groups).length;
+    if (groupCount <= 1) {
+      return acc;
+    }
+    const { tree, survivorGroupId } = closeLeaf(acc.tree, gid);
+    const { [gid]: _removed, ...restGroups } = acc.groups; void _removed;
+    const groupOrder = collectGroupsInOrder(tree);
+    const focusedGroupId = acc.focusedGroupId === gid ? (survivorGroupId ?? groupOrder[0] ?? null) : acc.focusedGroupId;
+    return { ...acc, tree, groups: restGroups, groupOrder, focusedGroupId };
+  };
+
+  return state.groupOrder.reduce<PanelSystemState>((acc, gid) => removeIfEmpty(acc, gid as GroupId), state);
+};

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

@@ -0,0 +1,53 @@
+/**
+ * @file Hooks that expose commands and commit handlers for the panel system.
+ */
+import * as React from "react";
+import type { DropZone, PanelCommands } from "../state/types";
+import { usePanelState } from "../state/StateContext";
+
+export const usePanelCommands = (): PanelCommands => {
+  const { actions } = usePanelState();
+  return React.useMemo<PanelCommands>(
+    () => ({
+      splitFocused: (direction) => {
+        actions.splitFocused(direction);
+      },
+      focusGroupIndex: (n) => {
+        actions.focusGroupIndex(n);
+      },
+      focusNextGroup: () => {
+        actions.focusNextGroup();
+      },
+      focusPrevGroup: () => {
+        actions.focusPrevGroup();
+      },
+      closeFocusedGroup: () => {
+        // intentionally no-op for now
+      },
+    }),
+    [actions],
+  );
+};
+
+export const useCommitHandlers = (): {
+  onCommitContentDrop: (payload: { fromGroupId: string; tabId: string; targetGroupId: string; zone: DropZone }) => void;
+  onCommitTabDrop: (payload: { fromGroupId: string; tabId: string; targetGroupId: string; targetIndex: number }) => void;
+} => {
+  const { actions } = usePanelState();
+
+  const onCommitContentDrop = React.useCallback(
+    ({ fromGroupId, tabId, targetGroupId, zone }: { fromGroupId: string; tabId: string; targetGroupId: string; zone: DropZone }) => {
+      actions.contentDrop({ fromGroupId, tabId, targetGroupId, zone });
+    },
+    [actions],
+  );
+
+  const onCommitTabDrop = React.useCallback(
+    ({ fromGroupId, tabId, targetGroupId, targetIndex }: { fromGroupId: string; tabId: string; targetGroupId: string; targetIndex: number }) => {
+      actions.tabDrop({ fromGroupId, tabId, targetGroupId, targetIndex });
+    },
+    [actions],
+  );
+
+  return { onCommitContentDrop, onCommitTabDrop };
+};

package/src/modules/panels/state/focus/Context.tsx

@@ -0,0 +1,25 @@
+/**
+ * @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;
+};
+
+const FocusContext = React.createContext<FocusActions | null>(null);
+
+export const useFocus = (): FocusActions => {
+  const ctx = React.useContext(FocusContext);
+  if (!ctx) {
+    throw new Error("useFocus must be used within FocusProvider");
+  }
+  return ctx;
+};
+
+export const FocusProvider: React.FC<React.PropsWithChildren<{ value: FocusActions }>> = ({ value, children }) => {
+  return <FocusContext.Provider value={value}>{children}</FocusContext.Provider>;
+};